lidar package¶

Submodules¶

filtering module¶

Module for applying filters to image.

lidar.filtering.GaussianFilter(in_dem, sigma=1, out_file=None)[source]¶

Applies a Gaussian filter to an image.

Parameters:	in_dem (str) – File path to the input image. sigma (int, optional) – Standard deviation. Defaults to 1. out_file (str, optional) – File path to the output image. Defaults to None.
Returns:	The numpy array containing the filtered image.
Return type:	np.array

lidar.filtering.MeanFilter(in_dem, kernel_size=3, out_file=None)[source]¶

Applies a mean filter to an image.

Parameters:	in_dem (str) – File path to the input image. kernel_size (int, optional) – The size of the moving window. Defaults to 3. out_file (str, optional) – File path to the output image. Defaults to None.
Returns:	The numpy array containing the filtered image.
Return type:	np.array

lidar.filtering.MedianFilter(in_dem, kernel_size=3, out_file=None)[source]¶

Applies a median filter to an image.

Parameters:	in_dem (str) – File path to the input image. kernel_size (int, optional) – The size of the moving window. Defaults to 3. out_file (str, optional) – File path to the output image. Defaults to None.
Returns:	The numpy array containing the filtered image.
Return type:	np.array

lidar.filtering.np2rdarray(in_array, no_data, projection, geotransform)[source]¶

Converts an numpy array to rdarray.

Parameters:	in_array (np.array) – The input numpy array. no_data (float) – The no_data value of the array. projection (str) – The projection of the image. geotransform (str) – The geotransform of the image.
Returns:	The richDEM array.
Return type:	object

filling module¶

Module for filling surface depressions.

class lidar.filling.Depression(id, count, size, volume, meanDepth, maxDepth, minElev, bndElev, perimeter, major_axis, minor_axis, elongatedness, eccentricity, orientation, area_bbox_ratio)[source]¶

Bases: object

The class for storing depression info.

lidar.filling.ExtractSinks(in_dem, min_size, out_dir, filled_dem=None)[source]¶

Extract sinks (e.g., maximum depression extent) from a DEM.

Parameters:	in_dem (str) – File path to the input DEM. min_size (int) – The minimum number of pixels to be considered as a sink. out_dir (str) – File path to the output directory. fill_dem (str, optional) – The filled DEM.
Returns:	The richDEM array containing sinks.
Return type:	object

lidar.filling.extract_sinks_by_bbox(bbox, filename, min_size=10, tmp_dir=None, mask=None, crs='EPSG:5070', kernel_size=3, resolution=10, to_cog=False, keep_files=True, ignore_warnings=True)[source]¶

Extract sinks from a DEM by HUC8.

Parameters:

bbox (list) – The bounding box in the form of [minx, miny, maxx, maxy].
filename (str, optional) – The output depression file name.
min_size (int, optional) – The minimum number of pixels to be considered as a sink. Defaults to 10.
tmp_dir (str, optional) – The temporary directory. Defaults to None, e.g., using the current directory.
mask (str, optional) – The mask file path. Defaults to None.
crs (str, optional) – The coordinate reference system. Defaults to “EPSG:5070”.
kernel_size (int, optional) – The kernel size for smoothing the DEM. Defaults to 3.
resolution (int, optional) – The resolution of the DEM. Defaults to 10.
to_cog (bool, optional) – Whether to convert the output to COG. Defaults to False.
keep_files (bool, optional) – Whether to keep the intermediate files. Defaults to True.
ignore_warnings (bool, optional) – Whether to ignore warnings. Defaults to True.

lidar.filling.extract_sinks_by_huc8(huc8, min_size=10, filename=None, tmp_dir=None, wbd=None, crs='EPSG:5070', kernel_size=3, resolution=10, keep_files=True, error_file=None, ignore_warnings=True)[source]¶

Extract sinks from a DEM by HUC8.

Parameters:

huc8 (str) – The HUC8 code, e.g., 01010002
min_size (int, optional) – The minimum number of pixels to be considered as a sink. Defaults to 10.
filename (str, optional) – The output depression file name. Defaults to None, e,g., using the HUC8 code.
tmp_dir (str, optional) – The temporary directory. Defaults to None, e.g., using the current directory.
wbd (str | GeoDataFrame, optional) – The watershed boundary file. Defaults to None.
crs (str, optional) – The coordinate reference system. Defaults to “EPSG:5070”.
kernel_size (int, optional) – The kernel size for smoothing the DEM. Defaults to 3.
resolution (int, optional) – The resolution of the DEM. Defaults to 10.
keep_files (bool, optional) – Whether to keep the intermediate files. Defaults to True.
error_file (_type_, optional) – The file to save the error IDs. Defaults to None.
ignore_warnings (bool, optional) – Whether to ignore warnings. Defaults to True.

lidar.filling.extract_sinks_by_huc8_batch(huc_ids=None, min_size=10, out_dir=None, tmp_dir=None, wbd=None, crs='EPSG:5070', kernel_size=3, resolution=10, keep_files=False, reverse=False, error_file=None, ignore_warnings=True, ignored_ids=[], overwrite=False)[source]¶

Extract sinks from NED by HUC8.

Parameters:

huc8 (str) – The HUC8 code, e.g., 01010002
min_size (int, optional) – The minimum number of pixels to be considered as a sink. Defaults to 10.
filename (str, optional) – The output depression file name. Defaults to None, e,g., using the HUC8 code.
tmp_dir (str, optional) – The temporary directory. Defaults to None, e.g., using the current directory.
wbd (str | GeoDataFrame, optional) – The watershed boundary file. Defaults to None.
crs (str, optional) – The coordinate reference system. Defaults to “EPSG:5070”.
kernel_size (int, optional) – The kernel size for smoothing the DEM. Defaults to 3.
resolution (int, optional) – The resolution of the DEM. Defaults to 10.
keep_files (bool, optional) – Whether to keep the intermediate files. Defaults to True.
reverse (bool, optional) – Whether to reverse the HUC8 list. Defaults to False.
error_file (_type_, optional) – The file to save the error IDs. Defaults to None.
ignore_warnings (bool, optional) – Whether to ignore warnings. Defaults to True.
overwrite (bool, optional) – Whether to overwrite the existing files. Defaults to False.

lidar.filling.get_dep_props(objects, resolution)[source]¶

Computes depression attributes.

Parameters:	objects (object) – The labeled objects. resolution (float) – The spatial reoslution of the image.
Returns:	A list of depression objects with attributes.
Return type:	list

lidar.filling.image_to_cog(source, dst_path=None, profile='deflate', **kwargs)[source]¶

Converts an image to a COG file.

Parameters:	source (str) – A dataset path, URL or rasterio.io.DatasetReader object. dst_path (str, optional) – An output dataset path or or PathLike object. Defaults to None. profile (str, optional) – COG profile. More at https://cogeotiff.github.io/rio-cogeo/profile. Defaults to “deflate”.
Raises:	`ImportError` – If rio-cogeo is not installed. `FileNotFoundError` – If the source file could not be found.

lidar.filling.np2rdarray(in_array, no_data, projection, geotransform)[source]¶

Converts an numpy array to rdarray.

Parameters:	in_array (array) – The input numpy array. no_data (float) – The no_data value of the array. projection (str) – The projection of the image. geotransform (str) – The geotransform of the image.
Returns:	The richDEM array.
Return type:	object

lidar.filling.polygonize(img, shp_path)[source]¶

Converts a raster image to vector.

Parameters:	img (str) – File path to the input image. shp_path (str) – File path to the output shapefile.

lidar.filling.regionGroup(img_array, min_size, no_data)[source]¶

IdentifIies regions based on region growing method

Parameters:	img_array (array) – The numpy array containing the image. min_size (int) – The minimum number of pixels to be considered as a depression. no_data (float) – The no_data value of the image.
Returns:	The labelled objects and total number of labels.
Return type:	tuple

lidar.filling.write_dep_csv(dep_list, csv_file)[source]¶

Saves the depression list info to a CSV file.

Parameters:	dep_list (list) – A list of depression objects with attributes. csv_file (str) – File path to the output CSV file.

slicing module¶

Module for the level-set algorithm.

lidar.slicing.DelineateDepressions(in_sink, min_size, min_depth, interval, out_dir, bool_level_shp=False)[source]¶

Delineates nested depressions.

Parameters:	in_sink (str) – The file path to the sink image. min_size (int) – The minimum number of pixels to be considered as a depression. min_depth (float) – The minimum depth to be considered as a depression. interval (float) – The slicing interval. out_dir (str) – The file path to the output directory. bool_level_shp (bool, optional) – Whether to generate shapefiles for each individual level. Defaults to False.
Returns:	The output level image, and the output object image.
Return type:	tuple

class lidar.slicing.Depression(id, level, count, size, volume, meanDepth, maxDepth, minElev, bndElev, inNbrId, regionId, perimeter, major_axis, minor_axis, elongatedness, eccentricity, orientation, area_bbox_ratio)[source]¶

Bases: object

The class for storing depression info.

lidar.slicing.extract_levels(level_img, obj_img, min_size, no_data, out_img_dir, out_shp_dir, template, bool_comb=False)[source]¶

Extracts individual level image.

Parameters:	level_img (np.array) – The numpy array containing the level image. obj_img (np.array) – The numpy array containing the object image. min_size (int) – The minimum number of pixels to be considered as a depression. no_data (float) – The no_data value of the image. out_img_dir (str) – The output image directory. out_shp_dir (str) – The output shapefile directory. template (str) – The file path to the template image. bool_comb (bool, optional) – Whether to extract combined level image. Defaults to False.
Returns:	The single level image, properties of region grouped level image, properties of region grouped object image.
Return type:	tuple

lidar.slicing.getMetadata(img)[source]¶

Gets rdarray metadata.

Parameters:	img (rdarray) – The richDEM array containing the image.
Returns:	no_data, projection, geotransform, cell_size
Return type:	tuple

lidar.slicing.get_image_paras(image_paras)[source]¶

Gets image parameters.

Parameters:	image_paras (dict) – The dictionary containing image parameters.
Returns:	A tuple containing no_data, min_size, min_depth, interval, resolution.
Return type:	tuple

lidar.slicing.get_min_max_nodata(image)[source]¶

Gets the minimum, maximum, and no_data value of a numpy array.

Parameters:	image (np.array) – The numpy array containing the image.
Returns:	The minimum, maximum, and no_data value.
Return type:	tuple

lidar.slicing.img_to_shp(in_img_dir, out_shp_dir)[source]¶

Converts images in a selected folder to shapefiles

Parameters:	in_img_dir (str) – The input iimage directory. out_shp_dir (str) – The output shapefile directory.

lidar.slicing.levelSet(img, region_id, obj_uid, image_paras)[source]¶

Identifies nested depressions using level-set method.

Parameters:	img (np.array) – The numpy array containing the image. region_id (int) – The unique id of the region. obj_uid (int) – The object id of the region. image_paras (dict) – The dictionary containing image parameters.
Returns:	(level image, depression list)
Return type:	tuple

lidar.slicing.np2rdarray(in_array, no_data, projection, geotransform)[source]¶

Converts numpy array to rdarray.

Parameters:	in_array (np.array) – The input numpy array containing the image. no_data (float) – The no_data value of the image. projection (str) – The projection coordinate system of the image. geotransform (str) – The geotransform of the image.
Returns:	The richDEM array containing the image.
Return type:	rdarray

lidar.slicing.obj_to_level(obj_img, dep_list)[source]¶

Derives depression level image based on the depression id image and depression list.

Parameters:	obj_img (np.array) – The numpy array containing the object image. dep_list (list) – A list containing depression info.
Returns:	The numpy array containing the object level image.
Return type:	np.array

lidar.slicing.polygonize(img, shp_path)[source]¶

Converts a raster image to vector.

Parameters:	img (str) – File path to the input image. shp_path (str) – File path to the output shapefile.

lidar.slicing.regionGroup(img_array, min_size, no_data)[source]¶

IdentifIies regions based on region growing method

Parameters:	img_array (np.array) – The numpy array containing the image. min_size (int) – The minimum number of pixels to be considered as a depression. no_data (float) – The no_data value of the image.
Returns:	The labelled objects and total number of labels.
Return type:	tuple

lidar.slicing.set_image_paras(no_data, min_size, min_depth, interval, resolution)[source]¶

Sets the input image parameters for level-set method.

Parameters:	no_data (float) – The no_data value of the input DEM. min_size (int) – The minimum number of pixels to be considered as a depression. min_depth (float) – The minimum depth to be considered as a depression. interval (float) – The slicing interval. resolution (float) – The spatial resolution of the DEM.
Returns:	A dictionary containing image parameters.
Return type:	dict

lidar.slicing.updateLevel(dep_list, obj_uid)[source]¶

Updates the inner neighbors of each depression.

Parameters:	dep_list (list) – A list containing depression info. obj_uid (int) – The unique id of an object.
Returns:	A list containing depression info.
Return type:	list

lidar.slicing.writeObject(img_array, obj_array, bbox)[source]¶

Writes depression objects to the original image.

Parameters:	img_array (np.array) – The output image array. obj_array (np.array) – The numpy array containing depression objects. bbox (list) – The bounding box of the depression object.
Returns:	The numpy array containing the depression objects.
Return type:	np.array

lidar.slicing.writeRaster(arr, out_path, template)[source]¶

Saves an numpy array as a GeoTIFF.

Parameters:	arr (np.array) – The numpy array containing the image. out_path (str) – The file path to the output GeoTIFF. template (str) – The file path to the template image containing projection info.
Returns:	The numpy array containing the image.
Return type:	np.array

lidar.slicing.write_dep_csv(dep_list, csv_file)[source]¶

Saves the depression list to a CSV file.

Parameters:	dep_list (list) – A list containing depression info. csv_file (str) – File path to the output CSV file.

mounts module¶

Module for delineating the nested hierarchy of elevated features (i.e., mounts).

lidar.mounts.DelineateMounts(in_dem, min_size, min_height, interval, out_dir, bool_shp=False)[source]¶

Delineates the nested hierarchy of elevated features (i.e., mounts).

Parameters:	in_dem (str) – File path to the input DEM. min_size (int) – The minimum number of pixels to be considered as an object. min_height (float) – The minimum depth of the feature to be considered as an object. interval (float) – The slicing interval. out_dir (str) – The output directory. bool_shp (bool, optional) – Whether to generate shapefiles. Defaults to False.
Returns:	File paths to the depression ID and level.
Return type:	tuple

lidar.mounts.FlipDEM(dem, delta=100, out_file=None)[source]¶

Flips the DEM.

Parameters:	dem (np.array) – The numpy array containing the image. delta (int, optional) – The base value to be added to the flipped DEM. Defaults to 100. out_file (str, optional) – File path to the output image. Defaults to None.
Returns:	The numpy array containing the flipped DEM.
Return type:	np.array

lidar.mounts.get_min_max_nodata(dem)[source]¶

Gets the minimum, maximum, and no_data value of a numpy array.

Parameters:	dem (np.array) – The numpy array containing the image.
Returns:	The minimum, maximum, and no_data value.
Return type:	tuple

Module contents¶

Top-level package for lidar.