DcmFileFormat Class Reference

a class handling the DICOM file format (with meta header) More...

Inheritance diagram for DcmFileFormat:

List of all members.

Public Member Functions
	DcmFileFormat ()
	default constructor
	DcmFileFormat (DcmDataset *dataset)
	constructor
	DcmFileFormat (const DcmFileFormat &old)
	copy constructor
virtual	~DcmFileFormat ()
	destructor
DcmFileFormat &	operator= (const DcmFileFormat &obj)
	assignment operator
virtual DcmObject *	clone () const
	clone method
virtual OFCondition	copyFrom (const DcmObject &rhs)
	Virtual object copying.
virtual DcmEVR	ident () const
	get type identifier
virtual OFCondition	clear ()
	clear file meta information header and dataset
virtual void	removeInvalidGroups ()
	remove all elements with an invalid group number from the meta information header and dataset
virtual void	print (STD_NAMESPACE ostream &out, const size_t flags=0, const int level=0, const char *pixelFileName=NULL, size_t *pixelCounter=NULL)
	print meta header and dataset to a stream
virtual OFCondition	validateMetaInfo (const E_TransferSyntax oxfer, const E_FileWriteMode writeMode=EWM_fileformat)
	make sure that all data elements of the file meta information header are existent in metainfo and contain correct values.
DcmMetaInfo *	getMetaInfo ()
	get file meta information header part of the fileformat
DcmDataset *	getDataset ()
	get dataset part of the fileformat
DcmDataset *	getAndRemoveDataset ()
	get dataset part and remove it from the fileformat.
virtual Uint32	calcElementLength (const E_TransferSyntax xfer, const E_EncodingType enctype)
	calculate the length of this DICOM element when encoded with the given transfer syntax and the given encoding type for sequences.
virtual OFBool	canWriteXfer (const E_TransferSyntax newXfer, const E_TransferSyntax oldXfer=EXS_Unknown)
	check if this DICOM object can be encoded in the given transfer syntax.
virtual OFCondition	read (DcmInputStream &inStream, const E_TransferSyntax xfer=EXS_Unknown, const E_GrpLenEncoding glenc=EGL_noChange, const Uint32 maxReadLength=DCM_MaxReadLength)
	read object from a stream.
virtual OFCondition	write (DcmOutputStream &outStream, const E_TransferSyntax oxfer, const E_EncodingType enctype, DcmWriteCache *wcache)
	write fileformat to a stream
virtual OFCondition	write (DcmOutputStream &outStream, const E_TransferSyntax oxfer, const E_EncodingType enctype, DcmWriteCache *wcache, const E_GrpLenEncoding glenc, const E_PaddingEncoding padenc=EPD_noChange, const Uint32 padlen=0, const Uint32 subPadlen=0, Uint32 instanceLength=0, const E_FileWriteMode writeMode=EWM_fileformat)
	write object to a stream (abstract)
virtual OFCondition	writeXML (STD_NAMESPACE ostream &out, const size_t flags=0)
	write object in XML format.
virtual OFCondition	loadFile (const OFFilename &fileName, const E_TransferSyntax readXfer=EXS_Unknown, const E_GrpLenEncoding groupLength=EGL_noChange, const Uint32 maxReadLength=DCM_MaxReadLength, const E_FileReadMode readMode=ERM_autoDetect)
	load object from a DICOM file.
virtual OFCondition	saveFile (const OFFilename &fileName, const E_TransferSyntax writeXfer=EXS_Unknown, const E_EncodingType encodingType=EET_UndefinedLength, const E_GrpLenEncoding groupLength=EGL_recalcGL, const E_PaddingEncoding padEncoding=EPD_noChange, const Uint32 padLength=0, const Uint32 subPadLength=0, const E_FileWriteMode writeMode=EWM_fileformat)
	save object to a DICOM file.
OFCondition	chooseRepresentation (const E_TransferSyntax repType, const DcmRepresentationParameter *repParam)
	select a specific representation (compressed or uncompressed) of the dataset and create the representation if needed.
OFBool	hasRepresentation (const E_TransferSyntax repType, const DcmRepresentationParameter *repParam)
	check if all PixelData elements in this dataset have a representation conforming to the given transfer syntax and representation parameters (see dcpixel.h for definition of "conforming").
void	removeAllButOriginalRepresentations ()
	removes all but the original representation in all pixel data elements
void	removeAllButCurrentRepresentations ()
	removes all but the current representation in all pixel data elements.
E_FileReadMode	getReadMode () const
	get current file read mode.
void	setReadMode (const E_FileReadMode readMode)
	set current file read mode.
virtual OFCondition	insertItem (DcmItem *item, const unsigned long where=DCM_EndOfListIndex)
	method inherited from base class that shall not be used for instances of this class.
virtual DcmItem *	remove (const unsigned long num)
	method inherited from base class that shall not be used for instances of this class.
virtual DcmItem *	remove (DcmItem *item)
	method inherited from base class that shall not be used for instances of this class.
virtual OFCondition	convertCharacterSet (const OFString &fromCharset, const OFString &toCharset, const OFBool transliterate=OFFalse)
	convert all element values that are contained in the dataset and that are affected by SpecificCharacterSet from the given source character set to the given destination character set.
virtual OFCondition	convertCharacterSet (const OFString &toCharset, const OFBool transliterate=OFFalse)
	convert all element values that are contained in the dataset and that are affected by SpecificCharacterSet to the given destination character set.
virtual OFCondition	convertCharacterSet (DcmSpecificCharacterSet &converter)
	convert all element values that are contained in the dataset and that are affected by SpecificCharacterSet from the currently selected source character set to the currently selected destination character set
virtual OFCondition	convertToUTF8 ()
	convert all element values that are contained in the dataset and that are affected by SpecificCharacterSet to UTF-8 (Unicode).
Static Private Member Functions
static OFCondition	checkMetaHeaderValue (DcmMetaInfo *metainfo, DcmDataset *dataset, const DcmTagKey &atagkey, DcmObject *obj, const E_TransferSyntax oxfer, const E_FileWriteMode writeMode)
	This function checks if a particular data element of the file meta information header is existent.
static E_TransferSyntax	lookForXfer (DcmMetaInfo *metainfo)
	read DCM_TransferSyntaxUID from meta header dataset and return as E_TransferSyntax value
Private Attributes
E_FileReadMode	FileReadMode
	file read mode, specifies whether to read the meta header or not

---

Detailed Description

a class handling the DICOM file format (with meta header)

---

Constructor & Destructor Documentation

DcmFileFormat::DcmFileFormat

(

DcmDataset *

dataset

)

constructor

Parameters:

dataset

to be copied (!) into the new DcmFileFormat object

DcmFileFormat::DcmFileFormat

(

const DcmFileFormat &

old

)

copy constructor

Parameters:

old	element to be copied

---

Member Function Documentation

virtual Uint32 DcmFileFormat::calcElementLength	(	const E_TransferSyntax	xfer,
		const E_EncodingType	enctype
	)		[virtual]

calculate the length of this DICOM element when encoded with the given transfer syntax and the given encoding type for sequences.

For elements, the length includes the length of the tag, length field, VR field and the value itself, for items and sequences it returns the length of the complete item or sequence including delimitation tags if applicable. Never returns undefined length.

Parameters:

xfer	transfer syntax for length calculation
enctype	sequence encoding type for length calculation

Returns:

length of DICOM element

Reimplemented from DcmSequenceOfItems.

virtual OFBool DcmFileFormat::canWriteXfer	(	const E_TransferSyntax	newXfer,
		const E_TransferSyntax	oldXfer = EXS_Unknown
	)		[virtual]

check if this DICOM object can be encoded in the given transfer syntax.

Parameters:

newXfer	transfer syntax in which the DICOM object is to be encoded
oldXfer	transfer syntax in which the DICOM object was read or created.

Returns:

true if object can be encoded in desired transfer syntax, false otherwise.

Reimplemented from DcmSequenceOfItems.

static OFCondition DcmFileFormat::checkMetaHeaderValue	(	DcmMetaInfo *	metainfo,
		DcmDataset *	dataset,
		const DcmTagKey &	atagkey,
		DcmObject *	obj,
		const E_TransferSyntax	oxfer,
		const E_FileWriteMode	writeMode
	)		[static, private]

This function checks if a particular data element of the file meta information header is existent.

If the element is not existent, it will be inserted. Additionally, this function makes sure that the corresponding data element will contain a correct value.

Parameters:

metainfo	the meta header information
dataset	the data set information
atagkey	tag of the data element which shall be checked
obj	data object from metainfo which represents the data element that shall be checked. Equals NULL if this data element is not existent in the meta header information.
oxfer	The transfer syntax which shall be used.
writeMode	flag indicating whether to update the file meta information or not

Returns:

EC_Normal if successful, an error code otherwise

OFCondition DcmFileFormat::chooseRepresentation	(	const E_TransferSyntax	repType,
		const DcmRepresentationParameter *	repParam
	)		[inline]

select a specific representation (compressed or uncompressed) of the dataset and create the representation if needed.

This may cause compression or decompression to be applied to the pixel data in the dataset.

Parameters:

repType	desired transfer syntax
repParam	desired representation parameter (e.g. quality factor for lossy compression)

Returns:

EC_Normal upon success, an error code otherwise.

virtual OFCondition DcmFileFormat::clear

(

)

[virtual]

clear file meta information header and dataset

Returns:

EC_Normal if successful, an error code otherwise

Reimplemented from DcmSequenceOfItems.

virtual DcmObject* DcmFileFormat::clone

(

)

const [inline, virtual]

clone method

Returns:

deep copy of this object

Reimplemented from DcmSequenceOfItems.

virtual OFCondition DcmFileFormat::convertCharacterSet	(	const OFString &	fromCharset,
		const OFString &	toCharset,
		const OFBool	transliterate = OFFalse
	)		[virtual]

convert all element values that are contained in the dataset and that are affected by SpecificCharacterSet from the given source character set to the given destination character set.

The defined terms for a particular character set can be found in the DICOM standard, e.g. "ISO_IR 100" for ISO 8859-1 (Latin 1) or "ISO_IR 192" for Unicode in UTF-8. An empty string denotes the default character repertoire, which is ASCII (7-bit). If multiple values are given for 'fromCharset' (separated by a backslash) code extension techniques are used and escape sequences may be encountered in the source string to switch between the specified character sets.

Parameters:

fromCharset	name of the source character set(s) used for the conversion
toCharset	name of the destination character set used for the conversion. Only a single value is permitted (i.e. no code extensions).
transliterate	mode specifying whether a character that cannot be represented in the destination character encoding is approximated through one or more characters that look similar to the original one

Returns:

status, EC_Normal if successful, an error code otherwise

virtual OFCondition DcmFileFormat::convertCharacterSet	(	const OFString &	toCharset,
		const OFBool	transliterate = OFFalse
	)		[virtual]

convert all element values that are contained in the dataset and that are affected by SpecificCharacterSet to the given destination character set.

The source character set is determined automatically from the value of the SpecificCharacterSet (0008,0005) element. The defined terms for the destination character set can be found in the DICOM standard, e.g. "ISO_IR 100" for ISO 8859-1 (Latin 1) or "ISO_IR 192" for Unicode in UTF-8. An empty string denotes the default character repertoire, which is ASCII (7-bit). NB: In case of a DICOMDIR, the SpecificCharacterSet in the main dataset is neither checked nor updated, since the Basic Directory IOD has no SOP Common Module.

Parameters:

toCharset	name of the destination character set used for the conversion. Only a single value is permitted (i.e. no code extensions).
transliterate	mode specifying whether a character that cannot be represented in the destination character encoding is approximated through one or more characters that look similar to the original one

Returns:

status, EC_Normal if successful, an error code otherwise

virtual OFCondition DcmFileFormat::convertCharacterSet

(

DcmSpecificCharacterSet &

converter

)

[virtual]

convert all element values that are contained in the dataset and that are affected by SpecificCharacterSet from the currently selected source character set to the currently selected destination character set

Parameters:

converter

character set converter to be used to convert the element values

Returns:

status, EC_Normal if successful, an error code otherwise

Reimplemented from DcmSequenceOfItems.

virtual OFCondition DcmFileFormat::convertToUTF8

(

)

[virtual]

convert all element values that are contained in the dataset and that are affected by SpecificCharacterSet to UTF-8 (Unicode).

The value of the SpecificCharacterSet (0008,0005) element is updated, set or deleted automatically if needed. The transliteration mode is disabled - see convertCharacterSet(). NB: In case of a DICOMDIR, the SpecificCharacterSet in the main dataset is neither checked nor updated, since the Basic Directory IOD has no SOP Common Module.

Returns:

status, EC_Normal if successful, an error code otherwise

virtual OFCondition DcmFileFormat::copyFrom

(

const DcmObject &

rhs

)

[virtual]

Virtual object copying.

This method can be used for DcmObject and derived classes to get a deep copy of an object. Internally the assignment operator is called if the given DcmObject parameter is of the same type as "this" object instance. If not, an error is returned. This function permits copying an object by value in a virtual way which therefore is different to just calling the assignment operator of DcmElement which could result in slicing the object.

Parameters:

rhs	- [in] The instance to copy from. Has to be of the same class type as "this" object

Returns:

EC_Normal if copying was successful, error otherwise

Reimplemented from DcmSequenceOfItems.

DcmDataset* DcmFileFormat::getAndRemoveDataset

(

)

get dataset part and remove it from the fileformat.

Please note that a new, initially empty dataset is also added to the fileformat.

Returns:

reference to previously stored but now removed dataset

DcmDataset* DcmFileFormat::getDataset

(

)

get dataset part of the fileformat

Returns:

reference to internally stored dataset

DcmMetaInfo* DcmFileFormat::getMetaInfo

(

)

get file meta information header part of the fileformat

Returns:

reference to internally stored file meta information header

E_FileReadMode DcmFileFormat::getReadMode

(

)

const [inline]

get current file read mode.

This mode specifies whether a file is read as a fileformat or dataset (without meta header). In addition, the reading can be restricted to DICOM files only.

Returns:

file read mode

OFBool DcmFileFormat::hasRepresentation	(	const E_TransferSyntax	repType,
		const DcmRepresentationParameter *	repParam
	)		[inline]

check if all PixelData elements in this dataset have a representation conforming to the given transfer syntax and representation parameters (see dcpixel.h for definition of "conforming").

Parameters:

repType	desired transfer syntax
repParam	desired representation parameter (e.g. quality factor for lossy compression)

Returns:

true if all pixel elements have the desired representation, false otherwise

virtual DcmEVR DcmFileFormat::ident

(

)

const [virtual]

get type identifier

Returns:

type identifier of this class (EVR_fileFormat)

Reimplemented from DcmSequenceOfItems.

virtual OFCondition DcmFileFormat::insertItem	(	DcmItem *	item,
		const unsigned long	where = DCM_EndOfListIndex
	)		[virtual]

method inherited from base class that shall not be used for instances of this class.

Method immediately returns with error code.

Parameters:

item	item
where	where

Returns:

always returns EC_IllegalCall.

virtual OFCondition DcmFileFormat::loadFile	(	const OFFilename &	fileName,
		const E_TransferSyntax	readXfer = EXS_Unknown,
		const E_GrpLenEncoding	groupLength = EGL_noChange,
		const Uint32	maxReadLength = DCM_MaxReadLength,
		const E_FileReadMode	readMode = ERM_autoDetect
	)		[virtual]

load object from a DICOM file.

This method supports DICOM objects stored as a file (with meta header) or as a dataset (without meta header). By default, the presence of a meta header is detected automatically.

Parameters:

fileName	name of the file to load (may contain wide chars if support enabled). Since there are various constructors for the OFFilename class, a "char *", "OFString" or "wchar_t *" can also be passed directly to this parameter.
readXfer	transfer syntax used to read the data (auto detection if EXS_Unknown)
groupLength	flag, specifying how to handle the group length tags
maxReadLength	maximum number of bytes to be read for an element value. Element values with a larger size are not loaded until their value is retrieved (with getXXX()) or loadAllDataElements() is called.
readMode	read file with or without meta header, i.e. as a fileformat or a dataset. Use ERM_fileOnly in order to force the presence of a meta header.

Returns:

status, EC_Normal if successful, an error code otherwise

static E_TransferSyntax DcmFileFormat::lookForXfer

(

DcmMetaInfo *

metainfo

)

[static, private]

read DCM_TransferSyntaxUID from meta header dataset and return as E_TransferSyntax value

Parameters:

metainfo

meta-header dataset

Returns:

E_TransferSyntax value for DCM_TransferSyntaxUID, EXS_Unknown if not found or unknown

DcmFileFormat& DcmFileFormat::operator=

(

const DcmFileFormat &

obj

)

assignment operator

Parameters:

obj	fileformat to be assigned/copied

Returns:

reference to this object

virtual void DcmFileFormat::print	(	STD_NAMESPACE ostream &	out,
		const size_t	flags = 0,
		const int	level = 0,
		const char *	pixelFileName = NULL,
		size_t *	pixelCounter = NULL
	)		[virtual]

print meta header and dataset to a stream

Parameters:

out	output stream
flags	optional flag used to customize the output (see DCMTypes::PF_xxx)
level	current level of nested items. Used for indentation.
pixelFileName	optional filename used to write the raw pixel data file
pixelCounter	optional counter used for automatic pixel data filename creation

Reimplemented from DcmSequenceOfItems.

virtual OFCondition DcmFileFormat::read	(	DcmInputStream &	inStream,
		const E_TransferSyntax	xfer = EXS_Unknown,
		const E_GrpLenEncoding	glenc = EGL_noChange,
		const Uint32	maxReadLength = DCM_MaxReadLength
	)		[virtual]

read object from a stream.

Parameters:

inStream	DICOM input stream
xfer	transfer syntax to use when parsing
glenc	handling of group length parameters
maxReadLength	attribute values larger than this value are skipped while parsing and read later upon first access if the stream type supports this.

Returns:

EC_Normal if successful, an error code otherwise

Reimplemented from DcmSequenceOfItems.

virtual DcmItem* DcmFileFormat::remove

(

const unsigned long

num

)

[virtual]

method inherited from base class that shall not be used for instances of this class.

Method immediately returns.

Parameters:

num

num

Returns:

always returns NULL.

Reimplemented from DcmSequenceOfItems.

virtual DcmItem* DcmFileFormat::remove

(

DcmItem *

item

)

[virtual]

method inherited from base class that shall not be used for instances of this class.

Method immediately returns.

Parameters:

item

item

Returns:

always returns NULL.

Reimplemented from DcmSequenceOfItems.

void DcmFileFormat::removeAllButCurrentRepresentations

(

)

[inline]

removes all but the current representation in all pixel data elements.

Makes the current representation original.

virtual OFCondition DcmFileFormat::saveFile	(	const OFFilename &	fileName,
		const E_TransferSyntax	writeXfer = EXS_Unknown,
		const E_EncodingType	encodingType = EET_UndefinedLength,
		const E_GrpLenEncoding	groupLength = EGL_recalcGL,
		const E_PaddingEncoding	padEncoding = EPD_noChange,
		const Uint32	padLength = 0,
		const Uint32	subPadLength = 0,
		const E_FileWriteMode	writeMode = EWM_fileformat
	)		[virtual]

save object to a DICOM file.

Parameters:

fileName	name of the file to save (may contain wide chars if support enabled). Since there are various constructors for the OFFilename class, a "char *", "OFString" or "wchar_t *" can also be passed directly to this parameter.
writeXfer	transfer syntax used to write the data (EXS_Unknown means use current)
encodingType	flag, specifying the encoding with undefined or explicit length
groupLength	flag, specifying how to handle the group length tags
padEncoding	flag, specifying how to handle the padding tags
padLength	number of bytes used for the dataset padding (has to be an even number)
subPadLength	number of bytes used for the item padding (has to be an even number)
writeMode	write file with or without meta header. Also allows for updating the information in the file meta information header.

Returns:

status, EC_Normal if successful, an error code otherwise

void DcmFileFormat::setReadMode

(

const E_FileReadMode

readMode

)

[inline]

set current file read mode.

This mode specifies whether a file is read as a fileformat or dataset (without meta header). In addition, the reading can be restricted to DICOM files only.

Parameters:

readMode

file read mode to be set

virtual OFCondition DcmFileFormat::validateMetaInfo	(	const E_TransferSyntax	oxfer,
		const E_FileWriteMode	writeMode = EWM_fileformat
	)		[virtual]

make sure that all data elements of the file meta information header are existent in metainfo and contain correct values.

Parameters:

oxfer	the transfer syntax which shall be used
writeMode	flag indicating whether to update the file meta information or not

virtual OFCondition DcmFileFormat::write	(	DcmOutputStream &	outStream,
		const E_TransferSyntax	oxfer,
		const E_EncodingType	enctype,
		DcmWriteCache *	wcache
	)		[virtual]

write fileformat to a stream

Parameters:

outStream	DICOM output stream
oxfer	output transfer syntax
enctype	encoding types (undefined or explicit length)
wcache	pointer to write cache object, may be NULL

Returns:

status, EC_Normal if successful, an error code otherwise

Reimplemented from DcmSequenceOfItems.

virtual OFCondition DcmFileFormat::write	(	DcmOutputStream &	outStream,
		const E_TransferSyntax	oxfer,
		const E_EncodingType	enctype,
		DcmWriteCache *	wcache,
		const E_GrpLenEncoding	glenc,
		const E_PaddingEncoding	padenc = EPD_noChange,
		const Uint32	padlen = 0,
		const Uint32	subPadlen = 0,
		Uint32	instanceLength = 0,
		const E_FileWriteMode	writeMode = EWM_fileformat
	)		[virtual]

write object to a stream (abstract)

Parameters:

outStream	DICOM output stream
oxfer	output transfer syntax
enctype	encoding types (undefined or explicit length)
wcache	pointer to write cache object, may be NULL
glenc	group length encoding
padenc	dataset trailing padding encoding
padlen	padding structure size for complete file
subPadlen	padding structure set for sequence items
instanceLength	number of extra bytes added to the item/dataset length used when computing the padding. This parameter is for instance used to pass the length of the file meta information header from the DcmFileFormat to the DcmDataset object.
writeMode	write file with or without meta header. Also allows for updating the information in the file meta information header.

Returns:

status, EC_Normal if successful, an error code otherwise

virtual OFCondition DcmFileFormat::writeXML	(	STD_NAMESPACE ostream &	out,
		const size_t	flags = 0
	)		[virtual]

write object in XML format.

The XML declaration (e.g. <?xml version="1.0"?>) is not written by this function.

Parameters:

out	output stream to which the XML document is written
flags	optional flag used to customize the output (see DCMTypes::XF_xxx)

Returns:

status, EC_Normal if successful, an error code otherwise

Reimplemented from DcmSequenceOfItems.

---

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

• dcmdata/include/dcmtk/dcmdata/dcfilefo.h