Overlay Overview

General information

Overlay bitmaps are separate 1-bit bitmaps that are drawn on top of you main bitmap. Every main bitmap can have up to 17 (MAX_OVERLAYS + 1) overlay bitmaps. 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 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 OVERLAYATTRIBUTES.crColor.

The overlays can be painted automatically by the L_PaintDC function or you can paint them manually using L_PaintDCOverlay. L_PaintDC 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 L_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 L_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 L_PaintDC functions or not. If set, L_PaintDC will automatically paint this overlay. If not set, L_PaintDC will not automatically paint this overlay. In this case, you might want to paint the overlay manually, using L_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 indicates 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 the Region Of Interest.
ROIMean	Average pixel value in the Region Of Interest.
ROIStandardDeviation	Standard deviation of the pixel values in the Region Of Interest.
NumFramesInOverlay	Number of frames in the overlay. This is required if the overlay data contains multiple frames.
ImageFrameOrigin	Number of the frame of a multi-frame image to which this overlay applies; frames are numbered starting with 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 main bitmap is freed. To set the attributes for a specific overlay, use L_SetOverlayAttributes. One or more attributes may be set at a time. TO get the current attributes for a specific overlay, call L_GetOverlayAttributes. The L_GetOverlayCount gets the number of overlays that have been defined.

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

1.	Calling L_SetOverlayBitmap and passing the overlay bitmap.
2.	Having LEADTOOLS generate an overlay bitmap from the bits of a certain bitplane from the main bitmap by calling L_UpdateBitmapOverlayBits and setting SETOVERLAYBITS_FROMBITMAP in uFlags.

To get the overlay bitmap for a specific overlay, call L_GetOverlayBitmap.

You can update the corresponding bitplane in the main bitmap with the bits from the overlay bitmap by calling L_UpdateBitmapOverlayBits and setting the SETOVERLAYBITS_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 bitmap with L_UpdateBitmapOverlayBits(…, SETOVERLAYBITS_FROMBITMAP);
apply the image processing function
restore the desired main bitmap bitplane with L_UpdateBitmapOverlayBits(…, SETOVERLAYBITS_FROMOVERLAY);

To preserve the whole bitplane, 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 – the overlay's left offset. The overlay's left offset is set in the OVERLAYATTRIBUTES.ptOrigin.x member. The display width depends on the bitmap’s view perspective 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 – the overlay's top offset. The overlay's top offset is set in the OVERLAYATTRIBUTES.ptOrigin.y member.

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