pydicom 2.2 : ユーザガイド : コア要素 (翻訳/解説)
翻訳 : (株)クラスキャット セールスインフォメーション
作成日時 : 09/20/2021 (v2.2.1)
* 本ページは、pydicom の以下のドキュメントを翻訳した上で適宜、補足説明したものです：
- User Guide : Core elements in pydicom
* サンプルコードの動作確認はしておりますが、必要な場合には適宜、追加改変しています。
* ご自由にリンクを張って頂いてかまいませんが、sales-info@classcat.com までご一報いただけると嬉しいです。
クラスキャット 人工知能 研究開発支援サービス ★ 無料 Web セミナー開催中 ★
◆ クラスキャットは人工知能・テレワークに関する各種サービスを提供しております。お気軽にご相談ください :
- 人工知能研究開発支援
- 人工知能研修サービス(経営者層向けオンサイト研修)
- テクニカルコンサルティングサービス
- 実証実験(プロトタイプ構築)
- アプリケーションへの実装
- 人工知能研修サービス
- PoC(概念実証)を失敗させないための支援
- テレワーク & オンライン授業を支援
◆ 人工知能とビジネスをテーマに WEB セミナーを定期的に開催しています。スケジュール。
- お住まいの地域に関係なく Web ブラウザからご参加頂けます。事前登録 が必要ですのでご注意ください。
- ウェビナー運用には弊社製品「ClassCat® Webinar」を利用しています。
◆ お問合せ : 本件に関するお問い合わせ先は下記までお願いいたします。
| 株式会社クラスキャット セールス・マーケティング本部 セールス・インフォメーション |
| E-Mail：sales-info@classcat.com ; WebSite: https://www.classcat.com/ ; Facebook |
pydicom 2.2 : ユーザガイド : コア要素
Dataset は直接扱う主要オブジェクトです。Dataset は辞書をラップします、そこではキーは DICOM タグ (下で説明される、BaseTag オブジェクトとして) で、値は対応する DataElement インスタンス (これも下で説明されます) です。それは dict の殆どのメソッドを実装していますので、殆どの場合それはラップされた dict のように動作します。これは以下で示されるように、タグを介してデータ要素への直接アクセスを可能にします。
Dataset は直接作成できますが、通常は既存の DICOM ファイルを読むことにより取得します :
import pydicom
from pydicom.data import get_testdata_file
# get some test data
filename = get_testdata_file("rtplan.dcm")
ds = pydicom.dcmread(filename)
その文字列 (str() or reprt()) 値を単純にプリントすることによりデータセット全体を表示できます :
ds
Dataset.file_meta -------------------------------
(0002, 0000) File Meta Information Group Length UL: 156
(0002, 0001) File Meta Information Version OB: b'\x00\x01'
(0002, 0002) Media Storage SOP Class UID UI: RT Plan Storage
(0002, 0003) Media Storage SOP Instance UID UI: 1.2.999.999.99.9.9999.9999.20030903150023
(0002, 0010) Transfer Syntax UID UI: Implicit VR Little Endian
(0002, 0012) Implementation Class UID UI: 1.2.888.888.88.8.8.8
-------------------------------------------------
(0008, 0012) Instance Creation Date DA: '20030903'
(0008, 0013) Instance Creation Time TM: '150031'
(0008, 0016) SOP Class UID UI: RT Plan Storage
(0008, 0018) SOP Instance UID UI: 1.2.777.777.77.7.7777.7777.20030903150023
(0008, 0020) Study Date DA: '20030716'
(0008, 0030) Study Time TM: '153557'
(0008, 0050) Accession Number SH: ''
(0008, 0060) Modality CS: 'RTPLAN'
(0008, 0070) Manufacturer LO: 'Manufacturer name here'
(0008, 0080) Institution Name LO: 'Here'
(0008, 0090) Referring Physician's Name PN: ''
(0008, 1010) Station Name SH: 'COMPUTER002'
(0008, 1040) Institutional Department Name LO: 'Radiation Therap'
(0008, 1070) Operators' Name PN: 'operator'
(0008, 1090) Manufacturer's Model Name LO: 'Treatment Planning System name here'
(0010, 0010) Patient's Name PN: 'Last^First^mid^pre'
(0010, 0020) Patient ID LO: 'id00001'
(0010, 0030) Patient's Birth Date DA: ''
(0010, 0040) Patient's Sex CS: 'O'
(0018, 1020) Software Versions LO: 'softwareV1'
(0020, 000d) Study Instance UID UI: 1.22.333.4.555555.6.7777777777777777777777777777
(0020, 000e) Series Instance UID UI: 1.2.333.444.55.6.7777.8888
(0020, 0010) Study ID SH: 'study1'
(0020, 0011) Series Number IS: '2'
(300a, 0002) RT Plan Label SH: 'Plan1'
(300a, 0003) RT Plan Name LO: 'Plan1'
(300a, 0006) RT Plan Date DA: '20030903'
(300a, 0007) RT Plan Time TM: '150023'
(300a, 000c) RT Plan Geometry CS: 'PATIENT'
(300a, 0010) Dose Reference Sequence 2 item(s) ----
(300a, 0012) Dose Reference Number IS: '1'
(300a, 0014) Dose Reference Structure Type CS: 'COORDINATES'
(300a, 0016) Dose Reference Description LO: 'iso'
(300a, 0018) Dose Reference Point Coordinates DS: [239.531250000000, 239.531250000000, -741.87000000000]
(300a, 0020) Dose Reference Type CS: 'ORGAN_AT_RISK'
(300a, 0023) Delivery Maximum Dose DS: '75.0'
(300a, 002c) Organ at Risk Maximum Dose DS: '75.0'
---------
(300a, 0012) Dose Reference Number IS: '2'
(300a, 0014) Dose Reference Structure Type CS: 'COORDINATES'
(300a, 0016) Dose Reference Description LO: 'PTV'
(300a, 0018) Dose Reference Point Coordinates DS: [239.531250000000, 239.531250000000, -751.87000000000]
(300a, 0020) Dose Reference Type CS: 'TARGET'
(300a, 0026) Target Prescription Dose DS: '30.826203'
---------
(300a, 0070) Fraction Group Sequence 1 item(s) ----
(300a, 0071) Fraction Group Number IS: '1'
(300a, 0078) Number of Fractions Planned IS: '30'
(300a, 0080) Number of Beams IS: '1'
(300a, 00a0) Number of Brachy Application Setups IS: '0'
(300c, 0004) Referenced Beam Sequence 1 item(s) ----
(300a, 0082) Beam Dose Specification Point DS: [239.531250000000, 239.531250000000, -751.87000000000]
(300a, 0084) Beam Dose DS: '1.0275401'
(300a, 0086) Beam Meterset DS: '116.0036697'
(300c, 0006) Referenced Beam Number IS: '1'
---------
---------
(300a, 00b0) Beam Sequence 1 item(s) ----
(0008, 0070) Manufacturer LO: 'Linac co.'
(0008, 0080) Institution Name LO: 'Here'
(0008, 1040) Institutional Department Name LO: 'Radiation Therap'
(0008, 1090) Manufacturer's Model Name LO: 'Zapper9000'
(0018, 1000) Device Serial Number LO: '9999'
(300a, 00b2) Treatment Machine Name SH: 'unit001'
(300a, 00b3) Primary Dosimeter Unit CS: 'MU'
(300a, 00b4) Source-Axis Distance DS: '1000.0'
(300a, 00b6) Beam Limiting Device Sequence 2 item(s) ----
(300a, 00b8) RT Beam Limiting Device Type CS: 'X'
(300a, 00bc) Number of Leaf/Jaw Pairs IS: '1'
---------
(300a, 00b8) RT Beam Limiting Device Type CS: 'Y'
(300a, 00bc) Number of Leaf/Jaw Pairs IS: '1'
---------
(300a, 00c0) Beam Number IS: '1'
(300a, 00c2) Beam Name LO: 'Field 1'
(300a, 00c4) Beam Type CS: 'STATIC'
(300a, 00c6) Radiation Type CS: 'PHOTON'
(300a, 00ce) Treatment Delivery Type CS: 'TREATMENT'
(300a, 00d0) Number of Wedges IS: '0'
(300a, 00e0) Number of Compensators IS: '0'
(300a, 00ed) Number of Boli IS: '0'
(300a, 00f0) Number of Blocks IS: '0'
(300a, 010e) Final Cumulative Meterset Weight DS: '1.0'
(300a, 0110) Number of Control Points IS: '2'
(300a, 0111) Control Point Sequence 2 item(s) ----
(300a, 0112) Control Point Index IS: '0'
(300a, 0114) Nominal Beam Energy DS: '6.0'
(300a, 0115) Dose Rate Set DS: '650.0'
(300a, 011a) Beam Limiting Device Position Sequence 2 item(s) ----
(300a, 00b8) RT Beam Limiting Device Type CS: 'X'
(300a, 011c) Leaf/Jaw Positions DS: [-100.00000000000, 100.000000000000]
---------
(300a, 00b8) RT Beam Limiting Device Type CS: 'Y'
(300a, 011c) Leaf/Jaw Positions DS: [-100.00000000000, 100.000000000000]
---------
(300a, 011e) Gantry Angle DS: '0.0'
(300a, 011f) Gantry Rotation Direction CS: 'NONE'
(300a, 0120) Beam Limiting Device Angle DS: '0.0'
(300a, 0121) Beam Limiting Device Rotation Direc CS: 'NONE'
(300a, 0122) Patient Support Angle DS: '0.0'
(300a, 0123) Patient Support Rotation Direction CS: 'NONE'
(300a, 0125) Table Top Eccentric Angle DS: '0.0'
(300a, 0126) Table Top Eccentric Rotation Direct CS: 'NONE'
(300a, 0128) Table Top Vertical Position DS: None
(300a, 0129) Table Top Longitudinal Position DS: None
(300a, 012a) Table Top Lateral Position DS: None
(300a, 012c) Isocenter Position DS: [235.711172833292, 244.135437110782, -724.97815409918]
(300a, 0130) Source to Surface Distance DS: '898.429664831309'
(300a, 0134) Cumulative Meterset Weight DS: '0.0'
(300c, 0050) Referenced Dose Reference Sequence 2 item(s) ----
(300a, 010c) Cumulative Dose Reference Coefficie DS: '0.0'
(300c, 0051) Referenced Dose Reference Number IS: '1'
---------
(300a, 010c) Cumulative Dose Reference Coefficie DS: '0.0'
(300c, 0051) Referenced Dose Reference Number IS: '2'
---------
---------
(300a, 0112) Control Point Index IS: '1'
(300a, 0134) Cumulative Meterset Weight DS: '1.0'
(300c, 0050) Referenced Dose Reference Sequence 2 item(s) ----
(300a, 010c) Cumulative Dose Reference Coefficie DS: '0.9990268'
(300c, 0051) Referenced Dose Reference Number IS: '1'
---------
(300a, 010c) Cumulative Dose Reference Coefficie DS: '1.0'
(300c, 0051) Referenced Dose Reference Number IS: '2'
---------
---------
(300c, 006a) Referenced Patient Setup Number IS: '1'
---------
(300a, 0180) Patient Setup Sequence 1 item(s) ----
(0018, 5100) Patient Position CS: 'HFS'
(300a, 0182) Patient Setup Number IS: '1'
(300a, 01b2) Setup Technique Description ST: ''
---------
(300c, 0002) Referenced RT Plan Sequence 1 item(s) ----
(0008, 1150) Referenced SOP Class UID UI: RT Plan Storage
(0008, 1155) Referenced SOP Instance UID UI: 1.9.999.999.99.9.9999.9999.20030903145128
(300a, 0055) RT Plan Relationship CS: 'PREDECESSOR'
---------
(300c, 0060) Referenced Structure Set Sequence 1 item(s) ----
(0008, 1150) Referenced SOP Class UID UI: RT Structure Set Storage
(0008, 1155) Referenced SOP Instance UID UI: 1.2.333.444.55.6.7777.88888
---------
(300e, 0002) Approval Status CS: 'UNAPPROVED'
Note : サンプルプログラム dcm_qt_tree.py を使用して DICOM ファイルを折り畳み式のツリーで見ることもできます。
DICOM キーワードやタグナンバーにより特定の要素にアクセスできます :
ds.PatientName
ds[0x10,0x10].value
'Last^First^mid^pre' 'Last^First^mid^pre'
タグナンバーを直接使用するとき DataElement インスタンスが返されますので、値を得るために DataElement.value が使用される必要があります。
Warning : pydicom では、private データ要素は名前を角括弧で囲んで表示されます (名前が pydicom に知れている場合)。これらは便宜上表示されているだけです ; 括弧内の記述的な名前はデータ要素を取得するためには使用できません。Private Data Elements の詳細を見てください。
要素のキーワードやタグナンバーを使用して要素の値を設定することもできます :
ds.PatientID = "12345"
ds.SeriesNumber = 5
ds[0x10,0x10].value = 'Test'
pydicom はメンバー変数のリクエストをインターセプトして、それらが DICOM 辞書にあるか確認しますので、名前の使用が可能です。それはキーワードを (group, element) タグに変換してそのタグの対応する値を (それがデータセットに存在すれば) 返します。
データ要素の削除と割当ての使用例については Anonymize DICOM data を参照してください。
Note : pydicom の Sequence の使用を理解するには、このオブジェクトモデルを参照してください :
- Dataset (Python dict をラップする)
- DataElement インスタンスを含みます、各要素の値は以下の一つです :
- int, float, str, bytes 等の通常の数値、文字列またはテキスト値
- 通常の値のリスト (e.g. a 三次元座標)
- Sequence インスタンス、ここで Sequence は Dataset インスタンスのリストです。
- Where each Dataset contains DataElement instances, and so on…
- DataElement インスタンスを含みます、各要素の値は以下の一つです :
シークエンス要素の値は Python リストをラップする Sequence インスタンスです。シークエンスの項目は Python の慣習のようにインデックス 0 で始まる、番号で参照されます。
ds.BeamSequence[0].BeamName
# Or, set an intermediate variable to a dataset in the list
beam1 = ds.BeamSequence[0] # First dataset in the sequence
beam1.BeamName
'Field 1'
Working with sequences を参照してください。
DICOM キーワードの使用はデータ要素にアクセスするために推奨される方法ですが、以下のように、タグナンバーを直接使用することもできます :
# Same thing with tag numbers - much harder to read:
# Really should only be used if DICOM keyword not in pydicom dictionary
ds[0x300a,0xb0][0][0x300a,0xc2].value
'Field 1'
正確な要素タグやキーワードを覚えていないか知らない場合、Dataset は便利な Dataset.dir() メソッドを提供しています、対話的セッションの間 Python プロンプトで役立ちます :
ds.dir()
['AccessionNumber', 'ApprovalStatus', 'BeamSequence', 'DoseReferenceSequence', 'FractionGroupSequence', 'InstanceCreationDate', 'InstanceCreationTime', 'InstitutionName', 'InstitutionalDepartmentName', 'Manufacturer', 'ManufacturerModelName', 'Modality', 'OperatorsName', 'PatientBirthDate', 'PatientID', 'PatientName', 'PatientSetupSequence', 'PatientSex', 'RTPlanDate', 'RTPlanGeometry', 'RTPlanLabel', 'RTPlanName', 'RTPlanTime', 'ReferencedRTPlanSequence', 'ReferencedStructureSetSequence', 'ReferringPhysicianName', 'SOPClassUID', 'SOPInstanceUID', 'SeriesInstanceUID', 'SeriesNumber', 'SoftwareVersions', 'StationName', 'StudyDate', 'StudyID', 'StudyInstanceUID', 'StudyTime']
ds.dir("pat")
['PatientBirthDate', 'PatientID', 'PatientName', 'PatientSetupSequence', 'PatientSex']
Dataset.dir() は、キーワード (case insensitive) で指定された文字列を任意の場所に持つ、データセット内部の非プライベート要素キーワードを返します。
Note : 引数を渡さずに Dataser.dir() を呼び出すとデータセットの総ての非プライベート要素キーワードのリストを返します。
_dicom_dict.py ファイルを参照することにより pydicom が知る総ての名前を見ることもできます。それは通常は必要ないはずですが、add_dict_entry() や add_dict_entries() を使用して独自のエントリを DICOM 辞書に実行時に追加することができます。同様に、using add_private_dict_entry() か add_private_dict_entries() を使用してプライベートデータ要素をプライベート辞書に追加できます。
内部的には、Dataset は各項目に対する DataElement オブジェクトをストアしますが、キーワード (e.g. ds.PatientName) によりアクセスされるときは DataElement の値だけが返されます。オブジェクト自身が必要な場合には、(公式 DICOM 要素のための) キーワードかタグナンバーのいずれかを使用して項目にアクセスできます。
# reload the data
ds = pydicom.dcmread(filename)
elem = ds['PatientName']
elem.VR, elem.value
# an alternative is to use:
elem = ds[0x0010,0x0010]
elem.VR, elem.value
('PN', 'Last^First^mid^pre')
Dataset が特定の要素を含むか確認するには要素のキーワードかタグで in 演算子を使用します :
"PatientName" in ds # or (0x0010,0x0010) in ds
True
Dataset から要素を削除するには del 演算子を使用します :
del ds.SoftwareVersions # or del ds[0x0018, 0x1020]
(7FE0,0010) Pixel Data を扱うには、PixelData キーワードで raw バイトが利用可能です :
# read data with actual pixel data
filename = get_testdata_file("CT_small.dcm")
ds = pydicom.dcmread(filename)
pixel_bytes = ds.PixelData
けれども numpy.ndarray を返す Dataset.pixel_array を使用するほうが遥かに便利です (NumPy ライブラリが必要です) :
arr = ds.pixel_array
arr
array([[175, 180, 166, ..., 203, 207, 216],
[186, 183, 157, ..., 181, 190, 239],
[184, 180, 171, ..., 152, 164, 235],
...,
[906, 910, 923, ..., 922, 929, 927],
[914, 954, 938, ..., 942, 925, 905],
[959, 955, 916, ..., 911, 904, 909]], dtype=int16)
詳細は、Pixel データの操作 を参照してください。
DataElement
DataElement クラスは通常はユーザコードで直接使用されませんが、Dataset により広範に使用されます。DataElement は単純なオブジェクトで以下のものをストアします :
- タグ – 要素のタグ (BaseTag オブジェクトとして)
- VR – 要素の値表現 – 保存されている値の形式に表わす 2 文字 str
- VM – 要素の int としての多重性 (= Value Multiplicity)。これは value の内容から自動的に決定されます。
- value – 要素の実際の値。数字や文字列のような通常の値 (or VM > 1 ならばそれらのリスト)、または Sequence。
タグ
一般には Tag() はユーザコードでは直接使用されません、上記のセクションで示されたようにキーワードを使用して要素を割当てたり読むときに BaseTag が自動的に作成されるからです。
BaseTag クラスは int から派生してるので、実際には、幾つかの追加動作を伴う単なる数値です :
- Tag() は BaseTag のインスタンスを作成するために使用され、DICOM タグが想定される 4 バイト (group, element) に収まることを強制します。
- BaseTag インスタンスは int または (group,element) を含むタプルからか、DICOM キーワードから作成できます :
from pydicom.tag import Tag t1 = Tag(0x00100010) # all of these are equivalent t2 = Tag(0x10,0x10) t3 = Tag((0x10, 0x10)) t4 = Tag("PatientName") t1 type(t1) t1==t2, t1==t3, t1==t4(True, True, True)
- タグのグループと要素部分を返すための BaseTag.group と BaseTag.elem。
- BaseTag.is_private プロパティはタグがプライベート・タグを表わすか否か (i.e. グループ・ナンバーが奇数か) を確認します。
シークエンス
シークエンス は Python のリストから派生しています。追加された唯一の機能は文字列表現をより良くする (= prettier) ことです。それ以外の項目の選択、append 等のリストの通常の総てのメソッドは利用可能です。
以上
