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

[Copilot]

download_multiple_images_async always exported at native EE scale, forcing full-resolution GeoTIFF downloads even for preview/thumbnail use cases where the pixels are discarded after client-side downsampling.

Changes

• _fetch_and_download_image — builds getDownloadURL params with scale → dimensions → neither precedence:

  params: dict[str, Any] = {"name": image_names[chunk_index], "region": ee_geometry}
  if scale is not None:
      params["scale"] = scale
  elif dimensions is not None:
      params["dimensions"] = dimensions

• _compute_images_cache_dir — includes scale and dimensions in the metadata hash so different resolutions get isolated cache dirs.
• download_multiple_images / download_multiple_images_async — expose scale: float | None and dimensions: int | str | None; both default to None (zero behaviour change for existing callers).
• ImagesRequest — adds scale (gt=0) and dimensions fields to the Pydantic model with Field descriptions, surfacing the knobs on POST /images.
• routes/images.py — threads request.scale / request.dimensions through to both the download call and the cache-dir hash.

• Fixes feat: optional scale/dimensions for image downloads (getDownloadURL) #30

[Copilot]

Pull request overview

Adds opt-in control over Earth Engine getDownloadURL output resolution for image downloads, allowing callers (including the /images API) to request lower-res exports via scale or dimensions to reduce download size for preview/thumbnail workflows (Fixes #30).

Changes:

• Thread scale / dimensions through download_multiple_images(_async) into _fetch_and_download_image and apply them to img.getDownloadURL(...) with scale → dimensions precedence.
• Add scale / dimensions to the deterministic cache-dir hashing to isolate cached downloads by resolution.
• Expose scale / dimensions on the FastAPI ImagesRequest model and pass them through in routes/images.py.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
agrigee_lite/get/image.py	Adds optional scale/dimensions plumbing to download URL params and includes them in cache hashing.
agrigee_lite/api/routes/images.py	Passes scale/dimensions from API requests into download calls and cache/job hashing.
agrigee_lite/api/_models.py	Adds scale/dimensions fields to the /images request model for OpenAPI exposure.

Suppressed comments (1)

agrigee_lite/get/image.py:396

• For SingleImageSatellite, scale/dimensions are included in _compute_images_cache_dir(...) (so they affect the cache dir/job hash), but _download_single_image_zip_async(...) always exports using scale=satellite.pixelSize and ignores these new options. This can create multiple cache dirs for identical output and makes the API parameters silently ineffective for single-image downloads. Either thread scale/dimensions into _download_single_image_zip_async (with a fallback to satellite.pixelSize when neither is provided), or omit these fields from the cache hash when satellite is a SingleImageSatellite.

            max_retries_per_chunk=max_retries_per_chunk,
            crs=crs,
            scale=scale,
            dimensions=dimensions,
        )

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Fixed in the latest commit. scale and dimensions are now only added to the cache-hash metadata dict when they are explicitly provided (not None), preserving stable cache IDs for existing callers. scale is also normalized via str(float(scale)) for canonical string representation.