Support custom polygon boundaries with automatic clipping #18

Current Behavior

Currently, BigMap only supports rectangular bounding boxes for data downloads, even when using county boundaries. When a user specifies a county, the system:

1. Loads the county polygon geometry
2. Extracts the rectangular bounding box using gdf.total_bounds
3. Downloads data for the entire rectangle
4. The actual polygon boundary is discarded

This means users get data for areas outside their region of interest (e.g., downloading a rectangular bbox for an irregularly-shaped county includes areas outside the county).

Proposed Enhancement

Add support for custom polygon boundaries that:

1. Accept polygon input from multiple sources:
   • GeoJSON files
   • Shapefiles
   • GeoDataFrame objects
   • WKT strings
2. Use the polygon's bounding box for the initial download
3. Automatically clip/mask the downloaded data to the actual polygon boundary after download
4. Preserve the polygon geometry in the Zarr store metadata for visualization

Use Cases

• Analyzing forest metrics for specific counties without including surrounding areas
• Custom study areas that follow watershed boundaries, ecological regions, or administrative boundaries
• Research projects requiring precise spatial boundaries for statistical analysis
• Reducing storage and processing requirements by excluding irrelevant data

API Design Proposal

from bigmap import BigMapAPI
from pathlib import Path

api = BigMapAPI()

# Option 1: From file
files = api.download_species(
    polygon="/path/to/boundary.geojson",
    species_codes=["0202"],
    clip_to_polygon=True  # Default: True
)

# Option 2: From GeoDataFrame
import geopandas as gpd
polygon_gdf = gpd.read_file("boundary.shp")
files = api.download_species(
    polygon=polygon_gdf,
    species_codes=["0202"]
)

# Option 3: Enhanced county/state (use actual boundary, not bbox)
files = api.download_species(
    state="Oregon",
    county="Lane",
    use_boundary_clip=True  # Use actual county shape, not just bbox
)

Implementation Considerations

1. Download: Still use rectangular bbox for REST API calls (server limitation)
2. Post-processing: Apply polygon mask after download using rasterio.mask.mask() or similar
3. Zarr storage: Store clipped arrays with polygon boundary in metadata
4. Performance: Add option to skip clipping for performance-critical workflows
5. Validation: Ensure polygon CRS matches or can be transformed to match data CRS
6. Visualization: Use stored polygon boundary for map overlays

Related Code

• bigmap/utils/location_config.py:197-229 - County config setup
• bigmap/utils/location_config.py:254-279 - Bounding box extraction
• bigmap/api.py:133-231 - Download species method
• bigmap/external/fia_client.py - REST client (bbox-based downloads)

References

• rasterio.mask.mask() - https://rasterio.readthedocs.io/en/stable/api/rasterio.mask.html
• GeoPandas clipping - https://geopandas.org/en/stable/docs/user_guide/set_operations.html