This module is designed to extract a swath profile from a raster using a line shapefile. Finally, it has been completely recoded, but this is a simplification of the pyswath module (https://github.com/robertxa/pyswath). The main difference is that pyswath relies on profiles defined by points, simple_swath relies on a shapefile, and not only on points definition.
To install it :
$ pip install simple_swath
- numpy
- gdal
- shapely
- rasterstats
- alive_progress
- matplotlib
- matplotlib_scalebar
- csv
- pickle
Inside a (i)python environnement:
- To import the module:
>>> from simple_swath import swath
- To run the swath extraction:
>>> swath(raster_path = 'Rasterpathandname', shapefile_path = 'shapepathandname', outfile = 'prefixname', increment_value = 10, window_size = 100, bins = 40, xshift = None, nodata_value = -9999, meanmedian = 'mean', minmax = True, frequencyplot = True, TEMP = False, ylim = None, subplots = True, map_plot = {'cmap': "terrain", 'alphaM' : 0.7, 'alphaH' : 1, 'map' : True, 'scalebar' : False, 'px_leg' : 'Elevation (m)', 'hshd' : True, 'hshd_az' : 315, 'hshd_alt' : 45}, profile_plot = {'xlabel' : 'Distance (m)', 'ylabel' : None, 'x-unit' : 'm', 'xlim' : None, 'ylim' : None, 'legendP' : True}, profiles_colors = None)
- To use options or inputs, you need to set them as:
>>> swath(option_name = option_value, [...])
Options/inputs are (option_names):
raster_path (str) : Path of the Raster to use. The raster needs to be projected; the units of the grid should be meters (m)
shapefile_path (str) : Path of the shapefile to use to extract the profile. The shapefile should be in the same projection than the input raster. The shapefile should have a line or polyline geometry (2D or 3D), and can have several features.
outfile (str) : Prefix to add to the outputs' names.
spl_incrt (float) : Increment along the profile (in m).
spl_wndw (float) : Width of the box to build (in m).
bins (integer, optional) : Number of categories to compute the histogram.
- xshift (real or list of reals, optional): if you need to shift a profile along the disance axis
for 1 profile, provide a real (or same shifting applied to all the profiles) for n profiles in the shp, provide a list of n reals (len(xshit) == n) Default to None.
nodata_value (integer) : set the input raster's nodata value; default to None
minmax (bool, optional) : True to plot the min/max. Defaults to False.
frequencyplot (bool, optional) : True to plot the frequency. Defaults to False.
TEMP (bool, optional) : True to keep the temporary shapefiles, False to delete the folder TEMP/. Defaults to False.
ylim (tuple, optional) : Tuple of y limits for the graph profile. Defaults to None
subplots (bool, optional) : True to plot the raster and the swath on the same plot, False to plot the raste and the swath as two separate plots. Default = False
map_plot (dict, optional) : Dictionnary to tune the plot of the raster. It should be as
- >>>map_plot = {'cmap' : "terrain",
'alphaM' : 0.7, 'alphaH' : 1, 'map' : True, 'scalebar' : False, 'px_leg' : 'Elevation (m)', 'hshd' : True, 'hshd_az' : 315, 'hshd_alt' : 45}
where cmap is the cmap used to plot the DEM, alphaM and alphaH the transparency of the DEM and hillshade, map is True to plot the DEM over the hillshade, scalebar is True to add a scalebar to the map plot, px_leg is the legend of the pixel values, hshd is True if you want an hillshade above the DEM, and hshd_az and hshd_alt the Azimuth and altitude used to compute the hillshade If a parameter is ommited or set to None, the default value will be applied. Default to None ; in that case, the values given in the ex. are used
profile_plot (dictionnary, optional) : Dictionnary to tune the swath graph It shoudl be as
>>> profile_plot = {'xlabel' : 'Distance', 'ylabel' : None, 'x-unit' : None, 'xlim' : None, 'ylim' : None, 'legendP': False}
where xlabel and ylabel are the x-axis and y-axis Labels (str; if ylabel is None, default set to 'pixel value'), x-unit is unit of the x-axis (it should be None, 'm' or 'km' or 'cm' or 'mm'), xlim and ylim set the range of x-axis and y-axis (Tuples as (xmin, xmax) and (ymin, ymax)), and legendP is True to plot the legend of the swath. If a parameter is ommited or set to None, the default value will be applied. Default to None ; in that case, the values given in the ex. are used
- profiles_colors (list, optional) : List of the matplotlib colors (see https://matplotlib.org/stable/gallery/color/colormap_reference.html) to use for the swaths.
The length of the list should be equal to the number of the swaths/features in the input shapefile Default to None ; in that case, all profiles are plot in red
Caution!
Be carefull, the raster should be projected and the grid should be in meters (m)...
- To get help in your (i)python environnement:
>>> help(swath)
The module outputs pdfs of graphs, csv files, and pickle binary files.
- pdfs are the plot of the raster with the line use for the swath, and the swath profile
- csv files are a record of the data use to plot the swath (max, min, mean, median, 1s). There is one file for each profile/feature. If a profile is shifted along distances, this is writen as a comment in the first line of the csv file
- pickle binary files record the data used plot the frequency plot. There are two files. The file "rater_freqs.pickle" contains the frequency data, and the file "bin_edges.pickle" contains the bins extend of the frequency.
Copyright (c) 2024 Xavier Robert <xavier.robert@ird.fr> and Benjamin Lehmann <lehmann.benj@gmail.com> SPDX-License-Identifier: GPL-3.0-or-later