# SDK: Pictures

> picture() is a layer that shows a still (PNG, JPEG, WebP, AVIF, GIF or SVG) in CSS's terms. It is a graphic layer of the layer contract (layers.md), so a video's part, a deck's component and a doc's component draw it alike. footage() of a still is the same layer (below). A deck's own pictures keep PowerPoint's crop (slides.md), worked out from the same geometry.

Source: https://allyhub.com/docs/reference/sdk/pictures · AllyHub 0.10.0
Index of all docs: https://allyhub.com/llms.txt

```ts file=launch/film/film.ts


  format: "9x16",
  parts: () => [
    part({
      key: "open",
      dur: 3,
      layers: [
        picture({ src: plate, fit: "cover", position: [0.62, 0.4] }),
        picture({
          src: "./product.png",
          box: [0.1, 0.55, 0.8, 0.35],
          fit: "contain",
          radius: 32,
        }),
      ],
    }),
  ],
});
```

| Option | Type | Default | What it is |
| --- | --- | --- | --- |
| `src` | an import, or a path from the module | (required) | The still |
| `box` | `[x, y, w, h]`, fractions of the layer's frame | the whole frame | Where it shows; nothing outside it |
| `fit` | `"cover"`, `"contain"`, `"fill"`, `"none"` | `"cover"` | CSS's `object-fit` |
| `position` | `[x, y]`, shares of the picture | `[0.5, 0.5]` | CSS's `object-position` in percentages: the point at `x`, `y` of the picture lies at `x`, `y` of the box |
| `crop` | `[x, y, w, h]`, fractions of the source | none | The part of the source fitted, as the whole picture would be; nothing outside it shows |
| `mask` | `"ellipse"`, a picture, or a CSS `mask-image` | none | `"ellipse"`: the ellipse inscribed in the box. A picture (an import, or a path with an image's extension): its alpha masks the box. Anything else is CSS: `"linear-gradient(black 60%, transparent)"`. Or a mask's object, every layer's ([image.md](https://allyhub.com/docs/reference/sdk/image.md)): its density, feather, inversion, or a path; laid over the box |
| `radius` | px of the frame, or a CSS `border-radius` | none | The box's corners |
| `blendMode` | Photoshop's names ([image.md](https://allyhub.com/docs/reference/sdk/image.md)) | `normal` | Every layer's: how it mixes with what is drawn under it, drawn on what shows of it |
| `filter` | a CSS `filter` | none | `"blur(8px) saturate(0.8)"` |
| `alt` | string | none | What a screen reader says |

Besides these, the layer options of any graphic layer: `at`, `until`, `dur`, `z` ([video.md](https://allyhub.com/docs/reference/sdk/video.md#layers)).

- **The geometry** is `placePicture` of `@allyhub/piece`, the numbers in [defaults.md](https://allyhub.com/docs/reference/sdk/defaults.md) (`PICTURE_DEFAULTS`). `none` draws a pixel of the source on a pixel of the frame.
- **Lengths** (`radius`, a `filter`'s blur) are the frame's pixels, as CSS's, not px at 1080p as footage's.
- **A blend mode** mixes with what the stage draws under it: graphic layers and other pictures. A video file's footage is not drawn by the stage in a render (it is composited after), so a picture over footage blends there with the graphics alone; the live preview blends it with the footage too.
- **Chrome draws it**, from the file alone: the same moment draws the same in order and out of order (AK-D002). A file that is not there is AK-A001; one that does not load AK-A005.

## Changing a picture's pixels

A picture's pixels are changed by AllyHub's cloud tools, each its own command (`allyhub ai-media <tool>`; `allyhub help ai-media <tool>` gives its input, its limits and its price): `generate-image`, `edit-image` (where a `mask` or a `markup` says, when given), `extend-image` and `cut-out-image` (the cut-out and its matte). A picture's parts as layers are the agent's to make: a part cut out (`cut-out-image`) and the picture without it (`edit-image` with a mask). No tool takes a model: what serves each is the cloud's to choose.

- **A picture on this computer** goes in by the address `allyhub upload` gives it.
- **What a call makes** is a new file, never the picture given changed, with its record beside it (`<file>.gen.json`: the tool, the whole input, what it returned, the credits). The same call to the same `--file` finds that file and calls nothing. Files the output names deeper (a matte, the layers) are downloaded beside it, each listed in the result.
- **Outside a mask** the model may redraw a little: what is kept exactly, and how, is the code's.
- **A Mark up note's region** is SVG path data in the pixels of the picture whose file it names.

## `footage()` of a still

`footage(still, opts)` is `picture()` with footage's options read as its: `at`, `until`, `dur`, `box` (one rectangle, or `"full"`), `fit`, `crop` (one rectangle), `reframe` (`"center"` or `{ x, y }`: its position; `"face"` throws, since a still has no face track yet), `shape: "circle"` (an ellipse mask) and `radius` (px at 1080p). A still has no time or sound of its own: any other option throws, and so do box keyframes and a box or crop per frame shape.

## A deck's pictures

A deck's picture keeps PowerPoint's model: its file stretched over its frame after `crop` (`a:srcRect`, the share cut from each side; a negative share is space left beside it). The editor's Crop menu has PowerPoint's Fill and Fit: Fill crops the picture to fill its frame, Fit fits it inside, each centred, the frame kept. Both are `placePicture`'s cover and contain written as `crop`, so a deck's picture and a `picture()` at the same point of the same plate, in frames of one shape, show the same part of it.
