Table of Contents

Getting Started with HiAPI

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. A script that drives a running HiNC web service over HTTP needs none of the packages; it starts from Driving the Web Service over HTTP instead.

Installation

  1. Create a dotnet project targeting net10.0 — or net10.0-windows if it also hosts a Windows UI. All the packages below are framework-independent and restore into either. An earlier target framework cannot reference any of them.

  2. Register the HiAPI package source on the machine.

    The feed requires authentication, and the same account that gives you the sample repositories gives you the packages. One command registers the source and its credentials, which is the whole of what a restore needs:

    dotnet nuget add source https://gitea.superhightech.com.tw/api/packages/HiAPI/nuget/index.json --name HiAPI --username <your-account> --password <your-token> --store-password-in-clear-text

    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.

    Prefer this to a project-local nuget.config, and never declare the feed in both places. NuGet resolves credentials by source name, 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 second, credential-less source. NuGet asks every source about every package, and one 401 fails the whole restore instead of falling through — so the packages it then reports as missing are the public nuget.org 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.

    Where a per-machine source is genuinely unavailable — an ephemeral build agent, say — a nuget.config 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:

    <?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="HiAPI" value="https://gitea.superhightech.com.tw/api/packages/HiAPI/nuget/index.json" />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
  </packageSources>
  <packageSourceCredentials>
    <HiAPI>
      <add key="Username" value="xxxxxx" />
      <add key="ClearTextPassword" value="xxxxxx" />
    </HiAPI>
  </packageSourceCredentials>
</configuration>

    That file holds a password in clear text: keep it out of version control.

  3. In the dotnet project file, add the package reference.

    <ItemGroup>
  <PackageReference Include="HiNc" Version="3.2.*" />
</ItemGroup>

    HiNc pulls the rest of the stack in. Nothing here puts a 3D view on screen — that component is your application's, and Building Your Own Rendering Canvas covers it.

  4. In the program file, setting the HiNC application initialization and finalization.

    using Hi.HiNcKits;
using Microsoft.Extensions.Logging;
using System;

namespace Sample
{
    /// <summary>
    /// 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.
    /// </summary>
    /// <remarks>
    /// 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)]
    /// </remarks>
    public static class HelloHiAPI
    {
        static int Main(string[] args)
        {
            Console.WriteLine("HiAPI starting.");
            using var loggerFactory = Microsoft.Extensions.Logging.LoggerFactory.Create(b => b.AddConsole());
            LocalApp.AppBegin(loggerFactory.CreateLogger("Hi.Sample"));

            Console.WriteLine("Hello World! HiAPI.");

            LocalApp.AppEnd();
            Console.WriteLine("HiAPI exited.");

            return 0;
        }
    }
}

The Shape of a HiNC Program

Every HiNC program, whether it is the shipped application or twenty lines in a console project, runs the same five steps. DemoBuildMachiningProject in the Hi.Sample repository is the complete worked example.

graph TD
    A["Create MachiningProject"] --> B["Setting Environment"]
    B --> C["Setting Project Tasks"]
    C --> D["Run Tasks"]
    D --> E["View Analysis Results"]

1. Create MachiningProject

Creating a machining project is the first step in the HiNC workflow, accomplished by initializing a MachiningProject object.

2. Setting Environment In MachiningProject

The equipment has two faces. SetupEquipment is the authored one — the only face a project file persists, and the one every setting below is written to. MachiningEquipment 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, the authored face's parts shown on it as copies. A value written onto the face MachiningEquipment hands out is written back to the authored face: a workpiece, fixture, machine chain or table transformer at once with no session alive and at the next session boundary otherwise, the environment values and the two file names (MachiningChainFile, SpindleCapabilityFile) at once. The runtime face follows (rebuilt, but for an environment value), so take it from the property again after a write. A tool written there is the run's and is not written back, and a value written onto a MachiningEquipment made with new is not saved. An equipment saved in a file of its own, whose root element is <MachiningEquipment>, loads as a SetupEquipment: read it with XFactory.GenByFile<SetupEquipment> and assign it to SetupEquipment (on a project a LocalProjectService already holds, call its NotifySetupEquipmentEdited after the assignment so the runtime face follows). Asked for as a MachiningEquipment (XFactory.GenByFile<MachiningEquipment>, the reading of the earlier versions), the file answers the runtime face built from it, whose AuthoredFace is the saved one; assigned to MachiningEquipment, that authored face, with what was written on the face read, becomes the project's, and the property read again is the face the service runs. A part assigned from one equipment to another leaves the first: equipment.Workpiece assigned to Workpiece leaves equipment, whose Workpiece then reads null; the fixture and the machine chain move the same way. A workpiece from an equipment file in another folder keeps its material, cutting parameter and stock in the project.

3. Setting Project Tasks

Set sequential tasks using PlayerCommand:

  • Set NC Files - Set the file path and customize simulation and optimization settings for each NC file
  • Configure NC optimization - Configure NC code optimization parameters
  • Set GeomDiffCommand - Configure geometry comparison functionality to compare target workpiece shape with simulated shape
  • Set MillingTraining - Configure milling parameter training to calibrate simulation parameters based on actual machining data
  • Other task configurations…

The PlayerCommand is typically a ListCommand that contains a sequence of command entries to be executed during the simulation.

4. Run the Tasks (Simulation and Optimization)

Run PlayerCommand through PacePlayer.

At this stage, the simulation process is similar to video playback, which can be:

  • Started
  • Stopped
  • Paused
  • Run one line
  • Run one step
  • Reset

The PacePlayer controls the execution pace of the simulation, allowing you to observe the machining process in detail or run it at full speed.

View the Analysis During Process or Result

ShellProgress contains a sequence of simulation messages and step data, which can be used to monitor and analyze the simulation process and results.

Ending the Program

Dispose the LocalProjectService and every DispEngine the program created, then call AppEnd last. Disposing the MachiningProject leaves the service alone, and the service holds the play's threads, the played steps and the cut workpiece. Make these calls explicitly before AppEnd: a using declaration in the block that calls AppEnd disposes after it. DemoBuildMachiningProject ends this way.

Sample Code to Start a MachiningProject

See the following sample code to start a HiAPI application.

  • DemoBuildMachiningProject Build a MachiningProject.
  • DemoUseMachiningProject Load a MachiningProject and run NC simulation.
  • DemoRenderingMachiningProcessAndStripPosSelection Apply MachiningProject to 3D canvas with user-interaction in windows platform.

See Also