⚡️ Speed up method ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size by 312%

[codeflash-ai]

📄 312% (3.12x) speedup for ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size in unstructured/metrics/object_detection.py

⏱️ Runtime : 335 microseconds → 81.3 microseconds (best of 250 runs)

📝 Explanation and details

The optimization replaces NumPy's vectorized .clip() operations with a custom Numba-compiled function that performs explicit bounds checking through manual loops. This achieves a 311% speedup (335μs → 81.3μs) despite appearing to trade vectorized operations for explicit loops.

Key optimizations applied:

1. Numba JIT compilation: The @njit(cache=True, fastmath=True) decorator compiles the clipping function to optimized machine code, eliminating Python interpreter overhead
2. Cache-enabled compilation: cache=True stores the compiled version for subsequent runs, avoiding recompilation costs
3. Fast math optimizations: fastmath=True enables aggressive floating-point optimizations
4. In-place operations: The function modifies the input array directly without creating intermediate arrays

Why this is faster than NumPy:

NumPy's .clip() creates intermediate arrays for fancy indexing operations like boxes[..., [0, 2]], requiring memory allocation and element copying. The original code performs this twice (once for x-coordinates, once for y-coordinates). The Numba version eliminates these allocations by processing elements directly in a tight loop that the compiler can heavily optimize.

Performance characteristics from tests:

• Small arrays (1-10 boxes): 600-700% speedup - Numba's compiled code dominates overhead
• Medium arrays (100s of boxes): 200-300% speedup - Sweet spot where loop efficiency shines
• Large arrays (1000+ boxes): 22-200% speedup - Still beneficial but diminishing returns as vectorization advantages increase

This optimization is particularly valuable for object detection pipelines that process many small to medium batches of bounding boxes, which is typical in computer vision workloads where this function would likely be called frequently during evaluation.

✅ Correctness verification report:

Test	Status
⚙️ Existing Unit Tests	🔘 None Found
🌀 Generated Regression Tests	✅ 35 Passed
⏪ Replay Tests	🔘 None Found
🔎 Concolic Coverage Tests	🔘 None Found
📊 Tests Coverage	100.0%

🌀 Generated Regression Tests and Runtime

import numpy as np

# imports
# function to test
import torch

from unstructured.metrics.object_detection import ObjectDetectionEvalProcessor

IOU_THRESHOLDS = torch.tensor(
    [0.5000, 0.5500, 0.6000, 0.6500, 0.7000, 0.7500, 0.8000, 0.8500, 0.9000, 0.9500]
)
SCORE_THRESHOLD = 0.1
RECALL_THRESHOLDS = torch.arange(0, 1.01, 0.01)

# unit tests

# 1. BASIC TEST CASES


def test_bbox_within_bounds_unchanged():
    # All bboxes are inside the image, should not be clipped
    boxes = np.array([[10, 20, 30, 40], [0, 0, 50, 50], [5, 5, 15, 15]], dtype=np.float32)
    img_shape = (100, 100)
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    clipped = codeflash_output  # 8.83μs -> 1.25μs (607% faster)


def test_bbox_partially_outside_bounds():
    # Some coords are negative or exceed image size
    boxes = np.array(
        [
            [-10, -10, 110, 110],  # All coords out of bounds
            [20, 30, 120, 140],  # x2, y2 out of bounds
            [-5, 10, 15, 120],  # x1, y2 out of bounds
        ],
        dtype=np.float32,
    )
    img_shape = (100, 100)
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    clipped = codeflash_output  # 8.58μs -> 1.25μs (587% faster)
    expected = np.array([[0, 0, 100, 100], [20, 30, 100, 100], [0, 10, 15, 100]], dtype=np.float32)


def test_bbox_exactly_on_bounds():
    # Bboxes exactly on the image edge
    boxes = np.array(
        [
            [0, 0, 100, 100],
            [100, 100, 100, 100],
            [0, 50, 100, 50],
        ],
        dtype=np.float32,
    )
    img_shape = (100, 100)
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    clipped = codeflash_output  # 8.50μs -> 1.17μs (629% faster)


def test_bbox_float_coords():
    # Bboxes with float coordinates
    boxes = np.array([[-1.7, 0.5, 100.2, 99.9], [10.4, 20.6, 50.7, 80.8]], dtype=np.float32)
    img_shape = (100, 100)
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    clipped = codeflash_output  # 8.50μs -> 1.17μs (629% faster)
    expected = np.array([[0.0, 0.5, 100.0, 99.9], [10.4, 20.6, 50.7, 80.8]], dtype=np.float32)


# 2. EDGE TEST CASES


def test_bbox_completely_outside_left_top():
    # All boxes are completely out of bounds (negative)
    boxes = np.array([[-50, -50, -10, -10], [-1, -2, -0.1, -0.2]], dtype=np.float32)
    img_shape = (100, 100)
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    clipped = codeflash_output  # 8.42μs -> 1.12μs (648% faster)
    expected = np.zeros_like(boxes)


def test_bbox_completely_outside_right_bottom():
    # All boxes are completely out of bounds (too large)
    boxes = np.array([[101, 101, 200, 200], [150, 120, 180, 180]], dtype=np.float32)
    img_shape = (100, 100)
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    clipped = codeflash_output  # 8.46μs -> 1.12μs (652% faster)
    expected = np.array([[100, 100, 100, 100], [100, 100, 100, 100]], dtype=np.float32)


def test_bbox_zero_area():
    # Boxes with zero area (x1==x2 or y1==y2)
    boxes = np.array([[10, 10, 10, 20], [5, 5, 15, 5]], dtype=np.float32)
    img_shape = (100, 100)
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    clipped = codeflash_output  # 8.33μs -> 1.08μs (669% faster)


def test_bbox_single_box():
    # Single box, partially outside
    boxes = np.array([[-10, 50, 120, 150]], dtype=np.float32)
    img_shape = (100, 100)
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    clipped = codeflash_output  # 8.67μs -> 1.12μs (670% faster)
    expected = np.array([[0, 50, 100, 100]], dtype=np.float32)


def test_bbox_empty_input():
    # No boxes
    boxes = np.empty((0, 4), dtype=np.float32)
    img_shape = (100, 100)
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    clipped = codeflash_output  # 8.92μs -> 1.12μs (693% faster)


def test_bbox_high_dimensional():
    # 3D array (e.g., batch of images)
    boxes = np.array(
        [[[10, 20, 110, 120], [-10, -20, 30, 40]], [[0, 0, 100, 100], [50, 50, 150, 150]]],
        dtype=np.float32,
    )
    img_shape = (100, 100)
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    clipped = codeflash_output  # 11.0μs -> 1.38μs (703% faster)
    expected = np.array(
        [[[10, 20, 100, 100], [0, 0, 30, 40]], [[0, 0, 100, 100], [50, 50, 100, 100]]],
        dtype=np.float32,
    )


def test_bbox_non_square_image():
    # Non-square image shape
    boxes = np.array([[-10, -10, 300, 60], [50, 10, 250, 80]], dtype=np.float32)
    img_shape = (60, 200)  # height=60, width=200
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    clipped = codeflash_output  # 8.71μs -> 1.17μs (646% faster)
    expected = np.array([[0, 0, 200, 60], [50, 10, 200, 60]], dtype=np.float32)


def test_bbox_minimal_image():
    # Image size 1x1
    boxes = np.array([[-10, -10, 10, 10], [0, 0, 1, 1]], dtype=np.float32)
    img_shape = (1, 1)
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    clipped = codeflash_output  # 8.50μs -> 1.12μs (656% faster)
    expected = np.array([[0, 0, 1, 1], [0, 0, 1, 1]], dtype=np.float32)


def test_bbox_non_integer_image_shape():
    # Image shape as floats (should work, but clip to int)
    boxes = np.array([[0, 0, 10, 10], [0, 0, 20, 20]], dtype=np.float32)
    img_shape = (15.5, 12.7)
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    clipped = codeflash_output  # 8.75μs -> 1.42μs (518% faster)
    expected = np.array([[0, 0, 10, 10], [0, 0, 12.7, 15.5]], dtype=np.float32)


# 3. LARGE SCALE TEST CASES


def test_bbox_large_number_of_boxes():
    # Many boxes, some in bounds, some out
    N = 1000
    boxes = np.zeros((N, 4), dtype=np.float32)
    # Half in bounds, half out
    boxes[: N // 2] = np.stack(
        [
            np.linspace(0, 50, N // 2),  # x1
            np.linspace(0, 50, N // 2),  # y1
            np.linspace(50, 100, N // 2),  # x2
            np.linspace(50, 100, N // 2),  # y2
        ],
        axis=-1,
    )
    boxes[N // 2 :] = np.stack(
        [
            np.linspace(-100, 200, N // 2),  # x1 (some negative, some > W)
            np.linspace(-100, 200, N // 2),  # y1
            np.linspace(-50, 250, N // 2),  # x2
            np.linspace(-50, 250, N // 2),  # y2
        ],
        axis=-1,
    )
    img_shape = (100, 100)
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    clipped = codeflash_output  # 14.2μs -> 4.38μs (226% faster)


def test_bbox_large_batch_of_images():
    # 3D array, batch of 50 images, each with 10 boxes
    batch = 50
    boxes_per_img = 10
    boxes = np.random.uniform(-50, 150, size=(batch, boxes_per_img, 4)).astype(np.float32)
    img_shape = (100, 100)
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    clipped = codeflash_output  # 14.0μs -> 11.0μs (27.7% faster)


def test_bbox_performance_large_array():
    # Test that function can process a large array quickly and correctly
    N = 1000
    boxes = np.random.uniform(-1e3, 1e3, size=(N, 4)).astype(np.float32)
    img_shape = (500, 500)
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    clipped = codeflash_output  # 14.0μs -> 14.0μs (0.300% faster)


# codeflash_output is used to check that the output of the original code is the same as that of the optimized code.

import numpy as np

# imports
# function to test
import torch

from unstructured.metrics.object_detection import ObjectDetectionEvalProcessor

IOU_THRESHOLDS = torch.tensor(
    [0.5000, 0.5500, 0.6000, 0.6500, 0.7000, 0.7500, 0.8000, 0.8500, 0.9000, 0.9500]
)
SCORE_THRESHOLD = 0.1
RECALL_THRESHOLDS = torch.arange(0, 1.01, 0.01)

# unit tests


# ------------- BASIC TEST CASES -------------
def test_bbox_inside_image():
    # All coordinates within image bounds, nothing should change
    boxes = np.array([[10, 20, 30, 40]], dtype=float)
    img_shape = (100, 100)
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    result = codeflash_output  # 8.83μs -> 1.25μs (607% faster)


def test_bbox_on_edges():
    # Box exactly on the image boundary
    boxes = np.array([[0, 0, 100, 100]], dtype=float)
    img_shape = (100, 100)
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    result = codeflash_output  # 8.17μs -> 1.08μs (654% faster)


def test_bbox_outside_positive():
    # Box extends beyond image boundaries, should be clipped
    boxes = np.array([[90, 90, 120, 130]], dtype=float)
    img_shape = (100, 100)
    expected = np.array([[90, 90, 100, 100]], dtype=float)
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    result = codeflash_output  # 8.21μs -> 1.08μs (658% faster)


def test_bbox_outside_negative():
    # Box starts before (0,0), should be clipped to zero
    boxes = np.array([[-10, -5, 20, 15]], dtype=float)
    img_shape = (100, 100)
    expected = np.array([[0, 0, 20, 15]], dtype=float)
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    result = codeflash_output  # 7.96μs -> 1.08μs (635% faster)


def test_multiple_boxes():
    # Multiple boxes with various positions
    boxes = np.array(
        [
            [10, 10, 90, 90],  # inside
            [-10, -10, 10, 10],  # negative
            [90, 90, 110, 120],  # positive overflow
            [0, 0, 100, 100],  # on edge
        ],
        dtype=float,
    )
    img_shape = (100, 100)
    expected = np.array(
        [
            [10, 10, 90, 90],
            [0, 0, 10, 10],
            [90, 90, 100, 100],
            [0, 0, 100, 100],
        ],
        dtype=float,
    )
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    result = codeflash_output  # 8.79μs -> 1.12μs (682% faster)


# ------------- EDGE TEST CASES -------------


def test_bbox_completely_outside():
    # Box completely outside image, should be clipped to zero width/height
    boxes = np.array(
        [
            [-50, -50, -10, -10],  # left-top out
            [150, 150, 200, 200],  # right-bottom out
        ],
        dtype=float,
    )
    img_shape = (100, 100)
    expected = np.array(
        [
            [0, 0, 0, 0],
            [100, 100, 100, 100],
        ],
        dtype=float,
    )
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    result = codeflash_output  # 8.50μs -> 1.08μs (685% faster)


def test_bbox_zero_area():
    # Box with zero area (x1 == x2, y1 == y2)
    boxes = np.array([[50, 50, 50, 50]], dtype=float)
    img_shape = (100, 100)
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    result = codeflash_output  # 8.29μs -> 1.08μs (666% faster)


def test_bbox_float_precision():
    # Box with floating point values, some slightly out of bounds
    boxes = np.array([[99.9999, 0.0001, 100.0001, -0.0001]], dtype=float)
    img_shape = (100, 100)
    expected = np.array([[99.9999, 0.0001, 100, 0]], dtype=float)
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    result = codeflash_output  # 8.12μs -> 1.08μs (650% faster)


def test_empty_boxes():
    # No boxes (empty array)
    boxes = np.empty((0, 4), dtype=float)
    img_shape = (100, 100)
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    result = codeflash_output  # 8.92μs -> 1.08μs (723% faster)


def test_high_dimensional_boxes():
    # Boxes with extra dimensions (e.g., batch of boxes)
    boxes = np.array(
        [[[-10, -10, 10, 10], [90, 90, 110, 120]], [[0, 0, 100, 100], [10, 10, 90, 90]]],
        dtype=float,
    )  # shape (2, 2, 4)
    img_shape = (100, 100)
    expected = np.array(
        [[[0, 0, 10, 10], [90, 90, 100, 100]], [[0, 0, 100, 100], [10, 10, 90, 90]]], dtype=float
    )
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    result = codeflash_output  # 11.0μs -> 1.38μs (700% faster)


def test_img_shape_not_square():
    # Non-square image shape
    boxes = np.array([[0, 0, 200, 50], [150, 40, 250, 60]], dtype=float)
    img_shape = (50, 200)  # height=50, width=200
    expected = np.array([[0, 0, 200, 50], [150, 40, 200, 50]], dtype=float)
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    result = codeflash_output  # 8.71μs -> 1.12μs (674% faster)


def test_img_shape_zero():
    # Image shape with zero height or width
    boxes = np.array([[0, 0, 10, 10], [-5, -5, 15, 15]], dtype=float)
    img_shape = (0, 0)
    expected = np.array([[0, 0, 0, 0], [0, 0, 0, 0]], dtype=float)
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    result = codeflash_output  # 8.50μs -> 1.12μs (656% faster)


def test_single_box_shape():
    # Single box, 1D shape
    boxes = np.array([10, 20, 30, 40], dtype=float)
    img_shape = (25, 25)
    expected = np.array([10, 20, 25, 25], dtype=float)
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    result = codeflash_output  # 8.58μs -> 1.29μs (565% faster)


# ------------- LARGE SCALE TEST CASES -------------


def test_large_number_of_boxes():
    # Large number of boxes, all within bounds
    n = 1000
    boxes = np.stack(
        [
            np.linspace(0, 50, n),
            np.linspace(0, 50, n),
            np.linspace(50, 100, n),
            np.linspace(50, 100, n),
        ],
        axis=-1,
    )  # shape (1000, 4)
    img_shape = (100, 100)
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    result = codeflash_output  # 14.5μs -> 3.67μs (294% faster)


def test_large_boxes_with_overflow():
    # Large number of boxes, some out of bounds
    n = 1000
    boxes = np.zeros((n, 4), dtype=float)
    boxes[:, 0] = np.linspace(-100, 50, n)  # x1, some negative
    boxes[:, 1] = np.linspace(-100, 50, n)  # y1, some negative
    boxes[:, 2] = np.linspace(50, 200, n)  # x2, some > width
    boxes[:, 3] = np.linspace(50, 200, n)  # y2, some > height
    img_shape = (100, 100)
    expected = boxes.copy()
    expected[:, 0] = np.clip(expected[:, 0], 0, img_shape[1])
    expected[:, 2] = np.clip(expected[:, 2], 0, img_shape[1])
    expected[:, 1] = np.clip(expected[:, 1], 0, img_shape[0])
    expected[:, 3] = np.clip(expected[:, 3], 0, img_shape[0])
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    result = codeflash_output  # 13.7μs -> 4.54μs (201% faster)


def test_large_high_dimensional_boxes():
    # Large batch, 3D array (batch, num_boxes, 4)
    batch = 10
    num_boxes = 50
    boxes = np.random.uniform(-50, 150, size=(batch, num_boxes, 4))
    img_shape = (100, 100)
    expected = boxes.copy()
    expected[..., [0, 2]] = np.clip(expected[..., [0, 2]], 0, img_shape[1])
    expected[..., [1, 3]] = np.clip(expected[..., [1, 3]], 0, img_shape[0])
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    result = codeflash_output  # 11.8μs -> 9.62μs (22.5% faster)


# ------------- ADDITIONAL EDGE CASES -------------


def test_negative_image_shape():
    # Negative image shape should clip all to zero (as max=img_shape[1/0]=negative)
    boxes = np.array([[10, 10, 20, 20]], dtype=float)
    img_shape = (-10, -10)
    expected = np.array([[-10, -10, -10, -10]], dtype=float)
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    result = codeflash_output  # 8.58μs -> 1.17μs (636% faster)


def test_non_integer_image_shape():
    # Non-integer image shape, e.g. float values
    boxes = np.array([[0, 0, 30, 40]], dtype=float)
    img_shape = (25.5, 25.5)
    expected = np.array([[0, 0, 25.5, 25.5]], dtype=float)
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    result = codeflash_output  # 8.29μs -> 1.38μs (503% faster)


def test_boxes_with_nan_inf():
    # Boxes with NaN or Inf values
    boxes = np.array([[np.nan, 0, 100, np.inf], [0, np.nan, np.inf, 100]], dtype=float)
    img_shape = (100, 100)
    codeflash_output = ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size(
        boxes.copy(), img_shape
    )
    result = codeflash_output  # 8.79μs -> 1.17μs (654% faster)


# codeflash_output is used to check that the output of the original code is the same as that of the optimized code.

To edit these changes git checkout codeflash/optimize-ObjectDetectionEvalProcessor._change_bbox_bounds_for_image_size-mjceh1u0 and push.