Aholo Viewer Integration

Use Aholo Viewer

Use this skill to build or modify user applications that consume the public @manycore/aholo-viewer npm package. Treat it as a full-featured browser rendering package, not as this repository's internal renderer source.

Source Docs

Before generating non-trivial code, read the AI-oriented docs advertised by https://aholojs.dev/llms.txt:

• https://aholojs.dev/llm/manual/getting-started.md for installation and the minimal Vite setup.
• https://aholojs.dev/llm/manual/basic-concepts.md for scenes, objects, cameras, viewports, and the render flow.
• https://aholojs.dev/llm/api/index.md to confirm public exports.
• https://aholojs.dev/llm/examples/index.md for runnable TypeScript patterns.

Prefer these Markdown docs over scraping rendered HTML pages.

Integration Workflow

1. Install the package in a browser app:

   npm install --save @manycore/aholo-viewer
   npm install --save-dev vite typescript

2. Import only public package exports from @manycore/aholo-viewer.

3. Create a real DOM container with stable dimensions before calling createViewer. Attach application DOM event listeners to this container, not to the engine canvas.

4. Create a camera, position it, call lookAt, add objects to viewer.getScene(), then call viewer.setCamera(camera).

5. Configure rendering with setViewerConfig(viewer, { pipeline: ... }).

6. Render explicitly with viewer.render(). If the app relies on viewer-triggered invalidation, set viewer.requestRenderHandler to schedule another render with requestAnimationFrame.

7. Clean up when removing content: detach scene objects, stop render/update loops that still reference them, then release GPU resources or owned resources according to the cleanup rules below.

Minimal Splat Example

Use this pattern for a Vite/TypeScript browser entry:

import {
    BackgroundMode,
    Color,
    PerspectiveCamera,
    SplatLoader,
    SplatUtils,
    Vector3,
    createViewer,
    setViewerConfig,
} from '@manycore/aholo-viewer';

const SPLAT_URL = 'https://holo-cos.aholo3d.cn/aholo-opensource/gs_file/bear/bear.3d71a266.sog';

const container = document.createElement('div');
container.style.width = '500px';
container.style.height = '500px';
document.body.appendChild(container);

async function main() {
    const viewer = createViewer('example-viewer', container, {});
    const camera = new PerspectiveCamera(60, 1, 0.1, 2000);

    const response = await fetch(SPLAT_URL);
    const buffer = await response.arrayBuffer();
    const data = await SplatLoader.parseSplatData(
        SplatLoader.SplatFileType.SOG,
        new Uint8Array(buffer),
        SplatLoader.SplatPackType.Compressed,
    );
    const splat = await SplatUtils.createSplat(data);

    camera.up.set(0, -1, 0);
    camera.position.set(-1.5, -0.5, 0);
    camera.lookAt(new Vector3(0, 0, 0));

    viewer.getScene().add(splat);
    viewer.setCamera(camera);
    setViewerConfig(viewer, {
        pipeline: {
            Background: {
                background: {
                    active: BackgroundMode.BasicBackground,
                    basic: { color: new Color(0, 0, 0) },
                },
                ground: { enabled: false },
            },
            Splatting: { enabled: true },
            TAA: { enabled: false },
        },
    });

    const render = () => viewer.render();
    viewer.requestRenderHandler = () => requestAnimationFrame(render);
    requestAnimationFrame(render);
}

main();

Common Public Exports

• Viewer setup: createViewer, setViewerConfig, Viewer, Viewport.
• Cameras and math: PerspectiveCamera, OrthographicCamera, Vector2, Vector3, Vector4, Color, Matrix4, Quaternion.
• Scene objects: Object3D, Scene3D, Mesh, Splat, AmbientLight, DirectionalLight, PointLight, SpotLight.
• Mesh content: BufferGeometry, BufferAttribute, MeshBasicMaterial, MeshPhongMaterial, Side, downloadTexture.
• Splat content: SplatLoader, SplatUtils, CompressedSplat, SuperCompressedSplat, SogSplat.
• Optional loaders/utilities: GLTFLoader, DracoLoader, Animation, Events.

Confirm exact symbols in /llm/api/index.md when using less common APIs.

Patterns

For 3DGS content:

• Use SplatLoader.parseSplatData(...) to parse supported splat formats.
• Use SplatUtils.createSplat(data) to create a renderable splat.
• Enable pipeline.Splatting.
• Set camera up vectors deliberately. OpenCV-style 3DGS data commonly uses camera.up.set(0, -1, 0).

For mesh content:

• Build geometry with BufferGeometry, BufferAttribute, and optional indices.
• Use MeshPhongMaterial with lights for shaded meshes, or MeshBasicMaterial for unlit objects.
• Add lights such as AmbientLight, DirectionalLight, or PointLight before rendering lit materials.

For interactive apps:

• Tie camera controls or animations to a frame loop that calls viewer.render().
• Keep viewer container size stable and update rendering after layout changes.
• Register pointer, wheel, keyboard focus, drag/drop, resize, and custom DOM event listeners on the viewer container or another application-owned element.
• Cache large splat data when appropriate, but keep the first example simple unless the user asks for caching.

DOM Events and Canvas Access

Treat the container as the stable application boundary:

• Listen for DOM events on the container passed to createViewer(...), or on another element owned by the application.
• Do not attach event listeners to the viewer canvas. The canvas is managed internally by the engine and may be replaced.
• Do not persistently store the engine canvas element in application state, class fields, module globals, framework refs, or closures intended to outlive the current operation.
• If direct canvas access is unavoidable, read it just-in-time from the current viewer/container state, use it immediately, and discard the reference.
• Remove container-level event listeners during teardown before releasing viewer or scene resources.