MaterialService

Owns material modes (Default / Matcap / Random), tracks original and "stable" materials per mesh so temporary effects can be restored, and provides helpers for color flashes, clipping planes, and X-ray shader materials.

Access

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

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

await viewer.ready();
const material = viewer.getService<MaterialService>("material");
material?.setMode("Matcap");

Public API

Lifecycle

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

Modes

• setMode(mode: MaterialMode): void — applies the mode to every mesh under viewer.root. Built-in modes: "Default", "Matcap", "Random".
• getCurrentMode(): MaterialMode
• registerMode(name: string, mode: IMaterialMode): void

Original / stable material tracking

• rememberOriginalMaterial(mesh: THREE.Mesh): void — captures the current material as the original if not already stored.
• getOriginalMaterial(mesh): THREE.Material | THREE.Material[] | null
• setStableMaterial(mesh, material): void — the material other systems should restore to after a temporary effect.
• getStableMaterial(mesh): THREE.Material | THREE.Material[] | null — falls back to the original if no stable override.
• resetStableMaterial(mesh): void — reset stable back to original.

Color

• setColor(mesh: THREE.Mesh, color: THREE.ColorRepresentation): void — stores mesh.userData.originalColor on first call.
• resetColor(mesh: THREE.Mesh): void
• resetAllColors(): void
• flash(mesh: THREE.Mesh, flashColor?: THREE.ColorRepresentation, duration?: number): void — short color pulse. Default color #ffff00, duration 0.6s.

Materials and effects

• createMaterial(config: MaterialConfig): THREE.Material
• createXRayMaterialSet(material, options?): THREE.Material | THREE.Material[] — returns an array if input is an array. Options: opacity, rimStrength, rimPower, rimColor, fillColor.
• getMaterial(name: string): THREE.Material | null — built-ins: "standard", "matcap", "random".

Clipping

• addClippingPlane(plane: THREE.Plane): void — applies to all registered materials.
• removeClippingPlane(): void

Types

IMaterialMode

interface IMaterialMode {
  readonly name: string;
  apply(mesh: THREE.Mesh): void;
  reset?(mesh: THREE.Mesh): void;
}

MaterialConfig

interface MaterialConfig {
  type: "standard" | "physical" | "basic" | "matcap" | "shader";
  properties: any;
}

Events

Event	Payload
material:mode-registered	{ name: string; mode: IMaterialMode }
material:mode-changed	{ mode: MaterialMode; previous: MaterialMode }
material:color-changed	{ mesh: THREE.Mesh; color: THREE.ColorRepresentation }

Example

const material = viewer.getService<MaterialService>("material");
if (!material) return;

material.setMode("Random");

// Custom mode
material.registerMode("Wireframe", {
  name: "Wireframe",
  apply: (mesh) => {
    mesh.material = new THREE.MeshBasicMaterial({ wireframe: true });
  },
});
material.setMode("Wireframe" as any);

// X-ray a selection
const xrayed = material.createXRayMaterialSet(targetMesh.material, {
  opacity: 0.25,
  rimColor: "#cce6ff",
});
targetMesh.material = xrayed;