Fix image reorientation and cropping bugs in conform workflow (fixes #764) by dkuegler · Pull Request #767 · Deep-MI/FastSurfer

dkuegler · 2026-01-19T18:26:28Z

Problem Statement

This PR addresses two related issues with FastSurfer's image reorientation and conforming pipeline:

Issue 1 - Incorrect Image Cropping (#764): The previous implementation had bugs in how images were cropped during reorientation, leading to misaligned data being processed by downstream models. This caused spatial errors in the segmentation pipeline.

Issue 2 - Image Center Offset During Orientation Flipping (related to FreeSurfer #1358): When images are flipped to change orientation (e.g., LAS→RAS), the affine matrix must correctly maintain the image center. The original code did not properly account for the MGH format's definition of image center at Ni/2 instead of (Ni-1)/2, causing the image content to shift in world coordinates during reorientation.

Solution

This PR introduces a comprehensive refactoring of the image orientation code:

New Reorientation Class: Encapsulates all orientation transformation logic in a dedicated class that:
- Manages the vox2vox transformation matrix and metadata
- Provides clear methods for applying forward and inverse transformations
- Properly handles image center preservation during arbitrary orientation changes
- Supports both simple reorientation and spatial resampling with interpolation
Fixed Transformation Mathematics:
- Corrects the affine matrix calculations for flipped orientations
- Properly computes image center offsets based on the shape and orientation
- Ensures consistent handling of image metadata across the pipeline
Improved Code Structure:
- Separates concerns between orientation detection and transformation application
- Removes functions (to_target_orientation, orientation_to_ornts)
- Simplifies the calling code in run_prediction.py with a clearer API
Comprehensive Testing:
- Adds two new test modules with 20+ test cases covering:
- World coordinate consistency after reorientation
- Round-trip conversions (original → target → original)
- Affine matrix correctness for various orientations
- Edge cases with anisotropic voxels and different image shapes

Changes

FastSurferCNN/data_loader/conform.py: Complete refactoring with new Reorientation class and helper functions
FastSurferCNN/run_prediction.py: Updated to use the new Reorientation API
FastSurferCNN/utils/common.py: Added array_flags context manager for temporary array flag manipulation
HypVINN/data_loader/data_utils.py: Simplified to use refactored utilities
'test/image/test_conform_reorient.py: New tests for conform and reorientation functions
test/image/test_orientation_transform.py: New unit tests for orientation transformation internals

Testing

All changes are covered by new comprehensive unit tests that verify:

✅ Images are correctly reoriented without data loss or corruption
✅ World coordinates remain consistent after transformations
✅ The image center is preserved during orientation flipping
✅ Round-trip conversions return images to their original state
✅ Affine matrices are correct for various orientation combinations

Backward Compatibility

⚠️ Breaking Changes:

to_target_orientation() has been removed (use Reorientation.from_target_orientation() instead)
orientation_to_ornts() has been removed (internal functionality now in Reorientation class)

Related Issues

Fixes Fastsurfer crops the image volumes #764 (incorrect image cropping)
Relates to FreeSurfer #1358

Copilot

Pull request overview

This work-in-progress PR addresses off-by-one errors in MGH header handling related to the Pxyz_c calculation, which represents the center of the image but is offset by half a voxel. The fix introduces two feature flags to optionally correct the affine calculation bug in nibabel's MGHHeader.get_affine() method.

Changes:

Introduces two feature flags (FIX_MGH_AFFINE_CALCULATION and FIX_CENTER_NOT_CENTER) to control the fix behavior
Adds helper functions get_affine_from_mgh() and get_affine_from_any() to provide corrected affine calculations
Modifies offset calculation in map_image() to account for off-by-one errors when flipping orientation
Updates center calculation logic in prepare_mgh_header() with conditional fix based on feature flags

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

dkuegler · 2026-04-24T08:42:37Z

This PR is already rebased on #804 and should be reviewed after integration of #804.

…bugfix to the property SubjectDirectory.asegdkt_segfile

Use this function in srun_fastsurfer and run_fastsurfer.sh

- make quick_qc.py follow the general formatting style - add ty into style extra (pyproject.toml) - Make brainvolstats satisfy ty typing rules

Add en_US.UTF-8 and C.UTF-8 to fix locale warnings. Update Singularity doc (workdir warning). Fix sep=>end argument in build.py's print statements on --print. Fix the default tag of the docker image, if no tag name is given (added v) and the --tag_dev default (<DEVICE>-dev instead of dev<DEVICE>-)

…_cmdf

Formatting Cleanup

Fix formatting

This commit refactors the image orientation and resampling code to fix two critical issues with image handling. First, it corrects the image cropping behavior to ensure proper alignment after reorientation (fixes Deep-MI#764). Second, it addresses the image center offset issue that occurs when flipping image orientations, which was caused by MGH format assumptions about voxel center positioning (relates to freesurfer #1358). A new Reorientation class encapsulates the orientation transformation logic for improved maintainability and correctness. Comprehensive unit tests validate the orientation transformations and world coordinate consistency.

Remove pandas-stubs dependency Remove unused code Add deprecated callback implementation for Python <=3.13 replace Numpy 1 function deprecate_with_doc by deprecated for numpy 2 Add NPY201 rule to pyproject.toml

… accordingly.

m-reuter requested a review from Copilot January 19, 2026 18:37

Copilot started reviewing on behalf of m-reuter January 19, 2026 18:37 View session

Copilot AI reviewed Jan 19, 2026

View reviewed changes

dkuegler force-pushed the fix/conform-reorient branch from b059c18 to d8b8d42 Compare January 19, 2026 19:21

dkuegler force-pushed the fix/conform-reorient branch 4 times, most recently from b053d7f to 90d5f5e Compare January 28, 2026 16:50

dkuegler force-pushed the fix/conform-reorient branch 2 times, most recently from a4e572a to 8d15c5c Compare March 11, 2026 16:01

dkuegler added 2 commits April 23, 2026 19:40

Remove print statements in paint_cc_into_pred.py

df325b9

Some formatting cleanup of version.py

7cd5e0a

dkuegler force-pushed the fix/conform-reorient branch 2 times, most recently from 744a9f2 to f7bff6b Compare April 24, 2026 07:47

dkuegler changed the title ~~WIP: Fix off-by-one errors in conform.py if flipping orientation~~ Fix image reorientation and cropping bugs in conform workflow (fixes #764) Apr 24, 2026

dkuegler force-pushed the fix/conform-reorient branch from f7bff6b to e32ffa1 Compare April 24, 2026 08:40

dkuegler added 13 commits April 24, 2026 13:07

Some formatting cleanup of FastSurferCNN/utils/common.py and a minor …

7904aaf

…bugfix to the property SubjectDirectory.asegdkt_segfile

Some formatting cleanup of recon-surf.sh

6f49fb3

Replace print statements with proper logging in segstats

e5e2a7a

Create a function to auto-detect the FREESURFER license.

9671ac8

Use this function in srun_fastsurfer and run_fastsurfer.sh

- fix print statements in quick_qc.py

307fec6

- make quick_qc.py follow the general formatting style - add ty into style extra (pyproject.toml) - Make brainvolstats satisfy ty typing rules

Clean up redundant logging in recon_surf/functions.sh -> RunIt/run_it…

8356490

…_cmdf

Add debug-helpers to gitignore and dockerignore

b5dbc8c

Fix typing for ty

2ca2d5d

Formatting Cleanup

Remove noop_context, replace by nullcontext

7b2da4a

Fix writable typo

992e180

Fix formatting

Remove redundant img2axcodes function

807caf4

Change empty image to zeros to avoid overflow in tests

539d7ad

Remove pandas-stubs dependency Remove unused code Add deprecated callback implementation for Python <=3.13 replace Numpy 1 function deprecate_with_doc by deprecated for numpy 2 Add NPY201 rule to pyproject.toml

dkuegler force-pushed the fix/conform-reorient branch from 9678e1b to 539d7ad Compare April 24, 2026 11:26

Move affine2orientation function to helper_functions and update tests…

606463b

… accordingly.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix image reorientation and cropping bugs in conform workflow (fixes #764)#767

Fix image reorientation and cropping bugs in conform workflow (fixes #764)#767
dkuegler wants to merge 17 commits intoDeep-MI:devfrom
dkuegler:fix/conform-reorient

dkuegler commented Jan 19, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dkuegler commented Apr 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

dkuegler commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem Statement

Solution

Changes

Testing

Backward Compatibility

Related Issues

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dkuegler commented Apr 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

dkuegler commented Jan 19, 2026 •

edited

Loading