Logo Search packages:      
Sourcecode: dcmtk version File versions

dcddirif.h

/*
 *
 *  Copyright (C) 2002-2004, OFFIS
 *
 *  This software and supporting documentation were developed by
 *
 *    Kuratorium OFFIS e.V.
 *    Healthcare Information and Communication Systems
 *    Escherweg 2
 *    D-26121 Oldenburg, Germany
 *
 *  THIS SOFTWARE IS MADE AVAILABLE,  AS IS,  AND OFFIS MAKES NO  WARRANTY
 *  REGARDING  THE  SOFTWARE,  ITS  PERFORMANCE,  ITS  MERCHANTABILITY  OR
 *  FITNESS FOR ANY PARTICULAR USE, FREEDOM FROM ANY COMPUTER DISEASES  OR
 *  ITS CONFORMITY TO ANY SPECIFICATION. THE ENTIRE RISK AS TO QUALITY AND
 *  PERFORMANCE OF THE SOFTWARE IS WITH THE USER.
 *
 *  Module:  dcmdata
 *
 *  Author:  Joerg Riesmeier
 *
 *  Purpose: Interface class for simplified creation of a DICOMDIR
 *
 *  Last Update:      $Author: joergr $
 *  Update Date:      $Date: 2004/02/13 17:36:46 $
 *  CVS/RCS Revision: $Revision: 1.3 $
 *  Status:           $State: Exp $
 *
 *  CVS/RCS Log at end of file
 *
 */


#ifndef DCDDIRIF_H
#define DCDDIRIF_H

#include "osconfig.h"

#include "dcdicdir.h"


/*-----------------------------------*
 *  contant declarations and macros  *
 *-----------------------------------*/

// default fileset ID
#define DEFAULT_FILESETID "DCMTK_MEDIA_DEMO"
// default specific character set of fileset descriptor file
#define DEFAULT_DESCRIPTOR_CHARSET "ISO_IR 100"


/*----------------------*
 *  class declarations  *
 *----------------------*/

/** Abstract interface to plugable image support for the DICOMDIR class.
 *  This is an abstract base class used as an interface to access DICOM
 *  images from the DicomDirInterface.  The implementation can be found
 *  in dcmjpeg/libsrc/ddpiimpl.cc (incl. JPEG support).
 */
00061 class DicomDirImagePlugin
{
  public:

    /** destructor (virtual)
     */
00067     virtual ~DicomDirImagePlugin() {}

    /** scale image (pixel data) to specified size
     *  @param srcData pointer to 8 bit source pixel data (original image)
     *  @param srcWidth width of the source image
     *  @param srcHeight height of the source image
     *  @param dstData pointer to 8 bit destination pixel data (scaled image).
     *    This array needs to be allocated prior to calling this function.
     *  @param dstWidth width of the destination image
     *  @param dstHeight height of the destination image
     *  @return OFTrue if successful, OFFalse otherwise
     */
    virtual OFBool scaleData(const Uint8 *srcData,
                             const unsigned int srcWidth,
                             const unsigned int srcHeight,
                             Uint8 *dstData,
                             const unsigned int dstWidth,
                             const unsigned int dstHeight) const = 0;

    /** scale image (from DICOM dataset) to specified size
     *  @param dataset DICOM dataset where the pixel data is stored (original image)
     *  @param pixel pointer to 8 bit destination pixel data (scaled image).
     *    This array needs to be allocated prior to calling this function.
     *  @param count number of bytes allocated for the 'pixel' array
     *  @param frame index of the frame to be scaled (0..n-1)
     *  @param width width of the destination image
     *  @param height height of the destination image
     *  @return OFTrue if successful, OFFalse otherwise
     */
    virtual OFBool scaleImage(DcmItem *dataset,
                              Uint8 *pixel,
                              const unsigned long count,
                              const unsigned long frame,
                              const unsigned int width,
                              const unsigned int height) const = 0;

  protected:

    /** constructor (protected)
     */
00107     DicomDirImagePlugin() {}
};


/** An interface class for simplified creation of a DICOMDIR
 */
00113 class DicomDirInterface
{

  public:

    /** list of supported media storage application profiles
     */
00120     enum E_ApplicationProfile
    {
        /// like GeneralPurpose without restricting the transfer syntax (also compressed files)
00123         AP_None,
        /// General Purpose Interchange on CD-R or DVD-RAM Media (STD-GEN-CD/DVD-RAM)
00125         AP_GeneralPurpose,
        /// default application profile: GeneralPurpose
00127         AP_Default = AP_GeneralPurpose,
        /// Basic Cardiac X-Ray Angiographic Studies on CD-R Media (STD-XABC-CD)
00129         AP_BasicCardiac,
        /// 1024 X-Ray Angiographic Studies on CD-R Media (STD-XA1K-CD)
00131         AP_XrayAngiographic,
        /// CT/MR Studies (STD-CTMR-xxxx)
00133         AP_CTandMR,
        /// Ultrasound Single Frame for Image Display (STD-US-ID-SF-xxxx)
00135         AP_UltrasoundIDSF,
        /// Ultrasound Single Frame with Spatial Calibration (STD-US-SC-SF-xxxx)
00137         AP_UltrasoundSCSF,
        /// Ultrasound Single Frame with Combined Calibration (STD-US-CC-SF-xxxx)
00139         AP_UltrasoundCCSF,
        /// Ultrasound Single & Multi-Frame for Image Display (STD-US-ID-MF-xxxx)
00141         AP_UltrasoundIDMF,
        /// Ultrasound Single & Multi-Frame with Spatial Calibration (STD-UD-SC-MF-xxxx)
00143         AP_UltrasoundSCMF,
        /// Ultrasound Single & Multi-Frame with Combined Calibration (STD-UD-CC-MF-xxxx)
00145         AP_UltrasoundCCMF,
        /// 12-lead ECG Interchange on Diskette (STD-WVFM-ECG-FD)
00147         AP_TwelveLeadECG,
        /// Hemodynamic Waveform Interchange on Diskette (STD-WVFM-HD-FD)
00149         AP_HemodynamicWaveform
    };

    /** constructor (default).
     *  No DICOMDIR object is created by default (see methods createNewDicomDir and
     *  appendToDicomDir).
     */
    DicomDirInterface();

    /** destructor (virtual).
     *  Free all memory allocated by this class.
     */
    virtual ~DicomDirInterface();

    /** reset the object to its initial state.
     *  That means e.g. free memory.
     */
    void cleanup();

    /** check whether current DICOMDIR is valid.
     *  That means e.g. that it can be written to a file.
     *  @return OFTrue if DICOMDIR is valid, OFFalse otherwise
     */
    OFBool isDicomDirValid() const;

    /** create a new DICOMDIR object.
     *  This function replaces any previously existing DICOMDIR file with the specified
     *  'filename'.  If the backup mode (see 'enableBackupMode') is enabled a backup
     *  copy ('filename' + ".BAK") is created from the existing file and automatically
     *  deleted after the new file has been written without any errors.
     *  @param profile media storage application profile to be used for the DICOMDIR
     *  @param filename name of the DICOMDIR file to be created (default: 'DICOMDIR').
     *    The filename may include a fully qualified pathname.
     *  @param filesetID value of the attribute FileSetID (default: 'DCMTK_MEDIA_DEMO')
     *  @return EC_Normal upon success, an error code otherwise
     */
    OFCondition createNewDicomDir(const E_ApplicationProfile profile = AP_GeneralPurpose,
                                  const char *filename = DEFAULT_DICOMDIR_NAME,
                                  const char *filesetID = DEFAULT_FILESETID);

    /** create a DICOMDIR object based on an existing DICOMDIR file.
     *  This function can be used to append new entries to an existing DICOMDIR file.
     *  If the backup mode (see 'enableBackupMode') is enabled a backup copy ('filename'
     *  + ".BAK") is created from the existing file and automatically deleted after the
     *  new file has been written without any errors.
     *  @param profile media storage application profile to be used for the DICOMDIR.
     *    NB: The same profile should be used as for the creation of the DICOMDIR file.
     *  @param filename name of the DICOMDIR file to be appended.  The filename may
     *    include a fully qualified pathname.
     *  @return EC_Normal upon success, an error code otherwise
     */
    OFCondition appendToDicomDir(const E_ApplicationProfile profile,
                                 const char *filename);

    /** write the current DICOMDIR object to file.
     *  NB: The filename has already been specified for the object creation (see above).
     *  @param encodingType flag, specifying the encoding with undefined or explicit length
     *  @param groupLength flag, specifying how to handle the group length tags
     *  @return EC_Normal upon success, an error code otherwise
     */
    OFCondition writeDicomDir(const E_EncodingType encodingType = EET_UndefinedLength,
                              const E_GrpLenEncoding groupLength = EGL_withoutGL);

    /** check whether specified filename is valid. i.e. conforms to the DICOM standard
     *  requirements (length, number of component and proper characters).  This function
     *  is called automatically for the following methods: checkDicomFile(), addDicomFile()
     *  and setFilesetDescriptor().  So usually there's no need to call it manually
     *  (especially not in addition to the above mentioned methods).
     *  @param filename filename to be checked for standard conformance
     *  @param allowEmpty empty filename (zero length) allowed if OFTrue
     *  @return OFTrue if filename is valid, OFFalse otherwise
     */
    OFBool isFilenameValid(const char *filename,
                           const OFBool allowEmpty = OFFalse);

    /** check whether given charset identifier is valid.
     *  Valid character sets are (see DICOM PS3.3 for details): ISO_IR 100, ISO_IR 101,
     *  ISO_IR 109, ISO_IR 110, ISO_IR 144, ISO_IR 127, ISO_IR 126, ISO_IR 138, ISO_IR 148,
     *  ISO_IR 166, ISO_IR 13.
     *  @param charset character set identifier to be checked
     *  @return OFTrue if charset is valid, OFFalse otherwise
     */
    OFBool isCharsetValid(const char *charset);

    /** check whether specified DICOM file is suitable to be included into the DICOMDIR.
     *  This method loads the given file and checks whether it conforms to the current
     *  application profile.  Since this check is also performed by addDicomFile() there
     *  is usually no need to call this method directly.
     *  @param filename name of the DICOM file to be checked
     *  @param directory directory where the DICOM file is stored (optional).
     *    This parameter might be useful in cases where the DICOM file is not (yet)
     *    stored in the final directory (i.e. "relative" to the DICOMDIR location).
     *  @return EC_Normal upon success, an error code otherwise
     */
    OFCondition checkDicomFile(const char *filename,
                               const char *directory = NULL);

    /** add specified DICOM file to the current DICOMDIR.
     *  This method loads the given file, checks whether it conforms to the current
     *  application profile and finally adds it to the DICOMDIR (in case of conformance).
     *  @param filename name of the DICOM file to be added
     *  @param directory directory where the DICOM file is stored (optional).
     *    This parameter might be useful in cases where the DICOM file is not (yet)
     *    stored in the final directory (i.e. "relative" to the DICOMDIR location).
     *  @return EC_Normal upon success, an error code otherwise
     */
    OFCondition addDicomFile(const char *filename,
                             const char *directory = NULL);

    /** set the fileset descriptor file ID and character set.
     *  Prior to any internal modification both 'filename' and 'charset' are checked
     *  using the above checking routines.  Existence of 'filename' is not checked.
     *  NB: Requires a DICOMDIR to exist (see createNewDicomDir and appendToDicomDir).
     *  @param filename name of the fileset descriptor file to be set
     *  @param charset character set of the fileset descriptor file to be set.
     *    default: ISO Latin 1 ("ISO_IR 100"), use NULL or empty string to omit value.
     *  @return EC_Normal upon success, an error code otherwise
     */
    OFCondition setFilesetDescriptor(const char *filename,
                                     const char *charset = DEFAULT_DESCRIPTOR_CHARSET);

    /** set preferred size of the icon images.
     *  NB: some application profiles require a particicular icon size.
     *      In those cases this manual setting is implicitly ignored.
     *  @param size size of the icon images in pixels (1..256, initial: 64)
     *  @return EC_Normal upon success, an error code otherwise
     */
    OFCondition setIconSize(const unsigned int size);

    /** set filename prefix for alternative icon images.
     *  If non-empty the filename prefix is used to create the icon image from an
     *  externally stored PGM (portable gray map, 8 bit binary) file instead of the
     *  DICOM image file.  The PGM filename is: 'prefix' + 'dicom_filename'.  The
     *  image does not need to have the correct size as it is scaled automatically.
     *  @param prefix filename prefix (NULL to disable = default)
     *  @return always returns EC_Normal
     */
    OFCondition setIconPrefix(const char *prefix);

    /** set filename of default icon image.
     *  For cases that the icon image cannot be created (neither from PGM nor from
     *  DICOM file, respectively) a default icon (8 bit binary PGM) can be specified.
     *  If this image also fails to load a black icon (filled with zeros) is used.
     *  @param filename name of the default PGM file
     *  @return always returns EC_Normal
     */
    OFCondition setDefaultIcon(const char *filename);

    /** get current status of the verbose mode
     *  @return OFTrue if mode is enabled, OFFalse otherwise
     */
00300     OFBool verboseMode() const
    {
        return VerboseMode;
    }

    /** get current status of the "abort on first error" mode.
     *  See enableAbortMode() for more details.
     *  @return OFTrue if mode is enabled, OFFalse otherwise
     */
00309     OFBool abortMode() const
    {
        return AbortMode;
    }

    /** get current status of the "map filenames" mode.
     *  See enableMapFilenamesMode() for more details.
     *  @return OFTrue if mode is enabled, OFFalse otherwise
     */
00318     OFBool mapFilenamesMode() const
    {
        return MapFilenamesMode;
    }

    /** get current status of the "invent missing values" mode.
     *  See enableInventMode() for more details.
     *  @return OFTrue if mode is enabled, OFFalse otherwise
     */
00327     OFBool inventMode() const
    {
        return InventMode;
    }

    /** get current status of the "invent missing patient ID" mode.
     *  See enableInventPatientIDMode() for more details.
     *  @return OFTrue if mode is enabled, OFFalse otherwise
     */
00336     OFBool inventPatientIDMode() const
    {
        return InventPatientIDMode;
    }

    /** get current status of the "create icon images" mode.
     *  See enableIconImageMode() for more details.
     *  @return OFTrue if mode is enabled, OFFalse otherwise
     */
00345     OFBool iconImageMode() const
    {
        return IconImageMode;
    }

    /** get current status of the "create backup" mode.
     *  See enableBackupMode() for more details.
     *  @return OFTrue if mode is enabled, OFFalse otherwise
     */
00354     OFBool backupMode() const
    {
        return BackupMode;
    }

    /** get current status of the "resolution check" mode.
     *  See enableResolutionCheck() for more details.
     *  @return OFTrue if check is enabled, OFFalse otherwise
     */
00363     OFBool resolutionCheck() const
    {
        return ResolutionCheck;
    }

    /** get current status of the "consistency check" mode.
     *  See enableConsistencyCheck() for more details.
     *  @return OFTrue if check is enabled, OFFalse otherwise
     */
00372     OFBool consistencyCheck() const
    {
        return ConsistencyCheck;
    }

    /** enable/disable the verbose mode.
     *  If the mode is enabled messages like "creating DICOMDIR file ..." or
     *  "adding file ..." are reported to the log stream (see setLogStream).
     *  Default: off, no messages
     *  @param newMode enable mode if OFTrue, disable if OFFalse
     *  @return previously stored value
     */
    OFBool enableVerboseMode(const OFBool newMode = OFTrue);

    /** enable/disable the "abort on first error" mode.
     *  If the mode is enabled addDicomFile() reports an error message and
     *  returns with an error status code if something went wrong.
     *  Default: off, do not abort
     *  @param newMode enable mode if OFTrue, disable if OFFalse
     *  @return previously stored value
     */
    OFBool enableAbortMode(const OFBool newMode = OFTrue);

    /** enable/disable the "map filenames" mode.
     *  If the mode is enabled filenames are automatically mapped to DICOM format
     *  (convert lower case to upper case characters and remove trailing period).
     *  Default: off, do not map filenames
     *  @param newMode enable mode if OFTrue, disable if OFFalse
     *  @return previously stored value
     */
    OFBool enableMapFilenamesMode(const OFBool newMode = OFTrue);

    /** enable/disable the "invent missing values" mode.
     *  If the mode is enabled required DICOMDIR attributes (type 1) are
     *  invented when missing in the DICOM file.
     *  Default: off, do not invent attribute values
     *  @param newMode enable mode if OFTrue, disable if OFFalse
     *  @return previously stored value
     */
    OFBool enableInventMode(const OFBool newMode = OFTrue);

    /** enable/disable the "invent new patient ID" mode.
     *  If the mode is enabled a new PatientID is invented in case of
     *  inconsistant PatientsName attributes, i.e. when different patients
     *  share the same ID.
     *  Default: off, do not invent new patient ID
     *  @param newMode enable mode if OFTrue, disable if OFFalse
     *  @return previously stored value
     */
    OFBool enableInventPatientIDMode(const OFBool newMode = OFTrue);

    /** enable/disable the "create icon images" mode.
     *  If the mode is enabled icon images are created for each IMAGE record.
     *  Please note that particular application profiles (e.g. Basic Cardiac)
     *  require an icon images to be present.  Therefore, this mode does not
     *  affect the icon images creation of such profiles.
     *  Default: off, do not create (optional) icon images
     *  @param newMode enable mode if OFTrue, disable if OFFalse
     *  @return previously stored value
     */
    OFBool enableIconImageMode(const OFBool newMode = OFTrue);

    /** disable/enable the "create backup file" mode.
     *  If this mode is disabled no backup file of an existing DICOMDIR is created.
     *  However, when appending new files to an existing DICOMDIR a _temporary_
     *  backup file "<dicomdir>.$$$" is always created.
     *  Default: on, create a backup file "<dicomdir>.BAK"
     *  @param newMode disable mode if OFFalse, enable if OFTrue
     *  @return previously stored value
     */
    OFBool disableBackupMode(const OFBool newMode = OFFalse);

    /** disable/enable the "image resolution check".
     *  If this mode is disabled the image resolution is not check for compliance
     *  with the selected application profile.  Please use this switch with care
     *  since the resulting DICOMDIR will probably violate the rules for the
     *  selected application profile.
     *  Default: on, check image resolution
     *  @param newMode disable check if OFFalse, enable if OFTrue
     *  @return previously stored value
     */
    OFBool disableResolutionCheck(const OFBool newMode = OFFalse);

    /** disable/enable the "consistency check".
     *  If this mode is disabled the consistency of newly added records with
     *  already existing ones is not checked (see 'warnAboutInconsistantAttributes'
     *  for details).
     *  Default: on, perform consistency check
     *  @param newMode disable check if OFFalse, enable if OFTrue
     *  @return previously stored value
     */
    OFBool disableConsistencyCheck(const OFBool newMode = OFFalse);

    /** add pluggable image support.
     *  NB: This plugin is required to create icon images from DICOM files!
     *  @param plugin pointer to an instance of the plugin implementation.
     *    See class DicomDirImageImplementation (dcmjpeg/include/ddpiimpl.h).
     *  @return OFTrue if successful, OFFalse otherwise
     */
    OFBool addImageSupport(DicomDirImagePlugin *plugin);

    /** set the log stream.
     *  The log stream is used to report any warnings, debug and error messages.
     ** @param stream pointer to the log stream (initial: NULL = no messages)
     */
    void setLogStream(OFConsole *stream);

    /* -- static function -- */

    /** get name/identifier associated with the given application profile
     *  @param profile media storage application profile
     *  @return name of the application profile (e.g. "STD-GEN-CD/DVD-RAM")
     */
    static const char *getProfileName(const E_ApplicationProfile profile);


  protected:

    /** select given application profile
     *  @param profile storage media application profile to be selected
     *  @return EC_Normal upon success, an error code otherwise
     */
    OFCondition selectApplicationProfile(const E_ApplicationProfile profile);

    /** load and check DICOM file regarding the current application profile
     *  @param filename name of the DICOM file to be checked
     *  @param directory directory where the DICOM file is stored (optional)
     *  @param fileformat object in which the loaded data is stored
     *  @return EC_Normal upon success, an error code otherwise
     */
    OFCondition loadAndCheckDicomFile(const char *filename,
                                      const char *directory,
                                      DcmFileFormat &fileformat);

    /** check SOP class and transfer syntax for compliance with current profile
     *  @param metainfo object where the DICOM file meta information is stored
     *  @param dataset object where the DICOM dataset is stored
     *  @param filename name of the DICOM file to be checked
     *  @return EC_Normal upon success, an error code otherwise
     */
    OFCondition checkSOPClassAndXfer(DcmMetaInfo *metainfo,
                                     DcmItem *dataset,
                                     const char *filename);

    /** check attributes for compliance with Basic Cardiac application profile
     *  @param dataset object where the DICOM dataset is stored
     *  @param filename name of the DICOM file to be checked
     *  @return EC_Normal upon success, an error code otherwise
     */
    OFCondition checkBasicCardiacAttributes(DcmItem *dataset,
                                            const char *filename);

    /** check attributes for compliance with X-ray Angiography application profile
     *  @param dataset object where the DICOM dataset is stored
     *  @param sopClass SOP class of the DICOM data to be checked
     *  @param filename name of the DICOM file to be checked
     *  @return EC_Normal upon success, an error code otherwise
     */
    OFCondition checkXrayAngiographicAttributes(DcmItem *dataset,
                                                const OFString &sopClass,
                                                const char *filename);

    /** check attributes for compliance with CT and MR application profile
     *  @param dataset object where the DICOM dataset is stored
     *  @param sopClass SOP class of the DICOM data to be checked
     *  @param filename name of the DICOM file to be checked
     *  @return EC_Normal upon success, an error code otherwise
     */
    OFCondition checkCTandMRAttributes(DcmItem *dataset,
                                       const OFString &sopClass,
                                       const char *filename);

    /** check attributes for compliance with Ultrasound application profiles
     *  @param dataset object where the DICOM dataset is stored
     *  @param transferSyntax transfer syntax of the DICOM data to be checked
     *  @param filename name of the DICOM file to be checked
     *  @return EC_Normal upon success, an error code otherwise
     */
    OFCondition checkUltrasoundAttributes(DcmItem *dataset,
                                          const OFString &transferSyntax,
                                          const char *filename);

    /** check attributes for comliance with current application profile
     *  @param metainfo object where the DICOM file meta information is stored
     *  @param dataset object where the DICOM dataset is stored
     *  @param filename name of the DICOM file to be checked
     *  @return EC_Normal upon success, an error code otherwise
     */
    OFCondition checkMandatoryAttributes(DcmMetaInfo *metainfo,
                                         DcmItem *dataset,
                                         const char *filename);

    /** check whether given DICOMDIR record matches dataset.
     *  The check depends on the record type and is performed mainly based on
     *  the unique key defined for the particular record type (e.g. SOPInstanceUID
     *  for IMAGE records).  For PATIENT records the PatientsName may also be used
     *  if the PatientID is absent.
     *  @param record DICOMDIR record to be checked
     *  @param dataset DICOM dataset of the current file
     *  @return OFTrue if record matches, OFFalse otherwise
     */
    OFBool recordMatchesDataset(DcmDirectoryRecord *record,
                                DcmItem *dataset);

    /** search for a given DICOMDIR record
     *  @param parent higher-level structure where the records are stored
     *  @param recordType type of DICOMDIR record to be searched for
     *  @param dataset DICOM dataset of the current file
     *  @return pointer to record if found, NULL otherwise
     */
    DcmDirectoryRecord *findExistingRecord(DcmDirectoryRecord *parent,
                                           const E_DirRecType recordType,
                                           DcmItem* dataset);

    /** create new patient record and copy required values from dataset
     *  @param dataset DICOM dataset of the current file
     *  @param sourceFilename name of the source DICOM file
     *  @return pointer to new record, NULL if an error occurred
     */
    DcmDirectoryRecord *buildPatientRecord(DcmItem *dataset,
                                           const OFString &sourceFilename);

    /** create new study record and copy required values from dataset
     *  @param dataset DICOM dataset of the current file
     *  @param sourceFilename name of the source DICOM file
     *  @return pointer to new record, NULL if an error occurred
     */
    DcmDirectoryRecord *buildStudyRecord(DcmItem *dataset,
                                         const OFString &sourceFilename);

    /** create new series record and copy required values from dataset
     *  @param dataset DICOM dataset of the current file
     *  @param sourceFilename name of the source DICOM file
     *  @return pointer to new record, NULL if an error occurred
     */
    DcmDirectoryRecord *buildSeriesRecord(DcmItem *dataset,
                                          const OFString &sourceFilename);

    /** create new overlay record and copy required values from dataset
     *  @param dataset DICOM dataset of the current file
     *  @param referencedFileID value of the Referenced File ID attribute
     *  @param sourceFilename name of the source DICOM file
     *  @return pointer to new record, NULL if an error occurred
     */
    DcmDirectoryRecord *buildOverlayRecord(DcmItem *dataset,
                                           const OFString &referencedFileID,
                                           const OFString &sourceFilename);

    /** create new modality LUT record and copy required values from dataset
     *  @param dataset DICOM dataset of the current file
     *  @param referencedFileID value of the Referenced File ID attribute
     *  @param sourceFilename name of the source DICOM file
     *  @return pointer to new record, NULL if an error occurred
     */
    DcmDirectoryRecord *buildModalityLutRecord(DcmItem *dataset,
                                               const OFString &referencedFileID,
                                               const OFString &sourceFilename);

    /** create new VOI LUT record and copy required values from dataset
     *  @param dataset DICOM dataset of the current file
     *  @param referencedFileID value of the Referenced File ID attribute
     *  @param sourceFilename name of the source DICOM file
     *  @return pointer to new record, NULL if an error occurred
     */
    DcmDirectoryRecord *buildVoiLutRecord(DcmItem *dataset,
                                          const OFString &referencedFileID,
                                          const OFString &sourceFilename);

    /** create new curve record and copy required values from dataset
     *  @param dataset DICOM dataset of the current file
     *  @param referencedFileID value of the Referenced File ID attribute
     *  @param sourceFilename name of the source DICOM file
     *  @return pointer to new record, NULL if an error occurred
     */
    DcmDirectoryRecord *buildCurveRecord(DcmItem *dataset,
                                         const OFString &referencedFileID,
                                         const OFString &sourceFilename);

    /** create new structure reporting record and copy required values from dataset
     *  @param dataset DICOM dataset of the current file
     *  @param referencedFileID value of the Referenced File ID attribute
     *  @param sourceFilename name of the source DICOM file
     *  @return pointer to new record, NULL if an error occurred
     */
    DcmDirectoryRecord *buildStructReportRecord(DcmItem *dataset,
                                                const OFString &referencedFileID,
                                                const OFString &sourceFilename);

    /** create new presentation state record and copy required values from dataset
     *  @param dataset DICOM dataset of the current file
     *  @param referencedFileID value of the Referenced File ID attribute
     *  @param sourceFilename name of the source DICOM file
     *  @return pointer to new record, NULL if an error occurred
     */
    DcmDirectoryRecord *buildPresentationRecord(DcmItem *dataset,
                                                const OFString &referencedFileID,
                                                const OFString &sourceFilename);

    /** create new waveform record and copy required values from dataset
     *  @param dataset DICOM dataset of the current file
     *  @param referencedFileID value of the Referenced File ID attribute
     *  @param sourceFilename name of the source DICOM file
     *  @return pointer to new record, NULL if an error occurred
     */
    DcmDirectoryRecord *buildWaveformRecord(DcmItem *dataset,
                                            const OFString &referencedFileID,
                                            const OFString &sourceFilename);

    /** create new RT dose record and copy required values from dataset
     *  @param dataset DICOM dataset of the current file
     *  @param referencedFileID value of the Referenced File ID attribute
     *  @param sourceFilename name of the source DICOM file
     *  @return pointer to new record, NULL if an error occurred
     */
    DcmDirectoryRecord *buildRTDoseRecord(DcmItem *dataset,
                                          const OFString &referencedFileID,
                                          const OFString &sourceFilename);

    /** create new RT structure set record and copy required values from dataset
     *  @param dataset DICOM dataset of the current file
     *  @param referencedFileID value of the Referenced File ID attribute
     *  @param sourceFilename name of the source DICOM file
     *  @return pointer to new record, NULL if an error occurred
     */
    DcmDirectoryRecord *buildRTStructureSetRecord(DcmItem *dataset,
                                                  const OFString &referencedFileID,
                                                  const OFString &sourceFilename);

    /** create new RT plan record and copy required values from dataset
     *  @param dataset DICOM dataset of the current file
     *  @param referencedFileID value of the Referenced File ID attribute
     *  @param sourceFilename name of the source DICOM file
     *  @return pointer to new record, NULL if an error occurred
     */
    DcmDirectoryRecord *buildRTPlanRecord(DcmItem *dataset,
                                          const OFString &referencedFileID,
                                          const OFString &sourceFilename);

    /** create new RT treatment record and copy required values from dataset
     *  @param dataset DICOM dataset of the current file
     *  @param referencedFileID value of the Referenced File ID attribute
     *  @param sourceFilename name of the source DICOM file
     *  @return pointer to new record, NULL if an error occurred
     */
    DcmDirectoryRecord *buildRTTreatmentRecord(DcmItem *dataset,
                                               const OFString &referencedFileID,
                                               const OFString &sourceFilename);

    /** create new stored print record and copy required values from dataset
     *  @param dataset DICOM dataset of the current file
     *  @param referencedFileID value of the Referenced File ID attribute
     *  @param sourceFilename name of the source DICOM file
     *  @return pointer to new record, NULL if an error occurred
     */
    DcmDirectoryRecord *buildStoredPrintRecord(DcmItem *dataset,
                                               const OFString &referencedFileID,
                                               const OFString &sourceFilename);

    /** create new key object doc record and copy required values from dataset
     *  @param dataset DICOM dataset of the current file
     *  @param referencedFileID value of the Referenced File ID attribute
     *  @param sourceFilename name of the source DICOM file
     *  @return pointer to new record, NULL if an error occurred
     */
    DcmDirectoryRecord *buildKeyObjectDocRecord(DcmItem *dataset,
                                                const OFString &referencedFileID,
                                                const OFString &sourceFilename);

    /** create new registration record and copy required values from dataset
     *  @param dataset DICOM dataset of the current file
     *  @param referencedFileID value of the Referenced File ID attribute
     *  @param sourceFilename name of the source DICOM file
     *  @return pointer to new record, NULL if an error occurred
     */
    DcmDirectoryRecord *buildRegistrationRecord(DcmItem *dataset,
                                                const OFString &referencedFileID,
                                                const OFString &sourceFilename);

    /** create new fiducial record and copy required values from dataset
     *  @param dataset DICOM dataset of the current file
     *  @param referencedFileID value of the Referenced File ID attribute
     *  @param sourceFilename name of the source DICOM file
     *  @return pointer to new record, NULL if an error occurred
     */
    DcmDirectoryRecord *buildFiducialRecord(DcmItem *dataset,
                                            const OFString &referencedFileID,
                                            const OFString &sourceFilename);

    /** create new raw data record and copy required values from dataset
     *  @param dataset DICOM dataset of the current file
     *  @param referencedFileID value of the Referenced File ID attribute
     *  @param sourceFilename name of the source DICOM file
     *  @return pointer to new record, NULL if an error occurred
     */
    DcmDirectoryRecord *buildRawDataRecord(DcmItem *dataset,
                                           const OFString &referencedFileID,
                                           const OFString &sourceFilename);

    /** create new spectroscopy record and copy required values from dataset
     *  @param dataset DICOM dataset of the current file
     *  @param referencedFileID value of the Referenced File ID attribute
     *  @param sourceFilename name of the source DICOM file
     *  @return pointer to new record, NULL if an error occurred
     */
    DcmDirectoryRecord *buildSpectroscopyRecord(DcmItem *dataset,
                                                const OFString &referencedFileID,
                                                const OFString &sourceFilename);

    /** create new image record and copy required values from dataset
     *  @param dataset DICOM dataset of the current file
     *  @param referencedFileID value of the Referenced File ID attribute
     *  @param sourceFilename name of the source DICOM file
     *  @return pointer to new record, NULL if an error occurred
     */
    DcmDirectoryRecord *buildImageRecord(DcmItem *dataset,
                                         const OFString &referencedFileID,
                                         const OFString &sourceFilename);

    /** create icon image from given PGM (portable gray map) file.
     *  Please note that only grayscale images in binary format are currently
     *  supported (magic word "P5").  Memory has to be allocated by the caller.
     *  @param filename name of the PGM file to be loaded
     *  @param pixel pointer to memory buffer where the pixel data are to be stored
     *  @param count number of bytes allocated for the 'pixel' memory buffer
     *  @param width width of the scaled icon image (in pixels )
     *  @param height height of the scaled icon image (in pixels)
     *  @return OFTrue if successful, OFFalse otherwise
     */
    OFBool getIconFromFile(const OFString &filename,
                           Uint8 *pixel,
                           const unsigned long count,
                           const unsigned int width,
                           const unsigned int height);

    /** create icon image from DICOM dataset.
     *  Please note that the memory buffer has to be allocated by the caller.
     *  @param dataset DICOM dataset from which the icon image is created
     *  @param pixel pointer to memory buffer where the pixel data are to be stored
     *  @param count number of bytes allocated for the 'pixel' memory buffer
     *  @param width width of the scaled icon image (in pixels )
     *  @param height height of the scaled icon image (in pixels)
     *  @return OFTrue if successful, OFFalse otherwise
     */
    OFBool getIconFromDataset(DcmItem *dataset,
                              Uint8 *pixel,
                              const unsigned long count,
                              const unsigned int width,
                              const unsigned int height);

    /** add icon image sequence to DICOMDIR record.
     *  If the icon image cannot be created from the DICOM dataset and there is no
     *  PGM file specified (neither for the particular image not a default one) a
     *  black image is used instead.
     *  @param record DICOMDIR record where the icon image is stored
     *  @param dataset DICOM dataset from which the icon image is possibly created
     *  @param size resolution of the icon image to be created (width and height)
     *  @param sourceFilename name of the source DICOM file
     *  @return EC_Normal upon success, an error code otherwise
     */
    OFCondition addIconImage(DcmDirectoryRecord *record,
                             DcmItem *dataset,
                             const unsigned int size,
                             const OFString &sourceFilename);

    /** add child record to a given parent record.
     *  A new record is only added if it does not already exist.
     *  @param parent parent record (add new record as a child of this one)
     *  @param recordType type of DICOMDIR record to be created
     *  @param dataset DICOM dataset containing data of the new record
     *  @param referencedFileID value of the Referenced File ID attribute
     *  @param sourceFilename name of the source DICOM file
     *  @return pointer to new/existing record, NULL if an error occurred
     */
    DcmDirectoryRecord *addRecord(DcmDirectoryRecord *parent,
                                  const E_DirRecType recordType,
                                  DcmItem *dataset,
                                  const OFString &referencedFileID,
                                  const OFString &sourceFilename);

    /** invent missing type 1 attributes for all child records (from patient level)
     *  @param parent invent missing attributes for all children of this record (root)
     *  @param recurse invent missing attributes also for lower level records if OFTrue.
     *    Only invent attributes for the top (patient) level if OFFalse.
     */
    void inventMissingAttributes(DcmDirectoryRecord *parent,
                                 const OFBool recurse = OFTrue);

    /** invent missing type 1 attributes for all child records (from study level)
     *  @param parent invent missing attributes for all children of this record
     */
    void inventMissingStudyLevelAttributes(DcmDirectoryRecord *parent);

    /** invent missing type 1 attributes for all child records (from series level)
     *  @param parent invent missing attributes for all children of this record
     */
    void inventMissingSeriesLevelAttributes(DcmDirectoryRecord *parent);

    /** invent missing type 1 attributes for all child records (from instance level)
     *  @param parent invent missing attributes for all children of this record
     */
    void inventMissingInstanceLevelAttributes(DcmDirectoryRecord *parent);

    /** create backup of a given file
     *  @param filename name of the file to be backuped
     */
    void createDicomDirBackup(const char *filename);

    /** delete backup file if one has been created
     */
    void deleteDicomDirBackup();

    /** print a message on the log stream (stdout)
     *  @param message message to be printed
     *  @param suffix optional message suffix
     */
    void printMessage(const char *message,
                      const char *suffix = NULL);

    /** print a warning message on the log stream (stderr).
     *  The prefix "Warning: " is printed automatically.
     *  @param message warning message to be printed
     *  @param suffix optional message suffix
     */
    void printWarningMessage(const char *message,
                             const char *suffix = NULL);

    /** print an error message on the log stream (stderr).
     *  The prefix "Error: " is printed automatically.
     *  @param message error message to be printed
     *  @param suffix optional message suffix
     */
    void printErrorMessage(const char *message,
                           const char *suffix = NULL);

    /** print a message that the value of a given tag is unexpected.
     *  The output format is: "{Error|Warning}: attribute <key.tagName()> <key>
     *  has other value than expected[ in file: <filename>]"
     *  @param key affected tag
     *  @param filename name of the file (optional, might be NULL)
     *  @param errorMsg print error message if OFTrue, a warning message otherwise
     */
    void printUnexpectedValueMessage(const DcmTagKey &key,
                                     const char *filename = NULL,
                                     const OFBool errorMsg = OFTrue);

    /** print an error message that a required attribute is missing/empty.
     *  The output format is: "Error: <error.text()>: required attribute <key.tagName()>
     *  <key> {empty|missing}[ in file: <filename>]"
     *  @param key affected tag
     *  @param filename name of the file (optional, might be NULL)
     *  @param emptyMsg print "empty" if OFTrue, "missing" otherwise
     */
    void printRequiredAttributeMessage(const DcmTagKey &key,
                                       const char *filename = NULL,
                                       const OFBool emptyMsg = OFFalse);

    /** print an error message that something went wrong with an attribute.
     *  The output format is: "Error: <error.text()>: [cannot <operation> ]<key.tagName()>
     *  <key>"
     *  @param key affected tag
     *  @param error status to be reported (only if ".bad()")
     *  @param operation name of the operation that failed (optional, might be NULL)
     */
    void printAttributeErrorMessage(const DcmTagKey &key,
                                    const OFCondition &error,
                                    const char *operation);

    /** print an error message that something went wrong with a given record.
     *  The output format is: "Error: <error.text()>: [cannot <operation> ]<recordType>
     *  directory record"
     *  @param error status to be reported (only if ".bad()")
     *  @param recordType type of DICOMDIR record which caused the error
     *  @param operation name of the operation that failed (optional, might be NULL)
     */
    void printRecordErrorMessage(const OFCondition &error,
                                 const E_DirRecType recordType,
                                 const char *operation);

    /** print the given error status to the log stream (stderr).
     *  The output format is: "Error: <error.text()>: [<operation> ][file: <filename>]"
     *  @param error status to be reported (only if ".bad()")
     *  @param operation name of the operation that failed (optional, might be NULL)
     *  @param filename name of the file (optional, might be NULL)
     */
    void printFileErrorMessage(const OFCondition &error,
                               const char *operation,
                               const char *filename);

    /** copy contents of specified file
     *  @param fromFilename name of the file to be copied
     *  @param toFilename name of the new file (copy of 'fromFilename')
     *  @return OFTrue if successful, OFFalse otherwise
     */
    OFBool copyFile(const char *fromFilename,
                    const char *toFilename);

    /** see if all the attributes in record match the values in dataset and warn if not
     *  @param record directory record to be checked
     *  @param dataset DICOM dataset to be compared with the directory record
     *  @param sourceFilename name of the source DICOM file
     *  @param abortCheck flag indicating whether to abort on the first inconsistent record
     *  @return OFTrue in case of any inconsistency, OFFalse otherwise
     */
    OFBool warnAboutInconsistantAttributes(DcmDirectoryRecord *record,
                                           DcmItem *dataset,
                                           const OFString &sourceFilename,
                                           const OFBool abortCheck = OFFalse);

    /** check whether given fileset ID is valid
     *  @param filesetID fileset ID to be checked
     *  @return OFTrue if ID is valid, OFFalse otherwise
     */
    OFBool checkFilesetID(const OFString &filesetID);

    /** check whether given tag exists in the DICOM dataset
     *  @param dataset DICOM dataset to be checked
     *  @param key tag to be searched for
     *  @param filename of the file (optional, report any error if specified)
     *  @return OFTrue if tag exists, OFFalse otherwise
     */
    OFBool checkExists(DcmItem *dataset,
                       const DcmTagKey &key,
                       const char *filename = NULL);

    /** check whether given tag exists with a value in the DICOM dataset
     *  @param dataset DICOM dataset to be checked
     *  @param key tag to be searched for
     *  @param filename of the file (optional, report any error if specified)
     *  @return OFTrue if tag exists with value, OFFalse otherwise
     */
    OFBool checkExistsWithValue(DcmItem *dataset,
                                const DcmTagKey &key,
                                const char *filename = NULL);

    /** check whether given tag exists in the DICOM dataset and has the expected string value
     *  @param dataset DICOM dataset to be checked
     *  @param key tag to be searched for
     *  @param value expected string value
     *  @param filename of the file (optional, report any error if specified)
     *  @return OFTrue if tag exists with given string value, OFFalse otherwise
     */
    OFBool checkExistsWithStringValue(DcmItem *dataset,
                                      const DcmTagKey &key,
                                      const OFString &value,
                                      const char *filename = NULL);

    /** check whether given tag exists in the DICOM dataset and has the expected integer value
     *  @param dataset DICOM dataset to be checked
     *  @param key tag to be searched for
     *  @param value expected integer value
     *  @param filename of the file (optional, report any error if specified)
     *  @return OFTrue if tag exists with given string value, OFFalse otherwise
     */
    OFBool checkExistsWithIntegerValue(DcmItem *dataset,
                                       const DcmTagKey &key,
                                       const long value,
                                       const char *filename = NULL);

    /** check whether given tag exists in the DICOM dataset and has an integer value in the expected range
     *  @param dataset DICOM dataset to be checked
     *  @param key tag to be searched for
     *  @param min minimum integer value of the expected range
     *  @param max maximum integer value of the expected range
     *  @param filename of the file (optional, report any error if specified)
     *  @param reject report an "Error" if OFTrue, a "Warning" if OFFalse
     *  @return OFTrue if tag exists with given string value, OFFalse otherwise
     */
    OFBool checkExistsWithMinMaxValue(DcmItem *dataset,
                                      const DcmTagKey &key,
                                      const long min,
                                      const long max,
                                      const char *filename = NULL,
                                      const OFBool reject = OFTrue);

    /** get string value from dataset and report an error (if any)
     *  @param dataset dataset from which the string value is to be retrieved
     *  @param key tag of the attribute to be retrieved
     *  @param result string variable in which the resulting value is stored
     *  @param searchIntoSub flag indicating whether to do a deep search or not
     *  @return reference to the resulting string value (parameter 'result')
     */
    OFString &getStringFromDataset(DcmItem *dataset,
                                   const DcmTagKey &key,
                                   OFString &result,
                                   OFBool searchIntoSub = OFFalse);

    /** get string value from file and report an error (if any)
     *  @param filename name of the file from which the string value is to be retrieved
     *  @param key tag of the attribute to be retrieved
     *  @param result string variable in which the resulting value is stored
     *  @param searchIntoSub flag indicating whether to do a deep search or not
     *  @return reference to the resulting string value (parameter 'result')
     */
    OFString &getStringFromFile(const char *filename,
                                const DcmTagKey &key,
                                OFString &result,
                                OFBool searchIntoSub = OFFalse);

    /** copy element from dataset to directory record
     *  @param dataset DICOM dataset containing the original data
     *  @param key tag of the element to be copied
     *  @param record directory record to which the element is to be copied
     *  @param optional flag indicating whether the element is optional or required
     */
    void copyElement(DcmItem *dataset,
                     const DcmTagKey &key,
                     DcmDirectoryRecord *record,
                     const OFBool optional = OFFalse);

    /** copy optional string value from dataset to directory record
     *  @param dataset DICOM dataset containing the original data
     *  @param key tag of the element value to be copied
     *  @param record directory record to which the element value is to be copied
     *  @param defaultValue default string value used in case the element is missing
     *  @param printWarning print warning message if element does not exist (with a value)
     *    and no default value is given
     */
    void copyStringWithDefault(DcmItem *dataset,
                               const DcmTagKey &key,
                               DcmDirectoryRecord *record,
                               const char *defaultValue = "",
                               const OFBool printWarning = OFFalse);

    /** compare string attribute from dataset and record and report any deviation
     *  @param dataset DICOM dataset where the string value is stored
     *  @param key tag of the string value to be compared
     *  @param record directory record where the string value is stored
     *  @param sourceFilename name of the source DICOM file
     *  @return OFTrue if string values are identical, OFFalse otherwise
     */
    OFBool compareStringAttributes(DcmItem *dataset,
                                   DcmTagKey &key,
                                   DcmDirectoryRecord *record,
                                   const OFString &sourceFilename);

    /** compare sequence attribute from dataset and record and report any deviation
     *  @param dataset DICOM dataset where the sequence value is stored
     *  @param key tag of the sequence to be compared
     *  @param record directory record where the sequence value is stored
     *  @param sourceFilename name of the source DICOM file
     *  @return OFTrue if sequences are identical, OFFalse otherwise
     */
    OFBool compareSequenceAttributes(DcmItem *dataset,
                                     DcmTagKey &key,
                                     DcmDirectoryRecord *record,
                                     const OFString &sourceFilename);

    /** set default value (number or prefix and number) to a given tag
     *  @param record directory record where the elements are stored
     *  @param key tag of the element to be modifed
     *  @param number numeric value to be set as a the element value
     *  @param prefix optional prefix to be added to the numeric value
     */
    void setDefaultValue(DcmDirectoryRecord *record,
                         const DcmTagKey &key,
                         const unsigned long number,
                         const char *prefix = NULL);


  private:

    /// output stream for error messages, NULL for no messages
01134     OFConsole *LogStream;

    /// pointer to the current DICOMDIR object
01137     DcmDicomDir *DicomDir;

    /// pointer to the optional image plugin (required for icon image support)
01140     DicomDirImagePlugin *ImagePlugin;

    /// currently selected application profile
01143     E_ApplicationProfile ApplicationProfile;

    /// print verbose messages
01146     OFBool VerboseMode;
    /// create DICOMDIR backup
01148     OFBool BackupMode;
    /// abort on first inconsistent record
01150     OFBool AbortMode;
    /// automatically map filenames
01152     OFBool MapFilenamesMode;
    /// invent missing attributes mode
01154     OFBool InventMode;
    /// invent missing patient ID mode
01156     OFBool InventPatientIDMode;
    /// check image resolution
01158     OFBool ResolutionCheck;
    /// check consistency of newly added record
01160     OFBool ConsistencyCheck;
    /// create icon images
01162     OFBool IconImageMode;

    /// name of the DICOMDIR backup file
01165     OFString BackupFilename;
    /// flag indicating whether a backup has been created
01167     OFBool BackupCreated;

    /// size of the optional icon image in pixels
01170     unsigned int IconSize;
    /// filename prefix for the external icon images
01172     OFString IconPrefix;
    /// filename of the default icon (if any)
01174     OFString DefaultIcon;

    /// flag indicating whether JPEG compression is supported
01177     OFBool JPEGSupport;
    /// flag indicating whether RLE compression is supported
01179     OFBool RLESupport;

    /// current patient number used to invent missing attribute values
01182     unsigned long AutoPatientNumber;
    /// current study number used to invent missing attribute values
01184     unsigned long AutoStudyNumber;
    /// current series number used to invent missing attribute values
01186     unsigned long AutoSeriesNumber;
    /// current instance number used to invent missing attribute values
01188     unsigned long AutoInstanceNumber;
    /// current overlay number used to invent missing attribute values
01190     unsigned long AutoOverlayNumber;
    /// current LUT number used to invent missing attribute values
01192     unsigned long AutoLutNumber;
    /// current curve number used to invent missing attribute values
01194     unsigned long AutoCurveNumber;

    /// private undefined copy constructor
    DicomDirInterface(const DicomDirInterface &obj);

    /// private undefined assignment operator
    DicomDirInterface &operator=(const DicomDirInterface &obj);
};


#endif


/*
 *
 * CVS/RCS Log:
 * $Log: dcddirif.h,v $
 * Revision 1.3  2004/02/13 17:36:46  joergr
 * Added support for new directory records RAW DATA and SPECTROSCOPY introduced
 * with CP 343.
 *
 * Revision 1.2  2004/02/13 14:11:15  joergr
 * Added support for new directory records REGISTRATION and FIDUCIAL introduced
 * with supplement 73 (Spatial Registration Storage SOP Classes).
 *
 * Revision 1.1  2003/08/12 14:35:00  joergr
 * Added new interface class for simplified creation of a DICOMDIR.
 *
 *
 *
 */

Generated by  Doxygen 1.6.0   Back to index