LDicomDS::GetOverlayBitmap

#include "ltdic.h"

L_UINT16 LDicomDS::GetOverlayBitmap(uOverlayIndex,pBitmap,uStructSize,uFlags)

L_UINT uOverlayIndex;	/* index */
pBITMAPHANDLE pBitmap;	/* pointer to the overlay bitmap handle */
L_UINT uStructSize;	/* size of a structure */
L_UINT uFlags;	/* reserved for future use */

Retrieves the "Overlay Data" (60xx,3000) for the specified overlay index.

Parameter	Description
uOverlayIndex	The index of the overlay for which to get the bitmap. This index is zero-based.
pBitmap	Pointer to a bitmap handle which will be filled with the overlay data. Cannot be NULL.
uStructSize	Size of the BITMAPHANDLE structure. Pass sizeof(BITMAPHANDLE).
uFlags	Reserved for future use. Pass 0.

Returns

0	The function was successful.
> 0	An error occurred. Refer to Return Codes.

Comments

This function will extract the "Overlay Data" (60xx,3000) for an overlay, initialize and allocate pBitmap based on the "Overlay Columns" (60xx,0011) and "Overlay Rows"(60xx,0010), and then fill pBitmap with the stream of bytes under the "Overlay Data" (60xx,3000) element. Please note that pBitmap is assumed to be unallocated and un-initialized. It will be filled without freeing the existing data.

If the function doesnt find the "Overlay Data" element inside the dataset it will return DICOM_ERROR_OVERLAY_DATA_MISSING.

Before calling this function you must call LDicomDS::GetOverlayAttributes to determine if the overlay pixel data is embedded in the "Image Pixel Data" (7FE0,0010) element or is under "Overlay Data" (60xx,3000) element. If the overlay data is embedded in the "Image Pixel Data", the flag OVERLAY_USEBITPLANE will be set inside pOverlayAttributes->uFlags (pOverlayAttributes is the OVERLAYATTRIBUTES structure returned by the LDicomDS::GetOverlayAttributes function).

If the overlay pixel data is embedded in the "Image Pixel Data" (7FE0, 0010), follow these steps to get the overlay data as a bitmap handle:

1.	Call one of the functions which can be used to extract the "Image Pixel Data", such as LDicomDS::GetImage. This will return a bitmap handle populated with the "Image Pixel Data" which has the overlay data embedded. For this example, assume that the bitmap handle returned by this function is called pMainBitmap.
2.	Call LDicomDS::GetOverlayAttributes to get the attributes of the overlay. For this example, assume that the OVERLAYATTRIBUTES structure returned by this function is called pOverlayAttributes.
3.	Now we need to add our overlay as one of the overlays associated with pMainBitmap. To do that we need to call LDicomDS::SetOverlayAttributes:
	LBitmap::SetOverlayAttributes(pMainBitmap,0,pOverlayAttributes, OVERLAYATTRIBUTES_FLAGS \| OVERLAYATTRIBUTES_BITINDEX \|OVERLAYATTRIBUTES_ORIGIN \|OVERLAYATTRIBUTES_DICOM \| OVERLAYATTRIBUTES_COLOR);
	We are assuming that this is the first overlay in the bitmap this is why we are passing 0 as the overlay index.
4.	Now we need to extract the overlay data from the main image data:
	LBitmap::UpdateOverlayBits(pMainBitmap,0, SETOVERLAYBITS_FROMBITMAP)
5.	Now call LBitmap::GetOverlay to get the overlay data itself as a bitmap handle.

Required DLLs and Libraries

LTDIC

For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application

Platforms

Win32, x64

See Also

Functions:	LDicomDS::GetOverlayCount, LDicomDS::GetOverlayAttributes, LDicomDS::GetOverlayActivationLayer, LDicomDS::GetOverlayBitmapList, LDicomDS::SetOverlayAttributes, LDicomDS::SetOverlayBitmap, LDicomDS::SetOverlayBitmapList, LDicomDS::DeleteOverlay
Topics:	Overlays Overview
	Overlays
	How to Disable the Automatic Loading of the default DICOM IOD Table

Example

This example will extract the overlays from a

DICOM dataset and associate them with a bitmap,

the bitmap is assumed to be extracted from the

same DICOM dataset.

L_INT LDicomDS_GetOverlayBitmapExample(LDicomDS       &InDS       ,// Input dataset
                                pBITMAPHANDLE  pBitmap     ,// Bitmap which will be associated with 
                                                            // the overlays, note this should be a 
                                                            // valid bitmap loaded from the same DICOM 
                                                            // dataset where the overlays exist. 
                                L_UINT         uStructSize  // pass sizeof(BITMAPHANDLE) 
                                )
{
   L_INT                nRet;
   L_UINT               uOverlayCount; 
   L_UINT               uOverlayIndex; 
   OVERLAYATTRIBUTES    OverlayAttributes = {0};
   L_INT                GroupNumber=0; 
   L_BOOL               IsOverlayInDataset = FALSE; 
   L_INT                nLEADRet; 
   L_UINT               uLEADOverlayIndex; 
   BITMAPHANDLE         OverlayBitmap = {0};
   //(1)Sanity Check ! 
   if(NULL == pBitmap) 
   {
      return DICOM_ERROR_NULL_PTR;
   }
   DICOM_CHECK_SIZE2(pBitmap,uStructSize); 
   uOverlayCount =0; 
   //(2)Do we have any overlays at all
   nRet = InDS.GetOverlayCount (&uOverlayCount); 
   if( (DICOM_SUCCESS != nRet) || (0 == uOverlayCount) ) 
   {
      return DICOM_SUCCESS;
   }
   //(3)Go through the overlays one by one
   uOverlayIndex     = 0; 
   uLEADOverlayIndex = 0; 
   while(uOverlayIndex < uOverlayCount) 
   {
      // Reset the overlay attributes structure
      memset(&OverlayAttributes,0,sizeof(OverlayAttributes)); 
      GroupNumber                =  0; 
      IsOverlayInDataset         = FALSE; 
      // Reset the overlay bitmap
      L_InitBitmap(  &OverlayBitmap, 
                     sizeof(OverlayBitmap), 
                     1,
                     1,
                     1);
      // Get the attributes of this overlay
      nRet = InDS.GetOverlayAttributes (  uOverlayIndex, 
                                    &OverlayAttributes, 
                                    sizeof(OverlayAttributes), 
                                    &GroupNumber, 
                                    &IsOverlayInDataset,0); 
      if(DICOM_SUCCESS != nRet) 
      {
         return nRet;
      }
      if(!IsOverlayInDataset) 
      {
         uOverlayIndex++;
         continue; 
      }
      // Auto paint and process overlays
      OverlayAttributes.uFlags |=   OVERLAY_AUTOPAINT    |
                                    OVERLAY_AUTOPROCESS  ; 
      OverlayAttributes.crColor = RGB(0xFF,0xFF,0xFF);      
      // Is the overlay embedded inside the image data ? 
      if(OverlayAttributes.uFlags & OVERLAY_USEBITPLANE) 
      {
         // Add this overlay to the list of overlays 
         // in the bitmap handle
         nLEADRet = L_SetOverlayAttributes(  pBitmap, 
                                             uLEADOverlayIndex, 
                                             &OverlayAttributes, 
                                             OVERLAYATTRIBUTES_FLAGS    |
                                             OVERLAYATTRIBUTES_BITINDEX |
                                             OVERLAYATTRIBUTES_ORIGIN   |
                                             OVERLAYATTRIBUTES_DICOM    |   
                                             OVERLAYATTRIBUTES_COLOR); 
         if(SUCCESS != nLEADRet) 
         {
            return DICOM_ERROR_MEMORY; 
         }
         // Make sure to extract the overlay data from the image data
         nLEADRet = L_UpdateBitmapOverlayBits(  pBitmap, 
                                                uLEADOverlayIndex, 
                                                SETOVERLAYBITS_FROMBITMAP); 
         if(SUCCESS != nLEADRet) 
         {
            return DICOM_ERROR_MEMORY; 
         }
      }
      // The overlay is inside overlay data
      else
      {
         // Add this overlay to the list of overlays
         // in the bitmap handle
         nLEADRet = L_SetOverlayAttributes(  pBitmap, 
                                             uLEADOverlayIndex, 
                                             &OverlayAttributes, 
                                             OVERLAYATTRIBUTES_FLAGS    |
                                             OVERLAYATTRIBUTES_ORIGIN   |
                                             OVERLAYATTRIBUTES_DICOM    |
                                             OVERLAYATTRIBUTES_COLOR); 
         if(SUCCESS != nLEADRet)
         {
            return DICOM_ERROR_MEMORY; 
         }
         // Get the overlay bitmap from the overlay data
         nRet = InDS.GetOverlayBitmap (uOverlayIndex,&OverlayBitmap,sizeof(OverlayBitmap),0);
         if(DICOM_SUCCESS != nRet) 
         {
            return nRet;
         }
         // Set the bitmap for this overlay inside the 
         // list of overlays we have in the bitmap handle
         nLEADRet = L_SetOverlayBitmap(pBitmap, 
                                       uLEADOverlayIndex, 
                                       &OverlayBitmap, 
                                       OVERLAY_MOVE); 
         if(SUCCESS != nLEADRet) 
         {
            if(OverlayBitmap.Flags.Allocated) 
            {
               L_FreeBitmap(&OverlayBitmap); 
               memset(&OverlayBitmap,0,sizeof(OverlayBitmap)); 
            }
            return DICOM_ERROR_MEMORY; 
         }
         memset(&OverlayBitmap,0,sizeof(OverlayBitmap)); 
      }
      uOverlayIndex++;
      uLEADOverlayIndex++;
   }
   return DICOM_SUCCESS; 
}