pycontrails.datalib.leo_utils.sentinel_metadata¶

Download and parse Sentinel metadata.

Functions

`extrapolate_array`(array)	Extrapolate NaN values in a 2D azimuth array using linear interpolation/extrapolation.
`get_detector_id`(detector_band_metadata_path, ...)	Return the detector ID that captured a given pixel in a Sentinel-2 image.
`get_time_delay_detectors`(datastrip_metadata_path)	Return the time delay for a given detector.
`gps_to_utc`(gps_time)	Convert GPS time (datetime object) to UTC time.
`parse_ephemeris_sentinel`(datatsrip_metadata_path)	Return the ephemeris data from the DATASTRIP xml file.
`parse_high_res_detector_mask`(metadata_path)	Load in the detector mask from either JP2 or GML file.
`parse_high_res_viewing_incidence_angles`(...)	Parse high-resolution viewing incidence angles (zenith and azimuth).
`parse_sensing_time`(granule_metadata_path)	Parse the sensing_time in the granule metadata.
`parse_sentinel_crs`(granule_metadata_path)	Parse the CRS in the granule metadata.
`parse_viewing_incidence_angle_by_detector`(...)	Read sensor incidence angles from metadata.
`parse_viewing_incidence_angles`(metadata_path)	Read sensor incidence angles from metadata.
`process_pixel`(pixel_val, pixel_location, ...)	Map a pixel value and location to an azimuth value.
`read_image_coordinates`(meta, band)	Read image x and y coordinates.

pycontrails.datalib.leo_utils.sentinel_metadata.extrapolate_array(array)¶: Extrapolate NaN values in a 2D azimuth array using linear interpolation/extrapolation.

pycontrails.datalib.leo_utils.sentinel_metadata.get_detector_id(detector_band_metadata_path, tile_metadata_path, x, y, band='B03')¶

Return the detector ID that captured a given pixel in a Sentinel-2 image.

Parameters:

detector_band_metadata_path (str) – Path to the MSK_DETFOO_Bxx.jp2 detector band mask file.
tile_metadata_path (str) – Path to the tile metadata XML file (MTD_TL.xml) containing image geometry.
x (npt.NDArray[np.floating]) – X coordinate (in UTM coordinate system) of the target pixel.
y (npt.NDArray[np.floating]) – Y coordinate (in UTM coordinate system) of the target pixel.
band (str, optional) – Spectral band to use for geometry parsing. Default is “B03”.

Returns:

npt.NDArray[np.integer] – The detector ID (in the range 1 to 12) that captured the pixel. Returns 0 if the pixel is outside the image bounds or not covered by any detector.

pycontrails.datalib.leo_utils.sentinel_metadata.get_time_delay_detectors(datastrip_metadata_path, band='B03')¶

Return the time delay for a given detector.

Detector id’s are positioned in alternating viewing angle.

Even detectors capture earlier, odd detectors later. Check page 41: https://sentiwiki.copernicus.eu/__attachments/1692737/S2-PDGS-CS-DI-PSD%20-%20S2%20Product%20Specification%20Document%202024%20-%2015.0.pdf?inst-v=e48c493c-f3ee-4a19-8673-f60058308b2a.

This function checks the DATASTRIP xml to find the reference times used for intializing the offset. Currently it calculates the average time for a certain band_id, and then returns the offset between the detector_id time and the average time. (Unsure whether average is actually correct usage)

Parameters:

datastrip_metadata_path (str) – The location of the DATASTRIP xml file
band (str, optional) – Spectral band to use for geometry parsing. Default is “B03”.

Returns:

dict[int, pd.Timedelta] – Time offset for each detector ID (1 to 12) as a dictionary.

pycontrails.datalib.leo_utils.sentinel_metadata.gps_to_utc(gps_time)¶

Convert GPS time (datetime object) to UTC time.

https://gssc.esa.int/navipedia/index.php/Transformations_between_Time_Systems

pycontrails.datalib.leo_utils.sentinel_metadata.parse_ephemeris_sentinel(datatsrip_metadata_path)¶

Return the ephemeris data from the DATASTRIP xml file.

Parameters:: datatsrip_metadata_path (str) – The location of the DATASTRIP xml file
Returns:: pandas.DataFrame – A pandas.DataFrame containing the ephemeris track with columns: - EPHEMERIS_TIME: Timestamps of the ephemeris data. - EPHEMERIS_ECEF_X: ECEF X coordinates. - EPHEMERIS_ECEF_Y: ECEF Y coordinates. - EPHEMERIS_ECEF_Z: ECEF Z coordinates.

pycontrails.datalib.leo_utils.sentinel_metadata.parse_high_res_detector_mask(metadata_path, scale=10)¶

Load in the detector mask from either JP2 or GML file.

JP2: Reads pixel-level mask indicating which detector [1-12] captured each pixel.
GML: Converts detector polygons to raster mask, where each pixel corresponds to a detector ID.

Lower the resolution with ‘scale’ to speed up processing. Scale 1 -> 10m resolution. Scale 10 -> 100m resolution.

Parameters:

metadata_path (str) – Path to metadata file (.jp2 or .gml).
scale (int) – Factor by which to lower the resolution.

Returns:

npt.NDArray[np.integer] – 2D array of detector IDs (1 to 12), shape (height, width).

pycontrails.datalib.leo_utils.sentinel_metadata.parse_high_res_viewing_incidence_angles(tile_metadata_path, detector_band_metadata_path, scale=10)¶

Parse high-resolution viewing incidence angles (zenith and azimuth).

Parameters:

tile_metadata_path (str) – Path to the tile-level metadata file (usually MTD_TL.xml).
detector_band_metadata_path (str) – Path to the detector-specific metadata file (e.g., MTD_DETFOO_B03.jp2).
scale (int, optional) – Desired resolution scale (default is 10, e.g., 10 for 10m resolution).

Returns:

xarray.Dataset – Dataset with coordinates (‘y’, ‘x’) containing: - VZA: View Zenith Angle - VAA: View Azimuth Angle

Raises:

ValueError – If required data (zenith or azimuth) cannot be parsed.

pycontrails.datalib.leo_utils.sentinel_metadata.parse_sensing_time(granule_metadata_path)¶: Parse the sensing_time in the granule metadata.

pycontrails.datalib.leo_utils.sentinel_metadata.parse_sentinel_crs(granule_metadata_path)¶: Parse the CRS in the granule metadata.

pycontrails.datalib.leo_utils.sentinel_metadata.parse_viewing_incidence_angle_by_detector(metadata_path, target_detector_id, target_band_id='2')¶

Read sensor incidence angles from metadata.

Parameters:

metadata_path (str) – Path to the XML file containing TILE metadata.
target_detector_id (str) – Target Detector_ID.
target_band_id (str) – Starts from 0 (e.g. band 2 (blue) = band_id “1”)

Returns:

tuple[np.ndarray, np.ndarray] – Zenith Angles, Azimuth Angles ((23x23) numpy arrays)

pycontrails.datalib.leo_utils.sentinel_metadata.parse_viewing_incidence_angles(metadata_path, target_band_id='2')¶

Read sensor incidence angles from metadata. Returns the total of all detectors.

Parameters:

metadata_path (str) – Path to the XML file containing TILE metadata.
target_band_id (str) – Starts from 0 (e.g. band 2 (blue) = band_id “1”)

Returns:

tuple[np.ndarray, np.ndarray] – Zenith Angles, Azimuth Angles ((23x23) numpy array)

pycontrails.datalib.leo_utils.sentinel_metadata.process_pixel(pixel_val, pixel_location, image_shape, azimuth_dict)¶: Map a pixel value and location to an azimuth value.

pycontrails.datalib.leo_utils.sentinel_metadata.read_image_coordinates(meta, band)¶: Read image x and y coordinates.