This repository contains a C++ program that implements the seamless Poisson image-cloning technique described in "Poisson Image Editing" by Patrick Pérez, Michel Gangnet, & Andrew Blake in 2003.
Follow these instructions in order to run this program on your local machine (NB: this has only been tested on Mac OSX).
This project requires the following libraries:
First, install the prerequisites using your favorite method (homebrew is recommended for Mac OSX). Then, download this repository, and run the Makefile using $ make. The C++ program should compile into poisson_clone without errors.
Once poisson_clone has been compiled, run it in the command line using the following arguments:
$ ./poisson_clone src.png mask.png dest.png out.png xOffset yOffset [-FLAG [extraArgs]]
Here is a breakdown of the meaning of the arguments and avaliable flags:
- src.png => file path to source image (required)
- mask.png => file path to mask image (required)
- dest.png => file path to dest image; must be of same dim as mask.png (required)
- out.png => file path to write result (required)
- xOffset => x offset in src.png (required)
- yOffset => y offset in src.png (required)
- flag argument (optional):
- no flag or unrecognized flag => seamless Poisson cloning
- "-d" or "-direct" => direct cloning
- "-mono" or "-monochrome" => convert src to monochrome before applying Poisson cloning
- "-mx" or "-mixed" => use mixed cloning (mix gradients of dest and src)
- "-f" or "-flat" followed by
threshold factor=> Threshold gradients abovethresholdand scale them byfactor - "-il" or "-illumination" followed by
alpha beta=> Apply exposure/specular correction usingalphaandbetaas parameters for applying a nonlinear transformation to the source gradient - "-dec" or "-decolor" => Attempt to decolor the background by converting the destination to monochrome before applying seamless Poisson cloning
- "-rec" or "-recolor" followed by
scaleR scaleG scaleB=> Scale color source channels by the provided parameters before applying Poisson cloning - "-tex" or "-texture" followed by
threshold=> Preserve grain (gradient below threshold) in dest
This section contains descriptions of each cloning mode in this program, along with examples on how to run them.
Poisson cloning is the main workhorse of this program and is run without flags:
$ ./poisson_clone src.png mask.png dest.png out.png xOffset yOffset
This method of cloning solves a sparse linear system of equations of the form Ax = b bound by two contraints: (1) the border of the cloned region must match the border of the region before cloning, and (2) the color gradient-field within the pasted cloned-region must match the gradient-field of the source cloned-region as closely as possible.
In pseudocode, the matrices and vectors for this system of equations are constructed as follows:
for each pixel i in the mask:
Np = 0 // "Number of neighbors"
for each neighbor j of i:
set Aij to -1 if j in mask;
add dest[j] to b_i if j in image but not in mask (=> j is a border pixel)
add 1 to Np if j is in image
add guidance (src[i] - src[j]) to b_i if j is in image
set Aii to num neighbors Np
| Direct Cloning | Poisson Cloning |
|---|---|
 |
 |
 |
 |
 |
 |
 |
 |
Direct cloning is the naive (seamed) implementation of cloning and requires a -d or -direct flag. It takes no further parameters:
$ ./poisson_clone src.png mask.png dest.png out.png xOffset yOffset -d
or
$ ./poisson_clone src.png mask.png dest.png out.png xOffset yOffset -direct
Monochromatic cloning requires the -mono or -monochrome flag and takes no further parameters:
$ ./poisson_clone src.png mask.png dest.png out.png xOffset yOffset -mono
or
$ ./poisson_clone src.png mask.png dest.png out.png xOffset yOffset -monochrome
First monochromatic cloning converts the source image to greyscale through luminance, and it then applies Poisson cloning on using the black and white source image. This is useful when the chromacity of the cloned region needs to remain relatively constant, as the default (polychromatic) Poisson cloning will allow for changes in color within the cloned region that are somewhat independent of the destination's border constraints.
| Source | Destination | Polychromatic Poisson Cloning | Monochromatic Poisson Cloning |
|---|---|---|---|
 |
 |
 |
 |
Mixed cloning requires the -mx or -mixed flag and takes no further parameters:
$ ./poisson_clone src.png mask.png dest.png out.png xOffset yOffset -mx
or
$ ./poisson_clone src.png mask.png dest.png out.png xOffset yOffset -mixed
Sometimes there is detail in the target region of the destination that needs to be preserved (e.g. a brick wall, or a sharp edge in the background). This is accomplished by adjusting the guidance function between two pixels (i, j) such that if the gradient between pixels i and j are greater (by magnitude) in the destitiation image than in the source, this larger gradient will be used for the system of equations
| Source | Destination | Poisson Cloning | Mixed Poisson Cloning |
|---|---|---|---|
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
Image flattening requires the -f or -flat flag along with threshold and factor values. It is recommended that the source and destination arguments point to the same image, and that the offsets are set to 0:
$ ./poisson_clone src.png mask.png src.png out.png 0 0 -f threshold factor
or
$ ./poisson_clone src.png mask.png src.png out.png 0 0 - flat threshold factor
Image flattening throws away gradients in the source that do not exceed the threshold value in magnitude. As such, only the sharper edges and features of the image are preserved, giving a flattening feel. The preserved gradients are either compressed or heightened depending on whether factor is greater than or less than 1 respectively.
| Source | Image Flattening |
|---|---|
 |
 |
Local illumination requires the -il or -illumination flag along with alpha and beta values. It is recommended that the source and destination arguments point to the same image, and that the offsets are set to 0:
$ ./poisson_clone src.png mask.png src.png out.png 0 0 -il alpha beta
or
$ ./poisson_clone src.png mask.png src.png out.png 0 0 -illumination alpha beta
Nonlinear expansion and compression of the source image gradient (applied through alpha and beta) can be used to fix locally underexposed (e.g. shadows) and overexposed (e.g. specular highlights) areas in images. It is recommended that alpha is set to a value in the vicinity of 0.2 times the average gradient of the image, and that beta be set to a value simply within the neighborhood of 0.2.
| Source | Local Illumination |
|---|---|
 |
 |
 |
 |
Background decolorization requires the -dec or -decolor flag and takes no further parameters. It is recommended that the source and destination arguments point to the same image, and that the offsets are set to 0:
$ ./poisson_clone src.png mask.png src.png out.png 0 0 -dec
or
$ ./poisson_clone src.png mask.png src.png out.png 0 0 -decolor
If there is a particularly colorful area within an image (more specifically, that the region has a distinct color from its immediate surroundings), then if the source is Poisson-cloned onto a greyscale version of itself, the colorful region should still retain its color through the cloning process.
| Source | Background Decolorization |
|---|---|
 |
 |
Local recolorization requires the -rec or -recolor flag as well as three additional parameters that coorespond to the scaling of RGB in recolorization. It is recommended that the source and destination arguments point to the same image, and that the offsets are set to 0:
$ ./poisson_clone src.png mask.png src.png out.png 0 0 -rec scaleR scaleG scaleB
or
$ ./poisson_clone src.png mask.png src.png out.png 0 0 -recolor scaleR scaleG scaleB
Recoloring works by scaling RGB values in the source image by the specified amounts before applying Poisson cloning. The bordering region around the object of interest in the mask will return to its original color when the boundary constraints of the cloning process are applied, the but object of interest itself will retain its new color.
| Source | Background Local Recolorization |
|---|---|
|
 |
Texture preserving poisson cloning requires the -tex or -texture flag as well as one addition threshold argument:
$ ./poisson_clone src.png mask.png src.png out.png xOffset yOffset -tex threshold
or
$ ./poisson_clone src.png mask.png src.png out.png xOffset yOffset -texture threshold
This is an experimental extension that was not proposed in the original 2003 paper. Although Poisson cloning is excellent at removing seams, differences between cloned textures and the destination textures (e.g. grain) can still leave an apparent seam around the cloning region. In an effort to preserve grain and other small details of the destination, gradients in the destination below the threshold are added onto the source gradient in this mode. Unfortunately, this method is not always successful as discoloration occasionally pops up, and it is not able to remove any grain from the source (so it effectively only adds grain and other nearly imperceptible details).
| Poisson Cloning vs. Poisson Cloning with Texture Preservation |
|---|
 |
- Reilly Bova - Cloning Program and Examples - ReillyBova
- Szymon Rusinkiewicz - Basic C++ and C Image I/O files
See also the list of contributors who participated in this project.
[1] Pérez, Patrick, Michel Gangnet, and Andrew Blake. "Poisson image editing." ACM Transactions on Graphics (TOG). Vol. 22. No. 3. ACM, 2003.
This project is licensed under the MIT License - see the LICENSE.md file for details
Thank you to Professor Szymon Rusinkiewicz for teaching and assigning this brilliant technique in the Fall 2018 semester of COS 526: Advanced Computer Graphics