---
title: "Pack modes"
description: "Pack 30 boats with each model lock, from FREE to LOCKED_ROTATION_FREE_TRANSLATION, using update_models and auto_pack_models, and compare the builds."
url: https://developer.formlabs.com/examples/pack-modes/
---

# Pack modes

This script packs 30 3DBenchy boats in a Fuse 1 build volume in one of four modes, and saves the
result as a `.form` file. A lock belongs to each part. Each mode sets the same lock on every boat,
so the four builds compare side by side.

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

For each mode, the script:

1. Opens `parts.form` with `open_form_file`.
2. Sets each part's lock with `update_models`.
3. Calls `auto_pack_models` with a fixed `seed`.
4. Saves the build with `save_form_file`.

[Layout modes](https://developer.formlabs.com/examples/layout-modes.md) does the same for SLA layout options.
[Pack across builds](https://developer.formlabs.com/examples/pack-across-builds.md) packs more parts than fit in one build volume, and
[Web SLS Packer](https://developer.formlabs.com/examples/web-sls-packer.md) lets you choose each part's lock in a browser app.

![Thirty boats tumbled at every angle](https://developer.formlabs.com/examples/pack-modes-free.png)

*`free`: `FREE`*

![Thirty boats spun at different angles, some upside down](https://developer.formlabs.com/examples/pack-modes-flip.png)

*`flip`: `LOCKED_XY_FLIP_ENABLED`*

![Thirty boats the right way up, spun at different angles](https://developer.formlabs.com/examples/pack-modes-spin.png)

*`spin`: `LOCKED_XY_ROTATION_FREE_TRANSLATION`*

![Thirty boats the right way up, all facing the same way](https://developer.formlabs.com/examples/pack-modes-upright.png)

*`upright`: `LOCKED_ROTATION_FREE_TRANSLATION`*

This example contains three files: `pack_modes.py` packs the boats, `parts.form` holds 30 3DBenchy
boats on a Fuse 1, all upright, and `ATTRIBUTION.md` credits the boat.

The #3DBenchy model, from [3DBenchy.com](https://www.3dbenchy.com/), is released under
[CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/).

## Choose the lock

Each mode is a lock for `update_models`:

```python
# Each mode locks every part the same way before the pack. Every mode passes the same
# seed, so a run of a mode always gives the same build.
MODES = {
    # Packing may move and turn each part any way.
    "free": "FREE",
    # Packing may spin each part about z and turn it upside down, but never tip it
    # on its side.
    "flip": "LOCKED_XY_FLIP_ENABLED",
    # Packing may spin each part about z, but keeps it the right way up.
    "spin": "LOCKED_XY_ROTATION_FREE_TRANSLATION",
    # Packing may move each part, but never turns it.
    "upright": "LOCKED_ROTATION_FREE_TRANSLATION",
}
```

A lock is set per part. `update_models` sets it on the parts in `model_ids`, or on every part when
`model_ids` is left out, so one build can mix locks: some parts kept upright, the rest free. Both
`auto_pack_models` and `auto_layout_models` respect each part's lock:

| Lock | What packing may do |
| --- | --- |
| `FREE` | Move and turn the model any way. The default |
| `LOCKED_XY_FLIP_ENABLED` | Move it, spin it about z, and turn it upside down |
| `LOCKED_XY_ROTATION_FREE_TRANSLATION` | Move it and spin it about z |
| `LOCKED_ROTATION_FREE_TRANSLATION` | Move it without turning it |
| `FULLY_LOCKED` | Nothing: the model stays where it is |

## 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.

## Lock and pack the parts

`update_models` leaves out `model_ids`, so it sets the mode's lock on every part, and
`auto_pack_models` packs them:

```python
# PreForm resolves paths from its own working directory.
scene_id = preform.open_form_file(file=str(FORM_FILE.resolve())).scenes[0].scene_id
try:
    # A lock belongs to each part. Without model_ids, update_models sets this
    # lock on every part, and auto_pack_models packs every part.
    preform.update_models(scene_id=scene_id, lock=MODES[mode])
    preform.auto_pack_models(scene_id=scene_id, seed=7)
    preform.save_form_file(file=str(out.resolve()), scene_ids=[scene_id])
finally:
    preform.delete_scene(scene_id=scene_id)
```

Every mode passes `seed=7`, so each run of a mode gives the same build.

## 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 pack_modes.py free
```

**uv:**

```bash
uv run pack_modes.py free
```

The modes are `free`, `flip`, `spin`, and `upright`. The script writes `parts.<mode>.form` next to
`parts.form`. To try another lock, add a mode to `MODES`.

```
-> parts.free.form
```

## 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)
- [Web SLS Packer](https://developer.formlabs.com/examples/web-sls-packer.md)
