Working with DICOM Overlays

General Information 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 attributes Each overlay has a number of attributes (or properties), which can be set by the user. These attributes are broken into two categories:

Display attributes

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.

DICOM-related attributes

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.

Overlay operations 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:

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

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:

Get the bitplane into an overlay image using the RasterImage.UpdateOverlayBits method, specifying the RasterUpdateOverlayBitsFlags.FromImage flag.
Apply the image processing function
Restore the desired main bitmap bitplane using the RasterImage.UpdateOverlayBits method, specifying the RasterUpdateOverlayBitsFlags.FromOverlay flag.

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.