@toolpath/viewer 2.2.1 → 2.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +110 -43
  2. package/dist/{chunk-7S6SIYHL.js → chunk-N54FHMTG.js} +753 -178
  3. package/dist/engine/index.d.ts +2 -2
  4. package/dist/engine/index.js +1 -1
  5. package/dist/index.d.ts +7 -205
  6. package/dist/index.js +290 -121
  7. package/dist/{normalize--FiXUhO4.d.ts → normalize-C4Wj4IGK.d.ts} +333 -3
  8. package/package.json +1 -1
package/README.md CHANGED
@@ -357,9 +357,9 @@ individual buttons to use only the controls and order your application needs.
357
357
  </ViewerToolbarProvider>
358
358
  ```
359
359
 
360
- `ViewerToolbar.Controls`, `Divider`, and the fifteen `*Button` components are available on
360
+ `ViewerToolbar.Controls`, `Divider`, and the sixteen `*Button` components are available on
361
361
  `ViewerToolbar`: `StockButton`, `AxesButton`, `GridButton`, `BananaButton`, `ToolsButton`, `DirectionsButton`,
362
- `DfmButton` (shows or hides an application's DFM flags), `HoverButton`, `FocusButton`, `WireframeButton`, `SectionButton`, `MeasureButton`, `FitButton`,
362
+ `DfmButton` (shows or hides an application's DFM flags), `SharpCornersButton`, `HoverButton`, `FocusButton`, `WireframeButton`, `SectionButton`, `MeasureButton`, `FitButton`,
363
363
  `ResetButton`, and `TopButton`. A rendered button requires its matching provider control. For an
364
364
  application-specific toolbar component, `useViewerToolbar()` reads the same controls from inside
365
365
  the provider.
@@ -388,19 +388,19 @@ override any of these selectors in your application stylesheet.
388
388
  The following `data-*` attributes identify generated elements without depending on labels, which
389
389
  can change with state or localization:
390
390
 
391
- | Attribute | Element and values |
392
- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
393
- | `data-viewer-root="true"` | `<Viewer>` wrapper |
394
- | `data-viewer-canvas-container="true"` | R3F canvas event container |
395
- | `data-viewer-canvas-frame="true"` | R3F canvas-sizing frame |
396
- | `data-viewer-canvas="true"` | The `<canvas>` itself |
397
- | `data-viewer-hover-card="true"` | `<HoverCard>` shell |
398
- | `data-viewer-toolbar="true"` | Toolbar stack |
399
- | `data-viewer-toolbar-controls="true"` | Controls group |
400
- | `data-viewer-toolbar-action` | Standard button: `stock`, `axes`, `grid`, `banana`, `tools`, `directions`, `hover`, `focus`, `wireframe`, `section`, `measure`, `fit`, `reset`, or `top` |
401
- | `data-viewer-toolbar-icon="true"` | Standard button SVG |
402
- | `data-viewer-toolbar-tooltip="true"` | Standard button tooltip |
403
- | `data-viewer-toolbar-divider="true"` | Toolbar separator |
391
+ | Attribute | Element and values |
392
+ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
393
+ | `data-viewer-root="true"` | `<Viewer>` wrapper |
394
+ | `data-viewer-canvas-container="true"` | R3F canvas event container |
395
+ | `data-viewer-canvas-frame="true"` | R3F canvas-sizing frame |
396
+ | `data-viewer-canvas="true"` | The `<canvas>` itself |
397
+ | `data-viewer-hover-card="true"` | `<HoverCard>` shell |
398
+ | `data-viewer-toolbar="true"` | Toolbar stack |
399
+ | `data-viewer-toolbar-controls="true"` | Controls group |
400
+ | `data-viewer-toolbar-action` | Standard button: `stock`, `axes`, `grid`, `banana`, `tools`, `directions`, `dfm`, `sharpCorners`, `hover`, `focus`, `wireframe`, `section`, `measure`, `fit`, `reset`, or `top` |
401
+ | `data-viewer-toolbar-icon="true"` | Standard button SVG |
402
+ | `data-viewer-toolbar-tooltip="true"` | Standard button tooltip |
403
+ | `data-viewer-toolbar-divider="true"` | Toolbar separator |
404
404
 
405
405
  Toggle buttons also carry standard `aria-pressed="true"` or `"false"`; use that to style their
406
406
  current state. `Fit`, `Reset`, and `Top view` are actions rather than toggles, so they omit the
@@ -477,17 +477,18 @@ Draws the part and handles clicks. You only use it directly when you
477
477
 
478
478
  **Colours**
479
479
 
480
- | Prop | Type | What it does |
481
- | ------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------- |
482
- | `selection` | `string[]` | Feature tags to highlight as selected (orange). |
483
- | `highlights` | `FeatureHighlight[]` | Your own colour per feature, e.g. difficulty or setup. |
484
- | `regionHighlights` | `RegionHighlight[]` | Your own colour per face. |
485
- | `candidates` | `string[]` | Other possible matches, faintly tinted by machining direction. |
486
- | `pickedRegions` | `number[]` | Faces to mark as just clicked. |
487
- | `hoveredFeatureIds` | `string[]` | Features to show as hovered, e.g. when hovering a list row. |
488
- | `showEdges` | `boolean` (`true`) | Draw outlines between faces. |
489
- | `display` | `'solid' \| 'wireframe'` (`'solid'`) | Wireframe draws face boundaries without triangle diagonals. Painted and hovered faces remain visible. |
490
- | `theme` | `Partial<ViewerTheme>` | Override the part's colours. |
480
+ | Prop | Type | What it does |
481
+ | ------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------- |
482
+ | `selection` | `string[]` | Feature tags to highlight as selected (orange). |
483
+ | `highlights` | `FeatureHighlight[]` | Your own colour per feature, e.g. difficulty or setup. |
484
+ | `regionHighlights` | `RegionHighlight[]` | Your own colour per face. |
485
+ | `candidates` | `string[]` | Other possible matches, faintly tinted by machining direction. |
486
+ | `pickedRegions` | `number[]` | Faces to mark as just clicked. |
487
+ | `hoveredFeatureIds` | `string[]` | Features to show as hovered, e.g. when hovering a list row. |
488
+ | `showEdges` | `boolean` (`true`) | Draw outlines between faces. |
489
+ | `sharpCorners` | `SharpCornerOptions \| null` (`null`) | Draw the sharp corners the DFM rules flag. See [Showing sharp corners](#showing-sharp-corners). |
490
+ | `display` | `'solid' \| 'wireframe'` (`'solid'`) | Wireframe draws face boundaries without triangle diagonals. Painted and hovered faces remain visible. |
491
+ | `theme` | `Partial<ViewerTheme>` | Override the part's colours. |
491
492
 
492
493
  **Interaction**
493
494
 
@@ -789,6 +790,68 @@ To list features by direction, use `groupByDirection(model)`. To label a directi
789
790
  `directionLabel(direction)`, which gives `+Z`, `−X`, or `0.707, 0, 0.707`. To colour a direction
790
791
  the same way as its arrow, use `directionColor(index)`.
791
792
 
793
+ ### Showing sharp corners
794
+
795
+ `sharpCorners` draws a part's sharp corners as red bands painted on the two faces that meet there: strong where you can see them, faint
796
+ where the part is in front of them. **Which corners is the DFM rules' call, not the viewer's.** Pass
797
+ the features the rules flag with a sharp corner — those whose `featureSheet(datasheet).sharpCorners`
798
+ is set, from `@toolpath/dfm/model` — and the viewer draws each one's inside corners that run along
799
+ its machining direction: the vertical corners between its walls that no end mill makes. Nothing else
800
+ is drawn — not a hole's rim, not an outside edge, not a floor meeting a wall.
801
+
802
+ The mesh only says where those corners are. It needs the closed mesh the Engine produces (every edge
803
+ shared by exactly two triangles) and the report's regions, which tell a real edge from tessellation.
804
+
805
+ ```tsx
806
+ const flagged = Object.entries(sheets)
807
+ .filter(([, sheet]) => sheet.sharpCorners)
808
+ .map(([tag]) => tag)
809
+
810
+ <ViewerToolbarProvider
811
+ controls={{ sharpCorners: { pressed: shown, onClick: () => setShown((on) => !on) } }}
812
+ >
813
+ <ViewerToolbar />
814
+ <Viewer>
815
+ <EnginePart report={report} sharpCorners={shown ? { features: flagged } : null} />
816
+ </Viewer>
817
+ </ViewerToolbarProvider>
818
+ ```
819
+
820
+ `ViewerToolbar.SharpCornersButton` turns them on and off; there is nothing else to offer users.
821
+ Tags are matched without regard to case, so the lower-cased keys an application keeps its sheets
822
+ under work as they are.
823
+
824
+ With `hover` on, the pointer on a corner is on the corner: it takes the theme's `hover` colour at
825
+ the same width, the face under it is not painted as hovered, and the pick `onHover` reports carries it as
826
+ `pick.sharpCorner`. That is a `SharpCorner`: the flagged `feature` it belongs to, its `start` and `end`,
827
+ its `length` (how deep a tool would have to reach, mm), and the `angle` between its faces (90 for a
828
+ square corner). What a hover card says about it is the application's call; with the feature's sheet,
829
+ the widest tool that fits it (`pinchDiameter`) says what milling would leave there — that tool's radius.
830
+
831
+ ```tsx
832
+ <HoverCard pick={pick}>
833
+ {(pick) =>
834
+ pick.sharpCorner ? (
835
+ <SharpCornerDetails corner={pick.sharpCorner} />
836
+ ) : (
837
+ <FeatureDetails pick={pick} />
838
+ )
839
+ }
840
+ </HoverCard>
841
+ ```
842
+
843
+ `findSharpCorners(creases, model, options)` lists the same corners without a pointer.
844
+
845
+ `features` is the only option. How sharp a fold must be to count, how closely it must follow the
846
+ machining direction, and how the bands look are fixed: the rules have already decided which corners
847
+ matter, and there is nothing left worth tuning. The colour is the `sharpCorner` theme key. To count
848
+ or measure the corners yourself, use `surfaceCreases(geometry, model)` and
849
+ `sharpCornerPositions(creases, model, options)`.
850
+
851
+ If your application paints the features a rule flags, leave that rule's paint off while the corners
852
+ are shown. A corner drawn in the rule's colour disappears into paint of the same colour, and the
853
+ corner is the rule's mark, more exactly than the paint is.
854
+
792
855
  ### Custom colours
793
856
 
794
857
  Use `highlights` for colours that mean something in your app, such as difficulty, setup, or cost.
@@ -986,7 +1049,8 @@ hatch lines, `sectionHandle` overrides the drag arrow's colour, and `sectionOutl
986
1049
  cutting-plane sheet and preview that `<SectionTool>` draws. Without a `sectionHandle` override, the
987
1050
  drag arrow uses the cutting plane's direction colour. `measure` and `measureSnap` are
988
1051
  `<MeasureTool>`'s lines and its snap indicator; a distance's X, Y, Z legs take `AXIS_COLORS`, the
989
- same hues as the section tool's global planes.
1052
+ same hues as the section tool's global planes. `sharpCorner` is the colour of
1053
+ [sharp corners](#showing-sharp-corners).
990
1054
 
991
1055
  `HIGHLIGHT_COLORS` has the standard selection colours (`default`, `toolIssue`, `geometryIssue`).
992
1056
  `DIRECTION_COLORS` has the 9 direction colours, which repeat for parts with more than 9 directions.
@@ -1241,21 +1305,24 @@ is a complete app built this way, with no API key needed.
1241
1305
 
1242
1306
  ### Helpers
1243
1307
 
1244
- | Helper | What it does |
1245
- | -------------------------------------------------------- | ----------------------------------------------------------- |
1246
- | `normalizePartReport(report)` | Checks an API report and converts it to a `PartModel`. |
1247
- | `buildRegionIndex({ regions, features, triangleCount })` | Builds the lookups between triangles, faces, and features. |
1248
- | `model.regionIndex.featuresForRegion(i)` | The features that own a face. |
1249
- | `model.regionIndex.regionsForFeature(tag)` | The faces that make up a feature. |
1250
- | `focusForPick(pick, lastRegion, lastFocus)` | Steps through a face's matches on repeated clicks. |
1251
- | `rankOwners` / `bestOwner` | The ranking `onPick` uses, if you want to run it yourself. |
1252
- | `groupByDirection(model)` | Features grouped by machining direction. |
1253
- | `featureTriangles(model, geometry, tag)` | A feature's triangles and outward normals, as plain arrays. |
1254
- | `directionLabel(v)` / `directionColor(i)` | A direction's label and colour. |
1255
- | `sectionFromPick({ point, normal })` | Turns a clicked surface into a section plane. |
1256
- | `measurementLabel(measurement, format?)` | Writes a measurement the way `<MeasureTool>` labels it. |
1257
- | `snapAt(hit, edges, camera, viewport)` | Where a point on the part snaps to, for a tool of your own. |
1258
- | `engineGeometryCache.clear()` | Frees every cached mesh. |
1308
+ | Helper | What it does |
1309
+ | -------------------------------------------------------- | -------------------------------------------------------------------- |
1310
+ | `normalizePartReport(report)` | Checks an API report and converts it to a `PartModel`. |
1311
+ | `buildRegionIndex({ regions, features, triangleCount })` | Builds the lookups between triangles, faces, and features. |
1312
+ | `model.regionIndex.featuresForRegion(i)` | The features that own a face. |
1313
+ | `model.regionIndex.regionsForFeature(tag)` | The faces that make up a feature. |
1314
+ | `focusForPick(pick, lastRegion, lastFocus)` | Steps through a face's matches on repeated clicks. |
1315
+ | `rankOwners` / `bestOwner` | The ranking `onPick` uses, if you want to run it yourself. |
1316
+ | `groupByDirection(model)` | Features grouped by machining direction. |
1317
+ | `featureTriangles(model, geometry, tag)` | A feature's triangles and outward normals, as plain arrays. |
1318
+ | `directionLabel(v)` / `directionColor(i)` | A direction's label and colour. |
1319
+ | `sectionFromPick({ point, normal })` | Turns a clicked surface into a section plane. |
1320
+ | `measurementLabel(measurement, format?)` | Writes a measurement the way `<MeasureTool>` labels it. |
1321
+ | `snapAt(hit, edges, camera, viewport)` | Where a point on the part snaps to, for a tool of your own. |
1322
+ | `surfaceCreases(geometry, model)` | Every edge between two faces, with its angle and which way it folds. |
1323
+ | `sharpCornerPositions(creases, model, options)` | The ones `sharpCorners` would draw, as line segment endpoints. |
1324
+ | `findSharpCorners(creases, model, options)` | The same, as whole corners: feature, ends, length and angle. |
1325
+ | `engineGeometryCache.clear()` | Frees every cached mesh. |
1259
1326
 
1260
1327
  The package also exports lower-level geometry, camera, and view-cube functions that the components
1261
1328
  use. They're listed in `dist/index.d.ts`.
@@ -1269,7 +1336,7 @@ use. They're listed in `dist/index.d.ts`.
1269
1336
  `MeasureMode`, `Measurement`, `DistanceMeasurement`, `AngleMeasurement`, `Snap`, `SnapKind`,
1270
1337
  `ViewerTheme`, `ViewName`, `DirectionArrowsProps`, `NamedDirection`, `GridProps`, `AxesProps`,
1271
1338
  `ViewCubeProps`, `ViewerToolbarProps`, `ViewerToolbarControlsProps`, `ViewerToolbarControls`,
1272
- `ViewerToolbarControl`.
1339
+ `ViewerToolbarControl`, `SharpCorner`, `SharpCornerOptions`, `SurfaceCreases`.
1273
1340
 
1274
1341
  `FeatureType` and `ShapeKind` accept any string, because newer Engine versions add new values.
1275
1342
  Handle values you don't recognize.