pydicom은(는) 무엇을 하나요?
DICOM 데이터셋 I/O 및 픽셀 처리를 위해 pydicom을 사용하세요. 여기서 검토된 현재 안정 릴리스는 버전 3.0.2입니다. 이 버전은 CVE-2026-32711(조작된 DICOMDIR 경로 탐색 문제)을 수정합니다. pydicom 3.0.2는 Python >=3.10을 선언하며, 번들 DICOM 사전은 2024c이고, 라이브 DICOM 표준은 더 최신일 수 있습니다.
필수 안전 경계
- 사용자가 액세스 권한이 있는 로컬 데이터에 대해서만 작업하십시오.
- DICOM 메타데이터, 파일 이름, 비공개 요소, 오버레이, 구조화된 콘텐츠 및 픽셀에는 보호 건강 정보(PHI)가 포함될 수 있습니다.
- 기본적으로
Dataset을 출력하거나, 전체 메타데이터/JSON을 내보내거나, 요소 값을 로깅하지 마십시오. 문서화된 허용 목록과 집계 출력을 사용하십시오. - pydicom은 일반 DICOM 프레임워크이지 진단 뷰어가 아닙니다. 픽셀 출력, 검증, 변환 및 플러그인 가용성은 진단적 주장이 아닙니다.
- 비식별화는 프로필, 목적, 수신자, 관할권 및 위협 컨텍스트에 따라 다릅니다. 개인정보 보호/DICOM 전문가의 확인이 필요합니다.
- 태그 제거 스크립트가 DICOM PS3.15, HIPAA, GDPR 또는 기타 규정을 준수한다고 주장하지 마십시오. 원본을 보존하고 파생 출력물을 감사하십시오.
- 결정론적 가명화 키와 UID 맵은 재식별 비밀로 취급하십시오: 최소 권한과 암호화/관리형 비밀 저장소를 사용하고, 절대 커밋, 동기화, 로깅 또는 파생물과 공유하지 말고, 백업, 순환, 폐기 및 폐기 절차를 정의하십시오. 키가 유출되면 의도된 분리가 무효화되며, 순환은 결정론적 매핑도 변경합니다.
- 신뢰할 수 없거나 비정상적으로 큰 데이터셋을 구문 분석하기 전에 명시적인 입력 파일, 파일 개수, 프레임 개수, 디코딩된 바이트 및 출력 제한을 설정하십시오.
설치
격리된 환경을 생성하거나 활성화한 후 정확히 검토된 릴리스를 설치하십시오:
uv pip install "pydicom==3.0.2"
압축되지 않은 픽셀 배열 및 이미지 렌더링:
uv pip install "pydicom==3.0.2" "numpy==2.5.1" "Pillow==12.3.0"
배포에 필요한 전송 구문 플러그인만 설치하십시오:
# JPEG/JPEG-LS, JPEG 2000/HTJ2K 및 pylibjpeg를 통한 더 빠른 RLE
uv pip install "numpy==2.5.1" "pylibjpeg==2.1.0" \
"pylibjpeg-libjpeg==2.4.0" "pylibjpeg-openjpeg==2.5.0" \
"pylibjpeg-rle==2.2.0"
# JPEG-LS 인코더/디코더
uv pip install "numpy==2.5.1" "pyjpegls==1.5.1"
# 플랫폼별 휠이 포함된 대체 디코더
uv pip install "python-gdcm==3.2.6"
플러그인 라이선스와 휠은 패키지/플랫폼에 따라 다릅니다. 배포 전에 검토하십시오. Pillow에는 문서화된 디코딩 제한 사항이 있으며, pydicom은 플러그인 출력을 독립적으로 확인해야 한다고 경고합니다.
네이티브 코덱 휠은 공급망 및 메모리 안전 경계를 넓힙니다. 통제된 배포를 위해 신뢰할 수 있는 빌드 호스트에서 이러한 정확한 핀을 확인하고, 휠 해시/출처를 잠그고 확인하고, 승인된 아티팩트를 내부에 미러링하고, 스캔한 다음, 런타임에 공개 인덱스에서 확인하지 않고 해시 적용을 통해 설치하십시오.
워크플로우 선택
- 집계 개요가 필요하면:
scripts/extract_metadata.py를 실행하십시오. - 제한된 기술적 확인이 필요하면:
scripts/dicom_inventory.py를 실행하십시오. - 코덱 배포 사전 점검이 필요하면:
scripts/transfer_syntax_inspector.py를 실행하십시오. - 프레임/메모리 계획이 필요하면:
scripts/pixel_frame_planner.py를 실행하십시오. - 진단용이 아닌 렌더링된 프레임 하나가 필요하면:
scripts/dicom_to_image.py를 실행하십시오. - 가명화된 파생물이 필요하면: 비식별화 섹션을 읽고, 사이트에서 검토된 작업 프로필을 생성한 다음,
scripts/anonymize_dicom.py및scripts/deidentification_audit.py를 실행하십시오. - 민감한 UID 맵을 확인해야 하면:
scripts/uid_mapping_validator.py를 실행하십시오.
데이터셋 안전하게 읽기
dcmread()는 파일 메타데이터, 프리앰블 및 원래 인코딩과 같은 파일 형식 상태를 가진 Dataset의 하위 클래스인 FileDataset를 반환합니다.
from pathlib import Path
import pydicom
path = Path("authorized/input.dcm")
ds = pydicom.dcmread(
path,
stop_before_pixels=True,
specific_tags=[
"SOPClassUID",
"Modality",
"Rows",
"Columns",
"NumberOfFrames",
],
)
technical = {
"sop_class": ds.get("SOPClassUID"),
"modality": ds.get("Modality"),
"rows": ds.get("Rows"),
"columns": ds.get("Columns"),
}
사용법:
- 메타데이터 전용 작업에는
stop_before_pixels=True를 사용하십시오. - 최소 허용 목록에는
specific_tags=[...]를 사용하십시오. - 나중에 쓰기 작업에서 큰 값을 보존해야 할 때는
defer_size="1 MiB"를 사용하십시오. force=False(기본값)를 사용하십시오.force=True는 파일 형식 헤더 검사만 우회하며, 바이트가 유효한 DICOM임을 증명하지 않습니다.
임상 데이터에 대해 print(ds), repr(ds)를 호출하거나 값을 로그에 반복하지 마십시오.
Dataset, DataElement 및 시퀀스
키워드로 표준 요소에 접근하고 부재를 확인하십시오:
modality = ds.get("Modality", "UNSPECIFIED")
if "ReferencedImageSequence" in ds:
for item in ds.ReferencedImageSequence:
referenced_class = item.get("ReferencedSOPClassUID")
태그 접근(예: ds[0x0010, 0x0010])은 DataElement를 반환하며, .value는 별도입니다. Sequence는 중첩된 Dataset 항목의 리스트처럼 동작합니다. 개인정보 보호 조치는 최상위 수준뿐만 아니라 모든 시퀀스 항목을 재귀적으로 처리해야 합니다.
파일을 생성할 때는 그룹 0002에 FileMetaDataset를 사용하고, 데이터셋과 파일 메타 SOP UID를 일관되게 유지하고, 전송 구문 UID를 설정하고, 강제 파일 형식으로 쓰십시오:
from pydicom import dcmwrite
from pydicom.dataset import FileDataset, FileMetaDataset
from pydicom.uid import CTImageStorage, ExplicitVRLittleEndian, generate_uid
meta = FileMetaDataset()
meta.MediaStorageSOPClassUID = CTImageStorage
meta.MediaStorageSOPInstanceUID = generate_uid()
meta.TransferSyntaxUID = ExplicitVRLittleEndian
ds = FileDataset(None, {}, file_meta=meta, preamble=b"\0" * 128)
ds.SOPClassUID = meta.MediaStorageSOPClassUID
ds.SOPInstanceUID = meta.MediaStorageSOPInstanceUID
# 쓰기 전에 선택한 IOD에 필요한 모든 속성을 추가하십시오.
dcmwrite("new.dcm", ds, enforce_file_format=True, overwrite=False)
write_like_original은 pydicom 3.0에서 더 이상 사용되지 않습니다. enforce_file_format을 사용하십시오. 성공적인 쓰기가 완전한 PS3.3 IOD 적합성을 의미하지는 않습니다.
UID 및 전송 구문
파일 메타 정보 전송 구문 UID는 데이터셋 인코딩 및 픽셀 압축을 제어합니다:
ts = ds.file_meta.TransferSyntaxUID
summary = {
"uid": str(ts),
"name": ts.name,
"compressed": ts.is_compressed,
"implicit_vr": ts.is_implicit_VR,
"little_endian": ts.is_little_endian,
}
pydicom 3.0은 레거시 데이터셋 플래그보다 전송 구문 UID에서 쓰기 인코딩을 선택합니다. 가명화 중에는 구조적 UID(전송 구문, SOP 클래스 또는 코딩 체계 UID)를 교체하지 마십시오. 인스턴스/참조 UID 교체는 완전히 선언된 범위에서 일대일로 일관되어야 합니다.
압축, 압축 해제 또는 캡슐화 전에 references/transfer_syntaxes.md를 읽으십시오.
픽셀 데이터 및 프레임
안정적인 pydicom.pixels API는 경로 기반의 프레임별 디코딩을 지원합니다:
from pydicom.pixels import pixel_array
# 소스가 허용하는 경우 선택한 프레임만 읽습니다.
frame = pixel_array("authorized/image.dcm", index=0, raw=False)
형상 의미:
- 그레이스케일 단일 프레임:
(rows, columns) - 그레이스케일 다중 프레임:
(frames, rows, columns) - 컬러 단일 프레임:
(rows, columns, samples) - 컬러 다중 프레임:
(frames, rows, columns, samples)
raw=False는 가능한 경우 YCbCr 픽셀 데이터를 RGB로 변환합니다. raw=True는 필수 최소 처리 후 디코딩된 색상 공간을 유지합니다. 제한된 다중 프레임 반복에는 iter_pixels(path, indices=[...])를 사용하십시오.
그레이스케일 디스플레이의 경우 다음 순서로 변환을 적용하십시오:
from pydicom.pixels import apply_modality_lut, apply_voi_lut
modality_values = apply_modality_lut(frame, ds)
display_values = apply_voi_lut(modality_values, ds, index=0)
Modality LUT/재조정 및 VOI/윈도잉은 디스플레이/값 의미를 변경합니다. MONOCHROME1은 프레젠테이션 반전이 필요할 수 있습니다. 팔레트 컬러는 apply_color_lut()가 필요합니다. 프레젠테이션 상태 및 ICC 동작은 검증된 뷰어가 필요할 수 있습니다. 정량적 분석을 위해 프레임별 최소/최대 정규화를 사용하지 마십시오.
압축, 압축 해제 및 캡슐화
pixel_array에 접근하면 필요에 따라 디코딩되지만 데이터셋은 변경되지 않습니다.Dataset.decompress()는 픽셀 데이터를 제자리에서 변경하고, Explicit VR Little Endian을 설정하고, 이미지 메타데이터를 업데이트하며, 기본적으로 새 SOP 인스턴스 UID를 생성합니다.Dataset.compress(uid)는 픽셀 데이터와 전송 구문을 제자리에서 변경하고 기본적으로 새 SOP 인스턴스 UID를 생성합니다.- pydicom 3.0 내장/발견된 인코더는 안정적인 플러그인 매트릭스에 문서화된 RLE 무손실, JPEG-LS 및 JPEG 2000 조합을 다룹니다.
- 각 압축 프레임은 별도로 인코딩된 후 캡슐화됩니다. 외부에서 인코딩된 프레임에는
encapsulate()또는encapsulate_extended()를 사용하십시오. - 현재
pydicom.encaps.generate_frames()또는get_frame()으로 프레임을 읽으십시오. 레거시 캡슐화 생성기 이름은 pydicom 4에서 더 이상 사용되지 않습니다.
항상 먼저 기능을 검사하고, 디코딩된 바이트/프레임을 제한하며, 픽셀 정확성을 독립적으로 확인하십시오. 손실 압축의 허용 가능성은 pydicom 및 DICOM 인코딩 사양 범위를 벗어납니다.
DICOM JSON 및 비공개 요소
Dataset.to_json(), to_json_dict() 및 Dataset.from_json()은 DICOM JSON 모델을 구현하지만, pydicom은 JSON 지원을 베타로 문서화합니다. 전체 JSON은 바이너리 데이터를 인라인으로 포함하고 모든 식별자와 픽셀 페이로드를 노출할 수 있습니다. 메타데이터 보고서로 내보내지 마십시오. BulkDataURI 핸들러는 별도의 저장소, 권한 부여 및 검색 의무를 도입합니다.
비공개 요소는 표준화되지 않았으며 PHI를 포함할 수 있습니다:
# 재귀적 제거이지만, 그 자체로 충분한 비식별화는 아닙니다.
ds.remove_private_tags()
명시적으로 검토된 안전-비공개 정책 하에서만 비공개 요소를 유지하십시오. 태그 접근, 개인정보 보호 클래스 및 표준 포인터는 references/common_tags.md를 읽으십시오.
비식별화 워크플로우
DICOM PS3.15 부록 E는 기밀성 프로필이 모든 식별 정보 제거를 보장하지 않으며 완전한 비식별화 프로세스를 대체하지 않는다고 명시합니다.
- 목적, 수신자, 연결 요구 사항, 규정, 위협 모델 및 허용 가능한 재식별 위험을 정의하십시오.
- 기본 애플리케이션 수준 기밀성 프로필과 필요한 옵션(픽셀, 인식 가능한 시각적 특징, 그래픽, 구조화된 콘텐츠, 설명자, 시간 정보, 환자 특성, 장치, 기관, UID 및 안전한 비공개 데이터)을 선택하십시오.
- 제어된 저장소에서 원본 개체를 변경하지 않고 보존하십시오.
- 중첩된 시퀀스를 포함한 모든 작업을 재귀적으로 적용하십시오.
- 인스턴스/참조 UID를 완전한 범위에서 일관되게 교체하십시오. 구조적 UID는 보존하십시오.
- 날짜/시간 처리를 명시적으로 결정하십시오. 고정 시프트는 간격을 보존할 수 있지만 부분 날짜, 시간대, 독립 실행형 시간, 윤일, 종단 간 연결 및 외부 이벤트는 검토된 정책이 필요합니다.
- 픽셀, 오버레이, 그래픽, 구조화된 콘텐츠 및 인식 가능한 시각적 특징을 검사하십시오. 누락된 메타데이터에서 깨끗한 픽셀을 유추하거나 확인 없이
BurnedInAnnotation=NO를 설정하지 마십시오. - 파일 메타 정보와 프리앰블을 재구성하여 유출을 방지하십시오.
- 기술적 검증과 비식별화 감사를 실행한 다음 전문가 검증과 문서화된 위험 검토를 수행하십시오.
번들 스크립트는 성공적인 비식별화를 설정할 수 없기 때문에 의도적으로 PatientIdentityRemoved를 NO로 설정합니다.
헬퍼 CLI
모든 --help 경로는 종속성이 없습니다. 도구는 네트워크 액세스를 수행하지 않으며 좁은 기술 허용 목록을 넘어 DICOM 값을 내보내지 않습니다.
번들 콘텐츠는 두 개의 연결된 참조, 문서화된 헬퍼 스크립트 및 합성 테스트로 구성됩니다. pydicom 런타임 종속성은 고정된 PyPI 릴리스에서 설치됩니다.
# 편집된 집계 메타데이터
python scripts/extract_metadata.py authorized/ --recursive
# 메타데이터 전용 기술 인벤토리
python scripts/dicom_inventory.py authorized/ --recursive
# 설치된 코덱/플러그인 기능
python scripts/transfer_syntax_inspector.py --input authorized/image.dcm
# 프레임 형상, 바이트 및 변환 계획
python scripts/pixel_frame_planner.py authorized/image.dcm --frames 0,2-4
# 진단용이 아닌 프레임 하나
python scripts/dicom_to_image.py authorized/image.dcm frame.png \
--acknowledge-pixel-phi
# 비밀 키 생성 후 범위가 지정된 가명화된 파생물 및 감사 생성
python scripts/anonymize_dicom.py --generate-uid-key project.key
python scripts/anonymize_dicom.py authorized/in.dcm derived/out.dcm \
--uid-key-file project.key --uid-scope export-v1 \
--audit-report derived/out.audit.json
# 감사 후보 메타데이터; 픽셀 압축 해제 없음
python scripts/deidentification_audit.py derived/out.dcm
# 명시적으로 요청된 민감한 UID 매핑 검증
python scripts/uid_mapping_validator.py derived/uid-map.json \
--uid-key-file project.key --uid-scope export-v1
생성된 원시 키 파일은 제어된 로컬 편의를 위한 것이며 소유자 전용 권한으로 생성됩니다. 프로덕션의 경우 승인된 비밀 관리자에서 키 바이트를 잠긴 임시 파일로 구체화하고, 비식별화 서비스에 대한 액세스를 제한하고, 사용 후 안전하게 제거하십시오. 선택적 UID 맵은 파생물과 별도로 저장하십시오. 원본 식별자와 대체 식별자를 직접 연결합니다.
pydicom 3.0 마이그레이션 참고 사항
read_file()및write_file()이 제거되었습니다.dcmread()및dcmwrite()를 사용하십시오.write_like_original은 더 이상 사용되지 않습니다.enforce_file_format을 사용하십시오.pydicom.pixel_data_handlers는 v4에서 제거를 위해 더 이상 사용되지 않습니다.pydicom.pixels를 사용하십시오.Dataset.pixel_array는 기본적으로 새 픽셀 백엔드를 사용하며 가능한 경우 YCbCr을 RGB로 변환합니다.JPEGLossless는 이제 UID1.2.840.10008.1.2.4.57을 의미합니다.JPEGLosslessSV1은.70입니다.Dataset.is_little_endian및is_implicit_VR는 v4에서 더 이상 사용되지 않습니다.
출처 (2026-07-23 확인)
- PyPI의 pydicom 3.0.2 — 2026-04-15 릴리스