NetFabric/NetFabric.Numerics / .agents/skills/coordinate-system-conversions
coordinate-system-conversions
VerifiedAbstract math for converting between 2D and 3D coordinate systems. USE FOR: Cartesian to/from polar (r, θ); Cartesian to/from spherical (r, azimuth, polar/colatitude); azimuth vs. elevation vs. colatitude conventions; canonical range enforcement after conversion; precision near the origin and poles; choosing azimuth reference direction. DO NOT USE FOR: angle unit conversions (use angles-and-circular-arithmetic); geodetic (lat/lon) coordinates (use geodetic-coordinate-bounds); rotation representations (use 3d-rotation-theory).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.5 KB |
| references/formulas.md | markdown | 2.1 KB |
| references/numerical-stability.md | markdown | 1.9 KB |
references/numerical-stability.md
View on GitHub# Coordinate System Conversions — Numerical Stability
## Near-Origin (r → 0)
When x ≈ 0 and y ≈ 0:
- `r = √(x²+y²)` underflows to 0 for subnormal inputs
- `θ = arccos(z/r)` → division by zero → NaN
- `φ = atan2(y, x)` at (0, 0) is implementation-defined (typically 0 or platform-specific)
Guard: check `r > ε` before computing angles. Return zero-angle representation for origin.
## Near-Pole (θ → 0 or θ → π)
Near the poles, `sin θ ≈ 0`, making the azimuth φ unreliable:
- `x = r sin θ cos φ ≈ 0`, `y = r sin θ sin φ ≈ 0` regardless of φ
- Converting back: `φ = atan2(y, x)` ≈ `atan2(0, 0)` — undefined
This is the coordinate singularity of spherical coordinates.
Round-trip through poles does NOT preserve azimuth.
## arccos Argument for Polar Angle
`θ = arccos(z/r)`: the ratio `z/r` can exceed [−1, 1] due to rounding, especially when z ≈ r:
```csharp
double polar = Math.Acos(Math.Clamp(z / r, -1.0, 1.0));
```
## atan2 Precision Near Axes
`atan2(y, x)` near the +x axis (y ≈ 0, x > 0) returns values near 0 accurately.
Near the −x axis (y ≈ 0, x < 0), the result is near ±π; small perturbations in y cause
the sign to flip. This is a genuine discontinuity in the canonical range (−π, π] at the −x axis.
For [0, 2π) canonical range, the discontinuity moves to the +x axis (0 and 2π boundary).
## Squared Radius Overflow
`x²+y²+z²` overflows for components near float.MaxValue / √3.
Scale by `max(|x|, |y|, |z|)` first, then scale the radius back.
## Polar → Cartesian Precision for Small θ
`x = r sin θ cos φ` when θ ≈ 0: `sin θ ≈ θ` — use Taylor approximation `sin θ ≈ θ − θ³/6` for θ < 1e-4 to avoid `sin` precision loss.
## IEEE 754 Sign of Zero
`atan2(−0.0, −1.0) = −π` but `atan2(+0.0, −1.0) = +π`.
When computing angles from exact-zero coordinates, the sign of zero matters.
Normalize −0.0 to 0.0 when canonicalizing.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |