Aholo Viewer

Viewer is an online tool built with @manycore/aholo-viewer designed to import and display supported 3D assets. It is compatible with standard formats and LOD-format data generated by @manycore/aholo-splat-transform.

Important Note on Data Access: Because browsers cannot access local files directly, chunk-lod data must be hosted via a server or CDN. For local development and validation, use @manycore/aholo-splat-dev-server to host your assets.

To maintain repository integrity, observe these strict constraints:

• API Integrity: The Renderer public API exports are user-owned. Do not modify packages/renderer/src/index.ts exports unless explicitly requested.
• Generated Files: Never hand-edit external/egs-core, website/.generated/api/, or any generated dist folders.
• Workspace Dependencies: Do not delete external/splat-transform; it is a required workspace package.
• Monaco: Keep Monaco route-local.
• Examples: Maintain examples as paired JSON metadata and TypeScript source files.

The Playground uses a paired file system for examples located in website/src/content/examples/. Each example requires two files with the same name:

1. .json file: Contains metadata such as title, description, tags, accent, and order.
2. .ts file: Contains the actual TypeScript code for the scene. This file is imported using the ?raw suffix to be passed into the Monaco editor.

Example structure:

website/src/content/examples/
  basic-scene.json
  basic-scene.ts

Playground URLs can include example (the preset slug) and code (the lz-string compressed editor source).

Geometry

Geometry defines the shape of a Drawable. Most common geometry is rendered as a Mesh using triangle faces. Geometry data is organized into attributes:

• position: Vertex positions.
• uv: Texture sampling coordinates.
• normal: Used for lighting calculations.
• index: Used to reduce duplicated vertex data by indexing into position.
• PopBufferGeometry: A specialized geometry type that supports PopBuffer and Level of Detail (LOD). It should be used in conjunction with PopMesh.

Materials

Materials determine how light interacts with geometry. Common types include:

• MeshPhongMaterial: A lighting-aware material.
• MeshBasicMaterial: A basic material that does not react to light.

Viewport

A viewport is a rendering output unit with its own bounds. A single Viewer can contain multiple viewports.

• A viewport can cover the full canvas or a specific bounded region.
• Each viewport can own an independent camera.
• Each viewport has an independent pipeline configuration.
• By default, a Viewer contains one viewport covering the full canvas.

Internal Rendering Flow

The rendering process follows this pipeline:

1. Config: User-provided Config affects the pipeline.
2. Render Pipeline: Generates a DrawcallList.
3. DrawcallList: Stores information for each draw command. Each drawcall maps to a low-level graphics API call (WebGL/WebGL2).

Note: The number of drawcalls typically correlates with CPU cost. You can inspect this flow using the Spector Chrome extension.

Aholo Viewer is a monorepo split into two primary products:

1. @manycore/aholo-viewer: The TypeScript renderer package (located in packages/renderer/). This is the core engine.
2. @manycore/aholo-viewer-website: An Astro-based application (located in website/) that hosts the documentation, API reference, and an interactive Playground.

The root package manages the entire workspace using pnpm, coordinating builds, API generation, and content validation via specialized scripts in the scripts/ directory.

When building interactive applications with Aholo Viewer, follow these rules to ensure stability:

1. Use a stable container: Attach all application DOM event listeners (pointer, wheel, keyboard, etc.) to the container element passed to createViewer, not to the engine's canvas.
2. Avoid persistent canvas references: The engine manages the canvas lifecycle and may replace it. Do not store the canvas element in application state, class fields, or long-lived closures.
3. Just-in-time access: If you must access the canvas directly, read it from the current viewer/container state just-in-time, use it immediately, and discard the reference.
4. Teardown: Remove container-level event listeners during your application's cleanup phase before releasing viewer or scene resources.

Lights are Object3D instances that interact with materials to determine object appearance.

Common Light Types

• DirectionalLight: Simulates a distant source (like sunlight) emitting light in a specific direction.
• AmbientLight: Provides non-directional ambient light to simulate diffuse indirect lighting.

Tip: A common setup involves one AmbientLight and four DirectionalLight instances from different directions.

Shadows

• Light Shadows: Controlled via the shadow field on a light instance.
• Casting: Controlled via the castShadow field on a Drawable.
• Planar Shadows: A special type of shadow that does not depend on lights; it must be enabled via configuration through planarShadow.

Cameras define the viewpoint in the scene. Aholo-Viewer supports two main categories:

• PerspectiveCamera: Follows the near-larger, far-smaller perspective rule. This is the standard choice for realistic 3D views.
• OrthographicCamera: Does not apply perspective scaling, making parallel lines remain parallel regardless of distance.