---
title: "Layout across builds"
description: "Lay out more parts than fit on one build platform with auto_layout_models, moving the newest parts to the next build until all are placed."
url: https://developer.formlabs.com/examples/layout-across-builds/
---

# Layout across builds

This script lays out 10 dental arches on as many Form 4 builds as they need, oldest first, and saves
each build as a `.form` file.

[View on GitHub](https://github.com/Formlabs/formlabs-api-python/tree/v1.0.0-alpha.1/examples/layout-across-builds) [Download layout-across-builds.zip](https://github.com/Formlabs/formlabs-api-python/releases/download/v1.0.0-alpha.1/layout-across-builds.zip)

For each build, the script:

1. Opens `arches.form` with `open_form_file` and deletes the arches earlier builds took with
   `delete_models`.
2. Calls `auto_layout_models` with `lock_rotation` and a fixed `seed`.
3. If the arches don't all fit, deletes the newest and tries again.
4. Saves the build with `save_form_file`.

[Layout modes](https://developer.formlabs.com/examples/layout-modes.md) shows each `auto_layout_models` option on its own.
[Pack across builds](https://developer.formlabs.com/examples/pack-across-builds.md) does the same for SLS builds, where `auto_pack_models`
sets aside the parts that don't fit.

![Six arches in two rows, all with their front teeth toward the front of the build platform](https://developer.formlabs.com/examples/layout-across-builds-1.png)

*Build 1: `case-2101` to `case-2106`*

![The four newest arches in two rows](https://developer.formlabs.com/examples/layout-across-builds-2.png)

*Build 2: `case-2107` to `case-2110`*

This example contains two files: `layout_across_builds.py` lays out the builds, and `arches.form`
holds 10 dental arches on a Form 4, named `case-2101` to `case-2110` in the order they arrived.

## Connect to PreForm

Make sure [PreForm is ready to accept connections](https://developer.formlabs.com/getting-started/install.md#connect-to-a-running-preform).

`main` connects to PreForm at `PREFORM_URL`:

```python
with FormlabsClient() as client:
    preform = client.preform.connect(base_url=PREFORM_URL)
```

`PREFORM_URL` defaults to `http://localhost:44388`. Set `FL_LOCAL_BASE_URL` to reach PreForm on
another port or host.

## Start each build

Each build reopens `arches.form` and deletes the arches earlier builds took:

```python
# Each build starts from every part, less the ones earlier builds took.
# PreForm resolves paths from its own working directory.
scene_id = preform.open_form_file(file=str(FORM_FILE.resolve())).scenes[0].scene_id
try:
    # Parts are named in the order they arrived, so the last one is the newest.
    models = sorted(preform.list_models(scene_id=scene_id).models, key=lambda m: m.name)
    taken = [m.id for m in models if m.name in placed]
    if taken:
        preform.delete_models(scene_id=scene_id, model_ids=taken)
    models = [m for m in models if m.name not in placed]
    if not models:
        break
```

The script stops when none remain.

## Eject the newest arch

When the arches don't all fit, `auto_layout_models` fails with `OPERATION_FAILED` and leaves the
scene unchanged. The script then deletes the newest arch and tries again:

```python
while True:
    try:
        # The arches all face the same way, so they lay out without turning.
        preform.auto_layout_models(
            scene_id=scene_id, model_ids=[m.id for m in models], lock_rotation=True, seed=42
        )
        break
    except PreFormApiError as exc:
        # OPERATION_FAILED here means the parts don't all fit together.
        if exc.code != "OPERATION_FAILED" or len(models) == 1:
            raise
        # Eject the newest part, so the oldest parts print first.
        preform.delete_models(scene_id=scene_id, model_ids=[models.pop().id])
```

The deleted arch waits for a later build, so the oldest arches print first.
`on_layout_failure="EJECT_A_MODEL_AND_RETRY"` has PreForm eject models itself, picked at random from
the `seed`.

## Save the build

`save_form_file` writes each build to its own `.form` file:

```python
    build += 1
    out = HERE / f"arches.build-{build}.form"
    preform.save_form_file(file=str(out.resolve()), scene_ids=[scene_id])
    placed |= {m.name for m in models}
    print(f"{out.name}: {', '.join(m.name for m in models)}")
finally:
    preform.delete_scene(scene_id=scene_id)
```

## Run the example

In a terminal, run the script from the folder you unzipped. With pip, [install the Formlabs SDK](https://developer.formlabs.com/getting-started/install.md)
first; with [uv](https://docs.astral.sh/uv/getting-started/installation/), `uv run` installs it from the
example's `pyproject.toml`.

**pip:**

```bash
python layout_across_builds.py
```

**uv:**

```bash
uv run layout_across_builds.py
```

The script writes `arches.build-1.form`, `arches.build-2.form`, and so on next to `arches.form`. To
lay out your own parts, change `FORM_FILE`.

```
arches.build-1.form: case-2101, case-2102, case-2103, case-2104, case-2105, case-2106
arches.build-2.form: case-2107, case-2108, case-2109, case-2110
```

## What's next

- [Layout modes](https://developer.formlabs.com/examples/layout-modes.md)
- [Pack across builds](https://developer.formlabs.com/examples/pack-across-builds.md)
- [Serial numbers](https://developer.formlabs.com/examples/serial-numbers.md)
