HiNC-2025-win-desktop-Deploy/App/wwwroot/HiAPI-docsite/workflows/project-construction.html

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
      <title>Workflow: Constructing a Project through the Web API | HiAPI-C# 2025 </title>
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <meta name="title" content="Workflow: Constructing a Project through the Web API | 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="Workflow-ProjectConstruction">
          <h1 id="workflow-constructing-a-project-through-the-web-api">Workflow: Constructing a Project through the Web API</h1>

<p><a href="basic-simulation.html">Basic Simulation</a> describes <em>what</em> a project contains. This page describes
<em>how to build one so that it is actually finished</em> — the ordering that avoids rework, how to shape
the mission, and the acceptance test that tells you the project is complete rather than merely
populated.</p>
<p>It is written for whoever assembles a <code>.hincproj</code> from a customer's deliverables — a person driving
the browser UI, or an agent driving the same operations over the HTTP API.</p>
<pre><code class="lang-mermaid">flowchart TD
    New[&quot;1 · New project&lt;br&gt;(self-contained root)&quot;]
    Assets[&quot;2 · Place assets&lt;br&gt;NC, STL, resource files&quot;]
    Equip[&quot;3 · Equipment&lt;br&gt;chain, spindle&quot;]
    Job[&quot;4 · Job&lt;br&gt;stock, ideal geom, material&quot;]
    Ctrl[&quot;5 · Controller&lt;br&gt;brand + its own tables&quot;]
    Tools[&quot;6 · Tool house&quot;]
    Mission[&quot;7 · Mission&lt;br&gt;grouped, per-group resolution&quot;]
    Replay[&quot;8 · Replay and read&lt;br&gt;every message&quot;]
    Cross[&quot;9 · Numeric cross-checks&quot;]
    Assume[&quot;10 · Record every assumption&quot;]

    New --&gt; Assets --&gt; Equip --&gt; Job --&gt; Ctrl --&gt; Tools --&gt; Mission --&gt; Replay --&gt; Cross --&gt; Assume
    Replay --&gt;|any warning| Ctrl
</code></pre>
<h2 id="build-through-the-api-not-by-editing-the-xml">Build through the API, not by editing the XML</h2>
<p>Create and modify projects through the service's HTTP API. It is the same code path the UI uses, so
a project built that way is on the supported create/load/save route. Hand-authoring the <code>.hincproj</code>
XML is a fallback for fields the API cannot yet reach — and when you hit one, the better fix is to
add the endpoint.</p>
<h2 id="1-one-self-contained-root">1. One self-contained root</h2>
<p>The <code>.hincproj</code> and <strong>every</strong> asset it references live under one folder — the project's own
directory — and every reference is relative to it with <strong>no <code>../</code></strong>.</p>
<pre><code>&lt;project&gt;/
├── &lt;name&gt;.hincproj
├── NC/                     the programs, copied in
├── Geom/                   workpiece / fixture STL
├── MachineTool/            the kinematic chain
├── SpindleCapability/
├── WorkpieceMaterial/
├── CuttingParameter/
├── CutterMaterial/
└── README.md               what was assumed, and why
</code></pre>
<p>Two things do not move themselves, so bring them in by hand before you wire anything:</p>
<ul>
<li><strong>NC files.</strong> A program-file command stores a plain relative path; nothing copies the file.</li>
<li><strong>Machine-tool side files.</strong> A chain that externalises its mechanism references the side file and
its STL bodies by bare name, relative to the <code>.mt</code>'s own folder — keep the whole folder together.</li>
</ul>
<p>Resource files (chain, spindle, cutting parameters, workpiece material, cutter material) are
<em>pre-prepared data loaded by reference</em>. Stage a copy inside the project and load it from there, so
the saved reference points inside the project rather than at a shared library.</p>
<h2 id="2-order-the-build-to-avoid-rework">2. Order the build to avoid rework</h2>
<p>Later steps read earlier ones, so this order costs the least:</p>
<ol>
<li><strong>New project</strong> at its final path.</li>
<li><strong>Machine tool</strong>, then <strong>spindle capability</strong>.</li>
<li><strong>Workpiece</strong>: stock geometry, ideal (target) geometry, resolution, the geometry-to-program-zero
and geometry-to-fixture transforms, then material and cutting parameters.</li>
<li><strong>Controller</strong>: brand first — switching brand later resets brand-specific tables — then the
controller's own tables (§4).</li>
<li><strong>Tool house</strong>: per tool, shaper profile → fluting → exposed height → holder → upper beam →
cutter material. Then refresh the offset tables from the tool house.</li>
<li><strong>Program zero</strong>: with the workpiece placed and the chain loaded, derive the work offset from the
model rather than typing a number. See <a href="../manual/setup/program-zero-alignment.html">Program Zero Alignment</a>.</li>
<li><strong>Mission</strong> (§3).</li>
<li><strong>Save</strong>, then <strong>load the saved file back</strong> and re-check. A project that cannot be reloaded
cleanly is not built.</li>
</ol>
<div class="IMPORTANT">
<h5>Important</h5>
<p>Verify the axis set after loading a machine tool. A kinematic chain binds each axis transformer by
<strong>branch name</strong> (<code>X</code>/<code>Y</code>/<code>Z</code>/<code>A</code>/<code>B</code>/<code>C</code>); a branch left at its authoring default name yields no
transformer, and that axis silently does not exist. The trap is that the controller preset already
seeds the linear axes, so a chain missing its Z branch still <em>reports</em> a Z — only a missing rotary
gives it away. Compare the reported axes against the mechanism you expect.</p>
</div>
<h2 id="3-shape-the-mission-around-the-process-not-the-file-list">3. Shape the mission around the process, not the file list</h2>
<p>A flat list of program files runs correctly but reads badly and gives you one knob for the whole
job. Group the programs into one <strong>List command per operation family</strong>, in the order the process
actually runs:</p>
<pre><code>Machining Motion Resolution
Collision Detection      [Off]
Pause on Failure         [Off]
Physics                  [On]
▸ 1 · Drilling                    Machining Resolution 0.5 mm
      centre drill, drill
▸ 2 · Outside roughing            Machining Resolution 0.5 mm
      roughing 1 … 5
▸ 3 · Outside finishing           Machining Resolution 0.2 mm
      finishing 1 … 7
▸ 4 · Pocket roughing             Machining Resolution 0.5 mm
▸ 5 · Pocket finishing            Machining Resolution 0.2 mm
▸ 6 · Rest milling                Machining Resolution 0.2 mm
▸ 7 · Rib machining               Machining Resolution 0.2 mm
▸ 8 · Deburring                   Machining Resolution 0.2 mm
Post-Execution                    geometry diff on
</code></pre>
<p>Why this shape:</p>
<ul>
<li><strong>Grouping must not reorder.</strong> The stock evolves from one operation to the next, so the sequence
is load-bearing. Group <em>adjacent</em> operations; never sort the list into tidy families if that moves
an operation past another one.</li>
<li><strong>Each group carries its own machining resolution.</strong> Roughing is about force, not surface, so a
coarse resolution is enough and runs quickly. Finishing, rib and deburring passes leave the final
surface with small and ball cutters and deserve a finer one. Setting the resolution mid-mission
only changes the value the act runner cuts with — the workpiece is not rebuilt, and the geometry
container is adaptive — so alternating coarse and fine between groups is safe.</li>
<li><strong>A group is a switch.</strong> Disabling one List skips a whole phase, which is how you re-run
just the finishing passes without deleting anything.</li>
<li><strong>Budget the fine groups.</strong> Machining resolution drives the cost of subtracting material, not the
number of simulation steps — the step count follows the <em>motion</em> resolution and does not change.
On one 33-operation job, refining the finishing groups from 0.5 mm to 0.2 mm left the step count
identical and multiplied wall-clock time by about 2.8. Decide the finish resolution with that
trade-off in view, and say what it costs in the project's README so nobody is surprised.</li>
<li><strong>Setup commands are granular.</strong> Machining resolution, motion resolution, collision detection,
pause-on-failure and physics are separate commands, so each can sit exactly where it should take
effect — global ones at the top, per-phase ones inside a group.</li>
</ul>
<div class="TIP">
<h5>Tip</h5>
<p>A project that loads an ideal (target) geometry and never compares against it is unfinished. Turn
on the geometry diff in the Post-Execution command so a full replay ends by measuring the machined
stock against the finished part.</p>
</div>
<h2 id="4-fill-the-controllers-own-tables">4. Fill the controller's own tables</h2>
<p>The tool house describes the <em>physical</em> tool. The controller has its own record of the same tool,
and the NC program reads the controller's copy. Both must exist.</p>
<p>For a Siemens-style controller that is two tables:</p>
<table>
<thead>
<tr>
<th>Table</th>
<th>Holds</th>
<th>If empty</th>
</tr>
</thead>
<tbody>
<tr>
<td>Tool name → tool number</td>
<td>the names a <code>T=&quot;…&quot;</code> call uses</td>
<td>the tool never mounts, and the program produces <strong>no machining steps at all</strong></td>
</tr>
<tr>
<td>Tool edge offsets</td>
<td>per <code>(tool, edge)</code>: length along the tool axis, radius</td>
<td>every edge call falls back to the generic offset table and logs a warning</td>
</tr>
</tbody>
</table>
<p>Take the values from the tool house and <strong>assert they match before writing</strong>. When the warning
disappears and the cut does not move at all, that is the proof the rows carry the right numbers —
if the geometry shifts, one of the two tables was wrong.</p>
<div class="NOTE">
<h5>Note</h5>
<p>Not every controller parameter has a consumer. Some, such as the maximum spindle speed, are
recorded machine data that nothing in the pipeline reads today. Filling them is good hygiene, but
do not report it as fixing a defect, and remember that copying a <em>guessed</em> value (an assumed
spindle, say) into a second place means both must move when the real datum arrives.</p>
</div>
<h2 id="5-the-finish-line-is-a-clean-replay-not-a-filled-form">5. The finish line is a clean replay, not a filled form</h2>
<p><strong>Replay the whole mission and inventory the messages by id.</strong> Every warning is an item on the
to-do list. Resist writing one up as an acceptable fallback: a fallback firing means the project
never supplied the data the fallback exists to cover.</p>
<p>Read messages at a low severity so nothing hides. The severities are
<code>Message</code>, <code>Success</code>, <code>Progress</code>, <code>Warning</code>, <code>Error</code> — note there is no <code>Info</code>, and an unrecognised
name is rejected in the response body rather than by an HTTP error, which reads exactly like
&ldquo;no messages&rdquo;.</p>
<p>Stop when only <em>declared informational</em> messages remain — the ones that state a known, deliberate
limitation. Typical survivors:</p>
<ul>
<li>one per NC file, reporting the line count;</li>
<li>machine M-codes that the runner recognises and consumes but does not model (OEM auxiliary
functions such as coolant valves), which are announced rather than silently ignored.</li>
</ul>
<p>Anything else is work.</p>
<h2 id="6-two-numeric-cross-checks--and-what-they-do-not-prove">6. Two numeric cross-checks — and what they do not prove</h2>
<p>Messages catch what the runner noticed. These two catch datum errors that produce no message at all.</p>
<p><strong>Depth of cut against the programmed layer depth.</strong> On a roughing pass whose step-down you can read
from the NC, the peak cutting depth must equal it. This pins the Z datum: if program zero is wrong,
the tool cuts a different amount and the peak does not land on the programmed number.</p>
<p><strong>Cycle time against the post-processor's own estimate.</strong> Many post-processors write a per-operation
machining time into the program as a comment. Sum them and compare with the simulated time.</p>
<div class="WARNING">
<h5>Warning</h5>
<p>Scope the cycle-time check honestly. It confirms that <strong>feed rates and path length</strong> are consumed
correctly. It is <strong>not</strong> a comparison against the real machine, because both sides ignore the same
things: there is no acceleration model (time is path length over feed rate, with no ramps — which
costs the most on finishing passes made of thousands of short segments), tool-change time defaults
to zero, and the tool-change and home positions come from the chain rather than from machine data.</p>
<p>For the same reason, a customer's &ldquo;total machining time&rdquo; running well above the sum of the
per-operation comments is usually <strong>not</strong> a contradiction — the comments are cutting time, the
total is wall clock including tool changes and inter-operation moves. Two different quantities.</p>
</div>
<h2 id="7-record-every-assumption">7. Record every assumption</h2>
<p>Real deliverables are incomplete. Build with sensible values, and write each one down in a
<code>README.md</code> beside the <code>.hincproj</code> — what was assumed, what it was inferred from, and what changes
when the real value arrives. Recurring items: work offsets, blank size and material, tool helix
angle, stick-out, holder dimensions, the spindle's power–torque curve, fixture geometry, and the
cycle-time inputs above.</p>
<p>Cross-reference: <a class="xref" href="project-data-checklist.html">Project Data Checklist</a> is the list to
hand the customer <em>before</em> building; this section is what you hand back <em>after</em>.</p>

</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>