dcm2json: DICOMファイルとデータセットをJSONに変換する
書式
dcm2json [options] dcmfile-in [jsonfile-out]
説明
dcm2json は、DICOMファイル（ファイル形式または生のデータセット）の内容を JSON（JavaScript Object Notation）に変換するユーティリティです。出力は DICOM Part 18 Section F に規定された「DICOM JSON Model」に従います。
dcm2json が生のデータセット（ファイル形式のメタヘッダを持たない DICOM データ）を読み込む場合、ファイル先頭の数バイトを調べて転送構文を推定しようとします。転送構文を常に正しく推定できるとは限らないため、可能な限り（dcmconv ユーティリティを使って）データセットをファイル形式に変換しておくのが望ましいです。また、-f オプションと -t[ieb] オプションを使えば、dcm2json に特定の転送構文でデータセットを読み込ませることもできます。
引数
dcmfile-in DICOM input filename to be converted ("-" for stdin)
jsonfile-out JSON 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 で読み込みます
処理オプション
-es --encode-strict- 'inf' と 'nan' をエラーとして報告します（既定値）
-ee --encode-extended- JSON の数値に 'inf' と 'nan' を許可します。IS と DS（整数文字列／10進文字列）要素のエンコード:
-ia --is-ds-auto- 妥当なら数値として、そうでなければ文字列としてエンコードします（既定値）
-in --is-ds-num- 常に数値としてエンコードし、不正な場合は失敗します
-is --is-ds-string- 常に文字列としてエンコードします。バルクデータ URI のオプション:
-b --bulk-disabled- すべてをインラインバイナリとして書き出します（既定値）
+b --bulk-enabled- 大きな属性をバルクデータとして書き出します
+bz --bulk-size [s]ize: integer (default: 1)- s kバイト以上の属性にバルクデータを使用します
+bp --bulk-uri-prefix [u]ri prefix: string- バルクデータ URI の生成時にプレフィックス u を使用します（既定値: file URI）
+bd --bulk-dir [d]irectory: string- バルクデータファイルをディレクトリ d に書き出します（既定値: '.'）
+bs --bulk-subdir- SOP インスタンスごとにサブディレクトリを作成します（既定値: サブディレクトリを作成しない）
出力オプション
+fc --formatted-code- 空白による整形を有効にします（既定値） # 読みやすさのために空白や改行を追加で出力します
-fc --compact-code- 必要な文字のみを出力します
+m --write-meta- メタ情報付きでデータセットを書き出します（警告: DICOM 標準には準拠しない）
JSON 形式
DICOM ファイルから生成される JSON 出力の基本構造は次のようになります（詳細は DICOM Part 18 Section F を参照）。
{
"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
]
}
}
バルクデータ
既定では、バイナリデータ、すなわち値表現（VR）が OB, OD, OF, OL, OV, OW, UN の DICOM 要素値は「InlineBinary」（base64 エンコード）として JSON 出力に書き出されます。–bulk-enabled オプションを指定すると、これらのバイナリデータに加えて DS, FD, FL, IS, SV, UV も、要素値がカットオフのしきい値（既定値: 1 kバイト）より大きい場合に「BulkDataURI」値へ置き換えられます。カットオフのしきい値は –bulk-size オプションで指定できます。要素値そのものは –bulk-dir オプションで指定したディレクトリ（既定値: カレントディレクトリ）にファイルとして書き出されます。ファイル名は要素値の SHA-256 チェックサムに基づきます。既定ではバルクディレクトリを指す file URI が生成されます。本番運用では、要素値を取得できる WADO-RS サービスの URI プレフィックスを –bulk-uri-prefix オプションで指定するとよいでしょう。これは dcm2json のバルクディレクトリへの読み取りアクセスを持つ Web サーバを構成することで実現できます。最後に、–bulk-subdir オプションを指定すると、個別の SOP インスタンスごとに専用のサブディレクトリが作成されます（バルクデータ URI にも使用されます）。
なお、「InlineBinary」形式でカプセル化されたピクセルデータを表現するための JSON 構文は DICOM で規定されておらず、カプセル化されたマルチフレームのピクセルデータの JSON 表現も同様です。このような DICOM ファイルは dcm2json で JSON に変換できません。
生成されるバルクデータファイルの拡張子は、WADO-RS サーバが返すべき MIME タイプの判定に利用できます。
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
最後に注意すべき点として、バルクデータは「そのまま」書き出されます。すなわち dcm2json は要素値を検証したり何らかの形で変更したりしません。たとえば JPEG ベースライン圧縮画像の場合でも、dcm2json は一部の JPEG ビューアが期待する JFIF ヘッダを追加しません。
注記
数値の文字列表現
DICOM 標準では、特定の数値系 DICOM 値表現、すなわち DS, IS, SV, UV を、JSON の数値または JSON の文字列のいずれかに変換することを許容しています。dcm2json は DS と IS の値を、妥当な10進文字列または整数文字列であれば JSON の数値に変換し、不正な文字を含む場合は文字列に変換します。SV と UV の値については、9007199254740991ll 以下かつ -9007199254740991ll 以上であれば数値に、そうでなければ文字列に変換します。JSON の仕様はこれより大きな数値も許容しますが、これは JavaScript が扱える最大の整数です。そのため、多くの JSON パーサはこれより大きな数値を処理できません。
文字エンコーディング
DICOM JSON エンコーディングの要件に従い、dcm2json は常に Unicode UTF-8 エンコーディングで出力を生成し、DICOM データセットをそれに合わせて変換します。たとえば DCMTK が文字セット変換のサポートなしでコンパイルされているなどの理由でこれが不可能な場合は、エラーが返されます。
ロギング
各種コマンドラインツールおよびその基盤となるライブラリのロギング出力のレベルは、ユーザが指定できます。既定では、エラーと警告のみが標準エラー出力に書き出されます。–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 に用意されています）。
終了コード
dcm2json ユーティリティは終了時に次の終了コードを使用します。これにより、アプリケーションが終了した理由をユーザが確認できます。
全般
EXITCODE_NO_ERROR 0
EXITCODE_COMMANDLINE_SYNTAX_ERROR 1
入力ファイルのエラー
EXITCODE_CANNOT_READ_INPUT_FILE 20
EXITCODE_NO_INPUT_FILES 21
出力ファイルのエラー
EXITCODE_CANNOT_WRITE_OUTPUT_FILE 40
処理エラー
EXITCODE_CANNOT_CONVERT_TO_UNICODE 80
EXITCODE_CANNOT_WRITE_VALID_JSON 81
環境変数
dcm2json ユーティリティは、DCMDICTPATH 環境変数で指定された DICOM データ辞書を読み込もうとします。既定では、すなわち DCMDICTPATH 環境変数が設定されていない場合は、データ辞書がアプリケーションに組み込まれている（Windows では既定）のでない限り、ファイル < datadir>/dicom.dic が読み込まれます。
通常はこの既定の動作が望ましく、DCMDICTPATH 環境変数は別のデータ辞書が必要な場合にのみ使用すべきです。DCMDICTPATH 環境変数は Unix シェルの PATH 変数と同じ形式で、コロン（":"）でエントリを区切ります。Windows システムでは、区切り文字としてセミコロン（";"）を使用します。データ辞書のコードは、DCMDICTPATH 環境変数で指定された各ファイルを読み込もうとします。データ辞書を1つも読み込めない場合はエラーとなります。
dcm2json ユーティリティは文字セットのマッピングテーブルを読み込もうとします。これは DCMTK が oficonv ライブラリ付きでコンパイルされており（既定）、かつマッピングテーブルがライブラリに組み込まれていない（DCMTK が共有ライブラリを使用する場合の既定）ときに発生します。
マッピングテーブルのファイルは DCMTK の < datadir> に存在することが期待されます。別の場所を指定するには DCMICONVPATH 環境変数を使用できます。別の場所を指定した場合、それらのマッピングテーブルは組み込みのテーブルも置き換えます。
著作権
Copyright (C) 2016-2025 by OFFIS e.V., Escherweg 2, 26121 Oldenburg, Germany.