retouch
Heal or clone pixels with a round brush. method heal paints a stroke that samples texture from elsewhere and blends it into its surroundings, for blemishes, dust and scratches; clone paints a stroke that copies the sampled pixels exactly; spot_heal takes round spots {x, y, radius} and picks each one's source automatically, from the nearby area whose brightness and texture best match the ring around the spot. Everything is in photo pixels. By default (target retouch_layer) the paint lands on a "Retouch" copy of the layer directly above it, shown only where you painted, so the original and the picture everywhere else stay untouched; later calls reuse that copy while it stays directly above the layer it was made from. target in_place paints the layer itself, and is required for a layer that is below 100% opacity, not in Normal mode, or has a layer mask; a layer with semi-transparent pixels also shows its original through the copy, so use in_place there. The current selection is kept and does not clip the retouch. Refuses layer groups, text layers, locked or hidden layers, indexed photos, and any point or spot outside the layer. A call has a work limit (a long stroke with a big brush, or many large spots): split it into several calls or use a smaller brush. Do NOT use for removing whole objects (use remove_object for those); a stroke or spot only blends in texture at the size of the brush. Returns layer_id, layer_name, created_layer, painted_bbox [x, y, w, h] and, for spot_heal, each spot's chosen source offset and score (lower is a closer match). To remove a whole object, use remove_object.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| image | Yes | Image id, as returned by open_photo. | |
| layer | No | Name of the pixel layer to retouch. Defaults to the selected layer, or the topmost layer if none is selected. | |
| spots | No | spot_heal: [{x, y, radius}] in image pixels (1-50 spots, radius 1-500). The source for each is picked from 8 directions at about 2.2x and 3.5x the radius, by how closely its brightness and texture match the ring around the spot. Every source is chosen before anything is painted, so a spot with no usable source fails the whole call unchanged. | |
| method | Yes | 'heal': paint a stroke that blends the sampled texture into its surroundings (blemishes, dust, scratches). 'clone': paint a stroke that copies the sampled pixels exactly. 'spot_heal': round spots, each healed from an automatically chosen nearby source. | |
| points | No | heal / clone: the stroke as [[x, y], ...] in image pixels (1-500 points), every one inside the layer. | |
| source | No | heal / clone: the image-pixel point to sample for points[0]; the rest of the stroke samples at the same offset. Give this OR source_offset. | |
| target | No | 'retouch_layer': paint on a 'Retouch' copy directly above the layer (made on the first call, reused while it stays directly above the layer it was made from); needs a Normal mode, 100% opacity layer without a layer mask. 'in_place': paint the layer itself. | retouch_layer |
| hardness | No | heal / clone: brush edge hardness, 0 soft to 1 hard. Default 0.5 for heal, 0.8 for clone. Not allowed with spot_heal. | |
| 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. | |
| brush_size | No | heal / clone: brush diameter in pixels. spot_heal sizes its own brush. | |
| source_offset | No | heal / clone: sample this many pixels from each stroke point (source = point + offset). Give this OR source. | |
| source_layer_id | No | clone only: sample from this pixel layer instead of the one being painted. The source point plus the stroke must lie inside it. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| spots | No | ||
| method | No | ||
| target | No | ||
| hardness | No | ||
| layer_id | No | ||
| brush_size | No | ||
| layer_name | No | ||
| painted_bbox | No | ||
| created_layer | No |