dcm2xml: DICOMファイルとデータセットをXMLへ変換する

書式

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

説明

dcm2xml ユーティリティは、DICOMファイル（ファイル形式または生のデータセット）の内容をXML（Extensible Markup Language）に変換します。出力形式は2種類あります。1つ目はDCMTK固有の形式で、そのDTD（Document Type Definition）は dcm2xml.dtd ファイルに記述されています。2つ目はDICOM part 19 のDICOM Application Hostingサービス向けに規定された「Native DICOM Model」に準拠した形式です。

dcm2xml が生のデータセット（ファイル形式のメタヘッダを持たないDICOMデータ）を読み込む場合、ファイル先頭の数バイトを調べて転送構文を推測しようとします。転送構文を正しく推測できるとは限らないため、可能な限り（dcmconv ユーティリティを使って）データセットをファイル形式に変換しておくほうがよいでしょう。また、-f と -t[ieb] オプションを使って、特定の転送構文でデータセットを読み込むよう dcm2xml に指示することもできます。

引数

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

xmlfile-out  XML output filename (default: stdout)

オプション

全般オプション

-h --help: このヘルプを表示して終了します
--version: バージョン情報を表示して終了します
--arguments: 展開後のコマンドライン引数を表示します
-q --quiet: quietモード。警告やエラーを表示しません
-v --verbose: verboseモード。処理の詳細を表示します
-d --debug: 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: ファイルメタ情報なしのデータセットを読み込みます。入力転送構文:
-t= --read-xfer-auto: TS（転送構文）の自動認識を使用します（既定値）
-td --read-xfer-detect: ファイルメタヘッダで指定されたTSを無視します
-te --read-xfer-little: explicit VR little endian TS で読み込みます
-tb --read-xfer-big: explicit VR big endian TS で読み込みます
-ti --read-xfer-implicit: implicit VR little endian TS で読み込みます。長いタグ値の扱い:
+M --load-all: 非常に長いタグ値（例: ピクセルデータ）を読み込みます
-M --load-short: 非常に長い値は読み込みません（既定値）
+R --max-read-length [k]bytes: integer (4..4194302, default: 4): 長い値とみなす閾値を k キロバイトに設定します

処理オプション

+Cr --charset-require: 拡張文字集合の宣言を必須とします（既定値）
+Ca --charset-assume [c]harset: string: 拡張文字集合が宣言されていない場合に文字集合 c を仮定します
+Cc --charset-check-all: 文字列値を持つすべてのデータ要素を検査します（既定値: PN, LO, LT, SH, ST, UC, UT のみ） # このオプションは、Specific Character Set (0008,0005) 属性が存在すべきかどうかの # 拡張チェックにのみ使われ、影響を受けない要素値（例: VR が CS の # 要素値）のUTF-8変換には使われません
+U8 --convert-to-utf8: Specific Character Set (0008,0005) の影響を受けるすべての要素値をUTF-8に変換します # これには下層の文字エンコーディングライブラリのサポートが必要です # （どのライブラリが利用可能かは --version の出力を参照）

出力オプション

-dtk --dcmtk-format: DCMTK固有の形式で出力します（既定値）
-nat --native-format: Native DICOM Model形式（part 19）で出力します
+Xn --use-xml-namespace: ルート要素にXML名前空間宣言を追加します。DCMTK固有形式（--native-format と併用不可）:
+Xd --add-dtd-reference: document type definition（DTD）への参照を追加します
+Xe --embed-dtd-content: document type definitionをXML文書に埋め込みます
+Xf --use-dtd-file [f]ilename: string: 指定したDTDファイルを使用します（+Xe と併用時のみ）（既定値: /usr/local/share/dcmtk-/dcm2xml.dtd）
+Wn --write-element-name: DICOMデータ要素の名前を書き出します（既定値）
-Wn --no-element-name: DICOMデータ要素の名前を書き出しません
+Wb --write-binary-data: OBおよびOW要素のバイナリデータを書き出します（既定値: off。--load-all との併用には注意）。バイナリデータのエンコード:
+Eh --encode-hex: バイナリデータを16進数としてエンコードします（DCMTK固有形式の既定値）
+Eu --encode-uuid: バイナリデータをUUID参照としてエンコードします（Native DICOM Modelの既定値）
+Eb --encode-base64: バイナリデータをBase64（RFC 2045, MIME）としてエンコードします

DCMTK形式

DICOMファイルから生成されるDCMTK固有のXML出力の基本構造は次のようになります。

<?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>

"file-format" タグと "meta-header" タグは、DICOMデータセットの場合には存在しません。

XMLエンコーディング

非常に大きな値フィールドを持つ属性（例: ピクセルデータ）は、既定では読み込まれません。これらは値が "no" の追加属性 "loaded" で識別できます（上の例を参照）。コマンドラインオプション –load-all を指定すると、非常に長いものも含めてすべての値フィールドを読み込みます。

さらに、OBおよびOW属性のバイナリデータは、既定ではXML出力ファイルに書き出されません。これらの要素は値が "hidden" の追加属性 "binary" で識別できます（既定値は "no"）。コマンドラインオプション –write-binary-data を指定すると、バイナリの値フィールドも出力されます（属性値は "yes" または "base64"）。ただし、このオプションを –load-all と併用する際は、大量のピクセルデータが出力されかねないため注意してください。なお、この文脈では VR が OD, OF, OL, OV の要素値は「バイナリデータ」とはみなしません。

複数の値（すなわちDICOMの値多重度が1より大きい場合）は、バックスラッシュ "\" で区切られます（Base64エンコードされたデータを除く）。"len" 属性は、DICOMデータセットに格納された当該値フィールドのバイト数を示します。つまり、たとえば除去された非有意なパディングのために、XMLエンコードされた値の長さとは異なる場合があります。この属性が "sequence" や "item" の開始タグに存在しない場合、対応するDICOM要素は未定義長で格納されています。

Native DICOM Model形式

Native DICOM Model形式の説明は、DICOM規格 part 19（"Application Hosting"）にあります。

バルクデータ

バイナリデータ、すなわち VR が OB または OW のDICOM要素値、ならびに OD, OF, OL, OV, UN の値は、そのサイズのため既定ではXML出力に書き出されません。代わりに各要素ごとに新しいUUID（Universally Unique Identifier）が生成され、 XML要素の属性として書き出されます。今のところ、バイナリデータの各チャンクを保持する追加ファイルを書き出す手段はありません。これは規格で要求されてはいないが、Application Hostingインターフェースの実装には役立つ可能性があり、今後のバージョンの dcm2xml でこの機能が提供されるかもしれません。

加えて、Supplement 163（Store Over the Web by Representational State Transfer Services）は、バイナリデータをBase64としてエンコードできる新しい XML要素を導入しました。現在、コマンドラインオプション –encode-base64 は次のVRに対してこのエンコードを有効にします: OB, OD, OF, OL, OV, OW, UN。

既知の問題

上記の「バルクデータ」の節に記したことに加えて、現在のNative DICOM Model形式の実装にはさらに既知の問題があります。たとえば、OB, OD, OF, OL, OV, OW, UN 以外のVRを持つ大きな要素値は、現状では決してバルクデータとして書き出されません。非常に長いテキスト要素（特にUT）や、各種VRの非常に長い数値フィールドなどでは、バルクデータとして書き出すほうが役立つ場合があるにもかかわらず、です。

注記

文字エンコーディング

XMLの文字エンコーディングは、DICOM属性 (0008,0005) "Specific Character Set" から次のマッピングに従って自動的に決定されます。

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"

このDICOM属性が必要であるのに入力ファイルに存在しない場合は、–charset-assume オプションを使って（DICOM定義語のいずれかで）適切な文字集合を手動で指定できます。本ツールの旧バージョンとの後方互換性のため、次の語もサポートされ、関連するDICOM定義語へ自動的にマッピングされます: latin-1, latin-2, latin-3, latin-4, latin-5, latin-9, cyrillic, arabic, greek, hebrew。

コード拡張技術を用いた複数文字集合はサポートされません。必要な場合は、–convert-to-utf8 オプションを使って、XML形式への変換に先立ってDICOMファイルまたはデータセットをUTF-8エンコーディングに変換できます。これは、各ディレクトリレコードが異なる文字集合を持ちうるDICOMDIRファイルでも有用です。

マッピングが定義されておらず、–convert-to-utf8 オプションも使われていない場合、非ASCII文字および #32 未満の文字は "&#nnn;"（"nnn" は数値の文字コードを指す）として格納されます。これは（ESCに対する "" のような）無効な文字実体参照を生じさせ、ほとんどのXMLパーサが文書を拒否する原因となりえます。

ロギング

各種コマンドラインツールおよび下層のライブラリのロギング出力のレベルは、ユーザが指定できます。既定では、エラーと警告のみが標準エラー出力に書き出されます。–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 ファイルに用意されています）。

環境変数

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

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

指定されたコマンドラインオプションによっては、dcm2xml ユーティリティは文字集合のマッピングテーブルを読み込もうとします。これは、DCMTKがoficonvライブラリ（これが既定）でコンパイルされ、かつマッピングテーブルがライブラリに組み込まれていない（DCMTKが共有ライブラリを使う場合の既定）ときに起こります。

マッピングテーブルファイルは、DCMTKの < datadir> にあると想定されます。別の場所を指定するには DCMICONVPATH 環境変数を使えます。別の場所を指定した場合、それらのマッピングテーブルは組み込みのテーブルも置き換えます。

ファイル

< datadir>/dcm2xml.dtd - Document Type Definition（DTD）ファイル