Skip to content
Get started

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.

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).

A board is drawn as a still: its layers are Photoshop’s (below), components, picture() (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.

import { custom } from "@allyhub/sdk";
import { board, fromPicture, image, picture } from "@allyhub/sdk/image";
import friends from "../assets/media/photos/friends.jpg";
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,
});
export default image({
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.

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): 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
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) 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.

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)
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). 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.

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.

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.

The script is every kind’s (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).

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

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.

  • 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); 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.

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.

Was this page helpful?