### Run Reall3dViewer with npm Package

Source: https://github.com/reall3d-com/reall3dviewer/blob/main/README_EN.md

Instructions for installing and using the Reall3dViewer npm package in a project. It demonstrates how to initialize the viewer and add 3D models.

```javascript
const viewer = new Reall3dViewer({ root: '#gsviewer' });
viewer.addModel(`https://reall3d.com/demo-models/yz.spx`);

const splatMesh = new SplatMesh({ renderer, scene, controls});
splatMesh.addModel({ url: 'https://reall3d.com/demo-models/yz.spx' });
scene.add(splatMesh);
```

--------------------------------

### Install and Use Reall3dViewer npm Package

Source: https://github.com/reall3d-com/reall3dviewer/blob/main/README.md

Steps to install the Reall3dViewer via npm and use its viewer and splat mesh functionalities in a JavaScript project. This requires a Node.js environment and a project set up with npm.

```javascript
// install
npm install @reall3d/reall3dviewer

// use built-in viewer
const viewer = new Reall3dViewer({ root: '#gsviewer' });
viewer.addModel(`https://reall3d.com/demo-models/yz.spx`);

// use splat mesh
const splatMesh = new SplatMesh({ renderer, scene, controls});
splatMesh.addModel({ url: 'https://reall3d.com/demo-models/yz.spx' });
scene.add(splatMesh);
```

--------------------------------

### Develop and Build Reall3dViewer

Source: https://github.com/reall3d-com/reall3dviewer/blob/main/README.md

Commands for developing and building the Reall3dViewer project. These are typically run in a shell environment to manage the project's lifecycle. Ensure Node.js and npm are installed.

```shell
# develop
npm run dev

# build
npm run build
```

--------------------------------

### Install Reall3dViewer via npm

Source: https://github.com/reall3d-com/reall3dviewer/blob/main/pkg/README.md

Installs the Reall3dViewer package using npm. This command fetches and installs the latest version of the package and its dependencies into your project's node_modules directory.

```shell
npm i @reall3d/reall3dviewer
```

--------------------------------

### Use Reall3dMapViewer to add scenes

Source: https://github.com/reall3d-com/reall3dviewer/blob/main/pkg/README.md

Initializes a Reall3dMapViewer instance and loads a collection of scenes from a JSON file. This is useful for displaying geographical or map-based 3D content. The root element should be present in the DOM.

```javascript
const mapViewer = new Reall3dMapViewer({ root: '#viewer4' });
mapViewer.addScenes('https://reall3d.com/demo-models/map/00.scenes.json');
```

--------------------------------

### Use Reall3dViewer to add a model

Source: https://github.com/reall3d-com/reall3dviewer/blob/main/pkg/README.md

Initializes a Reall3dViewer instance and adds a 3D model from a specified URL. Ensure the target DOM element exists before initialization. The model URL should point to a compatible 3D file format.

```javascript
const viewer = new Reall3dViewer({ root: '#viewer2' });
viewer.addModel(`https://reall3d.com/demo-models/yz.spx`);
```

--------------------------------

### Convert PLY to SPX using gsbox

Source: https://github.com/reall3d-com/reall3dviewer/blob/main/README.md

Command to convert a .ply file to a .spx file using the gsbox tool. This is useful for preparing models for use with Reall3dViewer. Ensure gsbox is installed and in your PATH.

```shell
# .spx file can be obtained through conversion using the gsbox
gsbox p2x -i /path/to/input.ply -o /path/to/output.spx -sh 0
```

--------------------------------

### Initialize Standalone Reall3dViewer

Source: https://context7.com/reall3d-com/reall3dviewer/llms.txt

Creates a basic 3DGS viewer instance with automatic setup for camera, controls, scene, and renderer. Options include quality level, sorting, auto-rotation, spherical harmonics degree, light factor, and background color. Models can be loaded and viewer options updated dynamically.

```typescript
import { Reall3dViewer } from '@reall3d/reall3dviewer';

// Basic initialization with default settings
const viewer = new Reall3dViewer({
  root: '#gsviewer',
  debugMode: false,
  qualityLevel: 5,      // 1-9, default 5 (balanced quality/performance)
  sortType: 1,          // Default sorting algorithm
  autoRotate: true,
  maxRenderCountOfPc: 5120000,
  maxRenderCountOfMobile: 2560000,
  shDegree: 3,          // Spherical harmonics degree (0-3)
  lightFactor: 1.1,     // Color brightness multiplier
  background: '#000000'
});

// Load a model
viewer.addModel('https://example.com/model.spx');

// Access configuration
const options = viewer.options();
console.log('Current quality level:', options.qualityLevel);

// Update settings dynamically
viewer.options({
  autoRotate: false,
  qualityLevel: 7,
  lightFactor: 1.2
});
```

--------------------------------

### Integrate SplatMesh with Three.js

Source: https://context7.com/reall3d-com/reall3dviewer/llms.txt

This example shows how to use the SplatMesh class directly within a Three.js scene. It covers importing necessary components, setting up the Three.js environment, creating a SplatMesh instance with various options, loading a model, adding it to the scene, updating options, managing the render loop, and cleaning up resources. Dependencies include `@reall3d/reall3dviewer` and `three`.

```typescript
import { SplatMesh } from '@reall3d/reall3dviewer';
import * as THREE from 'three';

// Create Three.js scene components
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(45, window.innerWidth / window.innerHeight, 0.1, 1000);
const renderer = new THREE.WebGLRenderer();
const controls = new THREE.OrbitControls(camera, renderer.domElement);

// Create SplatMesh with required dependencies
const splatMesh = new SplatMesh({
  renderer: renderer,
  scene: scene,
  controls: controls,
  qualityLevel: 5,
  sortType: 1,
  bigSceneMode: false,
  pointcloudMode: true,
  maxRenderCountOfPc: 5120000,
  shDegree: 3
});

// Add model to mesh
await splatMesh.addModel({
  url: 'https://example.com/model.spx',
  format: 'spx'
});

// Add to scene
scene.add(splatMesh);

// Configure options after creation
splatMesh.options({
  qualityLevel: 7,
  lightFactor: 1.2
});

// Render loop
renderer.setAnimationLoop(() => {
  controls.update();
  renderer.render(scene, camera);
});

// Cleanup
splatMesh.dispose();

```

--------------------------------

### Enable and Control Annotations and Measurements

Source: https://context7.com/reall3d-com/reall3dviewer/llms.txt

This snippet demonstrates how to enable annotation mode, set mark types and visibility, and programmatically control annotations. It covers starting, updating, deleting, and showing/hiding annotations. Dependencies include the viewer instance and window.$api.

```typescript
// Enable annotation mode
viewer.options({
  markMode: true,
  markType: 'point',      // 'point' | 'lines' | 'plans' | 'distance' | 'circle'
  markVisible: true,
  meterScale: 1.0         // Conversion ratio: 1 unit = 1.0 meters
});

// Annotation types:
// - point: Single point markers
// - lines: Multi-segment polylines
// - plans: Multi-plane polygons
// - distance: Two-point distance measurement
// - circle: Circular area marking

// Programmatic annotation control via window.$api
window.$api.startMark(1);  // 1=point, 2=lines, 3=plans, 4=distance

// Update existing annotation
const markData = {
  name: 'measurement1',
  type: 'distance',
  points: [[0,0,0], [10,5,2]],
  color: '#ff0000'
};
await window.$api.updateMark(markData, true);  // true = save to meta

// Delete annotation
await window.$api.deleteMark('measurement1');

// Toggle annotation visibility
window.$api.showMark(true);  // or false to hide

```

--------------------------------

### Configure SPX Format for Optimized 3DGS Storage

Source: https://context7.com/reall3d-com/reall3dviewer/llms.txt

Details the SPX format, an optimized binary format for 3DGS storage. It includes information on its structure, header fields, compression options, and supported data block formats. The documentation also provides a command-line example for converting PLY to SPX using the gsbox CLI tool and how to load SPX files within the viewer.

```typescript
// SPX format features:
// - Compressed binary format with flexible data blocks
// - 128-byte header with bounding box and metadata
// - Support for SH degrees 0-3
// - Open and exclusive format variants
// - Gzip or XZ compression per data block

// SPX file header fields:
const spxHeader = {
  magic: 'spx',              // Format identifier
  version: 2,                // SPX v2
  gaussianCount: 1500000,    // Total Gaussian points
  minX: -10, maxX: 10,       // Bounding box
  minY: -5,  maxY: 8,
  minZ: -12, maxZ: 12,
  shDegree: 3,               // Spherical harmonics degree (0-3)
  createrId: 0,              // Creator ID (0 = Reall3d)
  exclusiveId: 0,            // 0 = open format
  isLargeScene: false,       // Large scene flag
  maxDataCategory: 0         // Data categorization
};

// Convert PLY to SPX using gsbox CLI tool:
// gsbox p2x -i input.ply -o output.spx -sh 0

// Load SPX file
await viewer.addModel('https://example.com/model.spx');

// SPX data blocks support multiple formats:
// - Format 19: Basic data (x,y,z, sx,sy,sz, r,g,b,a, rx,ry,rz)
// - Format 20: Basic data with quaternion w
// - Format 190: WebP-encoded basic data
// - Format 1-4: Spherical harmonics data (SH1, SH2, SH3, combined)
```

--------------------------------

### Serve 3DGS Model in Browser

Source: https://github.com/reall3d-com/reall3dviewer/blob/main/README.md

Instructions to run the Reall3dViewer in a web browser and load a 3DGS model. This requires the viewer to be built and a model link to be provided via URL parameters. Ensure the viewer is accessible via a web server.

```shell
# open a web browser to render your 3dgs model
# http://hostname:port/index.html?url=your-model-link-address
```

--------------------------------

### Develop and Build Project with npm

Source: https://github.com/reall3d-com/reall3dviewer/blob/main/README_EN.md

Standard npm commands for developing and building the Reall3dViewer project. These commands are essential for local development and deployment.

```shell
npm run dev

# build
npm run build
```

--------------------------------

### Event Handling and Debug API for Reall3dViewer

Source: https://context7.com/reall3d-com/reall3dviewer/llms.txt

Demonstrates the use of the `fire()` API for various debugging and control functions, such as showing watermarks, managing fly-through animations, adjusting SH degree, quality level, and sort type. It also shows how to access internal viewer components like camera, scene, and renderer.

```typescript
// Testing fire() API
viewer.fire(1, 1);   // Show watermark
viewer.fire(2);      // Add position to fly-through
viewer.fire(3);      // Start fly-through
viewer.fire(4);      // Clear fly-through
viewer.fire(8, 1);   // Increase SH degree
viewer.fire(9, -1);  // Decrease quality level

// Accessing internal components
const internalEvents = viewer.events;
const camera = internalEvents.fire(GetCamera);
const scene = internalEvents.fire(GetScene);
```

--------------------------------

### Convert PLY to SPX using gsbox

Source: https://github.com/reall3d-com/reall3dviewer/blob/main/README_EN.md

Command-line usage of the gsbox tool to convert a .ply file to a .spx file, a format supported by Reall3dViewer. This is useful for preparing models for the viewer.

```shell
gsbox p2x -i /path/to/input.ply -o /path/to/output.spx -sh 0
```

--------------------------------

### Configure Camera Controls and Animations

Source: https://context7.com/reall3d-com/reall3dviewer/llms.txt

This snippet details how to configure camera behavior, including rotation, damping, zoom, and pan. It also covers manual camera positioning and programmatic control of fly-through animations. Dependencies include the viewer instance and window.$api.

```typescript
// Configure camera controls
viewer.options({
  autoRotate: true,
  enableDamping: true,
  enableZoom: true,
  enableRotate: true,
  enablePan: true,
  minDistance: 1,
  maxDistance: 1000,
  minPolarAngle: 0,
  maxPolarAngle: Math.PI,
  enableKeyboard: true
});

// Manual camera positioning
viewer.options({
  position: [10, 5, 15],     // Camera position [x, y, z]
  lookAt: [0, 0, 0],         // Look-at target
  lookUp: [0, -1, 0],        // Up vector
  fov: 45                    // Field of view in degrees
});

// Fly-through animation (development API)
viewer.fire(2);  // Add current camera position to fly-through path
viewer.fire(3);  // Start fly-through animation
viewer.fire(4);  // Clear all fly-through positions
viewer.fire(5);  // Save fly-through path to meta.json

// Toggle auto-rotation programmatically
window.$api.switchAutoRotate();

```

--------------------------------

### Manage Viewer Lifecycle for Memory Efficiency

Source: https://context7.com/reall3d-com/reall3dviewer/llms.txt

Demonstrates how to manage the Reall3D Viewer's lifecycle for optimal memory usage. This includes resetting the viewer with new configurations (debug mode, rendering limits, quality level, transition effects) and completely disposing of the viewer to free resources. After disposal, a new instance must be created for further use.

```typescript
// Reset viewer with new configuration
viewer.reset({
  debugMode: true,
  maxRenderCountOfPc: 10240000,
  qualityLevel: 6,
  transitionEffect: 1  // TransitionEffects.ModelCenterCircle
});

// Transition effects:
// 1 = ModelCenterCircle (circle from model center)
// 2 = ScreenCenterCircle (circle from screen center)
// 3 = ScreenMiddleToLeftRight (horizontal wipe)
// 4 = ScreenMiddleToTopBottom (vertical wipe)

// Disable transition on load
viewer.reset({
  disableTransitionEffectOnLoad: true
});

// Complete disposal (cleanup all resources)
viewer.dispose();

// After disposal, viewer cannot be reused
// Create new instance if needed
const newViewer = new Reall3dViewer({ root: '#gsviewer' });
```

--------------------------------

### Load 3DGS Models and Scenes

Source: https://context7.com/reall3d-com/reall3dviewer/llms.txt

Loads 3D Gaussian Splatting models from various formats (e.g., .spx, .ply) via URL, with optional explicit format specification. It also supports loading complete scenes including metadata like camera settings, watermarks, annotations, and quality configurations from JSON files. The scene data structure allows fine-grained control over rendering behavior.

```typescript
// Load model from URL (format auto-detected from extension)
await viewer.addModel('https://example.com/model.spx');

// Load with explicit format specification
await viewer.addModel({
  url: 'https://example.com/model.ply',
  format: 'ply'
});

// Load model with metadata file (*.meta.json)
// Metadata includes camera settings, watermarks, annotations, quality settings
await viewer.addModel('https://example.com/model.meta.json');

// Load complete scene with camera position and settings
await viewer.addScene('https://example.com/scene.scene.json');

// Scene JSON structure
const sceneData = {
  url: 'https://example.com/model.spx',
  autoCut: 16,                    // LOD subdivision (>1 enables large scene mode)
  qualityLevel: 6,                // Override default quality
  sortType: 2010,                 // Custom sort type for this scene
  watermark: 'Copyright 2025',
  showWatermark: true,
  cameraInfo: {
    position: [0, -5, 15],
    lookAt: [0, 0, 0],
    fov: 45
  },
  transform: [1,0,0,0, 0,1,0,0, 0,0,1,0, 0,0,0,1],  // 4x4 transformation matrix
  markData: [],                   // Saved annotations
  flyPositions: [],               // Fly-through camera positions
  flyTargets: []                  // Fly-through look-at points
};
```

--------------------------------

### Switch Display Modes and Adjust Rendering

Source: https://context7.com/reall3d-com/reall3dviewer/llms.txt

This code illustrates how to switch between point cloud and splat rendering modes, trigger animated transitions, and adjust scene brightness and lighting complexity. Dependencies include the viewer instance and window.$api.

```typescript
// Toggle point cloud vs. splat rendering
window.$api.changePointCloudMode(true);   // Enable point cloud mode
window.$api.changePointCloudMode(false);  // Enable splat rendering mode

// Circle transition effect
viewer.switchDeiplayMode();  // Animated circle transition between modes

// Adjust brightness/lighting
viewer.options({ lightFactor: 1.5 });  // Increase brightness by 50%
viewer.options({ lightFactor: 0.8 });  // Decrease brightness to 80%

// Adjust spherical harmonics degree (affects lighting complexity)
viewer.fire(8, 1);   // Increase SH degree by 1
viewer.fire(8, -1);  // Decrease SH degree by 1
viewer.fire(8);      // Reset to model's default SH degree

```

--------------------------------

### Initialize Map-Integrated Viewer for Large Scenes

Source: https://context7.com/reall3d-com/reall3dviewer/llms.txt

Initializes a map-integrated viewer for large-scale scenes using Reall3dMapViewer. It supports tile-based rendering and loading multiple scenes from an index file. The viewer automatically handles LOD, dynamic loading, spatial indexing, and label rendering. Ensure a DOM element with id 'map-container' exists.

```typescript
import { Reall3dMapViewer } from '@reall3d/reall3dviewer';

// Create map viewer with tile-based rendering
const mapViewer = new Reall3dMapViewer({
  root: document.getElementById('map-container'),
  debugMode: false
});

// Load multiple scenes from index file
mapViewer.addScenes('https://example.com/scenes-index.json');

// Scenes index JSON structure
const scenesIndex = {
  name: 'City District',
  version: '1.0',
  position: [17000, 30000, -35000],    // Initial camera position
  lookAt: [17000, 0, -35000],          // Initial look-at point
  flyPositions: [/* array of positions */],
  flyTargets: [/* array of targets */],
  scenes: [
    'https://example.com/scene1.scene.json',
    'https://example.com/scene2.scene.json',
    'https://example.com/scene3.scene.json'
  ]
};

// Map viewer automatically handles:
// - Tile-based LOD rendering
// - Dynamic model loading/unloading
// - Spatial indexing and culling
// - CSS3D label rendering

// Cleanup
mapViewer.dispose();
```

--------------------------------

### Enable Local File Drag-and-Drop for Quick Model Preview

Source: https://context7.com/reall3d-com/reall3dviewer/llms.txt

Enables drag-and-drop functionality for local files to quickly preview 3D models. This feature is enabled by default. Supported formats include various Reall3D formats (.spx, .splat, etc.), .obj, and .scene.json. Upon dropping a file, the viewer resets with high quality settings, enables point cloud and debug modes, loads the model, and cleans up temporary URLs.

```typescript
// Drag and drop is enabled by default
const viewer = new Reall3dViewer({
  root: '#gsviewer',
  disableDropLocalFile: false  // Set to true to disable
});

// Supported formats for drag-and-drop:
// - .spx, .splat, .ply, .spz, .sog (3DGS formats)
// - .obj (mesh format)
// - .scene.json (scene configuration)

// When file is dropped, viewer automatically:
// 1. Resets with high quality settings (qualityLevel: 9)
// 2. Enables point cloud mode
// 3. Enables debug mode
// 4. Loads and renders the model
// 5. Cleans up blob URL after loading
```

--------------------------------

### Performance Optimization with Reall3dViewer

Source: https://context7.com/reall3d-com/reall3dviewer/llms.txt

Configures render limits and quality levels for optimal performance based on device and scene type. It supports scene-specific strategies like indoor/occluded or open outdoor scenes and enables LOD for large scenes. Debug mode can be enabled to monitor performance metrics.

```typescript
const viewer = new Reall3dViewer({
  maxRenderCountOfMobile: 2560000,
  maxRenderCountOfPc: 5120000,
  qualityLevel: 5
});

// Indoor/occluded scenes
viewer.options({
  sortType: 2010,
  qualityLevel: 7
});

// Open outdoor scenes
viewer.options({
  sortType: 1,
  qualityLevel: 4
});

// Large scenes with LOD
const sceneConfig = {
  url: 'model.spx',
  autoCut: 16
};

// Enable debug mode
viewer.options({ debugMode: true });
```

--------------------------------

### Configure Rendering Quality and Sorting

Source: https://context7.com/reall3d-com/reall3dviewer/llms.txt

Adjusts rendering quality and sorting algorithms to optimize performance and visual fidelity. Quality levels range from 1 (fastest) to 9 (highest quality), automatically tuning parameters like SH degree and pixel thresholds. Various sorting types are available, including depth-based methods suitable for specific scene types like indoor mazes.

```typescript
// Quality levels: 1 (fastest) to 9 (highest quality)
// Each level automatically adjusts: SH degree, pixel thresholds, alpha cutoff, bucket counts
viewer.options({ qualityLevel: 5 });  // Default balanced mode
viewer.options({ qualityLevel: 1 });  // Low-end devices
viewer.options({ qualityLevel: 9 });  // High-end devices, best quality

// Available sort types
const SortTypes = {
  Default1: 1,              // Full view-projection matrix sorting
  ZdepthFrontNearest2010: 2010,   // Cull back/far, render nearest only
  ZdepthFront2011: 2011,          // Cull back-facing only
  ZdepthFrontNearFar2012: 2012,   // Two-stage near/far sorting, cull back
  ZdepthFullNearFar2112: 2112     // Two-stage near/far, no culling
};

// Select sort type based on scene characteristics
viewer.options({ sortType: SortTypes.Default1 });  // General purpose

// Indoor maze scene example: only see ~10 depth units at a time
viewer.options({
  sortType: 2010,  // Render only nearest depth
  // Configure depthNearValue=10 in meta.json for this model
});

// Point cloud rendering mode (shows raw splat points)
viewer.options({ pointcloudMode: true });
```

--------------------------------

### Manage Scene Watermarks

Source: https://context7.com/reall3d-com/reall3dviewer/llms.txt

This TypeScript code shows how to set, save, and toggle the visibility of text watermarks in the viewer. Watermarks are rendered as 3D Gaussian splats and have a maximum character limit. Dependencies include window.$api.

```typescript
// Set watermark text (renders as 3D Gaussian text)
window.$api.setWaterMark('Copyright 2025 - MyCompany', true);  // true = save to meta

// Toggle watermark visibility
window.$api.showWaterMark(true);   // Show
window.$api.showWaterMark(false);  // Hide

// Watermarks are fetched from remote service and rendered as Gaussian splats
// Requests are cached and batched for performance
// Maximum 100 characters supported

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.