transform_layer
Destructive
Transform one layer (layer / layer_id, else the active layer): op selects fit | scale | move | rotate | flip | skew | free, each documented on op. Rotate, skew and free grow the layer so nothing clips; a layer with no transparency gets one (alpha_added). REFUSES when the layer, or the layers inside a group target, carries a masked filter or an unmasked effect this transform cannot keep locked to the content.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| op | Yes | 'fit' scales the layer to fit (letterbox) or fill (cover) the canvas, preserving aspect, and centers it (mode fit|fill, idempotent). 'scale' is uniform (scale_percent) or non-uniform (scale_x_percent/scale_y_percent) — multiplicative, anchored at the layer's own center; a NON-uniform scale is refused while an unmasked position/direction-dependent effect filter (vignette/motion_blur/drop_shadow) is present. 'move' translates — pass exactly ONE of delta (relative), absolute (top-left target), or center_on (center target), each a {x, y} object (flat delta_x/absolute_x fields are not accepted); mixing modes is refused. 'rotate' rotates by relative degrees (positive clockwise) around the layer's own center; the layer GROWS to fit the rotated content — nothing is clipped; an arbitrary (non-90°-multiple) angle is refused while such an effect is present. 'flip' mirrors horizontal|vertical in place (axis). 'skew' slants the layer (skew_h_degrees/skew_v_degrees) around its own center. 'free' is a numeric free transform in one matrix: scale_x_percent/scale_y_percent + degrees + offset_x/offset_y. skew and free are always refused while such an effect is present (no angle is safe for either). A text layer stays a text layer through every op, never rasterized. | |
| axis | No | flip only. 'horizontal' mirrors left-right; 'vertical' mirrors top-bottom. | |
| mode | No | fit only. 'fit' letterboxes inside the canvas (shorter edge touches); 'fill' covers it (longer edge touches, overflow is left outside the canvas, not cropped). Defaults to 'fit'. | |
| delta | No | A document-pixel point: {x, y}. move, RELATIVE mode: offset from the layer's current top-left. Mutually exclusive with absolute/center_on. | |
| image | Yes | Image id, as returned by open_photo. | |
| layer | No | Layer name. Defaults to the selected layer, or the topmost layer if none is selected. Ignored when layer_id is given. | |
| degrees | No | rotate: relative rotation angle, positive clockwise, around the layer's own center. free: relative rotation angle (default 0), applied in the same combined matrix as the scale and offset. | |
| absolute | No | A document-pixel point: {x, y}. move, ABSOLUTE mode: target for the layer's top-left corner. Mutually exclusive with delta/center_on. | |
| layer_id | No | Layer id, as inspect (and any tool that creates a layer) reports it. Takes priority over `layer`, and is the only way to address one of two layers that share a name. | |
| offset_x | No | free only. Horizontal translation in document pixels, applied last. Defaults to 0. | |
| offset_y | No | free only. Vertical translation in document pixels, applied last. Defaults to 0. | |
| center_on | No | A document-pixel point: {x, y}. move, CENTER mode: target for the layer's center point. Mutually exclusive with delta/absolute. | |
| interpolation | No | Resampling filter for this call, every op. Always set explicitly here — never carried over from a previous transform_layer call. | cubic |
| scale_percent | No | scale only. Uniform scale percentage (100 = unchanged). 1..10000. | |
| skew_h_degrees | No | skew only. Horizontal slant angle in degrees — positive slants the top edge right. At least one of skew_h_degrees/skew_v_degrees is required. | |
| skew_v_degrees | No | skew only. Vertical slant angle in degrees — positive slants the left edge down. | |
| scale_x_percent | No | scale/free: horizontal scale percentage (100 = unchanged), 1..10000. scale: pair with scale_y_percent for non-uniform stretch/squash; the other axis defaults to scale_percent, or 100 if that is absent too. | |
| scale_y_percent | No | scale/free: vertical scale percentage. See scale_x_percent. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| axis | No | ||
| mode | No | ||
| bounds | No | ||
| degrees | No | ||
| layer_id | No | ||
| offset_x | No | ||
| offset_y | No | ||
| text_layer | No | ||
| alpha_added | No | ||
| interpolation | No | ||
| scale_percent | No | ||
| skew_h_degrees | No | ||
| skew_v_degrees | No | ||
| scale_x_percent | No | ||
| scale_y_percent | No | ||
| effect_update_failures | No | Names of effect filters (position/direction/size-dependent ones tracked through geometry changes — a center, an angle, an offset, or a size-dependent blur radius under resize) whose own params could not be updated for this transform (a live update failure) -- they were restored to their OLD values in manage_filters's own ledger (guaranteed), and the live render was also asked to restore those same OLD values (best effort — it can, rarely, also fail). Omitted when every filter updated cleanly. |