Building a world
A world is the scene a workflow runs in: tables and object instances with poses. How to create, edit, save and load one.
A world is the scene your skills and workflows run in: the tables, and every object instance on them with its pose. Each world is a folder worlds/<id>/ in your project. A workflow does not contain a world; you pick the world when you run, so one workflow can run against several layouts.
A world holds instances, not object definitions. Each instance names its object type, and the type's URDF and anchors come from your project's objects/<type>/ or from the mesh database (see Adding an object).
Worlds belong to a setup
A world's coordinates are measured in the frame of the robot rig, the setup your project names in project.json. The setup fixes where each arm's base stands; the world says where the tables and objects are relative to that. A world laid out for one setup is generally wrong for another. The starter project's shaker_deck world is laid out for the starter's setup: the left arm's base at the origin, the right arm's beside it towards -y, +x towards the front table, z up.
Three ways to start a world
| Start from | How | Result |
|---|---|---|
| The starter world | A new project ships worlds/shaker_deck/ | Two stands, a 96-well plate and the plate shaker on two tables |
| An empty bench | zeon new world <name> | worlds/<name>/world_state.json with a front table table and a back table table_back, for an arm base at the origin |
| The current scene | Save World in the World Builder | A new saved world from whatever is in the scene |
zeon new world walks up from the current directory to find the project, refuses to overwrite an existing file (file already exists: <path>), and prints the file it created. Sync it to use it in the app.
The first two produce a starting layout: a world_state.json you can read and edit by hand. It loads read-only. Edits you make in the app are saved as a new world, never written back into the starting layout. The full format is in worlds/<id>/world_state.json.
Tables
Tables are objects of the world, not of the setup. A world with no table loads with a warning and gives the arms no work surface. In a starting layout a table is a Cuboid entry with "metadata": {"role": "table"}:
"table": {
"geometry": {"type": "Cuboid", "name": "table", "dims": [0.76, 1.52, 0.05], "color": [0.6, 0.4, 0.2]},
"mount": {"type": "FixedMount",
"world_P_body_fixed": {"xyz": [0.26, 0.0, -0.025], "wxyz": [1.0, 0.0, 0.0, 0.0], "stamp_s": null}},
"metadata": {"name": "table", "role": "table"}
}dims is the box size in metres and the pose is the box centre, so this table's top is at z = 0. The World Builder has no control for adding or resizing a table: to change tables, edit a starting layout by hand, load it and save it as a new world.
Building the scene
The World Builder edits a live scene on your instance. The usual loop:
- Load a world. On the Saved Worlds tab, click Load into Editor on the world to start from.
- Add objects. In Add Objects, pick a type and click Add to Scene. If the project has no copy of the type yet, it is copied in and committed first. The new instance gets the id
<type>_<uuid>and appears at x = 0.4, y = -0.3, z = 0.05 m. - Place them. Select the object in Object Transform and type X, Y, Z (metres) and Roll, Pitch, Yaw (radians), then Update Transform. Or click the object in the 3D view and drag its gizmo; Load Current Pose reads the numbers back. The pose is that of the object's
objectanchor. Placement does not check for collisions. - Name them. Use Edit name / index on a row of Scene Objects to set a display name and an optional index.
- Save. Click Save World.
Position the objects from known measurements where you have them. A pose that looks right in the viewport can still be centimetres off on the bench.
Instance ids, names and indexes
| Example | Set by | |
|---|---|---|
| Instance id | wellplate_stand_1, wellplate_96_flatbottom_2f6c0f3e-... | The starting layout's key, or generated on add. Never changes. |
| Display name | wellplate, source_plate | You. Defaults to the type name; a repeated name on add gets _1, _2. |
| Index | 1, 2 | You, optionally. Numbers are stored as integers. |
Workflow and skill object inputs take instance ids. A run's object input (zeon run -i plate=..., a workflow input) also accepts a display name, or a type the world has exactly one instance of: the run maps it to the instance id before it starts. Inside a skill, resolve() also accepts a display name when exactly one object has it; when several do, it raises an error naming them. Give objects names your skills can rely on, or use their ids.
Saving
The Save World dialog asks for a World Name and an optional Description, and offers two saves:
| Button | Effect |
|---|---|
| Save as new | Writes a new folder. Never overwrites. |
| Update <name> | Rewrites the world you loaded, in place. Keeps its name and creation time. The description you enter replaces the stored one; an empty field clears it. |
The new folder's name is the world name lowercased, with every character other than a-z, 0-9 and _ turned into _, repeated underscores collapsed and leading or trailing ones removed (Bench Layout v2 becomes bench_layout_v2). When that folder already exists, the save goes to <name>_<YYYYMMDD_HHMMSS> instead. The name exactly as typed is kept as the world's display name.
Either save writes the world folder and commits it to the cloud project as Save world <id>. If someone else pushed to the project in the meantime, the save stops with Project changed during save, refresh and retry. Teammates see the world after they pull or sync.
Update is refused for:
- a starting layout:
'<id>' is an old (v1) world and is read-only; save it as a new world, - a world that loaded with missing objects (see below): updating would delete them from the saved world, so the message asks you to restore their types and reload, or save as a new world.
Saving does not change active_world in project.json.
Loading and missing objects
A world loads into the sim when you click Load into Editor in the World Builder, or with zeon up --world <id> (default: active_world). Each instance's type is looked up in your project's objects/ first, then in the mesh-database catalog your organization can see.
An instance whose type is found in neither place is left out; the rest of the world loads. A skill that names a left-out object fails with "no object". The World Builder does not list missing objects. zeon up prints them:
warning: world <id> loaded WITHOUT 1 object(s); skills that name them fail with 'no object':
<id> (<type>): <reason>
and zeon brief shows them under the world. The usual fix is to add the type to the project (zeon new object <type>) or ask Zeon to share the catalog item with your organization.
Run-time state
Tip pointers, seats and per-seat calibration change during runs and are stored beside the world in live_state.yaml, not in the world itself. Save as new copies it into the new folder. See live_state.yaml.
Related
Updated 1 day ago