---
title: "Serial numbers"
description: "Label every part in a build with a serial number through label_models, placed in the model's own coordinates so the part's orientation doesn't matter."
url: https://developer.formlabs.com/examples/serial-numbers/
---

# Serial numbers

This script labels every part in a build with a serial number through the PreForm API's
`label_models`. Each label is placed in the model's own coordinate system, so the part's orientation
in the scene doesn't matter.

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

For each build, the script:

1. Opens the `.form` file with `open_form_file` and lists its parts with `list_models`.
2. Numbers the parts in reading order on the build platform and fills in the serial template.
3. Moves the label's anchor and directions from the part's own coordinates to the build platform's,
   using the part's `position` and `orientation`.
4. Calls `label_models`, which projects the label from the anchor onto the part's surface.
5. Saves the labeled build with `save_form_file`.

The serial template and the label's placement come from `BUILDS` in the script, which stands in for the
part-numbering rules of a quality system.

![Nine cubes in a 3 by 3 grid on a Form 4 build platform, numbered 01 to 09 in large raised digits on their top faces](https://developer.formlabs.com/examples/serial-numbers-cubes.png)

*`cubes`: `{n:02d}` on the top face*

![A dental arch with the serial number A261029-005 on the outside of its base, the text running parallel to the build platform](https://developer.formlabs.com/examples/serial-numbers-arch.png)

*`arches`: `A{date:%y%m%d}-{n:03d}` on the base*

This example contains three files: `serial_numbers.py` adds the labels, and `cubes.form` and
`arches.form` are the sample builds: nine cubes numbered on the top face, and seven dental arches on
a Form 4 with a serial on the side.

## Describe a build

Each build names its `.form` file, a serial template, the label's size, and where the label goes:

```python
@dataclass
class Build:
    form_file: str
    # A Python format string, filled in with the print date and the part's number.
    serial: str
    font_size_mm: float
    depth_mm: float
    # Where the label goes, in the coordinates the part's mesh file was made in. PreForm
    # projects the label from anchor, a point outside the part, onto the part's surface.
    # The label faces along facing, and its text reads along reading.
    anchor: Vector
    facing: Vector
    reading: Vector


BUILDS = {
    # 15 mm cubes with their origin at the center of the base, numbered on the top face.
    "cubes": Build("cubes.form", "{n:02d}", font_size_mm=8.0, depth_mm=1.0,
                   anchor=(0, 0, 30), facing=(0, 0, 1), reading=(1, 0, 0)),
    # Dental arches with the base on z = 0, the back on y = 0, and the front teeth
    # toward -y. The serial goes on the -x side of the base and reads toward the front
    # teeth, parallel to the build platform.
    "arches": Build("arches.form", "A{date:%y%m%d}-{n:03d}", font_size_mm=3.0, depth_mm=0.6,
                    anchor=(-50, -20, 2.5), facing=(-1, 0, 0), reading=(0, -1, 0)),
}
```

The template is a Python format string, filled in with the print date and the part's number in the
build. The cubes get their place in the grid, 01 to 09. The arches get a serial such as
`A261029-001`: a production line, the print date, and the part's number.

`anchor`, `facing`, and `reading` are in the part's own coordinates, the ones its mesh file was made
in. Dental design software writes every arch in the same frame, so one anchor fits them all.

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

## Open the .form file

`open_form_file` returns the file's scene, and `list_models` gives each model's name, position, and
orientation:

```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:
    models = preform.list_models(scene_id=scene_id).models
    # Number the parts in reading order: back row first, left to right.
    models.sort(key=lambda m: (-round(m.position.y), m.position.x))
    for n, model in enumerate(models, start=1):
        serial = build.serial.format(date=datetime.date.today(), n=n)
```

The parts are numbered back row first, left to right, so a person unloading the build finds them in
order.

## Add the label

`label_models` adds the serial to the model, at an anchor and directions turned by the part's yaw
and moved by its position:

```python
# A model's position is where its mesh file's origin sits on the
# platform, and its orientation turns the mesh about that origin. These
# parts print flat, so they only turn about z.
yaw = model.orientation.z
x, y, z = turn(build.anchor, yaw)
result = preform.label_models(
    scene_id=scene_id,
    model_ids=[model.id],
    label=serial,
    position=ScenePosition(x=model.position.x + x, y=model.position.y + y, z=model.position.z + z),
    # The label faces along z_direction and reads along x_direction.
    orientation=DirectionVectors(
        z_direction=list(turn(build.facing, yaw)), x_direction=list(turn(build.reading, yaw))
    ),
    font_size_mm=build.font_size_mm,
    depth_mm=build.depth_mm,
)
# A label missing some of its characters is a wrong serial.
if result.warnings:
    sys.exit(f"{model.name}: {'; '.join(result.warnings)}")
print(f"{serial:16} {model.name}")
```

PreForm places the label where a line from the anchor, against `facing`, meets the part's surface.
`label_models` raises `PreFormApiError` with `OPERATION_FAILED` if the anchor misses the part. A
label that's missing some of its characters succeeds with a warning, and the script stops on that too.

## Save the build

`save_form_file` writes the labeled copy, and the `finally` block closes the scene whether or not the
save happened:

```python
    preform.save_form_file(file=str(out.resolve()), scene_ids=[scene_id])
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`.

1. Put serials on the cubes:

   **pip:**

   ```bash
   python serial_numbers.py cubes
   ```

   **uv:**

   ```bash
   uv run serial_numbers.py cubes
   ```
2. Put serials on the arches:

   **pip:**

   ```bash
   python serial_numbers.py arches
   ```

   **uv:**

   ```bash
   uv run serial_numbers.py arches
   ```

The script writes `cubes.serials.form` or `arches.serials.form` next to the original. To number your
own builds, add a `Build` to `BUILDS`.

```
A261029-001      case-2104
A261029-002      case-2107
A261029-003      case-2106
A261029-004      case-2101
A261029-005      case-2103
A261029-006      case-2102
A261029-007      case-2105
-> arches.serials.form
```

## What's next

- [Model](https://developer.formlabs.com/core-concepts/model.md)
- [Part labels](https://developer.formlabs.com/examples/part-labels.md)
- [Layout across builds](https://developer.formlabs.com/examples/layout-across-builds.md)
