Commands

Every operation in Photo Slop is a JSON command — the same bus drives the UI, Python callbacks and AI agents.

The command bus

Nothing in the editor mutates the canvas directly. A toolbar button, a keyboard shortcut, a Python callback and an AI agent all do the same thing: submit a command.

{ "id": "any-unique-string", "type": "layer.addShape",
  "payload": { "shape": "rect", "width": 400, "height": 240, "fill": "#2f9e44" } }

From Python, set the component's command prop. The component runs it, clears command, and always answers on commandResult:

{ "id": "any-unique-string", "type": "layer.addShape", "ok": true, "data": { "layerId": "l_gpcgpdlm" } }

On failure ok is false and error explains why. Rules worth knowing:

• Each id is executed once. Re-sending an id is ignored, so a re-rendered callback cannot double-apply an edit.
• Commands run serially, in the order they arrive, even when one awaits an image load.
• batch runs several commands as one undo step and stops at the first failure.
• Every committed change updates the document, layers, selection, rev, canUndo and canRedo props.

from dash import Input, Output, State, callback
from dash_photo_canvas import ops

@callback(Output("pc-canvas", "command"), Input("add-logo", "n_clicks"), prevent_initial_call=True)
def add_logo(_):
    return ops.cmd("layer.addImage", src="https://example.com/logo.png", name="Logo", x=200, y=120)

ops.cmd(type, **payload) fills in a unique id. ops.validate(command) is a cheap structural check (an id, and a type that is one of the published agent commands); the component itself validates payload values and reports problems on commandResult.

Reference

Document and canvas

Layers

Effects

Effect types and ranges are listed in the Document Model. Where layerId is optional, the first selected layer is used.

Interactive crop

layer.crop sets a window numerically. The crop tool is the interactive version: a window the user drags and resizes on the canvas, with the rest of the image dimmed and rule-of-thirds guides. It is opened through tool.set and driven by four commands:

Keyboard: C opens the tool on the selected image layer, Enter applies, Esc cancels; a double-click on the window applies too. Any other editing command sent while the tool is open cancels it first, because the window is a proposal, not document state — view.*, document.get and export.render are allowed and leave it open.

View, tools and history

Batch

batch runs commands: [{type, payload}, …] in order as one undo step. It stops at the first failing step; earlier steps are kept. On failure the acknowledgement is ok: false with error: "batch stopped at step N: …" and data: {results, failedStep} — the per-step results up to and including the failure — so a caller (the agent loop uses this) knows exactly which steps ran.

Export

export.render renders the artboard and, depending on dest, downloads it or sends it to the server.

The result carries width, height, bytes, format and, for server destinations, a server object with the stored key (a signed url for R2; id, kind and url for the catalogue). dest: catalog fails with 401 when nobody is signed in.

Pixel selections and pixel edits (image layers)

The pixel tools act on ONE image layer's pixels in its natural pixel space. Picking a pixel tool, or sending any select.* / pixels.* command, enters pixel mode: the image loses its handles (a dashed accent frame marks it), the other layers freeze, the options bar tints, and the keyboard scopes to the SELECTION — ⌘C / ⌘X copy or cut the selected pixels, ⌘V pastes them as a new layer in the same place, ⌘J lifts them into a layer, ⌫ erases them, ⌘A / ⌘D select all / none, ⌘⇧I inverts, the arrows move the outline, Esc deselects and then leaves the mode. Picking another image in the Layers panel retargets the tools; picking anything else ends the mode. The selection is never part of the document and never exported. Points are artboard pixels unless space: "image".

A pixel edit replaces the layer's source. The new pixels ride under a blob: URL — never a data URL, which would put megabytes into every history entry and the document prop — and are uploaded through the asset endpoint in the background; the layer, the clipboard and history then move to the stable URL, so a saved project names a URL every page can resolve.

Source: /guide/commands