@toolpath/viewer 1.1.0 → 1.2.0

package/dist/{normalize-OULo7e0F.d.ts → normalize-DHOSNiuO.d.ts}

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { Group, Mesh, LineSegments, Box3, Plane, BufferGeometry, Camera, Vector3 } from 'three';
+import { Group, Mesh, LineSegments, Box3, Plane, BufferGeometry, Vector3, Raycaster, Object3D, Intersection, Camera } from 'three';
 
 /**
  * The normalized part — the only thing the renderer consumes.
@@ -175,8 +175,13 @@ interface ViewerTheme {
     /** `EdgesGeometry` line color and opacity. */
     readonly edge: number;
     readonly edgeOpacity: number;
-    /** The capped face of a section cut, and the cutting plane's outline. */
+    /**
+     * The capped face of a section cut: its fill, and the hatch lines drawn over
+     * it. The cap's edge takes {@link ViewerTheme.sectionHandleOutline}.
+     */
     readonly sectionCap: number;
+    readonly sectionHatch: number;
+    /** The cutting plane itself — the translucent sheet `<SectionTool>` draws, its outline, and the surface preview. */
     readonly sectionOutline: number;
     /**
      * The arrow that drags the cut, and the shell that outlines it. Hovered it
@@ -184,6 +189,13 @@ interface ViewerTheme {
      */
     readonly sectionHandle: number;
     readonly sectionHandleOutline: number;
+    /**
+     * A measurement: its lines, end markers, arc and label border, as
+     * `<MeasureTool>` draws them. The indicator that shows where the pointer
+     * will snap takes {@link ViewerTheme.measureSnap}.
+     */
+    readonly measure: number;
+    readonly measureSnap: number;
     /**
      * The view cube's panels, the lines between them, and its face names. A
      * hovered panel takes {@link ViewerTheme.hover}, the same color the part uses
@@ -397,101 +409,144 @@ interface HighlightLayers {
 declare function applyHighlightLayers(part: PartObject, layers: HighlightLayers, theme: ViewerTheme): void;
 
 /**
- * Which modifier keys were down when the pick happened.
- *
- * Reported rather than interpreted: "hold this to add to the selection" is a
- * platform convention — command on a Mac, control everywhere else — and which
- * key means what belongs to the app, not to a viewport.
+ * Render order. The stencil pass must precede the cap, and the part must draw
+ * after both or it overwrites the cap it is supposed to be capped by. The part
+ * draws at 3 and its edges at 4, so the handle sits above the cap it stands on.
  */
-interface PickModifiers {
-    readonly alt: boolean;
-    readonly ctrl: boolean;
-    readonly meta: boolean;
-    readonly shift: boolean;
-    /** The right button, on a click that did not become a pan. */
-    readonly secondary: boolean;
-}
-declare const NO_MODIFIERS: PickModifiers;
+declare const SECTION_RENDER_ORDER: {
+    readonly stencil: 1;
+    readonly cap: 2;
+    readonly handle: 6;
+    /** The tool's translucent plane and its outline, over everything but the handle. */
+    readonly outline: 5;
+};
+/** The handle's length on screen, in CSS pixels, whatever the zoom. */
+declare const HANDLE_PIXELS = 78;
 /**
- * A pointer event on the part, resolved to the face it landed on and the
- * features that own it.
- *
- * `owners` travels alongside `best` on purpose. A click resolves to five to
- * eight readings and the ranking puts one of them up; that is a *default*, not
- * a claim of correctness, and a consumer that was handed only the winner could
- * not offer the alternatives it silently discarded.
+ * The hatch on the cap: stripe pitch and line thickness in CSS pixels, and the
+ * outline's width. Screen-space, so the cut reads the same at any zoom.
  */
-interface PartPick {
-    readonly region: number;
-    /** Every feature owning the face, in report order. */
-    readonly owners: readonly FeatureTag[];
-    /** The same set, ranked for this click. Filtered by an active direction. */
-    readonly ranked: readonly FeatureTag[];
-    /** The ranked pick, or `null` when nothing here is reachable that way. */
-    readonly best: FeatureTag | null;
-    readonly triangleIndex: number;
-    readonly point: readonly [number, number, number];
-    /** The surface's outward normal in world space — the plane under the cursor. */
-    readonly normal: readonly [number, number, number];
-    readonly modifiers: PickModifiers;
+declare const CAP_HATCH: {
+    readonly pitch: 9;
+    readonly line: 1.25;
+    readonly outline: 1.5;
+};
+/**
+ * The global cutting planes the tool offers: how far outside the part each one
+ * stands, and how much larger than the part it is drawn. Both are fractions of
+ * the part's largest dimension.
+ */
+declare const AXES_PLANE_OFFSET = 0.55;
+declare const AXES_PLANE_SCALE = 1.2;
+/** The surface preview under the pointer, as a fraction of the part's diagonal. */
+declare const PREVIEW_SCALE = 0.125;
+/** How far the tool's translucent plane extends past the part, as a fraction of the diagonal. */
+declare const OUTLINE_SCALE = 1.2;
+interface SectionOptions {
+    enabled: boolean;
     /**
-     * Whether this click completed a double click on the part.
-     *
-     * Reported rather than interpreted, for the same reason the modifiers are:
-     * what a second click means belongs to the app. A viewer that decided —
-     * withholding the pick so a double click could not disturb the selection —
-     * would be right for a list that walks through a face's readings and wrong
-     * for an editor where clicking a face twice puts it in and takes it out
-     * again. Both are ordinary, and only the app knows which one it is showing.
-     *
-     * The viewport still acts on the gesture itself: `retargetOnDoubleClick`
-     * re-aims the orbit, which is a question about the view rather than about the
-     * part, and is nobody else's to answer.
+     * The half-space that stays. Defaults to +Z, which keeps the top of the part
+     * and eats upward from the bottom as `offset` grows.
      */
-    readonly doubled: boolean;
+    normal?: Vec3;
+    /** Where the sweep sits, 0 (whole part) to 1 (gone). */
+    offset?: number;
+    /** Key the cut off one surface instead, usually from `sectionFromPick`. */
+    plane?: SectionPlacement | null;
+    /** How far past that surface to cut, in model units. */
+    depth?: number;
 }
-/** A unit vector from the part toward the camera, for the owner ranking. */
-declare function viewDirection(camera: Camera, target: Vector3): Vec3;
-interface BuildPickInput {
-    readonly model: PartModel;
-    readonly region: number;
-    readonly triangleIndex: number;
-    readonly point: readonly [number, number, number];
-    readonly normal: readonly [number, number, number];
-    readonly modifiers?: PickModifiers;
+interface SectionState {
+    readonly enabled: boolean;
+    readonly normal: Vec3;
+    readonly offset: number;
+    readonly constant: number;
+    readonly plane: SectionPlacement | null;
+    readonly depth: number | null;
     /**
-     * The machining direction the pick is scoped to, as an index into
-     * `candidateDirections`. Narrows the owners to two, one, or **none** — the
-     * empty case is real, and reads as "nothing here in this direction" rather
-     * than as a pick that missed.
+     * How far the cut can travel from its anchor, in model units, or `null` for a
+     * sweep — which is measured as a fraction of the part rather than a distance.
+     *
+     * Reported because a control that moves the cut has to be bounded by the same
+     * numbers the cut is, and only the viewer knows the part's extent along a
+     * given normal.
      */
-    readonly activeDirection?: number | null;
-    readonly viewDirection?: Vec3 | null;
-    /** Whether this click completed a double click. Defaults to `false`. */
-    readonly doubled?: boolean;
+    readonly depthRange: {
+        readonly min: number;
+        readonly max: number;
+    } | null;
+}
+declare const DEFAULT_SECTION_NORMAL: Vec3;
+/**
+ * What is reported when a cut goes away.
+ *
+ * A state rather than `null`, so a consumer that echoes the callback into its
+ * own state never has to special-case the absence: `enabled` says it.
+ */
+declare const DISABLED_SECTION: SectionState;
+/**
+ * The options that would resolve to `state` again.
+ *
+ * A cut keyed off a surface keeps its anchor and is moved by depth; a sweep is
+ * moved by offset. The state carries both descriptions, and which one to keep
+ * is what makes a dragged cut stay anchored to the face it was picked from.
+ */
+declare function sectionOptionsFromState(state: SectionState): SectionOptions;
+/** One of the three global cutting planes the tool offers. */
+interface AxesPlane {
+    /** Which world axis the plane is perpendicular to. */
+    readonly axis: 'x' | 'y' | 'z';
+    /** Which side of the part the camera is on along that axis, +1 or -1. */
+    readonly sign: 1 | -1;
+    /** Where to draw it: outside the part, on the side away from the camera. */
+    readonly position: Vec3;
+    /** Its edge length. */
+    readonly size: number;
+    /** The sweep a click on it starts: cutting in from the camera's side, halfway through. */
+    readonly options: SectionOptions;
 }
-declare function buildPick(input: BuildPickInput): PartPick;
 /**
- * The owner to focus for a click, given what the last click focused.
+ * Where the three global planes stand for a camera at `eye`.
  *
- * Clicking the same face again walks its readings — the standard CAD escape
- * hatch for an ambiguous click — while a click on a different face starts from
- * that face's own best answer.
+ * They sit past the part on the side *away* from the camera, like the walls of
+ * a room the part is standing in, so the part is never hidden behind them —
+ * and each one cuts in from the camera's own side, which is the half of the
+ * part somebody looking at it can see into. A camera dead on an axis has no
+ * side along the other two; they fall to +1, so the planes still stand
+ * somewhere rather than at the part's centre.
  */
-declare function focusForPick(pick: PartPick, previousRegion: number | null, previousFocus: FeatureTag | null): FeatureTag | null;
-
+declare function axesPlanes(box: Box3, eye: Vec3): readonly AxesPlane[];
+/** A point on the part under the pointer, with the surface's outward normal in world space. */
+interface SurfaceHit {
+    readonly point: Vector3;
+    readonly normal: Vector3;
+}
 /**
- * Render order. The stencil pass must precede the cap, and the part must draw
- * after both or it overwrites the cap it is supposed to be capped by. The part
- * draws at 3 and its edges at 4, so the handle sits above the cap it stands on.
+ * The nearest hit on the part along `raycaster`'s ray, or `null`.
+ *
+ * "The part" is whatever in the scene is a visible mesh outside an overlay —
+ * every overlay here marks its outermost group with `EXCLUDE_FROM_FRAME`, the
+ * same flag that keeps it out of the camera's framing, and the ones that are
+ * not clickable turn their own raycast off besides. What is left is the
+ * geometry the consumer put in.
+ *
+ * A surface a section cut has clipped away is skipped too. three's raycaster
+ * knows nothing about clipping planes, so without this a ray through the open
+ * half of a cut part lands on a face nobody can see — and a tool that previews
+ * or measures there is working on something that is not on screen.
  */
-declare const SECTION_RENDER_ORDER: {
-    readonly stencil: 1;
-    readonly cap: 2;
-    readonly handle: 6;
-};
-/** The handle's length on screen, in CSS pixels, whatever the zoom. */
-declare const HANDLE_PIXELS = 78;
+declare function hitUnderRay(raycaster: Raycaster, root: Object3D): Intersection | null;
+/**
+ * The nearest surface of the part along `raycaster`'s ray, or `null`, with the
+ * surface's outward normal in world space. Used by the tool to preview a cut
+ * on a hovered face without the part having to tell it where the pointer is.
+ */
+declare function surfaceUnderRay(raycaster: Raycaster, root: Object3D): SurfaceHit | null;
+/**
+ * Where the cut's plane meets the line through the part's centre along its
+ * normal — where the cap, the handle and the tool's outline all sit.
+ */
+declare function sectionAnchor(box: Box3, plane: Plane, into?: Vector3): Vector3;
 interface SectionBounds {
     /** Plane constant at which the whole part is clipped away. */
     readonly min: number;
@@ -586,68 +641,89 @@ declare function sectionPlane(box: Box3, normal: Vec3, offset: number, into?: Pl
  */
 declare function dragPlane(axis: Vector3, view: Vector3, point: Vector3, into?: Plane): Plane;
 
-interface SectionOptions {
-    enabled: boolean;
-    /**
-     * The half-space that stays. Defaults to +Z, which keeps the top of the part
-     * and eats upward from the bottom as `offset` grows.
-     */
-    normal?: Vec3;
-    /** Where the sweep sits, 0 (whole part) to 1 (gone). */
-    offset?: number;
-    /** Key the cut off one surface instead, usually from `sectionFromPick`. */
-    plane?: SectionPlacement | null;
-    /** How far past that surface to cut, in model units. */
-    depth?: number;
+/**
+ * Which modifier keys were down when the pick happened.
+ *
+ * Reported rather than interpreted: "hold this to add to the selection" is a
+ * platform convention — command on a Mac, control everywhere else — and which
+ * key means what belongs to the app, not to a viewport.
+ */
+interface PickModifiers {
+    readonly alt: boolean;
+    readonly ctrl: boolean;
+    readonly meta: boolean;
+    readonly shift: boolean;
+    /** The right button, on a click that did not become a pan. */
+    readonly secondary: boolean;
 }
-interface SectionState {
-    readonly enabled: boolean;
-    readonly normal: Vec3;
-    readonly offset: number;
-    readonly constant: number;
-    readonly plane: SectionPlacement | null;
-    readonly depth: number | null;
+declare const NO_MODIFIERS: PickModifiers;
+/**
+ * A pointer event on the part, resolved to the face it landed on and the
+ * features that own it.
+ *
+ * `owners` travels alongside `best` on purpose. A click resolves to five to
+ * eight readings and the ranking puts one of them up; that is a *default*, not
+ * a claim of correctness, and a consumer that was handed only the winner could
+ * not offer the alternatives it silently discarded.
+ */
+interface PartPick {
+    readonly region: number;
+    /** Every feature owning the face, in report order. */
+    readonly owners: readonly FeatureTag[];
+    /** The same set, ranked for this click. Filtered by an active direction. */
+    readonly ranked: readonly FeatureTag[];
+    /** The ranked pick, or `null` when nothing here is reachable that way. */
+    readonly best: FeatureTag | null;
+    readonly triangleIndex: number;
+    readonly point: readonly [number, number, number];
+    /** The surface's outward normal in world space — the plane under the cursor. */
+    readonly normal: readonly [number, number, number];
+    readonly modifiers: PickModifiers;
     /**
-     * How far the cut can travel from its anchor, in model units, or `null` for a
-     * sweep — which is measured as a fraction of the part rather than a distance.
+     * Whether this click completed a double click on the part.
      *
-     * Reported because a control that moves the cut has to be bounded by the same
-     * numbers the cut is, and only the viewer knows the part's extent along a
-     * given normal.
+     * Reported rather than interpreted, for the same reason the modifiers are:
+     * what a second click means belongs to the app. A viewer that decided —
+     * withholding the pick so a double click could not disturb the selection —
+     * would be right for a list that walks through a face's readings and wrong
+     * for an editor where clicking a face twice puts it in and takes it out
+     * again. Both are ordinary, and only the app knows which one it is showing.
+     *
+     * The viewport still acts on the gesture itself: `retargetOnDoubleClick`
+     * re-aims the orbit, which is a question about the view rather than about the
+     * part, and is nobody else's to answer.
      */
-    readonly depthRange: {
-        readonly min: number;
-        readonly max: number;
-    } | null;
+    readonly doubled: boolean;
 }
-/** The cut's plane for a set of options, or `null` when there is no cut. */
-declare function resolveSectionPlane(options: SectionOptions | undefined, box: Box3): {
-    plane: Plane;
-    state: SectionState;
-} | null;
-interface SectionViewProps {
-    geometry: BufferGeometry;
-    box: Box3;
-    plane: Plane;
-    theme: ViewerTheme;
-    showHandle: boolean;
-    onDrag?: (constant: number) => void;
+/** A unit vector from the part toward the camera, for the owner ranking. */
+declare function viewDirection(camera: Camera, target: Vector3): Vec3;
+interface BuildPickInput {
+    readonly model: PartModel;
+    readonly region: number;
+    readonly triangleIndex: number;
+    readonly point: readonly [number, number, number];
+    readonly normal: readonly [number, number, number];
+    readonly modifiers?: PickModifiers;
+    /**
+     * The machining direction the pick is scoped to, as an index into
+     * `candidateDirections`. Narrows the owners to two, one, or **none** — the
+     * empty case is real, and reads as "nothing here in this direction" rather
+     * than as a pick that missed.
+     */
+    readonly activeDirection?: number | null;
+    readonly viewDirection?: Vec3 | null;
+    /** Whether this click completed a double click. Defaults to `false`. */
+    readonly doubled?: boolean;
 }
+declare function buildPick(input: BuildPickInput): PartPick;
 /**
- * A clipping plane with a solid cap over the cut, and an arrow that drags it.
- *
- * The cap is the standard two-pass stencil trick: draw the clipped geometry's
- * back faces incrementing the stencil and its front faces decrementing it, so a
- * non-zero stencil marks exactly where the plane passes through solid material,
- * then fill that region with a quad. Without it a section shows the inside of
- * the far wall and the part reads as hollow.
+ * The owner to focus for a click, given what the last click focused.
  *
- * **The renderer must be created with `stencil: true`.** three defaults it to
- * false, and without it every one of those stencil operations is a silent
- * no-op — the cut still happens and the part still looks hollow, which is a
- * confusing way to find out.
+ * Clicking the same face again walks its readings — the standard CAD escape
+ * hatch for an ambiguous click — while a click on a different face starts from
+ * that face's own best answer.
  */
-declare const SectionView: ({ geometry, box, plane, theme, showHandle, onDrag, }: SectionViewProps) => react.JSX.Element;
+declare function focusForPick(pick: PartPick, previousRegion: number | null, previousFocus: FeatureTag | null): FeatureTag | null;
 
 interface PartMeshProps {
     /** The normalized report. `engine/normalize.ts` produces it. */
@@ -692,17 +768,23 @@ interface PartMeshProps {
      */
     activeDirection?: number | null;
     /**
-     * The section cut. Omit, or pass `enabled: false`, for none.
+     * The section cut. Pass `enabled: false` for none.
      *
      * Either sweep an axis — `normal` points into the half that stays and
      * `offset` runs 0 (whole) to 1 (gone) — or key the cut off one surface with
      * `plane`, which `depth` then moves in model units. `sectionFromPick` turns a
      * pick into that placement with the normal the right way round.
+     *
+     * **Omit it** and the part follows the cut the viewer holds for itself — the
+     * one `<SectionTool>` places and `ViewerHandle.setSection` sets — and shows
+     * the handle whenever there is one. Passing it takes that over: the cut is
+     * then the consumer's, and the viewer's own is ignored.
      */
     section?: SectionOptions;
     /**
      * The cut changed, including when the handle was dragged. Emitted only on a
-     * real change, so echoing it into state is safe.
+     * real change, so echoing it into state is safe. A cut going away is
+     * reported as `enabled: false`, once.
      */
     onSectionChange?: (state: SectionState) => void;
     /**
@@ -818,4 +900,4 @@ declare function normalizePartReport(report: unknown): PartModel;
  */
 declare function assertSupportedKernelVersion(kernelVersion: string): void;
 
-export { focusForPick as $, type SectionBounds as A, type BuildPickInput as B, CANDIDATE_WEIGHT as C, DEFAULT_THEME as D, EnginePart as E, type FeatureTag as F, type SectionOptions as G, HANDLE_PIXELS as H, type SectionPlacement as I, type SectionState as J, type KnownFeatureType as K, SectionView as L, MIN_KERNEL_VERSION as M, NO_MODIFIERS as N, type ShapeKind as O, type PartModel as P, applyHighlightLayers as Q, type RegionIndex as R, SECTION_RENDER_ORDER as S, type TriangleRange as T, buildPick as U, type Vec3 as V, buildRegionAttribute as W, buildRegionTexels as X, createPart as Y, directionColor as Z, dragPlane as _, type PartMeshRefs as a, pickedStartDepth as a0, resolveSectionPlane as a1, resolveTheme as a2, sectionBounds as a3, sectionConstant as a4, sectionDepth as a5, sectionDepthConstant as a6, sectionDepthRange as a7, sectionFromPick as a8, sectionOffset as a9, sectionPlane as aa, themesEqual as ab, viewDirection as ac, type EnginePartProps as b, assertSupportedKernelVersion as c, type ViewerTheme as d, type PartModelRegion as e, type PartModelFeature as f, type FeatureType as g, DIRECTION_COLORS as h, type FeatureHighlight as i, HIGHLIGHT_COLORS as j, HIGHLIGHT_WEIGHT as k, HOVER_WEIGHT as l, type HighlightLayers as m, normalizePartReport as n, type KnownShapeKind as o, PICKED_SURFACE_LABEL as p, PartMesh as q, type PartMeshProps as r, smoothRegionNormals as s, type PartObject as t, type PartPick as u, type PickModifiers as v, REGION_ATTRIBUTE as w, type RegionHighlight as x, type RegionPaint as y, type SectionAnchor as z };
+export { type SurfaceHit as $, AXES_PLANE_OFFSET as A, type BuildPickInput as B, CANDIDATE_WEIGHT as C, DEFAULT_SECTION_NORMAL as D, EnginePart as E, type FeatureTag as F, type PartObject as G, HANDLE_PIXELS as H, type PartPick as I, type PickModifiers as J, type KnownFeatureType as K, REGION_ATTRIBUTE as L, MIN_KERNEL_VERSION as M, NO_MODIFIERS as N, OUTLINE_SCALE as O, type PartModel as P, type RegionHighlight as Q, type RegionIndex as R, type SectionOptions as S, type TriangleRange as T, type RegionPaint as U, type Vec3 as V, SECTION_RENDER_ORDER as W, type SectionAnchor as X, type SectionBounds as Y, type SectionPlacement as Z, type ShapeKind as _, type PartMeshRefs as a, applyHighlightLayers as a0, axesPlanes as a1, buildPick as a2, buildRegionAttribute as a3, buildRegionTexels as a4, createPart as a5, directionColor as a6, dragPlane as a7, focusForPick as a8, hitUnderRay as a9, pickedStartDepth as aa, resolveTheme as ab, sectionAnchor as ac, sectionBounds as ad, sectionConstant as ae, sectionDepth as af, sectionDepthConstant as ag, sectionDepthRange as ah, sectionFromPick as ai, sectionOffset as aj, sectionOptionsFromState as ak, sectionPlane as al, surfaceUnderRay as am, themesEqual as an, viewDirection as ao, type EnginePartProps as b, assertSupportedKernelVersion as c, type ViewerTheme as d, type SectionState as e, type PartModelRegion as f, type PartModelFeature as g, type FeatureType as h, AXES_PLANE_SCALE as i, type AxesPlane as j, CAP_HATCH as k, DEFAULT_THEME as l, DIRECTION_COLORS as m, normalizePartReport as n, DISABLED_SECTION as o, type FeatureHighlight as p, HIGHLIGHT_COLORS as q, HIGHLIGHT_WEIGHT as r, smoothRegionNormals as s, HOVER_WEIGHT as t, type HighlightLayers as u, type KnownShapeKind as v, PICKED_SURFACE_LABEL as w, PREVIEW_SCALE as x, PartMesh as y, type PartMeshProps as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toolpath/viewer",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "React Three Fiber viewer for Toolpath Engine part reports",
   "license": "MIT",
   "engines": {