dcm2xml: Convertir un fichier DICOM et un jeu de données en XML

SYNOPSIS

dcm2xml [options] dcmfile-in [xmlfile-out]

DESCRIPTION

dcm2xml est un utilitaire qui convertit le contenu d'un fichier DICOM (format de fichier ou jeu de données brut) en XML (Extensible Markup Language). Il existe deux formats de sortie. Le premier est spécifique à DCMTK, avec sa DTD (Document Type Definition) décrite dans le fichier dcm2xml.dtd. Le second fait référence au "Native DICOM Model", spécifié pour le service DICOM Application Hosting défini dans la partie 19 de DICOM.

Si dcm2xml lit un jeu de données brut (données DICOM sans méta-en-tête de format de fichier), il tente de deviner la syntaxe de transfert en examinant les premiers octets du fichier. Il n'est pas toujours possible de deviner correctement la syntaxe de transfert, et il est préférable de convertir un jeu de données au format de fichier chaque fois que possible (à l'aide de l'utilitaire dcmconv). Il est également possible d'utiliser les options -f et -t[ieb] pour forcer dcm2xml à lire un jeu de données avec une syntaxe de transfert particulière.

PARAMÈTRES

dcmfile-in   DICOM input filename to be converted ("-" for stdin)

xmlfile-out  XML output filename (default: stdout)

OPTIONS

options générales

-h --help: affiche cette aide et quitte
--version: affiche les informations de version et quitte
--arguments: affiche les arguments de ligne de commande développés
-q --quiet: mode silencieux, n'affiche ni avertissements ni erreurs
-v --verbose: mode détaillé, affiche les détails du traitement
-d --debug: mode débogage, affiche les informations de débogage
-ll --log-level [l]evel: string constant: (fatal, error, warn, info, debug, trace) utilise le niveau l pour la journalisation
-lc --log-config [f]ilename: string: utilise le fichier de configuration f pour le journal

options d'entrée

+f --read-file: lit le format de fichier ou le jeu de données (par défaut)
+fo --read-file-only: lit uniquement le format de fichier
-f --read-dataset: lit un jeu de données sans informations de méta-fichier syntaxe de transfert d'entrée :
-t= --read-xfer-auto: utilise la reconnaissance de la TS (par défaut)
-td --read-xfer-detect: ignore la TS spécifiée dans l'en-tête du méta-fichier
-te --read-xfer-little: lit avec la TS explicit VR little endian
-tb --read-xfer-big: lit avec la TS explicit VR big endian
-ti --read-xfer-implicit: lit avec la TS implicit VR little endian valeurs de tag longues :
+M --load-all: charge les valeurs de tag très longues (par exemple les données de pixels)
-M --load-short: ne charge pas les valeurs très longues (par défaut)
+R --max-read-length [k]bytes: integer (4..4194302, default: 4): définit le seuil des valeurs longues à k kilooctets

options de traitement

+Cr --charset-require: exige la déclaration d'un jeu de caractères étendu (par défaut)
+Ca --charset-assume [c]harset: string: suppose le jeu de caractères c si aucun jeu de caractères étendu n'est déclaré
+Cc --charset-check-all: vérifie tous les éléments de données ayant des valeurs de type chaîne (par défaut : uniquement PN, LO, LT, SH, ST, UC et UT) # cette option n'est utilisée que pour la vérification étendue permettant de déterminer si # l'attribut Specific Character Set (0008,0005) doit être # présent, mais pas pour la conversion en UTF-8 des valeurs # d'éléments non affectés (par exemple les valeurs d'éléments avec un VR de CS)
+U8 --convert-to-utf8: convertit en UTF-8 toutes les valeurs d'éléments concernées par Specific Character Set (0008,0005) # nécessite la prise en charge d'une # bibliothèque de codage de caractères sous-jacente (voir la sortie de --version pour savoir laquelle est disponible)

options de sortie

-dtk --dcmtk-format: sortie au format spécifique à DCMTK (par défaut)
-nat --native-format: sortie au format Native DICOM Model (partie 19)
+Xn --use-xml-namespace: ajoute une déclaration d'espace de noms XML à l'élément racine format spécifique à DCMTK (pas avec --native-format) :
+Xd --add-dtd-reference: ajoute une référence à la définition de type de document (DTD)
+Xe --embed-dtd-content: intègre la définition de type de document dans le document XML
+Xf --use-dtd-file [f]ilename: string: utilise le fichier DTD spécifié (uniquement avec +Xe) (par défaut : /usr/local/share/dcmtk-/dcm2xml.dtd)
+Wn --write-element-name: écrit le nom des éléments de données DICOM (par défaut)
-Wn --no-element-name: n'écrit pas le nom des éléments de données DICOM
+Wb --write-binary-data: écrit les données binaires des éléments OB et OW (par défaut : off, soyez prudent avec --load-all) encodage des données binaires :
+Eh --encode-hex: encode les données binaires sous forme de nombres hexadécimaux (par défaut pour le format spécifique à DCMTK)
+Eu --encode-uuid: encode les données binaires sous forme de référence UUID (par défaut pour Native DICOM Model)
+Eb --encode-base64: encode les données binaires en Base64 (RFC 2045, MIME)

Format DCMTK

La structure de base de la sortie XML spécifique à DCMTK créée à partir d'un fichier DICOM se présente comme suit :

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE file-format SYSTEM "dcm2xml.dtd">
<file-format xmlns="http://dicom.offis.de/dcmtk">
  <meta-header xfer="1.2.840.10008.1.2.1" name="Little Endian Explicit">
    <element tag="0002,0000" vr="UL" vm="1" len="4"
             name="MetaElementGroupLength">
      166
    </element>
    ...
    <element tag="0002,0013" vr="SH" vm="1" len="16"
             name="ImplementationVersionName">
      OFFIS_DCMTK_353
    </element>
  </meta-header>
  <data-set xfer="1.2.840.10008.1.2" name="Little Endian Implicit">
    <element tag="0008,0005" vr="CS" vm="1" len="10"
             name="SpecificCharacterSet">
      ISO_IR 100
    </element>
    ...
    <sequence tag="0028,3010" vr="SQ" card="2" name="VOILUTSequence">
      <item card="3">
        <element tag="0028,3002" vr="xs" vm="3" len="6"
                 name="LUTDescriptor">
          256\0\8
        </element>
        ...
      </item>
      ...
    </sequence>
    ...
    <element tag="7fe0,0010" vr="OW" vm="1" len="262144"
             name="PixelData" loaded="no" binary="hidden">
    </element>
  </data-set>
</file-format>

Les balises "file-format" et "meta-header" sont absentes pour les jeux de données DICOM.

Encodage XML

Les attributs comportant des champs de valeur très volumineux (par exemple les données de pixels) ne sont pas chargés par défaut. Ils peuvent être identifiés par l'attribut supplémentaire "loaded" ayant la valeur "no" (voir l'exemple ci-dessus). L'option de ligne de commande –load-all force le chargement de tous les champs de valeur, y compris les plus longs.

Par ailleurs, les données binaires des attributs OB et OW ne sont pas écrites dans le fichier de sortie XML par défaut. Ces éléments peuvent être identifiés par l'attribut supplémentaire "binary" ayant la valeur "hidden" (la valeur par défaut est "no"). L'option de ligne de commande –write-binary-data entraîne également l'impression des champs de valeur binaires (la valeur de l'attribut est "yes" ou "base64"). Faites toutefois attention en combinant cette option avec –load-all, car de grandes quantités de données de pixels risquent alors d'être imprimées en sortie. Notez que, dans ce contexte, les valeurs d'éléments avec un VR de OD, OF, OL et OV ne sont pas considérées comme des "données binaires".

Les valeurs multiples (c'est-à-dire lorsque la multiplicité de valeur DICOM est supérieure à 1) sont séparées par une barre oblique inverse "\" (sauf pour les données encodées en Base64). L'attribut "len" indique le nombre d'octets du champ de valeur concerné tel qu'il est stocké dans le jeu de données DICOM, c'est-à-dire qu'il peut différer de la longueur de la valeur encodée en XML, par exemple en raison d'un remplissage non significatif qui a été supprimé. Si cet attribut est absent des balises de début "sequence" ou "item", l'élément DICOM correspondant a été stocké avec une longueur non définie.

Format Native DICOM Model

La description du format Native DICOM Model se trouve dans le standard DICOM, partie 19 ("Application Hosting").

Données volumineuses

Les données binaires, c'est-à-dire les valeurs d'éléments DICOM ayant une représentation de valeur (VR) OB ou OW, ainsi que les valeurs OD, OF, OL, OV et UN, ne sont par défaut pas écrites dans la sortie XML en raison de leur taille. À la place, pour chaque élément, un nouvel identifiant unique universel (UUID) est généré et écrit comme attribut d'un élément XML . Pour l'instant, il n'est pas possible d'écrire un fichier supplémentaire pour conserver les données binaires de chacun des blocs de données binaires. Cela n'est pas requis par le standard ; cela pourrait toutefois s'avérer utile pour la mise en œuvre d'une interface Application Hosting, et cette fonctionnalité pourrait donc être disponible dans de futures versions de dcm2xml.

En outre, le Supplement 163 (Store Over the Web by Representational State Transfer Services) introduit un nouvel élément XML qui permet d'encoder les données binaires en Base64. Actuellement, l'option de ligne de commande –encode-base64 active cet encodage pour les VR suivants : OB, OD, OF, OL, OV, OW et UN.

Problèmes connus

Outre ce qui est indiqué dans la section "Données volumineuses" ci-dessus, l'implémentation actuelle du format Native DICOM Model présente d'autres problèmes connus. Par exemple, les valeurs d'éléments volumineuses ayant un VR autre que OB, OD, OF, OL, OV, OW ou UN ne sont actuellement jamais écrites comme données volumineuses, bien que cela puisse s'avérer utile, par exemple pour des éléments de texte très longs (en particulier UT) ou des champs numériques très longs (de divers VR).

NOTES

Encodage des caractères

L'encodage de caractères XML est déterminé automatiquement à partir de l'attribut DICOM (0008,0005) "Specific Character Set", selon la correspondance suivante :

ASCII         (ISO_IR 6)    =>  "UTF-8"
UTF-8         "ISO_IR 192"  =>  "UTF-8"
ISO Latin 1   "ISO_IR 100"  =>  "ISO-8859-1"
ISO Latin 2   "ISO_IR 101"  =>  "ISO-8859-2"
ISO Latin 3   "ISO_IR 109"  =>  "ISO-8859-3"
ISO Latin 4   "ISO_IR 110"  =>  "ISO-8859-4"
ISO Latin 5   "ISO_IR 148"  =>  "ISO-8859-9"
ISO Latin 9   "ISO_IR 203"  =>  "ISO-8859-15"
Cyrillic      "ISO_IR 144"  =>  "ISO-8859-5"
Arabic        "ISO_IR 127"  =>  "ISO-8859-6"
Greek         "ISO_IR 126"  =>  "ISO-8859-7"
Hebrew        "ISO_IR 138"  =>  "ISO-8859-8"

Si cet attribut DICOM est absent du fichier d'entrée alors qu'il est nécessaire, l'option –charset-assume peut être utilisée pour spécifier manuellement un jeu de caractères approprié (en utilisant l'un des termes définis par DICOM). Pour des raisons de rétrocompatibilité avec les versions antérieures de cet outil, les termes suivants sont également pris en charge et automatiquement associés aux termes DICOM correspondants : latin-1, latin-2, latin-3, latin-4, latin-5, latin-9, cyrillic, arabic, greek, hebrew.

Les jeux de caractères multiples utilisant des techniques d'extension de code ne sont pas pris en charge. Si nécessaire, l'option –convert-to-utf8 peut être utilisée pour convertir le fichier ou le jeu de données DICOM en encodage UTF-8 avant la conversion au format XML. Cela est également utile pour les fichiers DICOMDIR, où chaque enregistrement de répertoire peut avoir un jeu de caractères différent.

Si aucune correspondance n'est définie et que l'option –convert-to-utf8 n'est pas utilisée, les caractères non-ASCII et ceux en dessous de #32 sont stockés sous la forme "&#nnn;", où "nnn" correspond au code numérique du caractère. Cela peut produire des références d'entité de caractère invalides (telles que "" pour ESC) et amènera la plupart des analyseurs XML à rejeter le document.

JOURNALISATION

Le niveau de détail de la journalisation des différents outils en ligne de commande et des bibliothèques sous-jacentes peut être spécifié par l'utilisateur. Par défaut, seules les erreurs et les avertissements sont écrits dans le flux d'erreur standard. L'option –verbose permet également de signaler des messages d'information tels que les détails du traitement. L'option –debug permet d'obtenir plus de détails sur l'activité interne, par exemple à des fins de débogage. L'option –log-level permet de sélectionner d'autres niveaux de journalisation. En mode –quiet, seules les erreurs fatales sont signalées. Dans de tels cas d'erreur très graves, l'application se termine généralement. Pour plus de détails sur les différents niveaux de journalisation, consultez la documentation du module "oflog".

Si la sortie de la journalisation doit être écrite dans un fichier (éventuellement avec rotation des fichiers journaux), vers syslog (Unix) ou le journal des événements (Windows), l'option –log-config peut être utilisée. Ce fichier de configuration permet également de diriger uniquement certains messages vers un flux de sortie particulier et de filtrer certains messages en fonction du module ou de l'application qui les génère. Un exemple de fichier de configuration est fourni dans < etcdir>/logger.cfg.

LIGNE DE COMMANDE

Tous les outils en ligne de commande utilisent la notation suivante pour les paramètres : les crochets entourent les valeurs facultatives (0-1), trois points de suspension à la fin indiquent que plusieurs valeurs sont autorisées (1-n), et la combinaison des deux signifie de 0 à n valeurs.

Les options de la ligne de commande se distinguent des paramètres par un signe '+' ou '-' en tête. En général, l'ordre et la position des options de la ligne de commande sont arbitraires (c'est-à-dire qu'elles peuvent apparaître n'importe où). Toutefois, si des options s'excluent mutuellement, c'est la dernière occurrence, la plus à droite, qui est utilisée. Ce comportement est conforme aux règles d'évaluation standard des shells Unix courants.

De plus, un ou plusieurs fichiers de commandes peuvent être spécifiés en utilisant un signe '@' comme préfixe du nom de fichier (par exemple @command.txt). Un tel argument de commande est remplacé par le contenu du fichier texte correspondant (les espaces multiples sont traités comme un séparateur unique, sauf s'ils apparaissent entre deux guillemets) avant toute évaluation ultérieure. Notez qu'un fichier de commandes ne peut pas contenir un autre fichier de commandes. Cette approche simple mais efficace permet de regrouper des combinaisons courantes d'options/paramètres et évite des lignes de commande longues et peu lisibles (un exemple est fourni dans le fichier < datadir>/dumppat.txt).

ENVIRONNEMENT

L'utilitaire dcm2xml tentera de charger les dictionnaires de données DICOM spécifiés dans la variable d'environnement DCMDICTPATH. Par défaut, c'est-à-dire si la variable d'environnement DCMDICTPATH n'est pas définie, le fichier < datadir>/dicom.dic sera chargé, à moins que le dictionnaire ne soit intégré à l'application (par défaut sous Windows).

Il est préférable de conserver le comportement par défaut et de n'utiliser la variable d'environnement DCMDICTPATH que lorsque des dictionnaires de données alternatifs sont nécessaires. La variable d'environnement DCMDICTPATH a le même format que la variable PATH des shells Unix, en ce sens que les deux-points (":") séparent les entrées. Sur les systèmes Windows, le point-virgule (";") est utilisé comme séparateur. Le code du dictionnaire de données tente de charger chaque fichier spécifié dans la variable d'environnement DCMDICTPATH. C'est une erreur si aucun dictionnaire de données ne peut être chargé.

Selon les options de ligne de commande spécifiées, l'utilitaire dcm2xml tentera de charger des tables de correspondance de jeux de caractères. Cela se produit lorsque DCMTK a été compilé avec la bibliothèque oficonv (ce qui est le cas par défaut) et que les tables de correspondance ne sont pas intégrées à la bibliothèque (par défaut lorsque DCMTK utilise des bibliothèques partagées).

Les fichiers de tables de correspondance sont attendus dans le < datadir> de DCMTK. La variable d'environnement DCMICONVPATH peut être utilisée pour indiquer un autre emplacement. Si un autre emplacement est indiqué, ces tables de correspondance remplacent également toutes les tables intégrées.