# Blender shots

Real product shots from a 3D model: the recipe, the four kinds, the stills judged first, and the clips with alpha a scene plays.

A rapid shot is a model and a recipe, rendered by Blender as frames with a transparent ground, so a scene can place the product over any field. A recipe is data, like a style. When a storyboard lists shots, the job renders them before the scenes that show them are built.

You need [Blender](/docs/install#requirements), and only for a video that plans a shot. rapid runs `/Applications/Blender.app`, or the binary in `RAPID_BLENDER`. `rapid setup --check` doesn't look for it, so a missing Blender first shows as a failed node or command.

## A recipe

Put the model under `assets/` (STL, OBJ, or GLB) and write the recipe as `shots/<id>.json`:

```json
{
  "schema_version": 1,
  "id": "pendant",
  "kind": "turntable",
  "model": "assets/pendant.stl",
  "size": 0.03,
  "frames": 90,
  "fps": 30,
  "width": 1080,
  "height": 1080,
  "engine": "cycles",
  "finish": "mirror",
  "metal": "#D9D4CC"
}
```

`width` and `height` are the size the shot sits at in the frame, not the frame's. `frames` at the format's rate covers the scenes that show it.

| Field | Type | Default | Notes |
|---|---|---|---|
| `schema_version` | `1` | required | |
| `id` | id | required | names `renders/shots/<id>/` |
| `kind` | `turntable`, `clay-metal`, `macro`, `build` | required | |
| `model` | path | required | in the project |
| `frames` | 1–3600 | required | |
| `width`, `height` | 1–4096 | required | |
| `fps` | 1–120 | `30` | |
| `size` | metres, up to 10 | `0.03` | the piece's real longest side; it scales the aperture, focus, and shadows |
| `engine` | `eevee`, `cycles` | `eevee` | EEVEE takes a fraction of a second a frame; Cycles is for hero metal and glass |
| `lean` | degrees, −90 to 90 | `6` | how far the piece leans back: about 6 for a small pendant, about 40 for a long chain |
| `camera.elevation` | degrees, −60 to 80 | `12` | the camera's height above the piece |
| `camera.lens` | mm, 10–300 | `100` | |
| `fill` | 0.1–1 | `0.76` | how much of the frame the piece fills at its widest |
| `finish` | `satin`, `mirror` | `satin` | satin for organic sculpts, mirror for faceted ones |
| `metal` | `#rrggbb` | `#D9D4CC` | |
| `turns` | up to 10 | `1` | turns over the clip |
| `samples` | 1–4096 | `64` | Cycles' samples |

## The kinds

| Kind | The shot | Its own fields |
|---|---|---|
| `turntable` | one turn, eased to dwell front and back and whip through edge-on, so the piece never reads as a flat stick | |
| `clay-metal` | the same turn twice, in clay and in metal, matched frame for frame, for a scene to sweep from one to the other | |
| `macro` | an insert close on one detail, the camera pushing in slowly as the piece drifts under it. Cut in and out hard | `angle`, `focus`, `zoom`, `drift` |
| `build` | the piece assembles from its named parts, each seating at its second, while it swings about its hero angle | `angle`, `swing`, `parts` |

| Field | Default | Notes |
|---|---|---|
| `angle` | `35` | degrees: 0 is the front, 35 the hero three-quarter |
| `focus` | `[0, -0.5, 0]` | the detail, in shares of the piece's box from its centre, each −0.5 to 0.5 |
| `zoom` | `0.3` | how much of the piece the frame spans, as a share of its longest side |
| `drift` | `8` | degrees the piece drifts over the clip |
| `swing` | `40` | degrees a build swings about its angle over the clip |
| `parts` | `[]` | `{ name, at }`: an object's name in the model and the second it seats. A build needs at least one; unnamed objects are seated throughout. Use a GLB or OBJ with one object per part |

A `turntable` or a `clay-metal` is a starting point like any other: change the recipe to fit the piece, and render more than one shot of it.

## In a video

The storyboard lists each recipe with the scenes that show it:

```json
{ "shots": [{ "recipe": "shots/pendant.json", "scenes": ["reveal", "close"] }] }
```

Each shot runs through the job in order, and the scenes showing it wait until it settles. Blender takes the `gpu` lane, one process at a time:

1. **Key stills.** `front`, `hero`, `side`, and `back`, at 0, 35, 90, and 180 degrees, in `renders/shots/<id>/stills/`.
2. **Review.** A reviewer judges the stills into `reviews/shot-<id>-k<try>.json`. A `revise` has the storyboarder change the recipe and renders fresh stills, two tries in all. After the last, the frames render from the last recipe, and the choice is recorded.
3. **Frames.** Each pass in chunks estimated under nine minutes each, every chunk a node of its own.
4. **Clips.** Each pass as VP9 with alpha, `<pass>.webm`, and `manifest.json`.

A shot's nodes are keyed by its recipe and the model's hash, so a changed model renders again.

## By hand

```sh
rapid shot shots/pendant.json --stills     # the key stills first
rapid shot shots/pendant.json              # the whole shot
```

See [`rapid shot`](/docs/cli#rapid-shot) for rendering one pass or a range of frames.

## In a scene

A shot is a clip like any other. It plays over the field with its transparency, and the runtime seeks it to the frame:

```html
<video src="../renders/shots/pendant/metal.webm" data-el="pendant" data-role="object" data-start="0.4"></video>
```

Look at `stills/` to see the piece, and `manifest.json` for its size and frames. For a `clay-metal` shot, stack `clay.webm` and `metal.webm` in one box and sweep a mask from one to the other. See [video clips](/docs/writing-scenes#video-clips).

The shot is the scene's hero: put it in the key frame's `assets`, and never redraw the product in CSS.