In TSID’s TaskSE3Equality, a mask chooses rows from a task expressed in a particular frame. setMask() and useLocalFrame() jointly define which physical directions the task controls. Keeping the same binary mask while switching the frame can change an end-effector constraint from tool-relative motion to motion along world-aligned axes.
The implementation makes this concrete: it forms the local Jacobian and tracking errors, applies the selected frame convention, and only then copies the active rows into the task equality. To specify “control x,” you must also specify whose x-axis you mean.
The mask selects acceleration equations
The official TaskSE3Equality implementation creates a six-dimensional motion task. In its compute() method, the task reads the controlled frame’s pose, velocity and classical acceleration drift, and obtains its local Jacobian. Tracking gains and reference motion produce a desired acceleration.
Write J for that Jacobian after the frame choice, dv for generalized acceleration, d for the drift, and a_des for desired task acceleration. The equality assembled by the code is the selected-row version of:
J × dv = a_des − d
If S selects the active rows, the partial task is S J dv = S(a_des − d). The code copies the same selected components into the stored desired acceleration, drift, position error and velocity error. Its getAcceleration(dv) then returns the selected Jacobian times dv, plus the selected drift. This keeps the reported task acceleration and desired acceleration in the same reduced coordinate space.
For example, a binary mask [1, 0, 0, 0, 0, 0] retains the first translational row. A mask [1, 1, 1, 0, 0, 0] retains the three translational rows. The mask operates on the task’s six motion components, rather than on robot joint indices. A selected row may involve several joints through its Jacobian coefficients.
Local and world-aligned axes keep the same controlled point
The class header describes the alternatives as a local frame and a local world-oriented frame. The second phrase matters: the axes align with the world while the task remains attached to the controlled frame’s point.
In the local branch, the Jacobian stays local. Reference velocity and acceleration are rotated into the local basis before the feedback terms are assembled. A selected translational x component therefore follows the controlled frame’s x-axis as the robot changes orientation.
In the other branch, the code rotates the local error, current velocity, drift and Jacobian into world-oriented axes, then forms the desired acceleration there. The helper transformation m_wMl is initialized to identity and its rotation is set from the controlled frame’s orientation. This branch does not populate a translation that shifts the motion reference point to the world origin.
| Setting | Basis of the task rows | Point associated with the task |
|---|---|---|
useLocalFrame(True) |
Axes of the controlled frame | Controlled frame |
useLocalFrame(False) |
Axes aligned with the world | Controlled frame |
This is a basis choice for the task at the end effector. A world-origin spatial-motion representation would introduce a different reference point and associated translation terms. Reading “world-oriented” as “evaluated at the world origin” changes the meaning of the equations.
A rotated tool makes the row choice visible
Consider a hypothetical instantaneous example: the end-effector frame is rotated +90 degrees about world z. Its local +x points along world +y. Let the task retain only the first translational row, and suppose its selected desired acceleration is 1 m/s². For this illustration, take the drift to be zero.
With the local-frame setting, that row requests acceleration along the tool’s local x, which is world y at this pose. With the world-oriented setting, the first translational row requests acceleration along world x. The mask contains the same six numbers in both cases, but the two task equations describe different directions.
| Same one-row mask | Direction of the selected 1 m/s² request at this pose |
|---|---|
| Local basis | World +y, because it is tool +x |
| World-oriented basis | World +x |
This also explains why rotation must precede row selection. Let X_R denote the six-dimensional action matrix of the pure rotation. In the world-oriented branch, the selected Jacobian is S X_R J_local. Selecting a row of J_local first would choose a local direction and discard the other rows needed to construct a different world-axis direction.
A tool insertion task may naturally use tool-relative directions. A task that adjusts height above a work surface may instead use a world-aligned vertical component, provided that vertical is defined by the chosen world frame. The operational question determines the frame; the mask then picks the required components in that frame.
Zero means an omitted task row, not a zero-motion command
An inactive mask entry removes that row from this task equality. It does not add an equation saying that the corresponding acceleration must be zero. Other motion tasks, contact constraints and the robot dynamics can still influence the omitted direction. Even the active row can couple multiple joint accelerations.
This distinction is useful when a partial tool task is combined with posture control. Keeping one tool-direction equation leaves the formulation more freedom than imposing all six end-effector equations. The remaining solution is determined by the other registered tasks and constraints, along with their weights and priorities. The broader relationship is covered in the whole-body control guide.
Use a binary mask for this implementation. dim() calculates the row count from the mask sum, while compute() copies only entries that equal exactly 1.0. Fractional entries are therefore not a supported way to express “half as much control” on an axis: row allocation and row selection use different operations. Tracking gains and formulation weights have their own roles; a binary row selector supplies a different kind of choice.
Configure the partial task before sizing the formulation
The official manipulator exercise sets the end-effector task gains, applies conf.ee_task_mask, and sets conf.ee_task_local_frame before registering the task with addMotionTask(). It later resizes the solver using the formulation’s variable, equality and inequality counts.
That sequence lets the registered problem reflect the task’s selected dimension. The exercise registers the end-effector task at priority 1, so its equality describes the task relation inside that optimization setup; the call does not turn every selected row into an independent hardware motion limit.
When reading or configuring a partial task, keep three pieces together: the controlled frame name, the local/world-oriented choice, and the binary mask. They determine the point, basis and rows of the acceleration relation. The reference and gains then define the requested motion in those coordinates, and the formulation combines it with the rest of the robot’s problem.
Source basis: the official TSID devel implementation, header and manipulator exercise checked October 16, 2026. These are branch snapshots; no TSID solver or robot experiment was run for this article.