---
title: "Scene"
description: "A scene is the server-side state of one build, the models and settings a job is created from."
url: https://developer.formlabs.com/core-concepts/scene/
---

# Scene

A *scene* is the server-side state of one build: a printer type, a material, a layer
thickness, a print setting, and the models placed in the printer's build volume. It's
the same thing you see in the PreForm window. Every PreForm API call that
changes a model names the scene it belongs to by its `scene_id`.

One PreForm process holds several scenes, so a script can prepare several builds in
one session. For example, a service bureau that receives orders in two materials
creates one scene per material and imports each order into the matching scene.

![The PreForm window with two models on the build platform, one of them selected.](https://developer.formlabs.com/assets/images/support/preform_scene.png)

*A scene holds everything that prints in one build on one printer.*

## What a scene holds

A scene ties the models to the settings they print with:

```mermaid
flowchart LR
    subgraph scene["Scene (scene_id)"]
        settings["Scene settings: machine type, material, layer thickness, print setting"]
        m1["Model"]
        m2["Model"]
        m3["Model"]
    end
    settings -. applies to .-> m1 & m2 & m3
    scene -- "slice" --> job["Job"]
    scene -- "save" --> form[".form file"]
```

- **Scene settings:** The machine type, such as `FORM-4-0`, the material code, such as
  `FLGPGR05`, the layer thickness, and the print setting. Together they select one
  print setting that Formlabs ships.
- **Models:** Each imported mesh, with its position, orientation, and supports. For
  more information, see [Model](https://developer.formlabs.com/core-concepts/model.md).
- **Derived values:** The build volume, which comes from the machine type, and the
  material usage and layer count, which PreForm recalculates as the models change.
  For an example that prices a build from its material usage, see
  [Instant quote](https://developer.formlabs.com/examples/instant-quote.md).

In PreForm, the **Summary** section of the side panel shows the derived values:

![The Summary section of the PreForm side panel for a Form 4 build in Grey V5, with the print time, the layer count, and the resin volume.](https://developer.formlabs.com/assets/images/screenshots/scene-summary-panel.png)

*The layer count and resin volume in **Summary** are the scene's `layer_count` and `material_usage`.*

In PreForm, the scene settings are the choices on the **Job Setup** screen:

![The PreForm Job Setup screen with four steps: choose printer, choose material, choose layer thickness, and choose print settings.](https://developer.formlabs.com/assets/images/support/job-setup-preform-jan-2023.png)

*The Job Setup screen in PreForm sets the same values as `create_scene`.*

For more information, see
[Introduction to the PreForm Print Settings Editor](https://formlabs.com/support/Introduction-to-the-Print-Settings-Editor/).

## Create a scene

The `create_scene` method takes the scene settings and returns the new scene:

**SDK:**

```python
# PreForm rejects a combination that Formlabs doesn't ship.
scene = preform.create_scene(
    machine_type="FORM-4-0",
    material_code="FLGPGR05",
    layer_thickness_mm=0.1,
)
# create_scene answers with the new scene's id and settings; get_scene has the rest.
build_volume = preform.get_scene(scene_id=scene.scene_id).build_volume
print(scene.scene_id, build_volume.dimensions_mm)
```

**curl:**

**macOS:**

```bash
curl -X POST http://localhost:44388/v1/scene/create/ \
    -H "Content-Type: application/json" \
    -d '{"machine_type": "FORM-4-0", "material_code": "FLGPGR05",
         "layer_thickness_mm": 0.1}'
```

**Windows:**

```powershell
@{ machine_type = "FORM-4-0"; material_code = "FLGPGR05"; layer_thickness_mm = 0.1 } |
    ConvertTo-Json |
    curl.exe -X POST http://localhost:44388/v1/scene/create/ `
        -H "Content-Type: application/json" `
        -d "@-"
```

The combination must be one that Formlabs ships, or PreForm rejects it. To find a
valid combination, see the
[Print Settings](https://developer.formlabs.com/api-reference/print-settings.md) endpoints.

## How long a scene lives

A scene lives in the memory of the PreForm process until you delete it:

```python
# Closing PreForm discards every scene. PreForm Server also keeps at most 30.
for listed in preform.list_scenes().scenes:
    print(listed.id, len(listed.models))

preform.delete_scene(scene_id=scene.scene_id)
```

A freshly started PreForm holds one default scene. Deleting the default scene resets
it to an empty scene with the same settings, and deleting any other scene removes it.

PreForm Server keeps at most 30 scenes and deletes the least recently used one when a
new scene exceeds the limit. PreForm has its own limit on how many scenes exist at
once: when it's reached, `create_scene` fails with `BUILD_VOLUME_LIMIT_EXCEEDED`, and
you must delete a scene before you create another.

Closing PreForm discards every scene, so save a scene you need later as a `.form`
file. For more information, see the [Scenes](https://developer.formlabs.com/api-reference/scenes.md) endpoints.

## What's next

- [Print settings](https://developer.formlabs.com/core-concepts/print-settings.md)
- [Automatic layout settings for SLA printing](https://formlabs.com/support/Automatic-layout-settings-for-SLA-printing/)