Composite Two Images

Problem

You have two images, Patches.exr and Ball.exr, and you wish to composite Ball.exr over Patches.exr, so that the ball appears in the bottom right corner of the image.

Solution

import Draft

img = Draft.Image.ReadFromFile( 'Patches.exr' )
ballImg = Draft.Image.ReadFromFile( 'Ball.exr' )
anchor = Draft.Anchor.SouthEast
compOp = Draft.CompositeOperator.OverCompositeOp
img.CompositeWithAnchor( ballImg, anchor, compOp )

img.WriteToFile( 'Patches with ball.exr' )

Discussion

We have three choices of composite methods, which differ in how we control the positioning of the top image: Composite(), CompositeWithAnchor(), and CompositeWithPositionAndAnchor().

The first method, Composite(), takes four parameters: the second image that will be composited with the current image, two floating point values that specify the horizontal and vertical offset of the second image relative to the first image, and the composite operator, which specifies how the pixels of the two images will be combined. The coordinates of the bottom left corner of the second image are given as a fraction of the width and height of the current image, and specify the distance from the bottom left corner of the current image. For example, if we wanted the second image’s bottom left corner to be positioned at 10% of the height of the first image, and 30% of the width, we would use:

xPos = 0.3
yPos = 0.1
img.Composite( ballImg, xPos, yPos, Draft.CompositeOperator.OverCompositeOp )

The second method, CompositeWithAnchor(), is the method we have chosen to use in our example. CompositeWithAnchor() takes three parameters; the first and last parameters (image and operation) are the same as Composite(), but now the second parameter, which specifies how to position the second image, is a named anchor constant. This named anchor constant specifies which coordinates of the two images are aligned. For example, Draft.Anchor.North specifies that the top centre of both images are aligned, whereas Draft.Anchor.SouthEast specifies that the bottom right corners of the images are aligned. The named Anchor coordinates correspond to the eight cardinal and intercardinal directions (NorthWest, North, NorthEast, East, SouthEast, South, SouthWest, West), plus Center.

The third method, CompositeWithPositionAndAnchor(), uses both position and anchor parameters, as its name implies. The position specifies a location on the current image, again as coordinates from the bottom left corner measured as a percentage of width and height. The anchor specifies which location on the second image will be aligned with the position on the first image. For example, if we want the centre of the second image to be located at the horizontal centre of the first image, 25% up from the bottom, we would use:

xPos = 0.5
yPos = 0.25
anchor = Draft.Anchor.Center
compOp = Draft.CompositeOperator.OverCompositeOp
img.CompositeWithPositionAndAnchor( ballImg, xPos, yPos, anchor, compOp )

Once we have chosen our method of positioning, there are many choices for how we combine the pixels of one image with the pixels of another. The most common composite operation is the “over” operation, which we select by using the over operator constant, Draft.CompositeOperator.OverCompositeOp. With the over operation, opaque pixels from ballImg will replace the corresponding pixels in img, and transparent pixels will leave the underlying pixels in img unchanged. For semi-transparent pixels in ballImg, we get a blend of the foreground and background that depends on the alpha value of the ballImg pixel.

Note that Draft assumes all images are not premultiplied; in other words, the color channels have not been multiplied by the alpha channel. Draft does any premultiplication necessary for the composite operation, and also returns an image that is unpremultiplied. If your images are already premultiplied, you can use img.Unpremultiply() to unpremultiply the image.

See Also

For more information on the import statement, ReadFromFile(), and WriteToFile(), see the Creating an Image section of this Cookbook.

For more information on the various composite operators, see the Library Reference.