object_remove
A from scratch, CPU implementation of an on device object removal pipeline (see
docs/ARCHITECTURE.md for the full design): a
polygon/scanline mask layer, three fill engines of increasing
sophistication, two interchangeable blend backends, and a locked/queued
session persistence layer.
Everything here is implemented from primitives (FAST corners, BRIEF descriptors, Hamming matching, PatchMatch, Laplacian/Poisson blending) — no OpenCV, no learned weights.
Quick start
pip install advanced-object-remove-cpu
import numpy as np
from object_remove import RemoveObjectJob, EngineTier
result = RemoveObjectJob(image_rgb).run(mask, tier=EngineTier.AUTO,
progress=lambda stage, frac: ...)
removed = result.image # float32 RGB in [0, 1]
print(result.tier_used) # which engine AUTO picked
image_rgb is any (H, W, 3) array (uint8 or float); mask is (H, W) with
nonzero marking the object to remove.
New to the package? Start with docs/USAGE.md — it walks
through loading an image, building a mask three different ways (brush stroke,
polygon selection, tap-to-auto-select), refining it, running the removal, and
undo/session history, with runnable snippets for each.
To run from a source checkout instead of the installed package:
pip install -r requirements.txt # numpy, scipy, Pillow
PYTHONPATH=. python examples/demo.py # writes before/after PNGs to examples/out/
PYTHONPATH=. python -m pytest -q # 31 tests
Module layout
| Stage | Concern | This repo |
|---|---|---|
| A — mask | selection, brush, auto select | object_remove/mask/ |
| B/D — scale/tiles | pyramid + tile scheduling | object_remove/pyramid/ |
| C1 — legacy CPU fill | segment aware patch comparator | fillengines/patch_comparator.py |
| C2 — texture synthesis | self similar rigid shift | fillengines/self_similar_shift.py |
| C3 — patch match | multi scale PatchMatch | fillengines/patchmatch/ |
| E — blend | multi band + Poisson | object_remove/render/ |
| F — session | undo / persistence | object_remove/session/ |
| — orchestration | tier selection, progress, cancellation | pipeline/remove_object_job.py |
The three fill engines
- Tier 1 —
SegmentAwarePatchFillEngine— greedy onion peel exemplar fill scored by segment aware SSD with byte mask validity. Cheap, correct on small holes; the low end / tiny hole fallback. - Tier 2 —
SelfSimilarShiftEngine— the fast default for repetitive texture. FAST corners + 256 bit BRIEF + Hamming matching find a rigid self similar offset; a 1D DP seam cuts the copied block in cleanly, run for x then y via a transpose trick. - Tier 3 —
PatchMatchEngine— multi scale, multi group PatchMatch inpainting (random init → propagation → random search, then patch voting reconstruction, coarse to fine). The quality path.
EngineTier.AUTO sends truly tiny holes to tier 1, otherwise tries the cheap
tier 2 rigid shift first and falls back to tier 3 PatchMatch when the shift's
boundary continuity score is poor.
The two blend backends
MultiBandBlender— Laplacian pyramid blend with a fixed 4 tap kernel,[0.15439, 0.15133, 0.14252, 0.12896], and the mask feathered per pyramid level.PoissonBlend/PoissonBlend2— gradient domain blend (sigma,multiplier,algo_n1|2 variant), solved as a sparse Poisson system. Poisson is the safe default for single image inpainting because it reads only the (valid) hole boundary; the compositor repairs the background under the hole so no backend ever samples the object being removed.
Session persistence
SessionManager gives each edit a session id and an RLE mask history. Directory
removal is dispatched onto a background queue and run under a lock — never
an inline delete from the caller. A separate EmptySessionSweeper GCs orphaned
empty session dirs left by aborted/crashed edits.
Status & scope
Implemented and tested: the full CPU pipeline across all stages. Auto select
is explicitly an interface + CPU fallback: a real segmentation model can be
dropped in behind AutoSelectModel, which ships a working color flood
fallback so tap to select runs end to end without one.
Engines run in pure Python/numpy for clarity; they are correct, not tuned for speed. The hot inner loops (PatchMatch sweep, Poisson solve) are the obvious targets for a native/GPU port.
object_remove/
mask/ brush_rasterizer, polygon_selection, selection_enhancer,
connected_components, auto_select
pyramid/ image_pyramid, scale_scheduler, tile_scheduler
fillengines/ patch_comparator (T1), self_similar_shift (T2), patchmatch/ (T3)
render/ multiband_blender, poisson_blender, compositor
session/ undo_session_manager, empty_session_sweeper
pipeline/ remove_object_job
Metadata
Release files for advanced-object-remove-cpu 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| advanced_object_remove_cpu-0.2.0.tar.gz | 40.5 kB | With provenance | Details for advanced_object_remove_cpu-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| advanced_object_remove_cpu-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for advanced_object_remove_cpu-0.2.0-py3-none-any.whl |
Total release size: 89.0 kB
Release files / advanced_object_remove_cpu-0.2.0.tar.gz
| Download URL | advanced_object_remove_cpu-0.2.0.tar.gz |
|---|---|
| Size | 40.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0784989340fbfecd98aea884a47ac93fc7e73c2af216db211fd850cf1c675e2b
|
|
BLAKE2b-256 checksum How to use checksums |
f0d5c0cfb67bf005f6b9f3b6b8029e2878249188f67d9059f357d27b6282dc0f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 12, 2026.
Transparency logRelease files / advanced_object_remove_cpu-0.2.0-py3-none-any.whl
| Download URL | advanced_object_remove_cpu-0.2.0-py3-none-any.whl |
|---|---|
| Size | 48.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
186a6849a86ad683a60d37177f3bb357ed578ef56650783374aead62099a2fdd
|
|
BLAKE2b-256 checksum How to use checksums |
3a2f537ce09966809ea10b3755aeb4d1e8c1b3df8774b0a713d467f910515d0c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 12, 2026.
Transparency logSecurity for advanced-object-remove-cpu 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for advanced_object_remove_cpu-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 12, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.