dcm2json: conversion d'un fichier et d'un jeu de données DICOM en JSON

SYNOPSIS

dcm2json [options] dcmfile-in [jsonfile-out]

DESCRIPTION

dcm2json est un utilitaire qui convertit le contenu d'un fichier DICOM (format de fichier ou jeu de données brut) en JSON (JavaScript Object Notation). La sortie se réfère au "DICOM JSON Model", décrit dans DICOM Part 18 Section F.

Lorsque dcm2json 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 dcm2json à 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)

jsonfile-out JSON 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 pas d'avertissements ni d'erreurs
-v --verbose: mode détaillé, affiche les détails du traitement
-d --debug: mode de 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 la journalisation

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 le jeu de données sans les métadonnées de fichier. Syntaxe de transfert en entrée :
-t= --read-xfer-auto: utilise la reconnaissance automatique de la TS (par défaut)
-td --read-xfer-detect: ignore la TS spécifiée dans le méta-en-tête du 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

options de traitement

-es --encode-strict: signale une erreur pour 'inf' et 'nan' (par défaut)
-ee --encode-extended: autorise 'inf' et 'nan' dans les nombres JSON. Encodage des éléments IS et DS (chaîne entière/décimale) :
-ia --is-ds-auto: encode en nombre si valide, en chaîne sinon (par défaut)
-in --is-ds-num: encode toujours en nombre, échoue si invalide
-is --is-ds-string: encode toujours en chaîne. Options des URI de données volumineuses :
-b --bulk-disabled: écrit tout sous forme de binaire en ligne (par défaut)
+b --bulk-enabled: écrit les attributs de grande taille sous forme de données volumineuses
+bz --bulk-size [s]ize: integer (default: 1): utilise des données volumineuses pour les attributs de taille égale ou supérieure à s Ko
+bp --bulk-uri-prefix [u]ri prefix: string: utilise le préfixe u lors de la génération des URI de données volumineuses (par défaut : URI de fichier)
+bd --bulk-dir [d]irectory: string: écrit les fichiers de données volumineuses dans d (par défaut : '.')
+bs --bulk-subdir: crée un sous-répertoire pour chaque instance SOP (par défaut : pas de sous-répertoire)

options de sortie

+fc --formatted-code: active le formatage avec espaces (par défaut) # ajoute des espaces et retours à la ligne supplémentaires pour améliorer la lisibilité
-fc --compact-code: affiche uniquement les caractères nécessaires
+m --write-meta: écrit le jeu de données avec les métadonnées (avertissement : non conforme à la norme DICOM)

Format JSON

La structure de base de la sortie JSON générée à partir d'un fichier DICOM se présente comme suit (voir DICOM Part 18 Section F pour plus de détails) :

{
    "00080005": {
        "vr": "CS",
        "Value": [
            "ISO_IR 192"
        ]
    },
    "00080020": {
        "vr": "DT",
        "Value": [
            "20130409"
        ]
    },
    "00080030": {
        "vr": "TM",
        "Value": [
            "131600.0000"
        ]
    },
    "00080050": {
        "vr": "SH",
        "Value": [
            "11235813"
        ]
    },
    "00080056": {
        "vr": "CS",
        "Value": [
            "ONLINE"
        ]
    },
    "00080061": {
        "vr": "CS",
        "Value": [
            "CT",
            "PET"
        ]
    },
    "00080090": {
        "vr": "PN",
        "Value": [
          {
            "Alphabetic": "^Bob^^Dr."
          }
        ]
    },
    "00081190": {
        "vr": "UR",
        "Value": [
            "http://wado.nema.org/studies/
            1.2.392.200036.9116.2.2.2.1762893313.1029997326.945873"
        ]
    },
    "00090010": {
        "vr": "LO",
        "Value": [
            "Vendor A"
        ]
    },
    "00091002": {
        "vr": "UN",
        "InlineBinary": "z0x9c8v7"
    },
    "00100010": {
        "vr": "PN",
        "Value": [
          {
            "Alphabetic": "Wang^XiaoDong"
          }
        ]
    },
    "00100020": {
        "vr": "LO",
        "Value": [
            "12345"
        ]
    },
    "00100021": {
        "vr": "LO",
        "Value": [
            "Hospital A"
        ]
    },
    "00100030": {
        "vr": "DA",
        "Value": [
            "19670701"
        ]
    },
    "00100040": {
        "vr": "CS",
        "Value": [
            "M"
        ]
    },
    "00101002": {
        "vr": "SQ",
        "Value": [
            {
                "00100020": {
                    "vr": "LO",
                    "Value": [
                        "54321"
                    ]
                },
                "00100021": {
                    "vr": "LO",
                    "Value": [
                        "Hospital B"
                    ]
                }
            },
            {
                "00100020": {
                    "vr": "LO",
                    "Value": [
                        "24680"
                    ]
                },
                "00100021": {
                    "vr": "LO",
                    "Value": [
                        "Hospital C"
                    ]
                }
            }
        ]
    },
    "0020000D": {
        "vr": "UI",
        "Value": [
            "1.2.392.200036.9116.2.2.2.1762893313.1029997326.945873"
        ]
    },
    "00200010": {
        "vr": "SH",
        "Value": [
            "11235813"
        ]
    },
    "00201206": {
        "vr": "IS",
        "Value": [
            4
        ]
    },
    "00201208": {
        "vr": "IS",
        "Value": [
            942
        ]
    }
}

Données volumineuses

Par défaut, les données binaires, c'est-à-dire les valeurs d'éléments DICOM dont la représentation de valeur (VR) est OB, OD, OF, OL, OV, OW ou UN, sont écrites sous la forme "InlineBinary" (encodage base64) dans la sortie JSON. L'option –bulk-enabled entraîne le remplacement des données binaires ainsi que des DS, FD, FL, IS, SV et UV par des valeurs "BulkDataURI" si la valeur de l'élément est supérieure au seuil de coupure (par défaut : 1 Ko). Le seuil de coupure peut être défini avec l'option –bulk-size. Les valeurs des éléments elles-mêmes sont écrites sous forme de fichiers dans le répertoire indiqué par l'option –bulk-dir (par défaut : répertoire courant). Le nom de fichier est basé sur une somme de contrôle SHA-256 de la valeur de l'élément. Par défaut, des URI de fichier pointant vers le répertoire des données volumineuses sont générées. Pour une utilisation en production, il est conseillé de spécifier avec l'option –bulk-uri-prefix un préfixe d'URI pour un service WADO-RS permettant de récupérer les valeurs des éléments. Cela peut être mis en œuvre en configurant un serveur web ayant un accès en lecture au répertoire des données volumineuses de dcm2json. Enfin, l'option –bulk-subdir entraîne la création d'un sous-répertoire distinct (également utilisé dans l'URI de données volumineuses) pour chaque instance SOP.

Notez que la syntaxe JSON pour la représentation de données de pixels encapsulées sous forme "InlineBinary" n'est pas spécifiée par DICOM, tout comme la représentation JSON de données de pixels encapsulées multi-images. Ces fichiers DICOM ne peuvent pas être convertis en JSON avec dcm2json.

L'extension de nom de fichier des fichiers de données volumineuses générés peut être utilisée pour déterminer le type MIME que devrait renvoyer le serveur WADO-RS :

  Extension     MIME Type

  .bin          application/octet-stream
  .jpeg         image/jpeg
  .dicom-rle    image/dicom-rle
  .jls          image/jls
  .jp2          image/jp2
  .jpx          image/jpx
  .jphc         image/jphc
  .jxl          image/jxl
  .mpeg         video/mpeg
  .mp4          video/mp4
  .H265         video/H265

Enfin, il convient de noter que les données volumineuses seront écrites "telles quelles", c'est-à-dire que dcm2json ne tentera pas de valider ou de modifier la valeur de l'élément de quelque façon que ce soit. Par exemple, dcm2json n'ajoutera pas d'en-tête JFIF dans le cas d'images compressées JPEG baseline, ce que certaines visionneuses JPEG peuvent attendre.

NOTES

Nombres sous forme de chaînes

La norme DICOM permet de convertir certaines représentations de valeur DICOM numériques, à savoir DS, IS, SV et UV, soit en nombre JSON, soit en chaîne JSON. dcm2json convertit les valeurs DS et IS en nombres JSON si ce sont des chaînes décimales ou des chaînes entières valides, et en chaînes si elles contiennent un caractère illégal. dcm2json convertit les valeurs SV et UV en nombres si elles ne sont pas supérieures à 9007199254740991ll ni inférieures à -9007199254740991ll, et en chaînes dans le cas contraire. Bien que la spécification JSON autorise des nombres plus grands, ce sont les plus grands entiers que JavaScript puisse gérer. Par conséquent, de nombreux analyseurs JSON ne peuvent pas traiter de nombres plus grands.

Encodage des caractères

Conformément aux exigences de l'encodage JSON DICOM, dcm2json produit toujours une sortie en encodage Unicode UTF-8 et convertit les jeux de données DICOM en conséquence. Si cela n'est pas possible, par exemple parce que DCMTK a été compilé sans prise en charge de la conversion de jeu de caractères, une erreur est renvoyée.

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

CODES DE SORTIE

L'utilitaire dcm2json utilise les codes de sortie suivants lorsqu'il se termine. Cela permet à l'utilisateur de vérifier la raison pour laquelle l'application s'est terminée.

général

EXITCODE_NO_ERROR                         0
EXITCODE_COMMANDLINE_SYNTAX_ERROR         1

erreurs de fichier d'entrée

EXITCODE_CANNOT_READ_INPUT_FILE          20
EXITCODE_NO_INPUT_FILES                  21

erreurs de fichier de sortie

EXITCODE_CANNOT_WRITE_OUTPUT_FILE        40

erreurs de traitement

EXITCODE_CANNOT_CONVERT_TO_UNICODE       80
EXITCODE_CANNOT_WRITE_VALID_JSON         81

ENVIRONNEMENT

L'utilitaire dcm2json tente 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 est chargé, sauf si le dictionnaire est intégré à l'application (comportement 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é.

L'utilitaire dcm2json tente de charger les 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 comportement par défaut) et que les tables de correspondance ne sont pas intégrées à la bibliothèque (comportement 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.