The mesh database

The mesh database is a shared catalog of physical objects: plates, cold blocks, fixtures, instruments. Items are uploaded as whole folders and stored centrally, so the same object looks and behaves the same way in every project.

The catalog itself is read-only for most users. To get an object into a project you materialize it: Zeon copies the item's URDF and object-model YAML into your project's objects/<name>/ folder. That flow is covered in Adding an Object. This page is about the catalog itself and the three places you look at it from.

What an item is

A catalog row is a name plus a manifest, the list of filenames stored under that item's folder. There is no description field and no per-item version number. These are the fields you actually see:

Field	What it is
`name`	Unique, lowercase, no spaces (`coldblock_holder`, `wellplate_96`)
`manifest`	Every filename in the item's folder, sub-paths included (`meshes/stl/foo.stl`)
`tags`	Free-form strings used for filtering
`visibility`	`public`, a list of orgs, or private (admin-only)
`source`	Provenance, e.g. `import:storage/mesh_database/bowl`, or `upload`
`imported_at` / `imported_by`	Timestamp and user id of the last upload

Items uploaded recently also carry a server-side summary of their object_model.yaml: anchor, articulation-preset, and part counts plus the names. This is computed once at upload time so a picker can show rich summaries without fetching every YAML. Rows uploaded before that summary existed, and any row whose upload carried no parseable object_model.yaml, leave those fields empty; empty means "not computed", not "zero".

⚠️
Not every item is a complete object. Some rows are geometry-only: mesh files with no <name>.urdf and <name>.object_model.yaml pair. They stay visible in the catalog but cannot be materialized into a project. Attempts fail with a message that the item appears to be a geometry-only item that can't be materialized as a project object. Check the manifest before you rely on an item.

The three surfaces

Surface	What it reads	Can it write?
Web IDE, Mesh database button	The shared catalog, over the sync service	No, read-only
Main app, Object Database screen	Your user instance's execution container	Yes, edits object annotations
CLI, `zeon mesh-database`	The shared catalog, over the sync service	Upload and delete are admin-only

The IDE and the CLI both talk to the same shared catalog, so their lists match. The Object Database screen goes through your own user instance instead, which is why its list can differ; see below.

In the Web IDE

Click Mesh database in the top bar. The browser opens as a centered modal over the editor, not a side panel. It is a list/detail split: items on the left, details for the selected item on the right.

The list shows each item's name, its file count, its tags, and a public marker where applicable. There are no thumbnails in the list. Above it, a search box filters on name substring only (it does not search tags) and a dropdown filters to a single tag. The header shows a <filtered> of <total> count. Items are sorted alphabetically by the client, because the server returns them in scan order.

Select an item and the detail panel shows the thumbnail (if the item has one), the source, visibility, tags, and the full manifest. This is where the thumbnail lives. Nowhere else.

Visibility is enforced on the server. The IDE renders whatever the catalog returns for you, so a private item is absent from your list.

The modal's Use in project button does not materialize anything by itself. It closes the browser and opens the New file dialog pre-filled with kind Object and the item's name, which you can edit before clicking Create. Creating that way writes placeholder URDF and YAML. The dialog describes the Object kind as a mesh-database object whose placeholder URDF and YAML are to be filled in later, and you still have to commit. To get the real geometry, use the CLI.

In the main app

Object Database in the sidebar, at /p/<project-id>/object-database. This is a full routed screen, not a picker, and it is the only surface where you can change an object. It has two tabs.

Annotate Objects is the editor. Pick an object from the dropdown and the screen loads it into the annotations viewer running on your instance, shown in a Viser 3D viewport alongside a control panel for anchors, articulation presets, and parts. Objects with neither a URDF nor a YAML are listed but disabled, marked (missing URDF and YAML).

Three mechanisms are worth knowing:

The viewport stays blank until you pick an object. The annotations viewer starts lazily on the execution container when the first edit request lands, so mounting the iframe earlier would proxy to a port that is not listening yet.
Save to Project does not write back to the shared catalog. It exports the current editor state, writes objects/<name>/<name>.urdf and objects/<name>/<name>.object_model.yaml into your active project, and commits them with the message Update object annotations for <name>. Your edits are project-local. Everyone else's copy of the catalog item is untouched.
Discard reloads the object from the project files, throwing away unsaved edits.

If someone else has moved the project forward while you were editing, the save is rejected and you get Project changed, refresh and retry. Nothing is written. Reload and redo the save.

View Database is the read-only inventory: a card per object with anchor, preset, and part counts and whether the URDF and YAML are on disk. View Details expands one object to list the anchor, preset, and part names; Edit Annotations → jumps to the Annotate tab with that object loaded. The 3D panel on the details view is a placeholder; the live viewer is on the Annotate tab.

Counts shown here are overlaid with your project's copy of an object where one exists, so after a save the numbers reflect your edits rather than the catalog's original.

From the CLI

See zeon mesh-database for the full reference.

zeon mesh-database list --tag container
zeon mesh-database show coldblock_holder
zeon mesh-database download coldblock_holder ./scratch/coldblock_holder

list and show are the same catalog the IDE renders. download mirrors an item's whole manifest to a local directory, preserving sub-paths, which is useful for inspecting an item before you commit to it.

To actually put an object in a project, use zeon new object:

zeon new object coldblock_holder
zeon push

This checks the item exists and that its manifest carries both required files, fetches them, and writes them to objects/coldblock_holder/. It refuses to overwrite existing files, and it writes nothing on failure, so you never end up with half an object. It is local-first: the files land on disk and zeon push commits them to the cloud project.

📘
This is the reliable path for getting real geometry into a project. The CLI fetches the canonical URDF and YAML; the IDE's New file dialog writes placeholders.

Why the lists can differ

The IDE and CLI read the shared catalog directly. The main app's Object Database screen asks your user instance instead, and what that instance serves depends on how it is configured: either a mesh-database directory on the instance, or a cached read-through of the shared catalog. The two are not guaranteed to be in sync.

Practically: if an object appears in the IDE browser but not on the Object Database screen, the instance has not picked it up. The catalog is the source of truth. Check with zeon mesh-database show <name>.

Uploading and deleting

zeon mesh-database upload <name> <src> replaces an item with the contents of a local folder, walking it recursively and preserving sub-paths. zeon mesh-database delete <name> drops the row and every file under it.

Both are admin-only, enforced on the server: non-admin callers get a 403. The IDE's empty state suggests the upload command, but running it without admin rights will fail. If you need an object added to the shared catalog, go through your Zeon contact. Editing an object's annotations for your own project does not require admin: use the Object Database screen, which saves into your project rather than the catalog.

Item history is kept internally by the storage layer, but there is no user-facing versioning: you cannot pin an item to a version, and re-uploading an item replaces what everyone sees. Projects that already materialized the object keep their own copy of the files, because materializing is a copy, not a link.

Where to go next

Adding an Object

The full flow for getting a catalog item into your project.

objects/*.object_model.yaml

What anchors, articulations, and parts mean.

zeon mesh-database

Browse, download, and (as admin) upload from the CLI.

Building a World

Place a materialized object into a scene.