pycontrails.datalib.landsat

Support for LANDSAT 8-9 imagery retrieval through Google Cloud Platform.

Module Attributes

BQ_TABLE	BigQuery table with imagery metadata
BQ_DEFAULT_COLUMNS	Default columns to include in queries
BQ_DEFAULT_EXTENT	Default spatial extent for queries
BQ_EXTRA_FILTERS	Extra filters for BigQuery queries
DEFAULT_BANDS	Default Landsat channels to use if none are specified.
GCP_STRIP_PREFIX	Strip this prefix from GCP URLs when caching Landsat files locally

Functions

extract_landsat_visualization(ds[, color_scheme])	Extract artifacts for visualizing Landsat data with the given color scheme.
intersect(flight[, columns])	Find Landsat 8 and 9 imagery intersecting with flight track.
query(start_time, end_time[, extent, columns])	Find Landsat 8 and 9 imagery within spatiotemporal region of interest.
to_google_contrails(ds)	Compute 3d RGB array for the Google contrails color scheme.
to_true_color(ds)	Compute 3d RGB array for the true color scheme.

Classes

Landsat(base_url[, bands, cachestore])

Support for Landsat 8 and 9 data handling.

pycontrails.datalib.landsat.BQ_DEFAULT_COLUMNS = ['base_url', 'sensing_time']

Default columns to include in queries

pycontrails.datalib.landsat.BQ_DEFAULT_EXTENT = '{"type": "Polygon", "coordinates": [[[-180, -90], [180, -90], [180, 90], [-180, 90], [-180, -90]]]}'

Default spatial extent for queries

pycontrails.datalib.landsat.BQ_EXTRA_FILTERS = 'AND spacecraft_id in ("LANDSAT_8", "LANDSAT_9")'

Extra filters for BigQuery queries

pycontrails.datalib.landsat.BQ_TABLE = 'bigquery-public-data.cloud_storage_geo_index.landsat_index'

BigQuery table with imagery metadata

pycontrails.datalib.landsat.DEFAULT_BANDS = ['B2', 'B3', 'B4']

Default Landsat channels to use if none are specified. These are visible bands for producing a true color composite.

pycontrails.datalib.landsat.GCP_STRIP_PREFIX = 'gs://gcp-public-data-landsat/'

Strip this prefix from GCP URLs when caching Landsat files locally

class pycontrails.datalib.landsat.Landsat(base_url, bands=None, cachestore=None)

Bases: object

Support for Landsat 8 and 9 data handling.

This class uses the PROJ coordinate transformation software through the pyproj python interface. pyproj is installed as part of the sat set of optional dependencies (pip install pycontrails[sat]), but PROJ must be installed manually.

Parameters:

• base_url (str) – Base URL of Landsat scene. To find URLs for Landsat scenes at specific locations and times, see query() and intersect().

• bands (str | set[str] | None) – Set of bands to retrieve. The 11 possible bands are represented by the string “B1” to “B11”. For the Google Landsat contrails color scheme, set bands=("B9", "B10", "B11"). For the true color scheme, set bands=("B2", "B3", "B4"). By default, bands for the true color scheme are used. Bands must share a common resolution. The resolutions of each band are:

  • B1-B7, B9: 30 m

  • B8: 15 m

  • B10, B11: 30 m (upsampled from true resolution of 100 m)

• cachestore (cache.CacheStore, optional) – Cache store for Landsat data. If None, a DiskCacheStore is used.

See also

query, intersect

get(reflective='reflectance', thermal='brightness_temperature')

Retrieve Landsat imagery.

Parameters:

• reflective (str = {"raw", "radiance", "reflectance"}, optional) – Whether to return raw values or rescaled radiances or reflectances for reflective bands. By default, return reflectances.

• thermal (str = {"raw", "radiance", "brightness_temperature"}, optional) – Whether to return raw values or rescaled radiances or brightness temperatures for thermal bands. By default, return brightness temperatures.

Returns:

xarray.DataArray – DataArray of Landsat data.

property reflective_bands

List of reflective bands.

property thermal_bands

List of thermal bands.

pycontrails.datalib.landsat.extract_landsat_visualization(ds, color_scheme='true')

Extract artifacts for visualizing Landsat data with the given color scheme.

Parameters:

• ds (xarray.Dataset) – Dataset of Landsat data as returned by Landsat.get().

• color_scheme (str = {"true", "google_contrails"}) – Color scheme to use for visualization. The true color scheme requires reflectances for bands B2, B3, and B4; and the Google contrails color scheme requires reflectance for band B9 and brightness temperatures for bands B10 and B11.

Returns:

• rgb (npt.NDArray[np.float32]) – 3D RGB array of shape (height, width, 3).

• src_crs (pyproj.CRS) – Imagery projection

• src_extent (tuple[float,float,float,float]) – Imagery extent in projected coordinates

References

[McCloskey et al., 2021]

pycontrails.datalib.landsat.intersect(flight, columns=None)

Find Landsat 8 and 9 imagery intersecting with flight track.

This function will return all scenes with a bounding box that includes flight waypoints both before and after the sensing time.

This function requires access to the Google BigQuery API and uses the BigQuery python library.

Parameters:

• flight (Flight) – Flight for intersection

• columns (list[str], optional.) – Columns to return from Google BigQuery table. By default, returns imagery base URL and sensing time.

Returns:

pandas.DataFrame – Query results in pandas DataFrame

See also

search.intersect()

pycontrails.datalib.landsat.query(start_time, end_time, extent=None, columns=None)

Find Landsat 8 and 9 imagery within spatiotemporal region of interest.

This function requires access to the Google BigQuery API and uses the BigQuery python library.

Parameters:

• start_time (numpy.datetime64) – Start of time period for search

• end_time (numpy.datetime64) – End of time period for search

• extent (str, optional) – Spatial region of interest as a GeoJSON string. If not provided, defaults to a global extent.

• columns (list[str], optional.) – Columns to return from Google BigQuery table. By default, returns imagery base URL and sensing time.

Returns:

pandas.DataFrame – Query results in pandas DataFrame

See also

search.query()

pycontrails.datalib.landsat.to_google_contrails(ds)

Compute 3d RGB array for the Google contrails color scheme.

Parameters:

ds (xarray.Dataset) – DataArray of Landsat data with reflectance for band B9 and brightness temperature for bands B10 and B11.

Returns:

• numpy.ndarray – 3d RGB array with Google landsat color scheme.

• src_crs (pyproj.CRS) – Imagery projection

References

• Google human-labeled Landsat contrails dataset

• [McCloskey et al., 2021]

pycontrails.datalib.landsat.to_true_color(ds)

Compute 3d RGB array for the true color scheme.

Parameters:

ds (xarray.Dataset) – DataArray of Landsat data with reflectances for bands B2, B3, and B4.

Returns:

• numpy.ndarray – 3d RGB array with true color scheme.

• src_crs (pyproj.CRS) – Imagery projection