Tutorial proposal: validated CT/DICOM SEG tensors with patient-disjoint splits

Hi IDC team,

Following our LinkedIn discussion about the IDC catalog on Hugging Face, I would like to contribute a compact, CPU-friendly notebook that takes a small public CT/DICOM SEG cohort through correspondence checks, tensor conversion, and a reproducible patient-disjoint train/test split.

The Getting Started Part 2 notebook already covers searching, downloading, and CT/SEG visualization. This contribution would build on it, focusing on validation and preparing traceable inputs for a PyTorch segmentation workflow.

Proposed dataset and scope

My initial candidate is C4KC-KiTS, which includes CT and manually annotated kidney/tumor segmentations. The TCIA collection page documents the acquisition phases, DICOM SEG conversion history, and CC BY 3.0 license.

I propose a default cohort of four patients, with the estimated download size shown before downloading and processing one case at a time. The first version would support single-frame CT series and BINARY SEG objects on the same spatial grid; unsupported or ambiguous cases would produce an explicit validation error.

Notebook workflow

Discover and record the cohort. Use the Hugging Face catalog and/or idc-index for discovery and idc-index for downloads, without requiring a BigQuery account. Record the catalog revision/IDC release, package versions, patient/study/series UIDs, selected SEG instances, licenses, and source citations.
Resolve CT↔SEG correspondence. Follow the SEG's referenced series and source SOP Instance UIDs to select the correct CT reconstruction/phase. Matching PatientID or StudyInstanceUID alone is insufficient.
Validate spatial alignment. Check frame of reference, orientation, positions, spacing, dimensions, and source-instance coverage. Sort CT slices geometrically and reconstruct SEG frames in the corresponding source-instance order using highdicom. Distinguish omitted empty segmentation frames from missing CT data; reject incompatible grids rather than silently resampling.
Create tensors and inspect overlays. Apply CT modality rescaling to HU. Export a float32 image tensor [1, D, H, W], binary mask channels [K, D, H, W], and spatial metadata. Preserve segment numbers, labels, and coded meanings in a channel mapping, including consistent semantic mapping across cases. Keep overlapping segments separate. Show representative CT/mask overlays and summary checks.
Split by patient. Use a fixed seed and stable patient ordering; keep every study, series, and slice belonging to a patient in one partition. Export a split manifest and assert that patient sets are disjoint. This small split is an instructional example within the public data, not the official KiTS challenge evaluation split.
Demonstrate consumption. Provide a minimal PyTorch Dataset example, without training a model or requiring a GPU.

Deliverable and validation

A proposed location is notebooks/advanced_topics/ct_seg_to_tensors.ipynb, with a README entry and the repository's required Colab link, update date, Support, and Acknowledgments sections.

Before submitting a PR, I would run the notebook end to end on the selected real cohort, check UID/geometry correspondence and patient separation, and record the actual download size and runtime. Any intensity normalization would be explicit and separate from the HU data.

Would C4KC-KiTS and this scope be a useful starting point, or would you prefer another CT/SEG collection or notebook location? I can prepare the PR around your recommendation.

Best regards,
Denis

@denis-samatov

@denis-samatov thank you for the initiative and your contribution!

I took a quick glance over the notebook, and will need more time to better understand, but I do have several comments right away. I think quite a bit of what you prepared can be simplified using the capabilities already available in idc-index and highdicom.

Resolve CT↔SEG correspondence. Follow the SEG's referenced series and source SOP Instance UIDs to select the correct CT reconstruction/phase. Matching PatientID or StudyInstanceUID alone is insufficient.

The segmented series is already captured in seg_index table available via idc-index. You do not need to do the mapping manually!

Validate spatial alignment. Check frame of reference, orientation, positions, spacing, dimensions, and source-instance coverage. Sort CT slices geometrically and reconstruct SEG frames in the corresponding source-instance order using highdicom. Distinguish omitted empty segmentation frames from missing CT data; reject incompatible grids rather than silently resampling.

We have most if not all of those checks pre-computed and available via the volume_geometry_index table!

Create tensors and inspect overlays. Apply CT modality rescaling to HU. Export a float32 image tensor [1, D, H, W], binary mask channels [K, D, H, W], and spatial metadata. Preserve segment numbers, labels, and coded meanings in a channel mapping, including consistent semantic mapping across cases. Keep overlapping segments separate. Show representative CT/mask overlays and summary checks.

I believe this can already be done using the functionality implemented in highdicom, as discussed in https://huggingface.co/datasets/ImagingDataCommons/idc-index-data#loading-images-as-tensors.

Did you consider the above approaches? Do you have reasons not to use those?

I understand this kind of details may not be easy to find. I recommend you give a try to the skill and hosted MCP server we maintain to support IDC users, see https://learn.canceridc.dev/ai-assistants/agents.

Hi Andrey, Thank you for the detailed pointers. You are right that the first version duplicated CT-volume validation that is already available in IDC and highdicom. It already used seg_index for the referenced CT series, but did not make sufficient use of volume_geometry_index or highdicom.Volume. I have updated PR #116 <#116>, commit c57646a <denis-samatov@c57646a> : - CT/SEG pairs are joined using seg_index.segmented_SeriesInstanceUID, and CT series are filtered by volume_geometry_index.regularly_spaced_3d_volume before downloading. Both the pinned Hugging Face and idc-index catalog routes include this index and record its checksum. - hd.get_volume_from_series() now handles slice ordering, regular-grid validation, the modality transform to HU, and the patient-space affine. Display and presentation transforms are disabled for the saved HU data. - SEG channels are loaded with seg.get_volume(combine_segments=False) and aligned with match_geometry(ct_volume, tol=1e-4), preserving overlaps without interpolation. The remaining local guards cover download completeness, CT/SEG identity and source SOP references, and whether each SEG frame actually corresponds to its referenced CT instance. These are pair-specific checks that the CT geometry index does not establish. Omitted SEG frames still require an explicit empty-frame policy; an explicit SpatialLocationsPreserved=NO remains an error. Validation: 27 behavior tests pass; all 34 notebooks pass the repository standards check. The revised notebook was executed locally on the four real C4KC-KiTS pairs, with 77,970,396 bytes of DICOM and a patient-disjoint 3/1 split. Both catalog routes select the same pairs. Google Colab has not been verified. The GitHub Check Notebook Standards run is currently action_required. Could you approve the fork workflow when convenient? The same standards check passes locally. Best regards, Denis On Tue, 13 Oct 2026 14:33:22 -0700, Andrey Fedorov ***@***.***> wrote: fedorov left a comment (ImagingDataCommons/IDC-Tutorials#115) @denis-samatov thank you for the initiative and your contribution! I took a quick glance over the notebook, and will need more time to better understand, but I do have several comments right away. I think quite a bit of what you prepared can be simplified using the capabilities already available in `idc-index` and `highdicom`. > Resolve CT↔SEG correspondence. Follow the SEG's referenced series and source SOP Instance UIDs to select the correct CT reconstruction/phase. Matching PatientID or StudyInstanceUID alone is insufficient. The segmented series is already captured in [`seg_index` table]( https://idc-index.readthedocs.io/en/latest/indices_reference.html#seg-index) available via `idc-index`. You do not need to do the mapping manually! > Validate spatial alignment. Check frame of reference, orientation, positions, spacing, dimensions, and source-instance coverage. Sort CT slices geometrically and reconstruct SEG frames in the corresponding source-instance order using highdicom. Distinguish omitted empty segmentation frames from missing CT data; reject incompatible grids rather than silently resampling. We have most if not all of those checks pre-computed and available via the [`volume_geometry_index` table]( https://idc-index.readthedocs.io/en/latest/indices_reference.html#volume-geometry-index)!

Create tensors and inspect overlays. Apply CT modality rescaling to HU.

Export a float32 image tensor [1, D, H, W], binary mask channels [K, D, H, W], and spatial metadata. Preserve segment numbers, labels, and coded meanings in a channel mapping, including consistent semantic mapping across cases. Keep overlapping segments separate. Show representative CT/mask overlays and summary checks. I believe this can already be done using the functionality implemented in `highdicom`, as discussed in https://huggingface.co/datasets/ImagingDataCommons/idc-index-data#loading-images-as-tensors. Did you consider the above approaches? Do you have reasons not to use those? I understand this kind of details may not be easy to find. I recommend you give a try to the skill and hosted MCP server we maintain to support IDC users, see https://learn.canceridc.dev/ai-assistants/agents. -- Reply to this email directly or view it on GitHub: #115 (comment) You are receiving this because you were mentioned. Message ID: ***@***.***>

Thank you for the quick response! I approved the workflow, which passed, and will comment in the PR after I make the time to review!

Navigation Menu

Repository navigation

Tutorial proposal: validated CT/DICOM SEG tensors with patient-disjoint splits #115

Proposed dataset and scope

Notebook workflow

Deliverable and validation

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Tutorial proposal: validated CT/DICOM SEG tensors with patient-disjoint splits #115

Description

Proposed dataset and scope

Notebook workflow

Deliverable and validation

Activity

fedorov commented on Oct 13, 2026

denis-samatov commented on Oct 15, 2026

fedorov commented on Oct 15, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions