The Object Database

The Object Database screen is where you annotate the objects in your project, and where you browse what the project already has. Annotating means placing an object's anchors and describing how the gripper should meet them, and recording the motions an arm makes around it. That is the information every picking skill reads. The page heading reads Object Database. You reach it from the Object Database entry in the sidebar, or from the Annotate Object tile on Home.

This page describes the screen. For what an object is and how you bring one into a project, see Adding an object and The mesh database. For what an anchor is and how a skill uses one, see Anchors, and for motions, Recording a motion.

The two tabs

Directly under the heading there are two tabs:

• Annotate Objects, the tab the screen opens on. A picker, a 3D viewport, and the annotation editor panel.
• View Database, a read-only browse of everything in the project.

The tabs share one list of objects. That list loads when you open the screen and reloads whenever the browser tab regains focus. If loading fails, a red bar appears under the tab strip, above the tab content, reading Failed to load objects: followed by the reason. It shows on whichever tab you are on.

Annotate Objects

This is where the work happens. You pick an object, it loads into a live 3D view with an editor panel beside it, and you place and describe its anchors.

The object picker

The tab opens with a row containing the label Object and a dropdown. Unopened, the dropdown reads Select an object, or Loading… while the list is still arriving. Picking an object loads it into the annotation editor, which takes a moment; a Loading… spinner appears at the right of the row while the swap runs. Picking a second object while one is still loading does nothing, so wait for the spinner to clear.

Once an object is loaded, a small summary appears next to the dropdown in the form 3 anchors · 2 presets · 5 parts.

If loading the object into the editor fails, a red bar appears under the picker with the reason.

The viewport

The left half of the tab is the 3D view of the object. Before you pick anything it reads Select an object to begin annotating, with the line The annotations viewer starts when you pick an object from the dropdown above. underneath. While a swap is running it reads Loading object…. The viewer starts on demand, which is why nothing is drawn until your first pick. Its camera and scene controls are the standard ones used across the app.

The annotation editor panel

The right half is the editor panel. Until an object is loaded it reads Select an object to edit its annotations., and while the editor is starting, Loading editor….

The panel and the menu inside the 3D viewport are two faces of the same editor. A change made in one appears in the other.

At the top of the panel is the loaded object's name. An unsaved badge appears beside it when the working copy differs from what is stored in the project.

Beside the object name sit two switches.

Arm capture turns on a live session with a real arm, and is described below. It is at the top of the panel rather than inside a tab because it puts the robot into play and much of what follows depends on it. On a machine with no rig, it is not shown at all.

Advanced is remembered between sessions. With it off the tab row reads Anchors and Motions, which is all most annotation needs. Turn it on and two more appear, so the row reads Anchors, Motions, Parts, Presets, and the anchor editor gains its more specialised controls. The panel opens on Anchors each time a new object loads.

Below the tabs, and visible on every tab, is a Joints block: one numeric field and one slider per actuated joint. Moving a joint poses the object in the viewport, so you can annotate a lid where it opens rather than only where it rests. The block is absent for objects that have no actuated joints.

Arm capture

On a local install attached to a rig, the Arm capture switch in the panel header starts a live session with a real arm. It is what lets you read a pose off the bench instead of typing one, and it is what the Motions tab records through. The cloud has no arm to guide, so the switch is not shown there.

If several copies of the object type are placed in the world, the switch asks Which one are you capturing against? before it starts, and lists them. Each row shows the copy's display name and, where it has them, its tagged unit, how far away it is, and whether its pose came from the loaded world. Pick one and press Start capture.

You cannot start a session at all while the object has unsaved edits. The Arm capture switch is greyed out and a Save before capturing from the arm card appears as soon as the working copy differs from the project, so you find out before trying rather than after. The placement was worked out against the object's own frame as stored in the project, so an unsaved change to that frame would offset every pose you capture. Save to Project first.

With a session running, the block under the header holds:

• A dropdown choosing Left arm or Right arm.
• A Freedrive switch. Record on the Motions tab turns freedrive on for you. However the arm gets moved, capture reads its joint encoders, so it does not matter what put it where.
• Live tool-tip pose in the object frame, a live readout of X, Y and Z in millimetres and roll, pitch and yaw in degrees. While it is warming up it reads Reading arm….
• Snap rotation to 90°, which tidies the orientation to right angles as you capture.

Capturing itself is not a button here. Use From arm in the anchor's pose editor, or press Enter.

Anchors

An anchor is a named frame on the object, together with the grasp and viewpoint information a skill reads off it. The Anchors tab is where you create those frames, place them in space, and describe how the gripper should meet them. This is the heart of the screen.

Choosing and creating anchors. The searchable picker at the top selects the anchor you are editing. New starts a fresh one; Duplicate copies the current anchor and asks you to name the copy, which is the fast way to make a second grasp that is a small offset from the first. Delete removes the current anchor and asks first, naming it so you cannot delete the wrong one by reflex. Each anchor carries a Name, a Parent link (the object link it attaches to, so it rides with that part when a joint moves it), and a Description.

Two view switches keep a busy object readable: Hide other anchors clears the viewport down to only the anchor you are working on, and Show camera model (under Advanced) draws the wrist camera where a viewpoint anchor would look at the object from.

Placing the anchor. The pose editor holds X, Y, Z in millimetres and Roll, Pitch, Yaw in degrees. Type them in, or drag the anchor's gizmo in the viewport and read the numbers back. The quick actions save most of the typing:

• From arm fills the pose from where an arm is sitting right now, so you can jog an arm to the spot you want and capture it instead of guessing coordinates.
• Zero resets the fields, Snap 90° rounds the orientation to the nearest right angle after a rough drag, and Rotate +90° turns the anchor a quarter turn about X, Y, or Z.
• Copy and Paste carry a whole pose from one anchor to another.
• Revert drops pose edits you have not applied yet, and Apply pose writes the fields onto the anchor so the change shows in the view.

Grasp, and the rest of the metadata. Below the pose are collapsible sections. Grasp is the block a picking skill actually reads: the gripper Width the object wants to be held at, and the Standoff distance to approach from. Width from robot reads the current gripper opening into the width field, so you can close the gripper on the part and capture the number rather than measure it. Gripper preview draws the gripper at the anchor to show whether it clears, and Show pre-grasp shadow adds a ghost at the standoff point. Under Advanced, two further sections appear: Localization, the settings AprilTag relocalization reads for this anchor, and Viewpoint, which marks the anchor as a place to look from and stores the camera framing for it.

Copy from… sits at the top of the metadata block, above Grasp, and copies another anchor's whole metadata: its grasp, its localization settings, and its viewpoint, not the grasp alone. It loads the values into the form, so Update anchor still has to commit them.

Update anchor is not in the tab body. It sits in the pinned action row at the bottom of the panel, next to Discard and Save to Project, because it acts on the object rather than on the tab. A brand-new anchor is the exception: the pinned button is absent and a full-width Create anchor appears in the tab body instead.

Update commits the anchor to the working copy only. Making it durable is a separate step, covered under Update against Save to Project below.

Viz objects

Placing an anchor is far easier when you can see what it has to line up with. Viz objects lets you drop other objects into the scene as scratch references while you work: bring in a plate, a tip box, a cold block, whatever this anchor interacts with, and check the anchor against real geometry instead of against empty space.

Add one from the picker with Add. Each reference object is one of three kinds, and each gets a row with a Held by anchor control and mode buttons to switch between them:

• Anchored rides with the anchor you are editing. Anchor a plate to a grip point and it tracks the anchor as you move it, which is how you confirm a grasp lines up.
• Free sits where you place it and stays put while you move the anchor, for checking clearance against a fixed neighbour.
• Frozen is pinned and will not move at all.

Viz objects are a workspace aid only. Nothing here is written into the object model, so they disappear when you reload and never reach the saved file.

Test on robot

Under an anchor's pose editor, on a rig, is a Test on robot bar. It drives the arm to the anchor you are looking at, so you can check the pose against the physical object rather than against the screen.

• Go to pre-approach moves to the anchor's standoff pose.
• Go to anchor moves to the anchor itself.
• Grip width sets the real gripper to the anchor's grasp width. It appears only when the anchor declares a grasp.
• Stop stops the arm where it is.

Targets come from what is on screen, including edits you have not applied, so it tests what you are actually looking at.

It refuses in a few sensible cases: with no session running, while a recording is in progress, while another move is already going, and for the object's own frame, which is not a drivable target. Starting a move leaves freedrive first, since an arm cannot be both loose and driven, and the Freedrive switch follows.

Reachability

Beside the Anchor label, and on each motion chip, is a small coloured dot. Hover it for the wording.

It updates as you work, following the object's placement, the joint sliders, and your unsaved edits. It pauses while a test move is driving the arm.

Motions

An anchor names a place. A motion names a path through places: a recorded tool path, stored on the object in the same frame an anchor uses, so it follows the object when the object moves. Lifting a lid off its hinge is a motion; the point you grab it at is an anchor.

The tab is visible without Advanced, because recording a motion is ordinary annotation rather than an internal.

Record from arm is the recorder, and it needs Arm capture on. Record starts sampling and turns freedrive on for you, so you can guide the arm straight away; Stop ends the take. Add keypose captures a single pose instead, and Enter does the same. A live count shows how many samples the take holds and how long it ran, with discard to throw it away.

Once you stop, the commit block appears: Save take as for the name, a description, and three numbers that decide how much of the take survives, pos tol (mm) and rot tol (deg) (both 3.0) and max keyposes (40). Trim still ends, on by default, drops you reaching for the arm and letting go of it. Save motion (n samples) commits it.

Motions on this object lists what the object already has, as chips. Selecting one opens its detail card, its description, and its keypose table.

The keypose table has a row per keypose: index, time, X, Y and Z in millimetres, the gripper width, and a delete control. X, Y and Z are editable in place, and so is the gripper cell: a number commands that width in millimetres, 0 closes, and an empty cell means no command at this keypose so the jaws hold whatever they had. Clicking a row selects that keypose and puts a drag handle on it in the 3D view, and clicking its node in the 3D view selects the row. Undo move reverts the last move, one level deep. Rows shown in red cannot be reached by the selected arm from where the object currently sits.

Delete motion removes the whole thing, behind a confirmation.

Three things the table deliberately does not do: it cannot reorder keyposes, it cannot change their rotation, and it cannot rename a motion.

For the full task, including what the tolerances trade and why editing a keypose changes how a replay behaves, read Recording a motion.

Rehearse and test a motion

Above the keypose table is a Rehearse & test bar.

During Play on arm, the on-screen gripper follows the arm's measured position rather than an estimate, so if the arm stalls the animation stalls with it.

Blend is worth understanding before you conclude a motion replayed wrongly. It rounds every corner in the path, which is smoother in transit but turns a deliberate press into a touch. A recorded contact that replays too lightly is usually blending, not a bad recording: set Blend to off and try again.

A motion replayed with a different gripper than it was recorded with traces an offset path, because the tool tip sits somewhere else. You get a warning, and only a warning: the replay still runs.

Parts and Presets

These two tabs appear only under Advanced.

Parts groups the object's mesh links into named parts, so a skill can refer to "the lid" or "the drawer" rather than a raw link name. Pick a part to edit its Name and Description, and tick which mesh links belong to it in the Links (n selected) checklist, with Clear to untick them all. Create part, Update part, and Delete manage the list.

Presets saves named joint configurations, the articulation presets, so an articulated object can be recalled to a known state such as open or closed. Pick a preset to edit its Name and Description, choose which joints it covers under Included joints, and turn on Show joint frames to draw the joints while you set it. Create preset, Update preset, and Delete manage them.

Update against Save to Project

These are two different levels of commit, and the distinction matters.

Update anchor, Update part and Update preset apply the edits in the tab body to the working copy of the object held by the editor. Nothing is written to your project yet. Save motion on the Motions tab behaves the same way, despite its name: it commits the take to the working copy, not to disk.

Pinned at the bottom of the panel are two controls that act on the whole object:

• Save to Project writes the entire object, every anchor, part and preset, out to the project files. The button reads Saving… while it works. On success a green bar appears above the viewport reading Saved <name> to the active project. If someone else changed the project underneath you, a red bar reads Project changed, refresh and retry. Reload the screen and save again. That check exists only in an ordinary project: in a shared reference project the save goes straight into the shared copy on the machine, with no concurrency check at all, so two people annotating the same object there will overwrite each other silently. Save to Project is disabled while an anchor still holds edits you have not applied, so apply them with Update anchor, or Discard, first.
• Discard reloads the object from the project files and throws away every unsaved edit, including any Update you have applied.

View Database

The other tab is a read-only browse of every object in the project.

The object list

Above the grid sits a count: N objects in database, or Loading… while the fetch is in flight. If the project has no objects, the count reads 0 objects in database and the grid below it is empty.

Each object is a card. A card shows the object name and up to six lines of fact, all read from the project's own files:

• Anchors: the number of anchors defined on the object.
• Articulation presets: the number of presets.
• Parts: the number of named parts.
• Tagged units: how many physical copies have their own set of tags recorded. This line is left out entirely for an object with none, which is most of them. See Localizing an object.
• URDF: yes or no.
• object_model.yaml: yes or no.

The card's only control is View Details.

The detail view

View Details replaces the grid with a two-column detail view for that object. A ← Back to Database button at the top returns you to the grid.

The left column repeats the object name as a heading, then lists:

• URDF on disk, yes or no.
• object_model.yaml on disk, yes or no.
• Anchors, every anchor name as a chip.
• Articulation presets, every preset name as a chip.
• Parts, every part name as a chip.
• Tagged units, every unit's handle as a chip. Absent when the object has none.

Below those is Edit Annotations →. It switches you to the Annotate Objects tab and loads this object into the editor in one step.

The right column is headed 3D View and is a placeholder, not a viewer. It shows a box icon, the text 3D Object Viewer, and the line Open the Annotate tab for the live editor. Nothing renders here. The live 3D view is on the other tab.

Related