image-local-replacer

Local Image Replacement

Perform controllable replacement of small-area content already fixed in a bitmap. Prefer deterministic local pixel editing: read the original image, process only the specified rectangular region according to the configuration, sample the background from the surrounding area when necessary, then write new content or only cover and erase.

Core Principles

Only modify the local region specified by the user or after calibration.
Do not use whole-image AI redrawing, and do not regenerate the entire image.
Do not change the image width/height, filename, or unselected regions.
First output to a preview directory, and only overwrite the original image after confirming it is correct.
When performing secondary correction of residual pixels, only cover the residual region and do not expand the scope of impact.

Applicable Scenarios

Scenario	Recommended Method
Replace numbers, labels, dates, or short text in an image	Cover the old text region, then write new text using similar colors, font size, and font
Mask local sensitive information	Cover the local region with a background-sampled color, a specified solid color, or an approximate color before blurring
Clean up ghosting from old characters or residual annotations	Use a smaller rectangle for secondary covering
Patch small errors in maps, engineering drawings, or screenshots	Process only the erroneous region and preserve other content such as lines, legends, boundaries, and points

Not suitable for: tasks that require understanding complex semantics, reconstructing large-area backgrounds, completing missing objects, changing image style, or generating new scenes; these should use specialized image editing workflows rather than this skill.

Workflow

Collect the target image path and replacement requirements, and clarify which regions are allowed to be modified.
Preview the image and locate the smallest rectangular region that needs to be replaced. Rectangle coordinates use [left, top, right, bottom]。
When new text needs to be written, record the text's top-left [x, y], color, font size, and font; try to match the original image's visual style.
Create a JSON configuration, with each local replacement item describing only one small region.
First run the script to output to the preview directory, and check each image one by one.
If there is ghosting, occlusion, or abrupt colors, fine-tune cover、background、padding、text_xy、font_size and rerun.
After confirming it is correct, use --overwrite to overwrite the original image.

Configuration Example

All coordinates are pixel coordinates:

{
  "default": {
    "font_size": 24,
    "fill": "#d71920",
    "stroke_width": 0
  },
  "items": [
    {
      "file": "map.png",
      "description": "替换左上角机位编号",
      "cover": [100, 120, 158, 148],
      "text": "XD1",
      "text_xy": [102, 116]
    },
    {
      "file": "screenshot.png",
      "description": "遮盖手机号",
      "cover": [320, 88, 460, 116],
      "background": "#ffffff"
    }
  ]
}

Field descriptions:

Field	Required	Description
`file`	Yes	Image path relative to the input directory
`cover`	Yes	The local rectangle to cover `[left, top, right, bottom]`
`description`	No	Manual review note; does not participate in drawing
`text`	No	New text to write after covering; if not filled in, only local covering is performed
`text_xy`	Required when writing text	Top-left of the new text `[x, y]`
`font_size`	No	Font size; if not set, use `default.font_size`
`font`	No	Font file path; if not set, common system fonts are tried
`fill`	No	Text color, supports `#RRGGBB` or `[r,g,b]`
`background`	No	Override color; if not set, the script samples the median color from around the overlay box
`padding`	No	Extra pixel expansion of the overlay box, default `0`
`stroke_width`	No	Text stroke width, default `0`
`stroke_fill`	No	Text stroke color

How to run

Install dependencies:

pip install -r resources/requirements.txt

First output to the inspection directory:

python3 scripts/apply_local_replacements.py ./images replacements.json -o ./preview-images

After confirming it is correct, overwrite the original file:

python3 scripts/apply_local_replacements.py ./images replacements.json --overwrite

If you need help locating red text or red annotations, you can generate a red pixel mask:

python3 scripts/apply_local_replacements.py ./images replacements.json --red-mask-dir ./red-mask

Acceptance

The output image has the same width and height as the original image.
The target local area has been replaced, covered, or cleaned up as required.
Unselected areas remain visually unchanged.
File names remain unchanged; if an output directory is used, only the directory changes, not the file name.
There are no obvious abrupt color blocks, residual pixels, or accidental occlusion at the edges of the covered area.