L_ApplyModalityLUT

#include "l_bitmap.h"

L_LTIMGCOR_API L_INT L_ApplyModalityLUT (pBitmap, pLUT, pLUTDescriptor, uFlags)

Remaps the bitmap pixels through a lookup-table (LUT). This function is available in the Medical Toolkit only.

Returns

Comments

This function remaps the bitmap pixels through a lookup-table (LUT). For DICOM, this is referred to as "applying a non-linear Modality LUT".

This function is similar to L_RemapBitmapIntensity because it remaps the bitmap pixel values through a LUT. The function differs from L_RemapBitmapIntensity as follows:

L_ApplyModalityLUT allows you to specify an incomplete LUT. Values less than the first mapped index will be mapped to the first entry in the palette. Values higher than "first mapped index" + "LUT length" will be mapped to the last entry in the LUT.

L_ApplyModalityLUT only works on grayscale bitmaps. Calling this function for non-grayscale bitmaps will return an error (ERROR_INV_PARAMETER).

L_ApplyModalityLUT can create signed bitmaps. The output bitmap will be signed (if M_LUT_SIGNED is set), or unsigned (M_LUT_SIGNED is not set).

The values in the LUT will be masked such that only the useful bits in the bitmap are considered. The values are considered as if the bitmap pixel values are normalized, LowBit = 0.

For example, lets say the bitmap is:

BitsPerPixel = 12

LowBit = 4

HighBit = 10

In this case, there are 10-4+1=7 valid bits. This means that there are 128 values to remap. For every pixel, L_ApplyModalityLUT will do the following:

Take the pixel value, shift it to the right by 4 and mask out the high bits, producing a value (val = 0..127).

val is remapped according to the LUT (values smaller than nFirstStoredPixelValueMapped are mapped to first LUT entry, while values greater than nFirstStoredPixelValueMapped + uNumberOfEntries are mapped to the last LUT entry)

After remapping, val is shifted to the left by 4 and will replace bits 4 thru 10 from the original bitmap

If the bitmap is signed, the indices for the LUT are assumed to be signed and be between 32768 and +32767.

If the bitmap is unsigned, the indices are unsigned and are between 0..65535.

It is recommended to always set the M_LUT_UPDATE_MIN_MAX flag.

This function is helpful in applying what is referred to as a "Non-Linear Modality LUT" in the DICOM world. According to the DICOM standard a "Modality LUT" defines the transformation of manufacturer-dependent pixel values into pixel values, which are manufacturer independent (e.g. Hounsfield units for CT, Optical Density for film digitizers, etc.).

This function supports 12 and 16-bit grayscale images. Support for 12 and 16-bit grayscale images is available only in the Document/Medical toolkits.

This function does not support 32-bit grayscale images. It returns the error code ERROR_GRAY32_UNSUPPORTED if a 32-bit grayscale image is passed to this function.

Required DLLs and Libraries

Platforms

Windows 2000 / XP/Vista.

See Also

Example

 L_INT ApplyModalityLUTExample(pBITMAPHANDLE pBitmap,L_BOOL  bLinear)
{
   L_INT nRet;
   if(bLinear)
   {   
       nRet = L_ApplyLinearModalityLUT (pBitmap, 0.0, 0.5, 0); 
       if(nRet != SUCCESS)
          return nRet;
   }
   else
   {
      L_UINT16             *pLUT; 
      L_UINT16                i; 
      DICOMLUTDESCRIPTOR   LUTDescriptor; 
      // allocate and initialize the LUT
      pLUT = (L_UINT16 *)malloc(0x10000 * sizeof(L_UINT16)); 
      if(!pLUT) 
         return ERROR_NO_MEMORY; 
      // set a LUT which reduces the intensity of each pixel to half
      for(i = 0; i <= 0xFFFF; i++)
         pLUT[i] = i / 2; 
      // fill the LUTDescriptor structure
      LUTDescriptor.uStructSize =sizeof(LUTDescriptor);
      LUTDescriptor.nFirstStoredPixelValueMapped = 0; 
      LUTDescriptor.uEntryBits = 16; 
      LUTDescriptor.uNumberOfEntries = 0x10000; 
      // apply the LUT   
      nRet = L_ApplyModalityLUT(pBitmap, pLUT, &LUTDescriptor, 0);
      if(nRet != SUCCESS)
      {
         return nRet;
      }
      // free the LUT
      free(pLUT);   
   }
   return SUCCESS; 
   
}