Renamed DicomMultiFrameStreamer to DICOMMultiFrameStreamer and FAST_MODULE_Dicom to FAST_MODULE_DICOM to be more consistent

smistad · smistad · commit 98f0e9a10d7b · 2025-12-02T09:00:22.000+01:00
diff --git a/.github/workflows/CI-mac-arm64.yml b/.github/workflows/CI-mac-arm64.yml
@@ -52,7 +52,7 @@ jobs:
             -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}}\
             -DCMAKE_OSX_ARCHITECTURES:STRING="arm64" \
             -DFAST_MODULE_OpenVINO=OFF \
-            -DFAST_MODULE_Dicom=ON \
+            -DFAST_MODULE_DICOM=ON \
             -DFAST_MODULE_WholeSlideImaging=ON \
             -DFAST_MODULE_OpenIGTLink=ON \
             -DFAST_MODULE_Clarius=OFF \
diff --git a/.github/workflows/CI-mac-x86_64.yml b/.github/workflows/CI-mac-x86_64.yml
@@ -47,7 +47,7 @@ jobs:
             -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}}\
             -DCMAKE_OSX_ARCHITECTURES:STRING="x86_64" \
             -DFAST_MODULE_OpenVINO=ON \
-            -DFAST_MODULE_Dicom=ON \
+            -DFAST_MODULE_DICOM=ON \
             -DFAST_MODULE_WholeSlideImaging=ON \
             -DFAST_MODULE_OpenIGTLink=ON \
             -DFAST_MODULE_Clarius=ON \
diff --git a/.github/workflows/CI-ubuntu.yml b/.github/workflows/CI-ubuntu.yml
@@ -89,7 +89,7 @@ jobs:
           cmake -B build \
               -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}}\
               -DFAST_MODULE_OpenVINO=ON \
-              -DFAST_MODULE_Dicom=ON \
+              -DFAST_MODULE_DICOM=ON \
               -DFAST_MODULE_WholeSlideImaging=ON \
               -DFAST_MODULE_OpenIGTLink=ON \
               -DFAST_MODULE_Clarius=ON \
diff --git a/.github/workflows/CI-windows.yml b/.github/workflows/CI-windows.yml
@@ -117,7 +117,7 @@ jobs:
         cmake ${{github.workspace}} -B ${{github.workspace}}/build `
             -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}} `
             -DFAST_MODULE_OpenVINO=ON `
-            -DFAST_MODULE_Dicom=ON `
+            -DFAST_MODULE_DICOM=ON `
             -DFAST_MODULE_WholeSlideImaging=ON `
             -DFAST_MODULE_OpenIGTLink=ON `
             -DFAST_MODULE_Clarius=ON `
@@ -141,7 +141,7 @@ jobs:
             -B ${{github.workspace}}/build `
             -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}} `
             -DFAST_MODULE_OpenVINO=ON `
-            -DFAST_MODULE_Dicom=ON `
+            -DFAST_MODULE_DICOM=ON `
             -DFAST_MODULE_WholeSlideImaging=ON `
             -DFAST_MODULE_OpenIGTLink=ON `
             -DFAST_MODULE_Clarius=ON `
diff --git a/.github/workflows/FP-mac-arm64.yml b/.github/workflows/FP-mac-arm64.yml
@@ -23,7 +23,7 @@ jobs:
             -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}}\
             -DCMAKE_OSX_ARCHITECTURES:STRING="arm64" \
             -DFAST_MODULE_OpenVINO=OFF \
-            -DFAST_MODULE_Dicom=OFF \
+            -DFAST_MODULE_DICOM=OFF \
             -DFAST_MODULE_WholeSlideImaging=ON \
             -DFAST_MODULE_OpenIGTLink=OFF \
             -DFAST_MODULE_Clarius=OFF \
diff --git a/.github/workflows/FP-mac.yml b/.github/workflows/FP-mac.yml
@@ -23,7 +23,7 @@ jobs:
         cmake -B ${{github.workspace}}/build \
             -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}}\
             -DFAST_MODULE_OpenVINO=ON \
-            -DFAST_MODULE_Dicom=OFF \
+            -DFAST_MODULE_DICOM=OFF \
             -DFAST_MODULE_WholeSlideImaging=ON \
             -DFAST_MODULE_OpenIGTLink=OFF \
             -DFAST_MODULE_Clarius=OFF \
diff --git a/.github/workflows/FP-ubuntu.yml b/.github/workflows/FP-ubuntu.yml
@@ -49,7 +49,7 @@ jobs:
         cmake -B build \
             -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}}\
             -DFAST_MODULE_OpenVINO=ON \
-            -DFAST_MODULE_Dicom=OFF \
+            -DFAST_MODULE_DICOM=OFF \
             -DFAST_MODULE_WholeSlideImaging=ON \
             -DFAST_MODULE_OpenIGTLink=OFF \
             -DFAST_MODULE_Clarius=OFF \
diff --git a/.github/workflows/FP-windows.yml b/.github/workflows/FP-windows.yml
@@ -108,7 +108,7 @@ jobs:
         cmake ${{github.workspace}} -B ${{github.workspace}}/build `
             -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}} `
             -DFAST_MODULE_OpenVINO=ON `
-            -DFAST_MODULE_Dicom=OFF `
+            -DFAST_MODULE_DICOM=OFF `
             -DFAST_MODULE_WholeSlideImaging=ON `
             -DFAST_MODULE_OpenIGTLink=OFF `
             -DFAST_MODULE_Clarius=OFF `
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -6,8 +6,8 @@ endif()
 project(FAST)
 
 set(VERSION_MAJOR 4)
-set(VERSION_MINOR 14)
-set(VERSION_PATCH 2)
+set(VERSION_MINOR 15)
+set(VERSION_PATCH 0)
 set(VERSION_SO 4)   # SO version, should be incremented by 1 every time the existing API changes
 set(FAST_VERSION "${VERSION_MAJOR}.${VERSION_MINOR}.${VERSION_PATCH}")
 
@@ -48,7 +48,7 @@ else()
 endif()
 option(FAST_MODULE_Clarius "Build clarius ultrasound module" ON)
 option(FAST_MODULE_WholeSlideImaging "Build whole slide imaging module" ON)
-option(FAST_MODULE_Dicom "Build DICOM module (DCMTK)" ON)
+option(FAST_MODULE_DICOM "Build DICOM module (DCMTK)" ON)
 option(FAST_MODULE_HDF5 "Build HDF5 module" OFF)
 option(FAST_MODULE_Plotting "Build plotting module (JKQTPlotter)" OFF)
 option(FAST_CONTINUOUS_INTEGRATION "Used for continuous integration tests" OFF)
diff --git a/cmake/Dependencies.cmake b/cmake/Dependencies.cmake
@@ -160,7 +160,7 @@ include(cmake/ModuleKinect.cmake)
 include(cmake/ModuleRealSense.cmake)
 include(cmake/ModuleWholeSlideImaging.cmake)
 include(cmake/ModuleClarius.cmake)
-include(cmake/ModuleDicom.cmake)
+include(cmake/ModuleDICOM.cmake)
 include(cmake/ModuleHDF5.cmake)
 include(cmake/ModulePlotting.cmake)
 
diff --git a/cmake/ModuleDICOM.cmake b/cmake/ModuleDICOM.cmake
@@ -1,5 +1,5 @@
 
-if(FAST_MODULE_Dicom)
+if(FAST_MODULE_DICOM)
     message("-- Enabling dicom (DCMTK) module.")
     add_definitions("-DFAST_MODULE_DICOM")
     if(WIN32)
diff --git a/doc/pages/Linux-instructions.md b/doc/pages/Linux-instructions.md
@@ -54,7 +54,7 @@ Here is a list of some options which might be useful:
 * FAST_MODULE_TensorFlow
 * FAST_MODULE_TensorRT
 * FAST_MODULE_OpenVINO
-* FAST_MODULE_Dicom
+* FAST_MODULE_DICOM
 * FAST_MODULE_WholeSlideImaging
 * FAST_MODULE_OpenIGTLink
 * FAST_MODULE_Clarius
diff --git a/doc/pages/Mac-OS-X-instructions.md b/doc/pages/Mac-OS-X-instructions.md
@@ -44,7 +44,7 @@ Here is a list of some options which might be useful:
 * FAST_MODULE_TensorFlo (not supported on Apple Silicon)w
 * FAST_MODULE_TensorRT (not supported on Mac)
 * FAST_MODULE_OpenVIN (not supported on Apple Silicon)O
-* FAST_MODULE_Dicom
+* FAST_MODULE_DICOM
 * FAST_MODULE_WholeSlideImaging
 * FAST_MODULE_OpenIGTLink
 * FAST_MODULE_Clarius (not supported on Apple Silicon)
diff --git a/doc/pages/Python-tutorial-ultrasound.dox b/doc/pages/Python-tutorial-ultrasound.dox
@@ -8,7 +8,7 @@ Ultrasound data
 ---------------------
 Ultrasound image data comes in many formats; as 2D images or 3D volumes, and often ultrasound data is a sequence
 of images/volumes over time.
-FAST can read sequences of ultrasound data stored as videos, images (.png/.jpeg), metaimages (.mhd/.raw/.zraw) and in ultrasound file format (UFF, HDF5).
+FAST can read sequences of ultrasound data stored as videos, DICOM multi-frame files (.dcm), images (.png/.jpeg), metaimages (.mhd/.raw/.zraw) and in ultrasound file format (UFF, HDF5).
 FAST can also stream data in real-time from ultrasound scanners either using the OpenIGTLink protocol or from Clarius scanners using their Cast API.
 Let's look at how we can stream data from each of these sources.
 
@@ -21,6 +21,7 @@ fast.downloadTestDataIfNotExists()
 Reading and visualizing ultrasound images
 ---------------------
 
+
 ### Read ultrasound images from a video
 Use the MovieStreamer object to read image frames from a video.
 Note that videos are often stored as color data, even though ultrasound videos typically are grayscale.
@@ -87,6 +88,33 @@ for frame in fast.DataStream(streamer):
 
 @image html images/examples/python/video_frames.jpg width=400px;
 
+### Read ultrasound images from a DICOM multiframe file
+
+In the DICOM format, ultrasound recordings are typically stored as a multiframe file.
+With this file format, all ultrasound video frames are stored in the same file and might be compressed with JPEG or other
+image compression formats.
+Such DICOM files can be read using the DICOMMultiFrameStreamer.
+This streamer has a useful option to crop the images to the region of interest (ROI) that is stored in the DICOM file.
+This typically removes part of the scanner GUI that is in the image, while keeping the actual ultrasound image.
+The streamer also has options to convert the image to grayscale and loop. By default it will stream images in the framerate
+that is stored in the DICOM file. You can override the framerate by setting the framerate in the create method.
+If you want to stream as fast as possible, you can disable the use of the file framerate by setting useFramerate=False
+in create().
+
+@code{.py}
+import fast
+
+streamer = fast.DICOMMultiFrameStreamer.create(
+    'path_to_dicom_file.dcm',
+    loop=True,
+    grayscale=False,
+    cropToROI=True,
+)
+
+fast.display2D(streamer)
+@endcode
+
+
 ### Read a single ultrasound image and convert to numpy array
 
 To read a single ultrasound image you can use the ImageFileImporter, and get the Image object using the runAndGetOutputData method.
diff --git a/doc/pages/Windows-instructions.md b/doc/pages/Windows-instructions.md
@@ -53,7 +53,7 @@ Here is a list of some options which might be useful:
 * FAST_MODULE_TensorFlow
 * FAST_MODULE_TensorRT
 * FAST_MODULE_OpenVINO
-* FAST_MODULE_Dicom
+* FAST_MODULE_DICOM
 * FAST_MODULE_WholeSlideImaging
 * FAST_MODULE_OpenIGTLink
 * FAST_MODULE_Clarius
diff --git a/source/FAST/Streamers/CMakeLists.txt b/source/FAST/Streamers/CMakeLists.txt
@@ -22,22 +22,22 @@ fast_add_python_interfaces(
 )
 fast_add_python_shared_pointers(Streamer RandomAccessStreamer FileStreamer MeshFileStreamer)
 fast_add_process_object(ImageFileStreamer ImageFileStreamer.hpp)
-if(FAST_MODULE_Dicom)
-    fast_add_sources(DicomMultiFrameStreamer.cpp DicomMultiFrameStreamer.hpp)
-    fast_add_process_object(DicomMultiFrameStreamer DicomMultiFrameStreamer.hpp)
-    fast_add_test_sources(Tests/DicomMultiFrameStreamerTests.cpp)
+if(FAST_MODULE_DICOM)
+    fast_add_sources(DICOMMultiFrameStreamer.cpp DICOMMultiFrameStreamer.hpp)
+    fast_add_process_object(DICOMMultiFrameStreamer DICOMMultiFrameStreamer.hpp)
+    fast_add_test_sources(Tests/DICOMMultiFrameStreamerTests.cpp)
 endif()
 if(FAST_MODULE_OpenIGTLink)
     fast_add_sources(
-            OpenIGTLinkStreamer.hpp
-            OpenIGTLinkStreamer.cpp
+        OpenIGTLinkStreamer.hpp
+        OpenIGTLinkStreamer.cpp
         Tests/DummyIGTLServer.cpp
         Tests/DummyIGTLServer.hpp
     )
     fast_add_process_object(OpenIGTLinkStreamer OpenIGTLinkStreamer.hpp)
     if(FAST_MODULE_Visualization)
     fast_add_test_sources(
-            Tests/OpenIGTLinkStreamerTests.cpp
+        Tests/OpenIGTLinkStreamerTests.cpp
     )
     endif()
 endif()
diff --git a/source/FAST/Streamers/DICOMMultiFrameStreamer.cpp b/source/FAST/Streamers/DICOMMultiFrameStreamer.cpp
@@ -1,4 +1,4 @@
-#include "DicomMultiFrameStreamer.hpp"
+#include "DICOMMultiFrameStreamer.hpp"
 #include "dcmtk/dcmimage/diregist.h"
 #include <dcmtk/dcmdata/dcfilefo.h>
 #include <dcmtk/dcmdata/dcdeftag.h>
@@ -13,7 +13,7 @@ namespace fast {
 
 /*
 template <>
-std::string DicomMultiFrameStreamer::getDicomTag<std::string>(ushort group, ushort element) {
+std::string DICOMMultiFrameStreamer::getDICOMTag<std::string>(ushort group, ushort element) {
     if(!m_dataset)
         load();
     OFString patientID;
@@ -22,7 +22,7 @@ std::string DicomMultiFrameStreamer::getDicomTag<std::string>(ushort group, usho
 }
 */
 
-DicomMultiFrameStreamer::DicomMultiFrameStreamer(std::string filename, bool loop, bool useFramerate, int framerate, bool convertToGrayscale, bool cropToROI) {
+DICOMMultiFrameStreamer::DICOMMultiFrameStreamer(std::string filename, bool loop, bool useFramerate, int framerate, bool convertToGrayscale, bool cropToROI) {
     createOutputPort(0);
     m_filename = filename;
     m_convertToGrayscale = convertToGrayscale;
@@ -33,13 +33,13 @@ DicomMultiFrameStreamer::DicomMultiFrameStreamer(std::string filename, bool loop
     DJDecoderRegistration::registerCodecs();// register JPEG codecs
 }
 
-void DicomMultiFrameStreamer::execute() {
+void DICOMMultiFrameStreamer::execute() {
     startStream();
 
     waitForFirstFrame();
 }
 
-void DicomMultiFrameStreamer::load() {
+void DICOMMultiFrameStreamer::load() {
     if(!fileExists(m_filename))
         throw FileNotFoundException(m_filename);
 
@@ -55,10 +55,10 @@ void DicomMultiFrameStreamer::load() {
         throw Exception("Unable to read dicom dataset");
     }
     if(m_image->getNumberOfFrames() == 1)
-        throw Exception("Dicom file given to DicomMultiFrameStreamer is not a multi frame file.");
+        throw Exception("DICOM file given to DICOMMultiFrameStreamer is not a multi frame file.");
 }
 
-void DicomMultiFrameStreamer::generateStream() {
+void DICOMMultiFrameStreamer::generateStream() {
     if(!m_image)
         load();
     const int width = m_image->getWidth();
@@ -102,7 +102,7 @@ void DicomMultiFrameStreamer::generateStream() {
         ROIfound = true;
     }
 
-    reportInfo() << "Dicom multi frame size: " << width << " " << height << " frames: " << frames << reportEnd();
+    reportInfo() << "DICOM multi frame size: " << width << " " << height << " frames: " << frames << reportEnd();
 
     auto previousTime = std::chrono::high_resolution_clock::now();
     while(true) {
@@ -154,17 +154,17 @@ void DicomMultiFrameStreamer::generateStream() {
     }
 }
 
-int DicomMultiFrameStreamer::getNrOfFrames() {
+int DICOMMultiFrameStreamer::getNrOfFrames() {
     if(!m_image)
         load();
     return m_image->getNumberOfFrames();
 }
 
-DicomMultiFrameStreamer::DicomMultiFrameStreamer() {
+DICOMMultiFrameStreamer::DICOMMultiFrameStreamer() {
 
 }
 
-DicomMultiFrameStreamer::~DicomMultiFrameStreamer() {
+DICOMMultiFrameStreamer::~DICOMMultiFrameStreamer() {
     DJDecoderRegistration::cleanup();
 }
 }
diff --git a/source/FAST/Streamers/DICOMMultiFrameStreamer.hpp b/source/FAST/Streamers/DICOMMultiFrameStreamer.hpp
@@ -9,27 +9,27 @@ class DcmFileFormat;
 namespace fast {
 
 /**
- * @brief Stream images from a dicom multi-frame image
+ * @brief Stream images from a DICOM multi-frame image
  *
  * <h3>Output ports</h3>
  * - 0: Image
  *
  * @ingroup streamers ultrasound
  */
-class FAST_EXPORT DicomMultiFrameStreamer : public RandomAccessStreamer {
-    FAST_PROCESS_OBJECT(DicomMultiFrameStreamer)
+class FAST_EXPORT DICOMMultiFrameStreamer : public RandomAccessStreamer {
+    FAST_PROCESS_OBJECT(DICOMMultiFrameStreamer)
     public:
         /**
          * @brief Create instance
-         * @param filename Dicom file to open
+         * @param filename DICOM file to open
          * @param loop Whether to loop or not
-         * @param useFramerate Whether to use framerate from dicom file or not. If this is set to false, images will be streamed as fast as possible
+         * @param useFramerate Whether to use framerate from DICOM file or not. If this is set to false, images will be streamed as fast as possible
          * @param framerate If framerate is > 0, this framerate will be used for streaming the images
          * @param grayscale Convert images to grayscale
          * @param cropToROI Try to extract ROI from dicom and crop the images to this ROI
          * @return instance
          */
-        FAST_CONSTRUCTOR(DicomMultiFrameStreamer,
+        FAST_CONSTRUCTOR(DICOMMultiFrameStreamer,
                          std::string, filename,,
                          bool, loop, = false,
                          bool, useFramerate, = true,
@@ -40,9 +40,9 @@ class FAST_EXPORT DicomMultiFrameStreamer : public RandomAccessStreamer {
         int getNrOfFrames() override;
         //template <class T>
         //T getDicomTag(ushort group, ushort element);
-        ~DicomMultiFrameStreamer();
+        ~DICOMMultiFrameStreamer();
     private:
-        DicomMultiFrameStreamer();
+        DICOMMultiFrameStreamer();
         void execute();
         void generateStream() override;
         void load();
@@ -57,6 +57,6 @@ class FAST_EXPORT DicomMultiFrameStreamer : public RandomAccessStreamer {
 };
 
 //template<>
-//std::string DicomMultiFrameStreamer::getDicomTag<std::string>(ushort group, ushort element);
+//std::string DICOMMultiFrameStreamer::getDicomTag<std::string>(ushort group, ushort element);
 
 }
diff --git a/source/FAST/Streamers/Tests/DICOMMultiFrameStreamerTests.cpp b/source/FAST/Streamers/Tests/DICOMMultiFrameStreamerTests.cpp
@@ -1,13 +1,13 @@
 #include <FAST/Testing.hpp>
-#include <FAST/Streamers/DicomMultiFrameStreamer.hpp>
+#include <FAST/Streamers/DICOMMultiFrameStreamer.hpp>
 #include <FAST/Visualization/ImageRenderer/ImageRenderer.hpp>
 #include <FAST/Visualization/SimpleWindow.hpp>
 #include <FAST/Visualization/Widgets/PlaybackWidget/PlaybackWidget.hpp>
 
 using namespace fast;
 
-TEST_CASE("DicomMultiFrameStreamer", "[fast][DicomMultiFrameStreamer][visual]") {
-    auto streamer = DicomMultiFrameStreamer::create(
+TEST_CASE("DICOMMultiFrameStreamer", "[fast][DICOMMultiFrameStreamer][visual]") {
+    auto streamer = DICOMMultiFrameStreamer::create(
             "file",
             false,
             true,
