Clarify clone sampling fallbacks and composite boundaries

This commit is contained in:
Ian committed 2026-11-11 14:27:30 -05:00
1 parent 6f796e0314
commit a078a37054
1 file changed
+1 -1
+1 -1
View File
@@ -59,7 +59,7 @@ The transport is `apps/photocraft/src/control_server.rs`, and the handlers are i
- `select.findLayers` (#10884, Select › Find Layers) filters the Layers panel by Name and selects none of the matches; as with any filter, a selected layer the filter hides is deselected (#10879). With `name` it sets the Name text; without it the text is kept. Through `engine.execute` or an action step that is all; through the menu, the shortcut or `ui.menu.invoke` without `name`, the Layers panel is also shown and its Name field takes the keyboard focus with the text selected (unless Filter Options › Hide hid the filter row, which stays hidden). The reply lists the ids of the layers the Name text matches in `selected` (trimmed, ignoring case: a blank text lists every layer, a text nothing matches none) and the Name filter applied in `layerFilter` (`{by: "name", name}`).
- `ui.set` also accepts the Histogram panel: `histogramPanel` `{view?, channel?, showChannelsInColor?, showStatistics?, source?}` (any subset, kept with the preferences): `view` is `compact`, `expanded` or `allChannels`; `channel` is `composite`, `red`, `green`, `blue`, `cyan`, `magenta`, `yellow`, `black`, `a`, `b`, `luminosity` or `colors` (one the document's mode lacks shows as its composite); `source` is `entireImage`, `selectedLayer` or `adjustmentComposite` (Entire Image is counted in Compact View, when the document has one layer, or when no adjustment layer is selected for Adjustment Composite). `histogramRange` is `[from, to]` (levels 0..255) or `null`: the dragged tonal range whose Count and Percentile the statistics show. `histogramRefresh: true` is Uncached Refresh: the current state is recounted at cache level 1. `ui.inspect` › `histogram` reports the options, the channel and source as they apply, the channels the document offers, whether the shown histogram is `current` (counted for the document's revision, source and cache level the panel wants now), its `cacheLevel`, `maxCacheLevel` (Preferences › Performance › Cache Levels), `preview` (an adjustment's preview is counted) and `stats` (`mean`, `stdDev`, `median`, `pixels`, `level`, `count`, `percentile`, `clipped` percent at 0 and 255). Histograms are counted while the panel is shown.
- Each painting tool keeps its own brush, as in Photoshop: `tools.setBrush` and `ui.set {brushSize}` change the active tool's brush, and switching tools swaps in that tool's own (size, hardness, mode, opacity, flow, dynamics, smoothing). A tool used for the first time starts from the brush in hand. The colours, the erase flag and the stroke seed stay shared. So `ui.set {tool: "eraser", brushSize: 12}` sets the Eraser's size, and `ui.set {tool: "brush"}` afterwards brings the Brush's own size back.
- For pixel-layer destinations, Clone Stamp and Healing Brush source slots remember the picked document and layer. Alt-click in one open document, switch tabs, and paint in another; Current Layer reads the picked layer, Current & Below reads its source stack, and All Layers reads its source document composite. Clone Stamp requires matching document color modes; Healing Brush additionally allows Grayscale on either side. Compatible cross-document colors use the document ICC profiles through the CMS. `cloneSource.set {"source":[x,y],"document":index}` selects an open source document explicitly; `cloneSource.list` reports its current index and `documentId`. A closed source document or deleted sampled layer returns an error until a new source is picked. Empty slots do not reuse an earlier slot's coordinates. Source canvas coverage is retained independently of stored alpha: no-alpha pixels inside the canvas are opaque, including black; pixels outside it do not paint. Wrapped sampling repeats the source canvas. Opaque destination surfaces retain their original native format after blending. Cross-document mask/channel destinations return an unsupported-target error instead of sampling the wrong document.
- For pixel-layer destinations, Clone Stamp and Healing Brush source slots remember the picked document and layer. Current Layer reads the picked pixel layer even after switching destination layers. If the picked layer has no pixel surface (such as a group or adjustment layer), Current Layer falls back to the destination surface for a same-document source and returns an error for a cross-document source; it does not sample the non-pixel layer itself. Current & Below composites the destination layer and everything below it for a same-document source; for a cross-document source it composites the picked source layer and everything below it. All Layers reads the entire source document composite. Alt-click in one open document, switch tabs, and paint in another to clone across documents. Clone Stamp requires matching document color modes; Healing Brush additionally allows Grayscale on either side. Compatible cross-document colors use the document ICC profiles through the CMS. `cloneSource.set {"source":[x,y],"document":index}` selects an open source document explicitly; `cloneSource.list` reports its current index and `documentId`. A closed source document or deleted sampled layer returns an error until a new source is picked. Empty slots do not reuse an earlier slot's coordinates. Source canvas coverage is retained independently of stored alpha: no-alpha pixels inside the canvas are opaque, including black; pixels outside it do not paint. Wrapped sampling repeats the source canvas. Opaque destination surfaces retain their original native format after blending. Cross-document mask/channel destinations return an unsupported-target error instead of sampling the wrong document.
- Clone Source X/Y are signed document-pixel offsets, using the existing `source - destination` convention. The panel derives the current preview/stroke pairing without anchoring it on hover. `cloneSource.list` exposes `anchor` (persistent Aligned pairing), `lastAnchor` (most recently used successful pairing), and `offset` (source minus that last reference). Unaligned strokes update the readout while restarting at the sample point each time; failed or canceled strokes do not commit a pairing. To edit the offset shown for a preview, use `cloneSource.set {"offset":[dx,dy],"anchor":[destinationX,destinationY]}`; without an explicit anchor an edit uses the last reported reference, then the existing aligned reference or sample point. Source picking clears both anchors; resetTransform retains them. Null optional coordinates are omitted consistently in mapping and source-document selection. Invalid coordinates, slot indexes, and oversized transformed sampling windows return errors without painting.
- Brush Pose's `pose.overrideTiltX` and `pose.overrideTiltY` are independent booleans. For example, `engine.execute {"command":"tools.setBrush","params":{"pose":{"enabled":true,"tiltX":45,"overrideTiltX":true,"overrideTiltY":false}}}` fixes X at 45° while Y follows the stylus. Pose tilts are degrees (±90); the Brush Settings panel displays percentages (±100). Old stored `overrideTilt` values migrate to both axes. In command patches, `overrideTilt` sets both axes unless an explicit axis field in the same patch overrides it. `brush.get` includes both axis flags and the legacy combined readback (`overrideTilt` is true only when both flags are true). Axis-only journals omit that derived combined key so replay retains the other axis. Present flag values must be booleans; null and other types return an error.
- `ui.set` also accepts the Eyedropper options bar (#1649): `eyedropperSampleSize` (`"point"` or 1, 3, 5, 11, 31, 51, 101: the side of the averaged square, shared by the Eyedropper, a painting tool's Alt-click eyedropper, the Curves/Color Picker eyedroppers and the Info panel), `eyedropperSample` (`current`, `currentAndBelow`, `all`, `allNoAdjustments`, `currentAndBelowNoAdjustments`) and `eyedropperRing` (boolean, Show Sampling Ring). `ui.inspect` reports them under `toolOptions` (`eyedropper_size`, `eyedropper_sample`, `eyedropper_ring`). The engine command `document.sampleColor {x, y, size, sampleLayer}` returns the colour such a sample picks, as four floats 0..1 (not 0..255).