feat: Curve.HorizontalFrameAtParameter bug

[eamiri]

Closes #17105

Curve.HorizontalFrameAtParameter Bug Fix — Implementation Plan

Overview

Curve.HorizontalFrameAtParameter produces coordinate systems with all axes aligned to the world basis (identity rotation) when called on circles, instead of producing frames whose Y-axis follows the curve tangent at each parameter. The root cause is in ProtoGeometry.dll, shipped as the closed-source LibG NuGet package (DynamoVisualProgramming.LibG_232_0_0 v4.0.0.4841). This repo cannot fix the underlying logic, but it must: (1) coordinate the upstream fix, (2) consume the patched version once available, (3) improve in-repo documentation clarity, and (4) add a regression sanity-check graph so the bug cannot silently recur.

Current State Analysis

Key Discoveries:

• HorizontalFrameAtParameter has no C# source in this repo — all 36 references are docs, icons, resx, and Lucene fixtures. Implementation is entirely in ProtoGeometry.dll from LibG.
• LibG is pinned at DynamoVisualProgramming.LibG_232_0_0 v4.0.0.4841 in src/DynamoCore/DynamoCore.csproj:35-37 (three package references: Release, Debug, and LibG_231 for compatibility).
• src/Config/CS_SDK.props:11 carries <LIBGVer>libg_232_0_0</LIBGVer> used by CI to resolve the preferred LibG folder.
• The documented contract (doc/distrib/NodeHelpFiles/en-US/Autodesk.DesignScript.Geometry.Curve.HorizontalFrameAtParameter.md:2): Z-axis = world Z, Y-axis = curve tangent, X-axis = cross-product completion. The bug: for circles the Y-axis (tangent) is never applied, every frame is identity.
• doc/distrib/xml/en-US/ProtoGeometry.XML:1029-1036 — XML summary is misleadingly vague: "axis-aligned CoordinateSystem at the point" — could be read as describing the buggy output.
• The sample .dyn (doc/distrib/NodeHelpFiles/en-US/Autodesk.DesignScript.Geometry.Curve.HorizontalFrameAtParameter.dyn) uses a NurbsCurve.ByControlPoints with random 3D points, not a circle — so the bug is invisible in the current documentation example.
• No test/core/GeometrySanityCheck/Curve.HorizontalFrameAtParameter*.dyn exists — there is no regression guard for this node.

Desired End State

After this plan is complete:

1. Curve.HorizontalFrameAtParameter on a circle produces 32 coordinate systems with distinct Y-axes (tangent direction rotating around the circle) and constant Z-axes (world up). Verifiable with the DesignScript snippet: crv = Circle.ByCenterPointRadius(Point.Origin(),10); coords = crv.HorizontalFrameAtParameter(0..1..#32);
2. The LibG version referenced in src/DynamoCore/DynamoCore.csproj:35-37 is updated to the patched build.
3. doc/distrib/xml/en-US/ProtoGeometry.XML:1029-1036 clearly describes the axis contract (Z=worldZ, Y=tangent) matching the Markdown documentation.
4. The sample .dyn and preview image in doc/distrib/NodeHelpFiles/en-US/ use a circle as the input curve, showing rotating frames.
5. test/core/GeometrySanityCheck/Curve.HorizontalFrameAtParameter.Circle.dyn exists as a regression sanity-check graph for this node.

What We're NOT Doing

• Implementing a Dynamo-side wrapper or monkey-patch for HorizontalFrameAtParameter. No precedent exists for overriding ProtoGeometry methods in this codebase, and it would create a divergent maintenance burden.
• Updating the 13 non-English localized ProtoGeometry.XML variants — only doc/distrib/xml/en-US/ProtoGeometry.XML exists in-repo; the localized XMLs ship from the LibG NuGet package and are not editable here.
• Updating the 14 localized .md files under doc/distrib/NodeHelpFiles/<locale>/ — localized documentation changes are out of scope for a bug fix.
• Changing any node behavior, ports, search tags, icons, or resx files.

Implementation Approach

This is a three-phase effort: (1) do all in-repo pre-work that is independent of the upstream fix; (2) wait for LibG to ship a patched build; (3) land the version bump + sample graph update in a single Dynamo PR.

---

IMPORTANT: Checkboxes are for implementation steps only. Steps requiring manual human verification (browser testing, manual QA, visual inspection, staging verification, human review) MUST NOT be checkboxes — place them in the numbered "Manual Testing Steps" section at the bottom of the plan instead.

---

TASK 1: Fix the Bug Upstream in LibG [HIGH PRIORITY]

Status: DONE
Milestone: A patched ProtoGeometry.dll NuGet package (e.g. DynamoVisualProgramming.LibG_232_0_0 at a version higher than 4.0.0.4841) is available that correctly computes the Y-axis (tangent) for HorizontalFrameAtParameter on circles and other horizontal-plane curves.

• File or locate an existing bug report in the LibG/ASM upstream repository describing the HorizontalFrameAtParameter circle regression (axes collapsing to identity for horizontal-plane curves).
• Add a cross-reference comment on this GitHub issue (Curve.HorizontalFrameAtParameter bug #17105) linking to the upstream LibG ticket, so downstream tracking is clear.
• Confirm with the LibG team whether the root cause is (a) a circle-specific special-case that bypasses tangent evaluation, or (b) an orthonormalization collapse in the (tangent × worldZ) step for any horizontal-plane curve — document the finding in the upstream ticket.
• Verify the fix covers the broader case: test HorizontalFrameAtParameter on a flat NurbsCurve lying in the world XY plane in addition to a circle.

Validation: crv = Circle.ByCenterPointRadius(Point.Origin(),10); coords = crv.HorizontalFrameAtParameter(0..0.75..#4); produces 4 coordinate systems whose Y axes are distinct (approximately [1,0,0], [0,1,0], [-1,0,0], [0,-1,0]) and whose Z axes are all [0,0,1].

Requirements from spec:

• Z-axis of each returned CoordinateSystem must equal world Z (0,0,1).
• Y-axis of each returned CoordinateSystem must equal the curve tangent at the given parameter.
• X-axis must be the cross-product completion (perpendicular to both Y and Z).

Files to Modify:

• (External — LibG repository, not this repo)

---

TASK 2: Update ProtoGeometry.XML Documentation [LOW PRIORITY]

Status: DONE
Milestone: The in-repo XML summary for HorizontalFrameAtParameter accurately describes the axis contract and cannot be mistaken for the buggy (identity) behavior. This task is independent of the upstream fix and can land before it.

• Open doc/distrib/xml/en-US/ProtoGeometry.XML at lines 1029–1036.
• Replace the vague <summary> text ("Get a CoordinateSystem with origin at the point at the given parameter") and <returns> text ("The axis-aligned CoordinateSystem at the point") with precise descriptions matching the Markdown contract: summary should state the method returns a CoordinateSystem with Z-axis aligned to world Z and Y-axis aligned to the curve tangent at the parameter; <returns> should read "CoordinateSystem with ZAxis = world Z, YAxis = curve tangent at param".
• Verify the updated XML is well-formed (no unclosed tags, valid XML entities).

Validation: grep -A 10 "HorizontalFrameAtParameter" doc/distrib/xml/en-US/ProtoGeometry.XML shows the updated summary mentioning "world Z" and "tangent".

Requirements from spec:

• XML summary must not describe the output in terms that could be read as "axis-aligned" in the world sense (which is what the bug produces).
• Must match the contractual description in the corresponding .md file.

Files to Modify:

• doc/distrib/xml/en-US/ProtoGeometry.XML — update <summary> and <returns> within the M:Autodesk.DesignScript.Geometry.Curve.HorizontalFrameAtParameter(System.Double) member element (lines 1029–1036).

---

TASK 3: Bump LibG NuGet Package Version [HIGH PRIORITY — depends on TASK 1]

Status: DONE
Milestone: src/DynamoCore/DynamoCore.csproj references the patched LibG version, and a local Dynamo build uses the corrected ProtoGeometry.dll.

• Obtain the patched LibG NuGet package version string from the upstream team (e.g., 4.0.0.XXXX or 4.1.0.XXXX).
• In src/DynamoCore/DynamoCore.csproj:35, update Version="4.0.0.4841" on DynamoVisualProgramming.LibG_231_0_0 to the patched version.
• In src/DynamoCore/DynamoCore.csproj:36, update Version="4.0.0.4841" on DynamoVisualProgramming.LibG_232_0_0 to the patched version.
• In src/DynamoCore/DynamoCore.csproj:37, update Version="4.0.0.4841" on DynamoVisualProgramming.LibG_232_0_0_debug to the patched version.
• If the LibG major version changed (e.g., libg_232_0_0 → libg_233_0_0): update <LIBGVer> in src/Config/CS_SDK.props:11 and rename/update any PackageReference Include= identifiers in DynamoCore.csproj:35-37 to match the new package name.
• Run dotnet restore src/DynamoCore.sln (or Dynamo.All.sln) to confirm the new package resolves without errors.
• Run dotnet build src/DynamoCore.sln -c Release to confirm the build succeeds with the updated LibG.

Validation: dotnet build src/DynamoCore.sln -c Release exits with code 0. Running Curve.HorizontalFrameAtParameter on a circle in Dynamo Sandbox produces rotating Y-axis frames.

Requirements from spec:

• All three LibG package references (Release, Debug, LibG_231 compat) must be bumped consistently.
• CI config (CS_SDK.props) must stay in sync with the package name used.

Files to Modify:

• src/DynamoCore/DynamoCore.csproj — lines 35–37, bump Version attribute on all three LibG PackageReference elements.
• src/Config/CS_SDK.props — line 11, update <LIBGVer> only if the LibG major package name changes.

---

TASK 4: Update Sample Documentation Graph and Preview Image [MEDIUM PRIORITY — depends on TASK 1]

Status: DONE
Milestone: The node help sample for HorizontalFrameAtParameter uses a circle as the input curve, demonstrating the correct rotating-frame behavior, with an updated preview image.

• Open doc/distrib/NodeHelpFiles/en-US/Autodesk.DesignScript.Geometry.Curve.HorizontalFrameAtParameter.dyn.
• Replace the current graph (NurbsCurve from random points + single slider) with a graph that: creates Circle.ByCenterPointRadius(Point.Origin(), 10) via a Code Block, feeds it into Curve.HorizontalFrameAtParameter with a range input 0..1..#8 (or a Number Slider 0–1), and outputs the resulting CoordinateSystems.
• Keep the Number Slider as the published input (so the example stays interactive in the docs viewer).
• Save the updated .dyn in the same JSON format (schema version matching other recent NodeHelpFiles .dyn files).
• Regenerate doc/distrib/NodeHelpFiles/en-US/Autodesk.DesignScript.Geometry.Curve.HorizontalFrameAtParameter_img.jpg by running the updated .dyn in Dynamo with the patched LibG, capturing a background-preview screenshot showing the 8 rotating frames on the circle, and saving it as the replacement JPG.

Validation: Opening the updated .dyn in Dynamo Sandbox (with patched LibG) shows 8 CoordinateSystems evenly spaced on a circle, each with a distinct Y-axis direction tangent to the circle, and a consistent Z-axis pointing up.

Requirements from spec:

• Sample must demonstrate the correct contract: rotating Y-axis (tangent), constant Z-axis (world up).
• Preview image must show correct output (not the buggy identity frames).

Files to Modify:

• doc/distrib/NodeHelpFiles/en-US/Autodesk.DesignScript.Geometry.Curve.HorizontalFrameAtParameter.dyn — replace NurbsCurve graph with circle-based graph.
• doc/distrib/NodeHelpFiles/en-US/Autodesk.DesignScript.Geometry.Curve.HorizontalFrameAtParameter_img.jpg — replace with new preview image captured from the updated graph.

---

TASK 5: Add Regression Sanity-Check Graph [MEDIUM PRIORITY]

Status: DONE
Milestone: test/core/GeometrySanityCheck/Curve.HorizontalFrameAtParameter.Circle.dyn exists and, when run against a patched LibG build, produces CoordinateSystem outputs whose Y-axis components are distinct across the sampled parameters — preventing silent regression.

• Create test/core/GeometrySanityCheck/Curve.HorizontalFrameAtParameter.Circle.dyn as an XML Workspace .dyn file matching the format of neighboring sanity check graphs (e.g., Curve.PlaneAtDistance.Simple.dyn).
• The graph should: define a Circle.ByCenterPointRadius(Point.Origin(), 10) via a Code Block, sample HorizontalFrameAtParameter at parameters {0, 0.25, 0.5, 0.75}, extract the YAxis of each returned CoordinateSystem, and feed all 4 Y-axis vectors into Watch nodes.
• Add CoordinateSystem.YAxis and CoordinateSystem.Origin extraction nodes so the output is inspectable/verifiable by a test runner.
• Set RunType="Manual" and HasRunWithoutCrash="False" as initial state (matching the convention in sibling sanity-check files).
• The graph must reference ProtoGeometry.dll in its NamespaceResolutionMap for Circle and CoordinateSystem.

Validation: Running the .dyn in Dynamo with the patched LibG produces 4 Vector outputs for the Y-axes: approximately (1,0,0), (0,1,0), (-1,0,0), (0,-1,0) (or their negatives, depending on circle orientation convention). None should be (0,0,1) or (1,0,0) for all four (which would indicate the regression is back).

Requirements from spec:

• Must use Circle.ByCenterPointRadius as the test curve (the exact reproducer from the bug report).
• Must sample at 4 distinct parameters to verify the Y-axis rotates.

Files to Create:

• test/core/GeometrySanityCheck/Curve.HorizontalFrameAtParameter.Circle.dyn — new XML Workspace sanity-check graph.

---

Testing Strategy

Unit Tests:

• No new NUnit tests are required: the implementation lives in ProtoGeometry.dll, not in testable C# in this repo.
• The sanity-check .dyn in TASK 5 serves as the behavioral regression guard.

Integration Tests:

• Run test/core/GeometrySanityCheck/Curve.HorizontalFrameAtParameter.Circle.dyn in Dynamo Sandbox after the version bump (TASK 3) to confirm correct frame outputs.
• Run the existing geometry sanity-check suite (test/core/GeometrySanityCheck/) to confirm no regressions in neighboring Curve frame methods (Curve.PlaneAtDistance, Curve.PlaneAtEqualArcLength, CoordinateSystem.AtParameter).

Manual Testing Steps:

1. Open Dynamo Sandbox with the patched LibG build and run: crv = Circle.ByCenterPointRadius(Point.Origin(),10); coords = crv.HorizontalFrameAtParameter(0..1..#32); — verify 32 coordinate-system glyphs visible in the background preview, each rotated tangentially around the circle, Z-axes all pointing up.
2. Verify the same script on a flat NurbsCurve.ByPoints lying in the world XY plane produces analogous rotating-frame output (regression check for the broader horizontal-plane curve case).
3. Verify CoordinateSystemAtParameter (sibling method) still produces its own distinct output (XAxis = normal, ZAxis = binormal) — confirm no cross-contamination from the fix.
4. Open the updated sample .dyn (TASK 4) in Dynamo Sandbox and confirm the circle-based graph runs without errors and the background preview matches the new _img.jpg.

Performance Considerations

None. This is a bug fix in a geometry evaluation method — there are no new allocations, loops, or data structures introduced in this repo. The version bump consumes the same NuGet restore path as the current build.

[Copilot]

Pull request overview

This PR attempts to address issue #17105 (Curve.HorizontalFrameAtParameter returning identity-rotated frames for circles). Because the buggy implementation lives in the closed-source ProtoGeometry.dll shipped via the DynamoVisualProgramming.LibG_232_0_0 NuGet package, the in-repo work here is limited to documentation clarifications and a regression sanity-check graph. The actual upstream LibG fix and the corresponding NuGet version bump (Task 3 in the PR description) were explicitly skipped, so the runtime behavior is unchanged by this PR.

Changes:

• Tighten the in-repo XML and node-help descriptions to spell out the axis contract (ZAxis = world Z, YAxis = curve tangent).
• Replace the NurbsCurve-from-random-points sample in the node help with a Circle.ByCenterPointRadius graph (the exact bug reproducer) and reset the camera view.
• Add a new geometry sanity-check .dyn exercising HorizontalFrameAtParameter against a circle at four parameters.

Reviewed changes

Copilot reviewed 2 out of 3 changed files in this pull request and generated 3 comments.

File	Description
doc/distrib/xml/en-US/ProtoGeometry.XML	Rewords <summary>/<returns> for HorizontalFrameAtParameter to describe the documented Z=worldZ, Y=tangent contract.
doc/distrib/NodeHelpFiles/en-US/Autodesk.DesignScript.Geometry.Curve.HorizontalFrameAtParameter.dyn	Replaces the sample graph with a circle-based example, adds Circle/Point namespace resolutions, and rewrites the node description text.
test/core/GeometrySanityCheck/Curve.HorizontalFrameAtParameter.Circle.dyn	New manual sanity-check graph sampling Y/Z/Origin from HorizontalFrameAtParameter on a circle at four parameters.

Files not reviewed (1)

• doc/distrib/xml/en-US/ProtoGeometry.XML: Language not supported

Comments suppressed due to low confidence (1)

test/core/GeometrySanityCheck/Curve.HorizontalFrameAtParameter.Circle.dyn:35

• Using fixed, sequential placeholder GUIDs such as 11111111-1111-1111-1111-111111111111 for node identifiers is not consistent with the rest of test/core/GeometrySanityCheck/, where every node uses a real random GUID (see neighbors like Curve.PlaneAtDistance.Simple.dyn). While Dynamo will load these patterned GUIDs, having them in a shared test asset increases the risk of collision with other graphs and makes it harder to grep/diff against real graphs. Regenerate the file from Dynamo to get proper random GUIDs.

    <Dynamo.Graph.Nodes.CodeBlockNodeModel guid="11111111-1111-1111-1111-111111111111" type="Dynamo.Graph.Nodes.CodeBlockNodeModel" nickname="Code Block" x="100" y="200" isVisible="true" isUpstreamVisible="true" lacing="Disabled" isSelectedInput="False" IsFrozen="false" isPinned="false" CodeText="center      = Point.ByCoordinates(0, 0, 0);&#xA;radius      = 10;&#xA;circle      = Circle.ByCenterPointRadius(center, radius);&#xA;parameters  = [0.0, 0.25, 0.5, 0.75];" ShouldFocus="false">
      <OutPortInfo LineIndex="0" />
      <OutPortInfo LineIndex="1" />
      <OutPortInfo LineIndex="2" />
      <OutPortInfo LineIndex="3" />
    </Dynamo.Graph.Nodes.CodeBlockNodeModel>
    <Dynamo.Graph.Nodes.ZeroTouch.DSFunction guid="22222222-2222-2222-2222-222222222222" type="Dynamo.Graph.Nodes.ZeroTouch.DSFunction" nickname="Curve.HorizontalFrameAtParameter" x="500" y="280" isVisible="true" isUpstreamVisible="true" lacing="Auto" isSelectedInput="False" IsFrozen="false" isPinned="false" assembly="ProtoGeometry.dll" function="Autodesk.DesignScript.Geometry.Curve.HorizontalFrameAtParameter@double">
      <PortInfo index="0" default="False" />
      <PortInfo index="1" default="False" />
    </Dynamo.Graph.Nodes.ZeroTouch.DSFunction>
    <Dynamo.Graph.Nodes.ZeroTouch.DSFunction guid="33333333-3333-3333-3333-333333333333" type="Dynamo.Graph.Nodes.ZeroTouch.DSFunction" nickname="CoordinateSystem.YAxis" x="850" y="220" isVisible="true" isUpstreamVisible="true" lacing="Auto" isSelectedInput="False" IsFrozen="false" isPinned="false" assembly="ProtoGeometry.dll" function="Autodesk.DesignScript.Geometry.CoordinateSystem.YAxis">
      <PortInfo index="0" default="False" />
    </Dynamo.Graph.Nodes.ZeroTouch.DSFunction>
    <Dynamo.Graph.Nodes.ZeroTouch.DSFunction guid="44444444-4444-4444-4444-444444444444" type="Dynamo.Graph.Nodes.ZeroTouch.DSFunction" nickname="CoordinateSystem.ZAxis" x="850" y="360" isVisible="true" isUpstreamVisible="true" lacing="Auto" isSelectedInput="False" IsFrozen="false" isPinned="false" assembly="ProtoGeometry.dll" function="Autodesk.DesignScript.Geometry.CoordinateSystem.ZAxis">
      <PortInfo index="0" default="False" />
    </Dynamo.Graph.Nodes.ZeroTouch.DSFunction>
    <Dynamo.Graph.Nodes.ZeroTouch.DSFunction guid="55555555-5555-5555-5555-555555555555" type="Dynamo.Graph.Nodes.ZeroTouch.DSFunction" nickname="CoordinateSystem.Origin" x="850" y="500" isVisible="true" isUpstreamVisible="true" lacing="Auto" isSelectedInput="False" IsFrozen="false" isPinned="false" assembly="ProtoGeometry.dll" function="Autodesk.DesignScript.Geometry.CoordinateSystem.Origin">
      <PortInfo index="0" default="False" />
    </Dynamo.Graph.Nodes.ZeroTouch.DSFunction>
    <CoreNodeModels.Watch guid="66666666-6666-6666-6666-666666666666" type="CoreNodeModels.Watch" nickname="Watch YAxis" x="1200" y="220" isVisible="true" isUpstreamVisible="true" lacing="Disabled" isSelectedInput="False" IsFrozen="false" isPinned="false">
      <PortInfo index="0" default="False" />
    </CoreNodeModels.Watch>
    <CoreNodeModels.Watch guid="77777777-7777-7777-7777-777777777777" type="CoreNodeModels.Watch" nickname="Watch ZAxis" x="1200" y="360" isVisible="true" isUpstreamVisible="true" lacing="Disabled" isSelectedInput="False" IsFrozen="false" isPinned="false">
      <PortInfo index="0" default="False" />
    </CoreNodeModels.Watch>
    <CoreNodeModels.Watch guid="88888888-8888-8888-8888-888888888888" type="CoreNodeModels.Watch" nickname="Watch Origin" x="1200" y="500" isVisible="true" isUpstreamVisible="true" lacing="Disabled" isSelectedInput="False" IsFrozen="false" isPinned="false">
      <PortInfo index="0" default="False" />
    </CoreNodeModels.Watch>

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud