HiNC-2025-win-desktop-Deploy/App/wwwroot/HiAPI-docsite/manual/utilities/mech-builder.html

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
      <title>Mechanism Builder | HiAPI-C# 2025 </title>
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <meta name="title" content="Mechanism Builder | 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="mechanism-builder">Mechanism Builder</h1>

<p>Building a mechanism: anchors joined by branches, each branch carrying the transform between its two
ends, and each anchor optionally carrying a shape. It is where a virtual machine tool's topology is
assembled and then written out as a file a project can load.</p>
<h2 id="where-it-is">Where it is</h2>
<p>Its own page, reached from the menu bar's <strong>Page → Mechanism Builder</strong>, at <code>/util/mech-builder</code>.
Nothing on it belongs to a project, so it opens and edits with <strong>no project loaded</strong>, as the File
Explorer beside it does. The mechanism is held by the server rather than by the page — more than the
page keep-alive <a href="../basics/the-app-window.html">The Application Window</a> grants every screen,
because there is one mechanism per server rather than one per browser: a second person editing at the
same time is editing the same one.</p>
<p>Three fixed, equal-width columns, none of them draggable: the <strong>File</strong> menu, the <strong>Add Anchor</strong>
button and the graph of anchors and branches on the left, where clicking a node, or the label on an
edge, selects it; the editor for whatever is selected in the middle, headed <strong>Anchor</strong> or <strong>Branch</strong>;
and <strong>Display</strong>, the 3D view of the mechanism, on the right, which redraws as the mechanism changes.</p>
<p><img src="mech-builder-img/anchor-selected.en.png" alt="The Mechanism Builder with a five-axis machine tool loaded: the graph of ten anchors on the left with the X anchor filled green, the Anchor editor in the middle showing the Identity and Geometry cards, and the assembled machine drawn in the Display column on the right"></p>
<p><em>At <code>/util/mech-builder</code>, with an anchor picked in the graph. The open file's path sits under the
File menu; the header of the middle column carries <strong>Extend</strong> and the delete button; and the
Geometry card here holds a <code>TransformationGeom</code>, so its own inner geometry — an STL file — and its
own inner transformer are edited underneath it.</em></p>
<p>What the anchors and branches must be <em>called</em> — the motion-axis and end-anchor keywords, which way
branches must point, and how to take the numbers off a CAD assembly — is
<a href="../setup/machine-tool.html">Building Virtual Machine Tools</a>; this page is only how to drive the
editor.</p>
<h2 id="starting-loading-and-saving">Starting, loading and saving</h2>
<table>
<thead>
<tr>
<th>File menu entry</th>
<th>What it does</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>New</strong></td>
<td>Discards the mechanism on screen and starts an empty one holding a single root anchor.</td>
</tr>
<tr>
<td><strong>Load…</strong></td>
<td>Opens the server file picker — <a href="file-explorer.html">File Explorer</a>'s browser in picker mode, over the roots that page lists — filtered to <code>*.GeneralMechanism</code>, <code>*.general-mech</code> and <code>*.xml</code> — the first is what this page's own Save As writes and what the shipped mechanism is named; the second is the older spelling hand-authored files still carry, and it loads the same way. The server reads the file where it sits and remembers its folder.</td>
</tr>
<tr>
<td><strong>ReLoad</strong></td>
<td>Re-reads the file you last loaded, dropping the edits made since. Disabled until a file has been loaded.</td>
</tr>
<tr>
<td><strong>Save As General Mechanism</strong></td>
<td>Writes the mechanism as a <code>.GeneralMechanism</code> XML where you pick, and re-points <strong>ReLoad</strong> at it.</td>
</tr>
<tr>
<td><strong>Save As Machine Tool</strong></td>
<td>Wraps the same mechanism as a machine tool and writes a <code>.MachineTool</code> XML. <strong>ReLoad</strong> goes on pointing at the mechanism file, because a machine tool is a different file type.</td>
</tr>
</tbody>
</table>
<p>There is no plain <strong>Save</strong> that overwrites what you opened: both writes are Save As and both ask
where the result goes. Under the File menu the left column shows the open file's relative path, or
<code>(unsaved)</code> while the mechanism has no file yet — after <strong>New</strong>, until the first Save As.</p>
<div class="NOTE">
<h5>Note</h5>
<p><strong>Save As Machine Tool does not check the end-anchor keywords.</strong> The write succeeds and reports
the file saved whatever the anchors are called, including a mechanism whose tool-end and
worktable-end anchors are mis-cased or missing altogether. A file written here asks for its
collision pairs to be generated, and generating them needs those two anchors by their exact
names, so such a file is refused the first time anything reads it — on the General Setup page's
<strong>Machine Tool</strong> branch, not here, and with a message naming the keyword it wanted. Get the names
right before saving; they are in
<a href="../setup/machine-tool.html">Building Virtual Machine Tools</a>.</p>
</div>
<p>A <code>.MachineTool</code> written here is not a project's chain until it is loaded onto one, on the General
Setup page's <strong>Machine Tool</strong> branch — see
<a href="../setup/machine-tool.html">Building Virtual Machine Tools</a>.</p>
<h2 id="growing-the-chain">Growing the chain</h2>
<ol>
<li>Click an anchor in the graph to select it. The root carries a <strong>Root</strong> badge and is the one
anchor that cannot be deleted.</li>
<li>Press <strong>Extend</strong> in its header. That creates a new anchor <em>and</em> the branch reaching it from the
selected one, then selects the new anchor — the normal way a chain grows.</li>
<li><strong>Add Anchor</strong>, beside the File menu, is for a loose anchor instead: it creates one connected to
nothing, which you join up afterwards with the <strong>Add Branch</strong> picker on an anchor's Identity
card. That picker offers every anchor except the selected one and those already joined to it in
either direction.</li>
<li>Name each anchor as you make it. New ones arrive as <code>NewAnchor-001</code>, <code>NewAnchor-002</code> and so on,
so type the real name into <strong>Name</strong> on the Identity card; it commits a moment after you stop
typing. A branch carries a <strong>Name</strong> field of its own in the same place.</li>
</ol>
<p>Deleting an anchor or a branch is a double-click on the red delete button in its header.</p>
<h2 id="geometry-on-an-anchor">Geometry on an anchor</h2>
<p>Geometry is optional and belongs to one anchor at a time. Select the anchor and tick <strong>Geometry</strong> on
the Geometry card; a badge beside the checkbox names the shape currently held, and un-ticking the
box removes it. Five kinds can be built here — <code>Box3d</code>, <code>Cylindroid</code>, <code>StlFile</code>, <code>TransformationGeom</code>
and <code>GeomCombination</code> — and <code>TransformationGeom</code> carries its own inner geometry and inner
transformer, so a shape can be offset from the anchor it hangs on. <strong>Display color</strong>, above the
shape editor, is written into the mechanism file itself, so everyone who opens that file sees the
same colour; until you set one the badge reads <strong>auto</strong> and the view uses a stable colour of its
own, which the reset button beside the swatch returns to.</p>
<h2 id="the-branch-transformer">The branch transformer</h2>
<p>Click the label on a branch's edge — the transformer type, or the branch's name and type — to select
the branch. Its Identity card names the two anchors it joins in order, the one the branch starts from
and then the one it reaches, with an arrow between them; that order is the branch's direction. Below
that, the <strong>Transformer</strong> card picks between seven kinds, in the order the picker lists them:
<code>Static Translation</code>, <code>Static Rotation</code>, <code>Static Freeform</code>, <code>Dynamic Translation</code>,
<code>Dynamic Rotation</code>, <code>General Transform</code> and <code>No Transform</code> — which is what every new branch starts
on. Pick a kind and its fields appear underneath; the choice takes effect at once, so the right-hand
view shows the joint as you edit it. The two dynamic kinds are the ones whose value varies at
runtime — a machine's moving axes are branches carrying those.</p>
<p><img src="mech-builder-img/branch-transformer.en.png" alt="The same mechanism with a branch picked instead: the graph edge is stroked green, the Identity card names the two anchors it joins with an arrow between them, and the Transformer card reads Dynamic Rotation over a rotation axis, an angle and a pivot"></p>
<p><em>At <code>/util/mech-builder</code>, with a branch picked. A <code>Dynamic Rotation</code> carries the axis it turns
about and the pivot it turns around; the angle is the value a run varies, so the number shown here
is the resting one. The sentence under the fields names the same three parts.</em></p>
<h2 id="see-also">See Also</h2>
<ul>
<li><a href="file-explorer.html">File Explorer</a> — the server-side browser behind this page's Load and Save As dialogs, and the roots they offer</li>
<li><a href="index.html">Utilities</a> — the other screens the Page menu lists beside this one</li>
<li><a href="../setup/machine-tool.html">Building Virtual Machine Tools</a> — the naming keywords, branch direction and CAD practice a machine chain built here must follow, and where the saved file is attached to a project</li>
<li><a class="xref" href="../../anatomy/util/mech-builder.html">Mechanism Builder Page</a> — the component behind this page: its cards, its file IO and how edits reach the canvas</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>