perf(inference): skip known-valid image range scans - #1387

predict() converts PIL images to 8-bit RGB, and to_tensor scales both those images and uint8 NumPy arrays into [0, 1]. It then runs (img > 1).any() and (img < 0).any() on the resulting tensor anyway.

Changes

• Record when the conversion already fixed the range, and short-circuit the existing deferred checks to False for those inputs. This also covers file-path and URL inputs, since both get opened into a PIL image before the check runs.
• Keep both reductions for tensor and non-uint8 NumPy inputs.
• Add regression tests that fail if PIL, uint8 NumPy, or file-path conversion ever reaches Tensor.any (including under the public default include_source_image=True), plus float32 NumPy controls that still have to raise on both bounds.

Performance

I benchmarked with the public predict(image, threshold=0.5, include_source_image=False) call, on one real COCO image as a uint8 NumPy array, with torch.set_num_threads(1). It alternates baseline and candidate within 101 pairs, repeating each configuration in three independent processes; CUDA numbers ran serially on an RTX 4060 Laptop GPU.

include_source_image=False isolates the preprocessing path from the source-image copy. Under the public default include_source_image=True, predict() does more work per call (it also captures the source image), so this same absolute saving becomes a smaller share of a bigger total — the percentages below don't carry over to the default configuration as-is.

Each run compares the baseline with itself first, matches boxes by IoU, and compares the matched public detection fields as raw bytes. Baseline and candidate outputs matched in every reported run.

On CPU, the removed reductions take 4.13-4.35 ms per four real images at their original sizes and allocate 6,113,984 bytes per call. The skipped path takes 0.267-0.289 us and allocates no tensor memory. Public CPU predict() timing was noisy, so I'm not reporting it as a speedup.

Validation

• New regression command: 4 failed / 2 passed before the implementation; 6 passed after it.
• tests/inference/test_predict.py: 122 passed.
• CPU inference tests: 281 passed, 1 skipped.
• Precommit: 19/19 hooks passed, including strict mypy.
• Split CPU suite: 4178 passed, 71 skipped, 1 failed. The failure is in tests/export/test_onnx_notes.py's _export_tiny_model doctest. It expects a fixed string, but under -n 2 it picks up an ONNX-export INFO log line from other work on the same xdist worker — it doesn't call predict() or touch this diff's code. I re-ran the same command on unmodified develop three times and got the identical failure, so it's pre-existing and unrelated.
• The patch applies to current develop, and the open PRs touching detr.py don't change this validation block.

COCO mAP wasn't re-run separately. The skip only substitutes a value for (img > 1).any()/(img < 0).any() that to_tensor's [0, 1] scaling of PIL and uint8 NumPy input already guarantees — it doesn't change the tensor the model sees. Public detections on real COCO images came out byte-identical to baseline across every Nano/Small, FP32/FP16 configuration I measured. Since mAP is a deterministic function of detections and ground truth, byte-identical detections mean byte-identical mAP.