Overlay images are separate 1-bit images that are drawn on top of you main image. Every main image can have up to 17 (RasterImage.MaxOverlays + 1) overlay images. The overlays are stored in an array containing RasterImage.MaxOverlays + 1 entries. Each array entry contains the overlay image and its attributes. The array uses a 0-based index. (That is the index of the first entry is 0.)

For each overlay, the overlay pixels with a value of 0 are considered transparent. The overlay pixels with a value of 1 are considered non-transparent and will be painted using the color set by the use in RasterOverlayAttributes.Color.

The overlays can be painted automatically by the RasterImage.Paint method or you can paint them manually using RasterImage.PaintOverlay. RasterImage.Paint paints the overlays in ascending index order: The overlay with index 0 is painted first, overlay with index 1 is painted next, etc. If you need to change the order in which the overlays are painted, you must paint them manually with RasterImage.PaintOverlay. Another option is to rearrange the overlays and make sure that the overlay with index 0 is the overlay you want painted first, and then use RasterImage.Paint.

Each overlay has a number of attributes (or properties), which can be set by the user. These attributes are broken into two categories:

1. Display attributes

   These properties specify how an overlay gets painted:

   RasterOverlayAttributes.Origin	The top-left offset, relative to the top-left displayed margin of the image. The offset is in the display view perspective, with the 0,0 being the top-left corner.
   RasterOverlayAttributes.Color	The color used to paint bits 1 of the overlay.
   Index	Each overlay has an index (0 – RasterImage.MaxOverlays). All methods to get/set an overlay attribute or its image takes an index parameter.
   RasterOverlayAttributes.BitPosition	The associated bit plane (valid only for grayscale 8, 12 and 16-bits per pixel images). Each overlay can be associated with an image bit plane (between 0 and image’s RasterImage.BitsPerPixel – 1). You can specify whether you want to associate each overlay with a bit plane or not. Do not confuse this with Index . The overlay’s associated BitPosition does not have to be the same as the overlay index. This property is valid only if the RasterOverlayAttributes.UseBitPlane is set to true.
   RasterOverlayAttributes.AutoPaint	Determines whether the overlay is automatically painted by the RasterImage.Paint method or not. If set, Paint will automatically paint this overlay. If not set, Paint will not automatically paint this overlay. In this case, you might want to paint the overlay manually, using RasterImage.PaintOverlay.
   RasterOverlayAttributes.AutoProcess	Determines whether the overlay will be automatically processed when the associated image changes. If set to true, the overlay will be automatically processed when the associated image is rotated, flipped, reversed, resized, sheared. The left, right and the overlay size will automatically be adjusted to stay on the corresponding image pixels. If set to false, the overlay will not be automatically processed when the associated image is rotated, flipped, reversed, resized, sheared.
   RasterOverlayAttributes.UseBitPlane	Indicates whether the RasterOverlayAttributes.BitPosition attribute should be used or not. If set to true, BitPosition is a corresponding plane index (0 - image bits/pixel – 1). If set to false, the BitPosition property is ignored.

2. DICOM-related attributes

   These properties are DICOM specific and are based on the "Overlay Plane Module Attributes" defined in PS 3.3 of the DICOM standard:

   RasterOverlayAttributes.Rows	Number of rows in the overlay.
   RasterOverlayAttributes.Columns	Number of columns in the overlay.
   RasterOverlayAttributes.Type	Indicates whether this overlay represents a region of interest or other graphics.
   RasterOverlayAttributes.BitsAllocated	Number of bits allocated in the overlay.
   RasterOverlayAttributes.Description	User-defined comments about the overlay.
   RasterOverlayAttributes.Subtype	Defined term, which identifies the intended purpose of the overlay type.
   RasterOverlayAttributes.Label	A user-defined text string, which may be used to label or name this overlay.
   RasterOverlayAttributes.RoiArea	Number of pixels in the Region Of Interest.
   RasterOverlayAttributes.RoiMean	Average pixel value in the Region Of Interest.
   RasterOverlayAttributes.RoiStandardDeviation	Standard deviation of the pixel values in the Region Of Interest.
   RasterOverlayAttributes.FramesInOverlay	Number of frames in the overlay. This is required if the overlay data contains multiple frames.
   RasterOverlayAttributes.ImageFrameOrigin	Number of the frame of a multi-frame image to which this overlay applies; frames are numbered starting with 1.
   RasterOverlayAttributes.ActivationLayer	The layer in which the overlay shall be displayed.

The overlay array is automatically created the first time you set the attributes or the image for a particular overlay index. The overlay array is automatically disposed when the main image is disposed. To set the attributes for a specific overlay, use RasterImage.UpdateOverlayAttributes. One or more attributes may be set at a time. To get the current attributes for a specific overlay, call RasterImage.GetOverlayAttributes. The RasterImage.OverlayCount gets the number of overlays that have been defined.

The overlay images are independent of the main image. Separate memory is allocated for each overlay image. You can set the overlay image by:

1. Calling RasterImage.SetOverlayImage and passing the overlay image.
2. Having LEADTOOLS generate an overlay image from the bits of a certain bitplane from the main image by calling RasterImage.UpdateOverlayBits and specifying the RasterUpdateOverlayBitsFlags.FromImage flag.

To get the overlay bitmap for a specific overlay, call RasterImage.GetOverlayImage.

You can update the corresponding bitplane in the main image with the bits from the overlay image by calling RasterImage.UpdateOverlayBits and specifying the RasterUpdateOverlayBitsFlags.FromOverlay flag. This may be used to preserve a specific bitplane during an image processing function. To prevent a certain image processing function from affecting a bitplane:

• Get the bitplane into an overlay image with RasterImage.UpdateOverlayBits and specifying the RasterUpdateOverlayBitsFlags.FromImage flag.
• Apply the image processing function
• Restore the desired main bitmap bitplane with RasterImage.UpdateOverlayBits and specifying the RasterUpdateOverlayBitsFlags.FromOverlay flag.

To preserve the whole bitplane, make sure the overlay offset is 0,0 and that the overlay has the same size as the overlay image. This is true by default, but if you change the overlay position and size, you must reset them.

The default overlay width is the display image width – the overlay's left offset. The overlay's left offset is set in RasterOverlayAttributes.Origin.X. The display width depends on the image’s RasterImage.ViewPerspective and it is the width of the image painted on the screen with a zoom factor of 100 percent.

The default overlay height is the display image height (the overlay's top offset). The overlay's top offset is set in RasterOverlayAttributes.Origin.Y.

You can change the size of the overlay image by calling RasterImage.SetOverlayImage. Note that you can call RasterImage.SetOverlayImageSize. to create an empty overlay with the specified size.