Patch Annotated Image

A reusable Codex skill for annotation-driven local image editing:

clean original + line/circle/scribble markup + written instructions → atomic PromptContracts → local donors → donor-informed masks → exact-coordinate composite → independent audit → Candidate

适合这类工作：提供干净原图、单独的线条批注图和文字修改意见，只生成圈选局部，再按原坐标合并，未授权区域保持不变。

What it does

• registers resized, cropped, or screenshot markup to the clean original;
• extracts tight edit crops and annotation masks;
• prepares local donor patches for ImageGen or another image editor;
• builds general-region, people, vegetation, and surface masks;
• protects fine details such as wires, text, hair, seams, and object edges;
• composites at recorded source coordinates;
• rejects base-file overwrite, empty masks, invalid coordinates, and edits outside an independent allowed-region mask;
• exports the full result, preview, local RGBA cutout with offset, full-canvas RGBA overlay, masks, and JSON audit report.

The v0.2 controller also:

• freezes a resumable patch-run@2 manifest;
• rejects unbound annotations, stale reference hashes, controlled prompt conflicts, and unauthorized Provider budgets before generation;
• compiles one semantic edit and one responsibility axis per PromptContract@1; geometry design and material finish are separate donors rather than one overloaded prompt;
• deduplicates identical Provider requests inside a run and finalizes all supplied donors in one batch;
• requires an independent visual review before the result becomes CANDIDATE_READY.

Built-in ImageGen is the default donor generator. Nano Banana is optional when the user explicitly authorizes the bounded call package and supplies their credential through a named environment variable or controlled secret source; secret values are never written into specs or receipts.

Illustrated tutorial

批注驱动的局部图像编辑教程（中文 PDF） uses a living-room wall case to explain the workflow in plain language: separate design from material, generate only the local change, build the mask after seeing the result, paste it back at the recorded coordinates, and verify that nothing outside the approved area changed.

The PDF is committed directly to this repository. Its public, reproducible appendix source is docs/build_tutorial_v02_appendix.py; rerunning it replaces pages 12-13 without duplicating them.

Input boundary

The deterministic helper targets already-oriented, opaque RGB PNG/JPG working images. It requires Python with Pillow and NumPy.

Install

Clone this repository into your personal Codex skills directory:

git clone https://github.com/cogco1/patch-annotated-image.git "$HOME\.codex\skills\patch-annotated-image"

Invoke it explicitly with $patch-annotated-image, or let Codex discover it automatically from requests that contain an original image, a separately annotated copy, and written local-edit instructions.

See SKILL.md for the entrypoint and references/workflow.md for manual low-level recovery.

For the automatic path, read references/automatic-workflow.md and references/prompt-contract.md. The deterministic entrypoints are scripts/patch_run.py and scripts/compile_patch_prompt.py; scripts/image_patch.py remains the low-level recovery toolkit.