---
name: adom-layouts
user-invokable: true
description: Spec for editing workcell layout JSON (molecules and wires). Use when the user wants to add, remove, or change molecules or wires in a layout file.
---

# Layout JSON Spec

When modifying a layout file (e.g. to add, remove, or move molecules), use this structure and these rules.

## Full example

```json
{
    "molecules": {
        "BHI385_Molecule v12": {
            "sku": "adom/BHI385_Molecule v12/v1",
            "name": "BHI385_Molecule v12",
            "position": {
                "x": 16,
                "y": 16,
                "z": 0
            },
            "rotation": {
                "z": 0
            },
            "scale": {
                "x": 1,
                "y": 1,
                "z": 1
            },
            "pins": {
                "FL": {
                    "x": 10,
                    "y": 10,
                    "z": 41.2
                },
                "FR": {
                    "x": 10,
                    "y": 10,
                    "z": 41.2
                },
                "BL": {
                    "x": 10,
                    "y": 10,
                    "z": 41.2
                },
                "BR": {
                    "x": 10,
                    "y": 10,
                    "z": 41.2
                }
            },
            "pinType": 5.6
        },
        "TXS0108E_8bitLevelShifter": {
            "sku": "adom/TXS0108E_8bitLevelShifter/v1",
            "name": "TXS0108E_8bitLevelShifter",
            "position": {
                "x": 16,
                "y": 48,
                "z": 0
            },
            "rotation": {
                "z": 0
            },
            "scale": {
                "x": 1,
                "y": 1,
                "z": 1
            },
            "pins": {
                "FL": {
                    "x": 10,
                    "y": 10,
                    "z": 41.2
                },
                "FR": {
                    "x": 10,
                    "y": 10,
                    "z": 41.2
                },
                "BL": {
                    "x": 10,
                    "y": 10,
                    "z": 41.2
                },
                "BR": {
                    "x": 10,
                    "y": 10,
                    "z": 41.2
                }
            },
            "pinType": 5.6
        }
    },
    "wires": [
        {
            "name": "Wire 1",
            "startReference": {
                "moleculeName": "BHI385_Molecule v12",
                "contactPosition": {
                    "x": 6,
                    "y": 8,
                    "z": 2.8
                },
                "contactName": "P$1"
            },
            "endReference": {
                "moleculeName": "TXS0108E_8bitLevelShifter",
                "contactPosition": {
                    "x": 8,
                    "y": 6,
                    "z": 2.8
                },
                "contactName": "P$1"
            },
            "manualBendPoints": [],
            "segments": [
                {
                    "vector": {
                        "x": 0,
                        "y": 0,
                        "z": 7.599999999999994
                    },
                    "startPoint": {
                        "x": 22,
                        "y": 24,
                        "z": 0.8000000000000114
                    },
                    "endPoint": {
                        "x": 22,
                        "y": 24,
                        "z": 8.400000000000006
                    },
                    "length": 7.599999999999994
                },
                {
                    "vector": {
                        "x": 2,
                        "y": 0,
                        "z": 0
                    },
                    "startPoint": {
                        "x": 22,
                        "y": 24,
                        "z": 8.400000000000006
                    },
                    "endPoint": {
                        "x": 24,
                        "y": 24,
                        "z": 8.400000000000006
                    },
                    "length": 2
                },
                {
                    "vector": {
                        "x": 0,
                        "y": 30,
                        "z": 0
                    },
                    "startPoint": {
                        "x": 24,
                        "y": 24,
                        "z": 8.400000000000006
                    },
                    "endPoint": {
                        "x": 24,
                        "y": 54,
                        "z": 8.400000000000006
                    },
                    "length": 30
                },
                {
                    "vector": {
                        "x": 0,
                        "y": 0,
                        "z": -7.599999999999994
                    },
                    "startPoint": {
                        "x": 24,
                        "y": 54,
                        "z": 8.400000000000006
                    },
                    "endPoint": {
                        "x": 24,
                        "y": 54,
                        "z": 0.8000000000000114
                    },
                    "length": 7.599999999999994
                }
            ],
            "color": {
                "r": 1,
                "g": 0,
                "b": 0
            },
            "diameter": 0.51,
            "routingType": "auto",
            "initialRaiseHeight": 2,
            "gauge": "24 AWG"
        }
    ]
}
```

- **molecules**: Object. Each key is the molecule’s **unique name**. Value is a molecule object (see below).
- **wires**: Array of wire objects. Each wire has `name`, `startReference`, `endReference` (each can use `moleculeName` + `pinType` or `moleculeName` + `contactPosition`/`contactName`), `manualBendPoints`, `segments`, `color`, `diameter` or `gauge`, `routingType`, `initialRaiseHeight`. If you rename a molecule, update every wire’s `startReference.moleculeName` and `endReference.moleculeName` that point to it.

If the file has no `molecules` or `wires` at the root, the whole root is treated as the molecules object and wires are empty.

## One molecule object

Each entry in `molecules` must look like this:

```json
{
  "name": "MyMolecule_1",
  "sku": "owner/moleculeName",
  "position": { "x": 0, "y": 0, "z": 0 },
  "rotation": { "z": 0 },
  "scale": { "x": 1, "y": 1, "z": 1 },
  "pins": {
    "FL": { "x": 10, "y": 10, "z": 41.2 },
    "FR": { "x": 10, "y": 10, "z": 41.2 },
    "BL": { "x": 10, "y": 10, "z": 41.2 },
    "BR": { "x": 10, "y": 10, "z": 41.2 }
  },
  "pinType": 5.6
}
```

| Field | Type | Notes |
|-------|------|--------|
| **name** | string | Display name; should match the key in `molecules`. Must be unique. |
| **sku** | string | Id for the 3D asset. Format: `owner/moleculeName` or `owner/moleculeName/version`. |
| **position** | `{ x, y, z }` | Numbers. Position on the workcell. |
| **rotation** | `{ z }` | **Degrees** (not radians). Only z is used. Must be 0, 90, 180, -90, -180|
| **scale** | `{ x, y, z }` | Numbers. Usually 1,1,1. |
| **pins** | object | FL, FR, BL, BR, each `{ x, y, z }`. Used when the molecule has no footprint file. |
| **pinType** | number | e.g. 5.6 or 2.6. Used with pins. |

## Editing rules

- **Add a molecule**: Add a new key to `molecules` (unique name) with a full molecule object. Copy the shape above and set name, sku, position, rotation, scale, pins, pinType.
- **Remove a molecule**: Delete that key from `molecules`.
- **Move a molecule**: Change `position.x`, `position.y`, and/or `position.z` for that molecule.
- **Rotate**: Change `rotation.z` in **degrees**.
- **Rename**: Change both the **key** in `molecules` and the **name** field inside the object so they match. Any wires referencing the old name must be updated to the new name.
- **Duplicate**: Add a new key (e.g. `Name_2`) with the same object but a unique `name` and adjusted `position` so it doesn’t overlap.

## Wires

Each item in `wires` matches the wire object in the full example above: `name`, `startReference`, `endReference`, `manualBendPoints`, `segments`, `color`, `diameter` or `gauge`, `routingType`, `initialRaiseHeight`. References use either `moleculeName` + `pinType` (e.g. `"BR"`) or `moleculeName` + `contactPosition` + `contactName`. When renaming a molecule, update every wire’s `startReference.moleculeName` and `endReference.moleculeName` that reference it. If you’re only editing molecules, leave `wires` unchanged.