Skip to content

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.

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. The tool is used to generate the footprint of a line based on absolute threshold.

FootprintAbsolute 

FootprintAbsolute(line_seg, in_chm, corridor_thresh, max_ln_width, exp_shk_cell)

Class to compute the footprint of a line based on absolute threshold.

compute 

compute()

Generate line footprint.

CenterlineParams

Bases: float, Enum

Parameters for centerline generation.

These parameters are used to control the behavior of centerline generation and should be adjusted based on the specific requirements of the application.

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)

Class to store seed line and least cost path.

ToolBase 

ToolBase()

Bases: object

Base class for tools.

CenterlineFlags

Bases: Flag

Flags for the centerline algorithm.

ParallelMode

Bases: IntEnum

Defines the parallel mode for the algorithms.

find_corridor_threshold 

find_corridor_threshold(raster)

Find the optimal corridor threshold by raster histogram Parameters

raster : corridor raster

Returns

corridor_threshold : float

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)

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

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.

CenterlineFlags

Bases: Flag

Flags for the centerline algorithm.

ParallelMode

Bases: IntEnum

Defines the parallel mode for the algorithms.

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 

Logger(name, console_level=INFO, file_level=INFO)

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 

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.

ToolBase 

ToolBase()

Bases: object

Base class for tools.