[Draft] Add HTJ2K DICOM support #1863

jantonguirao · 2025-10-17T09:46:18Z

Add HTJ2K DICOM support and upgrade to pydicom 3.0

Key Changes:

Upgrade to pydicom 3.0.0 for HTJ2K support
Replace pydicom-seg with highdicom (pydicom-seg unmaintained)
Add NvDicomReader for GPU-accelerated DICOM decoding with nvidia-nvimgcodec-cu{XX}
Add transcode_dicom_to_htj2k function to convert utils, to batch transcode a directory of DICOMs to Hight Throughput JPEG2000 (lossless)
Add transcode_dicom_to_htj2k and convert_single_frame_dicom_series_to_multiframe functions to convert utils:
- transcode_dicom_to_htj2k: Batch transcode a directory of DICOMs to High Throughput JPEG2000 (lossless)
- convert_single_frame_dicom_series_to_multiframe: Combine single-frame DICOM series into multi-frame files (optionally with HTJ2K compression)

NvDicomReader Features:

HTJ2K transfer syntax support (1.2.840.10008.1.2.4.{201, 202, 203}
Supports accelerated JPEG and JPEG2000 as well
Batch decoding for DICOM series
Proper spatial slice ordering and affine matrix calculation
Configurable layouts (NumPy-like D,H,W or ITK-like W,H,D)
Fallback to pydicom/SimpleITK when nvimgcodec unavailable

DICOM SEG Improvements:

Migrate to highdicom for DICOM SEG creation
Preserve ITK/dcmqi fallback path

Optional Dependencies:

nvidia-nvimgcodec and dcmqi are optional
Runtime checks with clear installation instructions

Testing:

Comprehensive NvDicomReader tests (HTJ2K decoding, consistency, metadata)
DICOM ↔ NIfTI conversion tests for original and HTJ2K files
Automatic HTJ2K test data generation

Key Changes: - Upgrade to pydicom 3.0.0 for HTJ2K support - Replace pydicom-seg with highdicom (pydicom-seg unmaintained) - Add NvDicomReader for GPU-accelerated DICOM decoding with nvidia-nvimgcodec NvDicomReader Features: - HTJ2K transfer syntax support (1.2.840.10008.1.2.4.201/202/203) - Batch decoding optimization for HTJ2K series - Proper spatial slice ordering and affine matrix calculation - Configurable layouts (NumPy D,H,W or ITK W,H,D) - Fallback to pydicom/SimpleITK when nvimgcodec unavailable DICOM SEG Improvements: - Migrate to highdicom for DICOM SEG creation - Memory-efficient processing with stop_before_pixels - Support up to 65,535 segments (uint16) - Preserve ITK/dcmqi fallback path Optional Dependencies: - nvidia-nvimgcodec and dcmqi are now optional - Runtime checks with clear installation instructions Testing: - Comprehensive NvDicomReader tests (HTJ2K decoding, consistency, metadata) - DICOM ↔ NIfTI conversion tests for original and HTJ2K files - Automatic HTJ2K test data generation Signed-off-by: Joaquin Anton Guirao <[email protected]>

Signed-off-by: Joaquin Anton Guirao <[email protected]>

SachidanandAlle · 2025-10-18T05:34:15Z

Looks good to me.. however better if all E2E is tested and verified for existing use cases to make sure new changes does break.

Thank you for trying to improve monai label.

Signed-off-by: Joaquin Anton Guirao <[email protected]>

…ch processing for large directories Signed-off-by: Joaquin Anton Guirao <[email protected]>

… to different series and run monailabel Signed-off-by: Joaquin Anton Guirao <[email protected]>

coderabbitai · 2025-10-23T17:44:53Z

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

dmoore247 · 2025-10-24T01:01:28Z

@jantonguirao
The PR should handle multi-frame DICOM files that are (now) compressed.
The compression utility create a (Basic or Extended) offset table (An array of integer byte offsets to mark the start of each (compressed) frame). The offset table is stored into the DICOM header.

The frame offsets are used for progressive decoding, download and rendering.

References: https://dicom.nema.org/medical/dicom/current/output/chtml/part05/sect_A.4.html

jantonguirao · 2025-10-24T07:17:53Z

@jantonguirao The PR should handle multi-frame DICOM files that are (now) compressed. The compression utility create a (Basic or Extended) offset table (An array of integer byte offsets to mark the start of each (compressed) frame). The offset table is stored into the DICOM header.

The frame offsets are used for progressive decoding, download and rendering.

References: https://dicom.nema.org/medical/dicom/current/output/chtml/part05/sect_A.4.html

@dmoore247 Currently looking into that. I will let you know once I have something ready for evaluation.

Signed-off-by: Joaquin Anton Guirao <[email protected]>

This commit fixes two critical issues with segmentation display: 1. Segmentations appearing misaligned/misplaced in multi-frame volumes 2. Segmentations misaligned when switching back to previously segmented series Files modified: - MonaiLabelPanel.tsx: Core segmentation logic - PointPrompts.tsx: Removed obsolete method calls Key changes: - Use series-specific segmentation IDs (seg-{SeriesUID}) instead of hardcoded '1' * Prevents conflicts when working with multiple series * Each series maintains its own independent segmentation - Defer segmentation creation until first inference run * Prevents conflicts with default segmentation ID * Creates segmentation per-series on demand - Add origin correction: adapt segmentation to image volume origin * Simple approach: copy image volume origin to segmentation * No complex camera adjustments or offset calculations * Segmentation follows image volume's coordinate system - Detect series switches and reapply origin correction * Subscribe to viewport grid ACTIVE_VIEWPORT_ID_CHANGED event * Automatically corrects alignment when switching to existing segmentations * Handles both tab changes and thumbnail clicks - Simplify segmentation creation on demand * Single 500ms retry instead of complex 50-attempt retry mechanism * Cleaner error handling Impact: - Removed 548 lines of complex retry/tracking/correction logic - Added 136 lines of focused, essential functionality - Net reduction: 412 lines (41% smaller) - More maintainable and robust The solution is elegant: instead of trying to fix the image volume's origin and adjust cameras accordingly, we simply make the segmentation adapt to whatever coordinate system the image volume is using. This eliminates all the complexity around camera position management and origin offset calculations. Signed-off-by: Joaquin Anton Guirao <[email protected]>

…ation validation This commit adds extensive test coverage for multi-frame HTJ2K DICOM handling and improves segmentation output validation across different DICOM formats. Test Improvements - test_dicom_segmentation.py: - Add _load_segmentation_array() helper for consistent segmentation loading - Add _compare_segmentations() helper using Dice coefficient and pixel accuracy - Refactor test_04 to test_04_compare_all_formats for comprehensive cross-format comparison * Compares Standard DICOM, HTJ2K, and Multi-frame HTJ2K outputs * Validates all formats produce highly similar segmentations (Dice > 0.95) - Improve test_05_compare_dicom_vs_nifti with actual segmentation comparison logic - Update test_06_multiframe_htj2k_inference with corrected test data path - Remove redundant tests (test_07, test_08, test_09) - functionality consolidated in test_04 Multi-frame HTJ2K Tests - test_convert.py: - Add HTJ2K_TRANSFER_SYNTAXES constant for explicit transfer syntax validation - Add test_transcode_dicom_to_htj2k_multiframe_metadata() * Validates all DICOM metadata preservation (ImagePositionPatient, ImageOrientationPatient, etc.) * Verifies per-frame functional groups match original files * Checks frame ordering and spatial attributes - Add test_transcode_dicom_to_htj2k_multiframe_lossless() * Validates pixel-perfect lossless compression * Verifies all frames match original pixel data - Add test_transcode_dicom_to_htj2k_multiframe_nifti_consistency() * Ensures multi-frame HTJ2K produces identical NIfTI output as original series - Update all transfer syntax checks to use HTJ2K_TRANSFER_SYNTAXES constant * Replaces .startswith("1.2.840.10008.1.2.4.20") with explicit UID list * Covers all three HTJ2K variants (lossless, RPCL, lossy) Code Cleanup: - Revert debug logging in monailabel/endpoints/infer.py - Add HTJ2K transfer syntax documentation in convert.py All tests pass successfully, validating that: 1. Segmentation outputs are consistent across all DICOM formats 2. Multi-frame HTJ2K transcoding preserves all metadata correctly 3. Multi-frame HTJ2K compression is lossless 4. Multi-frame HTJ2K produces identical results to single-frame series Signed-off-by: Joaquin Anton Guirao <[email protected]>

- Extract helper functions for frame extraction and validation - _extract_frames_from_compressed: Extract frames from encapsulated DICOM (now defaults to 1 frame for single-frame images without NumberOfFrames tag) - _extract_frames_from_uncompressed: Extract frames from pixel arrays - _validate_frames: Check for None values in decoded/encoded frames - _find_dicom_files: Recursively find DICOM files with proper sorting - Add PhotometricInterpretation update from YBR to RGB - Prevents double color space conversion by DICOM readers - Updates metadata to match actual RGB pixel data after nvimgcodec decoding - Add fancy_upsampling=1 option to nvimgcodec decoder - Add comprehensive test coverage using pydicom built-in examples: - test_transcode_multiframe_jpeg_ybr_to_htj2k: 30-frame JPEG with YBR_FULL_422 color space, verifies color space conversion and PhotometricInterpretation update (max_diff: 4.0, atol=5) - test_transcode_ct_example_to_htj2k: Uncompressed CT grayscale (MONOCHROME2), verifies lossless transcoding - test_transcode_mr_example_to_htj2k: Uncompressed MR grayscale (MONOCHROME2), verifies lossless transcoding - test_transcode_rgb_color_example_to_htj2k: Uncompressed RGB color image, verifies PhotometricInterpretation preservation and lossless transcoding - test_transcode_jpeg2k_example_to_htj2k: JPEG 2000 with YBR_RCT (reversible color transform), verifies PhotometricInterpretation update and perfect lossless conversion (max_diff: 0.0)

…retations. Group frames per PhotometricInterpretation before sending them to decode. Signed-off-by: Joaquin Anton Guirao <[email protected]>

This commit adds support for all five JPEG2000 progression orders in HTJ2K encoding, allowing users to optimize compression for different use cases: - LRCP: Layer-Resolution-Component-Position (quality scalability) - RLCP: Resolution-Layer-Component-Position (resolution scalability) - RPCL: Resolution-Position-Component-Layer (progressive by resolution, default) - PCRL: Position-Component-Resolution-Layer (progressive by spatial area) - CPRL: Component-Position-Resolution-Layer (component scalability) Changes: - Extended _setup_htj2k_encode_params() to accept progression_order parameter with validation against supported values - Added proper Transfer Syntax UID mapping for each progression order (1.2.840.10008.1.2.4.201 for LRCP/RLCP/PCRL/CPRL, 1.2.840.10008.1.2.4.202 for RPCL) - Changed bitstream type from JP2 to J2K format - Updated transcode_dicom_to_htj2k() to expose progression_order parameter - Added comprehensive test suite covering all progression orders with various DICOM configurations This enables better control over HTJ2K encoding characteristics based on specific deployment requirements (streaming, quality, resolution scalability). Signed-off-by: Joaquin Anton Guirao <[email protected]>

Introduces a skip_transfer_syntaxes parameter to transcode_dicom_to_htj2k() that allows skipping transcoding for files already in desired formats. Files with specified transfer syntaxes are copied directly to output, avoiding unnecessary re-encoding of already-compressed formats. Default skip list includes: - HTJ2K transfer syntaxes (to avoid re-encoding) - Lossy JPEG 2000 (1.2.840.10008.1.2.4.91) - Lossy JPEG formats (1.2.840.10008.1.2.4.50, 1.2.840.10008.1.2.4.51) Also simplifies Basic Offset Table conditional logic and adds comprehensive unit tests covering skip behavior, statistics tracking, and edge cases. Signed-off-by: Joaquin Anton Guirao <[email protected]>

Signed-off-by: Joaquin Anton Guirao <[email protected]>

- transcode_dicom_to_htj2k now accepts file_loader (Iterable) instead of input_dir/output_dir - Add DicomFileLoader class for simple file discovery and batching - DicomFileLoader preserves directory structure in output paths - Support for PyTorch DataLoader and any custom iterable - Add proper error handling for files without PixelData in both nvimgcodec and pydicom paths - Files causing exceptions during frame extraction are now properly skipped - Add test demonstrating PyTorch DataLoader compatibility Signed-off-by: Joaquin Anton Guirao <[email protected]>

for more information, see https://pre-commit.ci

Removed top-level ImagePositionPatient (line ~1102) Was causing OHIF to use same position for all frames → spacing[2] = 0 Removed top-level ImageOrientationPatient (line ~1108) Was interfering with functional groups parsing Added SOPClassUID setting (line ~1115) Now sets 1.2.840.10008.5.1.4.1.1.2.1 (Enhanced CT Image Storage) Removed per-frame PlaneOrientationSequence (line ~1163) Was triggering wrong parsing logic in OHIF Now only in SharedFunctionalGroupsSequence Updated logging messages Reflects actual OHIF requirements and warnings

Remove top-level ImagePositionPatient (prevents 1/Infinity) Keep top-level ImageOrientationPatient (enables MPR button) Remove per-frame PlaneOrientationSequence (prevents wrong parsing) Set correct SOPClassUID (Enhanced CT)

✅ PlanePositionSequence added to every frame (with default if missing) ✅ PlaneOrientationSequence added to SharedFunctionalGroupsSequence (with standard axial if missing) Both are MANDATORY for Enhanced CT multi-frame files to enable MPR in OHIF. Now regenerate your multi-frame files with the updated script and the MPR button should be active

Multi-frame DICOM file showed "1/Infinity" in OHIF MPR-axial viewport while working fine in stack view.

Signed-off-by: Joaquin Anton Guirao <[email protected]>

for more information, see https://pre-commit.ci

Signed-off-by: Joaquin Anton Guirao <[email protected]>

for more information, see https://pre-commit.ci

Set top level tags.

Fix washout in CT Scans

for more information, see https://pre-commit.ci

jantonguirao changed the title ~~[Draft] Refactor DICOM/NIfTI conversion with highdicom and optional dependencies~~ [Draft] Add HTJ2K DICOM support and upgrade to pydicom 3.0 Oct 17, 2025

jantonguirao changed the title ~~[Draft] Add HTJ2K DICOM support and upgrade to pydicom 3.0~~ [Draft] Add HTJ2K DICOM support Oct 17, 2025

jantonguirao force-pushed the htj2k_support branch 7 times, most recently from abd51e4 to a3a54b3 Compare October 17, 2025 15:40

jantonguirao force-pushed the htj2k_support branch 2 times, most recently from 3736a2b to 119f000 Compare October 17, 2025 17:01

Add batch transcode function to convert utils

7e9e7de

Signed-off-by: Joaquin Anton Guirao <[email protected]>

jantonguirao force-pushed the htj2k_support branch from 638fd66 to 7e9e7de Compare October 17, 2025 17:11

SachidanandAlle approved these changes Oct 18, 2025

View reviewed changes

jantonguirao added 2 commits October 20, 2025 19:53

Enable Lossless JPEG

67da848

Signed-off-by: Joaquin Anton Guirao <[email protected]>

transcode to htj2k function to use nvimgcodec for decoding + mini-bat…

b652ca7

…ch processing for large directories Signed-off-by: Joaquin Anton Guirao <[email protected]>

jantonguirao force-pushed the htj2k_support branch from 37ca835 to b652ca7 Compare October 23, 2025 10:23

OHIF v3 viewer to display proper segmentation regions after switching…

4c70c1f

… to different series and run monailabel Signed-off-by: Joaquin Anton Guirao <[email protected]>

jantonguirao force-pushed the htj2k_support branch from 352defc to 4c70c1f Compare October 23, 2025 17:44

jantonguirao added 2 commits October 27, 2025 20:48

Correct display after switching series

3c0babf

Signed-off-by: Joaquin Anton Guirao <[email protected]>

jantonguirao force-pushed the htj2k_support branch 2 times, most recently from 1854d7e to 0a3fd79 Compare October 28, 2025 10:25

jantonguirao force-pushed the htj2k_support branch from a4fa128 to c768909 Compare October 28, 2025 10:40

jantonguirao force-pushed the htj2k_support branch from e2c9b44 to 546e4dc Compare November 13, 2025 13:16

Set color_spec explicitly to RGB when decoding YBR Photometric interp…

13f3377

…retations. Group frames per PhotometricInterpretation before sending them to decode. Signed-off-by: Joaquin Anton Guirao <[email protected]>

jantonguirao force-pushed the htj2k_support branch from 663bdf7 to 13f3377 Compare November 13, 2025 17:52

jantonguirao added 2 commits November 14, 2025 11:08

jantonguirao force-pushed the htj2k_support branch from d3f4725 to cfab9d0 Compare November 14, 2025 11:52

Fix tests

7b2fd01

Signed-off-by: Joaquin Anton Guirao <[email protected]>

jantonguirao force-pushed the htj2k_support branch from 1dba624 to 7b2fd01 Compare November 14, 2025 12:38

jantonguirao force-pushed the htj2k_support branch from 807548e to 641315a Compare November 17, 2025 12:55

pre-commit-ci bot and others added 7 commits November 17, 2025 12:58

[pre-commit.ci] auto fixes from pre-commit.com hooks

a0e0732

for more information, see https://pre-commit.ci

The changes I just made should:

5d29589

Remove top-level ImagePositionPatient (prevents 1/Infinity) Keep top-level ImageOrientationPatient (enables MPR button) Remove per-frame PlaneOrientationSequence (prevents wrong parsing) Set correct SOPClassUID (Enhanced CT)

Revert

4f51a22

Merge pull request #2 from dmoore247/htj2k_support

d0ae90d

Multi-frame DICOM file showed "1/Infinity" in OHIF MPR-axial viewport while working fine in stack view.

Set correct SOPClassUID for multi-frame files

f88d03e

Signed-off-by: Joaquin Anton Guirao <[email protected]>

jantonguirao force-pushed the htj2k_support branch from 6051d0d to f88d03e Compare November 26, 2025 11:39

Skip files that don't have PixelData member

2bd3b9e

Signed-off-by: Joaquin Anton Guirao <[email protected]>

jantonguirao force-pushed the htj2k_support branch from 661ee86 to 2bd3b9e Compare November 26, 2025 15:01

pre-commit-ci bot and others added 2 commits November 26, 2025 15:01

[pre-commit.ci] auto fixes from pre-commit.com hooks

63a8a1b

for more information, see https://pre-commit.ci

Skip datasets without pixel data

e00d77b

Signed-off-by: Joaquin Anton Guirao <[email protected]>

jantonguirao force-pushed the htj2k_support branch from 63a8a1b to e00d77b Compare November 26, 2025 15:20

jantonguirao and others added 6 commits November 27, 2025 21:10

Create a new convert_multiframe.py file based on highdicom

44c8ec1

Signed-off-by: Joaquin Anton Guirao <[email protected]>

[pre-commit.ci] auto fixes from pre-commit.com hooks

a949f23

for more information, see https://pre-commit.ci

Merge branch 'jantonguirao:htj2k_support' into htj2k_support

5ee9877

Fix washout with CT scans.

13d2864

Set top level tags.

Merge pull request #3 from dmoore247/htj2k_support

d440042

Fix washout in CT Scans

[pre-commit.ci] auto fixes from pre-commit.com hooks

fd298c7

for more information, see https://pre-commit.ci

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[Draft] Add HTJ2K DICOM support #1863

[Draft] Add HTJ2K DICOM support #1863

Uh oh!

jantonguirao commented Oct 17, 2025 •

edited

Loading

Uh oh!

SachidanandAlle commented Oct 18, 2025

Uh oh!

coderabbitai bot commented Oct 23, 2025 •

edited

Loading

Review skipped

Uh oh!

dmoore247 commented Oct 24, 2025 •

edited

Loading

Uh oh!

jantonguirao commented Oct 24, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

[Draft] Add HTJ2K DICOM support #1863

Are you sure you want to change the base?

[Draft] Add HTJ2K DICOM support #1863

Uh oh!

Conversation

jantonguirao commented Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SachidanandAlle commented Oct 18, 2025

Uh oh!

coderabbitai bot commented Oct 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

dmoore247 commented Oct 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jantonguirao commented Oct 24, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jantonguirao commented Oct 17, 2025 •

edited

Loading

coderabbitai bot commented Oct 23, 2025 •

edited

Loading

dmoore247 commented Oct 24, 2025 •

edited

Loading