## 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.

Topic: APLX Help : System Classes : Methods : Overlay

[ Previous | Next | Contents | Index ]