Improve Affine transform documentation

[engmohamedsalah]

Summary

This PR improves the documentation for the Affine transform to address long-standing confusion about its coordinate system assumptions and parameters.

Addresses

Fixes #7092

Motivation

Users have been confused about:

1. The Affine transform's center-origin assumption (undocumented)
2. When to use normalized=True vs normalized=False
3. What the compute_w_affine method does (no docstring)

These documentation gaps make it difficult for users to correctly use the Affine transform, especially when working with medical imaging data.

Changes Made

1. Added Note section to Affine class

Clearly documents that transformations are performed relative to the image spatial center:

Note:
    This transform assumes that the origin of the coordinate system is at the spatial center
    of the image. When applying transformations (rotation, scaling, etc.), they are performed
    relative to this center point.

2. Clarified normalized parameter documentation

Replaced technical jargon with user-friendly explanation:

• Before: "indicating whether the provided affine is defined to include a normalization transform converting the coordinates from [-(size-1)/2, (size-1)/2]..."
• After: "Set to False (default) if your affine matrix works with pixel/voxel coordinates centered at the image center. When False, MONAI will automatically apply the necessary coordinate transformations. Most users should use the default False."

3. Added comprehensive docstring to compute_w_affine method

Previously had no documentation at all. Now includes:

• Clear explanation of purpose
• Documentation of all parameters
• Explanation of return value
• Context about center-based coordinate systems

Verification

Code Evidence - Center-Origin Assumption

shift_1 = create_translate(r, [float(d - 1) / 2 for d in img_size[:r]])
shift_2 = create_translate(r, [-float(d - 1) / 2 for d in sp_size[:r]])
mat = shift_1 @ convert_data_type(mat, np.ndarray)[0] @ shift_2

The matrix composition (translate_back @ transform @ translate_to_origin) confirms transformations happen around the image center.

Code Evidence - normalized Parameter

self.norm_coord = not normalized  # line 2268

• normalized=False → norm_coord=True → normalization applied ✓
• normalized=True → norm_coord=False → no normalization ✓

Documentation accurately reflects this behavior.

Testing Performed

• Python syntax validation (py_compile)
• Verified documentation matches actual code logic
• Reviewed for consistency with MONAI documentation style
• Verified no code behavior changes (documentation only)

Type of change

• Documentation improvement
• No functional code changes
• Addresses reported issue

Code Quality

• Clear, human-readable language
• Follows MONAI documentation conventions
• Comprehensive explanations
• DCO signoff included

Benefits to MONAI Community

1. Reduces User Confusion: Clear documentation helps users understand coordinate system assumptions
2. Improves Usability: Users can now understand when to use normalized parameter
3. Better Maintainability: Documented compute_w_affine makes code easier to understand
4. Addresses Long-Standing Issue: Fixes issue open since October 2023

Additional Notes

• No code behavior changes - only documentation improvements
• All changes verified against actual code implementation
• Written in clear, accessible language for users unfamiliar with coordinate system mathematics

[coderabbitai]

📝 Walkthrough

Walkthrough

A new classmethod compute_w_affine was added to the Affine class in monai/transforms/spatial/array.py to compute adjusted affine matrices accounting for center-based coordinate transformations. The method applies a center-based translation before and after the base affine transform. Documentation was updated with a note explaining that transformations are performed relative to the image center and providing guidance for adjusting the origin via translation or affine modifications.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title accurately describes the main change: improved documentation for the Affine transform class, though it omits mention of compute_w_affine docstring addition.
Description check	✅ Passed	Description covers all required template sections with detailed motivation, changes, verification, and testing. Minor: 'In-line docstrings updated' checked but should clarify this refers to compute_w_affine method docstring.
Linked Issues check	✅ Passed	PR addresses issue #7092 by adding comprehensive documentation explaining center-origin assumption and coordinate system behavior, directly resolving the confusion about why affine matrices don't match expected values.
Out of Scope Changes check	✅ Passed	All changes are documentation-only: Note section, normalized parameter clarification, and compute_w_affine docstring. No functional code changes outside the scope of issue #7092.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 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

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

monai/transforms/spatial/array.py (1)

2333-2358: ⚠️ Potential issue | 🟡 Minor

Add focused unit test for compute_w_affine and preserve input type.

The method lacks direct test coverage. Add a focused test (e.g., 2D case with known center shifts). Additionally, align with MONAI patterns by preserving the input matrix type:

Type preservation refactor

-        mat = shift_1 @ convert_data_type(mat, np.ndarray)[0] @ shift_2
-        return mat
+        mat_np = shift_1 @ convert_data_type(mat, np.ndarray)[0] @ shift_2
+        return convert_to_dst_type(mat_np, mat)[0]