⚡️ Speed up method GlobalMercator.PixelsToMeters by 60%

[codeflash-ai]

📄 60% (0.60x) speedup for GlobalMercator.PixelsToMeters in opendm/tiles/gdal2tiles.py

⏱️ Runtime : 706 microseconds → 441 microseconds (best of 420 runs)

📝 Explanation and details

The optimization adds resolution caching to the GlobalMercator class, achieving a 59% speedup by eliminating redundant mathematical calculations.

What was optimized:

• Added a _resolution_cache dictionary to store computed resolution values by zoom level
• Modified PixelsToMeters to check the cache before calling Resolution()
• Only computes resolution once per unique zoom level, then reuses the cached value

Why this works:
In typical tile processing workflows, the same zoom levels are used repeatedly across many pixel conversions. The original code called Resolution() for every PixelsToMeters() call, performing the expensive division self.initialResolution / (2**zoom) each time. The profiler shows this accounts for 78.5% of PixelsToMeters execution time.

The cache eliminates this redundancy - after the first call for a given zoom level, subsequent calls skip the mathematical computation entirely. The profiler confirms that Resolution() calls dropped from 2,099 to just 614 (only 41 unique zoom levels were encountered), while cache lookups are much faster than division operations.

Best performance gains occur when:

• Processing many pixels at the same zoom levels (like the batch test showing 77.6% improvement)
• Repeated tile generation workflows where zoom levels are reused
• Large-scale tile processing operations

The optimization maintains identical functionality while providing significant speedup for the common use case of processing multiple tiles at consistent zoom levels.

✅ Correctness verification report:

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

🌀 Generated Regression Tests and Runtime

import math

# imports
import pytest  # used for our unit tests
from opendm.tiles.gdal2tiles import GlobalMercator

# unit tests

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

def test_pixels_to_meters_origin_zoom0():
    """
    Test conversion of pixel (0, 0) at zoom level 0.
    Should return (-originShift, -originShift).
    """
    gm = GlobalMercator()
    mx, my = gm.PixelsToMeters(0, 0, 0) # 843ns -> 1.21μs (30.2% slower)

def test_pixels_to_meters_center_tile_zoom0():
    """
    Test conversion of pixel (128, 128) at zoom level 0 (center of tile).
    Should return (0, 0).
    """
    gm = GlobalMercator()
    mx, my = gm.PixelsToMeters(128, 128, 0) # 808ns -> 1.15μs (29.7% slower)

def test_pixels_to_meters_corner_tile_zoom0():
    """
    Test conversion of pixel (256, 256) at zoom level 0 (top-right corner).
    Should return (originShift, originShift).
    """
    gm = GlobalMercator()
    mx, my = gm.PixelsToMeters(256, 256, 0) # 814ns -> 1.11μs (26.7% slower)

def test_pixels_to_meters_arbitrary_pixel_zoom1():
    """
    Test conversion of pixel (100, 200) at zoom level 1.
    """
    gm = GlobalMercator()
    mx, my = gm.PixelsToMeters(100, 200, 1) # 1.10μs -> 1.41μs (22.2% slower)
    res = gm.Resolution(1)
    expected_mx = 100 * res - gm.originShift
    expected_my = 200 * res - gm.originShift

def test_pixels_to_meters_tile_boundary_zoom2():
    """
    Test conversion at tile boundary (512, 512) at zoom level 2.
    """
    gm = GlobalMercator()
    mx, my = gm.PixelsToMeters(512, 512, 2) # 1.04μs -> 1.33μs (21.6% slower)
    res = gm.Resolution(2)
    expected_mx = 512 * res - gm.originShift
    expected_my = 512 * res - gm.originShift

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

def test_pixels_to_meters_negative_pixel_coordinates():
    """
    Test conversion with negative pixel coordinates.
    Should compute meters accordingly (outside tile bounds).
    """
    gm = GlobalMercator()
    mx, my = gm.PixelsToMeters(-1, -1, 0) # 842ns -> 1.15μs (26.7% slower)
    expected_mx = -1 * gm.Resolution(0) - gm.originShift
    expected_my = -1 * gm.Resolution(0) - gm.originShift

def test_pixels_to_meters_large_zoom_level():
    """
    Test conversion at a large zoom level (zoom=22).
    """
    gm = GlobalMercator()
    px, py, zoom = 1, 1, 22
    mx, my = gm.PixelsToMeters(px, py, zoom) # 1.22μs -> 1.55μs (21.1% slower)
    res = gm.Resolution(zoom)
    expected_mx = px * res - gm.originShift
    expected_my = py * res - gm.originShift

def test_pixels_to_meters_zero_zoom_high_pixel():
    """
    Test conversion with high pixel coordinates at zoom 0.
    """
    gm = GlobalMercator()
    px, py, zoom = 10000, 10000, 0
    mx, my = gm.PixelsToMeters(px, py, zoom) # 815ns -> 1.12μs (27.1% slower)
    res = gm.Resolution(0)
    expected_mx = px * res - gm.originShift
    expected_my = py * res - gm.originShift

def test_pixels_to_meters_non_integer_pixel():
    """
    Test conversion with non-integer pixel coordinates.
    """
    gm = GlobalMercator()
    px, py, zoom = 128.5, 255.75, 1
    mx, my = gm.PixelsToMeters(px, py, zoom) # 1.06μs -> 1.33μs (20.3% slower)
    res = gm.Resolution(1)
    expected_mx = px * res - gm.originShift
    expected_my = py * res - gm.originShift

def test_pixels_to_meters_custom_tile_size():
    """
    Test conversion with a custom tile size (512).
    """
    gm = GlobalMercator(tileSize=512)
    px, py, zoom = 256, 256, 0
    mx, my = gm.PixelsToMeters(px, py, zoom) # 883ns -> 1.21μs (26.7% slower)
    res = gm.Resolution(0)
    expected_mx = px * res - gm.originShift
    expected_my = py * res - gm.originShift
    # The originShift should be unchanged, but resolution should be halved
    default_gm = GlobalMercator()

def test_pixels_to_meters_zoom_negative():
    """
    Test conversion with negative zoom (should still compute, but resolution increases).
    """
    gm = GlobalMercator()
    px, py, zoom = 1, 1, -1
    mx, my = gm.PixelsToMeters(px, py, zoom) # 1.51μs -> 1.79μs (15.5% slower)
    res = gm.Resolution(-1)
    expected_mx = px * res - gm.originShift
    expected_my = py * res - gm.originShift

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

def test_pixels_to_meters_many_pixels_zoom0():
    """
    Test conversion for a large number of pixels at zoom 0.
    """
    gm = GlobalMercator()
    for px in range(0, 1000, 100):  # 0, 100, ..., 900
        for py in range(0, 1000, 100):
            mx, my = gm.PixelsToMeters(px, py, 0)
            res = gm.Resolution(0)
            expected_mx = px * res - gm.originShift
            expected_my = py * res - gm.originShift

def test_pixels_to_meters_many_pixels_high_zoom():
    """
    Test conversion for a large number of pixels at zoom 10.
    """
    gm = GlobalMercator()
    zoom = 10
    for px in range(0, 256, 32):  # 0, 32, ..., 224
        for py in range(0, 256, 32):
            mx, my = gm.PixelsToMeters(px, py, zoom)
            res = gm.Resolution(zoom)
            expected_mx = px * res - gm.originShift
            expected_my = py * res - gm.originShift

def test_pixels_to_meters_extreme_pixel_values():
    """
    Test conversion for extreme pixel values at zoom 0 and zoom 22.
    """
    gm = GlobalMercator()
    for zoom in [0, 22]:
        px = 999
        py = 999
        mx, my = gm.PixelsToMeters(px, py, zoom) # 1.64μs -> 2.21μs (25.9% slower)
        res = gm.Resolution(zoom)
        expected_mx = px * res - gm.originShift
        expected_my = py * res - gm.originShift

def test_pixels_to_meters_batch_consistency():
    """
    Test batch conversion consistency for a set of pixel coordinates.
    """
    gm = GlobalMercator()
    pxs = [0, 50, 128, 255, 256, 512, 999]
    pys = [0, 50, 128, 255, 256, 512, 999]
    zooms = [0, 1, 5, 10, 22]
    for px in pxs:
        for py in pys:
            for zoom in zooms:
                mx, my = gm.PixelsToMeters(px, py, zoom)
                res = gm.Resolution(zoom)
                expected_mx = px * res - gm.originShift
                expected_my = py * res - gm.originShift
# codeflash_output is used to check that the output of the original code is the same as that of the optimized code.
#------------------------------------------------
import math

# imports
import pytest  # used for our unit tests
from opendm.tiles.gdal2tiles import GlobalMercator

# unit tests

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

def test_origin_at_zoom_0():
    # At zoom 0, pixel (0,0) should map to (-originShift, -originShift)
    gm = GlobalMercator()
    mx, my = gm.PixelsToMeters(0, 0, 0) # 875ns -> 1.14μs (23.0% slower)

def test_center_tile_at_zoom_0():
    # At zoom 0, center pixel (128,128) should map to (0,0)
    gm = GlobalMercator()
    mx, my = gm.PixelsToMeters(128, 128, 0) # 796ns -> 1.16μs (31.4% slower)

def test_upper_right_corner_at_zoom_0():
    # At zoom 0, pixel (256,256) should map to (originShift, originShift)
    gm = GlobalMercator()
    mx, my = gm.PixelsToMeters(256, 256, 0) # 794ns -> 1.11μs (28.5% slower)

def test_arbitrary_pixel_zoom_1():
    # At zoom 1, pixel (256,256) should be at (0,0)
    gm = GlobalMercator()
    mx, my = gm.PixelsToMeters(256, 256, 1) # 1.07μs -> 1.40μs (23.9% slower)

def test_non_integer_pixel():
    # Non-integer pixel values should be handled correctly
    gm = GlobalMercator()
    mx, my = gm.PixelsToMeters(128.5, 128.5, 0) # 817ns -> 1.12μs (27.3% slower)
    # Should be very close to (0,0) but offset by 0.5 * resolution
    offset = 0.5 * gm.Resolution(0)

def test_custom_tile_size():
    # Changing tile size should affect the results
    gm1 = GlobalMercator(tileSize=256)
    gm2 = GlobalMercator(tileSize=512)
    mx1, my1 = gm1.PixelsToMeters(128, 128, 0) # 819ns -> 1.12μs (27.0% slower)
    mx2, my2 = gm2.PixelsToMeters(256, 256, 0) # 468ns -> 584ns (19.9% slower)

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

def test_negative_pixel_coordinates():
    # Negative pixel coordinates should yield coordinates less than -originShift
    gm = GlobalMercator()
    mx, my = gm.PixelsToMeters(-1, -1, 0) # 840ns -> 1.11μs (24.7% slower)

def test_large_pixel_coordinates():
    # Large pixel coordinates at zoom 0 should yield coordinates greater than originShift
    gm = GlobalMercator()
    mx, my = gm.PixelsToMeters(1000, 1000, 0) # 833ns -> 1.09μs (23.4% slower)

def test_high_zoom_level():
    # At high zoom, the resolution is very small
    gm = GlobalMercator()
    zoom = 22
    px, py = 2**22, 2**22
    mx, my = gm.PixelsToMeters(px, py, zoom) # 1.29μs -> 1.61μs (20.3% slower)

def test_zero_zoom_high_pixel():
    # At zoom 0, pixel coordinates much larger than tileSize
    gm = GlobalMercator()
    mx, my = gm.PixelsToMeters(1_000_000, 1_000_000, 0) # 841ns -> 1.07μs (21.7% slower)

def test_minimum_zoom():
    # Test the lowest possible zoom (0)
    gm = GlobalMercator()
    mx, my = gm.PixelsToMeters(0, 0, 0) # 830ns -> 1.13μs (26.5% slower)

def test_maximum_reasonable_zoom():
    # Test a very high zoom level (e.g., 30)
    gm = GlobalMercator()
    zoom = 30
    px, py = 2**30, 2**30
    mx, my = gm.PixelsToMeters(px, py, zoom) # 1.76μs -> 2.02μs (12.7% slower)

def test_float_zoom_raises():
    # Zoom should be integer; float should still work by mathematical definition,
    # but let's check that the result is mathematically consistent
    gm = GlobalMercator()
    mx1, my1 = gm.PixelsToMeters(128, 128, 0) # 856ns -> 1.08μs (21.1% slower)
    mx2, my2 = gm.PixelsToMeters(128, 128, 0.0) # 782ns -> 824ns (5.10% slower)

def test_nan_pixel_input():
    # NaN input should propagate to output
    gm = GlobalMercator()
    mx, my = gm.PixelsToMeters(float('nan'), 0, 0) # 938ns -> 1.19μs (21.2% slower)
    mx, my = gm.PixelsToMeters(0, float('nan'), 0) # 521ns -> 512ns (1.76% faster)

def test_inf_pixel_input():
    # Infinite input should propagate to output
    gm = GlobalMercator()
    mx, my = gm.PixelsToMeters(float('inf'), 0, 0) # 891ns -> 1.12μs (20.4% slower)
    mx, my = gm.PixelsToMeters(0, float('inf'), 0) # 509ns -> 474ns (7.38% faster)

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

def test_many_pixels_linear():
    # Test a linear range of pixel coordinates at zoom 0
    gm = GlobalMercator()
    for px in range(0, 1000, 100):
        mx, _ = gm.PixelsToMeters(px, 0, 0) # 3.75μs -> 3.78μs (0.794% slower)
        # Should increase linearly
        expected = px * gm.Resolution(0) - gm.originShift

def test_many_pixels_zoom_5():
    # Test a range of pixel coordinates at zoom 5
    gm = GlobalMercator()
    zoom = 5
    for px in range(0, 1000, 100):
        mx, _ = gm.PixelsToMeters(px, 0, zoom) # 5.41μs -> 4.05μs (33.5% faster)
        expected = px * gm.Resolution(zoom) - gm.originShift

def test_grid_of_pixels():
    # Test a grid of pixels at zoom 3
    gm = GlobalMercator()
    zoom = 3
    for px in range(0, 256, 32):
        for py in range(0, 256, 32):
            mx, my = gm.PixelsToMeters(px, py, zoom)
            expected_mx = px * gm.Resolution(zoom) - gm.originShift
            expected_my = py * gm.Resolution(zoom) - gm.originShift

def test_large_batch_performance():
    # Test performance/scalability for 1000 points at zoom 10
    gm = GlobalMercator()
    zoom = 10
    # Use a list to store results to ensure the loop is not optimized away
    results = []
    for px in range(1000):
        mx, my = gm.PixelsToMeters(px, px, zoom) # 466μs -> 262μs (77.6% faster)
        results.append((mx, my))
    # Check a few sample points for correctness
    for i in [0, 100, 500, 999]:
        expected = i * gm.Resolution(zoom) - gm.originShift

def test_large_custom_tile_size():
    # Test with a large custom tile size and high zoom
    gm = GlobalMercator(tileSize=1024)
    zoom = 8
    px, py = 512, 512
    mx, my = gm.PixelsToMeters(px, py, zoom) # 1.21μs -> 1.62μs (25.4% slower)
# 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-GlobalMercator.PixelsToMeters-mh4iraja and push.