dcmodify: DICOM ファイルを編集する

書式

dcmodify [options] dcmfile-in...

説明

dcmodify は DICOM ファイル内のタグやアイテムを編集・挿入・削除するツールです。シーケンスや、値多重度（VM）が 1 を超えるタグも扱えます。現時点では、メタヘッダ情報やタグの VR を dcmodify で直接変更することはできません。タグの編集に加えて、dcmodify には入力ファイルの扱いをユーザー指定どおりに強制する入力オプションと、出力ファイルの形式を制御する出力オプションが用意されています。

複数の編集を行う場合、dcmodify はコマンドラインに現れた順序どおりに編集を実行します。なお、dcmodify は与えられた値がその値表現（VR）に合致するかどうかをチェックしない点に注意してください。通常はエラーメッセージが表示されますが、基本的には正しい VR を使うのはユーザーの責任です。

挿入しようとするタグを dcmodify が知らない場合、そのタグの VR は UN に設定され、コマンドラインで与えた値は（VR=OB のときと同様に）16 進数の並びとして解釈されます。この挙動を避けるには、これらのタグを辞書に登録してください。また -iun オプションを指定すれば、UN 値に手を加えないよう dcmodify に強制できます。-u オプションを使うと、VR=UN の属性をすべて OB として保存します。

dcmodify は、いわゆるタグパスを使ってシーケンス内のタグにアクセスできます。（疑似的に形式化した）構文は次のとおりです。

{sequence[item-no].}*element

ここで 'sequence' は (0008,1111) のようなシーケンスタグ、またはタグの辞書名です。'item-no' はアクセスするアイテム番号（0 から数える）を表します。'element' は処理対象のタグを指します。タグは (0010,0010) のように直接指定するか、対応する辞書名 "PatientName" で指定できます。'' は、DICOM ファイル内のより深い階層にアクセスするためにシーケンス指定を繰り返せることを表します（EXAMPLES の節を参照）。'item-no' には、囲んでいるシーケンス内のすべてのアイテムを選択するワイルドカード文字 '' も使えます（後述の WILDCARDS の節を参照）。

-i オプションで複数ノードからなるタグパス（単一の要素ではないパス）を挿入するとき、欠けているパス要素（アイテム、シーケンス、リーフ要素）があれば自動的に挿入されます。ただしアイテムのワイルドカードでは機能しません。囲んでいるシーケンスにアイテムが 1 つも存在しない場合、生成すべきアイテム数を dcmodify が決められないからです。一方、'5' のようにアイテム番号を指定すれば、挿入モードでは（0 から数えて）6 個すべてのアイテムを自動生成できます（実際に生成されます）。すでに 2 個のアイテムが存在していれば、残りの 4 個が挿入されます。

dcmodify はディレクトリに対しては動作しません。つまり引数 dcmfile-in... にディレクトリ名を含めてはなりません。

プライベートタグの編集（PRIVATE TAGS の節を参照）と UID の変更（CHANGING UIDs の節を参照）にはいくつか注意点がある点に留意してください。

引数

dcmfile-in  DICOM input filename(s) to be modified ("-" for stdin/stdout)

オプション

全般オプション

-h --help: このヘルプを表示して終了します
--version: バージョン情報を表示して終了します
--arguments: 展開後のコマンドライン引数を表示します
-q --quiet: 静音モード。警告とエラーを表示しません
-v --verbose: 詳細表示モード。処理の詳細を表示します
-d --debug: デバッグモード。デバッグ情報を表示します
-ll --log-level [l]evel: string constant: (fatal, error, warn, info, debug, trace) ロガーにレベル l を使います
-lc --log-config [f]ilename: string: ロガーに設定ファイル f を使います

入力オプション

+f --read-file: ファイル形式またはデータセットとして読みます（既定値）
+fo --read-file-only: ファイル形式としてのみ読みます
-f --read-dataset: ファイルメタ情報なしのデータセットとして読みます
+fc --create-file: ファイルが存在しない場合にファイル形式を作成します。入力転送構文:
-t= --read-xfer-auto: TS 自動判定を使います（既定値）
-td --read-xfer-detect: ファイルメタヘッダで指定された TS を無視します
-te --read-xfer-little: explicit VR リトルエンディアン TS で読みます
-tb --read-xfer-big: explicit VR ビッグエンディアン TS で読みます
-ti --read-xfer-implicit: implicit VR リトルエンディアン TS で読みます。奇数長属性の解析:
+ao --accept-odd-length: 奇数長の属性を受け入れます（既定値）
+ae --assume-even-length: 実際の長さが 1 バイト大きいものとみなします。自動データ補正:
+dc --enable-correction: 自動データ補正を有効にします（既定値）
-dc --disable-correction: 自動データ補正を無効にします。deflate 入力のビットストリーム形式:
+bd --bitstream-deflated: deflate 圧縮ビットストリームを期待します（既定値）
+bz --bitstream-zlib: deflate 圧縮 zlib ビットストリームを期待します

処理オプション

--backup: 編集前にファイルをバックアップします（既定値）
-nb --no-backup: ファイルをバックアップしません（危険）。挿入モード:
-i --insert "[t]ag-path=[v]alue": 位置 t のパスに値 v を挿入します（既存なら上書きします）
-if --insert-from-file "[t]ag-path=[f]ilename": 位置 t のパスにファイル f の値を挿入します（既存なら上書きします）
-nrc --no-reserv-check: プライベート予約をチェックしません。編集モード:
-m --modify "[t]ag-path=[v]alue": 位置 t のタグを値 v に編集します
-mf --modify-from-file "[t]ag-path=[f]ilename": 位置 t のタグをファイル f の値に編集します
-ma --modify-all "[t]ag=[v]alue": ファイル内で一致するタグ t をすべて値 v に編集します。消去モード:
-e --erase "[t]ag-path": 位置 t のタグ／アイテムを消去します
-ea --erase-all "[t]ag": ファイル内で一致するタグ t をすべて消去します
-ep --erase-private: ファイルからすべてのプライベートデータを消去します。一意識別子:
-gst --gen-stud-uid: 新しい Study Instance UID を生成します
-gse --gen-ser-uid: 新しい Series Instance UID を生成します
-gin --gen-inst-uid: 新しい SOP Instance UID を生成します
-nmu --no-meta-uid: データセット内の関連 UID を編集してもメタヘッダの UID を更新しません。エラー処理:
-ie --ignore-errors: 編集エラーが発生してもそのファイルの処理を続けます
-imt --ignore-missing-tags: ファイルの編集・消去時に「タグが見つからない」を成功として扱います
-iun --ignore-un-values: VR が UN の要素には値を書き込みません

出力オプション

+F --write-file: ファイル形式で書き出します（既定値）
-F --write-dataset: ファイルメタ情報なしのデータセットとして書き出します。出力転送構文:
+t= --write-xfer-same: 入力と同じ TS で書き出します（既定値）
+te --write-xfer-little: explicit VR リトルエンディアン TS で書き出します
+tb --write-xfer-big: explicit VR ビッグエンディアン TS で書き出します
+ti --write-xfer-implicit: implicit VR リトルエンディアン TS で書き出します。1993 年以降の値表現:
+u --enable-new-vr: 新しい VR（UN/UT）のサポートを有効にします（既定値）
-u --disable-new-vr: 新しい VR のサポートを無効にし、OB に変換します。グループ長の符号化:
+g= --group-length-recalc: グループ長があれば再計算します（既定値）
+g --group-length-create: 常にグループ長要素を付けて書き出します
-g --group-length-remove: 常にグループ長要素なしで書き出します。シーケンスとアイテムの長さ符号化:
+le --length-explicit: 明示的な長さで書き出します（既定値）
-le --length-undefined: 未定義長で書き出します。データセット末尾のパディング（--write-dataset 時は不可）:
-p= --padding-retain: パディングを変更しません（--write-dataset でない場合の既定値）
-p --padding-off: パディングなし（--write-dataset 時は暗黙的にこの動作）
+p --padding-create [f]ile-pad [i]tem-pad: integer: ファイルを f バイトの倍数に、アイテムを i バイトの倍数に整列します

プライベートタグ

プライベートタグを扱うときに考慮すべき注意点がいくつかあります。ただし、予約タグ (gggg,00xx) の挿入・編集は常に機能するはずです。

挿入

プライベートタグ（gggg,00xx の予約ではないもの）を挿入したい場合は、辞書に登録されていることを確認してください（詳細は < docdir>/datadict.txt を参照）。登録されていない場合、dcmodify は VR=UN として挿入します。また、値によっては挿入そのものが失敗することもあります。

辞書にプライベートタグが登録されている場合、dcmodify は次のように動作します。タグを囲むデータセット内に、プライベートクリエータが一致する予約が見つかれば、辞書にある VR とコマンドラインで与えた値で挿入が行われます。しかしプライベートクリエータが一致しない、または予約が設定されていない場合、dcmodify はエラーを返します。予約が存在しなくてもプライベートタグを挿入したい場合は、-nrc オプションを使って挿入を強制できます。ただしその場合はタグが辞書で見つからなくなるため、VR は UN に設定されます。

VR が不明な要素への値の挿入がどう扱われるかは、前述の説明を参照してください。

編集

プライベートタグの値を編集する場合、dcmodify はその VR を辞書と照合しません。したがって、タグの VR に合致する値だけを入力するよう注意してください。

プライベートタグの値と VR を変更したい場合（辞書にこのタグを追加したばかりのときなど）は、dcmodify でいったん削除してから再挿入できます。そうすれば dcmodify は辞書のエントリを使って正しい VR を決定します（挿入の項も参照）。

VR が不明な要素への値の挿入がどう扱われるかも、前述の説明を参照してください。

削除

dcmodify でプライベート予約タグを削除する場合、dcmodify はその予約配下のプライベートタグには手を付けない点に注意してください。予約とそれに紐づくプライベートタグの整合性は、ユーザーが管理する必要があります。

予約以外のプライベートタグの削除には、特別な注意点はありません。

UID の変更

挿入モードや編集モードのオプションでデータセット内の関連タグ（'SOP Class UID' と 'SOP Instance UID'）を変更すると、dcmodify はメタヘッダ内の 'Media Storage SOP Class UID' と 'Media Storage SOP Instance UID' を自動的に補正します。この挙動は -nmu オプションで無効にできます。

-gst 、-gse 、-gin で新しい UID を生成した場合、影響を受けるのは生成を選んだ UID だけです。つまり -gst で新しい 'Study Instance UID' を生成しても、'Series Instance UID' や 'SOP Instance UID' は影響を受けません。これにより各値を個別に生成できます。通常はこれに連なる UID も併せて編集することになるでしょう。この柔軟性の裏返しとして、dcmodify で新しい UID を持つ「新規」DICOM ファイルを作成する際、必要に応じて他の UID を更新するのはユーザーの責任となります。

-gin オプションを選んだ場合、関連するメタヘッダタグ（'Media Storage SOP Instance UID'）は自動的に更新されます。この挙動は無効にできません。

複数の入力ファイルを処理する場合、dcmodify は各ファイルを独立して処理します。つまりファイルごとに UID を生成します。例えば -gst オプションを使うと、dcmodify は単一の UID を生成してすべてのファイルに書き込むのではなく、各ファイルに異なる Study Instance UID を挿入します。

新しいファイルの作成

–create-file オプションを使うと、ディスク上にまだ存在しないファイルを dcmodify が作成します。これを使えば、–insert などのオプションで挿入を連続して行い、ファイルをゼロから作成できます。findscu や movescu のようなツール向けの問い合わせファイルを作成するときに特に便利でしょう。出力転送構文が特に指定されていない場合、dcmodify は出力に Little Endian Explicit Uncompressed を選びます。新規作成されるファイルは常に DICOM ファイル形式で書き出されます。つまり –write-dataset オプションを –create と併用することはできません。これにより少なくともメタヘッダは書き込まれ、dcmodify の呼び出しで挿入が一切行われなかった場合でも、長さ 0 バイトのファイルが作られることはありません。

ファイルから読み込む要素値

要素の値をコマンドラインで指定する代わりにファイルから読み込むには、-mf と -if オプションが使えます。なお OW 要素では、データはリトルエンディアン順であることが前提で、必要に応じてスワップされます。ファイルサイズは常に偶数バイトであるべきで、自動パディングは行われません。

ワイルドカード

dcmodify は、パス式中のアイテム番号にワイルドカード文字 "" を使うことも許しています。例えば "ContentSequence[].CodeValue" は、ContentSequence のすべてのアイテム内のすべての "Code Value" 属性を選択します。ワイルドカードは基本操作のすべて、すなわち編集 -m 、挿入 -i 、消去 -e の各オプションで使え、中間パスノードの自動生成と組み合わせることで、複雑なデータセットの構築・処理に役立つ手段となります。

タグを指定して DICOM 要素の出現箇所すべてを編集または削除する -ma と -ea オプションは、ワイルドカードを受け付けず、単一の要素（単一の辞書名またはタグキー）に対してのみ動作します。

例

-i --insert:: dcmodify -i "(0010,0010)=A Name" file.dcm 'file.dcm' の第 1 階層に PatientName タグを挿入します。タグがすでに存在する場合、-i は上書きします。値多重度が 1 を超える（例えば 4 の）要素を挿入したい場合は次のようにできます: dcmodify -i "(0018,1310)=1\\2\\3\\4" dcmodify -i "(0008,1111)[0].PatientName=Another Name" .dcm シーケンス (0008,1111) の最初のアイテムに PatientName タグを挿入します。ファイル名にワイルドカードを使える点に注意してください。より長いタグパスも指定できます（例 "(0008,1111)[0].(0008,1111)[1].(0010,0010)=A Third One"）。パスの一部、例えばシーケンスやアイテム "0" が存在しない場合は、dcmodify が自動的に挿入します。dcmodify -i "(0008,1111)[].PatientName=Another Name" .dcm シーケンス (0008,1111) の すべての アイテムに PatientName タグを挿入します。ファイル名にワイルドカードを使える点に注意してください。より長いタグパスも指定できます（例 "(0008,1111)[].(0008,1111)[*].(0010,0010)=A Third One"）。
-if --insert-from-file:: dcmodify -if "PixelData=pixel.raw" file.dcm 'file.dcm' の PixelData 要素にファイル 'pixel.raw' の内容を挿入します。ファイルの内容はそのまま読み込まれます。OW データはリトルエンディアン順であることが前提で、必要に応じてスワップされます。データ量が Rows や Columns といった他の属性に照らして妥当かどうかのチェックは行われません。
-m --modify:: dcmodify -m "(0010,0010)=A Name" file.dcm 第 1 階層のタグ (0010,0010) を "A Name" に変更します。このオプションも、-i について上で示したように長いタグパスを許します。リーフ要素やパスの中間部分が存在しない場合、'-i' オプションのようには挿入されません。dcmodify -m "(0010,0010)=A Name" -imt file.dcm 第 1 階層のタグ (0010,0010) を "A Name" に変更します。'-imt' オプションを指定したため、要素／アイテム（または長いパス中の中間ノード）が存在しなくても "tag not found" ではなく成功が返ります。'-m' オプションでは、パスの最後のノードがリーフ要素でなければならない（シーケンスやアイテムは不可）点に注意してください。
-mf --modify-from-file:: dcmodify -mf "PixelData=pixel.raw" file.dcm 'file.dcm' にすでに PixelData 要素があった場合は -if と同じ動作をします。なければ何も変更されません。
-ma --modify-all:: dcmodify -ma "(0010,0010)=New Name" file.dcm -m と同じだが、'file.dcm' 内で見つかった一致するタグすべてに対して動作します。したがってシーケンスを含むデータセット全体からタグ (0010,0010) を検索し、それらを "New Name" に変更します
-e --erase:: dcmodify -e "(0010,0010)" .dcm すべての .dcm ファイルの第 1 階層でタグ (0010,0010) を消去します。このオプションも、-i について上で示したように長いタグパスを許します。dcmodify -e "(0010,0010)" -imt .dcm すべての .dcm ファイルの第 1 階層でタグ (0010,0010) を消去します。'-imt' オプションを指定したため、要素／アイテム（または長いパス中の中間ノード）が存在しなくても "tag not found" ではなく成功が返ります。
-ea --erase-all:: dcmodify -ea "(0010,0010)" *.dcm -e と同じだが、シーケンスやアイテム内も検索します。
-ep --erase-private:: dcmodify -ep .dcm カレントディレクトリの .dcm に一致するすべてのファイルから、プライベートタグ（すなわちグループ番号が奇数のタグ）をすべて削除します。
-gst --gen-stud-uid:: dcmodify -gst file.dcm StudyInstanceUID (0020,000d) に新しい値を生成します。他の UID は編集されません。
-gse --gen-ser-uid:: dcmodify -gse file.dcm SeriesInstanceUID (0020,000e) に新しい値を生成します。他の UID は編集されません。
-gin --gen-inst-uid:: dcmodify -gin file.dcm このコマンドは SOPInstanceUID (0008,0018) に新しい値を生成します。対応する MediaStorageSOPInstanceUID (0002,0003) は新しい値に自動調整されます。なお、このメタヘッダ更新を -nmu オプションで回避することはできない点に注意してください。
-nmu --no-meta-uid:: dcmodify -m "SOPInstanceUID=[UID]" -nmu *.dcm SOPInstanceUID を指定した [UID] に編集しますが、-nmu によって dcmodify がメタヘッダの MediaStorageSOPInstanceUID も調整するのを防ぎます。

エラー処理

dcmodify はコマンドラインで与えられた各編集操作を実行しようとします。ある操作がエラーを返しても、他の操作はそのまま実行されます。ただしいずれかでエラーが起きた場合、–ignore-errors オプションを指定しない限り、編集後のファイルは保存されません。このオプションを選ぶと、dcmodify はコマンドラインで指定された後続のファイルの編集も続行します。指定しない場合、dcmodify は編集エラーのあった最初のファイルの後で終了します。

–ignore-missing-tags オプションを有効にすると、存在しないタグが原因で失敗する編集・消去操作（–insert 以外）は成功として扱われます。これは、特定のタグがファイルに存在しないこと、あるいは存在する場合に特定の値が設定されていることを確実にしたいときに役立ちます。

ロギング

各種コマンドラインツールおよび基盤ライブラリのロギング出力のレベルはユーザーが指定できます。既定ではエラーと警告だけが標準エラー出力に書き出されます。–verbose オプションを使うと、処理の詳細などの情報メッセージも報告されます。–debug オプションは、内部動作のより詳しい情報（デバッグ目的など）を得るために使えます。他のロギングレベルは –log-level オプションで選択できます。–quiet モードでは致命的エラーのみ報告されます。そうした非常に深刻なエラーが起きた場合、アプリケーションは通常終了します。各ロギングレベルの詳細は、モジュール "oflog" のドキュメントを参照してください。

ロギング出力をファイル（任意でログローテーション付き）、syslog（Unix）、またはイベントログ（Windows）に書き出したい場合は、–log-config オプションが使えます。この設定ファイルでは、特定のメッセージだけを特定の出力ストリームに振り向けたり、メッセージを生成したモジュールやアプリケーションに基づいて特定のメッセージを絞り込んだりもできます。設定ファイルの例は < etcdir>/logger.cfg に用意されています。

コマンドライン

すべてのコマンドラインツールは、引数について次の表記を用います。角括弧は省略可能な値（0〜1）を囲み、末尾の 3 つのドットは複数の値が許されること（1〜n）を示し、両者の組み合わせは 0〜n 個の値を意味します。

コマンドラインオプションは、先頭の '+' または '-' 記号によって引数と区別されます。通常、コマンドラインオプションの順序や位置は任意です（どこに現れてもよい）。ただしオプションが互いに排他的な場合は、最も右にある指定が使われます。この挙動は一般的な Unix シェルの標準的な評価規則に準じます。

さらに、ファイル名の前に '@' 記号を付けることで、1 つ以上のコマンドファイルを指定できます（例 @command.txt）。このようなコマンド引数は、それ以上の評価が行われる前に、対応するテキストファイルの内容で置き換えられます（連続する空白は、引用符で囲まれていない限り単一の区切りとして扱われます）。なお、コマンドファイルが別のコマンドファイルを含むことはできません。この単純ながら効果的な仕組みにより、よく使うオプションや引数の組み合わせをまとめられ、長く分かりにくいコマンドラインを避けられます（例は < datadir>/dumppat.txt に用意されています）。

環境変数

dcmodify ユーティリティは、環境変数 DCMDICTPATH で指定された DICOM データ辞書を読み込もうとします。既定では、すなわち DCMDICTPATH 環境変数が設定されていない場合、辞書がアプリケーションに組み込まれていない限り（Windows では既定で組み込み）、ファイル < datadir>/dicom.dic が読み込まれます。

通常は既定の挙動が望ましく、DCMDICTPATH 環境変数は別のデータ辞書が必要な場合にのみ使うべきです。DCMDICTPATH 環境変数は Unix シェルの PATH 変数と同じ形式で、コロン（":"）でエントリを区切ります。Windows システムではセミコロン（";"）を区切りに使います。データ辞書のコードは DCMDICTPATH 環境変数で指定された各ファイルを読み込もうとします。データ辞書を 1 つも読み込めない場合はエラーとなります。