pycontrails.datalib.sentinel

Support for Sentinel-2 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
DEFAULT_BANDS	Default Sentinel channels to use if none are specified.
GCP_STRIP_PREFIX	Strip this prefix from GCP URLs when caching Sentinel files locally

Functions

extract_sentinel_visualization(ds[, ...])	Extract artifacts for visualizing Sentinel data with the given color scheme.
intersect(flight[, columns])	Find Sentinel-2 imagery intersecting with flight track.
query(start_time, end_time[, extent, columns])	Find Sentinel-2 imagery within spatiotemporal region of interest.
to_true_color(ds)	Compute 3d RGB array for the true color scheme.

Classes

Sentinel(base_url, granule_id[, bands, ...])

Support for Sentinel-2 data handling.

pycontrails.datalib.sentinel.BQ_DEFAULT_COLUMNS = ['base_url', 'granule_id', 'sensing_time', 'source_url']

Default columns to include in queries

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

Default spatial extent for queries

pycontrails.datalib.sentinel.BQ_TABLE = 'bigquery-public-data.cloud_storage_geo_index.sentinel_2_index'

BigQuery table with imagery metadata

pycontrails.datalib.sentinel.DEFAULT_BANDS = ['B02', 'B03', 'B04']

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

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

Strip this prefix from GCP URLs when caching Sentinel files locally

class pycontrails.datalib.sentinel.Sentinel(base_url, granule_id, bands=None, cachestore=None)

Bases: object

Support for Sentinel-2 data handling.

Parameters:

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

• granule_id (str) – Granule ID of Sentinel-2 scene. To find URLs for Sentinel-2 scenes at specific locations and times, see query() and intersect().

• bands (str | Iterable[str] | None) – Set of bands to retrieve. The 13 possible bands are represented by the string “B01” to “B12” plus “B8A”. For the true color scheme, set bands=("B02", "B03", "B04"). By default, bands for the true color scheme are used. Bands must share a common resolution. The resolutions of each band are:

  • B02-B04, B08: 10 m

  • B05-B07, B8A, B11, B12: 20 m

  • B01, B09, B10: 60 m

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

See also

query, intersect

colocate_flight(flight, band='B03')

Colocate a flight track with satellite image pixels.

This function first projects flight waypoints into the UTM coordinate system of the satellite image, then applies a viewing angle correction to estimate the actual ground position imaged by the satellite. Next, the scan time for each point is estimated based on the satellite meta data. Finally, the point along the flight track is found where the flight time matches the satellite scan time.

Parameters:

• flight (Flight) – The flight object.

• band (str, optional) – Spectral band to use for geometry parsing. Default is “B03”.

Returns:

tuple[float, float, np.datetime64] – A tuple containing the x and y coordinates of the flight position in the satellite image CRS, and the corrected sensing_time of the satellite image.

get(reflective='reflectance')

Retrieve Sentinel-2 imagery.

Parameters:

reflective (str, optional) – Set to “raw” to return raw values or “reflectance” for rescaled reflectances. By default, return reflectances.

Returns:

xarray.Dataset – Dataset of Sentinel-2 data.

get_crs()

Return the CRS of the satellite image.

get_detector_id(x, y)

Return the detector_id of the Sentinel-2 detector that imaged the given points.

Parameters:

• x (npt.NDArray[np.floating]) – x coordinates of points in the Sentinel-2 image CRS

• y (npt.NDArray[np.floating]) – y coordinates of points in the Sentinel-2 image CRS

Returns:

npt.NDArray[np.integer] – Detector IDs for each point. If a point is outside the image, the detector ID is 0.

get_ephemeris()

Return the satellite ephemeris as a pandas.DataFrame.

get_sensing_time()

Return the sensing_time of the satellite image.

get_time_delay_detector(detector_id, band='B03')

Return the time delay for the given detector IDs.

get_viewing_angle_metadata(scale=10)

Return the dataset with viewing angles.

See parse_high_res_viewing_incidence_angles() for details.

pycontrails.datalib.sentinel.extract_sentinel_visualization(ds, color_scheme='true')

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

Parameters:

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

• color_scheme (str, optional) – Color scheme to use for visualization. The true color scheme (“true”, the only option currently implemented) requires bands B02, B03, and B04.

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

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

Find Sentinel-2 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] | None, optional) – Columns to return from Google BigQuery table. By default, returns imagery base URL, granule ID, and sensing time.

Returns:

pandas.DataFrame – Query results in pandas DataFrame

See also

search.intersect()

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

Find Sentinel-2 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 | None, optional) – Spatial region of interest as a GeoJSON string. If not provided, defaults to a global extent.

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

Returns:

pandas.DataFrame – Query results in pandas DataFrame

See also

search.query()

pycontrails.datalib.sentinel.to_true_color(ds)

Compute 3d RGB array for the true color scheme.

Parameters:

ds (xarray.Dataset) – DataArray of Sentinel data with bands B02, B03, and B04.

Returns:

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

• src_crs (pyproj.CRS) – Imagery projection