GridService

Renders an infinite-style shader grid in the scene using a custom ShaderMaterial. Supports orientation-aligned placement, per-cell and section line styling, fade-by-distance, follow-camera mode, and automatic fitting to loaded models or specific objects.

Access

Registered under the name "grid". No service dependencies.

GridService is not exported from the SDK entry point. Reach it by its registered name and use the class only as a type.

import type { GridService } from "@optellix/xviewr-sdk";

await viewer.ready();
const grid = viewer.getService<GridService>("grid");
grid?.createGrid();

The grid mesh is not created on init. Call createGrid() once to add it to the scene, then use updateConfig or orientation methods to adjust it.

Public API

Lifecycle

• init(context: ServiceContext): Promise<void>
• destroy(): Promise<void>
• getStatus(): ServiceStatus

Grid setup

• createGrid(): void — creates the grid mesh and adds it to the scene. Replaces any existing grid.
• updateConfig(config: Partial<GridConfig>): void — merges changes into the current config and updates shader uniforms. No geometry rebuild.
• setOrientation(orientation: GridOrientation): void — rotates the grid plane to align with the named axis.
• setTargetObject(object: THREE.Object3D): void — sets the reference object used by auto-sizing. Triggers immediate size update if a grid exists.

Visibility

• setVisible(visible: boolean): void
• isVisible(): boolean

Fitting

• fitGridToScene(): void — fits grid size and position to the viewer's root scene object.
• fitGridToObject(object: THREE.Object3D): void — fits to a specific object.
• calculateGridParameters(object: THREE.Object3D): GridParams — returns the computed size, position, cell sizes, and thicknesses without applying them.

Per-frame update

• update(): void — updates camera-projection uniforms and camera-follow position. Called by the viewer render loop; call manually only in custom loops.

Types

GridConfig

interface GridConfig {
  gridSize: [number, number];
  position: [number, number, number];
  cellColor: string;
  sectionColor: string;
  cellSize: number;
  sectionSize: number;
  followCamera: boolean;
  infiniteGrid: boolean;
  fadeDistance: number;
  fadeStrength: number;
  fadeFrom: number;
  cellThickness: number;
  sectionThickness: number;
  side: THREE.Side;
  visible: boolean;
  autoFit: boolean;       // when true, grid auto-fits on model:loaded
}

Default values: gridSize [1000, 1000], cellColor "#aaaaaa", sectionColor "#888888", cellSize 0.6, sectionSize 3.3, fadeDistance 10, fadeStrength 1, side THREE.BackSide.

GridOrientation

type GridOrientation = "X" | "Y" | "Z" | "-X" | "-Y" | "-Z";

Determines the rotation of the grid plane. "Y" (default) places the grid on the XZ plane.

GridParams

interface GridParams {
  size: [number, number];
  position: [number, number, number];
  cellSize: number;
  sectionSize: number;
  cellThickness: number;
  sectionThickness: number;
}

Events

Event	Payload
grid:created	{ config: GridConfig }
grid:config-changed	{ config: GridConfig }
grid:visibility-changed	{ visible: boolean }
grid:orientation-changed	{ orientation: GridOrientation }
grid:target-set	{ object: THREE.Object3D }
grid:fitted-to-scene	{}
grid:fitted-to-object	{ object: THREE.Object3D }

Example

const grid = viewer.getService<GridService>("grid");
if (!grid) return;

// Create a Y-aligned grid with custom colors
grid.updateConfig({
  cellColor: "#cccccc",
  sectionColor: "#666666",
  followCamera: true,
  autoFit: true,
});
grid.createGrid();

// Fit manually after loading a model
viewer.on("model:loaded", ({ model }) => {
  grid.fitGridToObject(model);
});

// Switch to Z-up orientation
grid.setOrientation("Z");

// Toggle visibility
grid.setVisible(false);

---