dcmodify: modifier des fichiers DICOM

SYNOPSIS

dcmodify [options] dcmfile-in...

DESCRIPTION

dcmodify est un outil qui permet de modifier, insérer et supprimer des tags et des items dans des fichiers DICOM. Les séquences et les tags dont la multiplicité de valeur est supérieure à 1 sont également pris en charge. Les informations du méta-en-tête et la VR du tag ne peuvent pas être modifiées directement par dcmodify pour le moment. Outre les modifications de tags, dcmodify propose des options d'entrée - forçant dcmodify à traiter ses fichiers d'entrée selon les indications de l'utilisateur - et des options de sortie pour contrôler le format des fichiers résultants.

Si plusieurs modifications doivent être effectuées, dcmodify les exécute dans le même ordre que celui dans lequel elles apparaissent sur la ligne de commande. Notez que dcmodify ne vérifie pas si une valeur donnée correspond à sa représentation de valeur (VR). En général, un message d'erreur est affiché, mais c'est à l'utilisateur de veiller à l'usage correct de la VR.

Si dcmodify ne connaît pas le tag qu'il doit insérer, la VR du tag est alors définie sur UN et la valeur fournie sur la ligne de commande est interprétée comme une suite de nombres hexadécimaux (comme cela se fait pour VR=OB). Insérez ces tags dans le dictionnaire pour éviter ce comportement. Par ailleurs, en spécifiant l'option -iun, il est possible de forcer dcmodify à laisser les valeurs UN intactes. L'option -u permet à dcmodify d'enregistrer tous les attributs VR=UN en tant qu'OB.

dcmodify est capable de travailler avec ce qu'on appelle des chemins de tags pour accéder aux tags dans les séquences. La syntaxe (pseudo-formalisée) est

{sequence[item-no].}*element

où 'sequence' est un tag de séquence tel que (0008,1111) ou un nom de dictionnaire pour un tag. 'item-no' décrit le numéro de l'item à accéder (en comptant à partir de zéro). 'element' définit le tag cible à traiter. Un tag peut être spécifié soit directement comme (0010,0010), soit via le nom de dictionnaire correspondant "PatientName". Le '' indique que vous pouvez répéter les instructions de séquence pour accéder à des niveaux plus profonds dans les fichiers DICOM (voir la section EXAMPLES). Pour 'item-no', un caractère générique '' peut également être utilisé pour sélectionner tous les items de la séquence englobante (voir la section WILDCARDS ci-dessous).

Lors de l'insertion de chemins de tags composés de plusieurs nœuds (c'est-à-dire pas un élément unique) avec l'option -i, tout élément de chemin manquant (item, séquence, élément terminal) est inséré automatiquement lorsqu'il fait défaut. Cela ne fonctionne pas avec les caractères génériques d'item : lorsqu'aucun item n'existe dans la séquence englobante, dcmodify ne peut évidemment pas décider combien d'items doivent être générés. En revanche, si un numéro d'item comme '5' est spécifié, les 6 items (comptés à partir de zéro) peuvent être (et sont) générés automatiquement en mode insertion. Si 2 items existaient déjà, les 4 restants seraient insérés.

dcmodify ne fonctionne pas sur les répertoires, c'est-à-dire que le paramètre dcmfile-in... ne doit pas inclure de noms de répertoires.

Notez qu'il existe quelques points d'attention concernant la modification des tags privés (voir la section PRIVATE TAGS) et le changement d'UID (voir la section CHANGING UIDs).

PARAMÈTRES

dcmfile-in  DICOM input filename(s) to be modified ("-" for stdin/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 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 informations méta du fichier
+fc --create-file: crée le format de fichier si le fichier n'existe pas. 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 méta 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. analyse des attributs de longueur impaire :
+ao --accept-odd-length: accepte les attributs de longueur impaire (par défaut)
+ae --assume-even-length: suppose que la longueur réelle est plus grande d'un octet. correction automatique des données :
+dc --enable-correction: active la correction automatique des données (par défaut)
-dc --disable-correction: désactive la correction automatique des données. format bitstream de l'entrée deflate :
+bd --bitstream-deflated: attend un bitstream deflate (par défaut)
+bz --bitstream-zlib: attend un bitstream zlib deflate

options de traitement

--backup: sauvegarde les fichiers avant modification (par défaut)
-nb --no-backup: ne sauvegarde pas les fichiers (DANGEREUX). mode insertion :
-i --insert "[t]ag-path=[v]alue": insère (ou écrase) le chemin à la position t avec la valeur v
-if --insert-from-file "[t]ag-path=[f]ilename": insère (ou écrase) le chemin à la position t avec la valeur du fichier f
-nrc --no-reserv-check: ne vérifie pas les réservations privées. mode modification :
-m --modify "[t]ag-path=[v]alue": modifie le tag à la position t avec la valeur v
-mf --modify-from-file "[t]ag-path=[f]ilename": modifie le tag à la position t avec la valeur du fichier f
-ma --modify-all "[t]ag=[v]alue": modifie TOUS les tags t correspondants du fichier avec la valeur v. mode suppression :
-e --erase "[t]ag-path": supprime le tag/item à la position t
-ea --erase-all "[t]ag": supprime TOUS les tags t correspondants du fichier
-ep --erase-private: supprime TOUTES les données privées du fichier. identifiant unique :
-gst --gen-stud-uid: génère un nouveau Study Instance UID
-gse --gen-ser-uid: génère un nouveau Series Instance UID
-gin --gen-inst-uid: génère un nouvel SOP Instance UID
-nmu --no-meta-uid: ne met pas à jour les UID du méta-en-tête si les UID associés du jeu de données sont modifiés. gestion des erreurs :
-ie --ignore-errors: poursuit avec le fichier en cas d'erreur de modification
-imt --ignore-missing-tags: traite 'tag not found' comme un succès lors de la modification ou de la suppression dans les fichiers
-iun --ignore-un-values: n'essaie pas d'écrire de valeurs dans les éléments dont la VR est UN

options de sortie

+F --write-file: écrit le format de fichier (par défaut)
-F --write-dataset: écrit le jeu de données sans les informations méta du fichier. syntaxe de transfert de sortie :
+t= --write-xfer-same: écrit avec la même TS que l'entrée (par défaut)
+te --write-xfer-little: écrit avec la TS explicit VR little endian
+tb --write-xfer-big: écrit avec la TS explicit VR big endian
+ti --write-xfer-implicit: écrit avec la TS implicit VR little endian. représentations de valeur postérieures à 1993 :
+u --enable-new-vr: active la prise en charge des nouvelles VR (UN/UT) (par défaut)
-u --disable-new-vr: désactive la prise en charge des nouvelles VR, convertit en OB. encodage de la longueur de groupe :
+g= --group-length-recalc: recalcule les longueurs de groupe si elles sont présentes (par défaut)
+g --group-length-create: écrit toujours avec les éléments de longueur de groupe
-g --group-length-remove: écrit toujours sans les éléments de longueur de groupe. encodage de la longueur dans les séquences et les items :
+le --length-explicit: écrit avec des longueurs explicites (par défaut)
-le --length-undefined: écrit avec des longueurs non définies. remplissage de fin de jeu de données (absent avec --write-dataset) :
-p= --padding-retain: ne modifie pas le remplissage (par défaut si --write-dataset n'est pas utilisé)
-p --padding-off: aucun remplissage (implicite avec --write-dataset)
+p --padding-create [f]ile-pad [i]tem-pad: integer: aligne le fichier sur un multiple de f octets et les items sur un multiple de i octets

TAGS PRIVÉS

Il existe quelques points d'attention à prendre en compte lorsqu'on travaille avec des tags privés. Cependant, l'insertion ou la modification d'un tag de réservation (gggg,00xx) devrait toujours fonctionner.

Insertions

Si vous souhaitez insérer un tag privé (pas une réservation avec gggg,00xx), assurez-vous de l'avoir répertorié dans votre dictionnaire (voir < docdir>/datadict.txt pour plus de détails). S'il n'y figure pas, dcmodify l'insérera avec VR=UN. Par ailleurs, dans certains cas, l'insertion peut même échouer pour certaines valeurs.

Si votre tag privé figure dans le dictionnaire, dcmodify procède comme suit. Lorsqu'il trouve une réservation dans le jeu de données englobant le tag, dont le créateur privé correspond, l'insertion se fait avec la VR trouvée dans le dictionnaire et la valeur donnée sur la ligne de commande. Mais si le créateur privé ne correspond pas ou si aucun n'est défini, dcmodify renverra une erreur. Si un tag privé doit être inséré indépendamment de l'existence d'une réservation, l'option -nrc peut être utilisée pour forcer l'insertion. Toutefois, la VR est alors définie sur UN, car le tag ne peut plus être trouvé dans le dictionnaire dans ce cas.

Voir la description ci-dessus pour savoir comment l'insertion de valeurs dans des éléments de VR inconnue est traitée.

Modifications

Si vous modifiez la valeur d'un tag privé, dcmodify ne vérifiera pas sa VR par rapport au dictionnaire. Veillez donc à ne saisir que des valeurs correspondant à la VR du tag.

Si vous souhaitez modifier la valeur et la VR d'un tag privé, parce que vous venez d'ajouter ce tag à votre dictionnaire, vous pouvez le supprimer avec dcmodify puis le réinsérer. dcmodify utilisera alors votre entrée de dictionnaire pour déterminer la VR correcte (voir aussi la sous-section Insertions).

Voir également la description ci-dessus pour savoir comment l'insertion de valeurs dans des éléments de VR inconnue est traitée.

Suppressions

Lorsque vous utilisez dcmodify pour supprimer un tag de réservation privé, notez que dcmodify ne touchera pas aux tags privés placés sous cette réservation. L'utilisateur doit assurer lui-même la cohérence entre les réservations et leurs tags privés associés.

Pour la suppression de tags privés hors réservation, il n'y a pas de point d'attention particulier.

CHANGEMENT DES UID

dcmodify corrige automatiquement 'Media Storage SOP Class UID' et 'Media Storage SOP Instance UID' dans le méta-en-tête si vous modifiez les tags associés du jeu de données ('SOP Class UID' et 'SOP Instance UID') via les options du mode insertion ou modification. Vous pouvez désactiver ce comportement avec l'option -nmu.

Si vous générez de nouveaux UID avec -gst, -gse ou -gin, cela n'affectera que l'UID que vous avez choisi de générer. Ainsi, si vous utilisez -gst pour générer un nouvel 'Study Instance UID', alors 'Series Instance UID' et 'SOP Instance UID' ne seront pas affectés ! Cela vous donne la possibilité de générer chaque valeur séparément. Normalement, vous modifieriez également les UID 'sous-jacents'. En contrepartie de cette flexibilité, l'utilisateur doit s'assurer que, lors de la création de fichiers DICOM 'nouveaux' avec de nouveaux UID via dcmodify, les autres UID sont mis à jour par l'utilisateur en fonction des besoins.

Lorsque l'option -gin est choisie, le tag de méta-en-tête associé ('Media Storage SOP Instance UID') est mis à jour automatiquement. Ce comportement ne peut pas être désactivé.

Lors du traitement de plusieurs fichiers d'entrée, dcmodify traite chaque fichier de manière isolée, c'est-à-dire qu'il génère des UID pour chaque fichier individuellement. Par exemple, avec l'option -gst, dcmodify insère un Study Instance UID différent dans chaque fichier au lieu d'en générer un seul et de l'écrire dans chaque fichier traité.

CRÉATION DE NOUVEAUX FICHIERS

L'option –create-file permet à dcmodify de créer un fichier s'il n'existe pas déjà sur le disque. On peut ainsi créer des fichiers à partir de zéro en effectuant des insertions successives avec des options telles que –insert. Cela peut se révéler particulièrement utile lors de la création de fichiers d'interrogation pour des outils comme findscu ou movescu. Si aucune syntaxe de transfert de sortie spécifique n'est définie, dcmodify choisit Little Endian Explicit Uncompressed pour la sortie. Les fichiers nouvellement créés sont toujours écrits au format de fichier DICOM, c'est-à-dire que l'option –write-dataset n'est pas autorisée avec –create. Ainsi, le méta-en-tête au moins est écrit et aucun fichier de longueur nulle n'est créé dans le cas où aucune insertion n'est effectuée lors de l'appel de dcmodify.

VALEURS D'ÉLÉMENT DEPUIS UN FICHIER

Pour lire la valeur d'un élément depuis un fichier plutôt que de la spécifier sur la ligne de commande, les options -mf et -if peuvent être utilisées. Notez que pour les éléments OW, les données sont attendues dans l'ordre little endian et leurs octets seront permutés si nécessaire. La taille du fichier devrait toujours être un nombre pair d'octets, c'est-à-dire qu'aucun remplissage automatique n'est effectué.

CARACTÈRES GÉNÉRIQUES

dcmodify permet également l'utilisation d'un caractère générique "" pour les numéros d'item dans les expressions de chemin, par exemple "ContentSequence[].CodeValue" sélectionne tous les attributs "Code Value" dans tous les items de ContentSequence. L'utilisation d'un caractère générique est possible pour toutes les opérations de base, à savoir la modification -m, l'insertion -i et les options -e, ce qui en fait, avec la création automatique des nœuds de chemin intermédiaires, un outil puissant pour la construction et le traitement de jeux de données complexes.

Les options -ma et -ea, qui permettent de modifier ou de supprimer toutes les occurrences d'un élément DICOM d'après son tag, n'acceptent aucun caractère générique et ne fonctionnent que sur des éléments uniques (c'est-à-dire un seul nom de dictionnaire ou une seule clé de tag).

EXEMPLES

-i --insert:: dcmodify -i "(0010,0010)=A Name" file.dcm Insère le tag PatientName dans 'file.dcm' au 1er niveau. Si le tag existe déjà, -i l'écrasera ! Si vous souhaitez insérer un élément avec une multiplicité de valeur supérieure à 1 (par exemple 4), vous pouvez le faire ainsi : dcmodify -i "(0018,1310)=1\\2\\3\\4" dcmodify -i "(0008,1111)[0].PatientName=Another Name" .dcm Insère le tag PatientName dans le premier item de la séquence (0008,1111). Notez que l'utilisation de caractères génériques pour les fichiers est possible. Vous pouvez également spécifier des chemins de tags plus longs (par exemple "(0008,1111)[0].(0008,1111)[1].(0010,0010)=A Third One"). Si une partie du chemin, par exemple la séquence ou l'item "0", n'existe pas, elle est insérée automatiquement par dcmodify. dcmodify -i "(0008,1111)[].PatientName=Another Name" .dcm Insère le tag PatientName dans chaque item de la séquence (0008,1111). Notez que l'utilisation de caractères génériques pour les fichiers est possible. Vous pouvez également spécifier des chemins de tags plus longs (par exemple "(0008,1111)[].(0008,1111)[*].(0010,0010)=A Third One").
-if --insert-from-file:: dcmodify -if "PixelData=pixel.raw" file.dcm Insère le contenu du fichier 'pixel.raw' dans l'élément PixelData de 'file.dcm'. Le contenu du fichier sera lu tel quel. Les données OW sont attendues dans l'ordre little endian et leurs octets seront permutés si nécessaire. Aucune vérification n'est effectuée pour s'assurer que la quantité de données est cohérente avec d'autres attributs tels que Rows ou Columns.
-m --modify:: dcmodify -m "(0010,0010)=A Name" file.dcm Change le tag (0010,0010) au 1er niveau en "A Name". Cette option permet également des chemins de tags plus longs comme montré ci-dessus pour -i. Si l'élément terminal ou une partie intermédiaire du chemin n'existe pas, il n'est pas inséré comme ce serait le cas avec l'option '-i'. dcmodify -m "(0010,0010)=A Name" -imt file.dcm Change le tag (0010,0010) au 1er niveau en "A Name". Grâce à l'option '-imt' donnée, un succès est renvoyé au lieu de "tag not found" si l'élément/item (ou tout nœud intermédiaire dans un chemin plus long) n'existe pas. Notez que pour l'option '-m', le dernier nœud du chemin doit être un élément terminal, c'est-à-dire ni une séquence ni un item.
-mf --modify-from-file:: dcmodify -mf "PixelData=pixel.raw" file.dcm Fait la même chose que -if s'il existait déjà un élément PixelData dans 'file.dcm'. Sinon, rien n'est modifié.
-ma --modify-all:: dcmodify -ma "(0010,0010)=New Name" file.dcm Fait la même chose que -m mais agit sur tous les tags correspondants trouvés dans 'file.dcm'. Il recherche donc le tag (0010,0010) dans l'ensemble du jeu de données, y compris dans les séquences, et le change en "New Name"
-e --erase:: dcmodify -e "(0010,0010)" .dcm Supprime le tag (0010,0010) dans tous les fichiers .dcm au 1er niveau. Cette option permet également des chemins de tags plus longs comme montré ci-dessus pour -i. dcmodify -e "(0010,0010)" -imt .dcm Supprime le tag (0010,0010) dans tous les fichiers .dcm au 1er niveau. Grâce à l'option '-imt' donnée, un succès est renvoyé au lieu de "tag not found" si l'élément/item (ou tout nœud intermédiaire dans un chemin plus long) n'existe pas.
-ea --erase-all:: dcmodify -ea "(0010,0010)" *.dcm Identique à -e, mais recherche aussi dans les séquences et les items.
-ep --erase-private:: dcmodify -ep .dcm Supprime tous les tags privés (c'est-à-dire les tags dont le numéro de groupe est impair) de tous les fichiers correspondant à .dcm dans le répertoire courant.
-gst --gen-stud-uid:: dcmodify -gst file.dcm Ceci génère une nouvelle valeur pour le StudyInstanceUID (0020,000d). Les autres UID ne sont pas modifiés !
-gse --gen-ser-uid:: dcmodify -gse file.dcm Ceci génère une nouvelle valeur pour le SeriesInstanceUID (0020,000e). Les autres UID ne sont pas modifiés !
-gin --gen-inst-uid:: dcmodify -gin file.dcm Cette commande génère une nouvelle valeur pour le SOPInstanceUID (0008,0018). Le MediaStorageSOPInstanceUID (0002,0003) correspondant est ajusté automatiquement à la nouvelle valeur. Notez qu'il n'est pas possible d'éviter cette mise à jour du méta-en-tête via l'option -nmu.
-nmu --no-meta-uid:: dcmodify -m "SOPInstanceUID=[UID]" -nmu *.dcm Ceci modifie le SOPInstanceUID avec l'[UID] donné, mais -nmu évite que dcmodify ajuste également le MediaStorageSOPInstanceUID dans le méta-en-tête.

GESTION DES ERREURS

dcmodify tente d'exécuter chaque opération de modification donnée sur la ligne de commande : si l'une renvoie une erreur, les autres sont quand même exécutées. Toutefois, en cas d'erreur, le fichier modifié n'est pas enregistré, sauf si l'option –ignore-errors est spécifiée. Si cette option est sélectionnée, dcmodify poursuit également la modification des autres fichiers spécifiés sur la ligne de commande ; sinon, dcmodify s'arrête après le premier fichier ayant rencontré des erreurs de modification.

Si l'option –ignore-missing-tags est activée, toute opération de modification ou de suppression (c'est-à-dire hors –insert) qui échoue en raison d'un tag inexistant est traitée comme un succès. Cela a du sens si l'on veut s'assurer que certains tags sont absents du fichier ou que, s'ils existent, ils ont une valeur spécifique.

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 dcmodify 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 (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é.