Angle Wrap — Robotics/Coordinate Transforms
Robotics/Coordinate_Transforms/Angle_Wrap · 1 input / 1 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.
Angle Wrap
Robotics / Coordinate Transforms
Folds an angle into a principal interval, entry by entry, by adding or subtracting whole turns of 2π. The value is unchanged modulo 2π; only its representative changes.
Ports
- u – the angle in radians, any size [m,n]. Any magnitude: an accumulated heading of a hundred turns is fine.
- y – the same angle in the configured interval, the same size as the input.
Parameters
- Wrap Range – which principal interval to fold into:
- (-pi, pi] – the default, and the interval Cartesian To Polar produces. Owns +π: an input of exactly π comes out as +π, and so does −π.
- 0, 2*pi) – owns 0: both 0 and 2π come out as 0. The convention for a compass bearing.
- 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.
The three HDL targets are genuine synthesizable Q16.16, not
this family's simulation-only real: the wrap is one multiply, one
floor and one multiply-add. The floor is fx_to_int, which is an
arithmetic shift right and therefore floor() for negatives too, and
the division by 2π never appears – its reciprocal is folded to a
literal at export time, which is what keeps a divider out of the
datapath.
Simulink bridge
None, and that is measured rather than assumed: base Simulink and
simulink_extras carry no angle-wrap block. The wrap blocks live in
the Aerospace Blockset, which is not installed on this machine, so there
is nothing to map onto and nothing a parity testbench could compare against.
Not to be confused with Wrap To Zero, which zeroes a signal above
a threshold rather than folding it.
Notes
- Algebraic and stateless, and piecewise – so it carries no state space.
- This is the only block in the library that wraps. Poses and headings carry a raw, unwrapped angle everywhere else – Unicycle Odometry, Pose Transform 2D and Polar To Cartesian all leave θ alone – so a wrap is always visible in the diagram as this block.
- The endpoint is part of the contract. Every one of the ten backends computes the same interval and the same boundary value; a target that disagreed would differ only on the boundary sample, which is why the formula uses a floor rather than a language's own modulo (whose sign convention for negatives is not the same everywhere).
- The inverse is Angle Unwrap, which removes the 2π jumps this block introduces.
Code facts#
| Fact | Value |
|---|---|
| registered type | Robotics/Coordinate_Transforms/Angle_Wrap |
| family | Robotics/Coordinate_Transforms |
| solver environment class | ICoreBlock_0_Robotics_1_Coordinate_Transforms_2_Angle_Wrap |
| source | [src/ICoreSDK/ICoreBlockLibrary/Blocks/Robotics/Coordinate_Transforms/Angle_Wrap/ICoreBlock_0_Robotics_1_Coordinate_Transforms_2_Angle_Wrap.cpp |
| header | src/ICoreSDK/ICoreBlockLibrary/Blocks/Robotics/Coordinate_Transforms/Angle_Wrap/ICoreBlock_0_Robotics_1_Coordinate_Transforms_2_Angle_Wrap.h |
| default size on canvas | 118 × 72 px |
| ports at insert | 1 in, 1 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 | u |
| 2 | out | ICoreDouble | y |
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#
| Config variable | Default | Simulink parameter |
|---|---|---|
Wrap Range | (-pi, pi]%~%[0, 2*pi)~~(-pi, pi] | — |
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::None |
| Simulink path | — |
| port-count rule | PortsParam::None |
SampleTime parameter | yes |
Caveat (shown to the user): no Simulink equivalent on this installation: base Simulink and simulink_extras carry no angle-wrap block -- the wrap blocks belong to the Aerospace Blockset, which is not installed -- so there is nothing to map onto and nothing a parity testbench could compare against. Wrap To Zero is a different function: it zeroes above a threshold rather than folding by whole turns
Catalog contract: src/ICoreSDK/ICoreCoder/ICoreCommandSystem/SimulinkBridge/ICoreSimulinkBlockCatalog.h
Description vs code#
The lists agree. check_block_descriptions.py finds no disagreement between the description's Ports, Parameters, Code export and Simulink bridge lists and the code's.
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.
File banner (developer view)#
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).
Angle Wrap — fold an angle into a principal interval, elementwise (-pi, pi] y = u + 2*pi*floor((pi - u) / (2*pi)) [0, 2*pi) y = u - 2*pi*floor(u / (2*pi))
⚠ The (-pi, pi] mode owns +pi, deliberately: Cartesian_To_Polar was MEASURED to return +pi on the negative x-axis, and a wrap block that owned -pi instead would contradict the transform feeding it on exactly that sample. See the header -- this is NOT the formula the board row sketched, and the difference is the endpoint.
⚠ Written with floor() and a FOLDED RECIPROCAL rather than a modulo or a division, which is what keeps all three HDL targets genuine synthesizable Q16.16: fx_to_int is an arithmetic shift right, i.e. floor() for negatives too, and 1/(2*pi) is a literal baked at export.
Sample results#
| t | in ICoreDouble-Out-0 | out ICoreDouble-Out-0 |
|---|---|---|
| 0 | -2 | -2 |
| 0.4 | 0.5 | 0.5 |
| 0.8 | -2 | -2 |
| 1.2 | 0.5 | 0.5 |
| 1.6 | -2 | -2 |
| 2 | 0.5 | 0.5 |
| 2.4 | -2 | -2 |
| 2.8 | 0.5 | 0.5 |
| 3.2 | -2 | -2 |
| 3.6 | 0.5 | 0.5 |
| 4 | -2 | -2 |
| 4.4 | 0.5 | 0.5 |
| 4.8 | -2 | -2 |
| 5.2 | 0.5 | 0.5 |
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 |
ramp | Ramp: slope 1 from t = 0 | -3.083 … 3.1 |
sine | Sine Wave: amplitude 1, 2 rad/s, no phase, no bias | -1 … 0.9996 |
step | Step: 0 -> 1 at t = 1 s | 0 … 1 |
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__Angle_Wrap.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).