# SDK: Images

> An image is any picture, or a set of pictures that ship together, each a **board** with its own size: a photo to change, a poster, a set of product pictures, a carousel (boards of one size, in order). An item is a module listed in allyhub.yaml as kind: image (project.md), and its script, which it names in image({ script }) from the module's folder (script: "./friends.{locale}.yaml"): its words, a file per language: {locale} once in the file's name stands for each (friends.en.yaml, friends.ja.yaml). An image without one has no words of its own. Two images in one folder share a script only when both name it.

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

Everything an image is made of is its code (and its script's words): its viewer shows the boards, and a person asks for a change with Mark up, which you make in the code ([below](#what-a-person-asks-for)).

A board is drawn as a still: its layers are Photoshop's (below), components, `picture()` ([pictures.md](https://allyhub.com/docs/reference/sdk/pictures.md)) and `custom()` among them, each drawn at its still moment, settled after its entrance. There is no time, speech, music or transition; a layer's `at`, `until` and `dur` count within that one moment, and `footage()` of a video file is not drawn.

```ts file=trip/friends.ts


const caption = (key: string, text: string, size: number) =>
  custom({
    key,
    mount(el) {
      el.style.cssText = `position:absolute;left:6%;bottom:8%;width:60%;color:white;font:700 ${String(size)}px var(--ak-font-display)`;
      el.textContent = text;
    },
    render: () => undefined,
  });

  script: "./friends.{locale}.yaml",
  matrix: { dims: { lang: ["en", "ja"] } },
  boards: (ctx) => [
    // The photo as it was taken: a board its own size, the photo the bottom layer.
    board({
      key: "photo",
      size: fromPicture(friends),
      layers: [
        picture({ key: "photo", src: friends }),
        caption("caption", ctx.s("trip.friends.photo.caption"), 96),
      ],
    }),
    // A square of it, its faces kept in view.
    board({
      key: "square",
      width: 1080,
      height: 1080,
      layers: [
        picture({ key: "photo", src: friends, position: [0.45, 0.35] }),
        caption("caption", ctx.s("trip.friends.photo.caption"), 64),
      ],
    }),
  ],
});
```

A picture a board starts from is never changed: a pixel edit (a matte, a part removed, the picture expanded) is a new file beside it, recorded in its `.gen.json`, which a layer then shows.

## `image()`

| Option        | Type                                  | Default                                    | What it is                                                                                  |
| ------------- | ------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------- |
| `boards`      | `(ctx) => Board[]`                    | required                                   | Its boards, in order. `ctx` is a build's context: `combo`, `s`, `asset`, `data`, `pool`     |
| `script`      | a path with `{locale}`                | none                                       | Its script, from the module's folder, with `{locale}` once in its name for each language (`./friends.{locale}.yaml`) |
| `matrix`      | `Matrix`                              | the project's languages and its script's   | Dimensions and slots, as a video's ([batches.md](https://allyhub.com/docs/reference/sdk/batches.md)): each combo is a set of the boards |
| `id`, `title`, `meta` |                               | its module's file without its extension; the script's `title` | As a video's                                                               |
| `transparent` | `boolean`                             | `false`                                    | No background: PNG, WebP and AVIF keep the alpha channel                                    |

## `board()`

| Option                   | Type                | Default                                         | What it is                                                                                         |
| ------------------------ | ------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `key`                    | `string`            | required                                        | Its name: unique in the image, its file's name, stable across combos                                |
| `size`                   | `"WxH"`             |                                                 | Its size in pixels, sides from 1 to 16384; `fromPicture(src)` is a picture's own (below)            |
| `width`, `height`        | `number`, `number \| "auto"` |                                        | Its size, instead of `size`. `"auto"`: as tall as its layers' content (below)                      |
| `minHeight`, `maxHeight` | `number`            | `BOARD_DEFAULTS` ([defaults.md](https://allyhub.com/docs/reference/sdk/defaults.md))   | An `"auto"` board's least and most height                                                           |
| `title`                  | `string`            | its key                                         | Its name for people                                                                                 |
| `layers`                 | `LayerSpec[]`       | required                                        | What it shows, back to front, each with its own `key` (a group's layers too)                         |
| `background`             | CSS colour, `"transparent"` | the image's                             | What is drawn under its layers (Photoshop's artboard background)                                    |
| `resolution`             | `number`            | `BOARD_DEFAULTS.resolution` (72)                | Pixels per inch, for print and PSD: metadata, nothing drawn changes                                 |
| `colorProfile`           | `string`            | `BOARD_DEFAULTS.colorProfile` (sRGB)            | The profile's name for print and PSD: metadata, a board is drawn in sRGB                            |

- **Every layer has a `key`**, unique on its board (AK-I003 without one, AK-I002 twice). The stage marks its element with it (`data-ak-layer`), and the facts name it: a layer of one key on several boards is compared across them.
- **`fromPicture(src)`** is a still picture's size as `size` takes it (`"4032x3024"`): a board that starts from a photo, the photo its bottom layer. A picture whose size is not known, or a video, is AK-I001.
- **An image knows no brand**: it has no look. Its stage's variables (`--ak-font-display`, `--ak-color-bg`…) are the neutral defaults; a brand's colours and fonts are the project's to import into its components.
- **`ctx.dims` is the board's own** in a layer: its width and height (its safe zone covers no edge).
- **`height: "auto"`**: the layers are laid out at the board's width and `minHeight`, the furthest their content reaches down is measured (each layer element's scroll height), and the board is laid out again that tall, at most `maxHeight`. Lay such a board out in flow; a `picture()` box is a share of the final height.

## Photoshop's layers

A board's layers follow Photoshop's model: the names of its scripting model (UXP: `blendMode`, `opacity`, `fillOpacity`, `isClippingMask` as `clipping`, `textItem`), one function a kind of layer as psd-tools has a class a kind. A video's part takes the same layers and fields (a video is a picture plus time); clipping there is a group's.

| Kind (psd-tools)            | Function                                                   | What it draws                                                                                                                        |
| --------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| pixel (`PixelLayer`)        | `picture({ key, src, … })`                                 | A still file in CSS's terms ([pictures.md](https://allyhub.com/docs/reference/sdk/pictures.md))                                                                              |
| type (`TypeLayer`)          | `textLayer({ key, textItem, box \| position })`            | Words in their style: paragraph text in a `box` (shares of the frame, wrapped) or point text from a `position`                       |
| shape (`ShapeLayer`)        | `shape({ key, shape, box, fill, stroke })`                 | Photoshop's shape tools (`rectangle` with `radius`, `ellipse`, `triangle`, `polygon` with `sides` and `starRatio`, `line`) or a `path` |
| smart object (`SmartObjectLayer`) | a component                                          | Code that draws; its declared `props` are what a person may set                                                                       |
| adjustment (`AdjustmentLayer`)| `adjustment({ key, kind, … })`                           | Changes what lies under it in its group (below)                                                                                       |
| fill (`FillLayer`)          | `fill({ key, fill })`                                      | The frame painted: `{ color }`, `{ gradient }` or `{ pattern, scale }`                                                               |
| group (`Group`)             | `group({ key, layers, … })`                                | Its layers, nested; `passThrough` unless it says otherwise                                                                            |

`textLayer()`, not `text()`: `text()` is a prop's type ([layers.md](https://allyhub.com/docs/reference/sdk/layers.md)). A type layer's words are the script's (`textItem: { contents: ctx.s("poster.title") }`), so a person retypes them and each language has its own.

### What every layer takes

| Field         | Type                                           | Default                       | What it is                                                                                                   |
| ------------- | ---------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `blendMode`   | Photoshop's names (`"multiply"`, `"softLight"`…) | `normal`, a group's `passThrough` | How it mixes with what lies under it (below)                                                             |
| `opacity`     | percent                                        | 100                           | It and its effects                                                                                           |
| `fillOpacity` | percent                                        | 100                           | What it shows without its effects                                                                            |
| `clipping`    | `boolean`                                      | `false`                       | Clipped to the layer under it among its own (Photoshop's clipping mask): a picture, a shape or a fill        |
| `mask`        | a picture, `"ellipse"`, a CSS `mask-image`, or `{ src \| path, box, mode, density, feather, invert, enabled }` | | A raster mask (a picture's alpha or, `mode: "luminance"`, its grey) or a vector mask (SVG path data in the board's pixels); `feather` is a Gaussian's standard deviation, px |
| `effects`     | `{ dropShadow, innerShadow, outerGlow, innerGlow, bevelEmboss, satin, colorOverlay, gradientOverlay, patternOverlay, stroke }` | Photoshop's (`EFFECT_DEFAULTS`) | The layer styles, each `{ enabled, blendMode, opacity, … }` with Photoshop's numbers (`size`, `distance`, `angle`, `spread`, `choke`, `depth`, `altitude`…) |
| `transform`   | `{ rotation, flipH, flipV }`                   | none                          | Turned (degrees, clockwise) and flipped about its box's centre                                              |
| `visible`     | `boolean`                                      | `true`                        | `false`: not drawn, nor measured                                                                            |

These are layer options: no component has a prop of these names. Every default is in [defaults.md](https://allyhub.com/docs/reference/sdk/defaults.md).

### Drawn by Chrome, or refused

Each field is drawn by CSS and SVG filters in the pinned Chrome, the same every time (AK-D002 checks it). What Chrome cannot draw exactly is AK-I007, with why; nothing is drawn near enough.

- **Blend modes** are `mix-blend-mode`, whose formulas are the W3C Compositing spec's, taken from Adobe's PDF Reference: `normal`, `darken`, `multiply`, `colorBurn`, `lighten`, `screen`, `colorDodge`, `overlay`, `softLight`, `hardLight`, `difference`, `exclusion`, `hue`, `saturation`, `color`, `luminosity`; a group's `passThrough` makes no group of its own. Refused: `dissolve` (random), `darkerColor` and `lighterColor` (a whole pixel chosen by luminance), `linearDodge` (CSS's `plus-lighter` differs wherever the layer is not opaque), `linearBurn`, `vividLight`, `linearLight`, `pinLight`, `hardMix`, `subtract` and `divide` (no CSS mode, and a layer's filter cannot read what is under it). A `fillOpacity` under 100 with `colorBurn`, `colorDodge` or `difference` (Photoshop applies it inside the blend), an adjustment's blend other than `normal`, and a `passThrough` group that fades, is masked or has effects while one of its layers is an adjustment or blends otherwise are refused too.
- **Effects and fill opacity** are one SVG filter on the layer, bottom to top: the drop shadow and the outer glow under what it shows (knocked out under it), then the pattern, gradient and colour overlays, the satin, the inner glow, the inner shadow and the bevel over it, each cut to its pixels. `size` is a blur's radius (twice the Gaussian's standard deviation), `spread` and `choke` divide its alpha by 1 − them, the light's `angle` is Photoshop's (counter-clockwise from the right). An effect under the layer blends as `normal` (or as `multiply` or `darken` in black, `screen` or `lighten` in white, which are the same); the bevel is the smooth inner bevel (feDiffuseLighting); the stroke is a type layer's glyphs' (outside or about them) or a shape's path's (inside, about or outside it), with neither an inner effect nor a `fillOpacity` under 100 beside it. A gradient's `angle` and `diamond` styles are refused on an overlay and on a shape (SVG has no such gradient); a fill layer draws `angle` as CSS's conic gradient.
- **Adjustments** are an SVG filter on what lies under them (`backdrop-filter`), in sRGB, each worked out at every one of a channel's 256 values: `levels` (inputs, the midtones' gamma, outputs; each channel, then `rgb`), `curves` (a natural cubic spline through the points, flat beyond them), `exposure` (in linear light), `brightnessContrast` (the legacy one: `useLegacy: false` is refused, as Photoshop's current one is not published), `hueSaturation` (CSS's `hue-rotate` and `saturate` matrices, lightness towards white or black; `colorize` refused), `vibrance` (each channel moved from the luminance by v·(1 − max + min)), `colorBalance` (GIMP's tonal weights a channel), `blackAndWhite` (min + (mid − min)·secondary + (max − mid)·primary, the sliders' known formula), `photoFilter` (the colour multiplied in at its density), `invert`, `threshold` and `gradientMap` (both on Rec. 601's luminance). `preserveLuminosity` adds back what the luminance changed by. Each intermediate is 8 bits a channel. These are AllyHub's stated formulas where Photoshop publishes none: a PSD (step 3) carries the numbers, and Photoshop draws them its own way.
- **Clipping** draws the base and the layers clipped to it in one group with the base's blend and opacity, each clipped layer masked by the base's own shape: a picture's shown pixels, a shape's path, a fill's frame. A type layer or a component as a base is refused (its pixels are HTML, which a mask cannot read), and so is a base with a mask, a turn, a filter or a radius of its own.

## Words

The script is every kind's ([project.md](https://allyhub.com/docs/reference/sdk/project.md)): a board's words under `boards`, its key as the `id` and its layers' words by name under `text`, words several boards share under the script's own `text`, all under the image's prefix (`trip.friends.photo.caption` for `trip/friends`'s board `photo`).

```yaml fragment
title: Friends
boards:
  - id: photo
    text: { caption: "The four of us, Lisbon" }
```

## What a person asks for

An image's viewer shows every board of every version, each drawn live, to zoom, pan, mark up and export; it changes nothing. A person who wants something changed marks it up: the mark reaches you with each layer under it (its key, the line of the module that names it, its words, its picture) and the mark as a region of the layer's pixels, the board's and a picture's own file's (which `allyhub ai-media edit-image` takes as its mask). You make the change in the module, or its script for words, and the viewer draws it.

## Check, frames, inspect and render

- `allyhub check` reports what cannot be drawn: a size that does not exist (AK-I001), a name used twice (AK-I002), a layer without a name (AK-I003), an image with no boards (AK-I005), what Chrome cannot draw exactly (AK-I007), and what any version reports: a picture that does not load (AK-A005), a fallback font (AK-L006), text the board's edge cuts (AK-L002), a board drawn differently in order and out of order (AK-D002).
- `allyhub frames <image>` draws every board on one sheet, each named by its key and size; `--part <key>` one board at its own size.
- `allyhub inspect <image>` gives `board` (each board's size and where it came from), `board-consistency` (a named layer's box, cap height and colour on every board that has it, and their spread, ΔE in OKLab), `picture-scale` (a picture's source pixels against the board pixels they fill), `overset` (a type layer's words its paragraph box does not hold: its lines and characters and those past the box's bottom, how far past; the box does not cut them, so this is a fact, not a rule), `generated`, `text-contrast` and the layout facts of one frame for each board.
- `allyhub render <image>` makes a PNG a board (`<item>.<combo>/<key>.png`); `--type jpeg`, `webp` and `avif` the same in those; `pdf` one file, a page a board at its own size, its text as text; `zip` the set, each board a PNG. `--param quality=…` (0–100) sets JPEG, WebP and AVIF quality ([defaults.md](https://allyhub.com/docs/reference/sdk/defaults.md)); `psd` a layered Photoshop file a board (below).
- A board's picture larger or smaller than the board, its layout kept: `--param scale=2` (0.25 to 4), or `width=…` or `height=…` in pixels (the other side in proportion, a scale for each board). Chrome draws it at that scale, so type and shapes are sharp; a picture has only the pixels its file has (`picture-scale` in `allyhub inspect`). A picture is at most 16384 px a side. A board of another shape is another board, in the code.
- `--param max-kb=…` keeps each board's JPEG, WebP or AVIF at most that many KB, at the best quality under it, which the render says (`chosen`); one that is over it at every quality, or a PNG over it (a PNG keeps every pixel), is not made, and the render says why.

## PSD: out and in

`allyhub render <image> --type psd` writes a Photoshop file a board and combo (`<item>.<combo>/<key>.psd`; `--param psd=psb` the large format, which no board needs: a PSD holds 30000 px a side). The board is an artboard with its background, `resolution` and the name of its `colorProfile`; its render is the file's composite. Each layer is a Photoshop layer of its kind, named by its key, with its `visible`, `opacity`, `fillOpacity`, `blendMode`, `clipping`, `mask` and `effects`, groups nested:

| Layer | In the PSD |
| --- | --- |
| `picture()` | a pixel layer: its pixels as drawn, with its transform |
| `textLayer()` | a type layer Photoshop can edit: its words, the font by a PostScript name made from its family and weight (`Inter-Bold`), size in points at the board's resolution, colour, tracking, leading, capitals, underline, justification, indents and spacing, a box or a point; its pixels as drawn, which Photoshop redraws on opening (it asks to update the text layers) |
| `shape()` | a shape layer: its path, its fill (a colour or a gradient) and its stroke; a pattern fill a pixel layer with its path as a vector mask |
| `fill()` | a fill layer (a colour or a gradient); a pattern fill a pixel layer |
| `adjustment()` | Photoshop's adjustment layer, its numbers as written |
| a component | a smart object holding its pixels as drawn; its code and props are not in the file |
| `group()` | a group, `passThrough` unless it says otherwise |

The pixels of a layer are drawn by Chrome alone, without what Photoshop applies itself (blend, opacity, mask, effects, clipping), so Photoshop draws effects, blends and adjustments by its own formulas: where it publishes none (Hue/Saturation, Vibrance, Color Balance, Black & White, Photo Filter, Brightness/Contrast) or draws its own way (layer styles, a mask's feather, text), the file shows near, not exact. `render` says each such layer (`fidelity` in `--json`: `approximate`, `pixels` or `omitted`). The same board writes the same bytes.

`allyhub image import <file.psd> --to <module>.ts` makes an image of a Photoshop file, named after its module: `<name>.ts`, which names `<name>.{locale}.yaml` for its script; a board an artboard (else its canvas), each layer of its kind with its fields, a pixel layer's pixels beside the module (`<board>-<layer>.png`), a type layer's words in the script (`<name>.<lang>.yaml`), each layer's key its PSD name in lower case with hyphens, the name itself a comment beside it where it is not the key (a PSD exported names its layers by their keys); the file as it was beside them. A picture or the file as it was takes a name no file there has; the import never writes over a file that is there. What AllyHub does not hold or refuses (AK-I007) is kept as pixels where the layer has them, drawn near (a blend mode as normal, a type layer by CSS), or left out, and the command lists every one. A smart object comes in as its pixels.
