keras-team/keras · error · ValueError

Invalid start_points shape: expected (4,2) for a single imag

Error message

Invalid start_points shape: expected (4,2) for a single image or (N,4,2) for a batch. Received shape: {start_points.shape}

What it means

In perspective's compute_output_spec, start_points must have trailing shape (4, 2) — the four corner (x, y) pairs — and overall ndim of 2 (single image) or 3 (batch). Any other layout, such as (2, 4), (8,), or (N, 2, 4), raises this error.

Source

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

    def call(self, images, start_points, end_points):
        return backend.image.perspective_transform(
            images,
            start_points,
            end_points,
            interpolation=self.interpolation,
            fill_value=self.fill_value,
            data_format=self.data_format,
        )

    def compute_output_spec(self, images, start_points, end_points):
        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 start_points.shape[-2:] != (4, 2) or start_points.ndim not in (2, 3):
            raise ValueError(
                "Invalid start_points shape: expected (4,2) for a single image"
                f" or (N,4,2) for a batch. Received shape: {start_points.shape}"
            )
        if end_points.shape[-2:] != (4, 2) or end_points.ndim not in (2, 3):
            raise ValueError(
                "Invalid end_points shape: expected (4,2) for a single image"
                f" or (N,4,2) for a batch. Received shape: {end_points.shape}"
            )
        if start_points.shape != end_points.shape:
            raise ValueError(
                "start_points and end_points must have the same shape."
                f" Received start_points.shape={start_points.shape}, "
                f"end_points.shape={end_points.shape}"
            )
        return KerasTensor(images.shape, dtype=images.dtype)


@keras_export("keras.ops.image.perspective_transform")

View on GitHub (pinned to 7a34a03db6)

Solutions

1. Reshape start_points to exactly (4, 2) or (N, 4, 2).
2. Keep each row as one corner's (x, y); do not transpose to (2, 4).
3. For a batch, stack per-image (4, 2) arrays along a new leading axis.

Example fix

# before
start_points = pts.reshape(2, 4)

# after
start_points = pts.reshape(4, 2)

import numpy as np
sp = np.asarray(start_points)
if sp.ndim == 1 and sp.size == 8: sp = sp.reshape(4, 2)
assert sp.ndim in (2, 3) and sp.shape[-2:] == (4, 2), sp.shape

def valid_corner_points(p):
    p = np.asarray(p)
    return p.ndim in (2, 3) and tuple(p.shape[-2:]) == (4, 2)

When it happens

Trigger: keras.ops.image.perspective(img, start_points=np.array(...).reshape(2,4), ...); passing a flat list of 8 coordinates; transposing the corner matrix.

Common situations: Hand-built corner lists where x/y pairs got flattened or re-ordered; batching corners with shape (4, 2, N) instead of (N, 4, 2).

Related errors

• Invalid end_points shape: expected (4,2) for a single image
• start_points and end_points must have the same shape. Receiv
• Invalid images rank: expected rank 4 (batch of images). Rece
• Invalid image1 rank: expected rank 3 (single image) or rank
• Invalid image2 rank: expected rank 3 (single image) or rank

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