libcom: a Python toolbox that gathers the many tasks of image composition

The problem is broader than copy and paste, and it splits into named tasks

libcom is the library of image composition, and the library describes itself as an image composition toolbox. The core problem it names is inserting one foreground into a background image to get a realistic composite, by addressing the inconsistencies between foreground and background in three ways: appearance, geometry and semantic inconsistency.

The reason it is a toolbox rather than a script is that image composition research has fragmented into a long list of narrow tasks, each with its own published method and its own evaluation. The library covers image blending, standard and painterly image harmonization, shadow generation, reflection generation, object placement, generative composition and quality evaluation, and the stated policy for each task is to integrate one or two selected methods with an eye to both efficiency and effectiveness, updated as better methods appear.

That selection policy is the design decision worth noticing. Rather than reimplementing the literature, the project curates it: for harmonization you get the standard and the painterly variant, for placement assessment you get both a pairwise score and a heat map over all positions and scales, and for generative composition there are two models with different levels of freedom. The stated ultimate goal is solving all the problems related to image composition with a simple import libcom, which is a goal rather than a current state, and the topics on the repository list the task names one by one, including cross domain composition, object relighting and inharmonious region localization.

The API is a list of model classes, one per published method

The main functions section reads as an inventory of what you can call, and the shape is consistent: each entry is a class that wraps a named method with its own weights and its own input contract.

Generation starts with get_composite_image, which does a naive copy and paste followed by image blending, either alpha blending or Poisson blending. That is the baseline, and it is deliberately simple, which makes it a useful control for measuring what the learned models add.

Around it sit the harmonization models. ImageHarmonizationModel adjusts the foreground illumination to be compatible with a photorealistic background, while PainterlyHarmonizationModel adjusts the foreground style for an artistic background with a photorealistic foreground, which is a different problem since matching a painted background is a style transfer rather than a relighting exercise. Color transfer is the traditional method, adjusting foreground colour to match background.

The evaluation side is just as large. HarmonyScoreModel judges whether foreground illumination is harmonious with the background, InharmoniousLocalizationModel finds the inharmonious region in a synthetic image, FOSScoreModel evaluates geometry and semantic compatibility, and the placement models cover the same idea from two directions. OPAScoreModel evaluates the rationality of the location and scale of a placed object, while FOPAHeatMapModel predicts rationality scores for all locations and scales for a background and foreground pair, which lets it output a composite with the optimal placement rather than just judging one.

Shadow, reflection and the two generative compositors

The effects that make an insertion believable are represented by dedicated models. ShadowGenerationModel generates a plausible shadow for the inserted object, and ReflectionGenerationModel generates a plausible reflection for it. Neither is a filter you apply to the composite, they are models that produce the extra pixels that sell the object's presence in the scene.

The generative compositors are where the recent work has gone, and the two classes differ in how much freedom they take. KontextBlendingHarmonizationModel is a generative image composition model that inserts the foreground into a specified bounding box in the background, with the pose and view of the foreground unchanged. It has two modes, and the difference is the interesting part: the blending mode does not adjust the foreground illumination, while the harmonization mode does adjust it to make the composite harmonious.

OSInsertModel also inserts the foreground into a specified bounding box, but it varies how much it is allowed to change the foreground. The conservative mode has weak ability to adjust the pose and view of the foreground according to the background, while the aggressive mode goes further. So the axis of variation across the two models is how much of the foreground the compositor is permitted to rewrite, and the two modes inside each class give you a dial between preserving what you pasted and letting the model fix it.

The requirements file shows the machinery behind these classes, with diffusers and transformers for the diffusion based ones, mmdet and mmpose for detection and pose, segment anything and clip for the os_insert path, and lpips and pydantic for the LBM model.

A heavy dependency set, and the weight of every selected method

The requirements file is the honest summary of what this package costs to install.

einops
huggingface_hub
imageio
torch==2.6.0
torchvision==0.21.0
diffusers==0.34.0
mmdet==3.2.0
mmpose==1.2.0
transformers==4.44.2

The pins are exact for the core of the stack, torch at 2.6.0 and torchvision at 0.21.0, diffusers at 0.34.0, mmdet at 3.2.0 and mmpose at 1.2.0, with transformers at 4.44.2, and a batch of supporting packages including huggingface_hub, modelscope, peft, open_clip_torch, taming-transformers-rom1504, scikit-learn and pytorch_lightning. The last group is the extra weights for specific models, with segment_anything and clip under an os_insert heading and pydantic plus lpips under lbm, which is a good sign about how the file is organised, since the dependencies of a model are grouped with the model that needs them rather than dumped in one list.

Two consequences follow. First, a fixed environment: a research codebase that pins torch and a detection framework exactly is one where the pinned versions are known to work together, and loosening them is your problem. Second, size. The library covers many tasks, and the union of their requirements is what you install, so a project that only needs harmonization still pulls the detection and pose stacks. The stated goal of a single import is convenient at the API level and expensive at the environment level.

The installation path itself is a plain setup.py with a custom post install command that prints a banner pointing at the online workbench, and the package is on PyPI as libcom.

An online workbench, a survey and a request for contributed models

Alongside the library there is an online workbench hosted at libcom.ustcnewly.com, built on the toolbox itself, with a screenshot in the README showing the interface. For a research library, a hosted workbench is a genuine convenience, since it lets someone try a method on an example pair without setting up the environment, and it doubles as a demo for the maintainers.

The project also maintains a broader set of resources. The README links an Awesome-Object-Insertion repository as dataset and code resources, and an arXiv survey at 2106.14490, and there is a WeChat discussion group for image composition and object insertion, plus a WeChat public account and a Zhihu column for updates. The library is published on PyPI with version and download badges.

The contribution model is stated in the README, and it is unusually specific about what the maintainers want. They welcome recommendations of self-developed models or models the sender has tested, to be opened as an issue, and the criterion is that a model delivers outstanding and stable performance before it will be considered for integration. There is a separate invitation for people who specialise in model inference acceleration, both voluntary and paid collaborations, with a contact address given.

That policy explains the shape of the library. It is a curated index of the best available method per task, maintained by a small group with the compute to run and compare them, and the cost of that curation is that you get one or two choices per task rather than a complete survey in code.

Where libcom does not reach

The clearest limit is that this is a research library, not a product. The models are large neural networks that need checkpoints, the environment is heavy, and the API is organised around loading a model class and calling it, which is the right shape for experiments and the wrong shape for a request handler. There is no service layer, no batching story and no latency budget anywhere in the description.

The second limit is that the task coverage is by curation, not by completeness. You get the methods the maintainers selected, and the stated policy is that they will be replaced as better ones appear. A paper that needs a specific baseline that is not the one selected is not served by this library, and the selection will change under you between versions.

The third is the fundamental one that the project is honest about. The library takes a foreground image and a background image, and it makes them consistent. It does not generate the foreground, it does not segment the object for you in general, and it does not decide what should be in the scene. Object insertion is a pipeline that starts upstream of this library, and the quality ceiling sits wherever your foreground came from.

The maintenance record is recent enough to be comfortable, with the last push on 2026-10-05, but the repository has no GitHub releases at all, so there are no version tags to pin and the PyPI version is the only release marker.

Editorial conclusion

Adopt libcom if you are doing image composition research and want the published methods for harmonization, placement scoring, shadow and reflection generation available through one API instead of five separate repositories. Do not adopt it for production pipelines without checking the dependency weight, because the requirements pin torch, torchvision, diffusers, mmdet and mmpose, and the models themselves pull separate checkpoints. Before you start, decide which tasks you actually need, since the stated goal of a single import comes at the cost of installing the union of every selected method's requirements.

Frequently asked questions

Official sources

1. bcmi/libcom on GitHub
2. Issues
3. License: Apache-2.0
4. README