What causes "The ndim({img.ndim}) of the img is not in [2, 3]" in opendatalab/MinerU?

Batched NHWC: loop over img[0] or use img.squeeze(0) for batch size 1.

opendatalab/MinerU · error · LoadImageError

The ndim({img.ndim}) of the img is not in [2, 3]

Error message

The ndim({img.ndim}) of the img is not in [2, 3]

What it means

convert_img's final guard: arrays must be 2-D (grayscale) or 3-D (multi-channel). ndim 1 (flattened vector), 4 (batched NCHW/NHWC), or higher raise LoadImageError with the actual ndim.

Source

Thrown at mineru/model/table/rec/unet_table/utils.py:135

        if img.ndim == 3:
            channel = img.shape[2]
            if channel == 1:
                return cv2.cvtColor(img, cv2.COLOR_GRAY2BGR)

            if channel == 2:
                return self.cvt_two_to_three(img)

            if channel == 4:
                return self.cvt_four_to_three(img)

            if channel == 3:
                return cv2.cvtColor(img, cv2.COLOR_RGB2BGR)

            raise LoadImageError(
                f"The channel({channel}) of the img is not in [1, 2, 3, 4]"
            )

        raise LoadImageError(f"The ndim({img.ndim}) of the img is not in [2, 3]")

    @staticmethod
    def cvt_four_to_three(img: np.ndarray) -> np.ndarray:
        """RGBA → BGR"""
        r, g, b, a = cv2.split(img)
        new_img = cv2.merge((b, g, r))

        not_a = cv2.bitwise_not(a)
        not_a = cv2.cvtColor(not_a, cv2.COLOR_GRAY2BGR)

        new_img = cv2.bitwise_and(new_img, new_img, mask=a)
        new_img = cv2.add(new_img, not_a)
        return new_img

    @staticmethod
    def cvt_two_to_three(img: np.ndarray) -> np.ndarray:
        """gray + alpha → BGR"""
        img_gray = img[..., 0]

View on GitHub (pinned to 4fe4bde114)

Solutions

Batched NHWC: loop over img[0] or use img.squeeze(0) for batch size 1.
CHW from torch: arr = t.cpu().numpy().transpose(1, 2, 0).
Flattened: arr = arr.reshape(h, w).

Example fix

# before
img = loader(tensor.cpu().numpy())  # shape (3, H, W), ndim=3 but CHW is fine; (1,H,W,3) fails

# after
arr = tensor.cpu().numpy()
if arr.ndim == 4: arr = arr[0]
if arr.shape[0] in (1, 3) and arr.ndim == 3: arr = arr.transpose(1, 2, 0)
img = loader(arr)

Defensive patterns

Strategy: validation

Validate before calling

if img.ndim == 4:
    img = img[0]
if img.ndim == 3 and img.shape[0] in (1, 3) and img.shape[-1] not in (1, 3):
    img = img.transpose(1, 2, 0)  # CHW -> HWC
assert img.ndim in (2, 3)

Type guard

def is_hwc_image(img: np.ndarray) -> bool:
    return img.ndim in (2, 3)

Try / catch

try:
    img = loader(arr)
except LoadImageError as e:
    if 'ndim' in str(e):
        raise ValueError(f'expected HWC image, got shape {arr.shape}') from e
    raise

Prevention

Standardize on HWC uint8 numpy as the interchange format between stages.
squeeze batch dims at the point tensors leave torch.
Log shapes at stage boundaries during development.

When it happens

Trigger: Passing a batched array (1, H, W, 3) or a CHW tensor converted to numpy (3, H, W), or a flattened image vector (H*W,).

Common situations: Forgetting to squeeze a batch dimension, converting torch CHW tensors to numpy without transpose, or reshaping that collapses spatial dims.

Related errors

AI-assisted analysis of opendatalab/MinerU@4fe4bde114 (2026-08-14). Data as JSON: /api/errors/7269386b8a896403. Report an issue: GitHub.