Altair-JS

Altair-JS - Package for creating 3D UI Interaction & Beautiful 3D Scene.

IMPORTANT : This project is still in the development and testing stages, licensing terms may be updated in the future. Please don't do any commercial usage currently.

Project Dependencies Guide

[ for Dependencies Details please see the end of this README ]

Altair-JS uses Three.js for 3D graphics rendering. Three.js licensed under the MIT License.

Altair-JS uses Vite for development, and Vitest for unit testing. Vite & Vitest licensed under the MIT License.

( Old Version )

Installation

Quick Start - No Need Coding !

1. Install Node.js and git clone this project.

2. Install Three.js and Vite using terminal in this project folder.

npm install three

npm install --save-dev vite

3. Run npx vite in terminal and then open the URL that Vite gives you.

npx vite

4. You'll see a URL in your terminal. Open this URL in your browser.

Embed Altair-JS to your project ( for quick use ignore this )

1. Install Node.js and git clone this project.

2. Install Three.js using terminal in your project folder.

npm install three

3. Put setup.js, components.js and ALTAIR3D folder into your project /src folder.

4. Import setup-tool & 3D components into your javascript / Three-js code

import { setup } from "./src/setup";

import {
    3DComponent-1,
    3DComponent-2,
    3DComponent-3,
    // ...
} from "./src/components";

5. For detail usage please see below topics.

How To Use

( for pure Three.js usage, jump to next topic )

1. create basic 3D Space

add 2 div, one for 3D render and one for CSS3D

<div id="three-area"></div>
<div id="three-area-css"></div>

setup basic scene in javascript

import { setup } from "./src/setup";

const basicScene = setup.jsVer("three-area", "three-area-css");

2. add 3D UI Conponent

import {
    MovieNebula,
} from "./src/components";

const nebula = new MovieNebula();
basicScene.create(nebula);

3. set the 3D UI Component scaling, position & rotation

nebula.scaleSet(10, 10, 10);
nebula.positionSet(0, 0, -120);
nebula.rotationSet(Math.PI / 6, 0, -Math.PI / 4);

( wip : color-setting & clean self-removing )

Directly use with Three.js ( for API usage ignore this )

1. new a 3D UI Component

import * as THREE from "three";
import {
    MovieNebula,
} from "./src/components";

2. add Component to your Three.js scene

// get all meshes ( JS object format )
const nebula = new MovieNebula();
const meshes = await nebula.getMeshes();
Object.values(meshes).forEach(mesh => {
    scene.add(mesh);
});

3. add component's animations to your Three.js code

// add this to animate function
const animateFunc = nebula.getAnimateFunc();

// add these to your Event Listener
// please setup Three.js RayCaster first, to judge the mouse intersects
const clickAnimation = nebula.getListenerFunc("click");

const mouseInAnimation = nebula.getListenerFunc("mouseover");

const mouseOutAnimation = nebula.getListenerFunc("notmouseover");

const mouseMoveAnimation = nebula.getListenerFunc("mousemove");

Full Example Code

import * as THREE from "three";
import { setup } from "./src/setup";
import {
    MovieWater,
    MovieStarRing,
    ButtonRadiant,
} from "./src/components";

import examplePureSky from '@hdr/example_puresky_1k.hdr';

const basicScene = setup.jsVer("three-area", "three-area-css");

const envMap = await basicScene.loadEnvironment(examplePureSky, 0, Math.PI * 5 / 9, 0);


const ocean = new MovieWater(basicScene, envMap);
basicScene.create(ocean);


const starRing = new MovieStarRing();
basicScene.create(starRing);

await starRing.loadModelAsync();
starRing.scaleSet(10, 10, 10);
starRing.positionSet(-20, 0, -120);
starRing.rotationSet(Math.PI / 6, 0, -Math.PI / 4);


const matelFlower = new ButtonRadiant();
basicScene.create(matelFlower);

matelFlower.positionSet(20, 10, -100);
matelFlower.scaleSet(7, 7, 7);


const matelFlower2 = new ButtonRadiant();
basicScene.create(matelFlower2);

matelFlower2.positionSet(0, 0, -20);

Project Detail / Debug

Setup special 3D Components

Water

import { setup } from "./src/setup";
import { MovieWater } from "./src/components";

import examplePureSky from '@hdr/example_puresky_1k.hdr';

const basicScene = setup.jsVer("three-area", "three-area-css");

const envMap = await basicScene.loadEnvironment(examplePureSky, 0, Math.PI * 5 / 9, 0);

const ocean = new MovieWater(basicScene, envMap);
basicScene.create(ocean);

Version History

V 2.0 (2026.03) - High-fidelity ripple and wave effects + Real-time Reflections. Support for HDRIs to achieve cinematic lighting.

V 1.3 (2025.07) - A consolidation of previous features. An expanded library of pre-built 3D UI components & Animations for faster development.

V 1.2 (2024.11) - GLB/glTF Support. A modular template system that allows developers to deploy GLB-based UI components and environments instantly.

V 1.1 (2024.10) - Layered Web Design Support, Multi-Scene Architecture, can mixed with 2D elements via z-index. Native Responsive Handling.

V 1.0 (2024.09) - The start of ALTAIR.js Project. High-level Three.js Wrapper, support hybrid development with Three.js. Intuitive method for 3D Scene & UI component creation.

Project Dependencies Details

Three.js License : https://github.com/mrdoob/three.js/blob/dev/LICENSE

Vite License : https://github.com/vitejs/vite/blob/main/LICENSE

Vitest License : https://github.com/vitest-dev/vitest/blob/main/LICENSE