use-aholo-viewer

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();