Raw

Table of contents

class raw.raw_event.Raw_event(granules_collection=None, bands_names=None, event_class=None, raw_useful_granules_idx=None, raw_complementary_granules_idx=None, useful_granule_bounding_box_dict=None, device=device(type='cpu'))

Creates an raw event from a granules collection and band_names. It is possible to associate an image class to the event.

Parameters:

• granules_collection (list, optional) – list of Raw_granule. Defaults to None.

• bands_names (list, optional) – list of band names. Defaults to None.

• event_class (string, optional) – class name. Defaults to None.

• raw_useful_granules_idx (list, optional) – list of useful granules indices. Defaults to None.

• raw_complementary_granules_idx (list, optional) – list of complementary granules indices. Defaults to None.

• useful_granule_bounding_box_dict (dict, optional) – {useful granule : bounding boxes}. Defaults to None.

• device (torch.device, optional) – device for each raw granule in the image. Defaults to torch.device(“cpu”).

coarse_coregistration(granules_idx=None, use_complementary_granules=False, crop_empty_pixels=False, downsampling=True, bands_shifts=None, verbose=False)

It implements the coarse coregistration of the bands by compensating the along-track pixels shift with respect to the first band.

Parameters:

• granules_idx (list, optional) – Indices of granules to stack and coregister. If None, internal __raw_useful_granules_idx are used. Defaults to None.

• use_complementary_granules (boolean, optional) – if True, coregistration is performed with filler elements. Defaults to False.

• crop_empty_pixels (boolean, optional) – if True and use_complementary_granules is False or no filler is available, empty pixels are cropped. Defaults to False.

• bands_shifts (list, optional) – bands shift values compared to the first band. If None, they will be read by the LUT file. Defaults to None.

• downsampling (boolean, optional) –

  if True, higher resolution bands will be undersampled

  to match the bands with the lowest resolution. If False, lower resolution bands will be upsampled to match the bands

  with the highest resolution. Defaults to True.

• verbose (boolean, optional) – if True, verbose mode is used. Defaults to False.

Returns:

granule with coarse-coregistered bands.

Return type:

Raw_granule

from_database(id_event, bands_list=None, cfg_file_dict=None, id_raw_l1_dict=None, verbose=True, database='THRAWS')

Read specific bands of the Sentinel-2 raw event “”id_event””, specified in “bands_list”, from database.

Parameters:

• id_event (str) – event ID.

• bands_list (list, optional) – bands list. If None, all bands are used and sorted according to the datasheet order. Defaults to None.

• cfg_file_dict (dict, optional) – dictionary containing paths to the different end2end directories. If None, internal CSV database will be parsed.

• id_raw_l1_dict (dict, optional) – id-raw-l1 dictionary. If None, internal CSV database will be parsed.

• verbose (bool, optional) – if True, if True, verbose mode is used. Defaults to True.

• database (string, optional) – database name. Defaults to “THRAWS”.

from_path(raw_dir_path, bands_list, verbose=True)

Read specific bands of the Sentinel-2 raw event located at “”raw_dir_path””.

Parameters:

• raw_dir_path (str) – path to the raw event dir.

• None (bands list. If) –

• None. (all bands are used and sorted according to the datasheet order. Defaults to) –

• verbose (bool, optional) – if True, if True, verbose mode is used. Defaults to True.

get_bands_list()

Returns the list of bands of every Raw_granule object in the collection.

Returns:

band names.

Return type:

list

get_bounding_box_dict()

Get bounding box dictionaries.

Returns:

Returns {useful granules : bounding box dictionary}

Return type:

dict

get_complementary_granules_idx()

Returns complementary granules indices.

Returns:

complementary granules indices.

Return type:

list

get_event_class()

Get event class.

Returns:

Returns {useful granules : bounding box dictionary}

Return type:

dict

get_granule(granule_idx)

It returns the granule addressed by granule_idx.

Parameters:

granule_idx (int) – granule index.

get_granules_info(granules_idx=None)

Return info of the granules requested through granules_idx from granules names.

Parameters:

granules_idx (list, optional) – list of granules for which getting the names. If None, all the names of the granules in the collection are returned. Defaults to None.

Raises:

ValueError – Empty granules lists

Returns:

granules name : granules info

Return type:

dictionary

get_granules_names(granules_idx=None)

Return names of the granules requested through granules_idx from granules names.

Parameters:

granules_idx (list, optional) – list of granules for which getting the names. If None, all the names of the granules in the collection are returned. Defaults to None.

Raises:

ValueError – Empty granules lists

Returns:

granules’ names.

Return type:

list

get_stackable_granules()

Returns list of stackable granules couples indices and stacking positions.

Returns:

list of stackable granules couples. list: stacking poisition for each couple of stackable granule.

Return type:

list

get_useful_granules_idx()

Returns useful granules indices.

Returns:

useful granules indices.

Return type:

list

is_void()

Returns true if the image is void.

Returns:

True if the image is void.

Return type:

bool

set_complementary_granules(complementary_granules)

useful_granules_list (list): Set useful granules from list.

set_useful_granules(useful_granules_list)

useful_granules_list (list): Set useful granules from list.

show_granules_info()

Print granules info.

stack_granules(granules_idx, positions)

Stack different granules recursively specified by granules_idx. Positions will specify the stacking positions. If granules_idx=[0,1,2] and positions=[“T”, “B”], granule_0 will be stacked at the top of granule_1 and the result will be stacked at the bottom of granule_2.

Parameters:

• granules_idx (list) – list of granule indices.

• positions (list) – list of stacking positions.

Returns:

recursively stacked granule.

Return type:

Raw_granule

stack_granules_couples()

Stacks automatically couples of granules by detector number and sensing time.

Returns:

stacked couples of granules list: indidces of couples of granules

Return type:

list

class raw.raw_granule.Raw_granule(granule_bands=None, bands_names=None, granule_name=None, granule_polygon_coordinates=None, single_granule_along_track_size=None, cloud_percentage=None, device=device(type='cpu'))

Initialize an raw granule.

Parameters:

• granule_bands (list, optional) – list of torch tensors representing each band in the format [H,W]. Defaults to None.

• bands_names (list, optional) – list of band names. Defaults to None.

• granule_name (string, optionl) – granule name. Defaults to None.

• granule_polygon_coordinates (list, optional) – list containing [lat, lon] for every polygon point. Defaults to None.

• single_granule_along_track_size (float, optional) – size of a single granule along track. Useful to keep this info when the granule has parents. Defaults to None.

• cloud_percentage (list or float, optional) – Cloud coverage percentage metadata. Defaults to None.

• device (torch.device, optional) – torch.device. Defaults to torch.device(“cpu”).

as_tensor(requested_bands=None, downsampling=True)

Returns a tensor containing all the bands if all the requested bands have the same resolution.

Parameters:

• requested_bands (list, optional) – list of requested bands. If None, all the bands are used. Defaults to None.

• downsampling (boolean, optional) – if True, bands are downsampled to the lowest resolution. Otherwise, they are upsampled to the highest one. Defaults to True.

Raises:

ValueError – The granule is empty

Returns:

tensor containing the requested bands.

Return type:

torch.tensor

check_bands_size(requested_bands)

Checks if the requested bands have the same size

Parameters:

requested_bands (list) – list of requested bands

Returns:

return True if all the requested bands have the same size. It returns False, otherwise.

Return type:

boolean

coarse_coregistration(rotate_swir_bands=True, granule_filler_before=None, granule_filler_after=None, crop_empty_pixels=False, downsampling=True, bands_shifts=None, verbose=False)

It implements the coarse coregistration of the bands by compensating the along-track pixels shift with respect to the first band.

Parameters:

• rotate_swir_bands (boolean, optional) – if True, SWIR bands are rotated before applying coregistration. Defaults to True.

• granule_filler_before (Raw_granule, optional) – if not None, bands of this tile will be used to fill the missing elements during the coregistration as before granule. Defaults to None.

• granule_filler_after (Raw_granule, optional) – if not None, bands of this tile will be used to fill the missing elements during the coregistration as bottom granule. Defaults to None.

• crop_empty_pixels (boolean, optional) – if True and no fillers are available or granule fillers are None, the image will be crop at the bottom and the top of a number of pixels equal to the maximum zeros pixels stacked from each band.

• downsampling (boolean, optional) – if True, higher resolution bands will be undersampled to match the bands with the lowest resolution. If False, lower resolution bands will be upsampled to match the bands with the highest resolution. Defaults to True.

• bands_shifts (list, optional) – bands shift values compared to the first band. If None, they will be read by the LUT file. Defaults to None.

• verbose (boolean, optional) – if True, verbose mode is used. Defaults to False.

Returns:

granule with coarse-coregistered bands.

Return type:

Raw_granule

create_granule(bands_list, granule_bands, granule_name, polygon_coordinates, single_granule_along_track_size, cloud_percentage)

Creates a granule from the list of bands and from a torch tensor.

Parameters:

• bands_list (list) – list of band names.

• granule_bands (list) – list of torch.tensors (bands) in format [H,W]

• granule_name (str) – granule name.

• polygon_coordinates (list) – list of [lan, lon] coordinates for every polygon point.

• single_granule_along_track_size (float) – along track size for a single granule.

• cloud_percentage (float or list) – cloud percentage.

export_to_tif(save_path)

Export to TIF file.

Parameters:

• save_path (str) – save path.

• downsampling (bool, optional) – If True, bands are downsampled. Defaults to True.

get_across_track_size()

Returns across track size.

Returns:

across track size

Return type:

float

get_along_track_size()

Returns along track size.

Returns:

along track size.

Return type:

float

get_band(band_name)

Returns a specific band as a tensor.

Parameters:

band_name (string) – band name

Returns:

requested band.

Return type:

torch.tensor

get_bands_coordinates(downsampling=True, latlon_format=True)

Returns the coordinates of the bands. :param downsampling: if True, bands are downsampled to have the same resolution.

Default to False.

Parameters:

latlon_format (bool) – format to use to get the granule’s coordinates. Default to: Latitude, Longitude.

Returns:

band-names/band coordinates dict.

Return type:

dict

get_cloud_percentage()

Returns cloud percentage.

Returns:

cloud percentage.

Return type:

list

get_detectors_number()

Returns the detector numbers list.

Returns:

List of detector numbers.

Return type:

list

get_granule_coordinates(latlon_format=True)

Returns the granule’s coordinates.

Parameters:

latlon_format (bool) – format to use to get the granule’s coordinates. Default to: Latitude, Longitude

Returns:

polygon coordinates.

Return type:

list

get_granule_info()

Returns name, sensing time, acquisition time, detector number information, originality, parents list, polygon coordinates list, cloud percentages. If the granule have parents, sensing time, acquisition time, detector number of parents, and cloud percentages are returned.

Returns:

name list of datetime: list of sensing time. list of datetime: acquisition time. list of int: detector numbers. boolean: originality list: parents_list. list: polygon coordinates. list: granules percentages.

Return type:

string

get_number_of_granules_along_track_line()

Returns the maximum number of granules stacked along track among parents.

Returns:

Number of granules correctly stacked (same detector number and correct sensing time difference) along track.

Return type:

int

get_parents()

Set granule parents from parents list

Returns:

parents list.

Return type:

list

get_raw_bbox(l1c_tif, bbox, mode='standard')

Changing bbox coordinates from green system (L1C) to raw.

Parameters:

• l1c_tif – tensor of the l1c image

• bbox – (list): [x_top_left, y_top_left, x_bottom_right, y_bottom_right]

Ret:

list: corrected bbox list

get_single_granule_along_track_size()

Retuns single granule along track size.

Returns:

single ganule along track size

Return type:

float

is_original()

It shows if the granule is original. :returns: originality. :rtype: boolean

rotate_band(requested_band)

Rotates one band of 180 degrees.

Parameters:

requested_band (string) – band name.

show_bands(requested_bands=None, downsampling=False, oversampling=False, rotate_swir_bands=False)

It shows the requested bands.

Parameters:

• requested_bands (list, optional) – list of requested bands to show. If None, all the bands are shown. Defaults to None.

• downsampling (bool, optional) – if True, bands are downsampled to have the same resolution. Default to False.

• oversampling (bool, optional) – if True, bands are oversampled to have the same resolution. Downsampling has priority over upampling. Default to False.

• rotate_swir_bands (bool, optional) – if True, SWIR bands are rotated. Default to False.

show_bands_superimposition(requested_bands=None, downsampling=True, equalize=False, n_std=2)

It shows the superimposition of bands in requested_bands

Parameters:

• requested_bands (list, optional) – requested bands list. If None, all the bands are used. Defaults to None.

• downsampling (boolean, optional) – if True, bands are downsampled to have the same resolution. Default to False.

• equalize (boolean, optional) – if True, bands are equalized for a better plotting by saturating the outliers of each band with an upper and lower valuer respectively equal to pixel value mean *- n_std * histogram standard deviation. Default to False.

• n_std (integer, optional) – number of times the value of the pixel values standard deviation used for histogram cropping. Defaults to 2.

Raises:

ValueError – Impossible to superimpose more than 3 bands

show_granule_info()

Print granule info.

show_raw_band(band_name)

Show a granule band specified by band_name.

Parameters:

band_name (string) – band_name

Raises:

• ValueError – Impossible to show the requested band: band_name

• ValueError – The requested granule is void.

stack_to_granule(granule_other, position)

It stacks the granule to another input granule to a specificied position. For instance, if position == “”T””, the granule will be stacked at the top of the “”granule_other””.

Parameters:

• granule_other (Raw_granule) – other granule to which the input granule will be stacked to.

• position (string) – Stacking poistion. Only [“”T””, “”B””, “”R””, “”L””] are supported.

Raises:

• ValueError – The granule is void.

• ValueError – Impossible to stack granules. Granules have different bands.

• ValueError – Only the following stacking positions are supported: [“”T””, “”B””, “”R””, “”L””].

Returns:

stacked granule

Return type:

Raw_granule