Fix 2D grayscale NumPy array prediction on color models

[maxime2476]

Fix grayscale NumPy array prediction on color models

Closes #24750

What this does

Makes LoadPilAndNumpy._single_check expand a 2D grayscale numpy array (H, W) to the model's channel count (3 for a color model, 1 for a grayscale model), the same way the PIL branch just above it already does. Adds a regression test.

Why

Passing a 2D grayscale numpy array to a normal 3-channel model crashed inside PyTorch:

RuntimeError: Given groups=1, weight of size [16, 3, 3, 3], expected input[1, 1, 640, 640] to have 3 channels, but got 1 channels instead

The same image works when passed as a PIL image or a file path, because both get normalized to the model's channel count. Only the raw numpy array failed: the grayscale branch added a single channel (im[..., None]) and ignored flag, unlike the PIL branch that calls .convert(flag). This change just makes the numpy path behave like the PIL and file paths.

Before / after

import numpy as np
from ultralytics import YOLO

model = YOLO("yolo11n.pt")
model.predict(np.zeros((640, 640), dtype=np.uint8), verbose=False)

Before: RuntimeError (3 vs 1 channels).
After: runs normally and returns 1 result, same as the PIL image / file path.

Scope

• Only the im.ndim == 2 (grayscale) branch changes.
• The im.ndim == 3 numpy path is left as-is, so multispectral/multichannel models aren't affected (test_multichannel feeds np.zeros((32, 32, 10))).
• Grayscale models (channels=1, flag="L") keep the old 1-channel behavior.

Tests

• New test_predict_grayscale_ndarray fails before the change (RuntimeError) and passes after.
• Ran locally on Windows 11 / Python 3.13.13 / torch 2.12.0+cpu: test_predict_img (all models including grayscale), test_predict_gray_and_4ch, test_grayscale, test_multichannel and the new test all pass (16 passed).
• ruff check and ruff format --check are clean.

Not included

A 4-channel (H, W, 4) RGBA numpy array fails the same way, but the loader can't tell it apart from a real 4-channel multispectral input (both are ndim == 3), so I left it out to avoid breaking multichannel models. Can be a separate discussion.

🛠️ PR Summary

_{Made with ❤️ by Ultralytics Actions}

🌟 Summary

Fixes grayscale NumPy array inference for color YOLO models by aligning 2D ndarray handling with existing PIL and file input behavior. 🖼️

📊 Key Changes

• Updates _single_check() in ultralytics/data/loaders.py to convert 2D grayscale NumPy arrays to 3-channel BGR when used with color models.
• Preserves 1-channel behavior for grayscale models by keeping flag == "L" inputs as single-channel arrays.
• Clarifies the loader docstring to document the new NumPy grayscale expansion behavior.
• Adds test_predict_grayscale_ndarray() in tests/test_python.py to verify that genuine 2D grayscale NumPy arrays run successfully through a default color model.

🎯 Purpose & Impact

• Fixes an inconsistency where grayscale PIL/file inputs worked, but equivalent 2D NumPy arrays could fail or be handled differently.
• Improves prediction reliability for users passing raw NumPy grayscale images directly into the Python API.
• Reduces input-format surprises and brings ndarray preprocessing in line with expected model channel requirements.
• Adds regression coverage to help prevent this grayscale input bug from reappearing. ✅

[github-actions]

All Contributors have signed the CLA. ✅
_{Posted by the CLA Assistant Lite bot.}

[UltralyticsAssistant]

👋 Hello @maxime2476, thank you for submitting a ultralytics/ultralytics 🚀 PR! This is an automated message to help streamline review, and an engineer will assist you shortly. Please review the checklist below to help ensure a smooth integration of your grayscale NumPy prediction fix 🧪

-✅ Define a Purpose: Clearly explain the purpose of your fix or feature in your PR description, and link to any relevant issues. Ensure your commit messages are clear, concise, and adhere to the project's conventions.
-✅ Synchronize with Source: Confirm your PR is synchronized with the ultralytics/ultralytics main branch. If it's behind, update it by clicking the 'Update branch' button or by running git pull and git merge main locally.
-✅ Ensure CI Checks Pass: Verify all Ultralytics Continuous Integration (CI) checks are passing. If any checks fail, please address the issues.
-✅ Update Documentation: Update the relevant documentation for any new or modified features.
-✅ Add Tests: If applicable, include or update tests to cover your changes, and confirm that all tests are passing.
-✅ Sign the CLA: Please ensure you have signed our Contributor License Agreement if this is your first Ultralytics PR by writing "I have read the CLA Document and I sign the CLA" in a new message.
-✅ Minimize Changes: Limit your changes to the minimum necessary for your bug fix or feature addition. "It is not daily increase but daily decrease, hack away the unessential. The closer to the source, the less wastage there is." — Bruce Lee

For more guidance, please refer to our Contributing Guide. Don't hesitate to leave a comment if you have any questions. Thank you for contributing to Ultralytics! 🚀

[UltralyticsAssistant]

🔍 PR Review

_{Made with ❤️ by Ultralytics Actions}

Good targeted fix and test coverage for the reported uint8 grayscale ndarray case. One issue to address before merging: the new cv2.cvtColor expansion introduces a dtype regression for non-OpenCV-compatible NumPy grayscale arrays, so a NumPy-based channel repeat would be safer here.

💬 Posted 1 inline comment

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[maxime2476]

I have read the CLA Document and I sign the CLA

[glenn-jocher]

Thanks @maxime2476! 🎉 Really clean fix — a 2D grayscale NumPy array now predicts correctly on color models (auto-expanded to 3 channels like PIL/file inputs), resolving the Given groups=1, ... expected input to have 3 channels, but got 1 crash. I reproduced the original bug against current main and confirmed your fix resolves it (verified for both uint8 and float64 2D arrays), tidied the inline comment to a single line, and added the version bump — all set. Appreciate the fix and the regression test to lock it in!

[glenn-jocher]

⚡ Actions Trigger

_{Made with ❤️ by Ultralytics Actions}

GitHub Actions below triggered via workflow dispatch for this PR at 2026-07-05 18:14:07 UTC with @ultralytics/run-all command
(available commands are @ultralytics/run-all, @ultralytics/run-ci, and @ultralytics/run-docker):

• ✅ CI: ci.yml run 25328
• ✅ Publish Docker Images: docker.yml run 2528