Main Content

dicomwrite

イメージを DICOM ファイルとして書き込む

説明

dicomwrite(X,filename) は、バイナリ、グレースケール、またはトゥルーカラーのイメージ X をファイル filename に書き込みます。関数 dicomwrite は、Digital Imaging and Communications in Medicine (DICOM) ファイルまたは Digital Imaging and Communication in Security (DICOS) ファイルを作成します。この構文は、セカンダリ キャプチャ DICOM Information Object (IOD) に必要なメタデータを含むファイルを書き込みます。

dicomwrite(X,cmap,filename) は、カラーマップ cmap を使用してインデックス付きイメージ X を書き込みます。

dicomwrite(___,meta_struct) は、前の構文の入力引数の組み合わせに加えて、オプションのメタデータまたはファイル オプションを構造体 meta_struct で指定します。meta_struct 内のフィールド名は DICOM ファイル属性名またはオプション名でなければなりません。フィールドの値は、属性またはオプションに割り当てる値にします。

dicomwrite(___,info) は、関数 dicominfo によって生成されるメタデータ構造体 info 内のメタデータを指定します。

dicomwrite(___,"ObjectType",IOD) は、特定のタイプの DICOM Information Object (IOD) に必要なメタデータを含むファイルを書き込みます。サポートされる IOD の場合、dicomwrite は、指定された IOD に必要なメタデータ属性がすべて存在するかを検証し、必要に応じて欠損している属性を作成して、可能であれば既定値を指定します。さらに、dicomwrite は、指定された IOD の DICOM 仕様に含まれていない属性を削除します。詳細については、ヒントを参照してください。

dicomwrite(___,"SOPClassUID",UID) は、DICOM の固有識別子 (UID) を使用して指定した、特定のタイプの IOD に必要なメタデータを含むファイルを書き込みます。

dicomwrite(___,Name,Value) は、名前と値の引数を使用して追加のオプションを指定します。また、この構文を使用して、個々のメタデータ属性とその値を指定して DICOM ファイルに書き込むこともできます。指定可能な DICOM 属性の一覧は、Image Processing Toolbox™ ソフトウェアに付属のデータ ディクショナリ ファイル dicom-dict.txt に記載されています。各属性名は引用符で囲みます。

status = dicomwrite(___) は、DICOM ファイルを生成するために使用されるメタデータとその記述に関する情報を返します。この構文は、info 構造体を関数 dicomwrite に指定する場合に便利です。

すべて折りたたむ

CT イメージを DICOM ファイルから読み取ります。

X = dicomread("CT-MONO2-16-ankle.dcm");

CT イメージをファイルに書き込んでセカンダリ キャプチャ イメージを作成します。この操作では、セカンダリ キャプチャ DICOM Information Object (IOD) に必要なメタデータ属性を含む DICOM ファイルを作成します。

dicomwrite(X,"sc_file.dcm");

CT イメージをメタデータと共に DICOM ファイルに書き込みます。関数 dicominfo を使用して DICOM ファイルからメタデータを取得します。既定で、関数 dicomwrite は、新しいファイル内のメタデータ属性が セカンダリ キャプチャ IOD の標準に準拠しているかを検証します。

metadata = dicominfo("CT-MONO2-16-ankle.dcm");
dicomwrite(X,"ct_file.dcm",metadata);

X を、メタデータをそのままコピーして、別の DICOM ファイルに書き込みます。CreateMode パラメーターが "copy" に設定されると、dicomwrite はファイルに書き込むメタデータを検証しません。

dicomwrite(X,"ct_copy.dcm",metadata,"CreateMode","copy");

入力引数

すべて折りたたむ

DICOM イメージ。以下のオプションのいずれかとして指定します。

  • 単一フレームのグレースケール イメージまたはインデックス付きイメージを表す m 行 n 列の行列

  • 単一フレームのトゥルーカラー (RGB) イメージを表す m × n × 3 の配列

  • マルチフレーム イメージを表す 4 次元配列

メモ

X が空の場合、関数 dicomwrite は空のイメージ データを使用して DICOM ファイルを書き込みます。DICOM ファイルのメタデータ属性は、既定値に設定されるか、CreateMode"Copy" と指定されている場合は meta_struct からコピーされます。

データ型: int8 | int16 | uint8 | uint16

インデックス付きイメージ X に関連付けられたカラーマップ。範囲 [0, 1] の値をもつ c 行 3 列の数値行列として指定します。各行は、カラーマップの単一色を構成する赤、緑、青の成分を指定する 3 要素の RGB 3 成分です。

データ型: double

書き込む DICOM ファイルの名前。文字ベクトルまたは string スカラーとして指定します。

データ型: char | string

オプションのメタデータまたはファイル オプション。構造体として指定します。meta_struct 内のフィールド名は DICOM ファイル属性名またはオプション名でなければなりません。フィールドの値は、属性またはオプションに割り当てる値にします。

関数 dicominfo によって生成されるメタデータ。構造体として指定します。

DICOM 情報オブジェクト。"Secondary Capture Image Storage""CT Image Storage"、または "MR Image Storage" を指定します。

データ型: char | string

IOD に対応する DICOM の固有識別子。string スカラーまたは文字ベクトルとして指定します。

データ型: char | string

名前と値の引数

オプションの引数のペアを Name1=Value1,...,NameN=ValueN として指定します。ここで、Name は引数名で、Value は対応する値です。名前と値の引数は他の引数の後に指定しなければなりませんが、ペアの順序は重要ではありません。

例: dicomwrite(X,"new_file.dcm",CompressionMode="JPEG lossless") は、イメージ データ X を DICOM ファイル new_file.dcm に JPEG 可逆圧縮を使用して書き込みます。

R2021a より前では、コンマを使用して名前と値をそれぞれ区切り、Name を引用符で囲みます。

例: dicomwrite(X,"new_file.dcm","CompressionMode","JPEG lossless") は、イメージ データ X を DICOM ファイル new_file.dcm に JPEG 可逆圧縮を使用して書き込みます。

イメージを格納するときに使用する圧縮モード。次のオプションのいずれかとして指定します。

  • "None"

  • "JPEG lossless"

  • "JPEG lossy"

  • "JPEG2000 lossy"

  • "JPEG2000 lossless"

  • "RLE"

メモ

圧縮モードが指定されている場合、dicomwriteEndian 引数または VR 引数に指定されている値をすべて無視します。

新しいファイルに格納するデータの作成方法。次のオプションのいずれかとして指定します。

  • "Create" — 入力値を検証して、不要な属性を削除し、欠損したデータ値を生成します。

  • "Copy" — 入力からすべての値をコピーします。欠損値の生成は行いません。

作成方法の選択についてのヘルプは、ヒントを参照してください。

DICOM データ ディクショナリ名。文字ベクトルまたは string スカラーとして指定します。既定のファイルは dicom-dict.mat です。

ファイルのバイト順。"ieee-le" または "ieee-be" として指定します。

メモ

VR"Implicit" に設定されている場合、Endian"ieee-le" でなければなりません。CompressionMode または TransferSyntax を指定すると、関数 dicomwrite はこの値を無視します。

マルチフレーム イメージの 1 ファイルへの書き込み。logical の 1 (true) または 0 (false) として指定します。true の場合、この関数は、X 内に含まれるフレームの数にかかわらず、1 つのファイルを作成します。false の場合は、イメージ内の各フレームに対してファイルを 1 つずつ作成します。

データ型: logical

転送構文。文字ベクトルまたは string スカラーとして指定します。TransferSyntax は UID で、EndianVR、および CompressionMode オプションの値をエンコードします。

メモ

転送構文が指定されている場合、dicomwriteEndianVR、および CompressionMode オプションに指定された値をすべて無視します。

メタデータ値の維持。logical の 0 (false) または 1 (true) として指定します。true の場合、dicomwrite はメタデータ構造体のフィールド "BitStored""BitsAllocated""HighBit" の既存の値を維持します。false の場合、dicomwrite はピクセル データのデータ型に基づいてこれらの値を計算します。

メモ

CreateMode"Create" として指定されている場合、dicomwrite はこの値を無視します。

データ型: logical

2 文字値表現 (VR) コードのファイルへの書き込み。以下のオプションのいずれかとして指定します。

  • "implicit" — データ ディクショナリから推測します。

  • "explicit" — VR をファイルに書き込みます。

メモ

Endian に値 "ieee-be" を指定した場合は、VR"explicit" を指定しなければなりません。TransferSyntax または CompressionMode を指定すると、関数 dicomwrite はこの値を無視します。

ファイルへのプライベート データの書き込み。logical の 0 (false) または 1 (true) として指定します。

データ型: logical

出力引数

すべて折りたたむ

属性のステータス。構造体として返されます。status は、DICOM ファイルを生成するために使用されるメタデータとその記述に関する情報が含まれます。メタデータを指定しない場合、dicomwrite は空の行列 ([]) を返します。

status 構造体には次のフィールドがあります。

フィールド

説明

BadAttribute

属性の内部記述が正しくありません。データ ディクショナリから欠損しているか、記述に正しくないデータが含まれている可能性があります。

MissingCondition

属性が条件付きですが、属性をどのようなとき使用するかに関する条件が指定されていません。

MissingData

ファイルに含めなければならない属性に関するデータが指定されていません。

SuspectAttribute

属性のデータが DICOM 仕様に含まれている列挙値のリストと一致していません。

ヒント

  • DICOM 形式の仕様には、作成可能な Information Object Definitions (IOD) がいくつか記載されています。これらの IOD は、さまざまな現実世界のモダリティ (MRI、X 線、超音波など) によって生成されるイメージおよびメタデータと対応しています。DICOM 仕様では、必要なメタデータのセットと、その他のメタデータの有効な値が IOD のタイプごとに定義されています。

    • dicomwrite は、一部の IOD (セカンダリ キャプチャ、コンピューター断層撮影、磁気共鳴) を完全に実装しています。これらの IOD の場合、dicomwrite は、指定された IOD に必要なメタデータ属性がすべて存在するかを検証し、必要に応じて欠損している属性を作成して、可能であれば既定値を指定します。さらに、dicomwrite は、指定された IOD の DICOM 仕様に含まれていない属性を削除します。この動作は、名前と値の引数 CreateMode が既定値である "Create" の場合の動作です。サポートされている IOD で DICOM ファイルを操作する場合は、CreateMode"Create" に設定することが、作成するファイルを DICOM 仕様に確実に準拠させる最善の方法です。

    • dicomwrite が完全にはサポートしていない IOD の DICOM ファイルを書き込む場合は、名前と値の引数 CreateMode の値に "Copy" を使用します。このモードの場合、dicomwrite は、info 入力引数を使用して指定されたメタデータと共にイメージ データをファイルに書き込みます。このオプションを使用すると、同じモダリティまたは IOD の既存のファイルからメタデータを取得して、それに基づいて別のイメージ ピクセル データをもつ新しい DICOM ファイルを作成することができます。イメージ データが空の場合、dicomwrite は、イメージに関連するメタデータ属性を新しい DICOM ファイルに書き込みません。

      メモ

      dicomwrite"Copy" モードでは検証なしでメタデータをファイルにコピーするため、DICOM 標準に準拠しない DICOM ファイルを作成することが可能です。たとえば、必要なメタデータがファイルから欠損しているか、余分なメタデータが含まれているか、または、元のイメージを生成するために使われるモダリティの設定にメタデータが対応しなくなっている可能性があります。"Copy" モードを使用する場合は、使用するメタデータが同じモダリティと IOD のものであることを確認してください。作成するコピーが元のイメージと関連していない場合は、dicomuid を使用してメタデータの series と study に対する新規の固有識別子を作成してください。適切な IOD 値の詳細については、DICOM 仕様 Part 3 の IOD に関する説明を参照してください。

  • 関数 dicomwrite は、DICOM ファイルを書き込む前に、名前と値の引数 CreateMode の値にかかわらず、名前に "Group Length" を含むメタデータ属性を削除します。グループ長の属性を含めるとエラーが起こりやすく、DICOM 仕様では現在推奨されていません。他のソフトウェアまたはデバイスは、グループ長の属性なしで DICOM ファイルを読み取ることができます。

バージョン履歴

R2006a より前に導入