DICOM 플러그인

DicomPlugin으로 의료 이미지를 보기

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

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

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

패키지 설치

bash
dotnet add package Doconut.NETStandard.Dicom

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

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

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

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

플러그인 등록

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
// base property를 통한 균일 범프…
new DicomConfig { ImageResolution = 150 };

// …또는 축별 제어
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };

메타데이터

DicomMetadata는 기술 및 이미지 태그만 포함합니다 — 프레임 수, 차원, 비트 깊이, 광도 해석, 전송 구문, 모달리티 및 기본 윈도우 레벨. 환자를 식별할 수 있는 데이터는 포함하지 않습니다. 전체 목록은 API reference에 있습니다. 이 패키지에서는 메타데이터를 사용할 수 없으며, Framework notes를 참조하십시오.

뷰어에서

뷰어는 DICOM 전용 설정이 필요 없습니다. 열려 있는 문서가 DICOM 파일인 경우, 메타데이터를 요청(?token=<token>&meta=1)하고 DICOM 버튼을 추가하여 기술 속성 패널을 엽니다. 해당 요청이 실패하면 패널은 숨겨진 상태로 유지되고 문서는 계속 렌더링됩니다. 이 패키지에서는 요청이 501로 응답하므로 패널이 절대 나타나지 않습니다.

자체 프론트엔드 구축

메타데이터는 UseDoconut()가 마운트된 경로(보통 /doconut) 아래 HTTP를 통해 사용할 수 있으며, 모든 열린 문서 토큰에 대해 제공됩니다:

경로목적성공 응답
GET ?token=<token>&meta=1열린 DICOM 문서의 기술 메타데이터를 읽음200 — DicomMetadata를 JSON 형태로 반환, API reference의 속성 이름(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 속성 표는 Format Configs에 있습니다.

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;
}

Dicom 디스플레이 모드

csharp
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }

Viewer.GetDicomMetadataAsync 메서드

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

문서가 DICOM 파일이 아닐 경우 null을 반환하고, 이 패키지에서는 항상 null을 반환합니다. 토큰이 알 수 없거나 만료된 경우 InvalidOperationException을 발생시킵니다.

Dicom 메타데이터

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 8 패키지를 사용하십시오
GetDicomMetadataAsync 예외 발생 Document session not found. Please re-open document.토큰이 만료되었거나 열리지 않았습니다문서를 다시 열십시오

프레임워크 참고 사항

  • DICOM 메타데이터 없음. DICOM 페이지 렌더링, 개별 프레임, 애니메이션, 변환 및 워터마킹이 지원됩니다. 기술 태그 메타데이터는 메타데이터 리더가 .NET 8 빌드만 제공하기 때문에 .NET Standard 패키지에서는 사용할 수 없습니다. 따라서 Viewer.GetDicomMetadataAsync(token)은 DICOM 세션에 대해 null을 반환하고 한 번만 경고를 기록합니다. 해당 ?token=…&meta=1 요청은 HTTP 501 Not Implemented와 안정적인 오류 코드 dicom_metadata_unsupported를 반환합니다. 기술적인 DICOM 메타데이터가 필요할 경우 .NET 8 패키지를 사용하십시오.
  • Windows 전용, .NET Standard 패키지의 나머지와 동일합니다.

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