@toolpath/viewer 2.3.3 → 2.6.0

package/README.md

@@ -306,6 +306,7 @@ the part opaque. For multiselection, update your own tag array and avoid duplica
 | `Viewer`                     | Canvas, camera, lighting, controls, initial framing, and viewer-owned section state. |
 | `EnginePart`                 | Validated Engine report plus cached mesh loading; imports from `/engine`.            |
 | `PartMesh`                   | Your normalized model and prepared geometry; selection, paint, picking, sections.    |
+| `ExplodedPart`               | Supplied surface groups, translations, colors, and controlled explosion amount.      |
 | `ViewCube`                   | 26 orientation targets: faces, edges, and corners.                                   |
 | `Grid`, `Axes`               | Reference geometry excluded from camera framing.                                     |
 | `DirectionArrows`            | Candidate and optional named/preview machining directions.                           |
@@ -331,6 +332,7 @@ the part opaque. For multiselection, update your own tag array and avoid duplica
 | `showOrbitTarget`       | `false`           | Show the pivot marker.                                                                |
 | `theme`                 | Default lighting  | Override lighting; part/cube/tool colors have their own theme props.                  |
 | `onPointerMissed`       | —                 | Empty-space primary click, with drag guarding; use it to clear selection.             |
+| `webglUnavailable`      | Default message   | Content of the alert shown instead of the canvas when WebGL is unavailable.           |
 | `style`, `className`    | Full-size wrapper | Set dimensions and background on the wrapper or parent.                               |
 | `ref`                   | —                 | `ViewerHandle` for controls outside the canvas.                                       |
 
@@ -340,6 +342,13 @@ the part opaque. For multiselection, update your own tag array and avoid duplica
 Named views are `top`, `bottom`, `front`, `back`, `left`, `right`, and `isometric`.
 Direction vectors point from the part toward the camera.
 
+`Viewer` checks for WebGL2 once per page, on the client. If the browser will not create a context
+(hardware acceleration off or the GPU blocklisted), it renders a `role="alert"`
+element (`viewer-webgl-unavailable`, `data-viewer-webgl-unavailable="true"`) in
+place of the canvas, asking the user to turn on graphics acceleration; children are
+not rendered. Pass `webglUnavailable` to replace that message. Server rendering assumes
+WebGL is available; the check runs on the client after hydration.
+
 #### CAD controls
 
 | Preset               | Rotate                                          | Pan                             | Zoom                        |
@@ -375,6 +384,7 @@ fails or is absent. It does not fetch a report or start an Engine job.
 | `activeDirection`                    | Candidate-direction index; `null`/omitted means all directions.                                                       |
 | `display`, `showEdges`               | `solid` or `wireframe`; outlines default on. Wireframe always shows semantic face boundaries, not triangle diagonals. |
 | `sharpCorners`                       | `{ features: tags }` for externally flagged features, or `null`.                                                      |
+| `threads`                            | `{ threads: marks }` to draw threads in their holes, or `null`. See "Showing threads".                                |
 | `section`, `onSectionChange`         | Controlled section options and change reporting. Omit `section` to follow the viewer's section store.                 |
 | `onAdjacency`                        | Receive touching-region sets for the prepared mesh.                                                                   |
 | `theme`                              | Partial `ViewerTheme` for the part.                                                                                   |
@@ -385,6 +395,118 @@ has `best === null`. `owners` still carries all owners. `directionHighlights(mod
 index)` produces region paint matching `DirectionArrows`; it does not hide geometry
 or establish that an unpainted face is impossible to machine.
 
+### `<ExplodedPart>`
+
+Renders application-defined surface pieces inside `<Viewer>` or an R3F canvas. Import
+`ExplodedPart`, `ExplodedPartProps`, `ExplodeGroup`, `ExplodeGroupIds`, `ExplodeInput`,
+`ExplodePick`, `ExplodeRegionColors`, `createExplodeAmount`, and `ExplodeAmount` from
+`@toolpath/viewer`. Version 2.5.0 does not contain these exports.
+
+The application supplies the pieces and their translations. The renderer neither selects
+feature interpretations nor chooses machining directions, setups, or an ownership policy for
+overlapping surfaces. It reads no planning data and makes no API requests.
+
+```tsx
+import { useMemo, useState } from 'react'
+import { ExplodedPart, Viewer, type ExplodeGroup, type PartModel } from '@toolpath/viewer'
+import type { BufferGeometry } from 'three'
+
+const ExplodeView = ({
+  model,
+  geometry,
+  groups,
+  amount,
+}: {
+  model: PartModel
+  geometry: BufferGeometry
+  groups: readonly ExplodeGroup[]
+  amount: number
+}) => {
+  const [selected, select] = useState<string | null>(null)
+  const [hovered, hover] = useState<string | null>(null)
+  const explode = useMemo(() => ({ groups, amount }), [groups, amount])
+  return (
+    <Viewer>
+      <ExplodedPart
+        model={model}
+        geometry={geometry}
+        explode={explode}
+        selected={selected}
+        hovered={hovered}
+        onPick={(pick) => select(pick.explodeGroupId)}
+        onHover={(pick) => hover(pick?.explodeGroupId ?? null)}
+      />
+    </Viewer>
+  )
+}
+```
+
+Each `ExplodeGroup` contains a unique `id`, `regionIdxs`, an `offset: { x, y, z }` in
+millimetres in the source geometry's frame, and a numeric RGB `color`. IDs belong to the
+application and need not be feature tags. Groups may contain any region set, and different
+groups can share the same surfaces without being merged. Region IDs must come from the same
+model and mesh. Source geometry must be non-indexed and match `model.mesh.triangleCount`.
+An empty `groups` array draws nothing. Invalid IDs, regions, or offsets throw before allocation.
+
+`explode.amount` interpolates all supplied offsets from zero to their full translations;
+values outside `[0, 1]` are clamped and nonfinite amounts use zero. The caller owns animation,
+timing, and reduced-motion preferences. Pass a number for ordinary controlled React updates.
+For frame-by-frame animation, create a stable controller with `createExplodeAmount(initial)`
+and pass it as `explode.amount`:
+
+```tsx
+const [amount] = useState(() => createExplodeAmount(0))
+const explode = useMemo(() => ({ groups, amount }), [groups, amount])
+// From the application's animation loop, slider, or animation library:
+amount.set(0.5)
+```
+
+The controller clamps its value to `[0, 1]`, exposes it as `amount.value`, and notifies
+subscribers only when it changes. `ExplodedPart` subscribes and requests a frame automatically,
+including on a demand-driven canvas, without React updates on every frame. Subscriptions are
+removed on unmount or when the controller changes; one controller can drive multiple viewers.
+The application owns scheduling and cancelling its animation loop. The renderer never moves
+the camera. Fit and Reset remain explicit.
+
+Keep the `groups` array stable across amount, selection, and color changes. An optional
+`explode.colors: ReadonlyMap<string, number>` changes colors by group ID without rebuilding
+the layout. Optional `explode.regionColors: ExplodeRegionColors` (a
+`ReadonlyMap<string, ReadonlyMap<number, number>>`) sets colors by group ID and source region index, overriding that group's color. The same
+source region may have different colors in different groups. Regions without an override use
+`explode.colors` or the group's own color; selection and hover tint all of a group's surfaces.
+Replace color maps when changing paint. Unknown group/region keys are ignored. Color changes
+retain geometry buffers, pick identities, and shader programs; they do not require one group
+per region. `visible={false}` retains its buffers while excluding it from rendering, picking,
+and framing. Optional `onReady` runs after warming shaders and buffers for a layout; an app can
+keep it hidden or disable its play control until then. Changing the source or group array
+rebuilds the owned buffers; unmounting releases them without disposing the source geometry.
+Batching uses per-instance colors where Three.js provides them and shared vertex colors on
+earlier supported Three.js releases.
+
+Pass `theme?: Partial<ViewerTheme>` to match the surrounding application. `part` colors
+the source ghost, `partEmissive` sets emissive lighting, and `edge`/`edgeOpacity` control
+the outlines (the ghost outline fades further with the explosion). `highlight` tints the
+selected piece, `picked` colors its source surfaces, and `hover` tints the hovered piece. Group colors and
+`explode.colors` remain application-owned. Omit the theme to retain the default explode
+appearance. Theme changes update materials and colors in place without rebuilding geometry,
+changing selection, warming shaders again, or moving the camera.
+
+The source part is drawn as an unpickable ghost during explosion. Selecting a group highlights
+its original surfaces and draws one connector. `selected` and `hovered` also accept arrays of
+group IDs, so an application can interact with several render chunks as one logical piece.
+Selection highlights all their source surfaces; one connector joins their combined source and
+translated bounds. `onPick` and `onHover` return an `ExplodePick`:
+the usual source `region` and `triangleIndex`, the application's `explodeGroupId`, the displayed
+world-space `point`/`normal`, and `modelPoint` in the original geometry's frame. Region owners
+and the default ranked feature remain available as `PartPick` fields; applications can use
+the group ID to supply their own metadata. Pass `activeDirection`, as on `<PartMesh>`, to rank
+those owners for one machining direction. Hidden groups and source overlays do not accept picks.
+
+At stationary zero, the example gives rendering and picking back to its ordinary `PartMesh`.
+That assembled/exploded mode switch and its toolbar are application UI. The example's candidate
+grouping, colors, translation spacing, and rendering-budget policy stay in
+`examples/react-viewer/src/explode/` and are not exported by the package.
+
 ### `<ViewCube>`, `<Grid>`, and `<Axes>`
 
 `ViewCube` defaults to `alignment="top-right"` and `margin={[80, 80]}` (pixels).
@@ -468,7 +590,7 @@ With no children, `ViewerToolbar` renders configured controls in standard order.
 For custom composition use `ViewerToolbar.Controls`, `ViewerToolbar.Divider`, and
 its `*Button` components. A button without a matching provider control throws.
 The supported action names are `stock`, `axes`, `grid`, `banana`, `tools`,
-`directions`, `dfm`, `sharpCorners`, `hover`, `focus`, `wireframe`, `section`,
+`directions`, `dfm`, `sharpCorners`, `threads`, `hover`, `focus`, `wireframe`, `section`,
 `measure`, `fit`, `reset`, and `top`; button names capitalize the action, such as
 `ViewerToolbar.SharpCornersButton`. `useViewerToolbar()` reads those controls.
 
@@ -670,6 +792,19 @@ axis legs also have `data-axis`, and finished labels have `data-measurement-id`.
 millimetres; the `format(mm)` callback changes their displayed string, not geometry
 units or angles (which remain degrees).
 
+### Showing threads
+
+The Engine cuts a modeled internal thread out of the mesh, so a tapped hole arrives as a
+plain bore. Pass `threads={{ threads: marks }}` to draw each thread back in as shading
+over its hole's cylinders, at its pitch and hand. Build a mark from a hole's Engine
+datasheet with `threadMark(feature, datasheet)` from `@toolpath/viewer/engine`; it is
+`null` unless the datasheet carries a thread, so only threads the Engine reports are
+drawn. A `ThreadMark` is `{ regions, pitch, majorDiameter }`: `pitch` is in mm and
+negative for a left-hand thread, and cylinders wider than `majorDiameter` (a counterbore)
+stay plain. The axis is fitted from the mesh, so marks need no coordinates. The datasheet
+gives no thread length, so a tap-drill section of the same bore below the thread is
+drawn threaded too.
+
 ### Showing sharp corners and tool marks
 
 DFM decisions belong to the application. Pass flagged feature tags as
@@ -719,9 +854,9 @@ Part keys include `part`, `partEmissive`, `hover`, `highlight`, `picked`, `edge`
 use `measure`/`measureSnap`; cube keys are `cube`, `cubeEdge`, and `cubeLabel`.
 The canvas background comes from the wrapper/parent, independently of those colors.
 
-Stable DOM classes include `viewer-root`, `viewer-canvas-container`,
-`viewer-canvas-frame`, `viewer-canvas`, `viewer-hover-card`, `viewer-toolbar-stack`,
-`viewer-toolbar`, `viewer-toolbar-button`, `viewer-toolbar-icon`,
+Stable DOM classes include `viewer-root`, `viewer-webgl-unavailable`,
+`viewer-canvas-container`, `viewer-canvas-frame`, `viewer-canvas`, `viewer-hover-card`,
+`viewer-toolbar-stack`, `viewer-toolbar`, `viewer-toolbar-button`, `viewer-toolbar-icon`,
 `viewer-toolbar-tooltip`, and `viewer-toolbar-divider`. Caller `className` values
 append to the component's hook. Corresponding `data-viewer-*` attributes identify
 the DOM boundaries; `data-viewer-toolbar-action` contains the control's action name.