ObjectClear removes an object and its effects together, and the mask is not optional

The problem is what the object left behind

ObjectClear is described as an object removal model that can jointly eliminate the target object and its associated effects, leveraging Adaptive Target-Aware Attention, while preserving background consistency.

Read that carefully, because the second half of the sentence is the contribution. Classic object removal inpaints a masked region and fills it with plausible background. That is straightforward when the object sits on a flat surface and hard when it does not, because a chair on a lawn casts a shadow, a mug on a table reflects in a polished surface, and a person standing in front of a window blocks the light. The pixels that need fixing are not only the ones inside the mask.

So the model is trained to remove the object and its effects together, and to keep the rest of the background consistent. The name of the mechanism, Adaptive Target-Aware Attention, is the paper's description of how the target is signalled to the network, and the README does not describe its internals, so the detail has to be read in the paper rather than in the repository.

The project is a CVPR 2026 publication from S-Lab at Nanyang Technological University, with four named authors and a project page, an arXiv entry, a Hugging Face demo space, and a public dataset card. That framing matters for how you should use the code: this is a research release, and the repository is organised around reproducing a paper.

The repository description is a machine learning task, so the honest audience is researchers and engineers working on image editing pipelines, not a product team looking for a photo retouching button.

SDXL inpainting with a CLIP encoder pointing at the target

The base architecture is stated plainly in the training section. ObjectClear is built on SDXL-Inpainting and uses a CLIP image encoder to encode the target object, with the SDXL base model downloaded automatically on the first run.

That gives the design its shape. The inpainting base model handles the generation, and the CLIP encoder provides the target conditioning, so the network knows which object in the scene it is meant to remove rather than removing whatever happens to be under the mask. The attention is described as target aware and adaptive, which is where the difference from a plain inpainting call is supposed to come from.

The concrete model weights are named in the documentation. The SDXL base is stable-diffusion-xl-1.0-inpainting-0.1, and the encoder is openai/clip-vit-large-patch14. The encoder is not fetched automatically with the base model, it is downloaded separately into ./ckpts, because the directory layout is part of the expected path:

# download the CLIP image encoder used as the object encoder
huggingface-cli download openai/clip-vit-large-patch14 --local-dir ./ckpts/clip-vit-large-patch14

A repository file named download_pretrained_weights.py exists in the tree as well, so the two weight pulling steps are split between a script and a command line download, which is worth checking rather than assuming which one the code expects.

The dependency list gives the rest of the picture: torch and torchvision, diffusers and transformers, accelerate for the training loop, safetensors, numpy, opencv-python, pillow, scipy, huggingface_hub, pyarrow for the parquet shards, pyyaml, tensorboard, tqdm and packaging. That is a diffusers style research stack rather than a packaged inference library, and it explains why the requirements file is a plain list of names with no versions pinned.

Every run needs an image and a matching mask

The inference section states the input contract, and it is stricter than many editing tools.

For each run, the tool takes an image and its segmentation mask as input. The examples are provided in an inputs folder, and the documented directory structure puts images in inputs/imgs and masks in inputs/masks with matching base names:

inputs
   ├─ imgs
   │   ├─ test-sample1.jpg      # .jpg, .png, .jpeg supported
   │   ├─ test-sample2.jpg
   └─ masks
       ├─ test-sample1.png
       ├─ test-sample2.png

The mask is not produced by the model. The documentation points you at interactive segmentation models such as the SAM2 demo on Hugging Face to obtain it.

That is the single most important operational fact about this project. ObjectClear does not find the object, it is told where the object is, and its quality depends on the quality of the mask you feed it. In a pipeline that already has segmentation, that is a sensible division of labour. In a one off use where you have a photo and want the tool to work out what to remove, it is an extra step with a real failure mode, because a mask that includes the shadow will change what the model believes the effect region is.

The inference commands show the two modes. A single image:

## Single image inference
python inference_objectclear.py -i inputs/imgs/test-sample1.jpg -m inputs/masks/test-sample1.png --guidance_scale 2.5 --use_fp16

And a batch over a folder of images and masks:

## Batch inference on image folder
python inference_objectclear.py -i inputs/imgs -m inputs/masks --guidance_scale 2.5 --use_fp16

The --use_fp16 flag is what makes this practical on consumer hardware, and the batch mode is the shape you would use to run a dataset through the model.

guidance_scale decides between removing and preserving

The one tuning parameter the documentation explains is the one that matters most, and the note about it is worth reading twice.

The guidance_scale option controls the trade-off: higher values lead to stronger removal, while lower values better preserve background details. The default is 2.5. And then there is the detail that saves you from publishing a wrong number: for all the benchmark results reported in the paper, the value used was 1.0.

So the default in the code is not the setting behind the reported results. If you want to reproduce the paper's comparisons, you need to pass 1.0 explicitly, and if you want the strongest removal the tool offers, the default is already there. The gap between 1.0 and 2.5 is where the trade-off lives, and it is a real one for this particular model, because the thing it is optimising for is exactly the background detail that stronger removal tends to smooth over.

That is worth stating as a general caution about the tool. Object removal with effect removal is asking a diffusion model to invent plausible content for two different regions at once, the object and the effect, and the region it invents is the background. Raising the guidance scale pushes the model harder toward removing everything that looks like the target, which is what you want when a shadow remains, and toward erasing texture that was never part of the target, which is what you do not want.

The command line also accepts the guidance value as a decimal, so intermediate settings are available, and the sensible workflow is to render the same input at a couple of values and pick, rather than to trust a default that the documentation itself distinguishes from the paper's setting.

OBER is 27 GB, gated, and non commercial

The dataset is the durable contribution of the project, and it is also the part with the strictest terms.

OBER, for OBject-Effect Removal, is a hybrid dataset designed to support research in object removal with effects, combining both camera-captured and simulated data. It is published on Hugging Face as OBERDataset_ObjectClear, with a note that it is made available solely for non commercial research use, and that any use, reproduction or redistribution must comply with the NTU S-Lab License 1.0 in the repository's LICENSE file.

The preparation steps are spelled out. Access to the dataset is gated, so you request access on the dataset page first, then log in and download:

# log in with your Hugging Face token (needed for the gated dataset)
huggingface-cli login

# download the OBER dataset (~27 GB) into ./data/OBER
huggingface-cli download sczhou/OBERDataset_ObjectClear --repo-type dataset --local-dir ./data/OBER

The training reads the parquet shards directly with no unpacking step, and the shards land in a predictable layout:

data/OBER/data
   ├─ train-00000-of-00053.parquet   # 37,994 cropped training pairs
   ├─ ...
   ├─ train-00052-of-00053.parquet
   └─ test-00000-of-00001.parquet    # test split (used for validation)

Fifty three training shards, 37,994 cropped training pairs, and one test split used for validation. Each sample provides four fields: input, gt, object_mask, and object_effect_mask. That last field is the interesting one, because it marks the effects separately from the object, which is what makes it possible to train a model that distinguishes the two instead of learning that a shadow is part of every object.

The size is a real constraint. 27 GB of parquet shards, a gated download that requires approval, and a model that needs an SDXL base checkpoint on top of it, is a considerable commitment to reproduce a paper.

The install is a conda environment and two requirements files

Installation is described in two steps, and it is conventional enough to be uneventful, which is a good sign for a research release.

Clone the repository:

    git clone https://github.com/zjx0101/ObjectClear.git
    cd ObjectClear

Then create the environment and install the dependencies:

    # create new conda env
    conda create -n objectclear python=3.10 -y
    conda activate objectclear

    # install python dependencies
    pip3 install -r requirements.txt
    # [optional] install python dependencies for gradio demo
    pip3 install -r hugging_face/requirements.txt

Python 3.10 is the pinned interpreter for the conda environment. The main requirements file is a flat list without version constraints, and the Gradio demo has its own requirements file under hugging_face/, installed separately and marked optional. That separation matches the repository layout, where hugging_face/ holds the demo space and evaluation/ holds the evaluation code.

The training entry points are train.sh and train_objectclear.py, and the model code itself sits in the objectclear/ package directory. There is also a media release, tagged media with the description Media Resources for ObjectClear, which is where the teaser and dataset figures live.

One more thing about the update timeline in the README, because it tells you what state the project is in. The repository was created in 2025.05, the inference code and Gradio demo were released in 2025.07, the benchmark datasets and the paper results were published in 2025.09, the OBER dataset was released in 2026.02, and the training code was released in 2026.08. The checkboxes for releasing the training code, the training datasets, the benchmark datasets and the inference code are all marked as done, so the release plan the project set out has been completed.

The licence terms are the sharpest constraint in this repository

Two different licensing situations sit in this project, and conflating them would be a mistake.

The repository licence is recorded as a custom licence that GitHub cannot categorise, and the OBER dataset is released under the NTU S-Lab License 1.0 for non commercial research use. The dataset note is explicit: any use, reproduction or redistribution must strictly comply with those terms. So the model code and the training data are governed differently, and the data is the more restrictive of the two.

The practical consequence is that the obvious commercial application of the technology, an in app object removal service, is exactly what the dataset terms do not support, unless you obtain separate permission. The model weights themselves are a third question the README does not answer directly, so the licences for the weights, the code and the data have to be read separately before any deployment decision.

The authors are clear that the dataset is offered as a research resource and benchmark for future object removal research, which matches the publication framing. The paper is on arXiv as 2505.22636, the project page carries more visual results, and there is a Hugging Face demo space for trying the model without setting up the environment.

The repository is not archived and the last push was on 2026-08-03, which is when the training code was released. For a paper release, that is the point at which the artefact is complete, and it is also the point at which you should pin your version, because there is no release tag beyond the media tag to fall back on.

Editorial conclusion

Use ObjectClear if you are working on object removal where the artefact left behind matters, and you have a segmentation mask and a GPU to run SDXL inpainting on. Do not plan to use it in a commercial product or to train on the OBER data, because the dataset is released for non commercial research under the NTU S-Lab License 1.0 even though the model code is separately published. Before you start, download the CLIP encoder into ./ckpts, run the single image inference on one of the provided samples with --guidance_scale 2.5, and compare against the same mask at the value of 1.0 that the paper benchmarks used, since the two settings trade removal strength against background preservation in opposite directions.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. zjx0101/ObjectClear on GitHub