DCMTK: datadict.txt file

DCMTK Version 3.7.0 OFFIS DICOM Toolkit

Loading...
Searching...
No Matches
datadict.txt file

    -----------------------------------------------------------------------------
    DICOM DATA DICTIONARY IN DCMTK
    -----------------------------------------------------------------------------

    In DICOM, the Data Dictionary (part 6 of the DICOM standard) stores for all
    attribute tags their respective VR, VM, name and other information.  This
    information must also be made available in DCMTK.  This is accomplished
    through a global data dictionary class.

    The global data dictionary is loaded within a C++ constructor into the global
    DcmDataDictionary class instance called dcmDataDict once it is accessed for
    the first time from the code.  The initial dictionary content is populated by
    two different approaches:

    1. builtin: The content (tags, VR, ...) is compiled into the dictionary code.
    2. external: The dictionary is filled by loading a default text file on
       startup from a pre-defined file path.

    It is also possible to not load any default dictionary on startup at all
    (option "disable" or setting "none", see below).

    The built-in approach offers the advantage that a binary will not have to
    load any information from a separate file, which may get lost or used in an
    outdated version.  Loading the dictionary content from a separate file,
    however, has the advantage that application programs need not be recompiled
    if additions or corrections are made to the data dictionary.

    By default, DCMTK uses an external data dictionary on Posix systems (Linux,
    Mac OS X, etc.) while a built-in dictionary is used on Windows systems.  How
    these defaults can be changed or how both approaches can even be combined is
    further explained below.

    There is also an option to evaluate the environment variable DCMDICTPATH and
    to read dictionaries defined therein, see below for details.

    -----------------------------------------------------------------------------
    DICTIONARY DEFAULT: AUTOCONF ON POSIX SYSTEMS
    -----------------------------------------------------------------------------

    By default, on a Posix system the global data dictionary will attempt to load
    the data dictionary from an external file.  The location is pre-configured
    to $DCMTK_DAT_DIR/dicom.dic where $DCMTK_DAT_DIR is DCMTK's data installation
    directory chosen using configure's --datadir option (default value: /dcmtk).
    See also --datarootdir and --prefix options.  The resulting path is stored as
    DCM_DICT_DEFAULT_PATH in the file config/include/dcmtk/config/osconfig.h,
    which is created by Autoconf during the execution of the configure script and
    thus is available to the dictionary code that includes osconfig.h.

    -----------------------------------------------------------------------------
    DICTIONARY DEFAULT: CMAKE ON WINDOWS AND POSIX SYSTEMS
    -----------------------------------------------------------------------------

    On Windows, the default behavior is to compile a fully-populated built-in data
    dictionary as a global data dictionary into the dcmdata library.  Thus, it is
    not required to load an external data dictionary from a file.

    On Posix systems, the default setting when using CMake is to load the data
    dictionary from an external file (as described in the above section on
    Autoconf).

    -----------------------------------------------------------------------------
    CHANGING DICTIONARY DEFAULTS
    -----------------------------------------------------------------------------

    Autoconf as well as CMake provide options to change their default dictionary
    behavior.  For Autoconf, there are two different options.  The first one is:

      --enable-default-dict=TYPE

    Possible values for TYPE are:

      "external": Compile with external default dictionary
      "builtin" : Compile with built-in default dictionary

    With the second option, the default dictionary can be disabled:

      --disable-default-dict

    When building with CMake, the related option is:

      - DCMTK_DEFAULT_DICT

    Possible values for this option are:

      "external": Compile with external default dictionary
      "builtin" : Compile with built-in default dictionary
      "none"    : Compile without any default dictionary (same as "disable")

    That means, both Autoconf and CMake provide the same functionality.  On Posix
    systems "external" is the default value, while on Windows it is "builtin".

    -----------------------------------------------------------------------------
    CUSTOM EXTERNAL DICTIONARIES THROUGH ENVIRONMENT VARIABLE "DCMDICTPATH"
    -----------------------------------------------------------------------------

    Sometimes it makes sense to change the dictionary that should be loaded
    without recompiling the source code.  This can be done either by modifying
    the dicom.dic that is already loaded (if using 'external' standard dictionary)
    or by specifying a different location in an environment variable that is
    evaluated on DCMTK startup.  This environment variable is called "DCMDICTPATH"
    and can be used on Windows and Posix systems.

    If DCMDICTPATH is not set, the behavior described in the sections above takes
    place (built-in or external dictionary from default path is loaded).
    Otherwise, the file provided in the environment variable DCMDICTPATH is loaded
    and any default external dictionary is ignored (!).  Note, however, that the
    built-in dictionary (if configured) is always loaded.

    In order to set DCMDICTPATH on Unix, the csh shell command

      setenv DCMDICTPATH $HOME/dicom.dic

    would cause all applications using the dcmdata library to load the data
    dictionary dicom.dic from the user's home directory.  When using the bash,
    the command is:

      export DCMDICTPATH=$HOME/dicom.dic

    For Windows, the call

      set DCMDICTPATH=c:\dicom.dic

    will cause all applications using the dcmdata library to load the data
    dictionary dicom.dic from the main directory on drive C.

    It is possible to completely disable the evaluation of DCMDICTPATH (e.g. for
    security reasons).  The related configure options controlling this behavior
    are the following:

      --enable-dcmdictpath (default)
      --disable-dcmdictpath

    When building with CMake, the related option is:

      - DCMTK_USE_DCMDICTPATH (on/off, default: on)

    By default, DCMDICTPATH evaluation is enabled on both on Windows and Posix
    systems.

    -----------------------------------------------------------------------------
    DICTIONARY LOAD ORDER AND USING MULTIPLE DICTIONARIES
    -----------------------------------------------------------------------------

    The load behavior is slightly different for built-in and external default
    dictionaries:

    If the built-in dictionary is enabled, it will be loaded first on startup.
    DCMTK then checks whether DCMDICTPATH should be evaluated (see above) and, if
    it is set and provides a non-empty value, DCMTK will load all additional
    dictionaries on top of the built-in default dictionary.

    If instead the external default dictionary is enabled and DCMDICTPATH
    evaluation is turned off, the external default dictionary will be loaded.

    However, if DCMDICTPATH evaluation is enabled and the environment variable
    provides a (non-empty) value, DCMTK will load the dictionary denoted by
    DCMDICTPATH and will not load the external default dictionary at all.

    It is not possible to enable both external and built-in default dictionary at
    the same time.

    If the user decides to use no default dictionary at all by defining
    (DCMTK_DEFAULT_DICT=none), it is still possible to define a dictionary by
    using the DCMDICTPATH mechanism.  If DCMTK_USE_DCMDICTPATH is turned off
    as well, no dictionary is loaded on startup and the user must populate
    the dictionary using his own code during runtime.

    Application programs should check that a data dictionary has been loaded
    before using the functionality of the dcmdata library.  The absence of
    a data dictionary is likely to cause unexpected behavior (e.g. unknown
    attributes will be encoded using VR=UN).

    -----------------------------------------------------------------------------
    USING MORE THAN ONE EXTERNAL DICTIONARY
    -----------------------------------------------------------------------------

    The DCMDICTPATH environment variable can even refer to several data
    dictionaries separated by colons (":") on Unix systems, or semicolons (";")
    on Windows systems.  Thus the Unix csh command

      setenv DCMDICTPATH /usr/local/share/dcmtk-<VERSION>/dicom.dic:$HOME/dicom.dic

    would cause all applications using the dcmdata library to first load the
    default data dictionary and subsequently load the data dictionary dicom.dic
    from the user's home directory.  When using the bash, the command would be:

      export DCMDICTPATH=/usr/local/share/dcmtk-<VERSION>/dicom.dic:$HOME/dicom.dic

    On Windows systems, the command would be:

      set DCMDICTPATH=c:\dcmtk-install\share\dcmtk-<VERSION>\dicom.dic;c:\dicom.dic

    Also here, data dictionary entries loaded later in the load sequence override
    entries loaded earlier.

    -----------------------------------------------------------------------------
    DATA DICTIONARIES INCLUDED IN DCMTK (DICOM.DIC, PRIVATE.DIC AND BUILT-IN)
    -----------------------------------------------------------------------------

    An example DICOM data dictionary can be found in dcmdata/data/dicom.dic,
    which is also installed (using Autoconf or CMake) and used as the default
    external dictionary (if external default dictionary is enabled).

    The example data dictionary is meant to be complete and includes all standard
    and retired attributes from part 6 of the DICOM standard (see the header of
    the file where the implemented version of the standard plus all supplements
    and CPs are listed).  Also contained, since they are included in part 6, are
    the official DICONDE (Digital Imaging and Communication in Nondestructive
    Evaluation) and DICOS (Digital Imaging and Communications in Security)
    attributes.

    Another example dictionary included is the dcmdata/data/private.dic, which
    includes all private tag information known to DCMTK developers and partly
    taken over from other DICOM toolkits and various other sources like DICOM
    Conformance Statements.  There is no guarantee that the information contained
    is valid or even complete.  By default, this dictionary is not taken into
    account.  It can be enabled to load on startup as an extra external dictionary
    using Autoconf's configure option --enable-private-tags and in CMake using the
    option DCMTK_ENABLE_PRIVATE_TAGS.  Enabling will result in private.dic being
    added to the DCM_DICT_DEFAULT_PATH, which lists those external dictionaries to
    be loaded on startup (see above).  Note that the private tag option is only
    considered for external dictionaries if external dictionaries are not disabled.

    DCMTK also includes two predefined built-in dictionaries, one fully populated
    containing the information from DCMTK's dicom.dic file (and possibly from the
    private.dic file if enabled, see next paragraph), and one that is empty.  Both
    are defined in dcdictbi.cc and the one to be used is selected by the dictionary
    build options (see above).

    The code for a useful built-in data dictionary can be regenerated at any time
    by the mkdictbi program (dcmdata/libsrc/mkdictbi).  The dcmdata library
    Makefiles (for Autoconf dcmdata/libsrc/Makefile.in, and for CMake
    dcmdata/libsrc/CMakeLists.txt) provide a target (updatebuiltindict) for this
    purpose.  After regenerating dcdictbi.cc, rebuilding the dcmdata library and
    relinking all applications will ensure that the built-in data dictionary is
    used.  This dictionary contains all definitions from the dicom.dic and
    private.dic file.  Please note, however, that the latter is only available if
    support for private tags has been enabled during DCMTK configuration and thus
    ENABLE_PRIVATE_TAGS is defined in osconfig.h.

    -----------------------------------------------------------------------------
    TAG NAME CONSTANTS FOR USE IN APPLICATIONS
    -----------------------------------------------------------------------------

    The include file dcmdata/include/dcmtk/dcmdata/dcdeftag.h can be generated
    from a data dictionary by the program mkdeftag.  The include file defines
    attribute tag names for use in application programs.  The names are generated
    from the official keywords specified in the data dictionary.  Duplicate names
    in the data dictionary will result in compiler warnings due to duplicate
    #define's when compiling code that includes the dcdeftag.h header file.
    Thus, when adding new entries to the data dictionary, care should be taken to
    ensure that attribute names are not duplicated for distinct tags.

    The dcmdata library Makefiles (for Autoconf dcmdata/libsrc/Makefile.in and for
    CMake dcmdata/libsrc/CMakeLists.txt) include a target (updatedeftag) that
    builds the mkdeftag tool and uses it to generate the
    dcmdata/include/dcmtk/dcmdata/dcdeftag.h header file.  The header file should
    be regenerated whenever additions or name modifications are made to the data
    dictionary.  Care should be taken before modifying any tag names since
    existing application programs may already use the old name and might
    subsequently fail to compile.

    ------------

    DCMTK Development Team, Oldenburg, Germany

    Last revised: 2021-08-31 (Riesmeier).

Generated on for DCMTK Version 3.7.0 by Doxygen 1.16.1