Formlabs Developers
Download PreForm Insider to start developing with the PreForm API.

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 Download 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

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

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.

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 first; with uv, uv run installs it from the example's pyproject.toml.

  1. Put serials on the cubes:

    Terminal
    python serial_numbers.py cubes
    Terminal
    uv run serial_numbers.py cubes
  2. Put serials on the arches:

    Terminal
    python serial_numbers.py arches
    Terminal
    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#