beckhoff-xts-viewer-3d 5.0.0 → 5.2.0

package/README.md

@@ -106,6 +106,15 @@ that wraps the seam of a closed loop; stations, areas, dimensions and info bars;
 stop-position ghost movers; and a stator heatmap driven by
 `(positionMm, value)` samples.
 
+**Measuring and annotating.** CAD-style tools — point-to-point distance with
+optional ΔX/ΔY/ΔZ guides, angle, polyline, and distance _along_ the XTS path —
+picked in the scene with snapping to geometry corners and edges as well as to
+mover centres, module boundaries, station stops and the track path itself.
+Annotations pin a label anywhere, including to a mover, where they follow it
+while it drives. Everything works the same in the 2D plan view, renders into
+screenshots and video frames, and is fully drivable from
+`viewerRef.current.measurements`.
+
 **Analysis.** Sub-millimetre mover collision detection, as a one-shot call or a
 continuous monitor, plus module-level collision probes.
 
@@ -119,6 +128,36 @@ the post-processing chain; the result reports whether that happened.
 animated `focusOn()` for stations, areas, movers, modules or the whole scene,
 and an opt-in CAD ViewCube.
 
+### Measurements and annotations
+
+```tsx
+const viewer = useRef<XtsViewer3DRef>(null);
+const [tool, setTool] = useState<MeasurementTool>('none');
+
+<XtsViewer3D
+  ref={viewer}
+  config={config}
+  // The same tools work in the 3D view and the 2D plan view.
+  projection={plan2D ? 'orthographic' : 'perspective'}
+  measurement={{
+    tool, // 'distance' | 'angle' | 'path' | 'trackDistance' | 'annotation'
+    snap: { enabled: true, radiusPx: 14 },
+    onMeasurementCreate: (m, result) => console.log(m.kind, result.text),
+  }}
+/>;
+
+// …or place and read measurements without any user interaction:
+viewer.current.measurements.add({
+  kind: 'distance',
+  points: [{ positionMm: [0, 0, 200] }, { positionMm: [1000, 0, 200] }],
+});
+viewer.current.measurements.results(); // [{ value: 1000, text: '1 000.0 mm', … }]
+const saved = viewer.current.measurements.toJSON(); // persist, restore with fromJSON()
+```
+
+See [Measurements + annotations](docs/USING-THE-COMPONENT.md#17-measurements--annotations)
+for the tools, the snap kinds and the full API.
+
 ## Gallery
 
 |                                                                                                                                                                                                          |                                                                                                                                                                                                        |
@@ -191,11 +230,22 @@ JSON sidecars:
 
 ```bash
 pnpm assets:convert                 # STP → GLB
+pnpm assets:optimize                # meshopt compression
+pnpm assets:apply-materials         # CAD placeholder colours → real PBR materials
+pnpm assets:verify-colors           # no authored STEP colour got lost
 pnpm assets:inspect                 # refresh docs/data/glb-inspection.json
 pnpm assets:generate-sidecars       # module .meta.json origin corrections
 pnpm assets:generate-mover-sidecars
 ```
 
+The CAD sources carry Autodesk Inventor placeholder colours, not product
+colours — an AT2 motor module's whole solid is styled #696969 — so
+`assets:apply-materials` maps them onto the named PBR library in
+`scripts/materialLibrary.mjs` (anodised aluminium, stainless steel, hardened
+rail steel, plastics, printed labels, LEDs). It rewrites only the GLB's JSON
+chunk, leaving geometry and the compressed binary chunk byte-identical, and is
+idempotent. See [docs/ADDING-A-MODULE.md](docs/ADDING-A-MODULE.md).
+
 The generators skip existing files so hand-tuned calibration is never
 overwritten; pass `--force` to regenerate. The release pipeline never runs them
 and reads the sidecars read-only.