DICOM 플러그인

DicomPlugin으로 의료 이미지를 보기

DICOM 플러그인은 Doconut에 의료 이미지 보기 기능을 추가합니다: 다중 프레임 DICOM 파일은 애니메이션 개요, 개별 프레임, 또는 둘 다로 렌더링됩니다. DICOM은 플러그인 전용 포맷이며 — 이 플러그인(및 해당 라이선스 기능) 없이는 .dcm 파일을 전혀 열 수 없습니다.

표면사용 시기
Viewer와 DicomConfig (C#)서버에서 DICOM 파일을 열고 프레임이 표시되는 방식을 선택합니다
뷰어 (docViewer)페이지에 연구를 표시합니다: 애니메이션 및 프레임

플러그인 자체 위젯이 없습니다: DICOM 파일은 일반 뷰어에서 열립니다. 컨버터 플러그인도 등록하면, .dcm 및 .ima 파일을 Pdf, Png, Jpeg, Bmp, Tiff 또는 Gif 로 변환할 수 있습니다; 해당 변환에는 Dicom 기능도 필요합니다.

패키지 설치

bash
dotnet add package Doconut.NET6.Dicom

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

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

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

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

플랫폼. 플러그인은 Doconut.NET6가 실행되는 모든 곳에서 동작합니다: 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 라이선스도 허용됩니다. 라이선스 로드 방법은 라이선스 설정을 참조하십시오.

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

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.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 버튼을 추가하여 기술 속성 패널을 엽니다. 요청이 실패하면 패널은 숨겨진 상태로 유지되고 문서는 계속 렌더링됩니다. 이 패키지에서는 요청이 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

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을 반환하고, 이 패키지에서는 항상 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 파일이 아닙니다메타데이터를 요청하기 전에 파일 유형을 확인하십시오.
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 요청은 HTTP 501 Not Implemented와 안정적인 오류 코드 dicom_metadata_unsupported를 반환합니다. 기술 DICOM 메타데이터가 필요할 경우 .NET 8 패키지를 사용하십시오.

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