HiNC-2025-win-desktop-Deploy/App/wwwroot/HiAPI-docsite/anatomy/general-setup/workpiece.html

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
      <title>Workpiece | HiAPI-C# 2025 </title>
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <meta name="title" content="Workpiece | HiAPI-C# 2025 ">
      
      
      <link rel="icon" href="../../img/HiAPI.favicon.ico">
      <link rel="stylesheet" href="../../public/docfx.min.css">
      <link rel="stylesheet" href="../../public/main.css">
      <meta name="docfx:navrel" content="../../toc.html">
      <meta name="docfx:tocrel" content="toc.html">
      
      <meta name="docfx:rel" content="../../">
      
      
      
      <meta name="loc:inThisArticle" content="In this article">
      <meta name="loc:searchResultsCount" content="{count} results for &quot;{query}&quot;">
      <meta name="loc:searchNoResults" content="No results for &quot;{query}&quot;">
      <meta name="loc:tocFilter" content="Filter by title">
      <meta name="loc:nextArticle" content="Next">
      <meta name="loc:prevArticle" content="Previous">
      <meta name="loc:themeLight" content="Light">
      <meta name="loc:themeDark" content="Dark">
      <meta name="loc:themeAuto" content="Auto">
      <meta name="loc:changeTheme" content="Change theme">
      <meta name="loc:copy" content="Copy">
      <meta name="loc:downloadPdf" content="Download PDF">

      <script type="module" src="./../../public/docfx.min.js"></script>

      <script>
        const theme = localStorage.getItem('theme') || 'auto'
        document.documentElement.setAttribute('data-bs-theme', theme === 'auto' ? (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light') : theme)
      </script>

  </head>

  <body class="tex2jax_ignore" data-layout="" data-yaml-mime="">
    <header class="bg-body border-bottom">
      <nav id="autocollapse" class="navbar navbar-expand-md" role="navigation">
        <div class="container-xxl flex-nowrap">
          <a class="navbar-brand" href="../../index.html">
            <img id="logo" class="svg" src="../../img/HiAPI.logo.png" alt="">
            
          </a>
          <button class="btn btn-lg d-md-none border-0" type="button" data-bs-toggle="collapse" data-bs-target="#navpanel" aria-controls="navpanel" aria-expanded="false" aria-label="Toggle navigation">
            <i class="bi bi-three-dots"></i>
          </button>
          <div class="collapse navbar-collapse" id="navpanel">
            <div id="navbar">
              <form class="search" role="search" id="search">
                <i class="bi bi-search"></i>
                <input class="form-control" id="search-query" type="search" disabled placeholder="Search" autocomplete="off" aria-label="Search">
              </form>
            </div>
          </div>
        </div>
      </nav>
    </header>

    <main class="container-xxl">
      <div class="toc-offcanvas">
        <div class="offcanvas-md offcanvas-start" tabindex="-1" id="tocOffcanvas" aria-labelledby="tocOffcanvasLabel">
          <div class="offcanvas-header">
            <h5 class="offcanvas-title" id="tocOffcanvasLabel">Table of Contents</h5>
            <button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#tocOffcanvas" aria-label="Close"></button>
          </div>
          <div class="offcanvas-body">
            <nav class="toc" id="toc"></nav>
          </div>
        </div>
      </div>

      <div class="content">
        <div class="actionbar">
          <button class="btn btn-lg border-0 d-md-none" type="button" data-bs-toggle="offcanvas" data-bs-target="#tocOffcanvas" aria-controls="tocOffcanvas" aria-expanded="false" aria-label="Show table of contents">
            <i class="bi bi-list"></i>
          </button>

          <nav id="breadcrumb"></nav>
        </div>

        <article data-uid="Anatomy-Workpiece">
          <h1 id="workpiece">Workpiece</h1>

<p>The Workpiece editor is the <code>equipment/workpiece</code> branch of the General Setup page's Control Tree (<code>/general-setup?tree=equipment/workpiece</code>); the old <code>/workpiece</code> route redirects there.</p>
<p>The key model is <a class="xref" href="../../api/Hi.NcMech.Workpieces.Workpiece.html">Workpiece</a>, taken from the Main Panel's
<a class="xref" href="../../api/Hi.MachiningProcs.LocalProjectService.html#Hi_MachiningProcs_LocalProjectService_Workpiece">Workpiece</a>. The cached solids it is drawn from belong to
<a class="xref" href="../../api/Hi.NcMech.Workpieces.WorkpieceService.html">WorkpieceService</a>.</p>
<p>The branch has no display config of its own: it shares the General Setup canvas, gated by the equipment-setup config (<code>Disp/EquipmentSetupDisplayeeConfig.cs</code>), which carries
the fixture and workpiece flags together — the fixture and workpiece geometry anchors keep separate
flags, while the fixture↔workpiece buckle pair, being one attached identity at one location, is a
single flag.</p>
<h2 id="layout">Layout</h2>
<h3 id="control-tree-branch">Control Tree Branch</h3>
<ul>
<li>Workpiece Root — a summary panel, rendered inline by the dock's primary editor pane. It carries no
Object Management button: the workpiece has no standalone <code>.Workpiece</code> file surface here, and its
geometry, anchors, mesh and material are all edited through the child items below.
<ul>
<li>Raw Geometry Type Badge and Target Geometry Type Badge (<code>none</code> when the slot is empty)</li>
<li>Intro caption, and an empty-state caption while the project has no workpiece</li>
</ul>
</li>
<li><code>equipment/workpiece/raw-geometry</code> — &ldquo;Raw Geometry&rdquo;, a Geometry slot backing
<a class="xref" href="../../api/Hi.NcMech.Workpieces.Workpiece.html#Hi_NcMech_Workpieces_Workpiece_InitGeom">InitGeom</a>. The slot's own panel is the kind picker
(<a class="xref" href="../geom/geom-manage-control.html">Geometry Management Control</a>, selector only); the picked kind's
editor is the slot's child item. Kinds offered: <code>Box3d</code>, <code>Cylindroid</code>, <code>StlFile</code>,
<code>TransformationGeom</code>, <code>GeomCombination</code>, <code>CubeTreeFile</code>, plus None. <code>ExtendedCylinder</code> is an
<code>IMakeXmlSource</code> and was offered here until its start section — wired by a host, never serialized
— was found to reload a saved project degenerate; see
<a class="xref" href="../geom/extended-cylinder-panel.html">Extended Cylinder Panel</a> for what an older project holding
one still shows. The source
choice folds into that one picker — picking the voxel <code>CubeTreeFile</code>, which the picker shows as
<code>MeshedGeomFile</code>, <em>is</em> the meshed source (see
<a class="xref" href="../geom/meshed-geom-panel.html">Meshed Geometry Panel</a>).</li>
<li><code>equipment/workpiece/target-geometry</code> — &ldquo;Target Geometry&rdquo;, the same slot shape backing
<a class="xref" href="../../api/Hi.NcMech.Workpieces.Workpiece.html#Hi_NcMech_Workpieces_Workpiece_IdealGeom">IdealGeom</a>. Kinds offered: <code>Box3d</code>, <code>Cylindroid</code>, <code>StlFile</code>,
<code>TransformationGeom</code>, plus None. The target must satisfy <code>IGetStl</code>, so <code>CubeTreeFile</code> is not among
them.</li>
<li><code>equipment/workpiece/anchor</code> — &ldquo;Anchor&rdquo;, a Group stem whose info text states how the workpiece is
placed. Two Transformer slots hang from it, each a kind picker
(<a class="xref" href="../geom/transformer-panel.html">Transformer Manage Panel</a>) over the picked kind's child editor:
<ul>
<li><code>.../anchor/geom-to-fixture</code> — &ldquo;Geom To Fixture&rdquo;, which positions the workpiece geometry on the
fixture's workpiece buckle (see <a class="xref" href="fixture.html">Fixture</a>).</li>
<li><code>.../anchor/geom-to-program-zero</code> — &ldquo;Geom To Program Zero&rdquo;, which places the program zero, the
NC origin, relative to the workpiece geometry.</li>
</ul>
</li>
<li><code>equipment/workpiece/runtime</code> — labelled <strong>Mesh</strong> in the tree.
<ul>
<li>Initial Resolution Select (<a class="xref" href="../../api/Hi.NcMech.Workpieces.Workpiece.html#Hi_NcMech_Workpieces_Workpiece_InitResolution">InitResolution</a>, in mm), a
fifteen-step powers-of-two ladder:
<ul>
<li>0.0009765625</li>
<li>0.001953125</li>
<li>0.00390625</li>
<li>0.0078125</li>
<li>0.015625</li>
<li>0.03125</li>
<li>0.0625</li>
<li>0.125</li>
<li>0.25</li>
<li>0.5</li>
<li>1</li>
<li>2</li>
<li>4</li>
<li>8</li>
<li>16</li>
</ul>
</li>
<li>Hint caption: a smaller resolution means a finer voxel grid and a slower runtime simulation.</li>
<li>The engine's own ladder bottoms out at <code>0.001953125</code>, 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 <a class="xref" href="../../technique/simulation-performance/mesh-resolution.html">Mesh Resolution</a>.</li>
<li>The panel self-gates on the project having a workpiece.</li>
</ul>
</li>
<li><code>equipment/workpiece/material</code> — &ldquo;Material&rdquo;, a Group stem whose info text names the two
pre-prepared resources loaded by reference. Present whenever the project has a workpiece; nothing
on this branch gates it on a physics flag. Its two children share one panel, which reads its role
from the node's own path:
<ul>
<li><code>.../material/workpiece-material</code> — <code>.WorkpieceMaterial</code> files, seeded to the resource root's
<code>WorkpieceMaterial</code> folder.</li>
<li><code>.../material/cutting-parameter</code> — <code>.mp</code> files, seeded to the resource root's
<code>CuttingParameter</code> folder.</li>
<li>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
(<a class="xref" href="../../api/Hi.Common.INameNote.html#Hi_Common_INameNote_Name">Name</a>) and a readonly Note field
(<a class="xref" href="../../api/Hi.Common.INameNote.html#Hi_Common_INameNote_Note">Note</a>).</li>
</ul>
</li>
</ul>
<h3 id="page-frame">Page Frame</h3>
<ul>
<li>The General Setup page lays the tree dock, the content column and the equipment canvas out in
nested splitters with device-local widths; inside the dock, a height divider between the Control
Tree row and the primary editor row trades their heights. See
<a class="xref" href="index.html">General Setup Page</a>.</li>
<li>Canvas Column — one RenderingCanvas bound to the equipment-setup displayee
(<code>Disp/EquipmentSetupDisplayee.cs</code>): the merged fixture + workpiece setup scene, with optional
machine and tool solids.
<ul>
<li><a class="xref" href="../widget/renderingcanvas-tool-bar.html">RenderingCanvas Tool Bar</a></li>
<li>Display Options Menu — six groups; the workpiece's own entries are in <strong>bold</strong>:
<ul>
<li>Solid — Machine, Tool, <strong>Meshed Geometry</strong></li>
<li>Fixture Rendering Mode — Solid / Edge / Hide</li>
<li><strong>Raw Shape Rendering Mode</strong> — Solid / Edge / Hide</li>
<li><strong>Target Shape Rendering Mode</strong> — Solid / Edge / Hide</li>
<li>Anchors — Fixture Geometry Anchor, <strong>Workpiece Buckle</strong> (the one flag for the
fixture↔workpiece pair), Table Buckle, <strong>Workpiece Geometry Anchor</strong>,
<strong>Program-Zero Anchor</strong>, Controller Coordinate</li>
<li>Display Aids — Dimension Bar</li>
</ul>
</li>
</ul>
</li>
</ul>
<h2 id="default-resource">Default Resource</h2>
<p>The default resources of Workpiece Material and Cutting Parameter exist in <code>Resource</code> folder under application folder (Not project folder). Both clients seed their file pickers at the matching <code>Resource</code> sub folder:</p>
<ul>
<li>&ldquo;Resource/WorkpieceMaterial&rdquo;</li>
<li>&ldquo;Resource/CuttingParameter&rdquo;</li>
</ul>
<h2 id="behavior">Behavior</h2>
<ul>
<li><p>A geometry slot's edit re-commits the swap-in <strong>before</strong> 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.</p>
</li>
<li><p>Call <a class="xref" href="../../api/Hi.NcMech.Workpieces.WorkpieceService.html">WorkpieceService</a>.<a class="xref" href="../../api/Hi.NcMech.Workpieces.WorkpieceService.html#Hi_NcMech_Workpieces_WorkpieceService_ClearRawGeomCache">ClearRawGeomCache()</a> on Raw Shape set or changed.</p>
</li>
<li><p>Call <a class="xref" href="../../api/Hi.NcMech.Workpieces.WorkpieceService.html">WorkpieceService</a>.<a class="xref" href="../../api/Hi.NcMech.Workpieces.WorkpieceService.html#Hi_NcMech_Workpieces_WorkpieceService_ClearIdealGeomCache">ClearIdealGeomCache()</a> on Target Shape set or changed.</p>
</li>
<li><p>The branch reaches that service by posting the controller's cache-clear endpoints.</p>
</li>
<li><p>Anchor edits re-commit their transformer and deliberately do <strong>not</strong> clear the geometry cache, so
a placement change forces no <code>CubeTreeFile</code> re-mesh.</p>
</li>
<li><p>The Mesh item's Initial Resolution feeds the runtime voxel simulation, not the setup canvas, so no
cache chain runs after a change.</p>
</li>
<li><p>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.</p>
</li>
<li><p>Keep <a href="../conventions/gui-file-path-assignment.html#portability">Portability</a> of the Material properties.</p>
</li>
</ul>
<h2 id="source-code-path">Source Code Path</h2>
<p>See <a class="xref" href="../index.html">HiNC App Anatomy</a> for git repository links.</p>
<p>HiNC-2025-webservice (Quasar CLI SPA):</p>
<ul>
<li><code>wwwroot-src/src/components/controlTree/useControlTreeHost.ts</code> — builds the whole
<code>equipment/workpiece</code> branch: the root, the two geometry slots, the anchor group with its two
transformer slots, the Mesh item and the material group with its two resource items — including
each slot's re-commit-then-clear chain and the two allowed-kind whitelists.</li>
<li><code>wwwroot-src/src/components/controlTree/PrimarySlavePanel.vue</code> — renders the root inline: the Raw
and Target type badges plus the intro.</li>
<li><code>wwwroot-src/src/components/controlTree/itemTypes.ts</code> — the ItemType registry mapping the branch's
children to their panels.</li>
<li><code>wwwroot-src/src/components/controlTree/GeometrySlotPanel.vue</code> — the kind picker behind the raw
and target geometry slots.</li>
<li><code>wwwroot-src/src/components/controlTree/TransformerSlotPanel.vue</code> — the kind picker behind the two
anchor slots.</li>
<li><code>wwwroot-src/src/components/controlTree/WorkpieceRuntimePanel.vue</code> — the Mesh item's editor: the
Initial Resolution ladder and its hint.</li>
<li><code>wwwroot-src/src/components/controlTree/WorkpieceResourcePanel.vue</code> — the one panel both Material
children share, choosing its extension and resource subfolder from the node's role path.</li>
<li><code>wwwroot-src/src/components/widgets/FilePathInput.vue</code> — the file field those children use; its
project Browse entry is suppressed under <code>resourceOnly</code>, leaving the Resource-root pick.</li>
<li><code>wwwroot-src/src/components/mech/EquipmentSetupPanel.vue</code> — the canvas column and its Display
Options menu.</li>
<li><code>wwwroot-src/src/pages/GeneralSetupPage.vue</code> — the <code>/general-setup</code> page hosting the tree dock,
the content column and the canvas in nested splitters.</li>
<li><code>wwwroot-src/src/api/workpiece.ts</code> — typed client for <code>/api/Workpiece/*</code>: initialize, status, the
geometry re-commit and cache-clear calls, the two anchor transformer updates, <code>init-resolution</code>,
the two resource loads and the diff settings.</li>
<li><code>wwwroot-src/src/api/equipmentSetup.ts</code> — typed client for the shared canvas: the three
rendering-mode targets and the ten display flags, several of which are the workpiece's own
overlays.</li>
<li><code>Mech/WorkpieceController.cs</code> — the model REST surface at <code>/api/Workpiece</code>: geometry install and
cache clears, the anchor transformer updates, <code>init-resolution</code>, <code>workpiece-material/load</code>,
<code>cutting-parameter/load</code>, and the geometry-diff settings pair (visual radius and detection radius)
whose menu rides the <a class="xref" href="../execution/execution-extended-renderingcanvas-tool-bar.html">Execution Extended Tool Bar</a> rather
than this branch.</li>
<li><code>Mech/EquipmentSetupDisplayController.cs</code> — <code>/api/mech/equipment-setup-display</code>: binds the
equipment-setup displayee to a rendering connection, framing it isometrically at bind time, and
serves the rendering-mode and flag endpoints.</li>
<li><code>Disp/EquipmentSetupDisplayee.cs</code> — the merged fixture + workpiece setup scene the canvas draws.</li>
<li><code>Disp/EquipmentSetupDisplayeeConfig.cs</code> — its config: the fixture and workpiece display flags in
one place.</li>
</ul>

</article>

        <div class="contribution d-print-none">
        </div>

        <div class="next-article d-print-none border-top" id="nextArticle"></div>

      </div>

      <div class="affix">
        <nav id="affix"></nav>
      </div>
    </main>

    <div class="container-xxl search-results" id="search-results"></div>

    <footer class="border-top text-secondary">
      <div class="container-xxl">
        <div class="flex-fill">
          <span> Copyright © 2025 <a href='https://superhightech.com.tw'>Tech Coordinate</a>. All rights reserved. <a href='https://superhightech.com.tw'>超級高科技股份有限公司</a> © 2025 版權所有 </span>
        </div>
      </div>
    </footer>
  </body>
</html>