From 3e43e2bfe66d153df3a98b360a38f7ef30d9b8ab Mon Sep 17 00:00:00 2001 From: changsheng Date: Wed, 3 Jun 2026 09:48:05 +0800 Subject: [PATCH] Fix misleading docstring in cartesian_to_spherical (fixes #3123) The docstring for cartesian_to_spherical stated the return order as (distance, phi, theta) but the actual return was [r, theta, phi]. This updates both cartesian_to_spherical and spherical_to_cartesian docstrings to clearly document the return order as (r, theta, phi) and define each component: r = radius, theta = azimuthal angle in the xy-plane, phi = polar angle from the positive z-axis. --- manim/utils/space_ops.py | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/manim/utils/space_ops.py b/manim/utils/space_ops.py index 0aa57b93c6..4af2ad34d3 100644 --- a/manim/utils/space_ops.py +++ b/manim/utils/space_ops.py @@ -810,12 +810,22 @@ def earclip_triangulation(verts: np.ndarray, ring_ends: list) -> list: def cartesian_to_spherical(vec: Vector3DLike) -> np.ndarray: """Returns an array of numbers corresponding to each - polar coordinate value (distance, phi, theta). + spherical coordinate value ``(r, theta, phi)``. Parameters ---------- vec A numpy array or a sequence of floats ``[x, y, z]``. + + Returns + ------- + np.ndarray + An array ``[r, theta, phi]`` where: + + - ``r`` is the distance (radius) from the origin, + - ``theta`` is the azimuthal angle (angle in the xy-plane + from the positive x-axis), + - ``phi`` is the polar angle (angle from the positive z-axis). """ norm = np.linalg.norm(vec) if norm == 0: @@ -833,13 +843,12 @@ def spherical_to_cartesian(spherical: Sequence[float]) -> np.ndarray: Parameters ---------- spherical - A list of three floats that correspond to the following: - - r - The distance between the point and the origin. - - theta - The azimuthal angle of the point to the positive x-axis. + A sequence of three floats ``(r, theta, phi)`` where: - phi - The vertical angle of the point to the positive z-axis. + - ``r`` is the distance from the origin, + - ``theta`` is the azimuthal angle (angle in the xy-plane + from the positive x-axis), + - ``phi`` is the polar angle (angle from the positive z-axis). """ r, theta, phi = spherical return np.array(