DICOM 플러그인
DicomPlugin으로 의료 이미지를 보기
DICOM 플러그인은 Doconut에 의료 이미지 뷰어 기능을 추가합니다: 다중 프레임 DICOM 파일은 애니메이션 개요, 개별 프레임 또는 두 가지 모두로 렌더링됩니다. DICOM은 플러그인 전용 포맷이며 — 이 플러그인(및 라이선스 기능)이 없으면 .dcm 파일을 전혀 열 수 없습니다.
| 구분 | 사용 시 |
|---|---|
Viewer와 DicomConfig (C#) | 서버에서 DICOM 파일을 열고 프레임이 표시되는 방식을 선택합니다 |
뷰어 (docViewer) | 페이지에 연구를 표시합니다: 애니메이션, 프레임 및 DICOM 속성 패널 |
HTTP 엔드포인트 (?token=<token>&meta=1) | 프론트엔드에서 기술 메타데이터를 읽습니다 |
플러그인 자체 위젯이 없습니다: DICOM 파일은 일반 뷰어에서 열립니다. Converter plugin도 등록하면, .dcm 및 .ima 파일을 Pdf, Png, Jpeg, Bmp, Tiff 또는 Gif 로 변환할 수 있습니다; 이 변환에는 Dicom 기능도 필요합니다.
패키지 설치
dotnet add package Doconut.NET8.Dicom버전이 지정되지 않은 명령은 최신 안정 릴리스를 설치합니다. 이 문서에서 설명하는 릴리스에 플러그인을 고정하려면, 버전을 별도로 전달하십시오:
dotnet add package Doconut.NET8.Dicom --version 26.10.0Doconut.NET8와 동일한 버전으로 DICOM 패키지를 유지하십시오. 패키지 ID는
Doconut.NET8.Dicom이며, .<version>는 다운로드된 .nupkg 파일명에만 나타납니다.
플러그인의 라이선스 파일인 Doconut.Viewer.Dicom.lic는 Doconut.Viewer.lic와 같은 폴더에 두며; 뷰어 라이선스와 함께 읽힙니다.
플랫폼. 플러그인은 Doconut.NET8가 실행되는 모든 환경에서 동작합니다: Windows와 x64용 glibc 기반 Linux (Alpine이나 기타 musl 기반 배포판 제외). Linux에서는 첫 문서가 열리기 전에 폰트 설정 라이브러리를 설치하십시오:
apt-get update && apt-get install -y libfontconfig1RHEL, Fedora 및 유사 배포판에서는 패키지가 fontconfig입니다. 이것이 없으면 문서 열기가 The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.와 함께 실패합니다.
플러그인 등록
builder.Services.AddDoconut(options =>
{
options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});플러그인 (Name: "Doconut DICOM Viewer")은 .dcm 및 .ima 확장자를 위한 뷰어를 등록하며, 이는 Dicom 기능에 의해 제어됩니다. 이를 부여하는 라이선스가 없으면, AddDoconut()는 앱이 요청을 처리하기 전에 시작 시 InvalidOperationException를 발생시킵니다:
The Dicom plugin is registered via AddPlugin but no active license grants Dicom. Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Dicom.라이선스가 없거나, 레거시 TRIAL 파일이 있거나, Dicom가 없는 라이선스이거나, 버전 창을 벗어난 유료 라이선스를 사용할 경우에 발생합니다. 임시 Demo/NFR 라이선스도 허용됩니다. 라이선스 로드 방법은 License Setup 를 참조하십시오.
내장 뷰어가 이러한 형식을 처리하지 못하기 때문에, 런타임 게이트는 나중에 해당 기능이 사용 불가능해지면 강력히 실패합니다:
LicenseException: This document type requires the 'Dicom' plugin license.라이선스 및 워터마크
| 라이선스 상태 | 시작 | DICOM 출력 |
|---|---|---|
유료 라이선스가 Dicom를 부여하고, 버전 창 내에 있음 | 시작 | 일반 페이지 워터마크 규칙에 따라 렌더링됩니다 |
| 활성 임시 (Demo/NFR) 라이선스 | 시작 | 평가 워터마크와 함께 렌더링됩니다 |
라이선스 없음, 레거시 TRIAL 파일, Dicom가 없는 라이선스, 또는 버전 창을 벗어난 유료 라이선스 | AddDoconut() 예외를 발생시킵니다 | — |
일반 페이지 워터마크 결정은 DICOM 출력에도 적용됩니다. 애니메이션 출력의 경우, 각 GIF 프레임에 워터마크가 찍혀 재생 전체 동안 표시됩니다. 맞춤형 DocOptions.Watermark은 라이선스 경로가 맞춤 워터마크를 허용할 때만 사용되며, 평가 워터마크를 대체할 수 없습니다.
C#에서 사용하기
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
DisplayMode = DicomDisplayMode.AnimationAndFrames
});이 플러그인을 통해 열리는 세션에 대해, Viewer 은 태그 메타데이터를 노출합니다:
var metadata = await viewer.GetDicomMetadataAsync(token);
// 세션이 DICOM 문서가 아닐 경우 null표시 모드, 해상도 및 메타데이터
표시 모드
다중 프레임 DICOM 파일은 세 가지 방식으로 표시될 수 있습니다 (DicomDisplayMode):
| 모드 | 생성된 페이지 | 용도 |
|---|---|---|
AnimationOnly | 페이지 1 = 모든 프레임을 순환하는 애니메이션 GIF | 빠른 시네마틱 검토 |
FramesOnly | 페이지 1..N = 프레임당 하나의 정적 PNG | 프레임별 진단 탐색 |
AnimationAndFrames (default) | 페이지 1 = 애니메이션 GIF, 페이지 2..N+1 = 프레임당 하나의 정적 PNG (N = 프레임 수) | 한 문서에 개요와 상세 |
애니메이션 타이밍은 AnimationFrameDelayMs (기본값 100 ms = 10 FPS; GIF 세분성은 10 ms 단위)와 LoopCount (0 = 무한 반복)으로 제어됩니다.
해상도
DicomConfig 은 기본적으로 축당 100 DPI로 렌더링됩니다. 해상도 속성에는 알아두면 좋은 폴백 체인이 있습니다: HorizontalResolution/VerticalResolution 을 명시적으로 설정하지 않으면, 설정된 경우 BaseConfig.ImageResolution 를 따르고, 그 다음에 100으로 폴백됩니다.
// 기본 속성을 통한 균일 버프…
new DicomConfig { ImageResolution = 150 };
// …또는 축별 제어
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };메타데이터
DicomMetadata 은 기술 및 이미지 태그만 포함합니다 — 프레임 수, 차원, 비트 깊이, 광도 해석, 전송 구문, 모달리티 및 기본 윈도우 레벨. 환자를 식별할 수 있는 데이터는 포함하지 않습니다. 전체 목록은 API 참조 에 있습니다.
뷰어에서
뷰어는 DICOM 전용 설정이 필요 없습니다. 열려 있는 문서가 DICOM 파일인 경우, 메타데이터 (?token=<token>&meta=1)를 요청하고 기술 속성 패널을 여는 DICOM 버튼을 추가합니다. 해당 요청이 실패하면 패널은 숨겨지고 문서는 계속 렌더링됩니다.
자체 프론트엔드 구축
메타데이터는 UseDoconut() 가 마운트된 경로(보통 /doconut) 아래 HTTP를 통해 사용할 수 있으며, 모든 열려 있는 문서 토큰에 대해 제공됩니다:
| 경로 | 목적 | 성공 응답 |
|---|---|---|
GET ?token=<token>&meta=1 | 열린 DICOM 문서의 기술 메타데이터 읽기 | 200 — DicomMetadata JSON 형식으로, API 참조 의 속성 이름을 사용하여 (Width, Height, NumberOfFrames, …) |
| 상태 | 상황 | 본문 |
|---|---|---|
404 | 문서가 DICOM 파일이 아닙니다 | 상태만 |
500 | 메타데이터 읽기 실패 | { "error": "metadata failed" } |
페이지 이미지(애니메이션 첫 페이지 포함)는 표준 뷰어 이미지 경로를 사용합니다.
프로덕션 환경에서
다중 프레임 연구는 애니메이션과 프레임당 정적 페이지를 모두 생성할 수 있습니다. AnimationAndFrames 은 가장 풍부한 탐색을 제공하지만 렌더링 및 캐시 비용이 가장 높습니다. 대규모 연구의 경우:
- 프레임 검사가 시네마틱 재생보다 중요할 때
FramesOnly을 사용하십시오; - 메모리를 측정하지 않고 해상도 축을 모두 증가시키는 것을 피하십시오;
- 연구가 더 이상 열려 있지 않을 때 세션을 명시적으로 종료하십시오;
- 반복 접근 이점이 보관된 이미지를 능가할 때만
CachePages을 활성화된 상태로 유지하십시오.
각 서버에 Doconut.Viewer.Dicom.lic 를 Doconut.Viewer.lic 옆에 배치하십시오.
API 참조
DicomConfig, DicomDisplayMode 및 DicomMetadata 은 Doconut 네임스페이스에 있습니다. DicomPlugin 은 Doconut.Plugins.Dicom 에 있습니다. 전체 DicomConfig 속성 테이블은 포맷 설정 에 있습니다.
DicomConfig
public sealed class DicomConfig : BaseConfig
{
public int HorizontalResolution { get; set; } // default: 설정된 경우 ImageResolution, 그렇지 않으면 100
public int VerticalResolution { get; set; } // default: 설정된 경우 ImageResolution, 그렇지 않으면 100
public int AnimationFrameDelayMs { get; set; } = 100;
public ushort LoopCount { get; set; } = 0; // 0 = 무한 반복
public DicomDisplayMode DisplayMode { get; set; } = DicomDisplayMode.AnimationAndFrames;
}DicomDisplayMode
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }Viewer.GetDicomMetadataAsync
public Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default);문서가 DICOM 파일이 아닐 경우 null 를 반환합니다. 토큰이 알 수 없거나 만료된 경우 InvalidOperationException 를 발생시킵니다.
DicomMetadata
public sealed class DicomMetadata
{
public int Width { get; init; }
public int Height { get; init; }
public int NumberOfFrames { get; init; }
public int BitsAllocated { get; init; }
public int BitsStored { get; init; }
public int SamplesPerPixel { get; init; }
public string? PhotometricInterpretation { get; init; }
public string? PixelRepresentation { get; init; } // "Unsigned" 또는 "Signed"
public string? PlanarConfiguration { get; init; }
public string? TransferSyntax { get; init; }
public string? Modality { get; init; } // null 노출되지 않을 때
public double? WindowCenter { get; init; }
public double? WindowWidth { get; init; }
public bool IsColor { get; init; }
}문제 해결
| 증상 | 원인 | 해결 방법 |
|---|---|---|
AddDoconut() 예외 발생 The Dicom plugin is registered via AddPlugin but no active license grants Dicom. | 라이선스가 없거나, TRIAL 파일, Dicom 가 없는 라이선스, 혹은 버전 기간을 벗어난 유료 라이선스 | Dicom 를 부여하는 라이선스를 설치하거나, AddPlugin<DicomPlugin>() 를 제거합니다. |
.dcm 파일을 열 때 Document format '.dcm' is not supported. 예외가 발생합니다. | DicomPlugin 가 등록되지 않았거나, 패키지가 배포되지 않았습니다. | AddDoconut() 안에 AddPlugin<DicomPlugin>() 를 추가하고 패키지를 배포합니다. |
.dcm 파일을 열 때 LicenseException: This document type requires the 'Dicom' plugin license. 예외가 발생합니다. | 로드된 라이선스가 더 이상 Dicom 를 부여하지 않습니다. | Dicom 를 부여하는 라이선스를 설치합니다. |
| 한 페이지만 표시됩니다. | 소스가 단일 프레임이거나, DisplayMode 가 AnimationOnly 입니다. | 다중 프레임 소스의 경우 FramesOnly 또는 AnimationAndFrames 를 사용합니다. |
| 애니메이션이 너무 빠르거나 느립니다. | AnimationFrameDelayMs 가 꺼져 있습니다; 실제 GIF 타이밍은 10 ms 단위를 사용합니다. | AnimationFrameDelayMs 를 조정합니다. |
| 대형 멀티프레임 파일에서 메모리가 증가합니다. | 디스플레이 모드, 해상도 및 페이지 캐시가 모두 유지된 이미지를 추가합니다. | 프로덕션에서 을 참조하십시오; 세션을 명시적으로 종료합니다. |
메타데이터가 null 입니다. | 문서가 DICOM 파일이 아닙니다. | 메타데이터를 요청하기 전에 파일 유형을 확인하십시오. |
GetDicomMetadataAsync 예외 발생 Document session not found. Please re-open document. | 토큰이 만료되었거나 열리지 않았습니다. | 문서를 다시 엽니다. |
이 페이지가 도움이 되었나요?