Cartesian To Spherical — Robotics/Coordinate Transforms

Robotics/Coordinate_Transforms/Cartesian_To_Spherical · 3 input / 3 output port(s) at insert · exports to Python, MATLAB, Java, Rust, C, C++, VHDL, Verilog, SystemVerilog, PLC Structured Text

Description#

The block's own DESCRIPTION_HTML, rendered verbatim — the same text the config dialog's info panel and the library navigator show. Fix a wrong sentence in the block's .cpp (R-D9), never here.

Cartesian To Spherical

Robotics / Coordinate Transforms

Converts a 3-D Cartesian point to spherical form, entry by entry:

r = √(x² + y² + z²), θ = atan2(y, x), φ = atan2(√(x² + y²), z)

θ is the azimuth in (−π, π] and φ is the inclination measured from the +Z axis in [0, π].

Ports

x, y, z – the Cartesian components, any size [m,n]. All three must be the same size; they are paired entry by entry and none is broadcast.
r – the radius, never negative.
theta – the azimuth, the angle of the point's shadow on the XY plane, measured from +X.
phi – the inclination, measured down from +Z. A point on +Z has φ = 0; a point in the XY plane has φ = π/2.

Parameters

Sampling Time (s) – zero or less inherits the solver's rate; a positive value runs the block at that period.

Code export

All ten targets: Python, MATLAB, Java, Rust, C, C++, VHDL, Verilog, SystemVerilog and PLC Structured Text. There is no tunable parameter, because the block has none.

The three HDL targets are simulation-only: a square root and two four-quadrant arctangents have no Q16.16 form to call.

PLC Structured Text has no ATAN2 in IEC 61131-3, so both angles are rebuilt from ATAN with the quadrant reconstruction. φ gets the shorter form of it, because its first argument is a square root and therefore never negative.

Simulink bridge

Both directions, onto simulink_extras/Transformations/Cartesian to Spherical. That block has no dialog parameters whatsoever (verified with get_param(blk, 'DialogParameters'), which comes back empty), so the bridge is the library path alone. It also has no SampleTime parameter, so Sampling Time (s) does not cross.

Notes

Algebraic and stateless; nonlinear, and deliberately carries no state space.
φ is the INCLINATION FROM +Z, not the elevation from the XY plane. The two differ by π/2, and this one is measured against the Simulink block rather than assumed. If you want elevation, subtract φ from π/2.
The naming is the block's own, and it is not the physics convention. Here θ is the azimuth and φ the polar angle; ISO 80000-2 uses those two letters the other way round. The port names follow Simulink's.
At the origin all three outputs are zero. θ and φ are of course undefined there in mathematics; zero is the shared convention, and it is what the Simulink block, C and MATLAB all produce.
The inverse is Spherical To Cartesian, and the pair round-trips exactly – measured at 4.4e-16 over the probe table.

Code facts#

Fact	Value
registered type	`Robotics/Coordinate_Transforms/Cartesian_To_Spherical`
family	`Robotics/Coordinate_Transforms`
solver environment class	`ICoreBlock_0_Robotics_1_Coordinate_Transforms_2_Cartesian_To_Spherical`
source	`src/ICoreSDK/ICoreBlockLibrary/Blocks/Robotics/Coordinate_Transforms/Cartesian_To_Spherical/ICoreBlock_0_Robotics_1_Coordinate_Transforms_2_Cartesian_To_Spherical.cpp`
header	`src/ICoreSDK/ICoreBlockLibrary/Blocks/Robotics/Coordinate_Transforms/Cartesian_To_Spherical/ICoreBlock_0_Robotics_1_Coordinate_Transforms_2_Cartesian_To_Spherical.h`
default size on canvas	132 × 96 px
ports at insert	3 in, 3 out
code generators implemented	`Python`, `MATLAB`, `Java`, `Rust`, `C`, `C++`, `VHDL`, `Verilog`, `SystemVerilog`, `PLC Structured Text`

Ports#

#	Direction	Signal type	Description label
1	in	`ICoreDouble`	x
2	in	`ICoreDouble`	y
3	in	`ICoreDouble`	z
4	out	`ICoreDouble`	r
5	out	`ICoreDouble`	theta
6	out	`ICoreDouble`	phi

Ports the constructor creates. A block whose port list changes with its configuration adds or removes ports at load time; the count above is the one a freshly inserted block has.

Configuration variables#

No config variable beyond the Sampling Time (s) every block carries.

Every block also carries Sampling Time (s) from ICoreBlockSolverEnvironment: zero or less inherits the solver's rate, a positive value runs the block at that period.

Simulink bridge#


support	`Support::Both`
Simulink path	`simulink_extras/Transformations/Cartesian to Spherical`
port-count rule	`PortsParam::None`
`SampleTime` parameter	no — the counterpart defines none; the rate stays on the ICore side

Caveat (shown to the user): the Simulink block has no dialog parameters at all, so nothing but the block itself crosses; it also defines no SampleTime, so "Sampling Time (s)" does not cross and the block runs at the surrounding Simulink rate

Catalog contract: src/ICoreSDK/ICoreCoder/ICoreCommandSystem/SimulinkBridge/ICoreSimulinkBlockCatalog.h

Description vs code#

The checker has a blind spot here — it could not resolve something (a grouped port bullet, a computed config name), which is reported and never counted as a pass. A reader has to settle it:

B0 Ports lists 4 entries for 6 ports (3 in, 3 out) — grouped, or one undocumented? a reader must say

The verdict above is tools/docs/check_block_descriptions.py (P7.1), which compares LISTS. It cannot read a sentence: "stateless" on a block with a state, an initial-value semantic the recursion does not implement, a "not synthesizable" caveat the HDL banner contradicts. That is the agent audit (P7.3) on BLOCK_DESCRIPTION_AUDIT.md, and this tool's green is not a substitute for one.

The top comment of the block's .cpp — the maths, the realization and the export strategy, addressed to whoever changes it. It must not contradict the description above (P7.5).

Cartesian To Spherical — the 3-D transform, elementwise r = sqrt(x^2 + y^2 + z^2) theta = atan2(y, x) AZIMUTH, (-pi, pi] phi = atan2(sqrt(x^2 + y^2), z) INCLINATION from +Z, [0, pi]

The convention was the open question on this block's board row and is now MEASURED with a 12-point probe: phi is the inclination from +Z, NOT the elevation from the XY plane (the elevation hypothesis is out by up to 4.71 rad), the azimuth is called theta and the polar angle phi -- the opposite of the ISO 80000-2 physics naming -- and the output order is (r, theta, phi). See the header.

⚠ phi IS atan2(hyp, z), NOT acos(z/r). Same value wherever r > 0, but the atan2 form is TOTAL -- no division, no domain clamp, and atan2(0,0) = 0 reproduces the block's measured phi at the origin for free. Verified against all twelve probe points.

Sample results#

t	in ICoreDouble-Out-0	in ICoreDouble-Out-0	in ICoreDouble-Out-0	out ICoreDouble-Out-0	out ICoreDouble-Out-1	out ICoreDouble-Out-2
0	-2	-2	-2	3.464	-2.356	2.186
0.4	0.5	0.5	0.5	0.866	0.7854	0.9553
0.8	-2	-2	-2	3.464	-2.356	2.186
1.2	0.5	0.5	0.5	0.866	0.7854	0.9553
1.6	-2	-2	-2	3.464	-2.356	2.186
2	0.5	0.5	0.5	0.866	0.7854	0.9553
2.4	-2	-2	-2	3.464	-2.356	2.186
2.8	0.5	0.5	0.5	0.866	0.7854	0.9553
3.2	-2	-2	-2	3.464	-2.356	2.186
3.6	0.5	0.5	0.5	0.866	0.7854	0.9553
4	-2	-2	-2	3.464	-2.356	2.186
4.4	0.5	0.5	0.5	0.866	0.7854	0.9553
4.8	-2	-2	-2	3.464	-2.356	2.186
5.2	0.5	0.5	0.5	0.866	0.7854	0.9553

Every 4th of 60 samples, from the table stimulus.

The same rig also ran:

Stimulus	What it is	Output range
`impulse`	Impulse: one sample of 1 at k = 5, 0 elsewhere (Repeating Sequence Stair)	0 … 1.732
`ramp`	Ramp: slope 1 from t = 0	0 … 10.05
`sine`	Sine Wave: amplitude 1, 2 rad/s, no phase, no bias	0 … 1.732
`step`	Step: 0 -> 1 at t = 1 s	0 … 1.732

Plotted: table — Repeating Sequence Stair: [-2 -1 -0.5 0 0.5 1 2 3], one entry per sample

Category static · sample time 0.1 · 60 steps · commit ccf005c8 · produced by docsSample --out <folder> --steps 60 · data docs/generated/samples/Robotics__Coordinate_Transforms__Cartesian_To_Spherical.json · the SVG is generated from those numbers by tools/docs/plot_svg.py, so it is a run and not a drawing (R-D10).

Cartesian To Spherical — Robotics/Coordinate Transforms

Description#