Skip to content

fix: clarify spherical coordinate naming in docstrings and variables#4678

Open
YizukiAme wants to merge 1 commit intoManimCommunity:mainfrom
YizukiAme:codex/fix-3123-spherical-docs
Open

fix: clarify spherical coordinate naming in docstrings and variables#4678
YizukiAme wants to merge 1 commit intoManimCommunity:mainfrom
YizukiAme:codex/fix-3123-spherical-docs

Conversation

@YizukiAme
Copy link
Copy Markdown

Overview

Fixes #3123.

The docstring for cartesian_to_spherical() previously described the return order as (distance, phi, theta), but the variable names phi and theta swap meaning between the math and physics conventions, making the documentation actively misleading.

This patch sidesteps the convention ambiguity entirely by replacing theta/phi with convention-neutral names: azimuthal_angle and polar_angle, following the approach suggested by @chopan050.

Changes

manim/utils/space_ops.py

  • cartesian_to_spherical(): Rewrote the docstring summary and added a Returns section (numpydoc format) that explicitly defines each angle geometrically. Renamed internal variables thetaazimuthal_angle, phipolar_angle.
  • spherical_to_cartesian(): Updated the parameter docstring from theta/phi to azimuthal_angle/polar_angle with clear definitions. Renamed the unpacking variables to match.

manim/mobject/geometry/arc.py

  • Updated two inline comments in position_tip() to use the same azimuthal angle / polar angle vocabulary for cross-file consistency.

tests/module/utils/test_space_ops.py

  • Renamed test_polar_coordstest_spherical_coords and used descriptive variable names (cartesian_point, spherical_point). No assertion values changed.

What did NOT change

  • Return order: still [r, azimuthal_angle, polar_angle] (same as the old [r, theta, phi]).
  • Math expressions: all trig calls are identical — this is a pure naming/docs patch.
  • Behavior: zero functional change. All existing callers (e.g., arc.py:position_tip()) access by index, not by name.

Verification

  • py_compile passes on all modified files.
  • Callers verified: arc.py:position_tip() uses angles[1] / angles[2] (index-based), unaffected by variable renames.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Confusing/Misleading docstring for cartesian_to_spherical

1 participant