Polygons

Module: spectralbridge.polygons.

Polygon extraction helpers for building spectral libraries.

This module provides utilities for extracting polygon-based subsets from the per-pixel Parquet products that the SpectralBridge pipeline already produces. The helpers are intentionally orthogonal to the default flightline pipeline so that they can be orchestrated separately while the workflow is stabilised.

API glossary · Workflow / scientific context

Signatures and documentation below are collected from the current source. Advanced objects are not newly declared stable by inclusion here.

Audience: advanced.

create_dummy_polygon

create_dummy_polygon(flight_paths: FlightlinePaths, reference_product: str = 'brdfandtopo_corrected_envi', pixel_size: tuple[int, int] | None = None, buffer_pct: float = 0.1, output_path: Path | str | None = None) -> Path

Create a dummy polygon covering a portion of the flightline.

Creates a simple rectangular polygon. If pixel_size is provided, creates a polygon covering exactly that many pixels (e.g., (4, 4) for a 4x4 pixel polygon). Otherwise, creates a polygon covering (100 - buffer_pct*2)% of the image, centered.

Parameters:

Name	Type	Description	Default
flight_paths	FlightlinePaths	Flightline paths object	required
reference_product	str	Reference product to use for determining image bounds	"brdfandtopo_corrected_envi"
pixel_size	tuple[int, int] | None	Size of polygon in pixels (width, height). If provided, creates a polygon covering exactly these pixels from the center of the image. Example: (4, 4) for a 4x4 pixel polygon. If None, uses buffer_pct instead.	None
buffer_pct	float	Percentage to buffer from edges (0.1 = 10% buffer on each side). Only used if pixel_size is None.	0.1
output_path	Path | str | None	Output path for the dummy polygon GeoJSON. If None, creates: _dummy_polygon.geojson	None

Returns:

Type	Description
Path	Path to the created dummy polygon GeoJSON file

Notes

To use a different polygon, provide a GeoJSON file path to polygon_path in go_forth_and_multiply() instead of using this function.

Audience: advanced.

validate_coordinate_match

validate_coordinate_match(polygons, img_path: Path, hdr_path: Path, *, tolerance_m: float = 10000.0) -> tuple[bool, str]

Validate that polygon and ENVI coordinates match.

Parameters:

Name	Type	Description	Default
polygons		GeoDataFrame containing polygons to validate	required
img_path	Path	Path to ENVI image file	required
hdr_path	Path	Path to ENVI header file	required
tolerance_m	float	Tolerance in meters for coordinate validation	100.0

Returns:

Type	Description
tuple[bool, str]	(is_valid, message) - True if coordinates match, False otherwise with error message

Audience: advanced.

filter_polygons_by_overlap

filter_polygons_by_overlap(polygons_path: str | Path, flight_paths: FlightlinePaths, reference_product: str = 'brdfandtopo_corrected_envi', min_overlap_pct: float = 0.0, *, output_path: Path | str | None = None, validate_coords: bool = True, search_buffer_m: float = 0.0) -> tuple[Path, pd.DataFrame]

Filter polygons from GeoJSON that overlap the flightline.

Parameters:

Name	Type	Description	Default
polygons_path	str | Path	Path to GeoJSON file containing polygons	required
flight_paths	FlightlinePaths	Flightline paths object	required
reference_product	str	Reference product to use for determining flightline bounds	"brdfandtopo_corrected_envi"
min_overlap_pct	float	Minimum percentage of polygon area that must overlap with flightline. Set to 0.0 to include any polygon that touches the flightline. Set to 1.0 to only include polygons completely inside the flightline.	0.0
output_path	Path | str | None	Path to save filtered GeoJSON. If None, saves to flightline directory.	None
search_buffer_m	float	Buffer distance in meters to expand the flightline search area. Polygons within this distance of the flightline will be included even if they don't directly overlap. Useful when polygons are nearby but don't intersect due to precision issues or small gaps.	0.0

Returns:

Type	Description
tuple[Path, DataFrame]	Path to filtered GeoJSON file and DataFrame with overlap statistics

Audience: advanced.

visualize_polygons_on_envi

visualize_polygons_on_envi(flight_paths: FlightlinePaths, polygons_path: str | Path, reference_product: str = 'brdfandtopo_corrected_envi', output_path: Path | str | None = None, *, rgb_bands: tuple[float, float, float] | None = None, dpi: int = 300, validate_coords: bool = True) -> Path

Create a visualization showing polygons overlaid on ENVI RGB image.

Parameters:

Name	Type	Description	Default
flight_paths	FlightlinePaths	Flightline paths object	required
polygons_path	str | Path	Path to GeoJSON file containing polygons	required
reference_product	str	Reference product to use for RGB visualization	"brdfandtopo_corrected_envi"
output_path	Path | str | None	Path to save visualization PNG. If None, saves to flightline directory.	None
rgb_bands	tuple[float, float, float] | None	Wavelengths (nm) for R, G, B bands. If None, uses default (660, 560, 490).	None
dpi	int	Resolution for output image	300

Returns:

Type	Description
Path	Path to saved visualization PNG

Audience: advanced.

build_polygon_pixel_index

build_polygon_pixel_index(flight_paths: FlightlinePaths, polygons_path: str | Path, output_path: Path | str | None = None, *, reference_product: str = 'brdfandtopo_corrected_envi', overwrite: bool = False, all_touched: bool = False) -> Path

Create a pixel→polygon lookup table for flight_paths.

The resulting Parquet table includes one row per pixel that intersects any polygon. Columns comprise the canonical pixel identifiers plus polygon attributes and geometry stored as WKB.

Audience: advanced.

extract_polygon_parquet_from_envi

extract_polygon_parquet_from_envi(envi_img: Path, envi_hdr: Path, polygon_index_path: Path, output_parquet_path: Path, *, chunk_size: int = 50000, overwrite: bool = False) -> Path

Extract polygon-filtered parquet directly from ENVI file.

This function reads an ENVI file and extracts only pixels that intersect with the polygon, writing directly to a parquet file. This avoids creating the full parquet file first.

Parameters:

Name	Type	Description	Default
envi_img	Path	Path to ENVI .img file	required
envi_hdr	Path	Path to ENVI .hdr file	required
polygon_index_path	Path	Path to polygon pixel index parquet (from build_polygon_pixel_index)	required
output_parquet_path	Path	Output path for the polygon-filtered parquet	required
chunk_size	int	Chunk size for reading ENVI file	50_000
overwrite	bool	Whether to overwrite existing parquet file	False

Returns:

Type	Description
Path	Path to the created polygon parquet file

Audience: advanced.

extract_all_polygon_parquets_from_envi

extract_all_polygon_parquets_from_envi(flight_paths: FlightlinePaths, polygon_index_path: Path, *, chunk_size: int = 50000, overwrite: bool = False) -> Dict[str, Path]

Extract polygon parquets directly from all ENVI files in flightline.

This discovers all ENVI files and extracts polygon-filtered parquets directly from them, skipping full parquet creation.

Parameters:

Name	Type	Description	Default
flight_paths	FlightlinePaths	Flightline paths object	required
polygon_index_path	Path	Path to polygon pixel index parquet	required
chunk_size	int	Chunk size for reading ENVI files	50_000
overwrite	bool	Whether to overwrite existing polygon parquets	False

Returns:

Type	Description
Dict[str, Path]	Dictionary mapping product names to polygon parquet paths

Audience: advanced.

extract_polygon_parquets_for_flightline

extract_polygon_parquets_for_flightline(flight_paths: FlightlinePaths, polygon_index_path: Path | str, products: list[str] | None = None, *, overwrite: bool = False) -> Dict[str, Path]

Filter per-product Parquet tables down to polygon pixels.

Audience: advanced.

merge_polygon_parquets_for_flightline

merge_polygon_parquets_for_flightline(flight_paths: FlightlinePaths, polygon_index_path: Path | str, product_polygon_parquets: Mapping[str, Path], output_path: Path | str | None = None, *, overwrite: bool = False, row_group_size: int = 25000) -> Path

Merge polygon-filtered Parquet tables into one spectral library.

Audience: advanced.

run_polygon_pipeline_for_flightline

run_polygon_pipeline_for_flightline(flight_paths: FlightlinePaths, polygons_path: str | Path, *, products: list[str] | None = None, reference_product: str = 'brdfandtopo_corrected_envi', overwrite: bool = False) -> Dict[str, object]

Execute the polygon pipeline end-to-end for one flightline.