LEADTOOLS For .NET Class Library Send comments on this topic. | Back to Introduction - All Topics | Help Version 17.0.3.28
Working with DICOM Overlays
General Information

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 RasterImagePainter.Paint method or you can paint them manually using RasterImagePainter.PaintOverlay. RasterImagePainter.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 RasterImagePainter.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 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:

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

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

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.