DcmFileFormat Class Reference

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

Inheritance diagram for DcmFileFormat:

DcmSequenceOfItems DcmElement DcmObject 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 char *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 char *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.

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)

Definition at line 48 of file dcfilefo.h.

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

DcmFileFormat& DcmFileFormat::operator= ( const DcmFileFormat &  obj  ) 

assignment operator

Parameters:
obj fileformat to be assigned/copied
Returns:
reference to this object

virtual DcmObject* DcmFileFormat::clone (  )  const [inline, virtual]

clone method

Returns:
deep copy of this object

Reimplemented from DcmSequenceOfItems.

Definition at line 81 of file dcfilefo.h.

References DcmFileFormat().

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.

virtual DcmEVR DcmFileFormat::ident (  )  const [virtual]

get type identifier

Returns:
type identifier of this class (EVR_fileFormat)

Reimplemented from DcmSequenceOfItems.

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

DcmMetaInfo* DcmFileFormat::getMetaInfo (  ) 

get file meta information header part of the fileformat

Returns:
reference to internally stored file meta information header

DcmDataset* DcmFileFormat::getDataset (  ) 

get dataset part of the fileformat

Returns:
reference to internally stored dataset

Referenced by chooseRepresentation(), hasRepresentation(), removeAllButCurrentRepresentations(), and removeAllButOriginalRepresentations().

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

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.

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

virtual OFCondition DcmFileFormat::loadFile ( const char *  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
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

virtual OFCondition DcmFileFormat::saveFile ( const char *  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
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

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.

Definition at line 286 of file dcfilefo.h.

References DcmDataset::chooseRepresentation(), and getDataset().

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

Definition at line 299 of file dcfilefo.h.

References getDataset(), and DcmDataset::hasRepresentation().

void DcmFileFormat::removeAllButCurrentRepresentations (  )  [inline]

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

Makes the current representation original.

Definition at line 315 of file dcfilefo.h.

References getDataset(), and DcmDataset::removeAllButCurrentRepresentations().

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

Definition at line 325 of file dcfilefo.h.

References FileReadMode.

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

Definition at line 335 of file dcfilefo.h.

References FileReadMode.

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

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

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

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

Generated on 6 Jan 2011 for OFFIS DCMTK Version 3.6.0 by Doxygen 1.5.1