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.SentinelDataset(*args, **kwargs).dataset
See also
- 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.SentinelMeta
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
- class xsar.SentinelMeta(name, xml_parser=None, driver='GTiff')¶
Handle dataset metadata. A xsar.SentinelMeta 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 ‘tiff’)
- 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 SentinelMeta 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
- 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
- property files¶
Files for current dataset. (Empty for multi datasets)
See also
- 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
- 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)¶
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
- 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)
- coords2heading(atracks, xtracks, to_grid=False)¶
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.SentinelMeta.coords2ll xsar.SentinelMeta.ll2coords for accurate methods.
Examples
get longitude and latitude from tuple (atrack, xtrack):
>>> longitude, latitude = self.transform * (atrack, xtrack)
get atrack and xtrack from tuple (longitude, latitude)
>>> atrack, xtrack = ~self.transform * (longitude, latitude)
- class xsar.SentinelDataset(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 SentinelMeta 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
- s1meta¶
xsar.SentinelMeta object
- coords2ll¶
Alias for xsar.SentinelMeta.coords2ll
See also
- property dataset¶
xarray.Dataset representation of this xsar.SentinelDataset 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.SentinelDataset.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.SentinelMeta.ll2coords is that coordinates are rounded to the nearest dataset coordinates.
See also
- 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