feat: optional scale/dimensions for image downloads (getDownloadURL)

[caioarantes]

feat: optional scale/dimensions for image downloads (getDownloadURL)

download_multiple_images_async (agrigee_lite/get/image.py) always calls:

url = await asyncio.wait_for(
    asyncio.to_thread(
        img.getDownloadURL, {"name": image_names[chunk_index], "region": ee_geometry}
    ),
    timeout=180,
)

No scale (or dimensions/crs_transform) is passed, so Earth Engine exports at the image's native/nominal projection scale regardless of what the caller actually needs the pixels for. That's fine when the goal is a scientific-grade raster, but for anything that only needs a low-res preview/thumbnail (e.g. rendering a small RGB/NDVI PNG for a UI), it means downloading full native-resolution GeoTIFFs — for Sentinel-2 that's 10 m/px over the whole requested region, which for a several-hectare polygon is comfortably more pixels than any on-screen rendering will ever use, all discarded after downsampling client-side.

Ask: thread an optional scale (meters/pixel) — and maybe dimensions as an alternative — through download_multiple_images / download_multiple_images_async down to the getDownloadURL call, e.g.:

params = {"name": image_names[chunk_index], "region": ee_geometry}
if scale is not None:
    params["scale"] = scale
elif dimensions is not None:
    params["dimensions"] = dimensions
url = await asyncio.wait_for(asyncio.to_thread(img.getDownloadURL, params), timeout=180)

with the same optional param surfaced on the FastAPI POST /images route (ImagesRequest) so it's usable end-to-end without a fork.

Why this is worth it: it's a pure opt-in (default None → today's native-scale behavior, zero behavior change for existing callers), and for preview/UI use cases it cuts the bytes GEE renders + the VM downloads + callers fetch by roughly (native_scale / requested_scale)² — often an order of magnitude for a coarse preview. Happy to send a PR for this if a scale/dimensions param is welcome — wanted to check the shape first since getDownloadURL also supports crs/crs_transform and I didn't want to guess which knobs you'd want exposed vs keep internal.

Context: we run agrigee-lite (pinned image) on a private VM to build a Sentinel-2/Landsat/MODIS NDVI time series + historical RGB/NDVI scene viewer for small-farm polygons (mateuspinto/AgriGEE.lite#28 is us too). The per-satellite bands param already lets us trim to just the 4 bands we render, which helps a lot — scale would be the other big lever for the imagery path specifically.