DCMTK  Version 3.6.2
OFFIS DICOM Toolkit
Public Member Functions | Static Public Member Functions | Protected Member Functions | Private Attributes | List of all members
DicomImage Class Reference

Interface class for dcmimgle/dcmimage module. More...

Public Member Functions

 DicomImage (const char *filename, const unsigned long flags=0, const unsigned long fstart=0, const unsigned long fcount=0)
 constructor, open a DICOM file. More...
 
 DicomImage (DcmObject *object, const E_TransferSyntax xfer, const unsigned long flags=0, const unsigned long fstart=0, const unsigned long fcount=0)
 constructor, use a given DcmObject More...
 
 DicomImage (DcmObject *object, const E_TransferSyntax xfer, const double slope, const double intercept, const unsigned long flags=0, const unsigned long fstart=0, const unsigned long fcount=0)
 constructor, use a given DcmObject with specified rescale/slope. More...
 
 DicomImage (DcmObject *object, E_TransferSyntax xfer, const DcmUnsignedShort &data, const DcmUnsignedShort &descriptor, const DcmLongString *explanation=NULL, const unsigned long flags=0, const unsigned long fstart=0, const unsigned long fcount=0)
 constructor, use a given DcmObject with specified modality LUT. More...
 
virtual ~DicomImage ()
 destructor
 
int processNextFrames (const unsigned long fcount=0)
 process next couple of frames. More...
 
EI_Status getStatus () const
 get current status information More...
 
unsigned long getFrameCount () const
 get number of frames. More...
 
unsigned long getFirstFrame () const
 get index of first frame. More...
 
unsigned long getNumberOfFrames () const
 get number of frames stored in the DICOM file/dataset. More...
 
unsigned long getRepresentativeFrame () const
 get index of representative frame. More...
 
double getFrameTime () const
 get nominal time (in milliseconds) between individual frames. More...
 
unsigned long getWidth () const
 get image width in pixels More...
 
unsigned long getHeight () const
 get image height in pixels More...
 
int getDepth () const
 get image depth More...
 
int getMinMaxValues (double &min, double &max, const int mode=0) const
 get minimum and maximum pixel values. More...
 
double getWidthHeightRatio () const
 get width height ratio (pixel aspect ratio: x/y). More...
 
double getHeightWidthRatio () const
 get height width ratio (pixel aspect ratio: y/x). More...
 
int setWidthHeightRatio (const double ratio) const
 set width height ratio (pixel aspect ratio: x/y) More...
 
int setHeightWidthRatio (const double ratio) const
 set height width ratio (pixel aspect ratio: y/x) More...
 
int isOutputValueUnused (const unsigned long value)
 check whether given output value is unused More...
 
unsigned long getOutputDataSize (const int bits=0) const
 get number of bytes required for the rendered output of a single frame. More...
 
const void * getOutputData (const int bits=0, const unsigned long frame=0, const int planar=0)
 render pixel data and return pointer to internal memory buffer. More...
 
int getOutputData (void *buffer, const unsigned long size, const int bits=0, const unsigned long frame=0, const int planar=0)
 render pixel data and output to given memory buffer. More...
 
const void * getOutputPlane (const int plane) const
 render pixel data and return pointer to given plane (internal memory buffer). More...
 
void deleteOutputData () const
 delete internal memory buffer used for rendered images. More...
 
int isMonochrome () const
 check whether image is monochrome or not. More...
 
EP_Interpretation getPhotometricInterpretation () const
 get code for photometric interpretation (color model). More...
 
int hasSOPclassUID (const char *uid) const
 check whether image has given SOP class UID. More...
 
const DiPixelgetInterData () const
 get intermediate pixel data representation (read-only). More...
 
DiDisplayFunctiongetDisplayFunction () const
 get display function More...
 
int setDisplayFunction (DiDisplayFunction *display)
 set display function More...
 
int setNoDisplayFunction ()
 set no display function. More...
 
int deleteDisplayLUT (const int bits=0)
 delete specified display LUT(s) More...
 
int convertPValueToDDL (const Uint16 pvalue, Uint16 &ddl, const int bits=8)
 convert P-value to DDL. More...
 
int setNoVoiTransformation ()
 unset all VOI transformations (windows and LUTs). More...
 
int setMinMaxWindow (const int idx=0)
 set automatically calculated minimum/maximum window. More...
 
int setHistogramWindow (const double thresh=0.05)
 set automatically calculated histogram window. More...
 
int setRoiWindow (const unsigned long left_pos, const unsigned long top_pos, const unsigned long width, const unsigned long height, const unsigned long frame=0)
 set automatically calculated VOI window for the specified Region of Interest (ROI). More...
 
int setWindow (const unsigned long window)
 set specified VOI window (given by index to window width/center sequence stored in image file). More...
 
int setWindow (const double center, const double width)
 set specified VOI window (given by window width and center). More...
 
int getWindow (double &center, double &width)
 get current VOI window as window center and width values More...
 
unsigned long getWindowCount () const
 get number of VOI windows (stored in image file). More...
 
int setVoiLutFunction (const EF_VoiLutFunction function)
 set VOI LUT function More...
 
EF_VoiLutFunction getVoiLutFunction () const
 get VOI LUT function. More...
 
int setVoiLut (const DcmUnsignedShort &data, const DcmUnsignedShort &descriptor, const DcmLongString *explanation=NULL, const EL_BitsPerTableEntry descripMode=ELM_UseValue)
 set VOI LUT (given by dcmdata elements). More...
 
int setVoiLut (const unsigned long table, const EL_BitsPerTableEntry descripMode=ELM_UseValue)
 set VOI LUT (given by index to VOI LUT sequence stored in image file). More...
 
unsigned long getVoiLutCount () const
 get number of VOI LUTs (stored in image file) More...
 
const char * getVoiTransformationExplanation () const
 get description of active VOI transformation More...
 
const char * getVoiWindowExplanation (const unsigned long window, OFString &explanation) const
 get description of specified VOI window (stored in the image file) More...
 
const char * getVoiLutExplanation (const unsigned long table, OFString &explanation) const
 get description of specified VOI LUT (stored in the image file) More...
 
const char * getModalityLutExplanation () const
 get description of performed modality LUT transformation More...
 
EP_Polarity getPolarity () const
 get polarity. More...
 
int setPolarity (const EP_Polarity polarity)
 set polarity. More...
 
int setHardcopyParameters (const unsigned int min, const unsigned int max, const unsigned int reflect, const unsigned int illumin)
 set hardcopy parameters. More...
 
ES_PresentationLut getPresentationLutShape () const
 get shape for presentation transformation. More...
 
int setPresentationLutShape (const ES_PresentationLut shape)
 set shape for presentation transformation. More...
 
int setPresentationLut (const DcmUnsignedShort &data, const DcmUnsignedShort &descriptor, const DcmLongString *explanation=NULL, const EL_BitsPerTableEntry descripMode=ELM_UseValue)
 set LUT for presentation transformation. More...
 
const char * getPresentationLutExplanation () const
 get description of active presentation LUT More...
 
int setInversePresentationLut (const DcmUnsignedShort &data, const DcmUnsignedShort &descriptor, const EL_BitsPerTableEntry descripMode=ELM_UseValue)
 set inverse LUT for presentation transformation. More...
 
int addOverlay (const unsigned int group, const signed int left_pos, const signed int top_pos, const unsigned int width, const unsigned int height, const DcmOverlayData &data, const DcmLongString &label, const DcmLongString &description, const EM_Overlay mode=EMO_Default)
 add specified plane to group of additional overlay planes. More...
 
int removeOverlay (const unsigned int group)
 remove specified (additional) overlay plane More...
 
int removeAllOverlays ()
 remove all additional overlay planes More...
 
int isOverlayVisible (const unsigned int plane, const unsigned int idx=0)
 check whether specified overlay plane is visible/activated. More...
 
int showOverlay (const unsigned int plane, const unsigned int idx=0)
 activate specified overlay plane More...
 
int showOverlay (const unsigned int plane, const EM_Overlay mode, const double fore=1.0, const double thresh=0.5, const unsigned int idx=0)
 activate specified overlay plane and change some parameters More...
 
int showOverlay (const unsigned int plane, const Uint16 pvalue)
 activate specified overlay plane and change 'pvalue' (only for bitmap shutters) More...
 
int showAllOverlays (const unsigned int idx=0)
 activate all overlay planes (make them visible) More...
 
int showAllOverlays (const EM_Overlay mode, const double fore=1, const double thresh=0.5, const unsigned int idx=0)
 activate all overlay planes and set specified parameters More...
 
int hideOverlay (const unsigned int plane, const unsigned int idx=0)
 deactivate specified overlay plane More...
 
int hideAllOverlays (const unsigned int idx=0)
 deactivate all overlay planes (make them invisible) More...
 
int placeOverlay (const unsigned int plane, const signed int left_pos, const signed int top_pos, const unsigned int idx=0)
 move origin of specified overlay plane to given position More...
 
unsigned int getOverlayCount (const unsigned int idx=0) const
 get number of overlay planes More...
 
unsigned int getOverlayGroupNumber (const unsigned int plane, const unsigned int idx=0) const
 get group number of specified overlay plane More...
 
const char * getOverlayLabel (const unsigned int plane, const unsigned int idx=0) const
 get label of specified overlay plane More...
 
const char * getOverlayDescription (const unsigned int plane, const unsigned int idx=0) const
 get description of specified overlay plane More...
 
EM_Overlay getOverlayMode (const unsigned int plane, const unsigned int idx=0) const
 get mode of specified overlay plane More...
 
const void * getOverlayData (const unsigned int plane, unsigned int &left_pos, unsigned int &top_pos, unsigned int &width, unsigned int &height, EM_Overlay &mode, const unsigned long frame=0, const int bits=8, const Uint16 fore=0xff, const Uint16 back=0x0, const unsigned int idx=2) const
 create bitmap for specified overlay plane. More...
 
const void * getFullOverlayData (const unsigned int plane, unsigned int &width, unsigned int &height, const unsigned long frame=0, const int bits=8, const Uint16 fore=0xff, const Uint16 back=0x0, const unsigned int idx=0) const
 create bitmap for specified overlay plane. More...
 
void deleteOverlayData () const
 delete buffer for overlay plane data. More...
 
unsigned long create6xxx3000OverlayData (Uint8 *&buffer, const unsigned int plane, unsigned int &width, unsigned int &height, unsigned long &frames, const unsigned int idx=0) const
 create bitmap for specified overlay plane and store it in (6xxx,3000) format. More...
 
DicomImagecreateDicomImage (unsigned long fstart=0, unsigned long fcount=0) const
 create copy of current image object. More...
 
DicomImagecreateScaledImage (const unsigned long width, const unsigned long height=0, const int interpolate=0, int aspect=0) const
 create scaled copy of current image object (given by exact size). More...
 
DicomImagecreateScaledImage (const double xfactor, const double yfactor=0, const int interpolate=0, const int aspect=0) const
 create scaled copy of current image object (given by scaling factors). More...
 
DicomImagecreateScaledImage (const signed long left_pos, const signed long top_pos, unsigned long clip_width, unsigned long clip_height, unsigned long scale_width=0, unsigned long scale_height=0, const int interpolate=0, int aspect=0, const Uint16 pvalue=0) const
 create scaled copy of specified (clipping) area of the current image object. More...
 
DicomImagecreateScaledImage (const signed long left_pos, const signed long top_pos, unsigned long width, unsigned long height, const double xfactor, const double yfactor=0, const int interpolate=0, const int aspect=0, const Uint16 pvalue=0) const
 create scaled copy of specified (clipping) area of the current image object. More...
 
DicomImagecreateClippedImage (const signed long left_pos, const signed long top_pos, unsigned long width=0, unsigned long height=0, const Uint16 pvalue=0) const
 create copy of specified area of the current image object (clipping). More...
 
int flipImage (int horz=1, int vert=0) const
 flip current image (horizontally and/or vertically) More...
 
DicomImagecreateFlippedImage (int horz=1, int vert=0) const
 create a flipped copy of the current image. More...
 
int rotateImage (signed int degree) const
 rotate current image (by steps of 90 degrees) More...
 
DicomImagecreateRotatedImage (signed int degree) const
 create a rotated copy of the current image. More...
 
DicomImagecreateMonochromeImage (const double red=0.299, const double green=0.587, const double blue=0.114) const
 create monochrome copy of the current image. More...
 
unsigned long createWindowsDIB (void *&data, const unsigned long size, const unsigned long frame=0, const int bits=24, const int upsideDown=0, const int padding=1)
 create true color (24/32 bit) or palette (8 bit) bitmap for MS Windows. More...
 
unsigned long createJavaAWTBitmap (void *&data, const unsigned long frame=0, const int bits=32)
 create true color (32 bit) or palette (8 bit) bitmap for Java (AWT default format). More...
 
DicomImagecreateMonoOutputImage (const unsigned long frame, const int bits)
 create new single frame DicomImage with applied grayscale transformations. More...
 
int writeFrameToDataset (DcmItem &dataset, const int bits=0, const unsigned long frame=0, const int planar=0)
 render pixel data of the given frame and write image related attributes to DICOM dataset. More...
 
int writeImageToDataset (DcmItem &dataset, const int mode=0, const int planar=2)
 write current image and related attributes to DICOM dataset. More...
 
int writePPM (const char *filename, const int bits=0, const unsigned long frame=0)
 write pixel data to PPM file (specified by filename). More...
 
int writePPM (STD_NAMESPACE ostream &stream, const int bits=0, const unsigned long frame=0)
 write pixel data to PPM file (specified by open C++ stream). More...
 
int writePPM (FILE *stream, const int bits=0, const unsigned long frame=0)
 write pixel data to PPM file (specified by open C stream). More...
 
int writeRawPPM (const char *filename, const int bits=0, const unsigned long frame=0)
 write pixel data to raw PPM file (specified by filename). More...
 
int writeRawPPM (FILE *stream, const int bits=0, const unsigned long frame=0)
 write pixel data to raw PPM file (specified by open C stream). More...
 
int writeBMP (FILE *stream, const int bits=0, const unsigned long frame=0)
 write pixel data to BMP file (specified by open C stream). More...
 
int writeBMP (const char *filename, const int bits=0, const unsigned long frame=0)
 write pixel data to BMP file (specified by filename). More...
 
int writePluginFormat (const DiPluginFormat *plugin, FILE *stream, const unsigned long frame=0)
 write pixel data to pluggable image format file (specified by open C stream). More...
 
int writePluginFormat (const DiPluginFormat *plugin, const char *filename, const unsigned long frame=0)
 write pixel data to pluggable image format file (specified by filename). More...
 

Static Public Member Functions

static const char * getString (const EI_Status status)
 convert status code to status string More...
 
static const char * getString (const EP_Interpretation interpret)
 convert photometric interpretation code to interpretation string (defined term) More...
 
static void * create12BitPackedBitmap (const void *buffer, const unsigned long size, const unsigned long count)
 create 12 bit packed (monochrome) bitmap for DICOM printers. More...
 

Protected Member Functions

 DicomImage (const DicomImage *dicom, DiImage *image, const EP_Interpretation interpret=EPI_Unknown)
 constructor, create copy of given image object with different image data and photometric interpretation More...
 
void Init ()
 initialize object. More...
 
int checkDataDictionary ()
 check whether data dictionary is present More...
 
const char * getSOPclassUID () const
 get SOP class UID of current image object More...
 
int normalizeDegreeValue (signed int &degree) const
 normalize given degree value (for internal use). More...
 

Private Attributes

EI_Status ImageStatus
 current state of converting progress (error level)
 
EP_Interpretation PhotometricInterpretation
 DICOM color model (enumeration)
 
DiDocumentDocument
 points to document object
 
DiImageImage
 points to image object
 

Detailed Description

Interface class for dcmimgle/dcmimage module.

The main purpose of these modules is image display.

Constructor & Destructor Documentation

◆ DicomImage() [1/5]

DicomImage::DicomImage ( const char *  filename,
const unsigned long  flags = 0,
const unsigned long  fstart = 0,
const unsigned long  fcount = 0 
)

constructor, open a DICOM file.

Opens specified file and reads image related data, creates internal representation of image data. Use getStatus() to obtain detailed information about any errors.

Parameters
filenamethe DICOM file
flagsconfiguration flags (see diutils.h, CIF_MayDetachPixelData is set automatically)
fstartfirst frame to be processed (optional, 0 = 1st frame), all subsequent use of parameters labeled 'frame' in this class refers to this start frame.
fcountnumber of frames (optional, 0 = all frames)

◆ DicomImage() [2/5]

DicomImage::DicomImage ( DcmObject object,
const E_TransferSyntax  xfer,
const unsigned long  flags = 0,
const unsigned long  fstart = 0,
const unsigned long  fcount = 0 
)

constructor, use a given DcmObject

Parameters
objectpointer to DICOM data structures (fileformat, dataset or item). (do not delete while referenced, i.e. while this image object or any descendant exists; not deleted within dcmimage unless configuration flag CIF_TakeOverExternalDataset is set - in this case do not delete it at all)
xfertransfer syntax of the 'object'. (could also be EXS_Unknown in case of fileformat or dataset)
flagsconfiguration flags (CIF_xxx, see diutils.h)
fstartfirst frame to be processed (optional, 0 = 1st frame), all subsequent use of parameters labeled 'frame' in this class refers to this start frame.
fcountnumber of frames (optional, 0 = all frames)

◆ DicomImage() [3/5]

DicomImage::DicomImage ( DcmObject object,
const E_TransferSyntax  xfer,
const double  slope,
const double  intercept,
const unsigned long  flags = 0,
const unsigned long  fstart = 0,
const unsigned long  fcount = 0 
)

constructor, use a given DcmObject with specified rescale/slope.

NB: This constructor ignores the Photometric Interpretation stored in the DICOM dataset and always creates a MONOCHROME2 image - useful in combination with Presentation States.

Parameters
objectpointer to DICOM data structures (fileformat, dataset or item). (do not delete while referenced, i.e. while this image object or any descendant exists; not deleted within dcmimage unless configuration flag CIF_TakeOverExternalDataset is set - in this case do not delete it at all)
xfertransfer syntax of the 'object'. (could also be EXS_Unknown in case of fileformat or dataset)
sloperescale slope (modality transformation)
interceptrescale intercept (modality transformation)
flagsconfiguration flags (CIF_xxx, see diutils.h)
fstartfirst frame to be processed (optional, 0 = 1st frame), all subsequent use of parameters labeled 'frame' in this class refers to this start frame.
fcountnumber of frames (optional, 0 = all frames)

◆ DicomImage() [4/5]

DicomImage::DicomImage ( DcmObject object,
E_TransferSyntax  xfer,
const DcmUnsignedShort data,
const DcmUnsignedShort descriptor,
const DcmLongString explanation = NULL,
const unsigned long  flags = 0,
const unsigned long  fstart = 0,
const unsigned long  fcount = 0 
)

constructor, use a given DcmObject with specified modality LUT.

NB: This constructor ignores the Photometric Interpretation stored in the DICOM dataset and always creates a MONOCHROME2 image - useful in combination with Presentation States.

Parameters
objectpointer to DICOM data structures (fileformat, dataset or item). (do not delete while referenced, i.e. while this image object or any descendant exists; not deleted within dcmimage unless configuration flag CIF_TakeOverExternalDataset is set - in this case do not delete it at all)
xfertransfer syntax of the 'object'. (could also be EXS_Unknown in case of fileformat or dataset)
datadataset element containing modality LUT data
descriptordataset element containing modality LUT descriptor
explanationdataset element containing modality LUT explanation
flagsconfiguration flags (CIF_xxx, see diutils.h)
fstartfirst frame to be processed (optional, 0 = 1st frame), all subsequent use of parameters labeled 'frame' in this class refers to this start frame.
fcountnumber of frames (optional, 0 = all frames)

◆ DicomImage() [5/5]

DicomImage::DicomImage ( const DicomImage dicom,
DiImage image,
const EP_Interpretation  interpret = EPI_Unknown 
)
protected

constructor, create copy of given image object with different image data and photometric interpretation

Parameters
dicomsource object to be copied
imagenew image data
interpretnew photometric interpretation

Member Function Documentation

◆ addOverlay()

int DicomImage::addOverlay ( const unsigned int  group,
const signed int  left_pos,
const signed int  top_pos,
const unsigned int  width,
const unsigned int  height,
const DcmOverlayData data,
const DcmLongString label,
const DcmLongString description,
const EM_Overlay  mode = EMO_Default 
)
inline

add specified plane to group of additional overlay planes.

replaces old overlay plane if group number already exists.

Parameters
groupgroup number (0x60nn) of overlay plane
widthwidth of overlay plane (in pixels)
heightheight of overlay plane (in pixels)
left_posx coordinate of plane origin (referring to image origin)
top_posy coordinate of plane origin
dataoverlay plane data (dcmdata element)
labeloverlay plane label
descriptionoverlay plane description
modedisplay mode (see 'diutils.h')
Returns
false (0) if an error occurred, true otherwise (1 = added new plane, 2 = replaced existing plane)

◆ checkDataDictionary()

int DicomImage::checkDataDictionary ( )
protected

check whether data dictionary is present

Returns
true if dictionary is present, false otherwise

◆ convertPValueToDDL()

int DicomImage::convertPValueToDDL ( const Uint16  pvalue,
Uint16 &  ddl,
const int  bits = 8 
)
inline

convert P-value to DDL.

conversion uses display LUT if present, linear scaling otherwise.

Parameters
pvalueP-value to be converted (0..65535)
ddlreference to resulting DDL
bitsnumber of bits for output
Returns
true if successful (1 = display function transformation, 2 = linear scaling), false otherwise

◆ create12BitPackedBitmap()

static void* DicomImage::create12BitPackedBitmap ( const void *  buffer,
const unsigned long  size,
const unsigned long  count 
)
inlinestatic

create 12 bit packed (monochrome) bitmap for DICOM printers.

Memory is not handled internally - must be deleted from calling program.

Parameters
bufferpointer to input memory buffer (16 bits allocated, 12 bits stored)
sizesize of memory buffer (will be checked whether it is sufficient)
countnumber of entries (pixels) in input buffer
Returns
pointer to memory buffer containing the packed output bitmap data (NULL if an error occurred)

References DiMonoImage::createPackedBitmap().

◆ create6xxx3000OverlayData()

unsigned long DicomImage::create6xxx3000OverlayData ( Uint8 *&  buffer,
const unsigned int  plane,
unsigned int &  width,
unsigned int &  height,
unsigned long &  frames,
const unsigned int  idx = 0 
) const
inline

create bitmap for specified overlay plane and store it in (6xxx,3000) format.

(1 bit allocated and stored, foreground color is 1, background color is 0, data is 16 bit padded - even length) memory is allocated but not handled internally - must be deleted from calling program.

Parameters
bufferstores pointer to overlay data (memory is allocated internally)
planenumber (0..15) or group number (0x60nn) of overlay plane
widthreturns width of overlay plane (in pixels)
heightreturns height of overlay plane (in pixels)
framesreturns number of frames
idxindex of overlay group (0 = dataset, planes stored in the image dataset; 1 = additional, planes added by addOverlay()), default: 0
Returns
number of bytes allocated for the 'buffer' if successful, 0 otherwise

◆ createClippedImage()

DicomImage* DicomImage::createClippedImage ( const signed long  left_pos,
const signed long  top_pos,
unsigned long  width = 0,
unsigned long  height = 0,
const Uint16  pvalue = 0 
) const

create copy of specified area of the current image object (clipping).

memory is not handled internally - must be deleted from calling program.

Parameters
left_posx coordinate of top left corner of area to be copied (referring to image origin, negative values create a border around the image)
top_posy coordinate of top left corner of area to be copied
widthwidth of area to be copied/clipped
heightheight of area to be copied/clipped
pvalueP-value used for the border outside the image (0..65535)
Returns
pointer to new DicomImage object (NULL if an error occurred)

◆ createDicomImage()

DicomImage* DicomImage::createDicomImage ( unsigned long  fstart = 0,
unsigned long  fcount = 0 
) const

create copy of current image object.

memory is not handled internally - must be deleted from calling program.

Parameters
fstartfirst frame to be processed (0 = 1st frame)
fcountnumber of frames (0 = all frames)
Returns
pointer to new DicomImage object (NULL if an error occurred)

◆ createFlippedImage()

DicomImage* DicomImage::createFlippedImage ( int  horz = 1,
int  vert = 0 
) const

create a flipped copy of the current image.

memory is not handled internally - must be deleted from calling program.

Parameters
horzflip horizontally if true
vertflip vertically if true
Returns
pointer to new DicomImage object (NULL if an error occurred)

◆ createJavaAWTBitmap()

unsigned long DicomImage::createJavaAWTBitmap ( void *&  data,
const unsigned long  frame = 0,
const int  bits = 32 
)
inline

create true color (32 bit) or palette (8 bit) bitmap for Java (AWT default format).

32 bit images allocate 32 bits per pixel (RGB), but only use the upper 24 bits. The sample order for color images is: Red, Green, Blue. Memory is not handled internally - must be deleted from calling program. This method does not work if original YCbCr color model is retained (see CIF_KeepYCbCrColorModel).

Parameters
dataresulting pointer to bitmap data (set to NULL if an error occurred)
frameindex of frame to be converted (default: 0 = first frame)
bitsnumber of bits per pixel used for the output bitmap (8 or 32, default: 32)
Returns
number of bytes allocated by the bitmap, or 0 if an error occurred

◆ createMonochromeImage()

DicomImage* DicomImage::createMonochromeImage ( const double  red = 0.299,
const double  green = 0.587,
const double  blue = 0.114 
) const

create monochrome copy of the current image.

equal to createDicomImage() for monochrome images. memory is not handled internally - must be deleted from calling program. This method does not work if original YCbCr color model is retained (see CIF_KeepYCbCrColorModel).

Parameters
redcoefficient by which the red component is weighted (default: NTSC value)
greencoefficient by which the green component is weighted (default: NTSC value)
bluecoefficient by which the blue component is weighted (default: NTSC value)
Returns
pointer to new DicomImage object (NULL if an error occurred)

◆ createMonoOutputImage()

DicomImage* DicomImage::createMonoOutputImage ( const unsigned long  frame,
const int  bits 
)

create new single frame DicomImage with applied grayscale transformations.

The method getOutputData() is used internally for the new bitmap. Limited to monochrome images.

Parameters
frameindex of frame to be converted
bitsnumber of bits per pixel used for the output bitmap
Returns
pointer to new DicomImage object (NULL if an error occurred)

◆ createRotatedImage()

DicomImage* DicomImage::createRotatedImage ( signed int  degree) const

create a rotated copy of the current image.

memory is not handled internally - must be deleted from calling program.

Parameters
degreeangle by which the image shall be rotated (-360, -270, -180, -90, 0, 90, 180, 270, 360)
Returns
pointer to new DicomImage object (NULL if an error occurred)

◆ createScaledImage() [1/4]

DicomImage* DicomImage::createScaledImage ( const unsigned long  width,
const unsigned long  height = 0,
const int  interpolate = 0,
int  aspect = 0 
) const

create scaled copy of current image object (given by exact size).

memory is not handled internally - must be deleted from calling program.

Parameters
widthwidth of new image (in pixels)
heightheight of new image (in pixels)
interpolatespecifies whether scaling algorithm should use interpolation (if necessary). default: no interpolation (0), preferred interpolation algorithm (if applicable): 1 = pbmplus algorithm, 2 = c't algorithm, 3 = bilinear magnification, 4 = bicubic magnification
aspectspecifies whether pixel aspect ratio should be taken into consideration (if true, width OR height should be 0, i.e. this component will be calculated automatically)
Returns
pointer to new DicomImage object (NULL if an error occurred)

◆ createScaledImage() [2/4]

DicomImage* DicomImage::createScaledImage ( const double  xfactor,
const double  yfactor = 0,
const int  interpolate = 0,
const int  aspect = 0 
) const

create scaled copy of current image object (given by scaling factors).

memory is not handled internally - must be deleted from calling program.

Parameters
xfactorwidth of new image is multiplied with this factor (> 0)
yfactorheight of new image is multiplied with this factor (> 0)
interpolatespecifies whether scaling algorithm should use interpolation (if necessary). default: no interpolation (0), preferred interpolation algorithm (if applicable): 1 = pbmplus algorithm, 2 = c't algorithm, 3 = bilinear magnification, 4 = bicubic magnification
aspectspecifies whether pixel aspect ratio should be taken into consideration (if true, width OR height should be 0, i.e. this component will be calculated automatically)
Returns
pointer to new DicomImage object (NULL if an error occurred)

◆ createScaledImage() [3/4]

DicomImage* DicomImage::createScaledImage ( const signed long  left_pos,
const signed long  top_pos,
unsigned long  clip_width,
unsigned long  clip_height,
unsigned long  scale_width = 0,
unsigned long  scale_height = 0,
const int  interpolate = 0,
int  aspect = 0,
const Uint16  pvalue = 0 
) const

create scaled copy of specified (clipping) area of the current image object.

memory is not handled internally - must be deleted from calling program. NB: Clipping and interpolated scaling at the same moment is not yet fully implemented!

Parameters
left_posx coordinate of top left corner of area to be scaled (referring to image origin, negative values create a border around the image)
top_posy coordinate of top left corner of area to be scaled
clip_widthwidth of area to be scaled
clip_heightheight of area to be scaled
scale_widthwidth of scaled image (in pixels)
scale_heightheight of scaled image (in pixels)
interpolatespecifies whether scaling algorithm should use interpolation (if necessary). default: no interpolation (0), preferred interpolation algorithm (if applicable): 1 = pbmplus algorithm, 2 = c't algorithm, 3 = bilinear magnification, 4 = bicubic magnification
aspectspecifies whether pixel aspect ratio should be taken into consideration (if true, width OR height should be 0, i.e. this component will be calculated automatically)
pvalueP-value used for the border outside the image (0..65535)
Returns
pointer to new DicomImage object (NULL if an error occurred)

◆ createScaledImage() [4/4]

DicomImage* DicomImage::createScaledImage ( const signed long  left_pos,
const signed long  top_pos,
unsigned long  width,
unsigned long  height,
const double  xfactor,
const double  yfactor = 0,
const int  interpolate = 0,
const int  aspect = 0,
const Uint16  pvalue = 0 
) const

create scaled copy of specified (clipping) area of the current image object.

memory is not handled internally - must be deleted from calling program. NB: Clipping and interpolated scaling at the same moment is not yet fully implemented!

Parameters
left_posx coordinate of top left corner of area to be scaled (referring to image origin, negative values create a border around the image)
top_posy coordinate of top left corner of area to be scaled
widthwidth of area to be scaled
heightheight of area to be scaled
xfactorwidth of new image is multiplied with this factor (> 0)
yfactorheight of new image is multiplied with this factor (> 0)
interpolatespecifies whether scaling algorithm should use interpolation (if necessary). default: no interpolation (0), preferred interpolation algorithm (if applicable): 1 = pbmplus algorithm, 2 = c't algorithm, 3 = bilinear magnification, 4 = bicubic magnification
aspectspecifies whether pixel aspect ratio should be taken into consideration (if true, width OR height should be 0, i.e. this component will be calculated automatically)
pvalueP-value used for the border outside the image (0..65535)
Returns
pointer to new DicomImage object (NULL if an error occurred)

◆ createWindowsDIB()

unsigned long DicomImage::createWindowsDIB ( void *&  data,
const unsigned long  size,
const unsigned long  frame = 0,
const int  bits = 24,
const int  upsideDown = 0,
const int  padding = 1 
)
inline

create true color (24/32 bit) or palette (8 bit) bitmap for MS Windows.

8 bit images require an appropriate color palette (256 entries, values: 0 to 255) and are only applicable to monochrome images, the beginning of a each line starts on a 32-bit address (if 'padding' is true); 24 bit images store 24 bits per pixel (BGR) and do align each line to a 32-bit address (if 'padding' is true); 32 bit images store 32 bits per pixel (ARGB), but only use the lower 24 bits (-RGB). The memory buffer can be allocated both externally (from the calling program) and internally (inside this class/module). If the 'data' parameter is not NULL and the 'size' parameter, which describes the size (in bytes) of the allocated buffer, is sufficiently large, the bitmap is stored in this buffer. Otherwise (i.e. 'data' is NULL) the memory is allocated internally. Please note that in both cases the memory is not handled internally after this method has finished and, therefore, must be deleted from the calling program. This method does not work if original YCbCr color model is retained (see CIF_KeepYCbCrColorModel).

Parameters
datauntyped pointer memory buffer (set to NULL if not allocated externally)
sizesize of the memory buffer in bytes (if 0 'data' is set to NULL)
frameindex of frame to be converted (default: 0 = first frame)
bitsnumber of bits per pixel used for the output bitmap (8, 24 or 32, default: 24)
upsideDownflag indicating whether the first line stored is the top-most (default: 0) or the bottom-most of the source image (as required by the BMP file format)
paddingalign each line to a 32-bit address if true (default)
Returns
number of bytes allocated by the bitmap, or 0 if an error occurred

◆ deleteDisplayLUT()

int DicomImage::deleteDisplayLUT ( const int  bits = 0)
inline

delete specified display LUT(s)

Parameters
bitsparameter of LUT to be deleted (0 = all)
Returns
true if successful, false otherwise

◆ deleteOutputData()

void DicomImage::deleteOutputData ( ) const
inline

delete internal memory buffer used for rendered images.

Save memory if data is no longer needed.

◆ deleteOverlayData()

void DicomImage::deleteOverlayData ( ) const
inline

delete buffer for overlay plane data.

Save memory if data is no longer needed.

◆ flipImage()

int DicomImage::flipImage ( int  horz = 1,
int  vert = 0 
) const

flip current image (horizontally and/or vertically)

Parameters
horzflip horizontally if true
vertflip vertically if true
Returns
true if successful (1 = flipped at least direction, 2 = not flipped, because of image resolution - width and/or height equal to 1), false otherwise

◆ getDepth()

int DicomImage::getDepth ( ) const
inline

get image depth

Returns
number of bits per sample of the internal representation

◆ getDisplayFunction()

DiDisplayFunction* DicomImage::getDisplayFunction ( ) const
inline

get display function

Returns
pointer to current display function, NULL if absent

◆ getFirstFrame()

unsigned long DicomImage::getFirstFrame ( ) const
inline

get index of first frame.

This functions returns the index of the first frame processed by this class (see constructors for details).

Returns
index of first frame (0..n-1)

◆ getFrameCount()

unsigned long DicomImage::getFrameCount ( ) const
inline

get number of frames.

Please note that this function does not return the number of frames stored in the DICOM file/dataset (use getNumberOfFrames() instead). It rather refers to the number of frames processed by this class (see constructors for details).

Returns
number of frames processed by this class

◆ getFrameTime()

double DicomImage::getFrameTime ( ) const
inline

get nominal time (in milliseconds) between individual frames.

This attribute might not always be stored in the DICOM dataset.

Returns
nominal time between individual frames, 0 if absent

◆ getFullOverlayData()

const void* DicomImage::getFullOverlayData ( const unsigned int  plane,
unsigned int &  width,
unsigned int &  height,
const unsigned long  frame = 0,
const int  bits = 8,
const Uint16  fore = 0xff,
const Uint16  back = 0x0,
const unsigned int  idx = 0 
) const
inline

create bitmap for specified overlay plane.

(up to 16 bits per pixel with two values: 'fore' and 'back') In contrast to the previous method the full bitmap data is always returned.

Parameters
planenumber (0..15) or group number (0x60nn) of overlay plane
widthreturns width of overlay plane (in pixels)
heightreturns height of overlay plane (in pixels)
frameindex of frame used for output (default: 0 = first)
bitsnumber of bits (stored) in the resulting array, default: 8, range: 1..16 Used to mask the values for foreground and background color. The resulting array is always padded to 8 or 16 bits with 1, 8 or 16 bits allocated depending on the value of 'bits'.
foreforeground color to be set in bitmap, default: 255, range: 0..2^bits-1
backbackground color to be set in bitmap (transparent), default: 0, range: 0..2^bits-1
idxindex of overlay group (0 = dataset, planes stored in the image dataset; 1 = additional, planes added by addOverlay()), default: 0
Returns
pointer to overlay plane data (internal memory buffer)

◆ getHeight()

unsigned long DicomImage::getHeight ( ) const
inline

get image height in pixels

Returns
number of pixels in one column

Referenced by DcmQuantColorMapping< T1, T2 >::create().

◆ getHeightWidthRatio()

double DicomImage::getHeightWidthRatio ( ) const
inline

get height width ratio (pixel aspect ratio: y/x).

If present in the dataset and not overwritten using setWidthHeightRatio(), the following attributes are checked in order to determine this value:

  • Pixel Spacing, Imager Pixel Spacing, Nominal Scanned Pixel Spacing, Pixel Aspect Ratio The first attribute (Pixel Spacing) is checked both on the main dataset level and within the Pixel Measures Sequence of the Shared Functional Groups Sequence (if present).
Returns
pixel aspect ratio (floating point value)

◆ getInterData()

const DiPixel* DicomImage::getInterData ( ) const
inline

get intermediate pixel data representation (read-only).

This function allows to access the pixel data after they have been extracted from the DICOM data element and the modality transformation has been applied (if present and not disabled). Please note that for monochrome images the internal representation might be signed whereas color images are automatically converted to unsigned RGB format. Pixels are aligned to 8, 16 or 32 bits. Always use DiPixel::getRepresentation() in order to determine the integer representation of the internally stored pixel data.

Returns
pointer to intermediate pixel data representation

◆ getMinMaxValues()

int DicomImage::getMinMaxValues ( double &  min,
double &  max,
const int  mode = 0 
) const
inline

get minimum and maximum pixel values.

the resulting pixel values are stored in 'double' variables to avoid problems with different number ranges, limited to monochrome images. Please note that the min/max values refer to the full pixel data (i.e. including all possible present frames as specified in the constructor of this class).

Parameters
minminimum pixel value (reference parameter)
maxmaximum pixel value (reference parameter)
mode0 = min/max 'used' pixel values, 1 = min/max 'possible' pixel values (absolute min/max)
Returns
status code (true if successful)

◆ getModalityLutExplanation()

const char* DicomImage::getModalityLutExplanation ( ) const
inline

get description of performed modality LUT transformation

Returns
pointer to description text (NULL if absent)

◆ getNumberOfFrames()

unsigned long DicomImage::getNumberOfFrames ( ) const
inline

get number of frames stored in the DICOM file/dataset.

This attribute is mandatory for DICOM images with multiple frames. For single frame images, the value defaults to 1.

Returns
number of frames stored in the DICOM file/dataset

◆ getOutputData() [1/2]

const void* DicomImage::getOutputData ( const int  bits = 0,
const unsigned long  frame = 0,
const int  planar = 0 
)
inline

render pixel data and return pointer to internal memory buffer.

apply VOI/PLUT transformation and (visible) overlay planes. internal memory buffer will be delete for the next getBitmap/Output operation. output data is always padded to 8, 16, 32, ... bits (bits allocated). Supported output color models: Monochrome 2 for monochrome images and RGB (or YCbCr_Full if flag CIF_KeepYCbCrColorModel is set) for color images. The rendered pixel data is always unsigned.

Parameters
bitsnumber of bits per sample used to render the pixel data (image depth, 1..MAX_BITS, 0 means 'bits stored' in the image) (MI_PastelColor = -1 for true color pastel mode, EXPERIMENTAL)
framenumber of frame to be rendered (0..n-1)
planar0 = color-by-pixel (R1G1B1...R2G2B2...R3G3B3...), 1 = color-by-plane (R1R2R3...G1G2G3...B1B2B3...) (only applicable to multi-planar/color images, otherwise ignored)
Returns
pointer to internal memory buffer containing rendered pixel data (if successful, NULL otherwise)

◆ getOutputData() [2/2]

int DicomImage::getOutputData ( void *  buffer,
const unsigned long  size,
const int  bits = 0,
const unsigned long  frame = 0,
const int  planar = 0 
)
inline

render pixel data and output to given memory buffer.

apply VOI/PLUT transformation and (visible) overlay planes. output data is always padded to 8, 16, 32, ... bits (bits allocated). Supported output color models: Monochrome 2 for monochrome images and RGB (or YCbCr_Full if flag CIF_KeepYCbCrColorModel is set) for color images. The rendered pixel data is always unsigned.

Parameters
bufferpointer to memory buffer (must already be allocated)
sizesize of memory buffer (will be checked whether it is sufficient)
bitsnumber of bits per sample used to render the pixel data (image depth, 1..MAX_BITS, 0 means 'bits stored' in the image) (MI_PastelColor = -1 for true color pastel mode, EXPERIMENTAL)
framenumber of frame to be rendered (0..n-1)
planar0 = color-by-pixel (R1G1B1...R2G2B2...R3G3B3...), 1 = color-by-plane (R1R2R3...G1G2G3...B1B2B3...) (only applicable to multi-planar/color images, otherwise ignored)
Returns
status code (true if successful)

◆ getOutputDataSize()

unsigned long DicomImage::getOutputDataSize ( const int  bits = 0) const
inline

get number of bytes required for the rendered output of a single frame.

This function determines the size of a rendered frame as created by getOutputData(). Therefore, it can be used to allocate a sufficiently large memory buffer and pass its size to the second variant of getOutputData().

Parameters
bitsnumber of bits per sample used to render the pixel data (image depth, 1..MAX_BITS, 0 means 'bits stored' in the image) (MI_PastelColor = -1 for true color pastel mode, EXPERIMENTAL)
Returns
number of bytes if successful, 0 otherwise

◆ getOutputPlane()

const void* DicomImage::getOutputPlane ( const int  plane) const
inline

render pixel data and return pointer to given plane (internal memory buffer).

apply VOI/PLUT transformation and (visible) overlay planes internal memory buffer will be delete for the next getBitmap/Output operation. Supported output color models: Monochrome 2 for monochrome images and RGB (or YCbCr_Full if flag CIF_KeepYCbCrColorModel is set) for color images. The rendered pixel data is always unsigned.

Parameters
planenumber of plane to be rendered
Returns
pointer to internal memory buffer containing rendered pixel data (if successful, NULL otherwise)

◆ getOverlayCount()

unsigned int DicomImage::getOverlayCount ( const unsigned int  idx = 0) const
inline

get number of overlay planes

Parameters
idxindex of overlay group (0 = dataset, 1 = additional), default: 0
Returns
number of overlay planes stored in the image

◆ getOverlayData()

const void* DicomImage::getOverlayData ( const unsigned int  plane,
unsigned int &  left_pos,
unsigned int &  top_pos,
unsigned int &  width,
unsigned int &  height,
EM_Overlay mode,
const unsigned long  frame = 0,
const int  bits = 8,
const Uint16  fore = 0xff,
const Uint16  back = 0x0,
const unsigned int  idx = 2 
) const
inline

create bitmap for specified overlay plane.

(up to 16 bits per pixel with two values: 'fore' and 'back') Please note that the current origin of the overlay plane is used. Furthermore, the size of the overlay plane is restricted to the size of the surrounding image. Use the method getFullOverlayData() if the complete bitmap data is required regardless of its position.

Parameters
planenumber (0..15) or group number (0x60nn) of overlay plane
widthreturns width of overlay plane (in pixels)
heightreturns height of overlay plane (in pixels)
left_posreturns x coordinate of plane's origin
top_posreturns y coordinate of plane's origin
modereturns display mode (see 'diutils.h')
frameindex of frame used for output (default: 0 = first)
bitsnumber of bits (stored) in the resulting array, default: 8, range: 1..16 Used to mask the values for foreground and background color. The resulting array is always padded to 8 or 16 bits with 1, 8 or 16 bits allocated depending on the value of 'bits'.
foreforeground color to be set in bitmap, default: 255, range: 0..2^bits-1
backbackground color to be set in bitmap (transparent), default: 0, range: 0..2^bits-1
idxindex of overlay group (0 = dataset, planes stored in the image dataset; 1 = additional, planes added by addOverlay(); 2 = 'additional' overlay planes hide 'dataset' planes when the overlay group number exists in both), default: 2
Returns
pointer to overlay plane data (internal memory buffer)

◆ getOverlayDescription()

const char* DicomImage::getOverlayDescription ( const unsigned int  plane,
const unsigned int  idx = 0 
) const
inline

get description of specified overlay plane

Parameters
planenumber (0..15) or group number (0x60nn) of overlay plane
idxindex of overlay group (0 = dataset, 1 = additional), default: 0
Returns
pointer to overlay plane description if successful, false (NULL) otherwise

◆ getOverlayGroupNumber()

unsigned int DicomImage::getOverlayGroupNumber ( const unsigned int  plane,
const unsigned int  idx = 0 
) const
inline

get group number of specified overlay plane

Parameters
planenumber (0..15) or group number (0x60nn) of overlay plane
idxindex of overlay group (0 = dataset, 1 = additional), default: 0
Returns
group number of given overlay plane if successful, false (0) otherwise

◆ getOverlayLabel()

const char* DicomImage::getOverlayLabel ( const unsigned int  plane,
const unsigned int  idx = 0 
) const
inline

get label of specified overlay plane

Parameters
planenumber (0..15) or group number (0x60nn) of overlay plane
idxindex of overlay group (0 = dataset, 1 = additional), default: 0
Returns
pointer to overlay plane label if successful, false (NULL) otherwise

◆ getOverlayMode()

EM_Overlay DicomImage::getOverlayMode ( const unsigned int  plane,
const unsigned int  idx = 0 
) const
inline

get mode of specified overlay plane

Parameters
planenumber (0..15) or group number (0x60nn) of overlay plane
idxindex of overlay group (0 = dataset, 1 = additional), default: 0
Returns
mode of overlay plane if successful, EMO_Default otherwise

References EMO_Default.

◆ getPhotometricInterpretation()

EP_Interpretation DicomImage::getPhotometricInterpretation ( ) const
inline

get code for photometric interpretation (color model).

Returns
code for photometric interpretation of the image

◆ getPolarity()

EP_Polarity DicomImage::getPolarity ( ) const
inline

get polarity.

applicable to monochrome and color images. possible values are EPP_Normal and EPP_Reverse

Returns
currently active polarity mode or EPP_Normal if not applicable

References EPP_Normal.

◆ getPresentationLutExplanation()

const char* DicomImage::getPresentationLutExplanation ( ) const
inline

get description of active presentation LUT

Returns
pointer to description text (NULL if absent)

◆ getPresentationLutShape()

ES_PresentationLut DicomImage::getPresentationLutShape ( ) const
inline

get shape for presentation transformation.

possible values are: ESP_Default, ESP_Identity, ESP_Inverse, ESP_LinOD. If a presentation LUT is currently active ESP_Default is always returned.

Returns
currently active presentation LUT shape or ESP_Default if not set

References ESP_Default.

◆ getRepresentativeFrame()

unsigned long DicomImage::getRepresentativeFrame ( ) const
inline

get index of representative frame.

This attribute is optionally stored in the DICOM dataset (type 3).

Returns
index of representative frame (0..n-1)

◆ getSOPclassUID()

const char* DicomImage::getSOPclassUID ( ) const
protected

get SOP class UID of current image object

Returns
SOP class UID (or NULL if an error occurred)

◆ getStatus()

EI_Status DicomImage::getStatus ( ) const
inline

get current status information

Returns
status code

◆ getString() [1/2]

static const char* DicomImage::getString ( const EI_Status  status)
static

convert status code to status string

Parameters
statuscode of current internal status
Returns
pointer to status string

◆ getString() [2/2]

static const char* DicomImage::getString ( const EP_Interpretation  interpret)
static

convert photometric interpretation code to interpretation string (defined term)

Parameters
interpretcode of image's photometric interpretation
Returns
pointer to photometric interpretation string

◆ getVoiLutCount()

unsigned long DicomImage::getVoiLutCount ( ) const
inline

get number of VOI LUTs (stored in image file)

Returns
number of VOI LUTs

◆ getVoiLutExplanation()

const char* DicomImage::getVoiLutExplanation ( const unsigned long  table,
OFString explanation 
) const
inline

get description of specified VOI LUT (stored in the image file)

Parameters
tableindex of the stored VOI LUT (0..n-1)
explanationvariable in which the explanation string is stored
Returns
pointer to description text (NULL if absent or index invalid)

◆ getVoiLutFunction()

EF_VoiLutFunction DicomImage::getVoiLutFunction ( ) const
inline

get VOI LUT function.

possible values are: EFV_Default, EFV_Linear, EFV_Sigmoid.

Returns
currently active VOI LUT function or EFV_Default if not set

References EFV_Default.

◆ getVoiTransformationExplanation()

const char* DicomImage::getVoiTransformationExplanation ( ) const
inline

get description of active VOI transformation

Returns
pointer to description text (NULL if absent)

◆ getVoiWindowExplanation()

const char* DicomImage::getVoiWindowExplanation ( const unsigned long  window,
OFString explanation 
) const
inline

get description of specified VOI window (stored in the image file)

Parameters
windowindex of the stored VOI window (0..n-1)
explanationvariable in which the explanation string is stored
Returns
pointer to description text (NULL if absent or index invalid)

◆ getWidth()

unsigned long DicomImage::getWidth ( ) const
inline

get image width in pixels

Returns
number of pixels in one row

Referenced by DcmQuantColorMapping< T1, T2 >::create().

◆ getWidthHeightRatio()

double DicomImage::getWidthHeightRatio ( ) const
inline

get width height ratio (pixel aspect ratio: x/y).

If present in the dataset and not overwritten using setWidthHeightRatio(), the following attributes are checked in order to determine this value:

  • Pixel Spacing, Imager Pixel Spacing, Nominal Scanned Pixel Spacing, Pixel Aspect Ratio. The first attribute (Pixel Spacing) is checked both on the main dataset level and within the Pixel Measures Sequence of the Shared Functional Groups Sequence (if present).
Returns
pixel aspect ratio (floating point value)

◆ getWindow()

int DicomImage::getWindow ( double &  center,
double &  width 
)
inline

get current VOI window as window center and width values

Parameters
centerreturn current window center value
widthreturn current window width value
Returns
true if successful, false otherwise

◆ getWindowCount()

unsigned long DicomImage::getWindowCount ( ) const
inline

get number of VOI windows (stored in image file).

NB: This function does nothing if the flag CIF_UsePresentationState is set.

Returns
number of VOI windows

◆ hasSOPclassUID()

int DicomImage::hasSOPclassUID ( const char *  uid) const

check whether image has given SOP class UID.

Parameters
uidSOP class UID to be checked
Returns
true if image has given SOP class UID, false otherwise

◆ hideAllOverlays()

int DicomImage::hideAllOverlays ( const unsigned int  idx = 0)
inline

deactivate all overlay planes (make them invisible)

Parameters
idxindex of overlay group (0 = dataset, 1 = additional), default: 0
Returns
false (0) if an error occurred, true otherwise (1 = planes have been successfully deactivated, 2 = no planes to be deactivated)

◆ hideOverlay()

int DicomImage::hideOverlay ( const unsigned int  plane,
const unsigned int  idx = 0 
)
inline

deactivate specified overlay plane

Parameters
planenumber (0..15) or group number (0x60nn) of overlay plane
idxindex of overlay group (0 = dataset, 1 = additional), default: 0
Returns
false (0) if an error occurred, true otherwise (1 = plane successfully deactivated, 2 = plane has already been invisible)

◆ Init()

void DicomImage::Init ( )
protected

initialize object.

create internal image object depending on color model. is used for all 'real' constructors.

◆ isMonochrome()

int DicomImage::isMonochrome ( ) const
inline

check whether image is monochrome or not.

Returns
true if image is monochrome, false otherwise (i.e. color image)

References EPI_Monochrome1, and EPI_Monochrome2.

◆ isOutputValueUnused()

int DicomImage::isOutputValueUnused ( const unsigned long  value)
inline

check whether given output value is unused

Parameters
valueoutput value to be checked
Returns
status, true if unused (1 = within output range, 2 = out of range), false otherwise

◆ isOverlayVisible()

int DicomImage::isOverlayVisible ( const unsigned int  plane,
const unsigned int  idx = 0 
)
inline

check whether specified overlay plane is visible/activated.

see show/hideOverlay() to modify the visibility status.

Parameters
planenumber (0..15) or group number (0x60nn) of overlay plane
idxindex of overlay group (0 = dataset, 1 = additional), default: 0
Returns
true (1) if overlay plane is visible, false (0) otherwise

◆ normalizeDegreeValue()

int DicomImage::normalizeDegreeValue ( signed int &  degree) const
protected

normalize given degree value (for internal use).

negative value are mapped to positive range (-360 -> 0, -270 -> 90, -180 -> 180, -90 -> 270), 360 is set to 0, all other values are rejected

Parameters
degreevalue to be normalized, valid values are: 0, 90, 180, 270
Returns
true if successful, false otherwise (invalid value)

◆ placeOverlay()

int DicomImage::placeOverlay ( const unsigned int  plane,
const signed int  left_pos,
const signed int  top_pos,
const unsigned int  idx = 0 
)
inline

move origin of specified overlay plane to given position

Parameters
planenumber (0..15) or group number (0x60nn) of overlay plane
left_posx coordinate of new plane origin (origin = 0)
top_posy coordinate of new plane origin (origin = 0)
idxindex of overlay group (0 = dataset, 1 = additional), default: 0
Returns
false (0) if an error occurred, true otherwise (1 = plane has been successfully moved, 2 = old and new position are equal, nothing to do)

◆ processNextFrames()

int DicomImage::processNextFrames ( const unsigned long  fcount = 0)
inline

process next couple of frames.

If the image object has been created with less than the number of frames stored in the DICOM image, this function allows for accessing the subsequent frames. Multiple calls to this function allow for successively processing all frames stored in the file or dataset. See parameters 'fstart' and 'fcount' of the constructor for how to initially create an instance of this class. NB: Only "original" images can be processed in this way, i.e. images that were created by one of the above constructors. Images that were created by one of the createXXX() methods can not be processed since they are derived from original image data in a certain way, e.g. scaled.

Parameters
fcountnumber of frames to be processed (0 = same number as before)
Returns
status, true if successful, false otherwise

◆ removeAllOverlays()

int DicomImage::removeAllOverlays ( )
inline

remove all additional overlay planes

Returns
false (0) if an error occurred, true otherwise (1 = all planes deleted, 2 = no planes to be deleted)

◆ removeOverlay()

int DicomImage::removeOverlay ( const unsigned int  group)
inline

remove specified (additional) overlay plane

Parameters
groupgroup number (0x60nn) of overlay plane
Returns
false (0) if an error occurred (e.g. plane doesn't exist), true otherwise

◆ rotateImage()

int DicomImage::rotateImage ( signed int  degree) const

rotate current image (by steps of 90 degrees)

Parameters
degreeangle by which the image shall be rotated (-360, -270, -180, -90, 0, 90, 180, 270, 360)
Returns
true if successful (1 = rotated by at least 90 degrees, 2 = not rotated, because of image resolution or angle), false otherwise

◆ setDisplayFunction()

int DicomImage::setDisplayFunction ( DiDisplayFunction display)
inline

set display function

Parameters
displayobject describing the output device characteristic (only referenced!)
Returns
true if successful, false otherwise

◆ setHardcopyParameters()

int DicomImage::setHardcopyParameters ( const unsigned int  min,
const unsigned int  max,
const unsigned int  reflect,
const unsigned int  illumin 
)
inline

set hardcopy parameters.

only applicable to monochrome images. used to display LinOD images

Parameters
minminimum density of the print-out (in hundreds of Optical Density, e.g. 150 means 1.5 OD)
maxmaximum density of the print-out (ditto)
reflectreflected ambient light (in candela per square meter - cd/m^2)
illuminillumination (ditto)
Returns
true if successful (1 = at least one of the parameters has changed, 2 = no parameter has changed), false otherwise

◆ setHeightWidthRatio()

int DicomImage::setHeightWidthRatio ( const double  ratio) const
inline

set height width ratio (pixel aspect ratio: y/x)

Parameters
ratiopixel aspect ratio (y/x)
Returns
status code (true if successful)

◆ setHistogramWindow()

int DicomImage::setHistogramWindow ( const double  thresh = 0.05)
inline

set automatically calculated histogram window.

possibly active VOI LUT is implicitly disabled.

Parameters
threshthreshold value specifying percentage of histogram border which shall be ignored (defaut: 5%).
Returns
true if successful, false otherwise

◆ setInversePresentationLut()

int DicomImage::setInversePresentationLut ( const DcmUnsignedShort data,
const DcmUnsignedShort descriptor,
const EL_BitsPerTableEntry  descripMode = ELM_UseValue 
)
inline

set inverse LUT for presentation transformation.

this LUT transform is e.g. used for DICOM print (12->8, 8->12 bit) possibly active presentation LUT will not be considered!

Parameters
datacontains LUT data
descriptordescribes LUT structure
descripModemode specifying the use of the bits per table entry value
Returns
true if successful, false otherwise

◆ setMinMaxWindow()

int DicomImage::setMinMaxWindow ( const int  idx = 0)
inline

set automatically calculated minimum/maximum window.

possibly active VOI LUT is implicitly disabled. Please note that the min/max values refer to the full pixel data (i.e. including all possible present frames as specified in the constructor of this class).

Parameters
idxignore global min/max values if true (1)
Returns
true if successful (1 = window has changed, 2 = new window is the same as previous one), false otherwise

◆ setNoDisplayFunction()

int DicomImage::setNoDisplayFunction ( )
inline

set no display function.

disables display function transformation, object is not deleted!

Returns
true if successful (1 = disabled current function, 2 = there was no function to disable), false otherwise

◆ setNoVoiTransformation()

int DicomImage::setNoVoiTransformation ( )
inline

unset all VOI transformations (windows and LUTs).

only applicable to monochrome images

Returns
true if successful (1 = previous window/LUT has been valid, 2 = otherwise), false otherwise (image is invalid or not monochrome)

◆ setPolarity()

int DicomImage::setPolarity ( const EP_Polarity  polarity)
inline

set polarity.

applicable to monochrome and color images.

Parameters
polaritypolarity (normal or reverse)
Returns
true if successful (1 = polarity has changed, 2 = polarity has not changed), false otherwise

◆ setPresentationLut()

int DicomImage::setPresentationLut ( const DcmUnsignedShort data,
const DcmUnsignedShort descriptor,
const DcmLongString explanation = NULL,
const EL_BitsPerTableEntry  descripMode = ELM_UseValue 
)
inline

set LUT for presentation transformation.

possibly active presentation LUT is implicitly disabled. Given data is only referenced and not copied! Make sure that the corresponding DcmXXX objects exist as long as the presentation LUT is set.

Parameters
datacontains LUT data
descriptordescribes LUT structure
explanationfree form description of presentation LUT (optional)
descripModemode specifying the use of the bits per table entry value
Returns
true if successful, false otherwise

◆ setPresentationLutShape()

int DicomImage::setPresentationLutShape ( const ES_PresentationLut  shape)
inline

set shape for presentation transformation.

possibly active presentation LUT is implicitly disabled.

Parameters
shapepresentation LUT shape (default, identity, inverse or lin OD). 'default' means that the output data is always created with 0 for black and maxvalue for white (i.e. monochrome2 data is created for output).
Returns
true if successful (1 = shape has changed, 2 = shape has not changed), false otherwise

◆ setRoiWindow()

int DicomImage::setRoiWindow ( const unsigned long  left_pos,
const unsigned long  top_pos,
const unsigned long  width,
const unsigned long  height,
const unsigned long  frame = 0 
)
inline

set automatically calculated VOI window for the specified Region of Interest (ROI).

The ROI is specified by means of a rectangle (left, top, width, height). Only the part of the ROI that overlaps with the image is regarded - if the overlapping area is empty this method returns false (0). Possibly active VOI LUT is implicitly disabled.

Parameters
left_posx-coordinate of the top left-hand corner of the ROI (starting from 0)
top_posy-coordinate of the top left-hand corner of the ROI (starting from 0)
widthwidth in pixels of the rectangular ROI (minimum: 1)
heightheight in pixels of the rectangular ROI (minimum: 1)
frameindex of the frame to be used for calculation (default: 0 = first)
Returns
true if successful (1 = window has changed, 2 = new window is the same as previous one), false otherwise

◆ setVoiLut() [1/2]

int DicomImage::setVoiLut ( const DcmUnsignedShort data,
const DcmUnsignedShort descriptor,
const DcmLongString explanation = NULL,
const EL_BitsPerTableEntry  descripMode = ELM_UseValue 
)
inline

set VOI LUT (given by dcmdata elements).

possibly active window/center is implicitly disabled. Given data is only referenced and not copied! Make sure that the corresponding DcmXXX objects exist as long as the VOI LUT is set.

Parameters
datacontains LUT data
descriptordescribes LUT structure
explanationfree form description of VOI LUT (optional)
descripModemode specifying the use of the bits per table entry value
Returns
true if successful, false otherwise

◆ setVoiLut() [2/2]

int DicomImage::setVoiLut ( const unsigned long  table,
const EL_BitsPerTableEntry  descripMode = ELM_UseValue 
)
inline

set VOI LUT (given by index to VOI LUT sequence stored in image file).

possibly active window/center is implicitly disabled. NB: This function does nothing if the flag CIF_UsePresentationState is set.

Parameters
tableindex to VOI LUT sequence (0..n-1)
descripModemode specifying the use of the bits per table entry value
Returns
true if successful, false otherwise (none monochrome or invalid index)

◆ setVoiLutFunction()

int DicomImage::setVoiLutFunction ( const EF_VoiLutFunction  function)
inline

set VOI LUT function

Parameters
functiontype of VOI LUT function (default, linear or sigmoid). 'default' basically means the same as 'linear'.
Returns
true if successful (1 = function has changed, 2 = function has not changed), false otherwise

◆ setWidthHeightRatio()

int DicomImage::setWidthHeightRatio ( const double  ratio) const
inline

set width height ratio (pixel aspect ratio: x/y)

Parameters
ratiopixel aspect ratio (x/y)
Returns
status code (true if successful)

◆ setWindow() [1/2]

int DicomImage::setWindow ( const unsigned long  window)
inline

set specified VOI window (given by index to window width/center sequence stored in image file).

possibly active VOI LUT is implicitly disabled. NB: This function does nothing if the flag CIF_UsePresentationState is set.

Parameters
windowindex to window width/center sequence (0..n-1)
Returns
true if successful, false otherwise (none monochrome or invalid index)

◆ setWindow() [2/2]

int DicomImage::setWindow ( const double  center,
const double  width 
)
inline

set specified VOI window (given by window width and center).

possibly active VOI LUT is implicitly disabled.

Parameters
centercenter of specified window
widthwidth of specified window (>= 1.0)
Returns
true if successful (1 = window has changed, 2 = new window is the same as previous one), false otherwise

◆ showAllOverlays() [1/2]

int DicomImage::showAllOverlays ( const unsigned int  idx = 0)
inline

activate all overlay planes (make them visible)

Parameters
idxindex of overlay group (0 = dataset, 1 = additional), default: 0
Returns
false (0) if an error occurred, true otherwise (1 = planes have been successfully activated, 2 = no planes to be activated)

◆ showAllOverlays() [2/2]

int DicomImage::showAllOverlays ( const EM_Overlay  mode,
const double  fore = 1,
const double  thresh = 0.5,
const unsigned int  idx = 0 
)
inline

activate all overlay planes and set specified parameters

Parameters
modedisplay mode (see 'diutils.h')
foreplane's foreground color (in percent, default: 1.0)
threshthreshold value (in percent, default: 0.5), only for EMO_ThresholdReplace
idxindex of overlay group (0 = dataset, 1 = additional), default: 0
Returns
false (0) if an error occurred, true otherwise (1 = planes have been successfully activated, 2 = no planes to be activated)

◆ showOverlay() [1/3]

int DicomImage::showOverlay ( const unsigned int  plane,
const unsigned int  idx = 0 
)
inline

activate specified overlay plane

Parameters
planenumber (0..15) or group number (0x60nn) of overlay plane
idxindex of overlay group (0 = dataset, 1 = additional), default: 0
Returns
false (0) if an error occurred, true otherwise (1 = plane successfully activated, 2 = plane has already been visible)

◆ showOverlay() [2/3]

int DicomImage::showOverlay ( const unsigned int  plane,
const EM_Overlay  mode,
const double  fore = 1.0,
const double  thresh = 0.5,
const unsigned int  idx = 0 
)
inline

activate specified overlay plane and change some parameters

Parameters
planenumber (0..15) or group number (0x60nn) of overlay plane
modedisplay mode (see 'diutils.h')
foreplane's foreground color (in percent, default: 1.0)
threshthreshold value (in percent, default: 0.5), only for EMO_ThresholdReplace
idxindex of overlay group (0 = dataset, 1 = additional), default: 0
Returns
false (0) if an error occurred, true otherwise

◆ showOverlay() [3/3]

int DicomImage::showOverlay ( const unsigned int  plane,
const Uint16  pvalue 
)
inline

activate specified overlay plane and change 'pvalue' (only for bitmap shutters)

Parameters
planenumber (0..15) or group number (0x60nn) of overlay plane
pvalueP-value used to display overlay plane
Returns
false (0) if an error occurred, true otherwise

◆ writeBMP() [1/2]

int DicomImage::writeBMP ( FILE *  stream,
const int  bits = 0,
const unsigned long  frame = 0 
)

write pixel data to BMP file (specified by open C stream).

pixel data is written in palette or truecolor mode. This method does not work if original YCbCr color model is retained (see CIF_KeepYCbCrColorModel).

Parameters
streamopen C output stream (binary mode required!)
bitsnumber of bits used for output of pixel data (8, 24 or 32, default (0): 8 for monochrome and 24 for color images)
frameindex of frame used for output (default: first frame = 0)
Returns
true if successful, false otherwise

◆ writeBMP() [2/2]

int DicomImage::writeBMP ( const char *  filename,
const int  bits = 0,
const unsigned long  frame = 0 
)

write pixel data to BMP file (specified by filename).

pixel data is written in palette or truecolor mode. This method does not work if original YCbCr color model is retained (see CIF_KeepYCbCrColorModel).

Parameters
filenamename of output file (d is replaced by frame number if present)
bitsnumber of bits used for output of pixel data (8, 24 or 32, default (0): 8 for monochrome and 24 for color images)
frameindex of frame used for output (default: first frame = 0)
Returns
true if successful, false otherwise

◆ writeFrameToDataset()

int DicomImage::writeFrameToDataset ( DcmItem dataset,
const int  bits = 0,
const unsigned long  frame = 0,
const int  planar = 0 
)
inline

render pixel data of the given frame and write image related attributes to DICOM dataset.

Applies VOI/PLUT transformation and (visible) overlay planes, output data is always padded to 8, 16, 32, ... bits (bits allocated). Replaces any modality transformation in the dataset by a linear rescale/slope since the modality transformation is rendered into the pixel data. Replaces the VOI transformations in the dataset by a "max range" VOI window. Removes all Overlay Plane Module attributes for embedded overlay planes from the dataset. Writes the following DICOM attributes (from Image Pixel Module):

  • Photometric Interpretation, Samples per Pixel
  • Columns, Rows, Number of Frames
  • Bits Allocated, Bits Stored, High Bit
  • Planar Configuration (only if "Samples per Pixel" is greater than 1)
  • Pixel Representation, Pixel Data Updates the following DICOM attributes (if present in the original image dataset):
  • Pixel Spacing and/or Pixel Aspect Ratio Supported output color models: Monochrome 2 for monochrome images and RGB (or YCbCr_Full if flag CIF_KeepYCbCrColorModel is set) for color images.
Parameters
datasetreference to DICOM dataset where the image attributes are stored
bitsnumber of bits per sample (image depth, 1..MAX_BITS)
framenumber of frame to be rendered (0..n-1)
planar0 = color-by-pixel (R1G1B1...R2G2B2...R3G3B3...), 1 = color-by-plane (R1R2R3...G1G2G3...B1B2B3...) (only applicable to multi-planar/color images, otherwise ignored)
Returns
true if successful, false otherwise

◆ writeImageToDataset()

int DicomImage::writeImageToDataset ( DcmItem dataset,
const int  mode = 0,
const int  planar = 2 
)
inline

write current image and related attributes to DICOM dataset.

Uses the internal representation of the pixel data, therefore the output data is always padded to 8, 16, 32, ... bits (bits allocated). Replaces any modality transformation in the dataset by a linear rescale/slope since the modality transformation is rendered into the pixel data. Removes all Overlay Plane Module attributes for embedded overlay planes from the dataset. Writes the following DICOM attributes (from Image Pixel Module):

  • Photometric Interpretation, Samples per Pixel
  • Columns, Rows, Number of Frames
  • Bits Allocated, Bits Stored, High Bit
  • Planar Configuration (only if "Samples per Pixel" is greater than 1)
  • Pixel Representation, Pixel Data Updates the following DICOM attributes (if present in the original image dataset):
  • Pixel Spacing and/or Pixel Aspect Ratio Supported output color models: Monochrome 1 or 2 for monochrome images and RGB (or YCbCr_Full if flag CIF_KeepYCbCrColorModel is set) for color images.
Parameters
datasetreference to DICOM dataset where the image attributes are stored
mode0 = determine value of BitsStored from 'used' pixel values, 1 = determine value of BitsStored from 'possible' pixel values (used for monochrome images only)
planar0 = color-by-pixel (R1G1B1...R2G2B2...R3G3B3...), 1 = color-by-plane (R1R2R3...G1G2G3...B1B2B3...), 2 = same as original DICOM image (i.e. color-by-pixel or color-by-plane) (only applicable to multi-planar/color images, otherwise ignored)
Returns
true if successful, false otherwise

References EPI_Unknown.

◆ writePluginFormat() [1/2]

int DicomImage::writePluginFormat ( const DiPluginFormat plugin,
FILE *  stream,
const unsigned long  frame = 0 
)

write pixel data to pluggable image format file (specified by open C stream).

Format specific parameters may be set directly in the instantiated 'plugin' class.

Parameters
pluginpointer to image format plugin (derived from abstract class DiPluginFormat)
streamopen C output stream (binary mode required!)
frameindex of frame used for output (default: first frame = 0)
Returns
true if successful, false otherwise

◆ writePluginFormat() [2/2]

int DicomImage::writePluginFormat ( const DiPluginFormat plugin,
const char *  filename,
const unsigned long  frame = 0 
)

write pixel data to pluggable image format file (specified by filename).

Format specific parameters may be set directly in the instantiated 'plugin' class.

Parameters
pluginpointer to image format plugin (derived from abstract class DiPluginFormat)
filenamename of output file (d is replaced by frame number if present)
frameindex of frame used for output (default: first frame = 0)
Returns
true if successful, false otherwise

◆ writePPM() [1/3]

int DicomImage::writePPM ( const char *  filename,
const int  bits = 0,
const unsigned long  frame = 0 
)

write pixel data to PPM file (specified by filename).

pixel data is written in ASCII format. This method does not work if original YCbCr color model is retained (see CIF_KeepYCbCrColorModel).

Parameters
filenamename of output file (d is replaced by frame number if present)
bitsnumber of bits used for output of pixel data (default: full resolution, max: 32; MI_PastelColor = -1 for true color pastel mode, EXPERIMENTAL)
frameindex of frame used for output (default: first frame = 0)
Returns
true if successful, false otherwise

◆ writePPM() [2/3]

int DicomImage::writePPM ( STD_NAMESPACE ostream &  stream,
const int  bits = 0,
const unsigned long  frame = 0 
)

write pixel data to PPM file (specified by open C++ stream).

pixel data is written in ASCII format. This method does not work if original YCbCr color model is retained (see CIF_KeepYCbCrColorModel).

Parameters
streamopen C++ output stream
bitsnumber of bits used for output of pixel data (default: full resolution, max: 32; MI_PastelColor = -1 for true color pastel mode, EXPERIMENTAL)
frameindex of frame used for output (default: first frame = 0)
Returns
true if successful, false otherwise

◆ writePPM() [3/3]

int DicomImage::writePPM ( FILE *  stream,
const int  bits = 0,
const unsigned long  frame = 0 
)

write pixel data to PPM file (specified by open C stream).

pixel data is written in ASCII format. This method does not work if original YCbCr color model is retained (see CIF_KeepYCbCrColorModel).

Parameters
streamopen C output stream
bitsnumber of bits used for output of pixel data (default: full resolution, max: 32; MI_PastelColor = -1 for true color pastel mode, EXPERIMENTAL)
frameindex of frame used for output (default: first frame = 0)
Returns
true if successful, false otherwise

◆ writeRawPPM() [1/2]

int DicomImage::writeRawPPM ( const char *  filename,
const int  bits = 0,
const unsigned long  frame = 0 
)

write pixel data to raw PPM file (specified by filename).

pixel data is written in binary format. This method does not work if original YCbCr color model is retained (see CIF_KeepYCbCrColorModel).

Parameters
filenamename of output file (d is replaced by frame number if present)
bitsnumber of bits used for output of pixel data (default: full resolution, max: 8; MI_PastelColor = -1 for true color pastel mode, EXPERIMENTAL)
frameindex of frame used for output (default: first frame = 0)
Returns
true if successful, false otherwise

◆ writeRawPPM() [2/2]

int DicomImage::writeRawPPM ( FILE *  stream,
const int  bits = 0,
const unsigned long  frame = 0 
)

write pixel data to raw PPM file (specified by open C stream).

pixel data is written in binary format. This method does not work if original YCbCr color model is retained (see CIF_KeepYCbCrColorModel).

Parameters
streamopen C output stream (binary mode required!)
bitsnumber of bits used for output of pixel data (default: full resolution, max: 8; MI_PastelColor = -1 for true color pastel mode, EXPERIMENTAL)
frameindex of frame used for output (default: first frame = 0)
Returns
true if successful, false otherwise

The documentation for this class was generated from the following file:


Generated on Mon Jul 17 2017 for DCMTK Version 3.6.2 by Doxygen 1.8.13