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:
- your project's
objects/<type>/, - 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
| Way | What it copies | Committed |
|---|---|---|
| World Builder, Add to Scene | URDF, object model YAML and tag files, when the project has no copy yet | Yes, as Materialize object <name> |
zeon new object <name> | URDF and object model YAML | No: sync it yourself |
| Object Database, picking the item and Save to Project | URDF 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 synczeon 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).
| Situation | Result |
|---|---|
| No catalog item with that name, or not visible to you | object '<name>' does not exist in the mesh database. Run `zeon mesh-database list` to see available items. |
| The item has no URDF and YAML pair | An error naming the missing files and listing the files the item has |
objects/<name>/<name>.urdf or .object_model.yaml already exists | file already exists: <path>, before any download |
| The name is not a valid item name | An 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).
Updated 9 days ago