Overlay Overview

General info

Every bitmap can have up to MAX_OVERLAYS + 1 (17) overlay bitmaps. Each overlay is a 1-bit image. The overlays are stored in an array containing MAX_OVERLAYS + 1 entries. Each array entry contains the overlay bitmap and its attributes. The array uses 0-based indexes (the index of the first entry is 0).

For each overlay, the overlay pixels with value of 0 are considered transparent.

For each overlay, the overlay pixels with value of 1 are considered non-transparent and will be painted with a certain color picked by the user.

The overlays can be painted automatically by the LPaint::PaintDC function or you can paint them using LPaint::PaintDCOverlay. The LPaint::PaintDC function 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 LPaint::PaintDCOverlay. 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 LPaint::PaintDC.

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

These properties specify how an overlay gets painted:

Origin	The top-left offset, relative to the top-left displayed margin of the bitmap. The offset is in the display view perspective, with the 0,0 being the top-left corner.
Color	The color used to paint bits 1 of the overlay.
Index	Each overlay has an index (0 – MAX_OVERLAYS).
BitPosition	The associated bit plane (valid only for grayscale 8, 12 and 16-bits per pixel bitmaps). Each overlay can be associated with a bitmap bit plane (between 0 and bitmap’s 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 UseBitPlane flag is set.
AutoPaint flag	Flag which determines whether the overlay is automatically painted by the LPaint::PaintDC functions or not. If set, LPaint::PaintDC will automatically paint this overlay. If not set, LPaint::PaintDC will not automatically paint this overlay. In this case, you might want to paint the overlay manually, using LPaint::PaintDCOverlay.
AutoProcess flag	Flag which determines whether the overlay will be automatically processed when the associated bitmap changes.
	If set, the overlay will be automatically processed when the associated bitmap is rotated, flipped, reversed, resized, sheared. The left, right and the overlay size will automatically be adjusted to stay on the corresponding bitmap pixels.
	If not set, the overlay will not be automatically processed when the associated bitmap is rotated, flipped, reversed, resized, sheared.
UseBitPlane flag	Flag that tells whether the BitPosition attribute should be used or not. If set, BitPosition is a corresponding plane index (0-bitmap bits/pixel – 1). If not set, the BitPosition property is ignored.

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:

Rows	Number of rows in the overlay.
Columns	Number of columns in the overlay.
Type	Indicates whether this overlay represents a region of interest or other graphics.
BitsAllocated	Number of bits allocated in the overlay.
Description	User-defined comments about the overlay.
Subtype	Defined term, which identifies the intended purpose of the overlay type.
Label	A user-defined text string, which may be used to label or name this overlay.
ROIArea	Number of pixels in ROI area.
ROIMean	ROI Mean.
ROIStandardDeviation	ROI standard deviation.
NumFramesInOverlay	Number of frames in overlay. Required if overlay data contains multiple frames.
ImageFrameOrigin	Frame number of multi-frame image to which this overlay applies; frames are numbered from 1.
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 bitmap for a particular overlay index. The overlay array is automatically freed when the bitmap is freed.

You set the attributes for a certain overlay index with LBitmap::SetOverlayAttributes. You can change one or more attributes at a time.

You can get the attributes for a certain overlay index with LBitmap::GetOverlayAttributes. You can find out how many overlays have been defined by calling LBitmap::GetOverlayCount.

The overlay bitmaps are independent of the main bitmap. Separate memory is allocated for each overlay bitmap.

You can set the overlay bitmap in two ways:

1.	Call LBitmap::SetOverlay and pass the overlay bitmap.
2.	Have LEADTOOLS generate an overlay bitmap for you from the bits of a certain bitplane from the main bitmap by calling LBitmap::UpdateOverlayBits and setting the SETOVERLAYBITS_FROMBITMAP flag.

You can get the overlay bitmap by calling LBitmap::GetOverlay.

You can update the corresponding bitplane in the main bitmap with the bits from the overlay bitmap by calling LBitmap::UpdateOverlayBits and setting the SETOVERLAYBITS_FROMOVERLAY flag. A typical use of this is if you want to make sure a certain bitplane is preserved by an image processing function. If you want to prevent a certain image processing function from affecting a bitplane, you can:

get the bitplane into an overlay bitmap with LBitmap::UpdateOverlayBits(…, SETOVERLAYBITS_FROMBITMAP);
apply the image processing
restore the desired main bitmap bitplane with LBitmap::UpdateOverlayBits(…, SETOVERLAYBITS_FROMOVERLAY);

In order to preserve the whole bitplane, you must make sure the overlay offset is 0,0 and that the overlay has the same size as the overlay bitmap. 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 bitmap width – Left offset. The display width depends on the bitmap’s ViewPerspective and it is the width of the bitmap painted on the screen with a zoom factor of 100%.

The default overlay height is the display bitmap height – top offset.

You can change the size of the overlay bitmap by calling LBitmap::SetOverlay. Note that you can call LBitmap::SetOverlay with an unallocated bitmap. In that case, only the width and height are used from the overlay bitmap.