RateLimiter3D

  7 minute read  

RateLimiter3D caps how fast a point in three dimensions may move. Each cycle it moves the output along a straight line toward the target, by no more than rateLimit per second.

It is the vector form of RateLimiter, and the difference matters. Limiting each axis’s rate separately makes a diagonal move bend — the axis that saturates first falls behind while the others carry on, so the path through space changes and not just its speed. Scaling the whole step keeps the point travelling in a straight line toward where it was told to go.

flowchart LR
    i1(["inputs — target point, three values"]) --> B["RateLimiter3D"]
    B --> o1(["outputs — rate-limited point, three values"])
    B --> o2(["active — true while limiting"])

rateLimit is the maximum speed through space, in units per second, and it applies to the whole vector — a diagonal move is limited to the same speed as a move along one axis. The setting keeps its meaning across task rates. While the target is close enough to reach in one cycle, the output arrives exactly and active reads false.

Both defaults leave the block transparent. enable is false, and rateLimit starts at the largest number a double can hold. You must set both.

This block has no disable input and no isEnabled output, unlike every other limiter here. enable is the only switch, and active tells you it is limiting — not that it is switched on.

After a controller start the output begins at the origin and travels to wherever inputs points. On a position command that is a commanded move from zero — see Limits and errors.

Signals

Inputs

Path	Unit	Range	Description
inputs	m, or any shared unit	unbounded	The target point, as three values. All three must share a unit for the speed limit to mean anything. Note the path name is plural.

Outputs

Path	Unit	Description
outputs	m, or the input unit	The rate-limited point, three values. It travels toward inputs in a straight line at no more than rateLimit, and arrives exactly once the remaining distance fits in one cycle. Starts at the origin after every controller start and is not cleared by a stop. Note the plural path name.
active	-	True while the step is being scaled — the equivalent of isLimiting on the other limiters, under a different name. False while the output is keeping up.

Parameters

Path	Unit	Default	Range	Effect
enable	-	false	-	False passes inputs straight to outputs, as a step. Set this, or the block does nothing.
rateLimit	unit per second	effectively unlimited	0 upward	The maximum speed through space. The default is so large that the block is transparent even when enabled — set a real value. 0 freezes the point. Not checked — a negative value drives the output away from the target.

Both are persistent and survive a controller restart. No parameters exist below this block.

Setup

1. Confirm all three elements of inputs share a unit — three positions in metres, or three velocities in metres per second. A mixed vector has no meaningful speed.

2. Set rateLimit to the maximum speed the machine may travel at. The default is not a limit.

3. Set enable true.

4. Command a target close to the current point and confirm outputs reaches it in one cycle with active reading false.

5. Command a distant target and confirm active goes true, outputs moves toward it, and the ratios between the three components of the remaining distance stay constant — that is what a straight path looks like.

   Step 5 is the check that the path is straight. If the ratios drift, something downstream is limiting the axes separately, which is exactly what this block exists to replace.

6. Time the move and divide the distance travelled by it. That should equal rateLimit.

7. Plan for the first cycle after a start. The output begins at the origin, so with a real rate configured the block will command a straight-line move from zero to the current target. Gate the consumer, or command the machine’s actual position first.

Tuning

1. Set the rate from the machine, not from the signal — it is the fastest the point may travel.
2. Confirm it does not bind during ordinary moves. active true all the time means the limit has become the speed governor rather than a safety net.
3. If you need the corners of the ramp smoothed as well, this block cannot do it: it bounds speed, not acceleration. A PVA limiter bounds the rate of the rate.
4. If individual axes also need a bound, add a per-axis limiter after this one — this block keeps the direction, and the per-axis clamp catches anything still out of range.
5. Nothing here needs re-checking after a task-rate change. The rate is in units per second.

Read the speed off the slope of any ramp.

Symptom	Cause	Action
Nothing is limited and active stays false	enable is false, or rateLimit is still at its enormous default	Set both
The machine made a long move immediately after a restart	Expected: the output starts at the origin and travels to the target	Command the machine’s actual position first, or gate the consumer
The output moves away from the target	rateLimit is negative	Set it positive, then disable for one cycle to re-seed the output
The output froze	rateLimit is 0	Set a positive rate
The path bends instead of running straight	Not possible in this block — something downstream is limiting the axes separately	Check what follows this block
The point jumped when the block was disabled	Expected: disabling assigns the target directly	Raise rateLimit until it no longer binds, then disable
active is true during ordinary moves	The rate is too low for normal motion	Raise it
The speed limit bites at a value that makes no sense	The three inputs do not share a unit	Use this block only on a vector with one unit
There is no way to override the block at runtime	Expected: there is no disable input	Write enable false, or raise rateLimit
I cannot tell whether the block is switched on	Expected: there is no isEnabled output. active means limiting, not enabled	Read enable back
The path has sharp corners at the start and end	Expected: this block bounds speed only	Use a PVA limiter if the corners matter
The outputs stuck at a non-numeric value	A non-numeric input latched into the output, which then poisons every step	Disable for one cycle to clear it, then fix the source

A starting point for limiting a Cartesian position command to 0.25 m/s:

enable    = true
rateLimit = 0.25

Limits and errors

Limit	Set by	What happens	Reported
rateLimit non-negative	Nothing	Not checked. A negative value drives the output away from the target, without bound. Only disabling the block or a restart clears it	Not reported
rateLimit = 0	Fixed	Freezes the point where it is	active reads true
rateLimit default	Fixed	Effectively unlimited, so an enabled but unconfigured block is transparent	Not reported
Speed through space	rateLimit while enabled	Bounded exactly, with the direction preserved	active
Individual axes	Nothing	Not bounded. This block limits the vector’s speed, not any one axis	Not reported
Position	Nothing	Unbounded — this block limits speed, not travel. Follow it with a limiter if the value needs a bound	Not reported
Startup position	Fixed	The output starts at the origin, not at the current target. There is no reset input	Not reported
Disabled behaviour	Fixed	Exact pass-through, so the point steps to the target	Not reported
Runtime override	Not available	There is no disable input and no isEnabled output	Not applicable
Non-numeric input	Nothing	Latches permanently — once an output is non-numeric every step derived from it is too. Disable for one cycle to clear	Not reported
Dimensions	Fixed	Always three channels. It cannot be resized	Not reported

The block raises no errors or warnings and logs nothing. Every failure above shows as a value on a trace, not as a message.

---

Verified against motorcortex-control3 3.30.0 (bc348fd).