Send comments on this topic. | Back to Introduction - All Topics | Help Version 17.5.11.19
Overlay images are separate 1-bit images that are drawn on top of the 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, any overlay pixels with a value of 0 are considered transparent. Overlay pixels with a value of 1 are considered non-transparent and will be painted using the color set in the RasterOverlayAttributes.Color property.
Overlays can be painted automatically by using the RasterImagePainter.Paint method or manually by using the RasterImagePainter.PaintOverlay method. The RasterImagePainter.Paint method paints the overlays in ascending index order: The overlay with index 0 is painted first, the 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 using the RasterImagePainter.PaintOverlay method. 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 RasterImagePainter.Paint.
Overlay attributesEach overlay has a number of attributes (or properties), which can be set by the user. These attributes are broken into two categories:
The following 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 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 the image's RasterImage.BitsPerPixel - 1). Specify whether you want to associate each overlay with a bit plane. Do not confuse this with the 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 RasterImagePainter.Paint method. If set, the Paint method will automatically paint this overlay. If not set, Paint will not automatically paint this overlay. In such cases, you can paint the overlay manually, using the RasterImagePainter.PaintOverlay method. |
| 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, or sheared. The left, right and the overlay size will automatically be adjusted to stay on top of 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. If set to true, the BitPosition is a corresponding plane index (0 - image bits/pixel - 1). If set to false, the BitPosition property is ignored. |
The following 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 the RasterImage.UpdateOverlayAttributes method. One or more attributes can be set at a time. To get the current attributes for a specific overlay, call the RasterImage.GetOverlayAttributes method. The RasterImage.OverlayCount method gets the number of overlays that have been defined.
Overlay images are independent of the main image. Separate memory is allocated for each overlay image. Set the overlay image by:
To get the overlay bitmap for a specific overlay, call the RasterImage.GetOverlayImage method.
Update the corresponding bitplane in the main image with the bits from the overlay image by calling the RasterImage.UpdateOverlayBits method and specifying the RasterUpdateOverlayBitsFlags.FromOverlay flag. This can be used to preserve a specific bitplane during an image processing function. To prevent a certain image processing function from affecting a bitplane:
To preserve the entire 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 the RasterOverlayAttributes.Origin.X property. 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 the RasterOverlayAttributes.Origin.Y property.
Change the size of the overlay image by calling the RasterImage.SetOverlayImage method. Note that you can call the RasterImage.SetOverlayImageSize method to create an empty overlay having the specified size.