API reference

xsar.open_dataset(*args, **kwargs)
Parameters

  • *args – Passed to xsar.SentinelDataset

  • **kwargs – Passed to xsar.SentinelDataset

Return type

xarray.Dataset

Notes

xsar.open_dataset` is a simple wrapper to xsar.SentinelDataset that directly returns the xarray.Dataset object.

>>> xsar.Sentinel1Dataset(*args, **kwargs).dataset

See also

xsar.Sentinel1Dataset

xsar.product_info(path, columns='minimal', include_multi=False, _xml_parser=None)
Parameters

  • path (str or iterable of str) – path or gdal url.

  • columns (list of str or str, optional) – ‘minimal’ by default: only include columns from attributes found in manifest.safe. Use ‘spatial’ to have ‘time_range’ and ‘geometry’. Might be a list of properties from xsar.Sentinel1Meta

  • include_multi (bool, optional) – False by default: don’t include multi datasets

Returns

One dataset per lines, with info as columns

Return type

geopandas.GeoDataFrame

See also

xsar.Sentinel1Meta

class xsar.Sentinel1Meta(name, _xml_parser=None)

Handle dataset metadata. A xsar.Sentinel1Meta object can be used with xsar.open_dataset, but it can be used as itself: it contains usefull attributes and methods.

Parameters

name (str) – path or gdal identifier like ‘SENTINEL1_DS:%s:WV_001’ % path

path = None

Dataset path

safe = None

Safe file name

name = None

Gdal dataset name

dsid = None

Dataset identifier (like ‘WV_001’, ‘IW1’, ‘IW’), or empty string for multidataset

short_name = None

Like name, but without path

subdatasets = None

Subdatasets as GeodataFrame (empty if single dataset)

multidataset = None

True if multi dataset

platform = None

Mission platform

rasters = Empty DataFrame Columns: [resource, read_function, get_function] Index: []

pandas dataframe for rasters (see xsar.Sentinel1Meta.set_raster)

have_child(name)

Check if dataset name belong to this Sentinel1Meta object.

Parameters

name (str) – dataset name

Return type

bool

property orbit_pass

Orbit pass, i.e ‘Ascending’ or ‘Descending’

property platform_heading

Platform heading, relative to north

property safe_files

Files and polarizations for whole SAFE. The index is the file number, extracted from the filename. To get files in official SAFE order, the resulting dataframe should be sorted by polarization or index.

Returns

with columns:

  • index : file number, extracted from the filename.

  • dsid : dataset id, compatible with gdal sentinel1 driver (‘SENTINEL1_DS:/path/file.SAFE:WV_012’)

  • polarization : polarization name.

  • annotation : xml annotation file.

  • calibration : xml calibration file.

  • noise : xml noise file.

  • measurement : tiff measurement file.

Return type

pandas.Dataframe

See also

xsar.Sentinel1Meta.files

property files

Files for current dataset. (Empty for multi datasets)

See also

xsar.Sentinel1Meta.safe_files

property footprint

footprint, as a shapely polygon or multi polygon

property geometry

alias for footprint

property geoloc

xarray.Dataset with [‘longitude’, ‘latitude’, ‘altitude’, ‘azimuth_time’, ‘slant_range_time’,’incidence’,’elevation’ ] variables and [‘line’, ‘sample’] coordinates, at the geolocation grid

classmethod set_mask_feature(name, feature)

Set a named mask from a shapefile or a cartopy feature.

Parameters

  • name (str) – mask name

  • feature (str or cartopy.feature.Feature) – if str, feature is a path to a shapefile or whatever file readable with fiona. It is recommended to use str, as the serialization of cartopy feature might be big.

Examples

Add an ‘ocean’ mask at class level (ie as default mask): ` >>> xsar.Sentinel1Meta.set_mask_feature('ocean', cartopy.feature.OCEAN) `

Add an ‘ocean’ mask at instance level (ie only for this self Sentinel1Meta instance): ` >>> xsar.Sentinel1Meta.set_mask_feature('ocean', cartopy.feature.OCEAN) `

High resoltion shapefiles can be found from openstreetmap. It is recommended to use WGS84 with large polygons split from https://osmdata.openstreetmap.de/

See also

xsar.Sentinel1Meta.get_mask

property mask_names

returns: mask names :rtype: list of str

get_mask(name, describe=False)

Get mask from name (e.g. ‘land’) as a shapely Polygon. The resulting polygon is contained in the footprint.

Parameters

name (str) –

Return type

shapely.geometry.Polygon

property coverage

coverage, as a string like ‘251km * 170km (sample * line )’

property pixel_line_m

pixel line spacing, in meters (at sensor level)

property pixel_sample_m

pixel sample spacing, in meters (at sensor level)

property time_range

time range as pd.Interval

property start_date

start date, as datetime.datetime

property stop_date

stort date, as datetime.datetime

property denoised

dict with pol as key, and bool as values (True is DN is predenoised at L1 level)

property ipf

ipf version

property swath

string like ‘EW’, ‘IW’, ‘WV’, etc …

property pols

polarisations strings, separated by spaces

property cross_antemeridian

True if footprint cross antemeridian

property orbit
orbit, as a geopandas.GeoDataFrame, with columns:

  • ‘velocity’ : shapely.geometry.Point with velocity in x, y, z direction

  • ‘geometry’ : shapely.geometry.Point with position in x, y, z direction

crs is set to ‘geocentric’

attrs keys:

  • ‘orbit_pass’: ‘Ascending’ or ‘Descending’

  • ‘platform_heading’: in degrees, relative to north

Notes

orbit is longer than the SAFE, because it belongs to all datatakes, not only this slice

property azimuth_fmrate

xarray.Dataset Frequency Modulation rate annotations such as t0 (azimuth time reference) and polynomial coefficients: Azimuth FM rate = c0 + c1(tSR - t0) + c2(tSR - t0)^2

coords2ll(*args, to_grid=False, approx=False)

convert lines, samples arrays to longitude and latitude arrays. or a shapely object in lines, samples coordinates to longitude and latitude.

Parameters

  • *args (lines, samples or a shapely geometry) – lines, samples are iterables or scalar

  • to_grid (bool, default False) – If True, lines and samples must be 1D arrays. The results will be 2D array of shape (lines.size, samples.size).

Returns

(longitude, latitude) , with shape depending on to_grid keyword.

Return type

tuple of np.array or tuple of float

See also

xsar.Sentinel1Meta.ll2coords, xsar.Sentinel1Dataset.ll2coords

ll2coords(*args)

Get (lines, samples) from (lon, lat), or convert a lon/lat shapely shapely object to line/sample coordinates.

Parameters

*args (lon, lat or shapely object) – lon and lat might be iterables or scalars

Return type

tuple of np.array or tuple of float (lines, samples) , or a shapely object

Examples

get nearest (line,sample) from (lon,lat) = (84.81, 21.32) in ds, without bounds checks

>>> (line, sample) = meta.ll2coords(84.81, 21.32) # (lon, lat)
>>> (line, sample)
(9752.766349989339, 17852.571322887554)

See also

xsar.Sentinel1Meta.coords2ll, xsar.Sentinel1Dataset.coords2ll

coords2heading(lines, samples, to_grid=False, approx=True)

Get image heading (lines increasing direction) at coords lines, samples.

Parameters

  • lines (np.array or scalar) –

  • samples (np.array or scalar) –

  • to_grid (bool) – If True, lines and samples must be 1D arrays. The results will be 2D array of shape (lines.size, samples.size).

Returns

heading , with shape depending on to_grid keyword.

Return type

np.array or float

property approx_transform

Affine transfom from geoloc.

This is an inaccurate transform, with errors up to 600 meters. But it’s fast, and may fit some needs, because the error is stable localy. See xsar.Sentinel1Meta.coords2ll xsar.Sentinel1Meta.ll2coords for accurate methods.

Examples

get longitude and latitude from tuple (line, sample):

>>> longitude, latitude = self.approx_transform * (line, sample)

get line and sample from tuple (longitude, latitude)

>>> line, sample = ~self.approx_transform * (longitude, latitude)

See also

xsar.Sentinel1Meta.coords2ll, xsar.Sentinel1Meta.ll2coords

get_annotation_definitions()
Returns

class xsar.Sentinel1Dataset(dataset_id, resolution=None, resampling=Resampling.rms, luts=False, chunks={'line': 5000, 'sample': 5000}, dtypes=None, patch_variable=True)

Handle a SAFE subdataset. A dataset might contain several tiff files (multiples polarizations), but all tiff files must share the same footprint.

The main attribute useful to the end-user is self.dataset (xarray.Dataset , with all variables parsed from xml and tiff files.)

Parameters

  • dataset_id (str or Sentinel1Meta object) – if str, it can be a path, or a gdal dataset identifier like ‘SENTINEL1_DS:%s:WV_001’ % filename)

  • resolution (dict, number or string, optional) –

    resampling dict like {‘line’: 20, ‘sample’: 20} where 20 is in pixels.

    if a number, dict will be constructed from {‘line’: number, ‘sample’: number}

    if str, it must end with ‘m’ (meters), like ‘100m’. dict will be computed from sensor pixel size.

  • resampling (rasterio.enums.Resampling or str, optional) –

    Only used if resolution is not None.

    ` rasterio.enums.Resampling.rms` by default. rasterio.enums.Resampling.nearest (decimation) is fastest.

  • luts (bool, optional) – if True return also luts as variables (ie sigma0_lut, gamma0_lut, etc…). False by default.

  • chunks (dict, optional) – dict with keys [‘pol’,’line’,’sample’] (dask chunks).

  • dtypes (None or dict, optional) – Specify the data type for each variable.

  • patch_variable (bool, optional) – activate or not variable pathching ( currently noise lut correction for IPF2.9X)

s1meta

xsar.Sentinel1Meta object

sliced

True if dataset is a slice of original L1 dataset

resampled

True if dataset is not a sensor resolution

add_high_resolution_variables(luts=False, patch_variable=True)

:parameter luts: bool, optional

if True return also luts as variables (ie sigma0_lut, gamma0_lut, etc…). False by default.

patch_variable: bool, optional

activate or not variable pathching ( currently noise lut correction for IPF2.9X)

apply_calibration_and_denoising()

apply calibration and denoising functions to get high resolution sigma0 , beta0 and gamma0 + variables *_raw :return:

property dataset

xarray.Dataset representation of this xsar.Sentinel1Dataset object. This property can be set with a new dataset, if the dataset was computed from the original dataset.

property geometry

geometry of this dataset, as a shapely.geometry.Polygon (lon/lat coordinates)

property footprint

alias for xsar.Sentinel1Dataset.geometry

ll2coords(*args)

Get (lines, samples) from (lon, lat), or convert a lon/lat shapely shapely object to line/sample coordinates.

Parameters

*args (lon, lat or shapely object) – lon and lat might be iterables or scalars

Return type

tuple of np.array or tuple of float (lines, samples) , or a shapely object

Notes

The difference with xsar.Sentinel1Meta.ll2coords is that coordinates are rounded to the nearest dataset coordinates.

See also

xsar.Sentinel1Meta.ll2coords

coords2ll(*args, **kwargs)

Alias for xsar.Sentinel1Meta.coords2ll

See also

xsar.Sentinel1Meta.coords2ll

property len_line_m

line length, in meters

property len_sample_m

sample length, in meters

property pixel_line_m

line pixel spacing, in meters (relative to dataset)

property pixel_sample_m

sample pixel spacing, in meters (relative to dataset)

property coverage

coverage string

recompute_attrs()

Recompute dataset attributes. It’s automaticaly called if you assign a new dataset, for example

>>> xsar_obj.dataset = xsar_obj.dataset.isel(line=slice(1000,5000))
>>> #xsar_obj.recompute_attrs() # not needed

This function must be manually called before using the .rio accessor of a variable

>>> xsar_obj.recompute_attrs()
>>> xsar_obj.dataset['sigma0'].rio.reproject(...)
map_raster(raster_ds)

Map a raster onto xsar grid

Parameters

raster_ds (xarray.Dataset or xarray.DataArray) – The dataset we want to project onto xsar grid. The raster_ds.rio accessor must be valid.

Returns

The projected dataset, with ‘line’ and ‘sample’ coordinate (same size as xsar dataset), and with valid .rio accessor.

Return type

xarray.Dataset or xarray.DataArray

reverse_calibration_lut(ds_var)

TODO: replace ds_var by var_name Inverse of _apply_calibration_lut : from var_name, reverse apply lut, to get digital_number. See official ESA documentation . > Level-1 products provide four calibration Look Up Tables (LUTs) to produce ß0i, σ0i and γi > or to return to the Digital Number (DN)

A warning message may be issued if original complex ‘digital_number’ is converted to module during this operation.

Parameters

ds_var (xarray.Dataset) – with only one variable name that must exist in self._map_var_lut to be able to reverse the lut to get digital_number

Returns

with one variable named ‘digital_number’.

Return type

xarray.Dataset

property get_burst_azitime

Get azimuth time at high resolution.

Returns

the high resolution azimuth time vector interpolated at the middle of the sub-swath

Return type

xarray.DataArray

get_burst_valid_location()

add a field ‘valid_location’ in the bursts sub-group of the datatree :return:

get_bursts_polygons(only_valid_location=True)

get the polygons of radar bursts in the image geometry

Parameters

only_valid_location (bool) – [True] -> polygons of the TOPS SLC bursts are cropped using valid location index False -> polygons of the TOPS SLC bursts are aligned with azimuth time start/stop index

Returns

polygons of the burst in the image (ie line/sample) geometry ‘geometry’ is the polygon

Return type

geopandas.GeoDataframe