Python API Reference
This page documents the PC2Products Python modules using mkdocstrings.
Tools API
rpy_las_info
rpy_las_info(in_las_folder, processes=0, **kwargs)
report las info on:LAS version CRS EPSG Units Extent Area Point count Point density Number of files Normalized / not normalized Ground elevation statistics
rpy_gnd_csf
rpy_gnd_csf(in_las_folder, out_folder, slope: bool = False, class_threshold=0.3, cloth_resolution=1.0, rigidness=1, processes=1, **kwargs)
Generate a raster of hummock hollows from LiDAR data. INPUT: LiDAR folder, output folder, smoothing method, minimum watershed size, lawn range, cell size returnValue: raster of hummock hollows
rpy_hh2raster
rpy_hh2raster(in_las_folder, out_folder, Smooth_by, Min_ws=3.0, lawn_range=0.3, cell_size=0.0, processes=0, **kwargs)
Generate a raster of hummock hollows from LiDAR data. INPUT: LiDAR folder, output folder, smoothing method, minimum watershed size, lawn range, cell size returnValue: raster of hummock hollows
surface_water_processes
surface_water_processes(processes, in_ortho, tile_size, min_patch_area)
R workers for surface_water_map on this machine: one per CPU core and tile, as far as the free memory holds one buffered tile per worker. processes > 0 caps the count.
rpy_surface_water
rpy_surface_water(in_ortho, in_training, out_folder, in_chm='', max_canopy_height=0.2, min_patch_area=0.04, points_per_polygon=2, seed=1, tile_size=2000, processes=0, **kwargs)
Map surface water from a true-colour orthomosaic with a decision tree.
Follows Chan, Dabros & McDermid (2026), Forests 17, 489, section 2.4.
INPUT: orthomosaic (bands 1-3 red, green, blue), training polygons with a 'class' field
('water' plus other classes such as 'ground' and 'shadow'), output folder,
optional CHM, canopy height mask threshold, minimum water patch area,
training points per polygon, random seed, tile size (cells per side; tiles are
classified in parallel by processes R workers)
returnValue: surface_water.tif (1 water, 0 not water) and cross-validation tables in out_folder
dtw_processes
dtw_processes(processes, in_dtm, kriging_cell_size, tile_size)
R workers for kriging the water table on this machine: one per CPU core and tile of the kriging grid, as far as the free memory holds one tile per worker. processes > 0 caps the count.
rpy_dtw
rpy_dtw(in_dtm, in_water, out_folder, in_mask='', grid_size=10.0, nmax=10, variogram_model='Ste', kriging_cell_size=0.01, tile_size=1000, processes=0, **kwargs)
Krige a water table from surface water elevations and compute depth-to-water.
Follows Chan, Dabros & McDermid (2026), Forests 17, 489, section 2.4.
INPUT: DTM, surface water raster (1 water, e.g. from Surface Water Mapping), output folder,
optional exclusion polygons, grid size, nearest observations, variogram model,
kriging cell size (0 = DTM cell size), tile size (kriging grid cells per side; tiles
are kriged in parallel by processes R workers)
returnValue: water_table.tif and dtw.tif (0 on surface water) in out_folder
rpy_seismic_line_analysis
rpy_seismic_line_analysis(in_segments, in_dtm, in_microform, out_folder, in_dtw='', significance=0.05, processes=0, **kwargs)
Compare seismic line segments with the adjacent matrix, by disturbance class.
Adapted from Chan, Dabros & McDermid (2026), Forests 17, 489. INPUT: segment polygons (fields new_id, note, Class), DTM raster, microform raster (1 hummock, 0 lawn, -1 hollow), optional depth-to-water raster (0 = surface water), output folder, significance level returnValue: CSV tables and PNG plots in out_folder/tables and out_folder/plots
R Interface
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: Maverick Fong
Description
This script is helper tools for execute the R scripts.
Webpage: https://github.com/BERATool/PC2Products
configure_r_environment
configure_r_environment()
Locate and configure R before importing rpy2.
isolate_env_r_library
isolate_env_r_library(r_home)
Keep the environment's R from using the user's personal R library.
R adds the personal library (R_LIBS_USER, e.g. %LOCALAPPDATA%/R/win-library/4.5 on Windows) ahead of its own library. For an R installed in the conda/pixi environment, that would load packages installed for a separate R and stop the tools from installing into the environment. A non-existent R_LIBS_USER is dropped from .libPaths(), leaving only the environment's library. A standalone R (outside the environment) is left alone.
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: Maverick Fong
Description
This script is helper tools for execute the R scripts.
Webpage: https://github.com/BERATool/PC2Products
r_processes_by_memory
r_processes_by_memory(processes, worker_bytes, tasks)
Workers for an R job whose memory per worker is known: as many as requested (all CPU cores if processes <= 0), limited by the CPU cores, the number of tasks and the free memory. 60% of the free memory is shared out, leaving room for the system and other programs.
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/BERATool/PC2Products
The purpose of this script is to provide common constants.
CenterlineStrategy
CenterlineMethod
CenterlineChmMode
CenterlineFlags
ParallelMode
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/BERATool/PC2Products
This module provides logger configuration and convenience functions for BERA Tools.
Each named logger can write to:
- A log file using a detailed timestamped format.
- The console using a concise message-only format.
The module also adds two convenience methods to each configured logger:
logger.file_only(...)
logger.debug_file_only(...)
These methods bypass console handlers and write directly to the logger's file handler.
NoParsingFilter
Bases: Filter
Exclude messages beginning with the word parsing.
This reduces console and file noise from repetitive parsing messages. The comparison is case-sensitive to retain the behavior of the original implementation.
Logger
Logger(logger_name, queue=None, file_level=DEFAULT_FILE_LEVEL, console_level=DEFAULT_CONSOLE_LEVEL)
Configure a named BERA Tools logger.
The logger uses two handlers:
-
File handler: Stores timestamped messages at
file_levelor higher. -
Console handler: Displays concise messages at
console_levelor higher.
Each logger is configured only once. Creating another Logger
instance with the same name reuses the existing handlers.
Parameters
logger_name : str Name of the logger.
int, default logging.INFO
Minimum logging level written to the log file.
int, default logging.INFO
Minimum logging level written to the console.
get_logger
get_logger() -> Logger
Return the configured logger.
Two convenience methods are attached to the logger:
logger.file_only(message, *args, level=logging.INFO)
Write only to file handlers.
logger.debug_file_only(message, *args)
Write a DEBUG message only to file handlers.
Returns
logging.Logger Configured logger instance.
print(message, flush: bool = True) -> None
Log a message at INFO level.
This method provides compatibility with code that previously
used print() for progress or status messages.
Parameters
message : object Message or object to log.
bool, default True
Flush all configured handlers after logging.
flush
flush() -> None
Flush all handlers associated with this logger.
Flushing should normally be used only for important progress messages, shutdown handling, or debugging. Flushing every log record can significantly reduce performance.
debug_file_only
staticmethod
Write a DEBUG message only to file handlers.
The message is not sent to console handlers.
Parameters
message : object Log message or formatting template.
*args Values used with standard logging percent formatting.
str
Name of an existing configured logger.
file_only
staticmethod
Write a message directly to the logger's file handlers.
Console handlers are intentionally bypassed.
Unlike a regular logger call, this method sends the record directly to each file handler. This allows a DEBUG file-only record to be written even when the logger's effective level is INFO or WARNING, provided the file handler accepts that level.
Parameters
message : object Log message or formatting template.
*args Values used with standard logging percent formatting.
int, default logging.INFO
Logging level associated with the record.
str
Name of an existing configured logger.
Notes
This method does not flush the file handler after every message.
Operating-system and Python buffering improve performance during
large multiprocessing jobs. Use Logger.flush() when an
immediate flush is required.
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/BERATool/PC2Products
The purpose of this script is to provide fundamental utilities for tools.
configure_worker_logging
configure_worker_logging(queue)
Configure worker process logger.