Spatial Grid & AERONET Sites¶

Satellite sources support spatial filtering via a Region of Interest (ROI) defined as a Grid object or a bounding box.

Grid Object¶

The Grid defines a rectangular ROI:

from gathering.grid import Grid

# From explicit center coordinates
grid = Grid(
    center_lat_lon=[37.164, -3.605],  # [latitude, longitude]
    size_yx=[100, 100],                # [Y lines, X pixels]
    resolution_m=1000.0,               # Spatial resolution in meters
    projection="latlon",               # Coordinate system
)

# Access computed bounding box
print(grid.bounding_box)  # [min_lon, min_lat, max_lon, max_lat]

Grid Parameters¶

Parameter	Type	Description
`center_lat_lon`	`[float, float]`	Center point `[latitude, longitude]`
`size_yx`	`[int, int]`	Grid dimensions `[Y lines, X pixels]`
`resolution_m`	`float`	Pixel resolution in meters
`projection`	`str`	Coordinate reference (`"latlon"`)
`site`	`str`	AERONET station name (alternative to `center_lat_lon`)

Note

Specify either center_lat_lon or site, not both. When site is used, the center coordinates are resolved automatically from AERONET station data.

AERONET Station Resolution¶

The site parameter resolves station names to geographic coordinates using NASA's aeronet_locations_v3.txt database:

from gathering.grid import grid_from_aeronet_site

# Resolve "Granada" to its lat/lon coordinates
grid = grid_from_aeronet_site(
    site="Granada",
    size_yx=[100, 100],
    resolution_m=1000.0,
)

print(grid.center_lat_lon)  # [37.164, -3.605]

Auto-Download¶

The AERONET station database file (aeronet_locations_v3.txt) is downloaded automatically on first use and cached in the default cache directory (/workspace/.cache/gathering/). Subsequent calls use the cached version.

Station Name Matching¶

Station names are matched case-insensitively and support partial matches. Examples:

"Granada" → Granada
"El_Arenosillo" → El_Arenosillo
"Thessaloniki" → Thessaloniki

Using Grid in YAML¶

From AERONET Station¶

grid:
  site: "Granada"
  size_yx: [100, 100]
  resolution_m: 1000.0
  projection: "latlon"

From Explicit Coordinates¶

grid:
  center_lat_lon: [37.164, -3.605]
  size_yx: [100, 100]
  resolution_m: 1000.0
  projection: "latlon"

Bounding Box Alternative¶

Some sources also support a direct bounding box:

# [min_lon, min_lat, max_lon, max_lat]
bounding_box: [-10.0, 35.0, 5.0, 45.0]

Tip

Use grid for precise ROI centered on a point of interest. Use bounding_box when you already know the exact geographic extent you need.

Sources Supporting Spatial Filtering¶

Source	Grid	Bounding Box
`cdse`
`eumdac`
`earthcare`
`pace`
`modis`