Workpiece

The Workpiece editor is the equipment/mechanism/workpiece branch of the Equipment page's Control Tree (/equipment?tree=equipment/mechanism/workpiece); /workpiece and anything below it redirect there, and a legacy ?tree= link into the retired anchor items under it lands on this root.

The key model is Workpiece, taken from the project service's Workpiece. The cached solids it is drawn from belong to WorkpieceService.

The branch edits what is the workpiece's own: the raw and target geometry, the runtime resolution and the material files. Where the workpiece sits — its anchors, branches and transformers — is part of the equipment topology and is edited in the page's Topology column; which of those anchors plays which role is bound on this item's root panel. See Equipment Topology.

The branch has no display config of its own: it shares the Equipment canvas, gated by the equipment-setup config (Disp/EquipmentSetupDisplayeeConfig.cs), which carries the fixture and workpiece flags together — the fixture and workpiece geometry anchors keep separate flags, while the fixture↔workpiece mount pair, being one attached identity at one location, is a single flag.

Layout

Control Tree Branch

Workpiece Root — a summary panel, rendered inline in the page's editor column. It carries no Object Management button: the workpiece has no standalone .Workpiece file surface here, and its geometry, mesh and material are all edited through the child items below.
- Raw Geometry Type Badge and Target Geometry Type Badge — the kind, Transformed {kind} under a transform, none when the slot is empty
- Intro caption, and an empty-state caption while the project has no workpiece
- Roles panel — titled Roles, one row per role of the workpiece's own assembly, all three anchors and all three required:
  - Fixture Mount (FixtureMount) — the anchor the fixture's workpiece mount, or the machine's worktable end when the project has no fixture, attaches to.
  - Program-Zero Anchor (ProgramZeroAnchor) — the frame the NC program is written in.
  - Geometry Anchor (GeomAnchor) — the frame the raw and target geometry are placed in.
  - Each row shows the role's label, its kind and required, a select over the workpiece's own anchors (clearing it unbinds), and an arm button (a target icon, tooltip “Pick on the graph”) that arms the role: the next click on one of the workpiece's anchors in the Topology column binds it.
  - Below the rows, the server's checks on the current binding — Unbound, NotOwn, Duplicate, NotReachable — or All checks pass. An incomplete binding is a legitimate editing state; the run start is what refuses a workpiece with a role missing.
There is no anchor item under this root. The workpiece's anchors and the branches between them — by default one from the geometry anchor to the fixture mount and one to the program-zero anchor, each carrying a transformer — are edited on the Workpiece cluster of the Topology column, like the fixture's. A workpiece anchor never carries a solid: the anchor card's Geometry section is absent on the workpiece, and the solid-writing routes answer 409 SolidsNotAllowed, because the raw and target geometry are the workpiece's own properties on the two items below.
equipment/mechanism/workpiece/raw-geometry — “Raw Geometry”, a Geometry slot backing InitGeom. The slot's own panel is the kind picker (Geometry Management Control, selector only); the picked kind's editor is the slot's child item, headed by the Transform picker — No Transform, or a transformer kind that places the geometry, whose editor is a further child item under the kind's. Kinds offered: Box3d, Cylindroid, StlFile, GeomCombination, CubeTreeFile, plus None; a transformed slot reads as its inner kind, never as TransformationGeom. ExtendedCylinder is an IMakeXmlSource but is not offered: its start section is wired by a host and never serialized, and a workpiece slot has no host, so a saved project would reload it degenerate; see ExtendedCylinder Editor for how an older project holding one still displays it — as the slot's current kind, which the picker lists but only re-selects. The source choice folds into that one picker — picking the voxel CubeTreeFile, which the picker shows as MeshedGeomFile, is the meshed source (see MeshedGeomFile Editor).
equipment/mechanism/workpiece/target-geometry — “Target Geometry”, the same slot shape backing IdealGeom, with the same Transform picker on its child item. Kinds offered: Box3d, Cylindroid, StlFile, plus None. The target must satisfy IGetStl, so CubeTreeFile is not among them.
equipment/mechanism/workpiece/runtime — labelled Mesh in the tree.
- Initial Resolution Select (InitResolution, in mm), a fifteen-step powers-of-two ladder:
  - 0.0009765625
  - 0.001953125
  - 0.00390625
  - 0.0078125
  - 0.015625
  - 0.03125
  - 0.0625
  - 0.125
  - 0.25
  - 0.5
  - 1
  - 2
  - 4
  - 8
  - 16
- Hint caption: a smaller resolution means a finer voxel grid and a slower runtime simulation.
- The engine's own ladder bottoms out at 0.001953125, so the first entry builds the same mesh as the second. Values typed in from elsewhere are rounded to the next finer rung rather than used as given — see Mesh Resolution.
- Under a licence that caps the resolution, the rungs finer than the width the licence allows this workpiece are greyed, never dropped: the server computes that width (GET /api/Workpiece/resolution-cap, below) and the picker only greys. A caption names the width, the ratio — 1/N of the workpiece's longest side, taken to the coarser rung — and the longest side it was measured from: the standing tree's own reference while that tree stands for the authored geometry (built from it, loaded for it, read or set under it), else the authored geometry's bounds; a stored value finer than that stays selectable, and a second caption says the stock is then built at the licensed width, which is what the engine's own warning, Workpiece-InitResolution--ClampedByLicense, says at the build. Nothing is greyed and no caption shows while the server reports no width — no cap in force, no reference size yet, the read failed — and the first caption is left out when the licensed width is the engine's own bottom, 0.001953125, since nothing is greyed then: the ladder's finest entry builds that same width, so it is not finer either.
- A meshed-geometry stock (CubeTreeFile, a .wct) is read at its own resolution whatever the licence says, so the item is not capped for it: nothing greyed, no caption.
- A setup edit — every write that ends in LocalProjectService.NotifySetupEquipmentEdited: a raw-geometry kind picked, the stock replaced, resized or moved by a transform, the target geometry's edits, this item's own write, the material loads and clears, a machining chain loaded, every topology edit, the program-zero alignment, and the facade's workpiece, fixture, tool, chain and error-terms setters — lets the resolutions never chosen follow the licensed default for the workpiece as it now is, the coarser of 0.125 mm and the licensed width of the authored geometry's bounds: the Initial Resolution and the Machining Resolution commands directly under the Mission root that still stand at the plain 0.125 mm, or at what this rule itself wrote earlier, go up for a larger part and come down again for a smaller one (and the runner's seed a project load copied from the Initial Resolution follows with them — at once while no session is open, else at the next session boundary). A command added into a nested List is outside the rule: it is created at the plain 0.125 mm, as a duplicate is, and the follow does not reach it. With no reference to follow — no geometry, a .wct whose tree is not loaded, a geometry without bounds — nothing is written and nothing is said. Two messages say so otherwise, Workpiece-InitResolution--DefaultFollowsLicense and MachiningResolution--DefaultFollowsLicense — in the messages of the setup edit's response, which every route that ends in NotifySetupEquipmentEdited gathers through a per-request collector and the SPA shows as notifications; on the session shell for a caller that passes no sink of its own while one is open; and in the service log either way. A value set explicitly — this item's own write, a command's field, a session's machining resolution — is the user's whatever it is while the project stays open (the marks are not saved with it): it is kept, and when finer than the licence it is clamped where it is used, with the engine's warning. Loading a project changes nothing — one saved at 0.125 mm under a cap runs clamped, with the warning, until a setup edit lets it follow or the value is set, a 0.125 mm set by hand before the save included — and without a cap nothing changes.
- The panel self-gates on the project having a workpiece.
equipment/mechanism/workpiece/material — “Material”, a Group stem whose info text names the two pre-prepared resources loaded by reference. Built only while the Preference menu's Show Physics Options is on — the two resources exist to feed the cutting-force and thermal physics — and the tree rebuilds when that flag flips. Its two children share one panel, which reads its role from the node's own path:
- .../material/workpiece-material — .WorkpieceMaterial files, seeded to the resource root's WorkpieceMaterial folder.
- .../material/cutting-parameter — .mp files, seeded to the resource root's CuttingParameter folder.
- Each child is one Resource-only File Path Input — the project-directory Browse entry is suppressed, leaving the Resource-root pick — plus a readonly Name field (Name) and a readonly Note field (Note).

Page Frame

The Equipment page lays the Control Tree, the editor, the canvas and the Topology column out side by side in nested splitters with device-local widths; the editor column holds the selected item's panel at the page's full height. See Equipment Page.
Canvas Column — one RenderingCanvas bound to the equipment-setup displayee (Disp/EquipmentSetupDisplayee.cs): the merged fixture + workpiece setup scene, with optional machine and tool solids.
- RenderingCanvas Tool Bar
- Display Options Menu — six groups; the workpiece's own entries are in bold:
  - Solid — Machine, Tool, Meshed Geometry
  - Fixture Rendering Mode — Solid / Edge / Hide
  - Raw Shape Rendering Mode — Solid / Edge / Hide
  - Target Shape Rendering Mode — Solid / Edge / Hide
  - Anchors — Fixture Geometry Anchor, Workpiece Mount (the one flag for the fixture↔workpiece pair), Table Mount, Workpiece Geometry Anchor, Program-Zero Anchor, Controller Coordinate, Role Anchors (off by default; draws every bound role anchor of every part as a triad — the workpiece's three among them — whatever the per-anchor flags say)
  - Display Aids — Dimension Bar
Topology Column — the equipment graph with the Workpiece cluster, where this item's anchors and branch transformers are edited; clicking the cluster selects this root in the Control Tree. See Equipment Topology.

Default Resource

The default resources of Workpiece Material and Cutting Parameter exist in Resource folder under application folder (Not project folder). The two Material items seed their file pickers at the matching Resource sub folder:

“Resource/WorkpieceMaterial”
“Resource/CuttingParameter”

Behavior

A geometry slot's edit re-commits the swap-in before clearing the cache. The canvas draws the runtime face's solids, and that face follows an authored edit only by rebuild, so a bare cache clear would re-solidify a stale face. The re-commit is skipped when the slot is cleared to None: None leaves the old object indexed, and re-committing would resurrect it. The runner plays against the same runtime face, so an API caller editing through a child key owes the same re-install before its next play; see Driving the Web Service over HTTP.
Call WorkpieceService.ClearRawGeomCache() on Raw Shape set or changed.
Call WorkpieceService.ClearIdealGeomCache() on Target Shape set or changed.
The branch reaches that service by posting the controller's cache-clear endpoints. The raw-geometry clear also resets the meshed cube tree while no session is running, so a re-picked source or a kind switch is not served from the previous tree.
A role bind, like every topology edit, rewires the equipment and redraws the canvas; the attachment branches on the graph are re-minted by every rewire, so the Topology column pulls the graph again rather than patching it. A workpiece branch transformer edited there redraws the canvas but does not clear the geometry cache, so a placement change forces no CubeTreeFile re-mesh.
The Mesh item's Initial Resolution feeds the runtime voxel simulation, not the setup canvas, so no cache chain runs after a change.
The equipment canvas snaps to the isometric view when its displayee is bound to a rendering connection; a shape edit on the branch re-commits and clears the cache so the next frame re-solidifies, and leaves the view alone.
The program-zero alignment on the Controller branch does not write on the workpiece: it rewrites the transformer of the fixture branch leading from the fixture's geometry anchor straight to its table mount. See Fixture.
A Workpiece Material is installed as its file writes it. Its load answers messages: a thermal constant that is not a finite positive number, or lies outside the range of a dense solid, comes back there as a warning, which the panel shows as a notification (Material-ThermalConstants--NotFinitePositive, Material-ThermalConstants--OutOfRange), and the values are used as given. An element the file lacks — HeatConductivity_WdmK, Density_gdcm3 or HeatCapacity_JdgK — is not given, and no default stands in: the thermal model is skipped for every tool, with the temperatures left at ambient and the wear at zero, and the material is named the same way (Material-ThermalConstants--NotGiven). The runner says each again when a session or a play begins.
Keep Portability of the Material properties.

Source Code Path

See HiNC App Anatomy for git repository links.

Web Application

HiNC-2025-webservice (Quasar CLI SPA):

wwwroot-src/src/components/controlTree/useControlTreeHost.ts — builds the whole equipment/mechanism/workpiece branch: the root, the two geometry slots, the Mesh item and the physics-gated material group with its two resource items — including each slot's re-commit-then-clear chain and the two allowed-kind whitelists.
wwwroot-src/src/components/controlTree/PrimarySlavePanel.vue — renders the root inline: the Raw and Target type badges, the intro and the Roles panel.
wwwroot-src/src/components/mech/MechanismRolesPanel.vue — the Roles panel: one row per role, the candidate select, the arm-and-pick button and the server's checks.
wwwroot-src/src/components/mech/EquipmentTopologyPanel.vue — the Topology column where the workpiece's anchors and branch transformers are edited; its anchor card leaves out the Geometry section for a workpiece anchor.
wwwroot-src/src/components/controlTree/itemTypes.ts — the ItemType registry mapping the branch's children to their panels.
wwwroot-src/src/components/controlTree/GeometrySlotPanel.vue — the kind picker behind the raw and target geometry slots.
wwwroot-src/src/components/controlTree/WorkpieceRuntimePanel.vue — the Mesh item's editor: the Initial Resolution ladder and its hint, the rungs greyed under a licence that caps the resolution and the two captions that go with them, read from resolution-cap on mount and again after each successful write; a refused write puts the previous value back.
wwwroot-src/src/components/controlTree/WorkpieceResourcePanel.vue — the one panel both Material children share, choosing its extension and resource subfolder from the node's role path, and showing the messages a material load answers as notifications.
wwwroot-src/src/components/widgets/FilePathInput.vue — the file field those children use; its project Browse entry is suppressed under resourceOnly, leaving the Resource-root pick.
wwwroot-src/src/components/mech/EquipmentSetupPanel.vue — the canvas column and its Display Options menu.
wwwroot-src/src/pages/EquipmentPage.vue — the /equipment page hosting the Control Tree, the editor, the canvas and the Topology column in nested splitters.
wwwroot-src/src/router/treeRoutes.ts — the legacy-id hops, among them the one that lands a retired workpiece anchor id on this root.
wwwroot-src/src/api/workpiece.ts — typed client for /api/Workpiece/*: initialize, status, the geometry re-commit and cache-clear calls, init-resolution, resolution-cap, the two resource loads with their untrack counterparts, and the diff settings.
wwwroot-src/src/utils/resolutionLadder.ts — the ladder both resolution pickers share; licensedResolutionOptions marks the rungs finer than the width it is given disabled, the current value excepted, and splices that width in as a selectable rung when it is not on the ladder (a large part under a cap has its licensed width to pick); isFinerThanLicensed judges a value by the width the engine would build for it, so an off-ladder 0.4 is finer than 0.5.
wwwroot-src/src/api/equipmentTopology.ts — typed client for /api/mech/equipment-topology: the graph, the roles and their binds, and the anchor / branch edits under owner workpiece.
wwwroot-src/src/composables/useEquipmentTopology.ts — the module-singleton state the Roles panel and the Topology column share: the graph, the per-owner roles, the armed role and the selection.
wwwroot-src/src/api/equipmentSetup.ts — typed client for the shared canvas: the three rendering-mode targets and the eleven display flags, several of which are the workpiece's own overlays.
Mech/WorkpieceController.cs — the model REST surface at /api/Workpiece: Initialize (the session's workpiece, raw-geometry and ideal-geometry keys) and Status, geometry install and cache clears — among them SetRawGeometryTransform and SetIdealGeometryTransform, which wrap the slot's geometry in place for the Transform picker; every route that ends in a setup edit answers the follow's messages beside its payload, as the material loads do — init-resolution, resolution-cap (what the licence's resolution cap means for the current workpiece: { hasWorkpiece, hasResolutionCap, resolutionCapRatio, referenceSize, referenceSource, licensedWidth, initResolution, initResolutionClamped, stockWidth, stockIsMeshedGeomFile } — referenceSource is rawGeomBounds when the size is the authored geometry's bounds, meshedGeom when it is the standing tree's own — whenever that tree stands for the authored geometry: built from it, loaded for it, read or set under it (MeshedGeomIsOf) — null with no reference; licensedWidth is null when nothing is capped; stockWidth is the width of the stock standing, null until the stock is built and null while the stock standing is not this geometry's (a geometry edit whose stock the next play has yet to build); { hasWorkpiece: false } without a workpiece. Read-only, as the process-wide GET /api/preference/license-caps is: no endpoint sets a cap), workpiece-material/load and cutting-parameter/load with their …/untrack counterparts (the Material rows' Clear: the file reference is dropped, the loaded resource stays and is saved inline), and the geometry-diff settings pair (the project-level visual radius and the detection radius the current overlay was built with) whose panel rides the Execution page's Program branch, on the Geometry Difference result node, rather than this branch.
Mech/Topology/EquipmentTopologyController.cs — /api/mech/equipment-topology: the graph, the roles (GET roles/workpiece, POST roles/workpiece/{role}) and the anchor / branch routes under owner workpiece; its solid-writing routes (enable-geom, disable-geom, index-geom, create-geom) answer 409 SolidsNotAllowed for that owner.
Mech/Topology/EquipmentRoles.cs — the role catalogue and checks the Roles panel lists.
Mech/EquipmentSetupDisplayController.cs — /api/mech/equipment-setup-display: binds the equipment-setup displayee to a rendering connection, framing it isometrically at bind time, and serves the rendering-mode and flag endpoints.
Disp/EquipmentSetupDisplayee.cs — the merged fixture + workpiece setup scene the canvas draws.
Disp/EquipmentSetupDisplayeeConfig.cs — its config: the fixture and workpiece display flags in one place, ShowRoleAnchors among them.

HiAPI Engine

HiMech/NcMech/Workpieces/Workpiece.cs — the key model: its own assembly, root anchor and empty solid dictionary; the three roles as settable anchor properties that check only that the anchor is the workpiece's own; CreateDefault for the default two-branch layout; the raw and target geometry, the initial resolution — with the licensed default an added command takes and a value never chosen follows, the coarser of 0.125 mm and the licensed width — and the material file references.
HiMech/NcMech/Workpieces/WorkpieceService.cs — the cached render solids, the meshed geometry, the two cache clears the branch posts, and the reference size the licence's cap is measured against: the standing tree's own reference while that tree stands for the authored geometry (the number the engine's clamp reads; a tree built from a shape recorded the raw bounds' longest side), else the longest side of the authored geometry's bounds — the service remembers what its tree stands for (MeshedGeomIsOf), so a tree of a previous geometry never answers — never a mesh generation.
HiNc/MachiningProcs/LocalProjectService.cs — NotifySetupEquipmentEdited, which every setup edit ends in: the resolutions never chosen following the licensed default (FollowLicensedDefaultResolutions, with the explicit writes marked chosen through MarkInitResolutionChosen / MarkMachiningResolutionChosen), before the runtime face follows the authored one; ReferenceSizeForCap_mm, the one reference every entrance of the rule — the added command's default, the follow, the runner's seed, the REST reply — is judged against: the standing tree's own reference while that tree stands for the authored geometry, else the authored geometry's bounds, with the stock's width beside it only while the stock standing is this geometry's.
HiMech/Machining/MachiningEquipmentUtils/MachiningEquipmentUtil.cs — the program-zero alignment, which measures the workpiece's program-zero anchor and writes onto the fixture branch.

Table of Contents