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.
image()
Section titled “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): 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()
Section titled “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) |
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 assizetakes 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.dimsis 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 andminHeight, the furthest their content reaches down is measured (each layer element’s scroll height), and the board is laid out again that tall, at mostmaxHeight. Lay such a board out in flow; apicture()box is a share of the final height.
Photoshop’s layers
Section titled “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) |
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.
What every layer takes
Section titled “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.
Drawn by Chrome, or refused
Section titled “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’spassThroughmakes no group of its own. Refused:dissolve(random),darkerColorandlighterColor(a whole pixel chosen by luminance),linearDodge(CSS’splus-lighterdiffers wherever the layer is not opaque),linearBurn,vividLight,linearLight,pinLight,hardMix,subtractanddivide(no CSS mode, and a layer’s filter cannot read what is under it). AfillOpacityunder 100 withcolorBurn,colorDodgeordifference(Photoshop applies it inside the blend), an adjustment’s blend other thannormal, and apassThroughgroup 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.
sizeis a blur’s radius (twice the Gaussian’s standard deviation),spreadandchokedivide its alpha by 1 − them, the light’sangleis Photoshop’s (counter-clockwise from the right). An effect under the layer blends asnormal(or asmultiplyordarkenin black,screenorlightenin 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 afillOpacityunder 100 beside it. A gradient’sangleanddiamondstyles are refused on an overlay and on a shape (SVG has no such gradient); a fill layer drawsangleas 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, thenrgb),curves(a natural cubic spline through the points, flat beyond them),exposure(in linear light),brightnessContrast(the legacy one:useLegacy: falseis refused, as Photoshop’s current one is not published),hueSaturation(CSS’shue-rotateandsaturatematrices, lightness towards white or black;colorizerefused),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,thresholdandgradientMap(both on Rec. 601’s luminance).preserveLuminosityadds 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: Friendsboards: - id: photo text: { caption: "The four of us, Lisbon" }What a person asks for
Section titled “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
Section titled “Check, frames, inspect and render”allyhub checkreports 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>givesboard(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-contrastand the layout facts of one frame for each board.allyhub render <image>makes a PNG a board (<item>.<combo>/<key>.png);--type jpeg,webpandavifthe same in those;pdfone file, a page a board at its own size, its text as text;zipthe set, each board a PNG.--param quality=…(0–100) sets JPEG, WebP and AVIF quality (defaults.md);psda 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), orwidth=…orheight=…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-scaleinallyhub 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
Section titled “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.