Python API Reference
This page documents the main Python modules in BERA Tools using mkdocstrings.
Tools API
Copyright (C) 2025 Applied Geospatial Research Group.
This script is licensed under the GNU General Public License v3.0. See https://gnu.org/licenses/gpl-3.0 for full license details.
Author: Richard Zeng
Description
This script is part of the BERA Tools. Webpage: https://github.com/appliedgrg/beratools
The purpose of this script is to provide main interface for line grouping tool.
qc_merge_multilinestring
qc_merge_multilinestring(gdf)
QC step: Merge MultiLineStrings if possible, else split into LineStrings.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
gdf
|
GeoDataFrame
|
Input GeoDataFrame. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
GeoDataFrame |
Cleaned GeoDataFrame with only LineStrings. |
qc_split_lines_at_intersections
qc_split_lines_at_intersections(gdf)
QC step: Split lines at intersections so each segment becomes a separate line object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
gdf
|
GeoDataFrame
|
Input GeoDataFrame of LineStrings. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
GeoDataFrame |
New GeoDataFrame with lines split at all intersection points. |
Copyright (C) 2025 Applied Geospatial Research Group.
This script is licensed under the GNU General Public License v3.0. See https://gnu.org/licenses/gpl-3.0 for full license details.
Author: Richard Zeng
Description
This script is part of the BERA Tools. Webpage: https://github.com/appliedgrg/beratools
The purpose of this script is the public interface for vertex optimization.
Copyright (C) 2025 Applied Geospatial Research Group.
This script is licensed under the GNU General Public License v3.0. See https://gnu.org/licenses/gpl-3.0 for full license details.
Author: Richard Zeng
Description
This script is part of the BERA Tools. Webpage: https://github.com/appliedgrg/beratools
The purpose of this script is to provide main interface for centerline tool.
centerline
centerline(in_line, in_raster, line_radius, proc_segments, out_line, guided_strategy=CENTERLINE_GUIDED_STRATEGY, use_angle_grouping=True, processes=0, call_mode=CLI, log_level='INFO')
Run centerline extraction.
guided_strategy modes: - MAIN_ROUTE: unguided main-route extraction. - PAIRWISE: endpoint-guided search over endpoint node pairs. - VIRTUAL_NODES: endpoint-guided search using virtual source/destination graph nodes. - DIRECT_INSERT: endpoint-guided search by inserting endpoints directly into the Voronoi graph.
Copyright (C) 2025 Applied Geospatial Research Group.
This script is licensed under the GNU General Public License v3.0. See https://gnu.org/licenses/gpl-3.0 for full license details.
Author: Richard Zeng
Description
This script is part of the BERA Tools. Webpage: https://github.com/appliedgrg/beratools
The purpose of this script is to provide main interface for canopy footprint tool.
canopy_footprint_abs
canopy_footprint_abs(in_line, in_chm, corridor_thresh=3.0, max_ln_width=32.0, exp_shk_cell=0, out_footprint=None, footprint_mode='absolute', tree_radius=1.5, max_line_dist=1.5, canopy_avoidance=0.0, exponent=1.0, canopy_thresh_percentage=50, processes=0, call_mode=CLI, log_level='INFO')
Run canopy footprint in absolute or adaptive mode.
CenterlineParams
CenterlineStatus
Bases: IntEnum
Status of centerline generation.
This enum is used to indicate the status of centerline generation. It can be used to track the success or failure of the centerline generation process.
SeedLine
SeedLine(line_gdf, ras_file, proc_segments, line_radius, guided_strategy='main_route')
Class to store seed line and least cost path.
CenterlineStrategy
CenterlineFlags
ParallelMode
find_corridor_threshold
find_corridor_threshold(raster)
Find the optimal corridor threshold by raster histogram Parameters
raster : corridor raster
Returns
corridor_threshold : float
main_line_footprint_relative
main_line_footprint_relative(in_line: str, in_chm: str, max_ln_width: float, out_footprint: str, out_centerline: str, exp_shk_cell: int, tree_radius: float, max_line_dist: float, canopy_avoidance: float, exponent: float, full_step: bool, canopy_thresh_percentage: int, processes: int, verbose: bool, debug_mode: bool = BT_DEBUGGING) -> None
This function take the centerlines with forest canopy height and distance to edge to generate dynamic footprint from input CHM. An option smooth centerlines will be generated. Args: in_line: Path like string for input centerlines in_chm: Path like string input CHM max_ln_width: Maximum processing width for input lines out_footprint: Path like string output footprint out_centerline: (Option) Path like string output centerline exp_shk_cell: Range as integer used for cell erosion tree_radius: Radius of trees influence in the cost raster max_line_dist: Maximum Euclidean distance from canopy canopy_avoidance: 0 < Ratio < 1 of importance between canopy search radius and Euclidean distance exponent: Affects the cost of vegetated areas in an exponential fashion canopy_thresh_percentage: Percentage as integer range 1-100
Returns:
| Type | Description |
|---|---|
None
|
New saved footprints and/or with smoothed centerlines dataset(s). |
centerline_is_valid
centerline_is_valid(centerline, input_line)
Check if centerline is valid.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
centerline
|
_type_
|
description |
required |
input_line
|
LineString
|
Seed line or least cost path. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
bool |
True if line is valid |
find_centerline
find_centerline(poly, input_line, guided_strategy='main_route')
Find centerline from polygon and input line.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
poly
|
sh_geom.Polygon |
required | |
input_line
|
LineString
|
Least cost path or seed line |
required |
Returns: centerline (sh_geom.LineString): Centerline status (CenterlineStatus): Status of centerline generation
process_single_centerline
process_single_centerline(row_and_path)
Find centerline.
Args: row_and_path (list of row (gdf and lc_path)): and least cost path first is GeoPandas row, second is input line, (least cost path)
Returns: row: GeoPandas row with centerline
regenerate_centerline
regenerate_centerline(poly, input_line)
Regenerates centerline when initial poly is not valid.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input_line
|
LineString
|
Seed line or least cost path. |
required |
Returns:
| Type | Description |
|---|---|
|
sh_geom.MultiLineString |
cut_line_by_length
cut_line_by_length(line, length, merge_threshold=0.5)
Split line into segments of equal length.
Merge the last segment with the second-to-last if its length is smaller than the given threshold.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
line
|
LineString Line to be split by distance along the line. |
required | |
length
|
float Length of each segment to cut. |
required | |
merge_threshold
|
float, optional Threshold below which the last segment is merged with the previous one. Default is 0.5. |
required |
Returns:
| Type | Description |
|---|---|
|
List of LineString objects A list containing the resulting line segments. |
Example
">>> from shapely.geometry import LineString ">>> line = LineString([(0, 0), (10, 0)]) ">>> segments = cut_line_by_length(line, 3, merge_threshold=1) ">>> for segment in segments: ">>> print(f"Segment: {segment}, Length: {segment.length}")
Output: Segment: LINESTRING (0 0, 3 0), Length: 3.0 Segment: LINESTRING (3 0, 6 0), Length: 3.0 Segment: LINESTRING (6 0, 9 0), Length: 3.0 Segment: LINESTRING (9 0, 10 0), Length: 1.0
After merging the last segment with the second-to-last segment:
Output: Segment: LINESTRING (0 0, 3 0), Length: 3.0 Segment: LINESTRING (3 0, 6 0), Length: 3.0 Segment: LINESTRING (6 0, 10 0), Length: 4.0
chk_df_multipart
chk_df_multipart(df: GeoDataFrame, chk_shp_in_string: str) -> tuple[GeoDataFrame, bool]
This function is check the input geopandas.GeoDataFrame object contains multipart geometry. If multipart geometry is found, function will try to explode and return single geometry and a boolean of multipart is found or not. Args: df: Any geopandas.GeoDataFrame like chk_shp_in_string: String that the input GeoDataFrame geometry type, i.e. 'Point', 'Polygon', 'LineString'
Returns:
main_canopy_threshold_relative
main_canopy_threshold_relative(in_line: str, in_chm: str, canopy_percentile: int, canopy_thresh_percentage: int, full_step: bool, processes: int, verbose: bool, out_DynCenterline: str = None) -> str | None
This is a function finding approximate surrounding forest canopy height and surrounding forest edge distance from input CHM Args: in_line: Path like string in_chm: Path like string canopy_percentile: Percentile as integer range 1-100 canopy_thresh_percentage: Percentage as integer range 1-100
Returns:
| Type | Description |
|---|---|
str | None
|
Path like string of the saved centerlines with extra attributes |
Copyright (C) 2025 Applied Geospatial Research Group.
This script is licensed under the GNU General Public License v3.0. See https://gnu.org/licenses/gpl-3.0 for full license details.
Author: Richard Zeng, Maverick Fong
Description
This script is part of the BERA Tools. Webpage: https://github.com/appliedgrg/beratools
This file hosts the ground_footprint tool.
prepare_line_args
prepare_line_args(line_gdf, poly_gdf, n_samples, offset, width_percentile)
Generate arguments for each line in the GeoDataFrame.
Returns:
| Name | Type | Description |
|---|---|---|
line_args |
list row : inter_poly : n_samples : offset : width_percentile : |
generate_sample_points
generate_sample_points(line, n_samples=10)
Generate evenly spaced points along a line.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
line
|
LineString
|
The line along which to generate points. |
required |
n_samples
|
int
|
The number of points to generate (default is 10). |
10
|
Returns:
| Name | Type | Description |
|---|---|---|
list |
List of shapely Point objects. |
generate_fixed_width_footprint
generate_fixed_width_footprint(line_gdf, max_width=False)
Create a buffer around each line.
In the GeoDataFrame using its 'max_width' attribute and saves the resulting polygons in a new shapefile.
Args: line_gdf: GeoDataFrame containing LineString with 'max_width' attribute. max_width: Use max width or not to produce buffer.
calculate_average_width
calculate_average_width(line, in_poly, offset, n_samples)
Calculate the average width of a polygon perpendicular to the given line.
Constants
Copyright (C) 2025 Applied Geospatial Research Group.
This script is licensed under the GNU General Public License v3.0. See https://gnu.org/licenses/gpl-3.0 for full license details.
Author: Richard Zeng
Description
This script is part of the BERA Tools. Webpage: https://github.com/appliedgrg/beratools
The purpose of this script is to provide common constants.
Logger
Copyright (C) 2025 Applied Geospatial Research Group.
This script is licensed under the GNU General Public License v3.0. See https://gnu.org/licenses/gpl-3.0 for full license details.
Author: Richard Zeng
Description
This script is part of the BERA Tools. Webpage: https://github.com/appliedgrg/beratools
The purpose of this script is to provide logger functions.
NoParsingFilter
Bases: Filter
Filter to exclude log messages that start with "parsing".
This is useful to avoid cluttering the log with parsing-related messages.
Logger
Bases: object
Logger class to handle logging in the BERA Tools application.
This class sets up a logger that outputs to both the console and a file. It allows for different logging levels for console and file outputs. It also provides a method to print messages directly to the logger.
print(msg, flush=True)
Re-define print in logging.
Args: msg : flush :
Tool Base
Copyright (C) 2025 Applied Geospatial Research Group.
This script is licensed under the GNU General Public License v3.0. See https://gnu.org/licenses/gpl-3.0 for full license details.
Author: Richard Zeng
Description
This script is part of the BERA Tools. Webpage: https://github.com/appliedgrg/beratools
The purpose of this script is to provide fundamental utilities for tools.