Adding an object

An object is something physical the robot interacts with: a plate, a holder, a fixture, an instrument. Objects come from a shared central catalog, so the same instrument has the same geometry and the same named frames in every project that uses it.

This page is about getting an object into your project. The catalog itself, and how items get into it, is covered in The Mesh Database.

What an object is on disk

In your project, every object lives at objects/<name>/ as exactly two files:

objects/plate_holder/
├── plate_holder.urdf               # Links, joints, mesh references
└── plate_holder.object_model.yaml  # Anchors, articulations, parts

The object's name is the folder name and both file prefixes. There is no separate id. Names must be lowercase, start with a letter or underscore, and contain only letters, digits, underscores, and hyphens (1 to 64 characters).

The URDF is the geometry and joint structure. The YAML is the Zeon-specific layer on top of it:

Anchors are where nearly all the authored value sits. A simple holder may have one anchor. A well plate has one per well. The object anchor is mandatory: loading a model without it raises "Required anchor(s) missing". Every field is documented in objects/<name>/<name>.object_model.yaml.

Once both files are in your project, they are the source of truth for that object. Anchor lookups at run time resolve the project copy first and only fall back to the central catalog if the project has no real copy of its own. Editing the YAML in your project changes behaviour for that project only. It never writes back to the catalog.

Finding an object in the catalog

The Object Database screen in the main app lists what the catalog holds, what each item carries, and what its anchors are called. See The Object Database for that screen and its controls.

From a terminal, zeon mesh-database list prints the catalog, and --tag <tag> filters it by an exact tag match. zeon mesh-database show <name> prints one item.

Not every item carries both files

Some catalog items carry only geometry, and a few carry neither file. The two cases matter differently:

• Annotation is blocked only when both files are missing. An item missing only one of the two is still open for annotation.
• Materializing an object needs both. zeon new object copies the URDF and the object-model YAML together and hard-fails if the catalog item does not have both.

Check what an item carries before you plan a workflow around it.

Getting an object into your project

The catalog is read-only to you. Putting an object in a project copies the item's URDF and object-model YAML into your project tree at objects/<name>/. It is a copy, not a link. A later change to the catalog item does not reach back into your project.

The CLI

zeon new object plate_holder

The CLI walks up from your current directory looking for a .zeon/ directory to find the project root, then fetches plate_holder.urdf and plate_holder.object_model.yaml and writes them into objects/plate_holder/.

It does not commit. On success it prints the two paths it wrote and tells you to push. Push them yourself:

zeon sync -m "Add plate_holder object"

Three failure modes, distinct on purpose:

The manifest check happens before the blob fetch, so a geometry-only item gives you a clear message instead of a confusing 404 partway through. The collision check happens before everything, so a failed run never leaves half an object written over a good one.

World Builder

If you are building a scene anyway, this is the path of least effort. In the main app, open a world and use the Add Objects panel: pick a name from the Select object... dropdown and click Add to Scene.

That dropdown lists the whole catalog, not only the objects already in your project. Before the object is added to the scene, the backend checks whether objects/<type>/<type>.urdf and <type>.object_model.yaml already exist in the project tree. If they do not, it fetches both, writes them, and commits them with the message Materialize object <name>. If they are already there, it does nothing and the existing files are left alone.

That gate is why a world never references an object your project cannot load. On a local install, Add + Localize goes through the same gate. That button is not shown in the cloud app.

Editing annotations

The live annotation editor lives on the Object Database screen. You can edit anchors, parts, and articulation presets there. Its object list covers the whole catalog, and picking an item your project does not have yet copies that item's files into the project tree first. The editor's layout and controls are documented in The Object Database.

Two actions decide what happens to your edits:

• Save to Project writes the edited URDF and YAML into your active project's objects/<name>/ and commits them. It does not write back to the shared catalog. Your edits stay in your project.
• Discard reloads the object from the project files and throws away unsaved edits.

If a teammate advanced the project while you were editing, the save is rejected with Project changed, refresh and retry. Nothing was written. Reload the page and redo the save.

A saved edit is a commit on the cloud project, so a teammate still has to pull before they see it. See How Sync Works.

Updating an object

A catalog item has one current set of blobs. Re-uploading an item replaces them under the same name. There is no version in the item record and no version in the blob URL, so there is nothing to pin to and nothing to upgrade to.

Your project keeps whatever it materialized until something overwrites it, and by design most things will not:

• Adding the object to another scene in World Builder is a no-op if the files already exist.
• zeon new object <name> hard-fails with file already exists.

To deliberately re-pull the current catalog version, delete objects/<name>/ locally, run zeon new object <name> again, then sync. Do this knowingly: any project-local edits you made to that YAML are discarded.

When the catalog does not have what you need

Uploading to the shared catalog is admin-only, enforced on the server. zeon mesh-database upload returns a permission error for anyone else, and so does zeon mesh-database delete. Neither is exposed in the main app.

If you think an item was uploaded but you cannot see it on the Object Database screen, confirm against the catalog directly with zeon mesh-database show <name> before assuming the screen is wrong. If it genuinely is not there, get in touch with your Zeon contact. They will need geometry (the URDF plus its meshes) and the anchor, articulation, and part definitions you want on it.