HiNC-2025-win-desktop-Deploy/App/wwwroot/HiAPI-docsite/manual/setup/program-zero-alignment.html

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
      <title>Program Zero Alignment | HiAPI-C# 2025 </title>
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <meta name="title" content="Program Zero Alignment | 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="">
          <h1 id="program-zero-alignment">Program Zero Alignment</h1>

<p><strong>Program zero</strong> (<code>ProgramZeroAnchor</code>) is the point an NC program treats as <code>X0 Y0 Z0</code>. It is related to the machine's work-coordinate offset (G54/G55/...): when the machine coordinate equals the work offset, the spindle sits at program zero.</p>
<p>Setting up a simulation requires relating program zero to the work offset. <strong>Which way you align depends on the scenario.</strong></p>
<h2 id="two-alignment-directions">Two Alignment Directions</h2>
<h3 id="nc-file-scenario-planning--align-g54-to-program-zero">NC-file scenario (planning) — align G54 to program zero</h3>
<p>When you drive the simulation from an NC file for <strong>planning</strong>, you usually keep the workpiece and fixture wherever they are convenient and set the work offset to match. The G54 value may not be obtained yet, and the layout does <strong>not</strong> need to reflect the real machine.</p>
<ul>
<li>Keep the workpiece/fixture placement as-is.</li>
<li>Read the machine coordinate at program zero with <a class="xref" href="../../api/Hi.Machining.MachiningEquipmentUtils.MachiningEquipmentUtil.html#Hi_Machining_MachiningEquipmentUtils_MachiningEquipmentUtil_GetMachinePositionAtProgramZero_">GetMachinePositionAtProgramZero</a> and store it into the ISO coordinate table (<code>IsoCoordinateTable.SetCoordinateOffset(&quot;G54&quot;, ...)</code>).</li>
</ul>
<h3 id="csv--real-time--online-mc-scenario-high-fidelity--align-program-zero-to-g54">CSV / real-time / online-MC scenario (high-fidelity) — align program zero to G54</h3>
<p>When you drive the simulation from a <strong>controller CSV log</strong> (see <a class="xref" href="../../api/Hi.MachiningProcs.SessionShell.html#Hi_MachiningProcs_SessionShell_PlayCsvFile_">PlayCsvFile</a>) or a real-time / online machine coordinate feed, the data is in <strong>absolute machine coordinates</strong>. To reproduce the real cut faithfully (高還原度), the workpiece + fixture must sit at their <strong>real positions</strong> so that collisions, overcut, and engagement match reality.</p>
<pre><code class="lang-csharp">// Places workpiece + fixture so ProgramZeroAnchor coincides with the
// world position the spindle reaches when the machine coordinate equals G54.
AlignWorkpieceProgramZeroToIso(&quot;G54&quot;);
</code></pre>
<p>The same action is available in the web UI on the Controller page's ISO Coordinate Table (<code>Align P0</code> per row, with a one-shot <code>Revert Align</code>).</p>
<p><code>AlignWorkpieceProgramZeroToIso</code> mutates only <code>Fixture.GeomToTableTransformer</code>. The three buckle transformers must already be placed per the rule below.</p>
<h2 id="buckle-general-rule">Buckle General Rule</h2>
<p>The workpiece/fixture assembly is built from buckle anchors (see <a href="anchor.html">Component Assembly and Anchors</a>). A typical block-on-plate setup places them at the geometry bounding-box centers:</p>
<table>
<thead>
<tr>
<th>Transformer</th>
<th>Position</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>Workpiece.WorkpieceGeomToFixtureBuckleTransformer</code></td>
<td>bottom center of the workpiece geom</td>
</tr>
<tr>
<td><code>Workpiece.WorkpieceGeomToProgramZeroTransformer</code></td>
<td>top center of the workpiece geom (or any chosen top tip)</td>
</tr>
<tr>
<td><code>Fixture.GeomToWorkpieceTransformer</code></td>
<td>top center of the fixture geom</td>
</tr>
</tbody>
</table>
<p><code>AlignWorkpieceProgramZeroToIso</code> then derives the final <code>Fixture.GeomToTableTransformer</code> from the live assembly topology (anchor-to-anchor vectors), so it works for any chain — it does not assume the buckles are at bounding-box centers.</p>
<h2 id="verifying-the-setup">Verifying the Setup</h2>
<p>A wrong setup (incorrect work offset or workpiece position) shows up as <strong>overcut</strong>, <strong>collision</strong>, or <strong>nocut</strong>. These are observable <strong>early</strong> — typically within the first ~100 NC lines or ~1 minute — so verify with a quick, cheap pass before a full run:</p>
<ol>
<li>Set a coarse <a class="xref" href="../../api/Hi.MachiningProcs.SessionShell.html#Hi_MachiningProcs_SessionShell_MachiningResolution_">MachiningResolution</a> ≈ <strong>1/8 of the cutter diameter</strong> for fast feedback.</li>
<li>Run and watch the <strong>opening Z plunge (下刀)</strong>. This is where overcut/collision most often appears when the work offset or workpiece Z is wrong.</li>
</ol>
<div class="TIP">
<h5>Tip</h5>
<p>If the tool plunges far deeper than the programmed depth and the holder crashes into the workpiece (a visible gouge on the rendered stock), the work offset Z is almost certainly wrong — the workpiece is modeled higher (or lower) than its real position.</p>
</div>
<div class="NOTE">
<h5>Note</h5>
<p>Rare false positive: a roughing cut with a <strong>spiral entrance on tough material</strong> can legitimately exceed the modeled cutting conditions yet still be a <em>correct</em> setup. This is uncommon — in most cases early overcut/collision/nocut means the setup is wrong.</p>
</div>
<h2 id="high-fidelity-caution-work-offset-must-reflect-the-real-machine">High-Fidelity Caution: Work Offset Must Reflect the Real Machine</h2>
<p>In the CSV / online-MC scenario, the work offset (G54/G55/...) you align to must be the <strong>actual offset used on the machine</strong>, not a planned/nominal value. Operators frequently re-zero between setups (manual tool changes, re-cut stock), so a planned G54 can differ from the real one — by an amount you cannot assume in advance.</p>
<p>When driving from a controller log, <strong>derive the offset from the log's own machine coordinates</strong> rather than trusting a planned value: invariants that survive operator edits — a known cutting depth, a feature span — mapped onto the recorded machine coordinates, recover the real offset on those axes. (Positions the operator may have shifted are not recoverable this way.) A work-offset Z that is wrong places the workpiece away from its true height, so the tool over- or under-plunges; if too high, the holder crashes the stock at the opening plunge — exactly the failure the rough-resolution check above catches.</p>
<h2 id="see-also">See Also</h2>
<ul>
<li><a href="anchor.html">Component Assembly and Anchors</a> — buckle anchors (<code>WorkpieceBuckle</code>, <code>TableBuckle</code>, <code>SpindleBuckle</code>)</li>
<li><a class="xref" href="../../workflows/force-training.html">Workflow: Milling Force Parameter Training</a> — milling force training, which depends on a correct setup</li>
<li><a class="xref" href="../../workflows/basic-simulation.html">Workflow: Basic Machining Simulation</a> — driving simulation from NC or CSV</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>