API reference

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

  • *args – Passed to xsar.SentinelDataset

  • **kwargs – Passed to xsar.SentinelDataset

Returns

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, driver='GTiff', _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, driver='GTiff')

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

Parameters

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

driver

GDAL driver used. (‘auto’ for SENTINEL1, or ‘GTiff’)

path

Dataset path

safe

Safe file name

product

Product type, like ‘GRDH’, ‘SLC’, etc ..

name

Gdal dataset name

dsid

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

short_name

Like name, but without path

subdatasets

Subdatasets list (empty if single dataset)

multidataset

True if multi dataset

platform

Mission platform

have_child(name)

Check if dataset name belong to this Sentinel1Meta object.

Parameters

name (str) – dataset name

Returns

Return type

bool

property orbit_pass

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

property platform_heading

Platform heading, relative to north

property rio

get rasterio.io.DatasetReader object. This object is usefull to get image height, width, shape, etc… See rasterio doc for more infos.

See also

rasterio.io.DatasetReader

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 gcps

get gcps from self.rio

Returns

xarray.DataArray with atracks/xtracks coordinates, and gcps as values. attrs is a dict with keys [‘footprint’, ‘coverage’, ‘pixel_atrack_m’, ‘pixel_xtrack_m’ ]

Return type

xarray.DataArray

property footprint

footprint, as a shapely polygon or multi polygon

property geometry

alias for footprint

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.

Examples

Add an ‘ocean’ mask: ` >>> self.set_mask_feature('ocean', cartopy.feature.OCEAN) `

See also

xsar.Sentinel1Meta.get_mask

get_mask(name)

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

Parameters

name (str) –

Returns

Return type

shapely.geometry.Polygon

property coverage

coverage, as a string like ‘251km * 170km (xtrack * atrack )’

property pixel_atrack_m

pixel atrack spacing, in meters (at sensor level)

property pixel_xtrack_m

pixel xtrack 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

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

convert atracks, xtracks arrays to longitude and latitude arrays. or a shapely object in atracks, xtracks coordinates to longitude and latitude.

Parameters

  • *args (atracks, xtracks or a shapely geometry) – atracks, xtracks are iterables or scalar

  • to_grid (bool, default False) – If True, atracks and xtracks must be 1D arrays. The results will be 2D array of shape (atracks.size, xtracks.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, dataset=None)

Get (atracks, xtracks) from (lon, lat), or convert a lon/lat shapely shapely object to atrack/xtrack coordinates.

Parameters

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

Returns

Return type

tuple of np.array or tuple of float (atracks, xtracks) , or a shapely object

Examples

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

>>> (atrack, xtrack) = meta.ll2coords(84.81, 21.32) # (lon, lat)
>>> (atrack, xtrack)
(9752.766349989339, 17852.571322887554)

See also

xsar.Sentinel1Meta.coords2ll, xsar.Sentinel1Dataset.coords2ll

coords2heading(atracks, xtracks, to_grid=False, approx=True)

Get image heading (atracks increasing direction) at coords atracks, xtracks.

Parameters

  • atracks (np.array or scalar) –

  • xtracks (np.array or scalar) –

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

Returns

heading , with shape depending on to_grid keyword.

Return type

np.array or float

property approx_transform

Affine transfom from gcps.

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 (atrack, xtrack):

>>> longitude, latitude = self.approx_transform * (atrack, xtrack)

get atrack and xtrack from tuple (longitude, latitude)

>>> atrack, xtrack = ~self.approx_transform * (longitude, latitude)

See also

xsar.Sentinel1Meta.coords2ll, xsar.Sentinel1Meta.ll2coords

class xsar.Sentinel1Dataset(dataset_id, resolution=None, resampling=<Resampling.average: 5>, luts=False, chunks={'atrack': 5000, 'xtrack': 5000}, dtypes=None)

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, optional) – resampling dict like {‘atrack’: 20, ‘xtrack’: 20} where 20 is in pixels.

  • resampling (rasterio.enums.Resampling or str, optional) – Only used if resolution is not None. ` rasterio.enums.Resampling.average` 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’,’atrack’,’xtrack’] (dask chunks).

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

See also

xsar.open_dataset

s1meta

xsar.Sentinel1Meta object

coords2ll

Alias for xsar.Sentinel1Meta.coords2ll

See also

xsar.Sentinel1Meta.coords2ll

sliced

True if dataset is a slice of original L1 dataset

resampled

True if dataset is not a sensor resolution

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 (atracks, xtracks) from (lon, lat), or convert a lon/lat shapely shapely object to atrack/xtrack coordinates.

Parameters

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

Returns

Return type

tuple of np.array or tuple of float (atracks, xtracks) , 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

property len_atrack_m

atrack length, in meters

property len_xtrack_m

xtrack length, in meters

property pixel_atrack_m

atrack pixel spacing, in meters (relative to dataset)

property pixel_xtrack_m

xtrack pixel spacing, in meters (relative to dataset)

property coverage

coverage string

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

class xsar.SentinelMeta(*args, **kwargs)
class xsar.SentinelDataset(*args, **kwargs)