keras-team/keras · error · ValueError

Invalid transform rank: expected rank 1 (single transform) o

Error message

Invalid transform rank: expected rank 1 (single transform) or rank 2 (batch of transforms). Received input with shape: transform.shape={transform.shape}

What it means

The same affine-transform op validates the transform argument: it must be rank 1 (a single transform vector, typically length 8) or rank 2 (a batch of transform vectors, one per image). Rank-0 scalars, rank-3 arrays, or per-pixel transform stacks raise this ValueError.

Source

Thrown at keras/src/ops/image.py:469

    def call(self, images, transform):
        return backend.image.affine_transform(
            images,
            transform,
            interpolation=self.interpolation,
            fill_mode=self.fill_mode,
            fill_value=self.fill_value,
            data_format=self.data_format,
        )

    def compute_output_spec(self, images, transform):
        if len(images.shape) not in (3, 4):
            raise ValueError(
                "Invalid images rank: expected rank 3 (single image) "
                "or rank 4 (batch of images). Received input with shape: "
                f"images.shape={images.shape}"
            )
        if len(transform.shape) not in (1, 2):
            raise ValueError(
                "Invalid transform rank: expected rank 1 (single transform) "
                "or rank 2 (batch of transforms). Received input with shape: "
                f"transform.shape={transform.shape}"
            )
        return KerasTensor(images.shape, dtype=images.dtype)


@keras_export("keras.ops.image.affine_transform")
def affine_transform(
    images,
    transform,
    interpolation="bilinear",
    fill_mode="constant",
    fill_value=0,
    data_format=None,
):
    """Applies the given transform(s) to the image(s).

View on GitHub (pinned to 7a34a03db6)

Solutions

Flatten each transform to a 1-D vector and stack: transforms = np.stack([t.flatten() for t in ts]) giving rank 2
For a single image, pass one flat vector (rank 1)
Check len(transform.shape) in (1, 2) before calling

Example fix

# before
y = keras.ops.image.affine_transform(imgs, transforms)  # transforms.shape=(N,1,8)

# after
transforms = transforms.reshape((-1, 8))  # rank 2
y = keras.ops.image.affine_transform(imgs, transforms)

Defensive patterns

Strategy: type-guard

Validate before calling

t = np.asarray(transform)
assert t.ndim in (1, 2), f'transform rank {t.ndim}, expected 1 or 2'
if t.ndim == 2:
    assert t.shape[0] in (1, images.shape[0])

Type guard

def is_valid_transform(t) -> bool:
    return np.asarray(t).ndim in (1, 2)

Prevention

Flatten each transform matrix to a 1-D vector before stacking
Match the transforms batch dim to the images batch dim

When it happens

Trigger: Passing a scalar or a (N,1,8) stack to affine_transform; passing transformation matrices shaped (3,3) for a projective op expecting flat vectors; batch size mismatch is not checked here but rank is.

Common situations: Converting OpenCV 2x3/3x3 matrices to Keras transform vectors and keeping an extra axis; building transforms with np.array([t1, t2]) where each ti is itself a sequence, accidentally making rank 3.

Related errors

AI-assisted analysis of keras-team/keras@7a34a03db6 (2026-08-25). Data as JSON: /api/errors/618295eeab498a6c. Report an issue: GitHub.