The 'Overlay' method

Argument: Nested or integer vector (see text)
Result: None

Valid for: Image

The Overlay method allows you to overlay one image (the foreground image) on to another (the background image). If the foreground image is transparent, the background image will be partially visible through the foreground image.

The background image should first be loaded into an Image object. You then copy the foreground image to a specified location on the background image. The foreground image usually comes from a file, but it can come from another Image object.

To load a foreground image from file, call the Overlay method with this syntax:

      Image.Overlay 'file_name' Top Left <Mode>
or
     'ImageName' ⎕WI 'Overlay' 'file_name' Top Left <Mode>

where file_name is the name of the file to load (one of the standard formats supported by ImageMagick), and Top and Left are the positions in the Image control where it should be loaded (these can be omitted, in which case 0 0 is assumed). If the file name is an empty vector, a dialog will be invoked to allow the user to select a file. The last parameter Mode is normally not needed - see below.

To load a foreground image from another Image object, call the Overlay method with this syntax:

      Image.Overlay Handle Top Left <Mode>
or
     'ImageName' ⎕WI 'Overlay' Handle Top Left <Mode>

where the Handle parameter is an integer representing the handle property of the source Image object. This is very useful if you want to create the foreground image dynamically, or load a non-transparent image and make it transparent (see the Setopacity method)

This function loads a background image from file, and places a foreground image (also from file) over it:

      ∇DEMO_Overlay;Win
[1]   '⎕' ⎕wi 'scale' 5
[2]   Win←'⎕' ⎕NEW 'form' ⋄ Win.title←'Transparency' ⋄ Win.where←1 1 420 700
[3]   Win.Pic.new 'Picture'
[4]   Win.Pic.Img.new 'Image' ⋄ Win.Pic.Img.scale←5 ⋄ Win.Pic.align←¯1
[5]   Win.Pic.Img.file←'c:\pictures\background.jpg'
[6]   Win.Pic.Img.Overlay 'c:\pictures\foreground.png' 200 120
[7]   ⊣1 ⎕WE Win
      ∇

This version of the function does the same, but uses a second Image object to hold the foreground image and transform it, before copying it into the background:

      ∇DEMO2_Overlay;Win;Img2;handle
[1]   '⎕' ⎕wi 'scale' 5
[2]   Win←'⎕' ⎕NEW 'form' ⋄ Win.title←'Transparency' ⋄ Win.where←1 1 420 700
[3]   Win.Pic.new 'Picture'
[4]   Win.Pic.Img.new 'Image' ⋄ Win.Pic.Img.scale←5 ⋄ Win.Pic.align←¯1
[5]   Win.Pic.Img.file←'c:\pictures\background.jpg'
[6]  ⍝ Create a second (invisible) image object:
[7]   Img2←'⎕' ⎕new 'Image'
[8]   Img2.file←'c:\pictures\foreground.png'
[9]   Img2.Transform 'Flip'
[10]  handle←Img2.handle
[11]  Win.Pic.Img.Overlay handle 200 120
[12]  ⊣1 ⎕WE Win
      ∇

The 'mode' parameter

The underlying ImageMagick call which does the copying is MagickCompositeImage(). If you omit the final Mode parameter, this is called with the 'compose' type set to AtopCompositeOp, which means that the foreground image is placed over the background image. This is the most common requirement. However, there are other possible values which you can specify as the Mode parameter. These are defined in an 'enum' called CompositeOperator in the ImageMagick source; unfortunately, the exact values of the mode parameter may vary from one release of ImageMagick to another, so you will need to check the ImageMagick include files (composite.h) to get the numeric values for the particular version you are using - they start with UndefinedCompositeOp = 0.

Useful values include:

OverCompositeOp
The result is the union of the the two image shapes with composite image obscuring image in the region of overlap. If the foreground pixel is part or all transparent, the corresponding background pixel will show through.

InCompositeOp
The result is simply the foreground image cut by the shape of the background. None of the image data of the background image is included in the result.

OutCompositeOp
The resulting image is foreground image with the shape of image cut out.

AtopCompositeOp
Same as OverCompositeOp, except the portion of the foreground image outside of the background image's shape does not appear in the result.

XorCompositeOp
The result is the image data from both the foreground and background images that is outside the overlap region. The overlap region will be blank.

PlusCompositeOp
The result is just the sum of the image data. Output values are cropped to 255 (no overflow). This operation is independent of the matte channels.

MinusCompositeOp
The result of foreground image - image, with overflow cropped to zero. The matte chanel is ignored (set to 255, full coverage).

AddCompositeOp
The result of foreground image + image, with overflow wrapping around (mod 256).

SubtractCompositeOp
The result of foreground image - image, with underflow wrapping around (mod 256). The add and subtract operators can be used to perform reversable transformations.

DifferenceCompositeOp
The result of abs(foreground image - image). This is useful for comparing two very similar images.

MultiplyCompositeOp
Multiplies the color of each target image pixel by the color of the corresponding foreground image pixel. The result color is always darker.

BumpmapCompositeOp
The result image shaded by the foreground image.

ReplaceCompositeOp
The resulting image is image replaced with foreground image. Transparency is ignored.

CopyCompositeOp
Replace the target image with the foreground image.

CopyRedCompositeOp
Copy the red channel from the foreground image to the target image.

CopyGreenCompositeOp
Copy the green channel from the foreground image to the target image.

CopyBlueCompositeOp
Copy the blue channel from the foreground image to the target image.

ClearCompositeOp
Make the background image transparent. The contents of the foreground image are ignored.

DissolveCompositeOp
Use to foreground image to 'dissolve' the background it overlays.

DarkenCompositeOp
Replace target image pixels with darker pixels from the foreground image.

LightenCompositeOp
Replace target image pixels with lighter pixels from the foreground image.

HueCompositeOp
Each pixel in the result image is the combination of the hue of the target image and the saturation and brightness of the foreground image.

SaturateCompositeOp
Each pixel in the result image is the combination of the saturation of the target image and the hue and brightness of the foreground image.

ColorizeCompositeOp
Each pixel in the result image is the combination of the brightness of the target image and the saturation and hue of the foreground image. This is the opposite of LuminizeCompositeOp.

LuminizeCompositeOp
Each pixel in the result image is the combination of the brightness of the foreground image and the saturation and hue of the target image. This is the opposite of ColorizeCompositeOp.

ScreenCompositeOp
Multiplies the inverse of each image's color information.

CopyCyanCompositeOp
Copy the cyan channel from the foreground image to the target image.

CopyMagentaCompositeOp
Copy the magenta channel from the foreground image to the target image.

CopyYellowCompositeOp
Copy the yellow channel from the foreground image to the target image.

CopyBlackCompositeOp
Copy the black channel from the foreground image to the target image.

ColorDodgeCompositeOp
Brightens the destination color to reflect the foreground color. Painting with black produces no change.

HardLightCompositeOp
Multiplies or screens the colors, dependent on the source color value. If the foreground color is lighter than 0.5, the destination is lightened as if it were screened. If the foreground color is darker than 0.5, the destination is darkened, as if it were multiplied. The degree of lightening or darkening is proportional to the difference between the foreground color and 0.5. If it is equal to 0.5 the destination is unchanged. Painting with pure black or white produces black or white.

SoftLightCompositeOp
Darkens or lightens the colors, dependent on the foreground color value. If the source color is lighter than 0.5, the destination is lightened. If the foreground color is darker than 0.5, the destination is darkened, as if it were burned in. The degree of darkening or lightening is proportional to the difference between the foreground color and 0.5. If it is equal to 0.5, the destination is unchanged. Painting with pure black or white produces a distinctly darker or lighter area, but does not result in pure black or white.