Prepare Image Edit Mask
Own the outcome: deliver or teach the user to deliver a verified image/mask pair. Run selection-first: establish real edit pixels before mechanical mask conversion.
Workflow
Establish the intended edit.
- Identify the source image, what should change, what must remain, and whether the user wants assistance or instruction.
- Complete when editable and protected content is unambiguous.
Obtain an explicit pixel selection.
- Reuse an existing mask, freehand selection, design-tool export, or segmentation output.
- For semantic targets such as hair, clothing, products, people, reflections, holes, or overlaps, use a proven selection or segmentation tool when available. Otherwise ask the user to mark the region.
- Preserve real boundaries and soft edges. A bounding shape is not a substitute for a complex object selection.
- Complete when an arbitrary raster selection exists and its convention is known: transparent selected, opaque selected, white selected, or black selected.
Normalize the selection with scripts/mask_tool.py normalize.
transparent-is-edit: copy the selection alpha.opaque-is-edit: invert the selection alpha.white-is-edit: convert white luminance to transparent edit pixels.black-is-edit: convert black luminance to transparent edit pixels.- The command writes
source.png, mask.png, a red-overlay preview, and a JSON report.
- Complete when it exits 0 and all four outputs exist.
Pass the preview gate with the user.
- Red pixels are editable; uncolored pixels are protected.
- Check complex boundaries, holes, occlusions, and feathering against the user's intent.
- Improve the upstream selection when the boundary is wrong. Alpha conversion cannot recover a missing semantic boundary.
- Complete when the visible overlay matches the intended edit region.
Validate the final pair with scripts/mask_tool.py inspect.
- Complete only when
valid is true, dimensions match, both outputs are PNG, the mask has an alpha channel, and the intended local edit includes alpha below 255.
Hand off the pair and submission roles.
image: source.pngmask: mask.pngprompt: describe the desired result in the editable region and what should remain stable.- State: "透明区域会被编辑；不透明区域会被保护。"
Teaching Branch
When the user wants instructions instead of file preparation, adapt steps to their software:
- Create a layer or document at the source image's exact pixel dimensions.
- Start fully opaque.
- Select the real edit region using brush, path, subject-selection, or layer-mask tools.
- Clear the selection to transparency; retain partial alpha for soft boundaries.
- Export a transparency-preserving PNG.
- Preview it over a checkerboard and as a colored overlay on the source.
Opening a transparent PNG against a white viewer background may look blank. Alpha, not black or white RGB color, defines editability.
Troubleshooting
| Observation |
Likely cause |
Action |
| Nothing changes |
Mask is fully opaque |
Make the intended region transparent |
| Whole image changes |
Mask is fully transparent or missing |
Restore opacity outside the edit region |
| Opposite region changes |
Selection convention was reversed |
Normalize with the matching selection mode |
| Mask looks blank |
Viewer hides transparency |
Use the red-overlay preview or checkerboard |
| Complex edge is wrong |
Pixel selection is inaccurate |
Refine selection or segmentation |
| Client claims to send a mask but none is observed |
Request body may omit or rename the mask field |
Capture the actual multipart request with examples/capture-image-edit-request.js, then inspect the downloaded files |
| Service rejects the pair |
Format, dimensions, size, or alpha is invalid |
Re-export a same-size PNG pair with alpha |
Commands
Locate a Python interpreter where import PIL succeeds. In Codex App, use the workspace-dependencies tool to locate the bundled Python and assign it to MASK_PYTHON.
$MASK_PYTHON scripts/mask_tool.py normalize \
--source INPUT_IMAGE \
--selection INPUT_SELECTION \
--selection-mode white-is-edit \
--output-source source.png \
--output-mask mask.png \
--output-preview mask-preview.png \
--output-report mask-report.json
$MASK_PYTHON scripts/mask_tool.py inspect \
--source source.png \
--mask mask.png \
--output-preview mask-preview.png \
--output-report mask-report.json
The helper requires Pillow. Request permission before installing dependencies into a user's project or global environment.
Completion Contract
- Source and mask are same-size PNG files.
- Alpha 0 is editable, alpha 255 is protected, and alpha 1-254 is a soft transition.
- The red overlay has been compared with the user's intended region.
- The JSON report says
valid: true.
- The user understands that a mask guides the model but does not guarantee a mathematically exact pixel boundary.
1---2name: prepare-image-edit-mask3description: Prepare and troubleshoot masks for OpenAI image edits. Use when a user needs help selecting an edit region, creating or converting an arbitrary raster selection, validating an existing mask, learning a software-specific workflow, or diagnosing an edit that changed the wrong area.4---56# Prepare Image Edit Mask78Own the outcome: deliver or teach the user to deliver a verified image/mask pair. Run selection-first: establish real edit pixels before mechanical mask conversion.910## Workflow11121. Establish the intended edit.13 - Identify the source image, what should change, what must remain, and whether the user wants assistance or instruction.14 - Complete when editable and protected content is unambiguous.15162. Obtain an explicit pixel selection.17 - Reuse an existing mask, freehand selection, design-tool export, or segmentation output.18 - For semantic targets such as hair, clothing, products, people, reflections, holes, or overlaps, use a proven selection or segmentation tool when available. Otherwise ask the user to mark the region.19 - Preserve real boundaries and soft edges. A bounding shape is not a substitute for a complex object selection.20 - Complete when an arbitrary raster selection exists and its convention is known: transparent selected, opaque selected, white selected, or black selected.21223. Normalize the selection with `scripts/mask_tool.py normalize`.23 - `transparent-is-edit`: copy the selection alpha.24 - `opaque-is-edit`: invert the selection alpha.25 - `white-is-edit`: convert white luminance to transparent edit pixels.26 - `black-is-edit`: convert black luminance to transparent edit pixels.27 - The command writes `source.png`, `mask.png`, a red-overlay preview, and a JSON report.28 - Complete when it exits 0 and all four outputs exist.29304. Pass the preview gate with the user.31 - Red pixels are editable; uncolored pixels are protected.32 - Check complex boundaries, holes, occlusions, and feathering against the user's intent.33 - Improve the upstream selection when the boundary is wrong. Alpha conversion cannot recover a missing semantic boundary.34 - Complete when the visible overlay matches the intended edit region.35365. Validate the final pair with `scripts/mask_tool.py inspect`.37 - Complete only when `valid` is true, dimensions match, both outputs are PNG, the mask has an alpha channel, and the intended local edit includes alpha below 255.38396. Hand off the pair and submission roles.40 - `image`: `source.png`41 - `mask`: `mask.png`42 - `prompt`: describe the desired result in the editable region and what should remain stable.43 - State: "透明区域会被编辑；不透明区域会被保护。"4445## Teaching Branch4647When the user wants instructions instead of file preparation, adapt steps to their software:48491. Create a layer or document at the source image's exact pixel dimensions.502. Start fully opaque.513. Select the real edit region using brush, path, subject-selection, or layer-mask tools.524. Clear the selection to transparency; retain partial alpha for soft boundaries.535. Export a transparency-preserving PNG.546. Preview it over a checkerboard and as a colored overlay on the source.5556Opening a transparent PNG against a white viewer background may look blank. Alpha, not black or white RGB color, defines editability.5758## Troubleshooting5960| Observation | Likely cause | Action |61|---|---|---|62| Nothing changes | Mask is fully opaque | Make the intended region transparent |63| Whole image changes | Mask is fully transparent or missing | Restore opacity outside the edit region |64| Opposite region changes | Selection convention was reversed | Normalize with the matching selection mode |65| Mask looks blank | Viewer hides transparency | Use the red-overlay preview or checkerboard |66| Complex edge is wrong | Pixel selection is inaccurate | Refine selection or segmentation |67| Client claims to send a mask but none is observed | Request body may omit or rename the mask field | Capture the actual multipart request with `examples/capture-image-edit-request.js`, then inspect the downloaded files |68| Service rejects the pair | Format, dimensions, size, or alpha is invalid | Re-export a same-size PNG pair with alpha |6970## Commands7172Locate a Python interpreter where `import PIL` succeeds. In Codex App, use the workspace-dependencies tool to locate the bundled Python and assign it to `MASK_PYTHON`.7374```bash75$MASK_PYTHON scripts/mask_tool.py normalize \76 --source INPUT_IMAGE \77 --selection INPUT_SELECTION \78 --selection-mode white-is-edit \79 --output-source source.png \80 --output-mask mask.png \81 --output-preview mask-preview.png \82 --output-report mask-report.json8384$MASK_PYTHON scripts/mask_tool.py inspect \85 --source source.png \86 --mask mask.png \87 --output-preview mask-preview.png \88 --output-report mask-report.json89```9091The helper requires Pillow. Request permission before installing dependencies into a user's project or global environment.9293## Completion Contract9495- Source and mask are same-size PNG files.96- Alpha 0 is editable, alpha 255 is protected, and alpha 1-254 is a soft transition.97- The red overlay has been compared with the user's intended region.98- The JSON report says `valid: true`.99- The user understands that a mask guides the model but does not guarantee a mathematically exact pixel boundary.
catoncat