BUG: Fix image_from_array shape handling for F-contiguous arrays

[Copilot]

Description

itk.image_from_array() incorrectly preserved the original array shape when given F-contiguous inputs (e.g., array.T), while itk.image_view_from_array() correctly used the transposed shape. This inconsistency broke user expectations and made the two functions behave differently for the same input.

Root cause: Double reversal in shape handling

• Python code unconditionally reversed shape: ndarr.shape[::-1]
• C++ code reversed again for F-contiguous buffers
• Net effect: original shape preserved instead of transposed

Fix: Conditional shape reversal based on contiguity

• C-contiguous: reverse in Python (C++ expects ITK order)
• F-contiguous: pass as-is (C++ handles reversal)

This matches the existing vector image logic and aligns both functions.

Changes

• Modules/Bridge/NumPy/wrapping/PyBuffer.i.in: Added contiguity check before shape reversal in GetImageViewFromArray()
• Wrapping/Generators/Python/Tests/extras.py: Added tests for transposed array handling with black-compliant formatting

Example

import itk
import numpy as np

array = np.empty((1, 2, 3))

# Before fix:
itk.image_from_array(array.T).shape    # (1, 2, 3) - WRONG
itk.image_view_from_array(array.T).shape  # (3, 2, 1) - correct

# After fix:
itk.image_from_array(array.T).shape    # (3, 2, 1) - correct
itk.image_view_from_array(array.T).shape  # (3, 2, 1) - correct

PR Checklist

• No API changes were made (or the changes have been approved)
• No major design changes were made (or the changes have been approved)
• Added test (or behavior not changed)
• Updated API documentation (or API not changed)
• Added license to new files (if any)
• Added Python wrapping to new files (if any) as described in ITK Software Guide Section 9.5
• Added ITK examples for all new major features (if any)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Unexpected behavior of itk.image_from_array when passing array.T</issue_title>
<issue_description>

Hi, and thanks again for making ITK!

Description

The shape of an image created with itk.image_from_array is unexpected when the input is not a contiguous array. I discovered this when passing array.T and was surprised when the shape was the same as for array. The issue doesn't happen with itk. image_view_from_array.

Steps to Reproduce

import itk
import numpy as np

array = np.empty((1, 2, 3))

print(f"{array.shape = }")
print()
print(f"{itk.image_from_array(array).shape = }")
print(f"{itk.image_from_array(array.T).shape = }")
print(f"{itk.image_from_array(array.T.copy()).shape = }")
print()
print(f"{itk.image_view_from_array(array).shape = }")
print(f"{itk.image_view_from_array(array.T).shape = }")
print(f"{itk.image_view_from_array(array.T.copy()).shape = }")
print()
print(f"{array.flags['C_CONTIGUOUS'] = }")
print(f"{array.T.flags['C_CONTIGUOUS'] = }")
print(f"{array.T.copy().flags['C_CONTIGUOUS'] = }")
print()
print(f"{array.flags['F_CONTIGUOUS'] = }")
print(f"{array.T.flags['F_CONTIGUOUS'] = }")
print(f"{array.T.copy().flags['F_CONTIGUOUS'] = }")

Expected behavior

I expected reversed shapes for itk.image_from_array(array) and itk.image_from_array(array.T).

Actual behavior (output of script above)

array.shape = (1, 2, 3)

itk.image_from_array(array).shape = (1, 2, 3)
itk.image_from_array(array.T).shape = (1, 2, 3)  # I expected (3, 2, 1) here!
itk.image_from_array(array.T.copy()).shape = (3, 2, 1)

itk.image_view_from_array(array).shape = (1, 2, 3)
itk.image_view_from_array(array.T).shape = (3, 2, 1)
itk.image_view_from_array(array.T.copy()).shape = (3, 2, 1)

array.flags['C_CONTIGUOUS'] = True
array.T.flags['C_CONTIGUOUS'] = False
array.T.copy().flags['C_CONTIGUOUS'] = True

array.flags['F_CONTIGUOUS'] = False
array.T.flags['F_CONTIGUOUS'] = True
array.T.copy().flags['F_CONTIGUOUS'] = False

Reproducibility

Always.

Versions

$ python -c "import numpy; print(numpy.__version__)"
1.26.2

$ python -c "import itk; print(itk.Version.GetITKVersion())"
5.3.0

Environment

$ python <(curl -s https://raw.githubusercontent.com/fepegar/torchio/main/print_system.py)
Platform:   macOS-14.0-arm64-arm-64bit
[...]
Python:     3.11.5 (main, Sep 11 2023, 08:31:25) [Clang 14.0.6 ]

</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Unexpected behavior of itk.image_from_array when passing array.T #4329

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[thewtex]

@copilot address failing ci tests

[Copilot]

@copilot address failing ci tests

Fixed in 7c49c8a. The pre-commit failure was due to black formatting - the test assertions now use black's preferred multi-line style. The macOS CI failures appear to be transient GitHub API errors (500/503) during git fetch, not related to the code changes.

[hjmjohnson]

Took over this branch — rebased onto current upstream/main (was 984 commits behind) and replaced the Python-side conditional-reversal with a deep-copy of any non-C-contiguous input. The Pixi-Cxx (macos-15) failure was a flake (DNS resolution failure for ExternalData CDN); the real test failure was itkPyBufferTest::test_NumPyBridge_FortranOrder.

Why deep-copy instead of conditional reversal

The C++ side at itkPyBuffer.hxx:96-103 already reverses size for F-contiguous buffers. The prior Python code unconditionally reversed shape[::-1], so for F-arrays the C++ side reversed it back, leaving ITK with the original NumPy shape — that's the bug this PR was opened to fix.

The conditional-reversal approach (if F_CONTIGUOUS: pass shape unreversed) corrects the .shape user complaint but breaks test_NumPyBridge_FortranOrder because the resulting ITK pixel layout reads the F-order bytes as if they were C-order, so ITK[i,j] != NumPy[j,i]. There is no zero-copy way to give an F-contiguous buffer the C-order pixel semantics that ITK assumes.

Deep-copying the input via np.ascontiguousarray() solves both:

• .shape matches arr.T.shape (the user-facing fix).
• ITK[i,j] == NumPy[j,i] holds for both C- and F-contiguous inputs (consistent semantics).

The cost is a copy for F-arrays. The existing fallback for fully non-contiguous arrays already does this with a warning; the same warning now covers F-arrays.

Test changes

test_NumPyBridge_FortranOrder previously asserted pixel values that were only correct under the prior double-reversal behavior. Updated to assert the new consistent mapping image.GetPixel((i,j)) == arrFortran[j,i], which is the same invariant the existing C-contiguous block of the test asserts.

[hjmjohnson]

@thewtex. --- working through old PR's, trying to address outstanding issues. You triggered the initial co-pilot start to this PR. I pushed to a green state.

I'm not sure if this is the approach you originally had anticipated, but it looks like a reasonable state to me.

[hjmjohnson]

Rebased onto current upstream/main (was 154 commits behind) so CI runs against fresh main. Code unchanged from the prior tip; expecting macOS.Python to recover (the failure on the old head was the only red, and it submitted no CDash results — looked like a transient infra/setup issue, not a real test failure). Will trigger /azp run if it doesn't auto-rerun.

[hjmjohnson]

Force-pushed 2181a2121f → ea5b650cb2 to rescue greptile P2 fixes that were claimed-but-not-actually-on-the-PR, plus add a few items the careful-review pass surfaced.

What was missing on the prior PR HEAD

Two greptile P2 threads were marked "Addressed in 2f75932964" earlier and resolved on GitHub, but 2f75932964 lived only on a fork backup branch and never made it to the upstream PR HEAD 5980cc0b8a. The previous rebase moved that incomplete HEAD forward as 2181a2121f. Concretely missing:

• extras.py:418-420 calling bare GetImageViewFromArray(arr_fortran) -- now wrapped in warnings.catch_warnings() so the new non-C-contiguous warning doesn't leak into CI output.
• F-contiguous vector-image subtest in test_NumPyBridge_itkVectorImage -- now restored: np.asfortranarray(vectorndarr) → GetImageViewFromArray(..., is_vector=True) → assert ndim / dtype / shape match.

Additional items the careful review surfaced

1. Stale docstrings on Wrapping/Generators/Python/itk/support/extras.py -- GetImageFromArray and GetImageViewFromArray still claimed "the Image representation will be the same for an array and its transpose" after this fix. Replaced with the post-fix rule (itk.size(image) == array.shape[::-1] regardless of layout, arr and arr.T produce reversed images).

2. Stale docstrings on Modules/Bridge/NumPy/wrapping/PyBuffer.i.in -- the SWIG-side docstrings had the same stale paragraph and weren't updated by the local DOC commit either. Both GetImageViewFromArray and GetImageFromArray here now match.

3. Migration-guide note -- this is a semantically breaking change (transpose was a no-op before; now arr.T produces a transposed image). Added a section to Documentation/docs/migration_guides/itk_6_migration_guide.md explaining the rationale, the new shape rule, and an audit checklist for callers.

Final commits

ea5b650cb2  DOC: Add ITKv6 migration note for image_from_array transpose semantics
45253fff40  BUG: image_from_array shape consistency for non-C-contiguous arrays

Two clean logical commits on top of fresh upstream/main. pre-commit run --all-files clean. CI re-firing on ea5b650cb2.

[hjmjohnson]

Force-pushed ea5b650cb2 → fdee9cb6d8 with corner-case test coverage and a few small UX/doc polishes from the second careful review pass.

What changed

Code (PyBuffer.i.in)

• Convert the bare assert ndarr.ndim in (1,...,5) to a proper ValueError so the check survives python -O.
• Reject is_vector=True with ndim<2 up-front (the shape[-2::-1] slice silently returns () for 1-D inputs and produces a malformed image — pre-existing edge that's now an explicit error).
• Add stacklevel=2 to the non-C-contiguous warning so users see their call site instead of PyBuffer.i.in:100.

Tests (itkPyBufferTest.py, extras.py)

• F-contiguous vector test now exercises both components=1 and components=3 via subTest, with a pre-seeded pattern so a silent no-op transpose would be caught.
• Pixel-equality round-trip: F input → deep-copy → array view equals np.ascontiguousarray(input).
• New transpose pixel-data check in extras.py: asserts image_from_array(arr.T) produces transposed data and is not equal to image_from_array(arr) (the regression site of the bug being fixed).
• Round-trip self-consistency loop covering C-contig, F-contig, transpose, and non-contiguous slice inputs.
• Deep-copy independence test: mutating the original F-contig array after image_from_array(...) must not change the image (since the function deep-copies).
• Error-path tests for the new ValueErrors (ndim>5 rejected, is_vector=True with ndim==1 rejected).

Migration guide (itk_6_migration_guide.md)

• Replaced the conceptual image[i,j,k] == array[k,j,i] with the literal image.GetPixel((i,j,k)) == array[k,j,i] (ITK Python images don't expose __getitem__ directly).
• Emphasised that the deep-copy means the image owns an independent buffer; mutations to the original array are no longer visible.
• Clarified that need_contiguous=False only exists on GetImageViewFromArray; GetImageFromArray already silences the warning since it always deep-copies via ImageDuplicator.

Final shape

fdee9cb6d8  DOC: Add ITKv6 migration note for image_from_array transpose semantics
95e65f6edb  BUG: image_from_array shape consistency for non-C-contiguous arrays

Both commits squashed clean (no fixup! residue). pre-commit run --all-files clean. PythonExtrasTest and itkPyBufferTest pass locally. CI re-firing.

[hjmjohnson]

I think this approach is correct. The migration guide indicates the backward compatibility, but the interface now looks like what I would expect.

It is almost like a self-review. Should let another person approve.

[thewtex]

LGTM

@hjmjohnson thanks!