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.
	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
	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.
	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.
virtual	~DicomImage ()
	destructor
int	processNextFrames (const unsigned long fcount=0)
	process next couple of frames.
EI_Status	getStatus () const
	get current status information
unsigned long	getFrameCount () const
	get number of frames.
unsigned long	getFirstFrame () const
	get index of first frame.
unsigned long	getRepresentativeFrame () const
	get index of representative frame.
unsigned long	getWidth () const
	get image width in pixels
unsigned long	getHeight () const
	get image height in pixels
int	getDepth () const
	get image depth
int	getMinMaxValues (double &min, double &max, const int mode=0) const
	get minimum and maximum pixel values.
double	getWidthHeightRatio () const
	get width height ratio (pixel aspect ratio: x/y).
double	getHeightWidthRatio () const
	get height width ratio (pixel aspect ratio: y/x).
int	setWidthHeightRatio (const double ratio) const
	set width height ratio (pixel aspect ratio: x/y)
int	setHeightWidthRatio (const double ratio) const
	set height width ratio (pixel aspect ratio: y/x)
int	isOutputValueUnused (const unsigned long value)
	check whether given output value is unused
unsigned long	getOutputDataSize (const int bits=0) const
	get number of bytes required for the rendered output of a single frame.
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.
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.
const void *	getOutputPlane (const int plane) const
	render pixel data and return pointer to given plane (internal memory buffer).
void	deleteOutputData () const
	delete internal memory buffer used for rendered images.
int	isMonochrome () const
	check whether image is monochrome or not.
EP_Interpretation	getPhotometricInterpretation () const
	get code for photometric interpretation (color model).
int	hasSOPclassUID (const char *uid) const
	check whether image has given SOP class UID.
const DiPixel *	getInterData () const
	get intermediate pixel data representation (read-only).
DiDisplayFunction *	getDisplayFunction () const
	get display function
int	setDisplayFunction (DiDisplayFunction *display)
	set display function
int	setNoDisplayFunction ()
	set no display function.
int	deleteDisplayLUT (const int bits=0)
	delete specified display LUT(s)
int	convertPValueToDDL (const Uint16 pvalue, Uint16 &ddl, const int bits=8)
	convert P-value to DDL.
int	setNoVoiTransformation ()
	unset all VOI transformations (windows and LUTs).
int	setMinMaxWindow (const int idx=0)
	set automatically calculated minimum/maximum window.
int	setHistogramWindow (const double thresh=0.05)
	set automatically calculated histogram window.
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).
int	setWindow (const unsigned long window)
	set specified window (given by index to window width/center sequence stored in image file).
int	setWindow (const double center, const double width)
	set specified window (given by window width and center).
int	getWindow (double &center, double &width)
	get current window center and width values
unsigned long	getWindowCount () const
	get number of VOI windows (stored in image file).
int	setVoiLutFunction (const EF_VoiLutFunction function)
	set VOI LUT function
EF_VoiLutFunction	getVoiLutFunction () const
	get VOI LUT function.
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).
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).
unsigned long	getVoiLutCount () const
	get number of VOI LUTs (stored in image file)
const char *	getVoiTransformationExplanation () const
	get description of active VOI transformation
const char *	getVoiWindowExplanation (const unsigned long window, OFString &explanation) const
	get description of specified VOI window (stored in the image file)
const char *	getVoiLutExplanation (const unsigned long table, OFString &explanation) const
	get description of specified VOI LUT (stored in the image file)
const char *	getModalityLutExplanation () const
	get description of performed modality LUT transformation
EP_Polarity	getPolarity () const
	get polarity.
int	setPolarity (const EP_Polarity polarity)
	set polarity.
int	setHardcopyParameters (const unsigned int min, const unsigned int max, const unsigned int reflect, const unsigned int illumin)
	set hardcopy parameters.
ES_PresentationLut	getPresentationLutShape () const
	get shape for presentation transformation.
int	setPresentationLutShape (const ES_PresentationLut shape)
	set shape for presentation transformation.
int	setPresentationLut (const DcmUnsignedShort &data, const DcmUnsignedShort &descriptor, const DcmLongString *explanation=NULL, const EL_BitsPerTableEntry descripMode=ELM_UseValue)
	set LUT for presentation transformation.
const char *	getPresentationLutExplanation () const
	get description of active presentation LUT
int	setInversePresentationLut (const DcmUnsignedShort &data, const DcmUnsignedShort &descriptor, const EL_BitsPerTableEntry descripMode=ELM_UseValue)
	set inverse LUT for presentation transformation.
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.
int	removeOverlay (const unsigned int group)
	remove specified (additional) overlay plane
int	removeAllOverlays ()
	remove all additional overlay planes
int	isOverlayVisible (const unsigned int plane, const unsigned int idx=0)
	check whether specified overlay plane is visible/activated.
int	showOverlay (const unsigned int plane, const unsigned int idx=0)
	activate specified overlay plane
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
int	showOverlay (const unsigned int plane, const Uint16 pvalue)
	activate specified overlay plane and change 'pvalue' (only for bitmap shutters)
int	showAllOverlays (const unsigned int idx=0)
	activate all overlay planes (make them visible)
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
int	hideOverlay (const unsigned int plane, const unsigned int idx=0)
	deactivate specified overlay plane
int	hideAllOverlays (const unsigned int idx=0)
	deactivate all overlay planes (make them invisible)
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
unsigned int	getOverlayCount (const unsigned int idx=0) const
	get number of overlay planes
unsigned int	getOverlayGroupNumber (const unsigned int plane, const unsigned int idx=0) const
	get group number of specified overlay plane
const char *	getOverlayLabel (const unsigned int plane, const unsigned int idx=0) const
	get label of specified overlay plane
const char *	getOverlayDescription (const unsigned int plane, const unsigned int idx=0) const
	get description of specified overlay plane
EM_Overlay	getOverlayMode (const unsigned int plane, const unsigned int idx=0) const
	get mode of specified overlay plane
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.
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.
void	deleteOverlayData () const
	delete buffer for overlay plane data.
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.
DicomImage *	createDicomImage (unsigned long fstart=0, unsigned long fcount=0) const
	create copy of current image object.
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).
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).
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.
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.
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).
int	flipImage (int horz=1, int vert=0) const
	flip current image (horizontally and/or vertically)
DicomImage *	createFlippedImage (int horz=1, int vert=0) const
	create a flipped copy of the current image.
int	rotateImage (signed int degree) const
	rotate current image (by steps of 90 degrees)
DicomImage *	createRotatedImage (signed int degree) const
	create a rotated copy of the current image.
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.
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.
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).
DicomImage *	createMonoOutputImage (const unsigned long frame, const int bits)
	create new single frame DicomImage with applied grayscale transformations.
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.
int	writeImageToDataset (DcmItem &dataset, const int mode=0, const int planar=2)
	write current image and related attributes to DICOM dataset.
int	writePPM (const char *filename, const int bits=0, const unsigned long frame=0)
	write pixel data to PPM file (specified by filename).
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).
int	writePPM (FILE *stream, const int bits=0, const unsigned long frame=0)
	write pixel data to PPM file (specified by open C stream).
int	writeRawPPM (const char *filename, const int bits=0, const unsigned long frame=0)
	write pixel data to raw PPM file (specified by filename).
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).
int	writeBMP (FILE *stream, const int bits=0, const unsigned long frame=0)
	write pixel data to BMP file (specified by open C stream).
int	writeBMP (const char *filename, const int bits=0, const unsigned long frame=0)
	write pixel data to BMP file (specified by filename).
int	writePluginFormat (const DiPluginFormat plugin, FILE stream, const unsigned long frame=0)
	write pixel data to plugable image format file (specified by open C stream).
int	writePluginFormat (const DiPluginFormat plugin, const char filename, const unsigned long frame=0)
	write pixel data to plugable image format file (specified by filename).
Static Public Member Functions
static const char *	getString (const EI_Status status)
	convert status code to status string
static const char *	getString (const EP_Interpretation interpret)
	convert photometric interpretation code to interpretation string (defined term)
static void *	create12BitPackedBitmap (const void *buffer, const unsigned long size, const unsigned long count)
	create 12 bit packed (monochrome) bitmap for DICOM printers.
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
void	Init ()
	initialize object.
int	checkDataDictionary ()
	check whether data dictionary is present
const char *	getSOPclassUID () const
	get SOP class UID of current image object
int	normalizeDegreeValue (signed int &degree) const
	normalize given degree value (for internal use).
Private Member Functions
	DicomImage (const DicomImage &)
DicomImage &	operator= (const DicomImage &)
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::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:

filename	the DICOM file
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::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::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::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::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

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 orgin (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)

int DicomImage::checkDataDictionary ( ) [protected]

check whether data dictionary is present

Returns:: true if dictionary is present, false otherwise

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

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)

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

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 orgin, 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)

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)

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)

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 occured

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)

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)

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)

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)

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)

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)

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 orgin, 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)

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 suffiently 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 occured

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

void DicomImage::deleteOutputData ( ) const [inline]

delete internal memory buffer used for rendered images.

Save memory if data is no longer needed.

void DicomImage::deleteOverlayData ( ) const [inline]

delete buffer for overlay plane data.

Save memory if data is no longer needed.

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

int DicomImage::getDepth ( ) const [inline]

get image depth

Returns:: number of bits per sample of the internal representation

DiDisplayFunction* DicomImage::getDisplayFunction ( ) const [inline]

get display function

Returns:: pointer to current display function, NULL if absent

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)

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. It rather refers to the number of frames processed by this class (see constructors for details).

Returns:: number of frames

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)

unsigned long DicomImage::getHeight ( ) const [inline]

get image height in pixels

Returns:: number of pixels in one column

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 supported in order to determine this value:

Pixel Spacing, Imager Pixel Spacing, Nominal Scanned Pixel Spacing, Pixel Aspect Ratio

Returns:: pixel aspect ratio (floating point value)

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

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)

const char* DicomImage::getModalityLutExplanation ( ) const [inline]

get description of performed modality LUT transformation

Returns:: pointer to description text (NULL if absent)

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, RGB (and YCbCr_Full if flag CIF_KeepYCbCrColorModel set). The rendered pixel data is alway 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)

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, RGB (and YCbCr_Full if flag CIF_KeepYCbCrColorModel set). The rendered pixel data is alway 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)

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

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, RGB (and YCbCr_Full if flag CIF_KeepYCbCrColorModel set). The rendered pixel data is alway unsigned.

Parameters:

plane number of plane to be rendered

Returns:: pointer to internal memory buffer containing rendered pixel data (if successful, NULL otherwise)

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

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)

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

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

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

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 succesful, EMO_Default otherwise

EP_Interpretation DicomImage::getPhotometricInterpretation ( ) const [inline]

get code for photometric interpretation (color model).

Returns:: code for photometric interpretation of the image

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

const char* DicomImage::getPresentationLutExplanation ( ) const [inline]

get description of active presentation LUT

Returns:: pointer to description text (NULL if absent)

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

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)

const char* DicomImage::getSOPclassUID ( ) const [protected]

get SOP class UID of current image object

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

EI_Status DicomImage::getStatus ( ) const [inline]

get current status information

Returns:: status code

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

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

unsigned long DicomImage::getVoiLutCount ( ) const [inline]

get number of VOI LUTs (stored in image file)

Returns:: number of VOI LUTs

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)

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

const char* DicomImage::getVoiTransformationExplanation ( ) const [inline]

get description of active VOI transformation

Returns:: pointer to description text (NULL if absent)

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)

unsigned long DicomImage::getWidth ( ) const [inline]

get image width in pixels

Returns:: number of pixels in one row

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 supported in order to determine this value:

Pixel Spacing, Imager Pixel Spacing, Nominal Scanned Pixel Spacing, Pixel Aspect Ratio
Returns:
pixel aspect ratio (floating point value)

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

get current window center and width values

Parameters:

center	return current window center value
width	return current window width value

Returns:: true if successful, false otherwise

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

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

check whether image has given SOP class UID.

Returns:: true if image has given SOP class UID, false otherwise

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)

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)

void DicomImage::Init ( ) [protected]

initialize object.

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

int DicomImage::isMonochrome ( ) const [inline]

check whether image is monochrome or not.

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

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

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

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)

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)

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

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)

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

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

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

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

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)

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

set automatically calculated histogram window.

possibly active VOI LUT is implicitly disabled.

Parameters:

thresh threshhold value specifying percentage of histogram border which shall be ignored (defaut: 5%).

Returns:: true if successful, false otherwise

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

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 sucessful (1 = window has changed, 2 = new window is the same as previous one), false otherwise

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

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)

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

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

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

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 sucessful (1 = window has changed, 2 = new window is the same as previous one), false otherwise

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

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)

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

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)

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

set specified 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)

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

set specified 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 (> 0.0)

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

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)

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	treshhold value (in percent, default: 0.5), only for EMO_TreshholdReplace
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)

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)

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	treshhold value (in percent, default: 0.5), only for EMO_TreshholdReplace
idx	index of overlay group (0 = dataset, 1 = additional), default: 0

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

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

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

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

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, RGB (and YCbCr_Full if flag CIF_KeepYCbCrColorModel set).

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

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/2, RGB (and YCbCr_Full if flag CIF_KeepYCbCrColorModel set).

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

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

write pixel data to plugable 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

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

write pixel data to plugable 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

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

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

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

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

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

Public Member Functions

Static Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation