dymokomi/luced-2d
Source of release 0.5.0
## luced-2d's scripting API, as Maya's is to its commands: every call here is
## one editor action, done in the open document as the script runs, and the
## whole run is one undo step. A script is a Luce program — `import luced`, a
## `main` — run by the editor's Luce interpreter in a sandbox folder.
##
## Colors are sRGB, 0..1 a channel. Positions and sizes are document pixels,
## (0, 0) the top-left corner. Layers count from 0 at the bottom of the stack.
## Queries (`document_width`, `layer_names`, ...) tell the document as it was when the
## script started; what the script itself changes is not seen by them.
##
## How it works: each call prints one line, `@l2d` and the action's name and
## fields separated by tabs, which the editor reads and does. Any other line
## a script prints goes to the script console.
import document
func send(action: str, fields: list[str]):
var message = "@l2d " + action
for field in fields:
message = message + "\t" + field.replace("\\", "\\\\").replace("\t", "\\t").replace("\n", "\\n")
print(message)
# mark: What the document was =================================================================
## The document's width and height in pixels.
pub func document_width() -> int:
return document.width()
pub func document_height() -> int:
return document.height()
## The layers' names, bottom to top.
pub func layer_names() -> list[str]:
return document.layers()
## The selected layer's place in the stack.
pub func selected_layer() -> int:
return document.selected()
## Whether the document blends its colors in linear light (Color Settings'
## "Blend RGB Colors Using Gamma 1.0"); false: as sRGB values, Photoshop's default.
pub func linear_blend() -> bool:
return document.linear_blend()
## The open document's file, or "" when it was never saved.
pub func document_path() -> str:
return document.path()
# mark: Documents ============================================================================
## A new empty document of `width` by `height` pixels in its own tab.
pub func new_document(width: int, height: int):
send("new_document", [str(width), str(height)])
## Open the picture or document at `path` in its own tab.
pub func open(path: str):
send("open", [path])
## Save the document at `path` (an .l2d keeps its layers).
pub func save(path: str):
send("save", [path])
## Export the flattened picture: PNG or JPEG by the name's extension;
## `quality` 1..100 for JPEG.
pub func export(path: str, quality: int = 90):
send("export", [path, str(quality)])
## Place a picture file as a new layer, centred.
pub func place(path: str):
send("place", [path])
## Undo the last step, or redo it.
pub func undo():
send("undo", [])
pub func redo():
send("redo", [])
## Any menu command by its id, as the Settings dialog's shortcut list names
## them ("flip_horizontal", "merge_down", "inverse", ...), headless too.
## One that opens a dialog opens it; the parametric calls here are for those.
pub func run(command: str):
send("run", [command])
# mark: Layers ===============================================================================
## A new empty layer named `name` above the selected one, selected.
pub func add_layer(name: str):
send("add_layer", [name])
## Select the layer at `index` (0 the bottom).
pub func select_layer(index: int):
send("select_layer", [str(index)])
## Select the topmost layer called `name`.
pub func select_layer_named(name: str):
send("select_layer_named", [name])
pub func rename_layer(name: str):
send("rename_layer", [name])
pub func delete_layer():
send("delete_layer", [])
pub func duplicate_layer():
send("duplicate_layer", [])
pub func merge_down():
send("merge_down", [])
## Move the selected layer `steps` places up the stack (negative: down).
pub func move_layer_up(steps: int):
send("reorder", [str(steps)])
## The selected layer's opacity, 0..1.
pub func set_opacity(opacity: float):
send("set_opacity", [str(opacity)])
## The selected layer's blend mode by Photoshop's name ("Multiply", "Screen", ...).
pub func set_blend(mode: str):
send("set_blend", [mode])
pub func set_visible(visible: bool):
send("set_visible", [str(visible)])
## Move the selected layer's pixels by (`dx`, `dy`).
pub func move_by(dx: int, dy: int):
send("move_by", [str(dx), str(dy)])
## A mask on the selected layer revealing the selection (everything without one).
pub func add_mask():
send("add_mask", [])
# mark: Painting =============================================================================
## The foreground color, and the background's.
pub func set_color(red: float, green: float, blue: float):
send("set_color", [str(red), str(green), str(blue)])
pub func set_background(red: float, green: float, blue: float):
send("set_background", [str(red), str(green), str(blue)])
## The brush: its diameter in pixels, hardness and opacity 0..1.
pub func set_brush(size: float, hardness: float = 0.75, opacity: float = 1.0):
send("set_brush", [str(size), str(hardness), str(opacity)])
## Paint one stroke through `points`, x and y pairs; `erase` erases instead.
pub func stroke(points: list[float], erase: bool = false):
var fields = [str(erase)]
for value in points:
fields.append(str(value))
send("stroke", fields)
## A straight stroke from (`x0`, `y0`) to (`x1`, `y1`).
pub func line(x0: float, y0: float, x1: float, y1: float):
stroke([x0, y0, x1, y1])
## Fill the selection (the whole layer without one) with the foreground color.
pub func fill():
send("fill", [])
## Erase the selection (the whole layer without one).
pub func clear():
send("clear", [])
## A gradient from the foreground color at (`x0`, `y0`) to the background at
## (`x1`, `y1`); `radial` for a circle about the start.
pub func gradient(x0: float, y0: float, x1: float, y1: float, radial: bool = false):
send("gradient", [str(x0), str(y0), str(x1), str(y1), str(radial)])
## A text layer of `words` at (`x`, `y`), `size` points, in the foreground color.
pub func text(x: float, y: float, words: str, size: float = 48.0):
send("text", [str(x), str(y), words, str(size)])
# mark: Selections ===========================================================================
## Select a rectangle or an ellipse; `mode` 0 new, 1 add, 2 subtract, 3 intersect.
pub func select_rectangle(x: int, y: int, width: int, height: int, mode: int = 0):
send("select_rectangle", [str(x), str(y), str(width), str(height), str(mode)])
pub func select_ellipse(x: int, y: int, width: int, height: int, mode: int = 0):
send("select_ellipse", [str(x), str(y), str(width), str(height), str(mode)])
pub func select_all():
send("select_all", [])
pub func deselect():
send("deselect", [])
pub func invert_selection():
send("invert_selection", [])
## Select › Modify: grow (positive `pixels`) or shrink (negative) the
## selection, then feather its edge by `feather` pixels.
pub func modify_selection(pixels: int, feather: int = 0):
send("modify_selection", [str(pixels), str(feather)])
## Quick Mask on (`on`) or off: while on, painting edits the selection
## (black masks, white selects); turning it off makes that the selection.
pub func quick_mask(on: bool = true):
send("quick_mask", [str(on)])
## Select › Save Selection: the selection kept as alpha channel `name`.
pub func save_selection(name: str):
send("save_selection", [name])
## Select › Load Selection: alpha channel `name` as the selection; `mode` 0
## new, 1 add, 2 subtract, 3 intersect.
pub func load_selection(name: str, mode: int = 0):
send("load_selection", [name, str(mode)])
## Delete alpha channel `name`.
pub func delete_channel(name: str):
send("delete_channel", [name])
## Select › Modify › Border: a band `width` pixels wide along the selection's edge.
pub func border_selection(width: int):
send("border_selection", [str(width)])
## Select › Modify › Smooth: corners rounded and specks dropped over `radius` pixels.
pub func smooth_selection(radius: int):
send("smooth_selection", [str(radius)])
## Select › Grow (`contiguous`) or Similar: more of the colors the selection
## covers, within `tolerance` (0..255, as the magic wand's).
pub func grow_selection(contiguous: bool = true, tolerance: float = 32.0):
send("grow_selection", [str(contiguous), str(tolerance)])
## Select › Transform Selection in one go: the outline scaled, turned by
## `angle` degrees about (`pivot_x`, `pivot_y`) and moved by (`dx`, `dy`).
pub func transform_selection(scale_x: float, scale_y: float, angle: float = 0.0, dx: float = 0.0, dy: float = 0.0, pivot_x: float = 0.0, pivot_y: float = 0.0):
send("transform_selection", [str(scale_x), str(scale_y), str(angle), str(dx), str(dy), str(pivot_x), str(pivot_y)])
## The Magnetic Lasso: its first anchor at the first of `points` (x, y
## pairs, document pixels), a click at each of the others, then closed back
## to the start along the edge; `mode` 0 new, 1 add, 2 subtract, 3 intersect.
pub func magnetic_lasso(points: list[float], width: float = 10.0, contrast: float = 10.0, frequency: int = 57, mode: int = 0):
var fields = [str(width), str(contrast), str(frequency), str(mode)]
for value in points:
fields = fields + [str(value)]
send("magnetic_lasso", fields)
## Select › Select and Mask in one go: edge detection `radius` (0..250 px),
## `smooth` (0..100), `feather` (0..250 px), `contrast` (0..100%) and
## `shift` edge (-100..100%), as one step.
pub func select_and_mask(radius: int = 0, smooth: int = 0, feather: int = 0, contrast: float = 0.0, shift: float = 0.0):
send("select_and_mask", [str(radius), str(smooth), str(feather), str(contrast), str(shift)])
## Select › Color Range. `range` is "Sampled Colors" (the sRGB triples in
## `colors`, within `fuzziness` 0..200), "Reds", "Yellows", "Greens", "Cyans",
## "Blues", "Magentas", "Highlights", "Midtones" or "Shadows"; `invert`
## selects the rest instead.
pub func select_color_range(range: str = "Sampled Colors", colors: list[float]? = none, fuzziness: float = 40.0, invert: bool = false):
let names = ["Sampled Colors", "Reds", "Yellows", "Greens", "Cyans", "Blues", "Magentas", "Highlights", "Midtones", "Shadows"]
var index = 0
while index < names.length and names[index] != range:
index += 1
var fields = [str(index), str(fuzziness), str(invert)]
let sampled = colors else []
var at = 0
while at + 2 < sampled.length:
fields = fields + [str(sampled[at]), str(sampled[at + 1]), str(sampled[at + 2]), "false"]
at += 3
send("select_color_range", fields)
# mark: Adjustments and filters ==============================================================
## Adjust the selected layer's pixels once by adjustment `name` ("Levels",
## "Hue / Saturation", "Exposure", "Vignette", ...) with its settings in the
## units its dialog shows, in its dialog's order; fewer keep the defaults.
pub func adjust(name: str, settings: list[float]? = none):
var fields = [name]
for value in settings else []:
fields.append(str(value))
send("adjust", fields)
## The same adjustment as a live adjustment layer above the selected layer.
pub func add_adjustment_layer(name: str, settings: list[float]? = none):
var fields = [name]
for value in settings else []:
fields.append(str(value))
send("adjustment_layer", fields)
## Filter `name` ("Gaussian Blur", "Motion Blur", "Lens Correction", "Bloom",
## "Tonal Contrast", "Add Noise") with its settings as its dialog shows them.
pub func filter(name: str, settings: list[float]? = none):
var fields = [name]
for value in settings else []:
fields.append(str(value))
send("filter", fields)
# mark: Transforms ===========================================================================
## Edit › Transform › Distort in one go: the selected layer's painted box (the
## selection's, whose pixels then float) with its corners moved to `corners`,
## x and y pairs clockwise from the top-left, in perspective.
pub func distort(corners: list[float]):
var fields: list[str] = []
for value in corners:
fields.append(str(value))
send("distort", fields)
## Edit › Transform › Skew in one go: the box slanted `horizontal` degrees
## (its top to the right) and `vertical` degrees (its right side down) about its middle.
pub func skew(horizontal: float, vertical: float = 0.0):
send("skew", [str(horizontal), str(vertical)])
## Edit › Transform › Perspective in one go: the box's top narrowed by
## `amount` of its width (negative widens it), or with `vertical` its right
## side by that much of its height; the opposite side stays.
pub func perspective(amount: float, vertical: bool = false):
send("perspective", [str(amount), str(vertical)])
## Edit › Transform › Warp in one go with a style — "Arc", "Arch", "Bulge",
## "Flag", "Wave" or "Rise" — bent by `bend` (-1..1).
pub func warp(style: str = "Arc", bend: float = 0.5):
send("warp", [style, str(bend)])
## Edit › Transform › Warp by its patch: sixteen x, y points row by row over
## the layer's painted box, as the Warp mesh has them (corners 0, 3, 12, 15).
pub func warp_points(points: list[float]):
var fields: list[str] = []
for value in points:
fields.append(str(value))
send("warp_points", fields)
## Edit › Puppet Warp in one go: a pin for each four of `pins` — put at the
## first x, y and dragged to the second — the picture bent about them;
## `density` 0 fewer, 1 normal, 2 more mesh points.
pub func puppet_warp(pins: list[float], density: int = 1):
var fields = [str(density)]
for value in pins:
fields.append(str(value))
send("puppet_warp", fields)
# mark: Vectors ==============================================================================
## A vector element on the selected layer — `kind` "rectangle", "ellipse",
## "line" or "polygon" — in the box, filled with the foreground color and
## stroked as the shape tools' header says (a line is stroked with the
## foreground). It goes on a new vector layer unless the selected layer is
## one, or holds nothing.
pub func add_vector(kind: str, x: float, y: float, width: float, height: float):
send("add_vector", [kind, str(x), str(y), str(width), str(height)])
## A pen path through `points` (x, y pairs; corner anchors), closed back to
## the first unless `closed` is false, placed as `add_vector`.
pub func add_path(points: list[float], closed: bool = true):
var fields = [str(closed)]
for value in points:
fields.append(str(value))
send("add_path", fields)
## The Vector panel's New Path: an empty path called `name`, active, for the Pen.
pub func new_path(name: str):
send("new_path", [name])
## The selected layer's element at `index` (0 the bottom) made active, so a
## move or transform acts on it alone; -1 for none, the whole layer.
pub func select_vector(index: int):
send("select_vector", [str(index)])
pub func rename_vector(index: int, name: str):
send("rename_vector", [str(index), name])
pub func set_vector_visible(index: int, visible: bool):
send("show_vector", [str(index), str(visible)])
## Element `index` put at place `to` among the layer's elements (0 the bottom).
pub func move_vector(index: int, to: int):
send("move_vector", [str(index), str(to)])
pub func duplicate_vector(index: int):
send("duplicate_vector", [str(index)])
pub func delete_vector(index: int):
send("delete_vector", [str(index)])
## Make Selection: element `index`'s outline as the selection; `mode` 0 new,
## 1 add, 2 subtract, 3 intersect.
pub func vector_selection(index: int, mode: int = 0):
send("vector_selection", [str(index), str(mode)])
## Element `index` alone scaled, turned by `angle` degrees about
## (`pivot_x`, `pivot_y`) and moved by (`dx`, `dy`), crisp.
pub func transform_vector(index: int, scale_x: float, scale_y: float, angle: float = 0.0, dx: float = 0.0, dy: float = 0.0, pivot_x: float = 0.0, pivot_y: float = 0.0):
send("transform_vector", [str(index), str(scale_x), str(scale_y), str(angle), str(dx), str(dy), str(pivot_x), str(pivot_y)])
# mark: Node graphs ==========================================================================
## A new vector layer above the selected one, selected: its node graph a star
## cloned round a circle, whose nodes are called "star", "circle", "clone" and
## "output".
pub func new_vector_layer():
send("new_vector_layer", [])
## A node of `kind` — "Rectangle", "Ellipse", "Polygon", "Star", "Path",
## "Grid", "Circle", "Line", "Random Scatter", "Points of Shape", "Clone",
## "Transform", "Merge", "Number", "Random", "Color Gradient" or "Output" — in
## the selected vector layer's graph, called `name` from here on, at (`x`, `y`)
## in the Node Editor.
pub func add_node(kind: str, name: str, x: float = 0.0, y: float = 0.0):
send("add_node", [kind, name, str(x), str(y)])
## Node `source`'s output wired into input `input` of node `target` (its name,
## as the node shows it — "Shapes", "Points", "Count" — or its number).
pub func link_nodes(source: str, target: str, input: str):
send("link_nodes", [source, target, input])
pub func unlink_node(target: str, input: str):
send("unlink_node", [target, input])
## Setting `setting` of node `node` (as the Node Editor names it: "Count",
## "Radius", "Jitter Rotation", ...); a toggle is 1 or 0.
pub func set_node(node: str, setting: str, value: float):
send("set_node", [node, setting, str(value)])
## A color setting ("Fill Color", "Start", ...), sRGB 0..1 a channel.
pub func set_node_color(node: str, setting: str, red: float, green: float, blue: float):
send("set_node_color", [node, setting, str(red), str(green), str(blue)])
pub func delete_node(node: str):
send("delete_node", [node])
# mark: The canvas ===========================================================================
## Scale the whole document to `width` by `height` pixels.
pub func resize_image(width: int, height: int):
send("resize_image", [str(width), str(height)])
## Change the canvas to `width` by `height`, the picture kept at the top-left
## moved by (`x`, `y`).
pub func resize_canvas(width: int, height: int, x: int = 0, y: int = 0):
send("resize_canvas", [str(width), str(height), str(x), str(y)])
## Crop to the rectangle.
pub func crop(x: int, y: int, width: int, height: int):
send("crop", [str(x), str(y), str(width), str(height)])
pub func flip_canvas(horizontal: bool = true):
send("flip_canvas", [str(horizontal)])
## Document Settings' "Blend RGB Colors Using Gamma 1.0": `on` mixes colors
## in linear light from here on; off, as sRGB values, as Photoshop does. One step.
pub func set_linear_blend(on: bool):
send("set_linear_blend", [str(on)])