Recording a motion

Some things an arm has to do are not a pose. Lifting a lid off its hinge, sweeping a tool along a channel, easing a plate out of a slot at an angle: the useful part is the shape of the path, and writing that out as a list of coordinates is miserable.

A motion is that path, recorded by hand-guiding the arm through it once. An anchor names a place; a motion names a path through places. Both are stored in the object's own frame, so both follow the object when it is re-localized.

Where the work happens

The Motions tab of the annotation editor, on the Object Database screen. It sits beside Anchors, and unlike Parts and Presets it is visible without turning Advanced on.

Two things have to be true before you can record:

1. The object is placed in the world. A motion is stored relative to the object, so where the object actually is has to be established first. Do that in the World Builder. Until it is, the panel says so and offers a button that takes you there.
2. Arm capture is on. The switch is in the panel header, next to Advanced. It is what puts the real robot into play. Recording needs it, and so do the reachability dots, Preview and Play on arm. Browsing and editing motions the object already has works without it.

Recording a take

The recorder is the Record from arm card.

• Record starts sampling and turns freedrive on for you, so you can move the arm by hand straight away. Guide it through the path. A red recording badge shows while it runs.
• Stop ends the take. The badge changes to take open.
• Add keypose captures one pose right now, without recording continuously. Enter does the same thing, which matters because your other hand is on the arm.

You can build a whole motion out of Add keypose presses if the path is a few deliberate positions rather than a sweep. You can also mix the two.

Under the buttons is a live count of samples and the take's duration, with a discard link to throw the take away and start again.

If the panel warns about missed or stale ticks, the 3D view that feeds the recorder is not running. Open the real viewport and record again.

Saving the take

Once you stop, the commit block appears.

What the tolerances actually trade

The take you recorded is hundreds of samples. What gets stored is a handful of keyposes: the recorder throws away every sample that a straight interpolation between the ones it kept could have reproduced within your tolerances.

So tighter tolerances mean more keyposes and a more faithful path. Looser tolerances mean fewer. What they do not affect is how smooth the replay is, because that comes from the replay step and not from how many points are stored. A three-keypose motion still plays back as a smooth curve.

Start with the defaults. Tighten them only if the replayed path visibly cuts a corner you needed.

What refuses the save

• Fewer than two poses. A single pose is an anchor, so record it as one.
• A missing name, or one this object already uses.

Editing a motion

Select a motion under Motions on this object and its keyposes appear in a table: index, time, X, Y and Z in millimetres, and the gripper width.

• X, Y and Z are editable in the table. Type a number, press Enter.
• The gripper cell is editable too, in millimetres, and it has three states rather than two. A number commands that width at this keypose. 0 means closed. Empty means no command here, so the jaws keep whatever the previous keypose left them at. Clearing a cell is how you delete a gripper action without deleting the keypose.
• Clicking a row selects that keypose and puts a drag handle on it in the 3D view. Drag it there instead, and the change commits when you let go. Clicking a node in the 3D view selects its row too.
• Undo move reverts the last keypose move. It is one level deep.
• Delete removes the selected keypose, down to a floor of two.
• Delete motion removes the whole thing, behind a confirmation.

Three limits are worth knowing before you plan an edit:

• Rotation is not editable. The handle moves a keypose's position only. To change the orientation along a path, record it again.
• Keyposes cannot be reordered. They are in the order you recorded them.
• Timing is not editable. Use time_scale at replay instead.

Keyposes shown in red cannot be reached by the selected arm from where the object is now.

Trying it before a skill needs it

The Rehearse & test bar sits above the keypose table.

• Preview animates the gripper along the compiled path in the 3D view. No hardware moves, so it is safe to repeat as often as you like, though it does need an arm-capture session running. Clear removes it.
• Play on arm runs the same replay a skill runs, at whatever Speed is set to, with the path solved for every sample before the arm moves at all. During the replay the on-screen gripper tracks the arm's measured position, so if the arm stalls the animation stalls with it rather than pretending.
• Stop stops the arm where it is.
• Speed is a slider, 5 to 100 mm/s, starting at 20. It is the dial worth reaching for: crawl through a path you do not trust yet, then wind it up once it is proven. Preview honours it too.
• Blend is a slider, 0 to 5 mm, starting at 5, reading off at zero. It rounds the corners of the path. Rounding is what you want in transit and wrong for a deliberate contact, because it turns a recorded press into a touch. If a press replays too lightly, set Blend off. It has no effect on Preview, which hands nothing to a controller.
• A Reset button appears next to them once either differs from its default.
• Gripper decides whether the replay drives the real jaws. It is on by default, matching what a skill does.
• Draw as changes which gripper the preview draws, without changing what was recorded. Set as recorded does change the record, for when a motion was demonstrated with a different tool than it says.

The gripper matters

A motion can command the jaws as well as the path, and a width part-way along splits the replay: the arm parks at that keypose, the jaws actuate while it is stationary, then the next leg runs. So a motion that grabs something in the middle replays properly, and it will pause where it does so. That is why the gripper cell in the keypose table is worth editing: it is how you decide when the jaws move, not only how wide.

The other half is which gripper. A motion records the one that was fitted when you demonstrated it, because the tool tip sits in a different place on different tools. Replay it with a different gripper and the whole path is offset by the difference between the two.

The editor's Play on arm tells you when this happens, as a gripper-mismatch line under the bar, and it is only a warning: the replay still runs. A skill gets no warning at all. play_object_motion never checks which gripper a motion was recorded with, so it traces the offset path silently.

To replay it faithfully, switch back in Hardware Setup and restart, or record the motion again with the tool you actually intend to use.

Replaying it from a skill

motion = load_object_motion("plate_reader", "lid_lift")
start = motion["keyposes"][0]

move_arm("right_arm", start["xyz"], start["rpy"])
play_object_motion("right_arm", "plate_reader", "lid_lift", speed=0.05)

Get the arm onto the first keypose first. A replay refuses to travel more than 150 mm to reach its own start, because getting there is a straight line nothing has checked. See Motions for the full API.

Related