[1-Bort-1]

KiteGeometry had its own calc_heading(R_b_to_w, pos), a second function under the same name as the calc_heading(attitude, elevation, azimuth) KiteUtils exports. Loading both packages, as every KiteViewers user does, made the name ambiguous, and the two computed the same angle. KiteGeometry now uses KiteUtils' function to turn a kite to its heading when it places a system, and no longer defines or exports one of its own. using KiteUtils, KiteGeometry then gives one unambiguous calc_heading.

calc_heading(R_b_to_w, pos)                                   # before, KiteGeometry
-calc_heading(R_b_to_w, elevation, azimuth; respos=false)     # after, KiteUtils

This removes public API, so the changelog marks it BREAKING. A caller of the two-argument form passes the elevation and azimuth instead; the minus sign is because KiteUtils' heading turns the other way to KiteGeometry's.

A transform's heading keeps the sense it had, so every authoring document places the kite exactly where it did before. Making it turn the way KiteUtils' heading does would change every document's input; that is the owner's call, in the same spirit as the azimuth convention question on OpenSourceAWE/SymbolicAWEModels.jl#430.

This works with KiteUtils 0.13 and 0.14 alike: it passes the azimuth as an angle rather than calling azimuth_east, whose sign changed in 0.14.

This merges in either order with #86, which turns a transform's azimuth the other way: placement reads the east-to-north azimuth KiteUtils wants off the direction the transform turns its object to, rather than negating the transform's azimuth. No follow-up is needed whichever lands second. I chose this over stacking on #86, which would have tied this change to a larger one for the sake of one sign.

KiteViewers can now drop its line that disambiguates calc_heading; that change is KiteViewers'.

Verification

• Reproduced first: n/a, refactor. On six random rotations and positions, KiteUtils' heading was exactly the negative of KiteGeometry's.
• This branch: test-transforms.jl 27/27, test-structure.jl 172/172, test-authoring.jl 655/655.
• Merged with Let a tool build its segments and tethers on KiteGeometry's own definitions, and turn azimuth anti-clockwise #86: test-transforms.jl red with the azimuth negated (kite heading 0.930 rad where 0.436 is wanted), 30/30 with this change; test-authoring.jl and test-structure.jl pass.
• Reading the azimuth without the elevation correction fails the new zenith test (frames 2.83 apart across 90°, under 0.01 required).
• Local full suite (Julia 1.13.0): running · GitHub CI: pending
• Docs: only a test and one line of placement changed since CI last built them · REUSE lint: not run, reuse is not installed on the box · merges cleanly with main
• Benchmark: n/a
• Risk: code outside this repo that calls KiteGeometry.calc_heading(R, pos) breaks; within the ecosystem I know only the KiteViewers line named above.

Opened by 1-Bort-1, an AI agent working for @1-Bart-1.
Closes #70 · task KiteGeometry.jl-70
Refs OpenSourceAWE/KiteViewers.jl#57

[1-Bort-1]

Independent review (advisory)

Verdict: APPROVE WITH COMMENTS · 1 inline, 0 off the diff

Good

• src/transforms.jl:120 adds the method to KiteUtils.calc_heading instead of defining a second function, so both packages share one name; this is the single-codepath fix §2 asks for and matches the card
• src/KiteGeometry.jl:18 imports calc_heading from KiteUtils, so the existing export now re-exports the same binding; the card says this and the export list is unchanged
• The internal caller at src/transforms.jl:206 still works unqualified through the imported binding; I checked this with grep
• docs/src/structure.md:71 points the @docs entry at the two-argument signature, so the page shows only KiteGeometry's docstring and not KiteUtils' whole function; the card says the docs build clean
• CHANGELOG entry is one compact line under Fixed, describes the change users will see, and is not hard-wrapped
• The diff is small and has one idea; nothing changed that the card does not name

Not good

• test/test-transforms.jl:142 — The testset proves only that the two bindings are identical. It never calls both forms unqualified under using KiteUtils, KiteGeometry, so a dispatch collision such as a future two-argument KiteUtils method replacing this one would not be caught here. One call of each form in the probe would cover the risk the card itself names.
• The new method has untyped arguments on a function KiteGeometry does not own (type piracy by arity); the card names the risk, but a follow-up issue in KiteUtils to reserve or type the two-argument form would make it visible to people working on that package
• The test's Module() plus Core.eval probe is clever where @test KiteGeometry.calc_heading === KiteUtils.calc_heading would prove the same thing in plain code; identical bindings already rule out the ambiguity
• The card does not say what was searched before writing (§2 'say in the PR what you searched for'), e.g. other calc_heading callers in the ecosystem that rely on KiteGeometry's own function
• Full suite and CI are reported as not awaited or pending, so the merge depends on CI going green

_{claude, rubric CLEAN_CODE.md. A different lab from the implementer
on purpose: a reviewer sharing its blind spots would not flag its mistakes.}

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[1-Bart-1]

KiteUtils has a new release now, so why not directly use KiteUtils' function?

[1-Bart-1]

KG should not have duplicate/overlapping functions with KiteUtils. Use the KiteUtils functions

[1-Bart-1]

KU v0.14 (released now) has the other sign in this function, so you don't need the minus sign anymore, just pin KU to 0.14.

[1-Bort-1]

The minus signs stay: KiteUtils 0.14.0 didn't change calc_heading. Its code is the same in v0.13.1, v0.14.0 and main. What 0.14 flipped is azimuth_east (OpenSourceAWE/KiteUtils.jl#165), which KiteGeometry doesn't call. On KiteUtils 0.14.0, test/test-transforms.jl passes 26/26 as the branch stands. Dropping the leading minus fails 6 of 26: a placed kite reads -2.337 rad where 0.436 is expected. Dropping the minus on the azimuth argument fails the same 6. So #71 has nothing to change and keeps its KiteUtils bound; #79 already widens it to 0.14.