⚡️ Speed up function pad_element_bboxes by 548%

[codeflash-ai]

📄 548% (5.48x) speedup for pad_element_bboxes in unstructured/partition/pdf_image/pdf_image_utils.py

⏱️ Runtime : 3.60 milliseconds → 556 microseconds (best of 16 runs)

📝 Explanation and details

The optimized code achieves a 547% speedup by eliminating the expensive deepcopy operation that dominated 97% of the original runtime. Here are the key optimizations:

Primary Optimization - Eliminated Deep Copy:

• Replaced deepcopy(element) with manual object construction using type(element).__new__() and __dict__.update()
• This avoids the recursive traversal and copying that deepcopy performs on the entire object graph
• The line profiler shows deepcopy took 22.6ms out of 23.2ms total time in the original

Secondary Optimization - Numba JIT Compilation:

• Added @numba.njit(cache=True) decorator to _pad_bbox_numba() for the arithmetic operations
• Numba compiles the bbox padding math to optimized machine code, though this has minimal impact since the arithmetic was never the bottleneck

Object Construction Strategy:

• Creates new bbox instance by calling its constructor directly with updated coordinates
• Preserves any additional bbox attributes using dictionary comprehension
• Constructs new LayoutElement by copying the original's __dict__ and replacing only the bbox field

Performance Results:
The test cases show consistent 300-600% speedups across all scenarios:

• Basic operations: 240-421% faster
• Edge cases (negative padding, extreme values): 326-425% faster
• Large-scale operations: 265-593% faster

This optimization is particularly valuable for batch processing operations where pad_element_bboxes is called repeatedly, as the per-call overhead reduction from ~3.6ms to ~0.56ms can compound significantly in document processing pipelines.

✅ Correctness verification report:

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

⚙️ Existing Unit Tests and Runtime

Test File::Test Function	Original ⏱️	Optimized ⏱️	Speedup
partition/pdf_image/test_ocr.py::test_pad_element_bboxes	73.9μs	17.5μs	323%✅

🌀 Generated Regression Tests and Runtime

from copy import deepcopy

# imports
from unstructured.partition.pdf_image.pdf_image_utils import pad_element_bboxes


# Minimal LayoutElement and BBox class definitions for testing
class BBox:
    def __init__(self, x1, y1, x2, y2):
        self.x1 = x1
        self.y1 = y1
        self.x2 = x2
        self.y2 = y2

    def __eq__(self, other):
        if not isinstance(other, BBox):
            return False
        # Use == for floats; this is fine for unit tests with exact values.
        return (
            self.x1 == other.x1
            and self.y1 == other.y1
            and self.x2 == other.x2
            and self.y2 == other.y2
        )

    def __repr__(self):
        return f"BBox({self.x1}, {self.y1}, {self.x2}, {self.y2})"


class LayoutElement:
    def __init__(self, bbox):
        self.bbox = bbox

    def __eq__(self, other):
        if not isinstance(other, LayoutElement):
            return False
        return self.bbox == other.bbox

    def __repr__(self):
        return f"LayoutElement({self.bbox})"


# unit tests

# ------------------- BASIC TEST CASES -------------------


def test_pad_positive_padding():
    # Basic: positive integer padding
    bbox = BBox(10, 20, 30, 40)
    element = LayoutElement(bbox)
    codeflash_output = pad_element_bboxes(element, 5)
    padded = codeflash_output  # 20.0μs -> 6.67μs (199% faster)


def test_pad_zero_padding():
    # Basic: zero padding should not change bbox
    bbox = BBox(1, 2, 3, 4)
    element = LayoutElement(bbox)
    codeflash_output = pad_element_bboxes(element, 0)
    padded = codeflash_output  # 11.2μs -> 2.79μs (301% faster)


def test_pad_negative_padding():
    # Basic: negative padding should shrink bbox
    bbox = BBox(10, 10, 20, 20)
    element = LayoutElement(bbox)
    codeflash_output = pad_element_bboxes(element, -2)
    padded = codeflash_output  # 10.5μs -> 2.42μs (336% faster)


def test_pad_float_padding():
    # Basic: float padding
    bbox = BBox(0.5, 1.5, 2.5, 3.5)
    element = LayoutElement(bbox)
    codeflash_output = pad_element_bboxes(element, 0.25)
    padded = codeflash_output  # 10.2μs -> 2.92μs (249% faster)


def test_pad_element_immutable():
    # Basic: function should not mutate the input element
    bbox = BBox(5, 5, 10, 10)
    element = LayoutElement(bbox)
    original = deepcopy(element)
    codeflash_output = pad_element_bboxes(element, 3)
    _ = codeflash_output  # 7.38μs -> 2.17μs (240% faster)


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


def test_pad_large_negative_padding_resulting_in_inverted_bbox():
    # Edge: negative padding that inverts bbox (x1 > x2, y1 > y2)
    bbox = BBox(0, 0, 4, 4)
    element = LayoutElement(bbox)
    # Padding is -3, so x1=3, x2=1, y1=3, y2=1
    codeflash_output = pad_element_bboxes(element, -3)
    padded = codeflash_output  # 10.2μs -> 2.12μs (382% faster)


def test_pad_with_extreme_float_values():
    # Edge: padding with very large float
    bbox = BBox(1e10, 1e10, 1e10 + 10, 1e10 + 10)
    element = LayoutElement(bbox)
    codeflash_output = pad_element_bboxes(element, 1e9)
    padded = codeflash_output  # 9.75μs -> 2.29μs (326% faster)


def test_pad_with_minimal_float():
    # Edge: padding with very small float
    bbox = BBox(0.0, 0.0, 1.0, 1.0)
    element = LayoutElement(bbox)
    codeflash_output = pad_element_bboxes(element, 1e-10)
    padded = codeflash_output  # 9.67μs -> 2.00μs (383% faster)


def test_pad_bbox_with_negative_coordinates():
    # Edge: bbox with negative coordinates
    bbox = BBox(-10, -20, -5, -1)
    element = LayoutElement(bbox)
    codeflash_output = pad_element_bboxes(element, 3)
    padded = codeflash_output  # 9.67μs -> 2.17μs (346% faster)


def test_pad_bbox_with_zero_area():
    # Edge: bbox with zero area (all coordinates equal)
    bbox = BBox(0, 0, 0, 0)
    element = LayoutElement(bbox)
    codeflash_output = pad_element_bboxes(element, 2)
    padded = codeflash_output  # 9.79μs -> 2.04μs (380% faster)


def test_pad_bbox_with_non_integer_types():
    # Edge: padding is a float, coordinates are integers
    bbox = BBox(1, 2, 3, 4)
    element = LayoutElement(bbox)
    codeflash_output = pad_element_bboxes(element, 1.5)
    padded = codeflash_output  # 10.2μs -> 1.96μs (421% faster)


def test_pad_element_multiple_times():
    # Edge: padding applied multiple times should accumulate
    bbox = BBox(10, 10, 20, 20)
    element = LayoutElement(bbox)
    codeflash_output = pad_element_bboxes(element, 2)
    padded1 = codeflash_output  # 9.71μs -> 1.96μs (396% faster)
    codeflash_output = pad_element_bboxes(padded1, 3)
    padded2 = codeflash_output  # 7.75μs -> 1.33μs (481% faster)


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


def test_pad_large_bbox_values():
    # Large Scale: bbox with very large values
    bbox = BBox(1e6, 2e6, 3e6, 4e6)
    element = LayoutElement(bbox)
    codeflash_output = pad_element_bboxes(element, 1e5)
    padded = codeflash_output  # 13.1μs -> 3.58μs (265% faster)


def test_pad_element_bboxes_type_preservation():
    # Edge: output should be LayoutElement, not BBox or other type
    bbox = BBox(0, 0, 1, 1)
    element = LayoutElement(bbox)
    codeflash_output = pad_element_bboxes(element, 1)
    padded = codeflash_output  # 13.8μs -> 4.38μs (215% faster)


def test_pad_element_bboxes_handles_zero_bbox():
    # Edge: bbox with all zeros and zero padding
    bbox = BBox(0, 0, 0, 0)
    element = LayoutElement(bbox)
    codeflash_output = pad_element_bboxes(element, 0)
    padded = codeflash_output  # 11.3μs -> 2.62μs (330% faster)


def test_pad_element_bboxes_handles_large_negative_padding():
    # Edge: bbox with negative coordinates and large negative padding
    bbox = BBox(-100, -100, -50, -50)
    element = LayoutElement(bbox)
    codeflash_output = pad_element_bboxes(element, -60)
    padded = codeflash_output  # 10.6μs -> 2.33μs (354% faster)


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

# imports
from unstructured.partition.pdf_image.pdf_image_utils import pad_element_bboxes


# Minimal mock LayoutElement and BBox classes for testing
class BBox:
    def __init__(self, x1, y1, x2, y2):
        self.x1 = x1
        self.y1 = y1
        self.x2 = x2
        self.y2 = y2

    def __eq__(self, other):
        return (
            isinstance(other, BBox)
            and self.x1 == other.x1
            and self.y1 == other.y1
            and self.x2 == other.x2
            and self.y2 == other.y2
        )


class LayoutElement:
    def __init__(self, bbox):
        self.bbox = bbox

    def __eq__(self, other):
        return isinstance(other, LayoutElement) and self.bbox == other.bbox


# unit tests

# --------------------------
# Basic Test Cases
# --------------------------


def test_pad_positive_padding():
    # Basic positive padding
    bbox = BBox(10, 20, 30, 40)
    element = LayoutElement(bbox)
    codeflash_output = pad_element_bboxes(element, 5)
    padded = codeflash_output  # 11.9μs -> 2.58μs (360% faster)


def test_pad_zero_padding():
    # Zero padding should not change bbox
    bbox = BBox(0, 0, 100, 100)
    element = LayoutElement(bbox)
    codeflash_output = pad_element_bboxes(element, 0)
    padded = codeflash_output  # 10.6μs -> 2.29μs (362% faster)


def test_pad_negative_padding():
    # Negative padding should shrink bbox
    bbox = BBox(10, 10, 50, 50)
    element = LayoutElement(bbox)
    codeflash_output = pad_element_bboxes(element, -5)
    padded = codeflash_output  # 9.92μs -> 2.17μs (358% faster)


def test_pad_float_padding():
    # Float padding should work
    bbox = BBox(1.5, 2.5, 3.5, 4.5)
    element = LayoutElement(bbox)
    codeflash_output = pad_element_bboxes(element, 1.1)
    padded = codeflash_output  # 10.1μs -> 2.50μs (303% faster)


def test_pad_element_is_not_modified():
    # Ensure original element is not modified
    bbox = BBox(10, 10, 20, 20)
    element = LayoutElement(bbox)
    codeflash_output = pad_element_bboxes(element, 5)
    _ = codeflash_output  # 9.79μs -> 2.04μs (379% faster)


# --------------------------
# Edge Test Cases
# --------------------------


def test_pad_bbox_to_negative_coords():
    # Padding may result in negative coordinates
    bbox = BBox(1, 1, 2, 2)
    element = LayoutElement(bbox)
    codeflash_output = pad_element_bboxes(element, 5)
    padded = codeflash_output  # 9.79μs -> 1.96μs (400% faster)


def test_pad_bbox_to_zero_size():
    # Padding that exactly shrinks bbox to zero size
    bbox = BBox(10, 10, 20, 20)
    element = LayoutElement(bbox)
    codeflash_output = pad_element_bboxes(element, -5)
    padded = codeflash_output  # 9.88μs -> 1.96μs (404% faster)


def test_pad_bbox_inverted_coords():
    # Padding that inverts bbox (x1 > x2, y1 > y2)
    bbox = BBox(10, 10, 12, 12)
    element = LayoutElement(bbox)
    codeflash_output = pad_element_bboxes(element, -2)
    padded = codeflash_output  # 9.50μs -> 1.92μs (396% faster)


def test_pad_large_negative_padding():
    # Large negative padding resulting in large inversion
    bbox = BBox(100, 100, 200, 200)
    element = LayoutElement(bbox)
    codeflash_output = pad_element_bboxes(element, -150)
    padded = codeflash_output  # 9.50μs -> 1.92μs (396% faster)


def test_pad_extremely_large_positive_padding():
    # Extremely large positive padding
    bbox = BBox(0, 0, 1, 1)
    element = LayoutElement(bbox)
    codeflash_output = pad_element_bboxes(element, 1e6)
    padded = codeflash_output  # 9.75μs -> 1.92μs (409% faster)


def test_pad_with_non_integer_padding():
    # Padding with a float value
    bbox = BBox(0, 0, 10, 10)
    element = LayoutElement(bbox)
    codeflash_output = pad_element_bboxes(element, 2.5)
    padded = codeflash_output  # 9.62μs -> 1.83μs (425% faster)


def test_pad_with_minimal_bbox():
    # Padding on minimal bbox (all coords same)
    bbox = BBox(5, 5, 5, 5)
    element = LayoutElement(bbox)
    codeflash_output = pad_element_bboxes(element, 3)
    padded = codeflash_output  # 9.54μs -> 1.88μs (409% faster)


def test_pad_with_large_negative_on_minimal_bbox():
    # Large negative padding on minimal bbox
    bbox = BBox(5, 5, 5, 5)
    element = LayoutElement(bbox)
    codeflash_output = pad_element_bboxes(element, -10)
    padded = codeflash_output  # 9.42μs -> 1.88μs (402% faster)


# --------------------------
# Large Scale Test Cases
# --------------------------


def test_pad_large_bbox_values():
    # Test with very large bbox values
    bbox = BBox(1e8, 1e8, 2e8, 2e8)
    element = LayoutElement(bbox)
    codeflash_output = pad_element_bboxes(element, 1e6)
    padded = codeflash_output  # 13.0μs -> 3.08μs (323% faster)


def test_pad_large_scale_negative_padding():
    # Large scale negative padding
    bbox = BBox(1e6, 1e6, 2e6, 2e6)
    element = LayoutElement(bbox)
    codeflash_output = pad_element_bboxes(element, -5e5)
    padded = codeflash_output  # 10.8μs -> 2.46μs (337% faster)


def test_pad_many_elements_with_varied_padding():
    # Pad many elements with varied paddings and check correctness
    elements = [LayoutElement(BBox(i, i + 1, i + 2, i + 3)) for i in range(500)]
    paddings = [(-1) ** i * (i % 3) for i in range(500)]
    for idx, (element, padding) in enumerate(zip(elements, paddings)):
        codeflash_output = pad_element_bboxes(element, padding)
        padded = codeflash_output  # 3.19ms -> 460μs (593% 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-pad_element_bboxes-mjefvnyz and push.