HiNC-2025-win-desktop-Deploy/App/wwwroot/HiAPI-docsite/technique/api-foundations/getting-started.html

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
      <title>Getting Started with HiAPI | HiAPI-C# 2025 </title>
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <meta name="title" content="Getting Started with HiAPI | 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="Technique-GettingStarted">
          <h1 id="getting-started-with-hiapi">Getting Started with HiAPI</h1>

<p>What a first HiAPI application needs: where the packages come from, what the program has to
initialise, and the shape every HiNC program follows once it runs.</p>
<h2 id="installation">Installation</h2>
<ol>
<li><p>Create a dotnet project. A console or service project targets <strong>net10.0</strong>. A project that also
takes one of the Windows UI packages targets <strong>net10.0-windows</strong> — that is what <code>Hi.WinForm</code> and
<code>Hi.WpfPlus</code> are built for, and a plain <code>net10.0</code> project cannot reference them. An earlier
target framework cannot reference any of the packages.</p>
</li>
<li><p>Register the HiAPI package source on the machine.</p>
<p>The feed requires authentication, and the same account that gives you the sample repositories
gives you the packages. One command registers the source <em>and</em> its credentials, which is the
whole of what a restore needs:</p>
<pre><code>dotnet nuget add source https://superhightech-gitea.webredirect.org/api/packages/HiAPI/nuget/index.json --name HiAPI --username &lt;your-account&gt; --password &lt;your-token&gt; --store-password-in-clear-text
</code></pre>
<p>Run it once per machine. Customers served by the mainland mirror register the feed address
issued with their account in place of the URL above; nothing else changes.</p>
<p><strong>Prefer this to a project-local <code>nuget.config</code>, and never declare the feed in both places.</strong>
NuGet resolves credentials by source <em>name</em>, and the match is case-sensitive, so a file that
declares the same URL under a name the machine holds no credentials for adds a <em>second</em>,
credential-less source. NuGet asks every source about every package, and one <code>401</code> fails the
whole restore instead of falling through — so the packages it then reports as missing are the
public <code>nuget.org</code> ones, and the cause is nowhere near the symptom. A credential-free file
cannot stand in for the command either: the feed rejects anonymous requests, so it carries a
fresh clone no further than having no source at all.</p>
<p>Where a per-machine source is genuinely unavailable — an ephemeral build agent, say — a
<code>nuget.config</code> beside the project file does the job, provided it is the only declaration of
that URL and carries its own credentials under exactly the key it gave the source:</p>
<pre><code class="lang-xml">&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&gt;
&lt;configuration&gt;
  &lt;packageSources&gt;
    &lt;add key=&quot;HiAPI&quot; value=&quot;https://superhightech-gitea.webredirect.org/api/packages/HiAPI/nuget/index.json&quot; /&gt;
    &lt;add key=&quot;nuget.org&quot; value=&quot;https://api.nuget.org/v3/index.json&quot; protocolVersion=&quot;3&quot; /&gt;
  &lt;/packageSources&gt;
  &lt;packageSourceCredentials&gt;
    &lt;HiAPI&gt;
      &lt;add key=&quot;Username&quot; value=&quot;xxxxxx&quot; /&gt;
      &lt;add key=&quot;ClearTextPassword&quot; value=&quot;xxxxxx&quot; /&gt;
    &lt;/HiAPI&gt;
  &lt;/packageSourceCredentials&gt;
&lt;/configuration&gt;
</code></pre>
<p>That file holds a password in clear text: keep it out of version control.</p>
</li>
<li><p>In the dotnet project file, add the package reference.</p>
<pre><code class="lang-xml">&lt;ItemGroup&gt;
  &lt;PackageReference Include=&quot;HiNc&quot; Version=&quot;3.2.*&quot; /&gt;
  &lt;!--optional; needs a net10.0-windows project--&gt;
  &lt;PackageReference Include=&quot;Hi.WpfPlus&quot; Version=&quot;3.2.*&quot; /&gt; 
&lt;/ItemGroup&gt;
</code></pre>
</li>
<li><p>In the program file, setting the HiNC application initialization and finalization.</p>
<pre><code class="lang-csharp" name="SampleCode">using Hi.HiNcKits;
using Microsoft.Extensions.Logging;
using System;

namespace Sample
{
    /// &lt;summary&gt;
    /// A sample class demonstrating initialization and usage of the HiAPI framework.
    /// Shows the basic setup of display engine, MongoDB server, licensing, and other core functionality.
    /// &lt;/summary&gt;
    /// &lt;remarks&gt;
    /// This example serves as an entry point for those getting started with HiAPI.
    /// It demonstrates proper initialization and teardown of key components.
    /// ### Source Code
    /// [!code-csharp[SampleCode](~/../Hi.Sample/HelloHiAPI.cs)]
    /// &lt;/remarks&gt;
    public static class HelloHiAPI
    {
        static int Main(string[] args)
        {
            Console.WriteLine(&quot;HiAPI starting.&quot;);
            using var loggerFactory = Microsoft.Extensions.Logging.LoggerFactory.Create(b =&gt; b.AddConsole());
            LocalApp.AppBegin(loggerFactory.CreateLogger(&quot;Hi.Sample&quot;));

            Console.WriteLine(&quot;Hello World! HiAPI.&quot;);

            LocalApp.AppEnd();
            Console.WriteLine(&quot;HiAPI exited.&quot;);

            return 0;
        }
    }
}
</code></pre></li>
</ol>
<h2 id="the-shape-of-a-hinc-program">The Shape of a HiNC Program</h2>
<p>Every HiNC program, whether it is the shipped application or twenty lines in a console project,
runs the same five steps. <code>DemoBuildMachiningProject</code> in the Hi.Sample repository is the complete
worked example.</p>
<pre><code class="lang-mermaid">graph TD
    A[&quot;Create MachiningProject&quot;] --&gt; B[&quot;Setting Environment&quot;]
    B --&gt; C[&quot;Setting Project Tasks&quot;]
    C --&gt; D[&quot;Run Tasks&quot;]
    D --&gt; E[&quot;View Analysis Results&quot;]
</code></pre>
<h3 id="1-create-">1. Create <a class="xref" href="../../api/Hi.MachiningProcs.MachiningProject.html">MachiningProject</a></h3>
<p>Creating a machining project is the first step in the HiNC workflow, accomplished by initializing a <a class="xref" href="../../api/Hi.MachiningProcs.MachiningProject.html">MachiningProject</a> object.</p>
<h3 id="2-setting-environment-in-">2. Setting Environment In <a class="xref" href="../../api/Hi.MachiningProcs.MachiningProject.html">MachiningProject</a></h3>
<p>The equipment has two faces. <a class="xref" href="../../api/Hi.Machining.MachiningEquipmentUtils.SetupEquipment.html">SetupEquipment</a> is the
authored one — the only face a project file persists, and the one every setting below is written to.
<a class="xref" href="../../api/Hi.Machining.MachiningEquipmentUtils.MachiningEquipment.html">MachiningEquipment</a> is the runtime face the runner,
physics, collision and execution display read; it is rebuilt from the authored face at project
assignment and at session boundaries, so a value written onto it is discarded rather than saved.</p>
<ul>
<li>Set <a class="xref" href="../../api/Hi.Machining.MachiningEquipmentUtils.SetupEquipment.html">SetupEquipment</a>:
<ul>
<li>Usually one-time settings:
<ul>
<li><a class="xref" href="../../api/Hi.Machining.MachiningEquipmentUtils.SetupEquipment.html#Hi_Machining_MachiningEquipmentUtils_SetupEquipment_MachiningChain">MachiningChain</a> - Configure the complete machine tool including geometry, kinematic chain, and coordinate transformations</li>
<li><a class="xref" href="../../api/Hi.Machining.MachiningEquipmentUtils.SetupEquipment.html#Hi_Machining_MachiningEquipmentUtils_SetupEquipment_SpindleCapability">SpindleCapability</a> - Configure <a class="xref" href="../../api/Hi.Milling.SpindleCapability.html">SpindleCapability</a></li>
<li><a class="xref" href="../../api/Hi.Machining.MachiningEquipmentUtils.SetupEquipment.html#Hi_Machining_MachiningEquipmentUtils_SetupEquipment_CoolantHeatCondition">CoolantHeatCondition</a> - Configure coolant heat conditions</li>
<li><a class="xref" href="../../api/Hi.Machining.MachiningEquipmentUtils.SetupEquipment.html#Hi_Machining_MachiningEquipmentUtils_SetupEquipment_AmbientTemperature_C">AmbientTemperature_C</a> - Configure the ambient (shop-floor) temperature in Celsius, the temperature the thermal model starts from; <a class="xref" href="../../api/Hi.Machining.MachiningEquipmentUtils.SetupEquipment.html#Hi_Machining_MachiningEquipmentUtils_SetupEquipment_AmbientTemperature_K">AmbientTemperature_K</a> holds the same value in Kelvin</li>
</ul>
</li>
<li>Variable settings:
<ul>
<li><a class="xref" href="../../api/Hi.NcMech.Fixtures.Fixture.html">Fixture</a> - Configure fixture</li>
<li><a class="xref" href="../../api/Hi.NcMech.Workpieces.Workpiece.html">Workpiece</a> - Configure workpiece</li>
</ul>
</li>
</ul>
</li>
<li>Set <a class="xref" href="../../api/Hi.Machining.MachiningToolHouse.html">MachiningToolHouse</a> - Configure tool house</li>
<li>Set <a class="xref" href="../../api/Hi.Numerical.HardNcEnv.html">HardNcEnv</a> (Controller) - Configure NC system environment parameters</li>
</ul>
<h3 id="3-setting-project-tasks">3. Setting Project Tasks</h3>
<p>Set sequential tasks using <a class="xref" href="../../api/Hi.MachiningProcs.MachiningProject.html#Hi_MachiningProcs_MachiningProject_PlayerCommand">PlayerCommand</a>:</p>
<ul>
<li>Set NC Files - Set the file path and customize simulation and optimization settings for each NC file</li>
<li>Configure NC optimization - Configure NC code optimization parameters</li>
<li>Set <a class="xref" href="../../api/Hi.SessionCommands.GeomDiffCommand.html">GeomDiffCommand</a> - Configure geometry comparison functionality to compare target workpiece shape with simulated shape</li>
<li>Set <a class="xref" href="../../api/Hi.MillingForces.Training.MillingTraining.html">MillingTraining</a> - Configure milling parameter training to calibrate simulation parameters based on actual machining data</li>
<li>Other task configurations&hellip;</li>
</ul>
<p>The PlayerCommand is typically a <a class="xref" href="../../api/Hi.SessionCommands.ListCommand.html">ListCommand</a> that contains a sequence of command entries to be executed during the simulation.</p>
<h3 id="4-run-the-tasks-simulation-and-optimization">4. Run the Tasks (Simulation and Optimization)</h3>
<p>Run <a class="xref" href="../../api/Hi.MachiningProcs.MachiningProject.html#Hi_MachiningProcs_MachiningProject_PlayerCommand">PlayerCommand</a> through <a class="xref" href="../../api/Hi.MachiningProcs.LocalProjectService.html#Hi_MachiningProcs_LocalProjectService_PacePlayer">PacePlayer</a>.</p>
<p>At this stage, the simulation process is similar to video playback, which can be:</p>
<ul>
<li>Started</li>
<li>Stopped</li>
<li>Paused</li>
<li>Run one line</li>
<li>Run one step</li>
<li>Reset</li>
</ul>
<p>The <a class="xref" href="../../api/Hi.MachiningProcs.LocalProjectService.html#Hi_MachiningProcs_LocalProjectService_PacePlayer">PacePlayer</a> controls the execution pace of the simulation, allowing you to observe the machining process in detail or run it at full speed.</p>
<h4 id="view-the-analysis-during-process-or-result">View the Analysis During Process or Result</h4>
<p><a class="xref" href="../../api/Hi.MachiningProcs.ShellProgress.html">ShellProgress</a> contains a sequence of simulation messages and step data, which can be used to monitor and analyze the simulation process and results.</p>
<h2 id="sample-code-to-start-a-">Sample Code to Start a <a class="xref" href="../../api/Hi.MachiningProcs.MachiningProject.html">MachiningProject</a></h2>
<p>See the following sample code to start a HiAPI application.</p>
<ul>
<li><code>DemoBuildMachiningProject</code>
Build a <a class="xref" href="../../api/Hi.MachiningProcs.MachiningProject.html">MachiningProject</a>.</li>
<li><code>DemoUseMachiningProject</code>
Load a <a class="xref" href="../../api/Hi.MachiningProcs.MachiningProject.html">MachiningProject</a> and run NC simulation.</li>
<li><code>DemoRenderingMachiningProcessAndStripPosSelection</code>
Apply <a class="xref" href="../../api/Hi.MachiningProcs.MachiningProject.html">MachiningProject</a> to 3D canvas with user-interaction in windows platform.</li>
</ul>
<h2 id="see-also">See Also</h2>
<ul>
<li><a href="packages-and-samples.html">HiAPI Packages and Sample Code</a> — the NuGet feed and the sample repositories the demos named here live in</li>
<li><a href="basic-geometry.html">Geometry Objects</a> — the geometry types the environment in step 2 is assembled from</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>