fix SoftNcRunner GM code normalization.

This commit is contained in:
2026-05-06 13:21:19 +08:00
parent 0fe9497552
commit 2f57932000
1238 changed files with 69405 additions and 22511 deletions
@@ -6,7 +6,7 @@
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="title" content="Class TransformationUtil | HiAPI-C# 2025 ">
<meta name="description" content="Utilities for the chain. Each entry has &amp;ldquo;Source&amp;rdquo; (string) and &amp;ldquo;Mat4d&amp;rdquo; (16-element JsonArray). inserts or replaces an entry by source name. composes all entries into a single Mat4d.">
<meta name="description" content="Utilities for the chain. Each entry is {Source, Kind, Mat4d}; entries are composed in order with pure matrix multiplication (). partitions the entries by contour validity: — the matrix is valid across the whole block, applicable to any interpolated point along the contour. — the matrix is a block-endpoint snapshot of a rotary-state-dependent transform (RTCP rotary-dynamic). Composing it produces a correct endpoint MC, but interpolated points along the contour must be derived per-step by motion semantics (); do not apply it to interpolated ProgramXyz. Both kinds carry a real Mat4d so composition stays a pure matrix product — no entry has a missing matrix. Use to detect the dynamic-rotary state without consulting a sibling section flag.">
<link rel="icon" href="../img/HiAPI.favicon.ico">
<link rel="stylesheet" href="../public/docfx.min.css">
<link rel="stylesheet" href="../public/main.css">
@@ -98,9 +98,21 @@ Class TransformationUtil
</div>
<div class="markdown summary"><p>Utilities for the <a class="xref" href="Hi.NcParsers.Keywords.ITransformationDef.html#Hi_NcParsers_Keywords_ITransformationDef_ProgramToMcTransform">ProgramToMcTransform</a> chain.
Each entry has &ldquo;Source&rdquo; (string) and &ldquo;Mat4d&rdquo; (16-element JsonArray).
<a class="xref" href="Hi.NcParsers.Syntaxs.TransformationUtil.html#Hi_NcParsers_Syntaxs_TransformationUtil_AddOrReplaceTransform_System_Text_Json_Nodes_JsonObject_System_String_Hi_Geom_Mat4d_">AddOrReplaceTransform(JsonObject, string, Mat4d)</a> inserts or replaces an entry by source name.
<a class="xref" href="Hi.NcParsers.Syntaxs.TransformationUtil.html#Hi_NcParsers_Syntaxs_TransformationUtil_GetComposedTransform_System_Text_Json_Nodes_JsonObject_">GetComposedTransform(JsonObject)</a> composes all entries into a single Mat4d.</p>
Each entry is <code>{Source, Kind, Mat4d}</code>; entries are composed in order
with pure matrix multiplication (<a class="xref" href="Hi.NcParsers.Syntaxs.TransformationUtil.html#Hi_NcParsers_Syntaxs_TransformationUtil_GetComposedTransform_System_Text_Json_Nodes_JsonObject_">GetComposedTransform(JsonObject)</a>).</p>
<p>
<a class="xref" href="Hi.NcParsers.Syntaxs.TransformationUtil.html#Hi_NcParsers_Syntaxs_TransformationUtil_KindKey">KindKey</a> partitions the entries by contour validity:
<ul><li><a class="xref" href="Hi.NcParsers.Syntaxs.TransformationUtil.html#Hi_NcParsers_Syntaxs_TransformationUtil_KindStatic">KindStatic</a> — the matrix is valid across the whole
block, applicable to any interpolated point along the contour.</li><li><a class="xref" href="Hi.NcParsers.Syntaxs.TransformationUtil.html#Hi_NcParsers_Syntaxs_TransformationUtil_KindDynamic">KindDynamic</a> — the matrix is a block-endpoint snapshot
of a rotary-state-dependent transform (RTCP rotary-dynamic). Composing it
produces a correct endpoint MC, but interpolated points along the contour
must be derived per-step by motion semantics
(<a class="xref" href="Hi.NcParsers.Semantics.ClLinearMotionSemantic.html">ClLinearMotionSemantic</a>); do not apply it to
interpolated ProgramXyz.</li></ul>
Both kinds carry a real Mat4d so composition stays a pure matrix product —
no entry has a missing matrix. Use <a class="xref" href="Hi.NcParsers.Syntaxs.TransformationUtil.html#Hi_NcParsers_Syntaxs_TransformationUtil_HasDynamicEntry_System_Text_Json_Nodes_JsonObject_">HasDynamicEntry(JsonObject)</a> to detect
the dynamic-rotary state without consulting a sibling section flag.
</div>
<div class="markdown conceptual"></div>
@@ -157,12 +169,108 @@ Each entry has &ldquo;Source&rdquo; (string) and &ldquo;Mat4d&rdquo; (16-element
<h3 id="Hi_NcParsers_Syntaxs_TransformationUtil_KindDynamic" data-uid="Hi.NcParsers.Syntaxs.TransformationUtil.KindDynamic">
KindDynamic
</h3>
<div class="markdown level1 summary"><p>The entry's Mat4d is a block-endpoint snapshot only; intermediate
contour points must be resolved by per-step IK in motion semantics.</p>
</div>
<div class="markdown level1 conceptual"></div>
<div class="codewrapper">
<pre><code class="lang-csharp hljs">public const string KindDynamic = &quot;Dynamic&quot;</code></pre>
</div>
<h4 class="section">Field Value</h4>
<dl class="parameters">
<dt><a class="xref" href="https://learn.microsoft.com/dotnet/api/system.string">string</a></dt>
<dd></dd>
</dl>
<h3 id="Hi_NcParsers_Syntaxs_TransformationUtil_KindKey" data-uid="Hi.NcParsers.Syntaxs.TransformationUtil.KindKey">
KindKey
</h3>
<div class="markdown level1 summary"><p>JSON key for the entry's contour-validity classification.
Value must be <a class="xref" href="Hi.NcParsers.Syntaxs.TransformationUtil.html#Hi_NcParsers_Syntaxs_TransformationUtil_KindStatic">KindStatic</a> or <a class="xref" href="Hi.NcParsers.Syntaxs.TransformationUtil.html#Hi_NcParsers_Syntaxs_TransformationUtil_KindDynamic">KindDynamic</a>.</p>
</div>
<div class="markdown level1 conceptual"></div>
<div class="codewrapper">
<pre><code class="lang-csharp hljs">public const string KindKey = &quot;Kind&quot;</code></pre>
</div>
<h4 class="section">Field Value</h4>
<dl class="parameters">
<dt><a class="xref" href="https://learn.microsoft.com/dotnet/api/system.string">string</a></dt>
<dd></dd>
</dl>
<h3 id="Hi_NcParsers_Syntaxs_TransformationUtil_KindStatic" data-uid="Hi.NcParsers.Syntaxs.TransformationUtil.KindStatic">
KindStatic
</h3>
<div class="markdown level1 summary"><p>The entry's Mat4d is valid for any point along the contour.</p>
</div>
<div class="markdown level1 conceptual"></div>
<div class="codewrapper">
<pre><code class="lang-csharp hljs">public const string KindStatic = &quot;Static&quot;</code></pre>
</div>
<h4 class="section">Field Value</h4>
<dl class="parameters">
<dt><a class="xref" href="https://learn.microsoft.com/dotnet/api/system.string">string</a></dt>
<dd></dd>
</dl>
<h3 id="Hi_NcParsers_Syntaxs_TransformationUtil_Mat4dKey" data-uid="Hi.NcParsers.Syntaxs.TransformationUtil.Mat4dKey">
Mat4dKey
</h3>
<div class="markdown level1 summary"></div>
<div class="markdown level1 summary"><p>JSON key for the <a class="xref" href="Hi.Geom.Mat4d.html">Mat4d</a> snapshot inside each chain entry.</p>
</div>
<div class="markdown level1 conceptual"></div>
<div class="codewrapper">
@@ -187,12 +295,51 @@ Each entry has &ldquo;Source&rdquo; (string) and &ldquo;Mat4d&rdquo; (16-element
<h3 id="Hi_NcParsers_Syntaxs_TransformationUtil_PivotTransformSource" data-uid="Hi.NcParsers.Syntaxs.TransformationUtil.PivotTransformSource">
PivotTransformSource
</h3>
<div class="markdown level1 summary"><p>Canonical source name for the RTCP pivot transform — the
kinematic transform from Pn (post-G54, post-G68.2) to MC at the
block's endpoint ABC. Contributed by
<a class="xref" href="Hi.NcParsers.LogicSyntaxs.PivotTransformationSyntax.html">PivotTransformationSyntax</a>. Must be the
<b>last</b> entry written into the chain so that all Pn-frame
operations (tilt, tool-height, coord-offset) are accumulated before
the final kinematic IK; this ordering is enforced by the syntax-
chain registration order, not by the writer API.</p>
</div>
<div class="markdown level1 conceptual"></div>
<div class="codewrapper">
<pre><code class="lang-csharp hljs">public const string PivotTransformSource = &quot;PivotTransform&quot;</code></pre>
</div>
<h4 class="section">Field Value</h4>
<dl class="parameters">
<dt><a class="xref" href="https://learn.microsoft.com/dotnet/api/system.string">string</a></dt>
<dd></dd>
</dl>
<h3 id="Hi_NcParsers_Syntaxs_TransformationUtil_SourceKey" data-uid="Hi.NcParsers.Syntaxs.TransformationUtil.SourceKey">
SourceKey
</h3>
<div class="markdown level1 summary"></div>
<div class="markdown level1 summary"><p>JSON key for the transform origin label inside each chain entry.</p>
</div>
<div class="markdown level1 conceptual"></div>
<div class="codewrapper">
@@ -216,25 +363,60 @@ Each entry has &ldquo;Source&rdquo; (string) and &ldquo;Mat4d&rdquo; (16-element
<h3 id="Hi_NcParsers_Syntaxs_TransformationUtil_ToolHeightCompensationSource" data-uid="Hi.NcParsers.Syntaxs.TransformationUtil.ToolHeightCompensationSource">
ToolHeightCompensationSource
</h3>
<div class="markdown level1 summary"><p>Canonical source name for the tool-height-compensation entry
(tool-normal · offset_mm along the current tool axis). Matches the
<code>ToolHeightCompensation</code> section key read for
<a class="xref" href="Hi.NcParsers.Keywords.IToolHeightCompensationDef.html#Hi_NcParsers_Keywords_IToolHeightCompensationDef_Offset_mm">Offset_mm</a>.</p>
</div>
<div class="markdown level1 conceptual"></div>
<div class="codewrapper">
<pre><code class="lang-csharp hljs">public const string ToolHeightCompensationSource = &quot;ToolHeightCompensation&quot;</code></pre>
</div>
<h4 class="section">Field Value</h4>
<dl class="parameters">
<dt><a class="xref" href="https://learn.microsoft.com/dotnet/api/system.string">string</a></dt>
<dd></dd>
</dl>
<h2 class="section" id="methods">Methods
</h2>
<a id="Hi_NcParsers_Syntaxs_TransformationUtil_AddOrReplaceTransform_" data-uid="Hi.NcParsers.Syntaxs.TransformationUtil.AddOrReplaceTransform*"></a>
<h3 id="Hi_NcParsers_Syntaxs_TransformationUtil_AddOrReplaceTransform_System_Text_Json_Nodes_JsonObject_System_String_Hi_Geom_Mat4d_" data-uid="Hi.NcParsers.Syntaxs.TransformationUtil.AddOrReplaceTransform(System.Text.Json.Nodes.JsonObject,System.String,Hi.Geom.Mat4d)">
AddOrReplaceTransform(JsonObject, string, Mat4d)
<h3 id="Hi_NcParsers_Syntaxs_TransformationUtil_AddOrReplaceTransform_System_Text_Json_Nodes_JsonObject_System_String_System_String_Hi_Geom_Mat4d_" data-uid="Hi.NcParsers.Syntaxs.TransformationUtil.AddOrReplaceTransform(System.Text.Json.Nodes.JsonObject,System.String,System.String,Hi.Geom.Mat4d)">
AddOrReplaceTransform(JsonObject, string, string, Mat4d)
</h3>
<div class="markdown level1 summary"><p>Adds or replaces a named transformation entry in the chain.
If an entry with the same source already exists, it is replaced in-place.
Otherwise the new entry is appended.</p>
Otherwise the new entry is appended.
<code class="paramref">kind</code> must be <a class="xref" href="Hi.NcParsers.Syntaxs.TransformationUtil.html#Hi_NcParsers_Syntaxs_TransformationUtil_KindStatic">KindStatic</a> or <a class="xref" href="Hi.NcParsers.Syntaxs.TransformationUtil.html#Hi_NcParsers_Syntaxs_TransformationUtil_KindDynamic">KindDynamic</a>.</p>
</div>
<div class="markdown level1 conceptual"></div>
<div class="codewrapper">
<pre><code class="lang-csharp hljs">public static void AddOrReplaceTransform(JsonObject json, string source, Mat4d mat)</code></pre>
<pre><code class="lang-csharp hljs">public static void AddOrReplaceTransform(JsonObject json, string source, string kind, Mat4d mat)</code></pre>
</div>
<h4 class="section">Parameters</h4>
@@ -243,6 +425,8 @@ Otherwise the new entry is appended.</p>
<dd></dd>
<dt><code>source</code> <a class="xref" href="https://learn.microsoft.com/dotnet/api/system.string">string</a></dt>
<dd></dd>
<dt><code>kind</code> <a class="xref" href="https://learn.microsoft.com/dotnet/api/system.string">string</a></dt>
<dd></dd>
<dt><code>mat</code> <a class="xref" href="Hi.Geom.Mat4d.html">Mat4d</a></dt>
<dd></dd>
</dl>
@@ -265,8 +449,12 @@ Otherwise the new entry is appended.</p>
</h3>
<div class="markdown level1 summary"><p>Composes all entries in the chain into a single Mat4d (left-to-right multiplication).
Returns identity if chain is empty or absent.</p>
<div class="markdown level1 summary"><p>Composes all entries in the chain into a single block-endpoint Mat4d
(left-to-right multiplication). Pure multiplication — no special
cases, no kinematic lookup. The returned matrix is valid <b>only</b>
for the block's endpoint state; see
<a class="xref" href="Hi.NcParsers.Keywords.ITransformationDef.html#Hi_NcParsers_Keywords_ITransformationDef_ProgramToMcTransform">ProgramToMcTransform</a> for
the endpoint-semantic contract.</p>
</div>
<div class="markdown level1 conceptual"></div>
@@ -335,35 +523,35 @@ Returns identity if chain is empty or absent.</p>
<a id="Hi_NcParsers_Syntaxs_TransformationUtil_GetVec3d_" data-uid="Hi.NcParsers.Syntaxs.TransformationUtil.GetVec3d*"></a>
<a id="Hi_NcParsers_Syntaxs_TransformationUtil_HasDynamicEntry_" data-uid="Hi.NcParsers.Syntaxs.TransformationUtil.HasDynamicEntry*"></a>
<h3 id="Hi_NcParsers_Syntaxs_TransformationUtil_GetVec3d_System_Text_Json_Nodes_JsonObject_System_String_Hi_Geom_Vec3d_" data-uid="Hi.NcParsers.Syntaxs.TransformationUtil.GetVec3d(System.Text.Json.Nodes.JsonObject,System.String,Hi.Geom.Vec3d)">
GetVec3d(JsonObject, string, Vec3d)
<h3 id="Hi_NcParsers_Syntaxs_TransformationUtil_HasDynamicEntry_System_Text_Json_Nodes_JsonObject_" data-uid="Hi.NcParsers.Syntaxs.TransformationUtil.HasDynamicEntry(System.Text.Json.Nodes.JsonObject)">
HasDynamicEntry(JsonObject)
</h3>
<div class="markdown level1 summary"><p>Reads a Vec3d from a sub-object with X/Y/Z keys.
Returns <code class="paramref">fallback</code> if not present.</p>
<div class="markdown level1 summary"><p>Returns <code>true</code> if any entry in the chain carries
<a class="xref" href="Hi.NcParsers.Syntaxs.TransformationUtil.html#Hi_NcParsers_Syntaxs_TransformationUtil_KindDynamic">KindDynamic</a>. Used by motion-form selection
(<a class="xref" href="Hi.NcParsers.LogicSyntaxs.LinearMotionSyntax.html">LinearMotionSyntax</a>) and ProgramXyz
strategy dispatch (<a class="xref" href="Hi.NcParsers.LogicSyntaxs.ProgramXyzUtil.html">ProgramXyzUtil</a>) to
detect RTCP-rotary-dynamic state without consulting a flag on a
sibling section. Throws if any entry lacks <a class="xref" href="Hi.NcParsers.Syntaxs.TransformationUtil.html#Hi_NcParsers_Syntaxs_TransformationUtil_KindKey">KindKey</a>.</p>
</div>
<div class="markdown level1 conceptual"></div>
<div class="codewrapper">
<pre><code class="lang-csharp hljs">public static Vec3d GetVec3d(JsonObject json, string sectionKey, Vec3d fallback)</code></pre>
<pre><code class="lang-csharp hljs">public static bool HasDynamicEntry(JsonObject json)</code></pre>
</div>
<h4 class="section">Parameters</h4>
<dl class="parameters">
<dt><code>json</code> <a class="xref" href="https://learn.microsoft.com/dotnet/api/system.text.json.nodes.jsonobject">JsonObject</a></dt>
<dd></dd>
<dt><code>sectionKey</code> <a class="xref" href="https://learn.microsoft.com/dotnet/api/system.string">string</a></dt>
<dd></dd>
<dt><code>fallback</code> <a class="xref" href="Hi.Geom.Vec3d.html">Vec3d</a></dt>
<dd></dd>
</dl>
<h4 class="section">Returns</h4>
<dl class="parameters">
<dt><a class="xref" href="Hi.Geom.Vec3d.html">Vec3d</a></dt>
<dt><a class="xref" href="https://learn.microsoft.com/dotnet/api/system.boolean">bool</a></dt>
<dd></dd>
</dl>
@@ -377,31 +565,94 @@ Returns <code class="paramref">fallback</code> if not present.</p>
<a id="Hi_NcParsers_Syntaxs_TransformationUtil_SetVec3d_" data-uid="Hi.NcParsers.Syntaxs.TransformationUtil.SetVec3d*"></a>
<a id="Hi_NcParsers_Syntaxs_TransformationUtil_MakePivotTransformMat_" data-uid="Hi.NcParsers.Syntaxs.TransformationUtil.MakePivotTransformMat*"></a>
<h3 id="Hi_NcParsers_Syntaxs_TransformationUtil_SetVec3d_System_Text_Json_Nodes_JsonObject_System_String_Hi_Geom_Vec3d_" data-uid="Hi.NcParsers.Syntaxs.TransformationUtil.SetVec3d(System.Text.Json.Nodes.JsonObject,System.String,Hi.Geom.Vec3d)">
SetVec3d(JsonObject, string, Vec3d)
<h3 id="Hi_NcParsers_Syntaxs_TransformationUtil_MakePivotTransformMat_Hi_Numerical_Xyzabc_IMachineKinematics_Hi_Geom_Vec3d_" data-uid="Hi.NcParsers.Syntaxs.TransformationUtil.MakePivotTransformMat(Hi.Numerical.Xyzabc.IMachineKinematics,Hi.Geom.Vec3d)">
MakePivotTransformMat(IMachineKinematics, Vec3d)
</h3>
<div class="markdown level1 summary"><p>Writes a Vec3d as a sub-object with X/Y/Z keys.</p>
<div class="markdown level1 summary"><p>Builds the <a class="xref" href="Hi.NcParsers.Syntaxs.TransformationUtil.html#Hi_NcParsers_Syntaxs_TransformationUtil_PivotTransformSource">PivotTransformSource</a> Mat4d — an
empirically-constructed Pn→MC rigid-affine transform at the block's
endpoint ABC. Equivalent to
<code>kinematics.PnToMc(pn_input, normal).Point</code> when applied to
a Pn-frame point, but expressed as a reusable Mat4d so the chain
stays a pure matrix product (no per-point IK call inside
<a class="xref" href="Hi.NcParsers.Syntaxs.TransformationUtil.html#Hi_NcParsers_Syntaxs_TransformationUtil_GetComposedTransform_System_Text_Json_Nodes_JsonObject_">GetComposedTransform(JsonObject)</a>).</p>
<p>
Constructed by probing <a class="xref" href="Hi.Numerical.Xyzabc.IMachineKinematics.html#Hi_Numerical_Xyzabc_IMachineKinematics_McToPn_Hi_Geom_DVec3d_">McToPn(DVec3d)</a> at
the four standard basis points (origin + XYZ unit vectors) at the
target ABC to derive <code>K(abc)</code>, and similarly at ABC=0 to derive
<code>K(0)</code>; returns <code>K(0) · K(abc).GetInverse()</code>. Topology-
agnostic — works for any affine kinematic chain regardless of axis
order. Legacy <a class="xref" href="Hi.Numerical.Xyzabc.IMachineKinematics.html#Hi_Numerical_Xyzabc_IMachineKinematics_PnToMc_Hi_Geom_DVec3d_Hi_Geom_DVec3d__">PnToMc(DVec3d, out DVec3d)</a> remains the
reference oracle.
</p>
</div>
<div class="markdown level1 conceptual"></div>
<div class="codewrapper">
<pre><code class="lang-csharp hljs">public static void SetVec3d(JsonObject json, string sectionKey, Vec3d v)</code></pre>
<pre><code class="lang-csharp hljs">public static Mat4d MakePivotTransformMat(IMachineKinematics kinematics, Vec3d abc_rad)</code></pre>
</div>
<h4 class="section">Parameters</h4>
<dl class="parameters">
<dt><code>json</code> <a class="xref" href="https://learn.microsoft.com/dotnet/api/system.text.json.nodes.jsonobject">JsonObject</a></dt>
<dt><code>kinematics</code> <a class="xref" href="Hi.Numerical.Xyzabc.IMachineKinematics.html">IMachineKinematics</a></dt>
<dd></dd>
<dt><code>sectionKey</code> <a class="xref" href="https://learn.microsoft.com/dotnet/api/system.string">string</a></dt>
<dd></dd>
<dt><code>v</code> <a class="xref" href="Hi.Geom.Vec3d.html">Vec3d</a></dt>
<dt><code>abc_rad</code> <a class="xref" href="Hi.Geom.Vec3d.html">Vec3d</a></dt>
<dd></dd>
</dl>
<h4 class="section">Returns</h4>
<dl class="parameters">
<dt><a class="xref" href="Hi.Geom.Mat4d.html">Mat4d</a></dt>
<dd></dd>
</dl>
<a id="Hi_NcParsers_Syntaxs_TransformationUtil_MakeToolHeightMat_" data-uid="Hi.NcParsers.Syntaxs.TransformationUtil.MakeToolHeightMat*"></a>
<h3 id="Hi_NcParsers_Syntaxs_TransformationUtil_MakeToolHeightMat_Hi_Numerical_Xyzabc_IMachineKinematics_Hi_Geom_Vec3d_System_Double_" data-uid="Hi.NcParsers.Syntaxs.TransformationUtil.MakeToolHeightMat(Hi.Numerical.Xyzabc.IMachineKinematics,Hi.Geom.Vec3d,System.Double)">
MakeToolHeightMat(IMachineKinematics, Vec3d, double)
</h3>
<div class="markdown level1 summary"><p>Builds the tool-height-compensation Mat4d for a given rotary state:
translate by (tool-normal at <code class="paramref">abc_rad</code>) · <code class="paramref">height_mm</code>.
Pure translation (no rotation component); combines with the
downstream <a class="xref" href="Hi.NcParsers.Syntaxs.TransformationUtil.html#Hi_NcParsers_Syntaxs_TransformationUtil_PivotTransformSource">PivotTransformSource</a> to form the full
Pn→MC IK.</p>
</div>
<div class="markdown level1 conceptual"></div>
<div class="codewrapper">
<pre><code class="lang-csharp hljs">public static Mat4d MakeToolHeightMat(IMachineKinematics kinematics, Vec3d abc_rad, double height_mm)</code></pre>
</div>
<h4 class="section">Parameters</h4>
<dl class="parameters">
<dt><code>kinematics</code> <a class="xref" href="Hi.Numerical.Xyzabc.IMachineKinematics.html">IMachineKinematics</a></dt>
<dd></dd>
<dt><code>abc_rad</code> <a class="xref" href="Hi.Geom.Vec3d.html">Vec3d</a></dt>
<dd></dd>
<dt><code>height_mm</code> <a class="xref" href="https://learn.microsoft.com/dotnet/api/system.double">double</a></dt>
<dd></dd>
</dl>
<h4 class="section">Returns</h4>
<dl class="parameters">
<dt><a class="xref" href="Hi.Geom.Mat4d.html">Mat4d</a></dt>
<dd></dd>
</dl>