xeokit Model Inspector

IDE-style inspect / quick-fix toolkit for SceneModel.

Catches data-integrity errors and performance / correctness warnings, surfaces them as a structured report, and dispatches each finding to a pluggable Fix that knows how to remediate it. Mental model is eslint's rule registry + IntelliJ's "fix all problems" — bring your own rules and your own remediations; the framework wires them together.

Shape

classDiagram
    direction TB
    class inspectSceneModel {
      +(params) InspectionReport
    }
    class applyFixes {
      +(params) SDKResult~ApplyFixesResult~
    }
    class InspectionReport {
      +issues   : Issue[]
      +errors / warnings / info : Issue[]
      +byCode   : Map~code, Issue[]~
    }
    class Issue {
      +code      : string
      +severity  : error | warning | info
      +message   : string
      +resourceId? / context?
    }
    class ApplyFixesResult {
      +fixed    : Issue[]
      +skipped  : Issue[]
      +errors   : Issue[]
    }
    class Inspection {
      +codes    : string[]
      +run(sceneModel, push)
    }
    class Fix {
      +codes    : string[]
      +apply(issue, sceneModel)
    }
    class InspectionRegistry {
      +register(inspection)
    }
    class FixRegistry {
      +register(fix)
      +unregister(code)
    }
    inspectSceneModel ..> InspectionRegistry : walks
    inspectSceneModel ..> InspectionReport : produces
    InspectionRegistry "1" *-- "*" Inspection
    InspectionReport "1" *-- "*" Issue
    applyFixes ..> InspectionReport : consumes
    applyFixes ..> FixRegistry : dispatches
    applyFixes ..> ApplyFixesResult : returns
    FixRegistry "1" *-- "*" Fix

Pipeline

flowchart LR
    A[SceneModel] --> B[inspectSceneModel]
    B --> C[InspectionReport]
    C --> D[applyFixes]
    D --> E[ApplyFixesResult]
    E -- re-inspect --> B

Features

• Pluggable rules — Inspections registered into an InspectionRegistry produce typed Issues; the shipped DEFAULT_INSPECTION_REGISTRY covers structural integrity, dangling references, geometry quality, transform cycles, texture sanity, and more.
• Pluggable fixes — Fixes registered into a FixRegistry claim issue codes and apply remediation in place. DEFAULT_FIX_REGISTRY ships ~20 built-ins; last-registration-wins lets plugins override built-ins by re-registering for the same code.
• Structured byCode payloads — Issue.context carries the strategy-readable payload (e.g. {geometryId}, {duplicates: [ids]}) so fix code never has to parse a human-readable message.
• Severity tiers — issues split into errors, warnings, and info. Errors block downstream optimisation (optimizeSceneModel refuses to run with any errors present) because auto-fixing them would mask data corruption.
• Opt-in expensive walks — geometry-quality / duplicate / similarity / dense / oversize checks are off by default and enabled via checkX flags so a default inspection stays cheap.
• Re-inspection loop — typical pipeline is inspect → fix → re-inspect to see the post-fix state.
• Async variants — inspectSceneModelAsync + applyFixesAsync yield to the host periodically so very large models don't block the main thread.
• Orchestrator facade — optimizeSceneModel wraps the "inspect → split oversized geometries → prune orphans" path when callers want a one-call convenience.

Installation

npm install @xeokit/sdk
Copy

Three core artefacts:

• Issue — one finding (severity, code, message, resourceId, structured context). The context field carries strategy-readable payload ({geometryId}, {duplicates: [ids]}, …) so fix code never has to parse the message.

• InspectionReport — {issues, errors, warnings, info, byCode}. The byCode Map<code, Issue[]> is the canonical "set of issue lists" view that fix dispatch iterates, and that the demo example (see examples/ValidateSceneModel_Duplex) groups by in its UI.

• Fix — {codes[], description, apply}. The apply function is the fix itself; codes is the list of issue codes the strategy claims.

Plugin registries

Both halves of the pipeline are pluggable through symmetric registries:

• InspectionRegistry — list of Inspections inspectSceneModel walks. Singleton at DEFAULT_INSPECTION_REGISTRY; plugins register additional rules into it on import. Inspection registration is append-only — adding a rule never removes an existing one.
• FixRegistry — per-code dispatch table applyFixes reaches into. Singleton at DEFAULT_FIX_REGISTRY; plugins register replacements for built-in fixes by re-registering against the same code (last-registration-wins).

Tests / one-off pipelines build fresh registries instead and pass them via the matching registry field on the params object.

// Plug a strategy into the singleton — every applyFixes() call
// sees it from now on.
import * as sceneModelInspector from "@xeokit/sdk/inspect/sceneModel";

sceneModelInspector.DEFAULT_FIX_REGISTRY.register({
  codes: ["MyApp/STALE_PROPERTY_SET"],
  description: "Prune deprecated property sets",
  apply(issue, sceneModel) {
    // … remediation in place; return {fixed: true} on success
    return {ok: true, value: {fixed: true}};
  },
});
Copy

// Or build a one-off registry — leaves the default untouched.
import {
  FixRegistry,
  mergeDuplicateGeometries,
  applyFixes,
} from "@xeokit/sdk/inspect/sceneModel";

const registry = new FixRegistry([
  mergeDuplicateGeometries,   // pick the built-ins you want
  myFix,
]);
applyFixes({sceneModel, report, registry});
Copy

Last registration wins for a given code, so plugins can override built-ins by registering after them. Use unregister(code) to opt out.

Built-in inspections

One file per inspection under studio/sceneModelInspector/inspections, all pre-registered into DEFAULT_INSPECTION_REGISTRY. Each inspection groups codes by topical concern — one walk, multiple codes — so the file count stays low and the registration order is meaningful.

Built-in fixes

One file per fix under studio/sceneModelInspector/fixes, all pre-registered into DEFAULT_FIX_REGISTRY.

Codes deliberately without a built-in fix (MESH_DANGLING_*, MESH_NONFINITE_MATRIX, every malformed GEOMETRY_*, TRANSFORM_CYCLE) need user judgement — auto-fixing them would mask data corruption or silently change semantics.

Typical pipeline: load → inspect → applyFixes → re-inspect → render.

Putting it together

import * as sceneModelInspector from "@xeokit/sdk/inspect/sceneModel";

const report = sceneModelInspector.inspectSceneModel({
  sceneModel,
  checkDuplicateGeometries: true,   // opt-in: byte-identical detection
  checkSimilarGeometries:   true,   // opt-in: pose-invariant shape match
});

if (report.errors.length > 0) {
  // Errors block downstream optimisation — auto-fixing them
  // would mask data corruption. Surface to the user instead.
  for (const e of report.errors) {
    console.error(`[${e.code}] ${e.message}`);
  }
  return;
}

const fixResult = sceneModelInspector.applyFixes({sceneModel, report});
if (!fixResult.ok) throw new Error(fixResult.error);

const {fixed, skipped, errors} = fixResult.value;
console.log(
  `fixed ${fixed.length}, skipped ${skipped.length}, ` +
  `errors ${errors.length}`,
);

// Re-inspect to see the post-fix state.
const after = sceneModelInspector.inspectSceneModel({sceneModel});
Copy

optimizeSceneModel is the broader orchestrator — runs inspection up-front (refusing to run if any errors are present), splits oversized geometries, and prunes orphan resources. Use it when you want the convenience facade; reach for inspectSceneModel / applyFixes directly when you want IDE-style granularity (per-rule remediation, custom strategies, partial application).