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 기능도 필요합니다.

패키지 설치

bash
dotnet add package Doconut.NET8.Dicom

버전이 지정되지 않은 명령은 최신 안정 릴리스를 설치합니다. 이 문서에서 설명하는 릴리스에 플러그인을 고정하려면, 버전을 별도로 전달하십시오:

bash
dotnet add package Doconut.NET8.Dicom --version 26.10.0

Doconut.NET8와 동일한 버전으로 DICOM 패키지를 유지하십시오. 패키지 ID는
Doconut.NET8.Dicom이며, .<version>는 다운로드된 .nupkg 파일명에만 나타납니다.

플러그인의 라이선스 파일인 Doconut.Viewer.Dicom.lic는 Doconut.Viewer.lic와 같은 폴더에 두며; 뷰어 라이선스와 함께 읽힙니다.

플랫폼. 플러그인은 Doconut.NET8가 실행되는 모든 환경에서 동작합니다: Windows와 x64용 glibc 기반 Linux (Alpine이나 기타 musl 기반 배포판 제외). Linux에서는 첫 문서가 열리기 전에 폰트 설정 라이브러리를 설치하십시오:

bash
apt-get update && apt-get install -y libfontconfig1

RHEL, 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.와 함께 실패합니다.

플러그인 등록

csharp
builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

플러그인 (Name: "Doconut DICOM Viewer")은 .dcm 및 .ima 확장자를 위한 뷰어를 등록하며, 이는 Dicom 기능에 의해 제어됩니다. 이를 부여하는 라이선스가 없으면, AddDoconut()는 앱이 요청을 처리하기 전에 시작 시 InvalidOperationException를 발생시킵니다:

text
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 를 참조하십시오.

내장 뷰어가 이러한 형식을 처리하지 못하기 때문에, 런타임 게이트는 나중에 해당 기능이 사용 불가능해지면 강력히 실패합니다:

text
LicenseException: This document type requires the 'Dicom' plugin license.

라이선스 및 워터마크

라이선스 상태시작DICOM 출력
유료 라이선스가 Dicom를 부여하고, 버전 창 내에 있음시작일반 페이지 워터마크 규칙에 따라 렌더링됩니다
활성 임시 (Demo/NFR) 라이선스시작평가 워터마크와 함께 렌더링됩니다
라이선스 없음, 레거시 TRIAL 파일, Dicom가 없는 라이선스, 또는 버전 창을 벗어난 유료 라이선스AddDoconut() 예외를 발생시킵니다—

일반 페이지 워터마크 결정은 DICOM 출력에도 적용됩니다. 애니메이션 출력의 경우, 각 GIF 프레임에 워터마크가 찍혀 재생 전체 동안 표시됩니다. 맞춤형 DocOptions.Watermark은 라이선스 경로가 맞춤 워터마크를 허용할 때만 사용되며, 평가 워터마크를 대체할 수 없습니다.

C#에서 사용하기

csharp
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
    DisplayMode = DicomDisplayMode.AnimationAndFrames
});

이 플러그인을 통해 열리는 세션에 대해, Viewer 은 태그 메타데이터를 노출합니다:

csharp
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으로 폴백됩니다.

csharp
// 기본 속성을 통한 균일 버프…
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

csharp
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

csharp
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }

Viewer.GetDicomMetadataAsync

csharp
public Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default);

문서가 DICOM 파일이 아닐 경우 null 를 반환합니다. 토큰이 알 수 없거나 만료된 경우 InvalidOperationException 를 발생시킵니다.

DicomMetadata

csharp
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.토큰이 만료되었거나 열리지 않았습니다.문서를 다시 엽니다.

이 페이지가 도움이 되었나요?