DICOM 플러그인
DicomPlugin으로 의료 이미지를 보기
DICOM 플러그인은 Doconut에 의료 이미지 보기 기능을 추가합니다: 다중 프레임 DICOM 파일은 애니메이션 개요, 개별 프레임, 또는 둘 다로 렌더링됩니다. DICOM은 플러그인 전용 포맷이며 — 이 플러그인(및 해당 라이선스 기능) 없이는 .dcm 파일을 전혀 열 수 없습니다.
| 표면 | 사용 시기 |
|---|---|
Viewer와 DicomConfig (C#) | 서버에서 DICOM 파일을 열고 프레임이 표시되는 방식을 선택합니다 |
뷰어 (docViewer) | 페이지에 연구를 표시합니다: 애니메이션 및 프레임 |
플러그인 자체 위젯이 없습니다: DICOM 파일은 일반 뷰어에서 열립니다. 컨버터 플러그인도 등록하면, .dcm 및 .ima 파일을 Pdf, Png, Jpeg, Bmp, Tiff 또는 Gif 로 변환할 수 있습니다; 해당 변환에는 Dicom 기능도 필요합니다.
패키지 설치
dotnet add package Doconut.NET6.Dicom버전이 지정되지 않은 명령은 최신 안정 릴리스를 설치합니다. 이 문서에서 설명하는 릴리스에 플러그인을 고정하려면, 버전을 별도로 전달하십시오:
dotnet add package Doconut.NET6.Dicom --version 26.10.0Doconut.NET6와 동일한 버전으로 DICOM 패키지를 유지하십시오. 패키지 ID는
Doconut.NET6.Dicom이며, .<version>은 다운로드된 .nupkg 파일 이름에만 나타납니다.
플러그인의 라이선스 파일인 Doconut.Viewer.Dicom.lic은 Doconut.Viewer.lic와 같은 폴더에 두어야 합니다; 뷰어 라이선스와 함께 읽힙니다.
플랫폼. 플러그인은 Doconut.NET6가 실행되는 모든 곳에서 동작합니다: 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 라이선스도 허용됩니다. 라이선스 로드 방법은 라이선스 설정을 참조하십시오.
내장 뷰어가 이러한 형식을 처리하지 못하기 때문에, 런타임 게이트는 나중에 해당 기능이 사용 불가능해지면 강력히 실패합니다:
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.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 버튼을 추가하여 기술 속성 패널을 엽니다. 요청이 실패하면 패널은 숨겨진 상태로 유지되고 문서는 계속 렌더링됩니다. 이 패키지에서는 요청이 501 로 응답하므로 패널이 절대 나타나지 않습니다.
자신만의 프런트엔드 구축
메타데이터는 UseDoconut() 가 마운트된 경로(보통 /doconut) 아래 HTTP를 통해 사용할 수 있으며, 모든 열려 있는 문서 토큰에 대해 제공됩니다.
| 경로 | 목적 | 성공 응답 |
|---|---|---|
GET ?token=<token>&meta=1 | 열려 있는 DICOM 문서의 기술 메타데이터를 읽음 | 200 — DicomMetadata JSON 형태로, [API 레퍼런스]의 속성 이름(Width, Height, NumberOfFrames, …)을 포함 |
| 상태 | 조건 | 본문 |
|---|---|---|
404 | 문서가 DICOM 파일이 아닙니다 | 상태만 |
501 | 문서는 DICOM 파일이지만, 이 패키지는 해당 태그를 읽을 수 없습니다 | { "error": "dicom_metadata_unsupported", "message": "DICOM technical metadata is not supported on this package: the underlying medical-imaging engine has no build for this target framework. On this package it always returns null; use the .NET 8 package if you need it. DICOM rendering is unaffected." } |
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을 반환하고, 이 패키지에서는 항상 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 파일이 아닙니다 | 메타데이터를 요청하기 전에 파일 유형을 확인하십시오. |
DICOM 파일에 대한 메타데이터가 null이거나, &meta가 501를 반환합니다 | .NET 6 제한으로 예상되는 동작이며, 렌더링에는 영향을 주지 않습니다 | 태그가 필요할 때는 .NET 8 패키지를 사용하십시오. |
GetDicomMetadataAsync 예외 발생 Document session not found. Please re-open document. | 토큰이 만료되었거나 열리지 않았습니다 | 문서를 다시 열어보십시오. |
프레임워크 참고 사항
- DICOM 메타데이터 없음. DICOM 페이지 렌더링, 개별 프레임, 애니메이션, 변환 및 워터마킹이 지원됩니다. 기술 태그 메타데이터는 메타데이터 리더에 .NET 6 빌드가 없기 때문에 .NET 6 패키지에서 사용할 수 없습니다.
Viewer.GetDicomMetadataAsync(token)은(는) 따라서 DICOM 세션에 대해null을 반환하고 한 번만 경고를 기록합니다. 해당?token=…&meta=1요청은 HTTP501 Not Implemented와 안정적인 오류 코드dicom_metadata_unsupported를 반환합니다. 기술 DICOM 메타데이터가 필요할 경우 .NET 8 패키지를 사용하십시오.
이 페이지가 도움이 되었나요?