GeoTIFF
- static from_file.GeoTIFF(path_or_dataset, data_crs_key=None, data_crs=None, sel=None, isel=None, plot_crs=None, shape=None, classify_specs=None, val_transform=None, coastline=False, mask_and_scale=False, fill_values='mask', extent=None, **kwargs)
Convenience function to initialize a new Maps-object from a GeoTIFF file.
If no explicit shape is provided, EOmaps will try several attempts to plot the data (fastest first).
fist, shading as a raster is used: m.set_shape.shade_raster
if it fails, shading with points is used: m.set_shape.shade_raster
if it fails, ordinary ellipse-plot is created: m.set_shape.ellipses
This function is (in principal) a shortcut for:
>>> m = Maps(crs=...) >>> m.set_data(**m.read_file.GeoTIFF(...)) >>> m.set_classify_specs(...) >>> m.plot_map(**kwargs)
- Parameters:
path_or_dataset (str, pathlib.Path or xar.Dataset) –
If str or pathlib.Path: The path to the file.
If xar.Dataset: The xarray.Dataset instance to use
data_crs_key (str, optional) –
The variable-name that holds the crs-information.
By default the following options are tried: - <crs_key> = “spatial_ref”, “crs”
crs = file.<crs_key>.attrs[“crs_wkt”]
crs = file.<crs_key>.attrs[“wkt”]
data_crs (None, optional) – Optional way to specify the crs of the data explicitly. (“data_crs_key” will be ignored if “data_crs” is provided!)
sel (dict, optional) – A dictionary of keyword-arguments passed to xarray.Dataset.sel() (see https://xarray.pydata.org/en/stable/generated/xarray.Dataset.sel.html) The default is None.
isel (dict, optional) – A dictionary of keyword-arguments passed to xarray.Dataset.isel(). (see https://xarray.pydata.org/en/stable/generated/xarray.Dataset.isel.html) The default is {“band” : 0} (if sel is None).
plot_crs (any, optional) – The plot-crs. A crs-identifier usable with cartopy. The default is None, in which case the crs of the GeoTIFF is used if possible, else epsg=4326.
shape (str, dict or None, optional) –
if str: The name of the shape to use, e.g. one of: [‘geod_circles’, ‘ellipses’, ‘rectangles’, ‘voronoi_diagram’, ‘delaunay_triangulation’, ‘shade_points’, ‘shade_raster’]
if dict: a dictionary with parameters passed to the selected shape. The dict MUST contain a key “shape” that holds the name of the shape!
>>> dict(shape="rectangles", radius=1, radius_crs=.5)
classify_specs (dict, optional) – A dict of keyword-arguments passed to m.set_classify_specs(). The default is None.
val_transform (None or callable) –
A function that is used to transform the data-values. (e.g. to apply scaling etc.)
>>> def val_transform(a): >>> return a / 10
coastline (bool) – Indicator if a coastline should be added or not. The default is False
mask_and_scale (bool) –
Indicator if the data should be masked and scaled with respect to the file-attributes _FillValue, scale_factor and add_offset.
If False: the data will only be scaled “on demand”, avoiding costly initialization of very large float-arrays. Masking will still be applied in case a _FillValue attribute has been found. (a masked-array is returned to avoid dtype conversions) The encoding is accessible via m.data_specs.encoding
If True: all data will be masked and scaled after reading. For more details see xarray.open_dataset.
NOTE: using mask_and_scale=True results in a conversion of the data-values to floats!! For very large datasets this can cause a huge increase in memory-usage! EOmaps handles the scaling internally to show correct values for callbacks and colorbars, even if mask_and_scale=False!
The default is False.
fill_values (str ("mask", "keep")) –
Indicator how to treat fill-values to avoid performance issues for extremely large (integer encoded) datasets.
Only relevant for integer-encoded data if “mask_and_scale” is False and a “_FillValue” is provided in the metadata.
If “mask”, a “numpy.masked_array” is used to incorporate fill-value masking while maintaining integer dtype. NOTE that this can lead to performance issues for very large datasets due to the increased memory usage (and reduced performance) of masked_arrays.
If “keep”, no masking with respect to fill-values is performed and a normal “numpy.array” is returned that still contains fill_values.
The fill-value is accessible via m.data_specs.encoding[“_FillValue”]
To adjust the color of fill_values in the plot without explicit masking, set the “over” and “unuder” colors of the used colorbar:
plt.cm.viridis.with_extremes(over=… under=…)
cmap.set_over(…), cmap.set_under(…))
(fill-values are excluded when evaluating data-limits)
extent (tuple or string) –
Set the extent of the map prior to plotting (can provide great speedups if only a subset of the dataset is shown!)
If a tuple is provided, it is used to set the plot-extent before plotting via m.set_extent(extent)
(x0, x1, y0, y1) : provide the extent in lat/lon (epsg 4326)
((x0, x1, y0, y1), crs) : provide the extent in the given crs
If a string is provided, it is used to attempt to set the plot-extent before plotting via m.set_extent_to_location(extent)
The default is None
kwargs – Keyword-arguments passed to m.plot_map()
- Returns:
m – The created Maps object.
- Return type:
Examples
# to just read the data use one of the following:
>>> from eomaps import Maps >>> path = r"C:/folder/file.tiff" >>> m = Maps.from_file.GeoTIFF(path)
# to select specific datasets from the file, use sel or isel:
>>> sel = dict(band = 1) >>> m = Maps.from_file.GeoTIFF(path, sel=sel)
# you can also use already opened filehandles:
>>> file = xar.open_dataset(path) >>> m = Maps.from_file.GeoTIFF(file)
>>> with xar.open_dataset(path) as file: >>> m = Maps.from_file.GeoTIFF(file)