beckhoff-xts-viewer-3d 5.0.0 → 5.1.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
 
 |                                                                                                                                                                                                          |                                                                                                                                                                                                        |