Table of Contents

Workflow: Constructing a Project through the Web API

Basic Simulation describes what a project contains. This page describes how to build one so that it is actually finished — 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.

It is written for whoever assembles a .hincproj from a customer's deliverables — a person driving the browser UI, or an agent driving the same operations over the HTTP API.

flowchart TD
    New["1 · New project<br>(self-contained root)"]
    Assets["2 · Place assets<br>NC, STL, resource files"]
    Equip["3 · Equipment<br>chain, spindle"]
    Job["4 · Job<br>stock, ideal geom, material"]
    Ctrl["5 · Controller<br>brand + its own tables"]
    Tools["6 · Tool house"]
    Mission["7 · Mission<br>grouped, per-group resolution"]
    Replay["8 · Replay and read<br>every message"]
    Cross["9 · Numeric cross-checks"]
    Assume["10 · Record every assumption"]

    New --> Assets --> Equip --> Job --> Ctrl --> Tools --> Mission --> Replay --> Cross --> Assume
    Replay -->|any warning| Ctrl

Build through the API, not by editing the XML

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 .hincproj XML is a fallback for fields the API cannot yet reach — and when you hit one, the better fix is to add the endpoint.

1. One self-contained root

The .hincproj and every asset it references live under one folder — the project's own directory — and every reference is relative to it with no ../.

<project>/
├── <name>.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

Two things do not move themselves, so bring them in by hand before you wire anything:

  • NC files. A program-file command stores a plain relative path; nothing copies the file.
  • Machine-tool side files. A chain that externalises its mechanism references the side file and its STL bodies by bare name, relative to the .mt's own folder — keep the whole folder together.

Resource files (chain, spindle, cutting parameters, workpiece material, cutter material) are pre-prepared data loaded by reference. 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.

2. Order the build to avoid rework

Later steps read earlier ones, so this order costs the least:

  1. New project at its final path.
  2. Machine tool, then spindle capability.
  3. Workpiece: stock geometry, ideal (target) geometry, resolution, the geometry-to-program-zero and geometry-to-fixture transforms, then material and cutting parameters.
  4. Controller: brand first — switching brand later resets brand-specific tables — then the controller's own tables (§4).
  5. Tool house: per tool, shaper profile → fluting → exposed height → holder → upper beam → cutter material. Then refresh the offset tables from the tool house.
  6. Program zero: with the workpiece placed and the chain loaded, derive the work offset from the model rather than typing a number. See Program Zero Alignment.
  7. Mission (§3).
  8. Save, then load the saved file back and re-check. A project that cannot be reloaded cleanly is not built.
Important

Verify the axis set after loading a machine tool. A kinematic chain binds each axis transformer by branch name (X/Y/Z/A/B/C); 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 reports a Z — only a missing rotary gives it away. Compare the reported axes against the mechanism you expect.

3. Shape the mission around the process, not the file list

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 List command per operation family, in the order the process actually runs:

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

Why this shape:

  • Grouping must not reorder. The stock evolves from one operation to the next, so the sequence is load-bearing. Group adjacent operations; never sort the list into tidy families if that moves an operation past another one.
  • Each group carries its own machining resolution. 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.
  • A group is a switch. Disabling one List skips a whole phase, which is how you re-run just the finishing passes without deleting anything.
  • Budget the fine groups. Machining resolution drives the cost of subtracting material, not the number of simulation steps — the step count follows the motion 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.
  • Setup commands are granular. 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.
Tip

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.

4. Fill the controller's own tables

The tool house describes the physical tool. The controller has its own record of the same tool, and the NC program reads the controller's copy. Both must exist.

For a Siemens-style controller that is two tables:

Table Holds If empty
Tool name → tool number the names a T="…" call uses the tool never mounts, and the program produces no machining steps at all
Tool edge offsets per (tool, edge): length along the tool axis, radius every edge call falls back to the generic offset table and logs a warning

Take the values from the tool house and assert they match before writing. 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.

Note

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 guessed value (an assumed spindle, say) into a second place means both must move when the real datum arrives.

5. The finish line is a clean replay, not a filled form

Replay the whole mission and inventory the messages by id. 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.

Read messages at a low severity so nothing hides. The severities are Message, Success, Progress, Warning, Error — note there is no Info, and an unrecognised name is rejected in the response body rather than by an HTTP error, which reads exactly like “no messages”.

Stop when only declared informational messages remain — the ones that state a known, deliberate limitation. Typical survivors:

  • one per NC file, reporting the line count;
  • 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.

Anything else is work.

6. Two numeric cross-checks — and what they do not prove

Messages catch what the runner noticed. These two catch datum errors that produce no message at all.

Depth of cut against the programmed layer depth. 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.

Cycle time against the post-processor's own estimate. Many post-processors write a per-operation machining time into the program as a comment. Sum them and compare with the simulated time.

Warning

Scope the cycle-time check honestly. It confirms that feed rates and path length are consumed correctly. It is not 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.

For the same reason, a customer's “total machining time” running well above the sum of the per-operation comments is usually not a contradiction — the comments are cutting time, the total is wall clock including tool changes and inter-operation moves. Two different quantities.

7. Record every assumption

Real deliverables are incomplete. Build with sensible values, and write each one down in a README.md beside the .hincproj — 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.

Cross-reference: Project Data Checklist is the list to hand the customer before building; this section is what you hand back after.