Adding an object

Copy an object type from the mesh database into your project, then place instances of it in a world.

An object type is a kind of thing: wellplate_96_flatbottom, wellplate_stand. An instance is one of them in a world, with its own id and pose: wellplate_stand_1 and wellplate_stand_2 are two instances of wellplate_stand in the starter world. This page is about types. Placing instances is in Building a world.

In your project, a type is a folder with two files:

objects/wellplate_stand/
├── wellplate_stand.urdf
└── wellplate_stand.object_model.yaml

The folder name is the type name and the catalog item name. The project copy carries no meshes; they are read from the mesh database.

Where a world finds a type

When a world loads, each instance's type is looked up in this order:

  1. your project's objects/<type>/,
  2. the mesh-database catalog your organization can see.

So a type does not have to be in your project for a world to use it, but the project copy is the one you can edit, and it wins when both exist. Its anchors are the ones your skills get. An instance whose type is in neither place is left out of the loaded world and reported as missing; the rest of the world still loads.

Three ways to add a type

WayWhat it copiesCommitted
World Builder, Add to SceneURDF, object model YAML and tag files, when the project has no copy yetYes, as Materialize object <name>
zeon new object <name>URDF and object model YAMLNo: sync it yourself
Object Database, picking the item and Save to ProjectURDF and object model YAML (and motions.yaml when present)Yes, on save, as Update object annotations for <name>

None of them overwrites a copy you already have. The World Builder skips the copy when the project already has both files, the CLI refuses, and the Object Database edits the existing copy.

From the CLI

Run it inside a project working tree:

zeon new object wellplate_stand
zeon commit -m "Add wellplate_stand"
zeon sync

zeon new object checks that the item exists and that its manifest has both <name>.urdf and <name>.object_model.yaml, then writes them to objects/<name>/ and lists the files it wrote:

materialized object wellplate_stand
  - objects/wellplate_stand/wellplate_stand.urdf
  - objects/wellplate_stand/wellplate_stand.object_model.yaml

It writes files only; commit and push them with zeon sync (see Syncing your work).

SituationResult
No catalog item with that name, or not visible to youobject '<name>' does not exist in the mesh database. Run `zeon mesh-database list` to see available items.
The item has no URDF and YAML pairAn error naming the missing files and listing the files the item has
objects/<name>/<name>.urdf or .object_model.yaml already existsfile already exists: <path>, before any download
The name is not a valid item nameAn error with the naming rule: ^[a-z_][a-z0-9_-]{0,63}$

From the World Builder

Pick the type in Add Objects and click Add to Scene. If your project has no copy yet, the copy is written and committed first, then the instance is added. See The World Builder.

From the Object Database

Picking a catalog item in the editor copies its files into the project on your instance so you can edit them. The copy reaches the cloud project when you click Save to Project. See The Object Database.

Updating a type from the catalog

A catalog item has no versions, and your project keeps the model files it copied. To take the catalog's current model files, delete objects/<name>/, run zeon new object <name> again and sync. Any anchors you edited in that folder are lost, so copy them out first.

Meshes are always read from the catalog, so a mesh update there needs no action in your project.

Your own edits

Your project copy is yours: add anchors, fix descriptions, add presets. The catalog never changes because of your edits, and other projects do not see them. Edit in the Object Database or by hand in the YAML (format).


Did this page help you?