DCMTK Version 3.7.0 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 OFFilename &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 DiPixel * | getInterData () const
| get intermediate pixel data representation (read-only). More...
DiDisplayFunction * | getDisplayFunction () 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...
DicomImage * | createDicomImage (unsigned long fstart=0, unsigned long fcount=0) const
| create copy of current image object. More...
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). More...
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). More...
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. More...
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. More...
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). More...
int | flipImage (int horz=1, int vert=0) const
| flip current image (horizontally and/or vertically) More...
DicomImage * | createFlippedImage (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...
DicomImage * | createRotatedImage (signed int degree) const
| create a rotated copy of the current image. More...
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. 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...
DicomImage * | createMonoOutputImage (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)
DiDocument * | Document
| points to document object
DiImage * | Image
| 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 OFFilename & | 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

  filename | the DICOM file specified by its filename
  flags | configuration flags (see diutils.h, CIF_MayDetachPixelData is set automatically)
  fstart | first frame to be processed (optional, 0 = 1st frame), all subsequent use of parameters labeled 'frame' in this class refers to this start frame.
  fcount | number 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

  object | pointer 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)
  xfer | transfer syntax of the 'object'. (could also be EXS_Unknown in case of fileformat or dataset)
  flags | configuration flags (CIF_xxx, see diutils.h)
  fstart | first frame to be processed (optional, 0 = 1st frame), all subsequent use of parameters labeled 'frame' in this class refers to this start frame.
  fcount | number 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

  object | pointer 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)
  xfer | transfer syntax of the 'object'. (could also be EXS_Unknown in case of fileformat or dataset)
  slope | rescale slope (modality transformation)
  intercept | rescale intercept (modality transformation)
  flags | configuration flags (CIF_xxx, see diutils.h)
  fstart | first frame to be processed (optional, 0 = 1st frame), all subsequent use of parameters labeled 'frame' in this class refers to this start frame.
  fcount | number 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

  object | pointer 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)
  xfer | transfer syntax of the 'object'. (could also be EXS_Unknown in case of fileformat or dataset)
  data | dataset element containing modality LUT data
  descriptor | dataset element containing modality LUT descriptor
  explanation | dataset element containing modality LUT explanation
  flags | configuration flags (CIF_xxx, see diutils.h)
  fstart | first frame to be processed (optional, 0 = 1st frame), all subsequent use of parameters labeled 'frame' in this class refers to this start frame.
  fcount | number 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

  dicom | source object to be copied
  image | new image data
  interpret | new 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

  group | group number (0x60nn) of overlay plane
  width | width of overlay plane (in pixels)
  height | height of overlay plane (in pixels)
  left_pos | x coordinate of plane origin (referring to image origin)
  top_pos | y coordinate of plane origin
  data | overlay plane data (dcmdata element)
  label | overlay plane label
  description | overlay plane description
  mode | display 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

  pvalue | P-value to be converted (0..65535)
  ddl | reference to resulting DDL
  bits | number 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
| ) |  |
| inline static

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

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

Parameters

  buffer | pointer to input memory buffer (16 bits allocated, 12 bits stored)
  size | size of memory buffer (will be checked whether it is sufficient)
  count | number 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

  buffer | stores pointer to overlay data (memory is allocated internally)
  plane | number (0..15) or group number (0x60nn) of overlay plane
  width | returns width of overlay plane (in pixels)
  height | returns height of overlay plane (in pixels)
  frames | returns number of frames
  idx | index 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_pos | x coordinate of top left corner of area to be copied (referring to image origin, negative values create a border around the image)
  top_pos | y coordinate of top left corner of area to be copied
  width | width of area to be copied/clipped
  height | height of area to be copied/clipped
  pvalue | P-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

  fstart | first frame to be processed (0 = 1st frame)
  fcount | number 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

  horz | flip horizontally if true
  vert | flip 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

  data | resulting pointer to bitmap data (set to NULL if an error occurred)
  frame | index of frame to be converted (default: 0 = first frame)
  bits | number 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

  red | coefficient by which the red component is weighted (default: NTSC value)
  green | coefficient by which the green component is weighted (default: NTSC value)
  blue | coefficient 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

  frame | index of frame to be converted
  bits | number 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

  degree | angle 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 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

  xfactor | width of new image is multiplied with this factor (> 0)
  yfactor | height of new image is multiplied with this factor (> 0)
  interpolate | specifies 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
  aspect | specifies 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 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_pos | x coordinate of top left corner of area to be scaled (referring to image origin, negative values create a border around the image)
  top_pos | y coordinate of top left corner of area to be scaled
  clip_width | width of area to be scaled
  clip_height | height of area to be scaled
  scale_width | width of scaled image (in pixels)
  scale_height | height of scaled image (in pixels)
  interpolate | specifies 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
  aspect | specifies 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)
  pvalue | P-value used for the border outside the image (0..65535)

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 | 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_pos | x coordinate of top left corner of area to be scaled (referring to image origin, negative values create a border around the image)
  top_pos | y coordinate of top left corner of area to be scaled
  width | width of area to be scaled
  height | height of area to be scaled
  xfactor | width of new image is multiplied with this factor (> 0)
  yfactor | height of new image is multiplied with this factor (> 0)
  interpolate | specifies 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
  aspect | specifies 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)
  pvalue | P-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 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

  width | width of new image (in pixels)
  height | height of new image (in pixels)
  interpolate | specifies 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
  aspect | specifies 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)

## ◆ 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

  data | untyped pointer memory buffer (set to NULL if not allocated externally)
  size | size of the memory buffer in bytes (if 0 'data' is set to NULL)
  frame | index of frame to be converted (default: 0 = first frame)
  bits | number of bits per pixel used for the output bitmap (8, 24 or 32, default: 24)
  upsideDown | flag 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)
  padding | align 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

  bits | parameter 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

  horz | flip horizontally if true
  vert | flip 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

  plane | number (0..15) or group number (0x60nn) of overlay plane
  width | returns width of overlay plane (in pixels)
  height | returns height of overlay plane (in pixels)
  frame | index of frame used for output (default: 0 = first)
  bits | number 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'.
  fore | foreground color to be set in bitmap, default: 255, range: 0..2^bits-1
  back | background color to be set in bitmap (transparent), default: 0, range: 0..2^bits-1
  idx | index 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

  min | minimum pixel value (reference parameter)
  max | maximum pixel value (reference parameter)
  mode | 0 = 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

  bits | number 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)
  frame | number of frame to be rendered (0..n-1)
  planar | 0 = 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

  buffer | pointer to memory buffer (must already be allocated)
  size | size of memory buffer (will be checked whether it is sufficient)
  bits | number 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)
  frame | number of frame to be rendered (0..n-1)
  planar | 0 = 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

  bits | number 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

  plane | number 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

  idx | index 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

  plane | number (0..15) or group number (0x60nn) of overlay plane
  width | returns width of overlay plane (in pixels)
  height | returns height of overlay plane (in pixels)
  left_pos | returns x coordinate of plane's origin
  top_pos | returns y coordinate of plane's origin
  mode | returns display mode (see 'diutils.h')
  frame | index of frame used for output (default: 0 = first)
  bits | number 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'.
  fore | foreground color to be set in bitmap, default: 255, range: 0..2^bits-1
  back | background color to be set in bitmap (transparent), default: 0, range: 0..2^bits-1
  idx | index 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

  plane | number (0..15) or group number (0x60nn) of overlay plane
  idx | index 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

  plane | number (0..15) or group number (0x60nn) of overlay plane
  idx | index 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

  plane | number (0..15) or group number (0x60nn) of overlay plane
  idx | index 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

  plane | number (0..15) or group number (0x60nn) of overlay plane
  idx | index 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

  status | code 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

  interpret | code 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

  table | index of the stored VOI LUT (0..n-1)
  explanation | variable 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

  window | index of the stored VOI window (0..n-1)
  explanation | variable 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

  center | return current window center value
  width | return 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

  uid | SOP 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

  idx | index 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

  plane | number (0..15) or group number (0x60nn) of overlay plane
  idx | index 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

  value | output 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

  plane | number (0..15) or group number (0x60nn) of overlay plane
  idx | index 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

  degree | value 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

  plane | number (0..15) or group number (0x60nn) of overlay plane
  left_pos | x coordinate of new plane origin (origin = 0)
  top_pos | y coordinate of new plane origin (origin = 0)
  idx | index 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

  fcount | number 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

  group | group 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

  degree | angle 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

  display | object 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

  min | minimum density of the print-out (in hundreds of Optical Density, e.g. 150 means 1.5 OD)
  max | maximum density of the print-out (ditto)
  reflect | reflected ambient light (in candela per square meter - cd/m^2)
  illumin | illumination (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

  ratio | pixel 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

  thresh | threshold value specifying percentage of histogram border which shall be ignored (default: 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

  data | contains LUT data
  descriptor | describes LUT structure
  descripMode | mode 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

  idx | ignore 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

  polarity | polarity (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

  data | contains LUT data
  descriptor | describes LUT structure
  explanation | free form description of presentation LUT (optional)
  descripMode | mode 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

  shape | presentation 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_pos | x-coordinate of the top left-hand corner of the ROI (starting from 0)
  top_pos | y-coordinate of the top left-hand corner of the ROI (starting from 0)
  width | width in pixels of the rectangular ROI (minimum: 1)
  height | height in pixels of the rectangular ROI (minimum: 1)
  frame | index 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

  data | contains LUT data
  descriptor | describes LUT structure
  explanation | free form description of VOI LUT (optional)
  descripMode | mode 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

  table | index to VOI LUT sequence (0..n-1)
  descripMode | mode 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

  function | type 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

  ratio | pixel aspect ratio (x/y)

Returns
  status code (true if successful)

## ◆ setWindow() [1/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

  center | center of specified window
  width | width of specified window (>= 1.0)

Returns
  true if successful (1 = window has changed, 2 = new window is the same as previous one), false otherwise

## ◆ setWindow() [2/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

  window | index to window width/center sequence (0..n-1)

Returns
  true if successful, false otherwise (none monochrome or invalid index)

## ◆ showAllOverlays() [1/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

  mode | display mode (see 'diutils.h')
  fore | plane's foreground color (in percent, default: 1.0)
  thresh | threshold value (in percent, default: 0.5), only for EMO_ThresholdReplace
  idx | index 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 unsigned int | idx = `0` | ) |
| inline

activate all overlay planes (make them visible)

Parameters

  idx | index 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 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

  plane | number (0..15) or group number (0x60nn) of overlay plane
  mode | display mode (see 'diutils.h')
  fore | plane's foreground color (in percent, default: 1.0)
  thresh | threshold value (in percent, default: 0.5), only for EMO_ThresholdReplace
  idx | index of overlay group (0 = dataset, 1 = additional), default: 0

Returns
  false (0) if an error occurred, true otherwise

## ◆ showOverlay() [2/3]

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

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

Parameters

  plane | number (0..15) or group number (0x60nn) of overlay plane
  pvalue | P-value used to display overlay plane

Returns
  false (0) if an error occurred, true otherwise

## ◆ showOverlay() [3/3]

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

activate specified overlay plane

Parameters

  plane | number (0..15) or group number (0x60nn) of overlay plane
  idx | index 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)

## ◆ writeBMP() [1/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

  filename | name of output file (d is replaced by frame number if present)
  bits | number of bits used for output of pixel data (8, 24 or 32, default (0): 8 for monochrome and 24 for color images)
  frame | index of frame used for output (default: first frame = 0)

Returns
  true if successful, false otherwise

## ◆ writeBMP() [2/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

  stream | open C output stream (binary mode required!)
  bits | number of bits used for output of pixel data (8, 24 or 32, default (0): 8 for monochrome and 24 for color images)
  frame | index 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

  dataset | reference to DICOM dataset where the image attributes are stored
  bits | number of bits per sample (image depth, 1..MAX_BITS)
  frame | number of frame to be rendered (0..n-1)
  planar | 0 = 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

  dataset | reference to DICOM dataset where the image attributes are stored
  mode | 0 = determine value of BitsStored from 'used' pixel values, 1 = determine value of BitsStored from 'possible' pixel values (used for monochrome images only)
  planar | 0 = 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

## ◆ writePluginFormat() [1/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

  plugin | pointer to image format plugin (derived from abstract class DiPluginFormat)
  filename | name of output file (d is replaced by frame number if present)
  frame | index of frame used for output (default: first frame = 0)

Returns
  true if successful, false otherwise

## ◆ writePluginFormat() [2/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

  plugin | pointer to image format plugin (derived from abstract class DiPluginFormat)
  stream | open C output stream (binary mode required!)
  frame | index 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

  filename | name of output file (d is replaced by frame number if present)
  bits | number of bits used for output of pixel data (default: full resolution, max: 32; MI_PastelColor = -1 for true color pastel mode, EXPERIMENTAL)
  frame | index of frame used for output (default: first frame = 0)

Returns
  true if successful, false otherwise

## ◆ writePPM() [2/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

  stream | open C output stream
  bits | number of bits used for output of pixel data (default: full resolution, max: 32; MI_PastelColor = -1 for true color pastel mode, EXPERIMENTAL)
  frame | index of frame used for output (default: first frame = 0)

Returns
  true if successful, false otherwise

## ◆ writePPM() [3/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

  stream | open C++ output stream
  bits | number of bits used for output of pixel data (default: full resolution, max: 32; MI_PastelColor = -1 for true color pastel mode, EXPERIMENTAL)
  frame | index 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

  filename | name of output file (d is replaced by frame number if present)
  bits | number of bits used for output of pixel data (default: full resolution, max: 8; MI_PastelColor = -1 for true color pastel mode, EXPERIMENTAL)
  frame | index 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

  stream | open C output stream (binary mode required!)
  bits | number of bits used for output of pixel data (default: full resolution, max: 8; MI_PastelColor = -1 for true color pastel mode, EXPERIMENTAL)
  frame | index 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:

- dcmimgle/include/dcmtk/dcmimgle/dcmimage.h

Generated on Mon Dec 15 2025 for DCMTK Version 3.7.0 by Doxygen 1.9.1