Add docstring note that Transpose/Transposed do not update the affine matrix

monai/transforms/utility/array.py

@@ -571,6 +571,13 @@ def __call__(self, img):
 class Transpose(Transform):
     """
     Transposes the input image based on the given `indices` dimension ordering.
+
+    .. note::
+        This transform does not update the affine matrix in the metadata. As a result,
+        affine-dependent transforms applied after (e.g. :py:class:`monai.transforms.Spacing`)
+        may produce unexpected results, because the affine no longer corresponds to the
+        transposed data. To reorient medical images in an affine-aware way, use
+        :py:class:`monai.transforms.Orientation` instead.
     """
 
     backend = [TransformBackends.TORCH]

monai/transforms/utility/dictionary.py

@@ -636,6 +636,13 @@ def __call__(self, data: Mapping[Hashable, Any]) -> dict[Hashable, Any]:
 class Transposed(MapTransform, InvertibleTransform):
     """
     Dictionary-based wrapper of :py:class:`monai.transforms.Transpose`.
+
+    .. note::
+        This transform does not update the affine matrix in the metadata. As a result,
+        affine-dependent transforms applied after (e.g. :py:class:`monai.transforms.Spacingd`)
+        may produce unexpected results, because the affine no longer corresponds to the
+        transposed data. To reorient medical images in an affine-aware way, use
+        :py:class:`monai.transforms.Orientationd` instead.
     """
 
     backend = Transpose.backend