🩻 dcm4che – Spring에서 DICOM 파일 다루기

이 글에서는 dcm4che 라이브러리를 활용해 Spring에서 DICOM 파일을 읽는 방법에 대해 다룹니다. 구현 방법은 🧭 환경 설정 부터 나와있습니다.

왜 dcm4che를 사용하는가

DICOM 파일은 무엇인가

DICOM은 Digital Imaging and COmmunication in Medicine의 약어로, 의료 영상(Medical imaging)에서 사용하는 이미지 형식이다. 정의는 아래와 같다.

의료용 디지털 영상 및 통신(Digital Imaging and Communications in Medicine, DICOM) 표준은 의료용 기기에서 디지털 영상표현과 통신에 사용되는 여러 가지 표준을 총칭하는 말이다.

DICOM 파일에는 이미지와 메타 데이터(key-value 형식)가 포함되어 있다. 이미지의 크기가 클 뿐더러 이에 대한 메타 데이터도 포함하고 있기에 각 파일의 용량이 20~30MB 정도로 크다. 내가 다뤘던 Mammography 이미지가 평균적으로 그랬다는거지, 더 클 수도 있다.

왜 DICOM 파일을 사용하는가

현재 개발 중인 것은 Mammography 이미지로 유방암 발생률을 진단하는 제품이다. 이때 Mammography 이미지가 DICOM 파일이다. 이에 대한 진단 결과(Secondary capture) 또한 DICOM 파일로 구성되어있다. 진단 결과는 인퍼런스를 통해 나오는데, 인퍼런스가 불가한 조건을 필터링해 valid한 이미지만 AI 서버에 전달해야 한다. 이를 위해 DICOM 파일을 읽어 태그를 validation한다. 예를 들자면, 이미지의 분류가 Mammography가 아닌 경우 invalid한 이미지로 분류되는 식이다.

왜 굳이 dcm4che를 쓰는가

DICOM 이미지의 validation은 key-value 형식의 메타 데이터, 즉 tag를 검증하는 방식으로 구현했다. tag를 읽기 위해서는 DICOM 파일을 읽는 라이브러리를 사용해야 했다. Java로 DICOM 파일을 읽기 위해 여러 라이브러리를 찾아봤지만, dcm4che가 Java 라이브러리들 중 가장 사용 빈도가 높아 사용하기로 결정했다. 또한 dcm4che는 의존성 설정만으로 간단하게 사용할 수 있기에 선택하게 되었다.

🧭 환경 설정

environment

• Spring Boot v3.3.1
• Gradle build

의존성 설정

해당 라이브러리는 maven central에 없는 아티팩트이기 때문에 다른 repository를 등록해야 한다. repository 등록 없이 진행하면 정상적으로 동작하지 않는다.
이 글에서는 아래의 아티팩트만을 사용했지만, 다른 기능을 사용하기 위해서는 maven repository에서 검색 후 찾아서 사용하는 것을 권장한다.

• Maven Repository: org.dcm4che » dcm4che-core
• Maven Repository: org.dcm4che.tool » dcm4che-tool-common
• Maven Repository: org.dcm4che » dcm4che-json

...
repositories {
    mavenCentral()
    maven{ // repository 등록
        url "https://maven.scijava.org/content/repositories/public/"
    }
}

dependencies {
    ...
    // dcm4che
    implementation 'org.dcm4che:dcm4che-core:5.31.1'
    implementation 'org.dcm4che.tool:dcm4che-tool-common:5.30.0'
    implementation 'org.dcm4che.tool:dcm4che-tool-dcm2json:5.30.0'
	...
}
...

🚀 How to use

아래는 DICOM 파일의 태그를 파싱하고 이를 validation하는 예제이다. 원하는 태그만 읽어서 저장해둘 수 있도록 DicomTagValue 클래스를 아래와 같이 선언했다.

DicomTagValue.java

package example.api.instance.util;

import java.util.Date;
import lombok.AllArgsConstructor;
import lombok.Data;

@Data
@AllArgsConstructor
public class DicomTagValue {

    private String patientName;
    private String institutionName;
    private String patientId;
    private String studyInstanceUid;
    private String SOPInstanceUid;

    private String SOPClassUid;
    private String viewPosition;
    private String imageLaterality;
    private String imageType;
    private Double estimatedRadiographicMagnificationFactor;
    private String patientSex;
    private String breastImplantPresent;
    private String performedProcedureStepDescription;
    private String seriesDescription;
    private String ProtocolName;
    private String presentationLUTShape;
    private String exposureStatus;

    private String studyDescription;
    private Date studyDate;
}

DicomTagParser.java

parser가 각 태그에 맞는 자료형으로 값을 추출하길 바랬기 때문에 제네릭 타입으로 각 태그를 읽어올 수 있도록 했다. 하지만 뭔가 마음에 들지 않아 차후 리팩토링이 필요할 것으로 보인다.

package example.api.instance.util;

import java.io.File;
import java.io.IOException;
import java.util.Date;
import example.global.exception.DicomTagParseException;
import org.dcm4che3.data.Attributes;
import org.dcm4che3.data.Tag;
import org.dcm4che3.io.DicomInputStream;

/**
 * Dicom tag parser
 */
public class DicomTagParser {

    /**
     * Parse dicom tag
     *
     * @param dicomFile dicom file
     * @return dicom tag value
     */
    public static DicomTagValue parseDicomTag(File dicomFile) {

        DicomTagValue dicomTagValue = new DicomTagValue(
            getDicomTagValue(dicomFile, Tag.PatientName, String.class),
            getDicomTagValue(dicomFile, Tag.InstitutionName, String.class),
            getDicomTagValue(dicomFile, Tag.PatientID, String.class),
            getDicomTagValue(dicomFile, Tag.StudyInstanceUID, String.class),
            getDicomTagValue(dicomFile, Tag.SOPInstanceUID, String.class),
            getDicomTagValue(dicomFile, Tag.SOPClassUID, String.class),
            getDicomTagValue(dicomFile, Tag.ViewPosition, String.class),
            getDicomTagValue(dicomFile, Tag.ImageLaterality, String.class),
            getDicomTagValue(dicomFile, Tag.ImageType, String.class),
            getDicomTagValue(dicomFile, Tag.EstimatedRadiographicMagnificationFactor, Double.class),
            getDicomTagValue(dicomFile, Tag.PatientSex, String.class),
            getDicomTagValue(dicomFile, Tag.BreastImplantPresent, String.class),
            getDicomTagValue(dicomFile, Tag.PerformedProcedureStepDescription, String.class),
            getDicomTagValue(dicomFile, Tag.SeriesDescription, String.class),
            getDicomTagValue(dicomFile, Tag.ProtocolName, String.class),
            getDicomTagValue(dicomFile, Tag.PresentationLUTShape, String.class),
            getDicomTagValue(dicomFile, Tag.ExposureStatus, String.class),
            getDicomTagValue(dicomFile, Tag.StudyDescription, String.class),
            getDicomTagValue(dicomFile, Tag.StudyDate, Date.class)
        );

        return dicomTagValue;
    }

    /**
     * Get dicom tag value
     *
     * @param file dicom file
     * @param tag  dicom tag
     * @param type tag value type
     * @return tag value
     */
    private static <T> T getDicomTagValue(File file, int tag, Class<T> type) {

        try (DicomInputStream dis = new DicomInputStream(file)) {

            Attributes dicomAttributes = dis.readDataset(-1, -1);

            if (type.equals(Double.class)) {
                return (T) Double.valueOf(dicomAttributes.getString(tag));
            }

            if (type.equals(java.util.Date.class)) {
                return (T) dicomAttributes.getDate(tag);
            }

            return (T) dicomAttributes.getString(tag);

        } catch (IOException e) {
            throw new DicomTagParseException();
        }
    }
}

DicomTagValidator.java

DICOM 파일의 태그의 유효성 검사 예시는 아래의 메서드와 같다. 실제로는 public 메서드에서 private 메서드 여러 개를 불러와 검증하는 식으로 구현했다. 나머지 유효성 검사는 조건이 너무 많고 코드가 길어져 생략했다.

/**
  * validate Image that does not contain "supplemental", "localization", "3d", "tomo", "combo",
  * "implant"
  *
  * @param performedProcedureStepDescription PerformedProcedureStepDescription
  * @param SeriesDescription                 SeriesDescription
  * @param protocolName                      ProtocolName
  */
private void validateImage(String performedProcedureStepDescription, String SeriesDescription, String protocolName) {

    List<String> temp = List.of(
        performedProcedureStepDescription,
        SeriesDescription,
        protocolName
    );

    temp = temp.stream()
        .map(String::toLowerCase)
        .toList();

    List<String> NotContains = List.of("supplemental", "localization", "3d", "tomo", "combo",
        "implant");

    if (temp.stream().anyMatch(s -> NotContains.stream().anyMatch(s::contains))) {
        throw new InvalidDicomTagValueException(
            "PerformedProcedureStepDescription, SeriesDescription, ProtocolName");
    }
}

그래서 이걸 어디에 사용할 수 있는데?

어디든 쓸모가 있겠지.....

사실 의료 영상을 다루지 않는다면 굳이 dcm4che를 사용할 필요가 없다. 그럼에도 불구하고 이렇게 정리해두는 것은 내가 의료기기 개발을 하고 있기 때문이다. 라이브러리를 사용해보고자 구글링을 많이 했는데, 한국어로 dcm4che 사용 방법에 대해 정리해둔 글이 거의 없었다. 물론 내가 못찾은 것일수도 있다.

의료 영상 처리? 야 너두 할 수 있어

dcm4che 라이브러리의 가장 큰 장점은 DICOM 파일 핸들링이 쉽게 느껴지도록 많은 기능을 지원해준다는 것이다. 나의 경우, 태그 파싱 작업을 위해 각 태그를 어떻게 입력해줘야 하는 지에 대해 궁금했었는데, DICOM 형식에서 공식적으로 지원하는 태그들을 Tag 클래스로 묶어둬서 굉장히 편리했다.
아쉬운 점은 비슷한 이름의 클래스들이 많아 어떤 클래스를 사용해야 하는 지 모호했다는 점이다. 하지만 이도 개발 초기에만 부각되었던 단점이라 장점이 더 많게 느껴졌다.

앞으로도 DICOM 파일을 다룰 일이 많을 것 같은데, dcm4che 라이브러리를 더 잘 사용할 수 있는 방법을 발견하면 글을 작성해보고자 한다.

---

Reference : 영상 중에서도 의료 영상?, DICOM이란?