Utilities¶

Logging¶

pix4dvortex provides seamless interoperability with Python, allowing callable logger objects to be passed to most functions. These objects may be any Python callable of type Callable[[int, str], None], where the first parameter is a logging level and the second is a message. This is satisfied, for example, by logging.Logger.log(), but may be a simple user-defined function, as shown in the examples below.

All logging-enabled functions have a parameter logger which accepts a callable of the type described above.

Note

Internally, the invocations of the callable are executed sequentially in an asynchronous queue running in a separate thread, ensuring that the logging itself doesn’t unnecessarily block the processing functions from which it is called, while ensuring that the Python Global Interpreter Lock (GIL) is released and acquired as needed.

Note

On Windows, configure logging with UTF-8 encoding (for example via encoding="utf-8" in logging.basicConfig() or when opening log files). UTF-8 is the default on Linux, but without it on Windows, non-ASCII path names in log messages may be lost or cause errors.

This example shows how to use Python logging functionality, both in a script, and passed into processing functions:

import logging
from pathlib import Path

from pix4dvortex import calib, cameras

logging.basicConfig(
    format="%(asctime)s | %(name)-17s | %(levelname)-8s | %(message)s", level=logging.INFO
)

data_dir = Path("some/data/dir/img")
imgs = list(data_dir.glob("*.JPG"))

vtx_log = logging.getLogger("vortex").log
vtx_log(logging.INFO, "Make input cameras")

input_cameras = cameras.make_input_cameras(image_info=imgs, logger=vtx_log)

projected_cameras = cameras.ProjectedCameras(input_cameras=input_cameras)

vtx_log(logging.INFO, "Run calibration")

calibrated_scene = calib.calibrate(
    cameras=projected_cameras,
    settings=calib.Settings(),
    logger=vtx_log,
)

vtx_log(logging.INFO, "Processing finished.")

This example has a user defined logging function which simply prints to standard output:

import logging
from pathlib import Path

from pix4dvortex import calib, cameras


def print_log(level, msg):
    print(f"{logging.getLevelName(level)} | {msg}")


data_dir = Path("some/data/dir/img")
imgs = list(data_dir.glob("*.JPG"))

print_log(logging.INFO, "Make input cameras")
input_cameras = cameras.make_input_cameras(image_info=imgs, logger=print_log)

projected_cameras = cameras.ProjectedCameras(input_cameras=input_cameras)

print_log(logging.INFO, "Run calibration")

calibrated_scene = calib.calibrate(
    cameras=projected_cameras,
    settings=calib.Settings(),
    logger=print_log,
)

print_log(logging.INFO, "Processing finished.")

Progress callbacks¶

Major processing and export functions accept an optional progress_callback parameter. The callable has the form Callable[[str, int], None]: the first argument is a step name (a stable, user-facing string) and the second is the completion percentage for that step, in the range 0–100.

One exception is ~pix4dvortex.gsplat._gen_gs_rasters, which reports completion as a floating-point ratio (0.0–1.0) without a step name.

Each function reports progress for one or more named steps. For most APIs, a single step runs from 0 to 100. Within a step, reported percentages are monotonic.

Pass None to omit progress reporting. When no callback is provided, processing functions do not incur progress-reporting overhead.

Many of the same functions also accept an optional stop_function for cooperative cancellation. See Stop functions.

Example:

def on_progress(step: str, percent: int) -> None:
    print(f"{step}: {percent}%")


calibrated_scene = calib.calibrate(
    cameras=projected_cameras,
    settings=calib.Settings(),
    progress_callback=on_progress,
)

The table below lists every API that exposes progress_callback and the step name(s) it reports. Public APIs are shown as :func: references; internal helpers are explicitly labeled. Step names are stable identifiers suitable for logging, UI labels, and pipeline aggregation.

Progress callbacks¶
API	Step name(s)	Notes
`make_input_cameras()`	`Creating input cameras`	Single step
`calibrate()`	`Calibrating`	Single step
`reoptimize()`	`Reoptimizing`	Single step
`densification()`	`Densifying sparse point cloud`	Single step
`gen_pcl()`	`Generating depth point cloud`	Single step
`pcl_merge()`	`Merging point clouds`	Single step
`detect_gcp_marks()`	`Marking targets`	Single step
`gen_segment_masks()`	`Generating masks`	Single step
`alignment()`	`Loading point clouds`; `Global registration`; `Refining`; `Evaluating`	Four sequential steps, each 0–100
`gen_tiled_dsm()`	`Generating DEM`	Single step
`gen_dsm()`	`Generating DEM`	Single step
`gen_tiled_dtm()`	`Generating DEM`	Single step
`gen_dtm()`	`Generating DEM`	Single step
`gen_tiled_orthomosaic()`	`Generating orthomosaic`	Single step
`gen_orthomosaic()`	`Generating orthomosaic`	Single step
`gen_mesh_geometry()`	`Triangulating mesh`	Single step
`gen_mesh_texture()`	`Texturing mesh`	Single step
`gen_textured_mesh_lod()`	`Generating mesh`	Single step
`gen_mesh()`	`Generating mesh`	Single step
`gen_gs()`	`Generating gaussian splatting`	Single step
`~pix4dvortex.gsplat._gen_gs_rasters`	`Generating gaussian splatting rasters`	Single step
`gen_gs_dsm()`	`Generating gaussian splatting DSM raster`	Single step
`calibrate()`	`Calibrating cameras`	Single step
`gen_tiled_orthomosaic()`	`Generating orthomosaic`	Single step
`gen_orthomosaic()`	`Generating orthomosaic`	Single step
`write_pcl()`	`Writing LAS point cloud`	Single step
`write_geotiff()`	`Writing DSM GeoTIFF` or `Writing orthomosaic GeoTIFF`	Single step with names considering tiles types
`write_pcl()`	`Writing SLPK point cloud`	Single step
`write_mesh()`	`Writing SLPK mesh`	Single step
`write_mesh()`	`Exporting mesh to FBX`	Single step
`pix4dvortex.io.obj._write_lod_mesh`	`Writing OBJ LoD mesh`	Single step

Stop functions¶

Major processing and export functions accept an optional stop_function parameter for cooperative cancellation. The callable has the form Callable[[], bool]: it takes no arguments and returns True to request that processing stop.

Processing functions poll stop_function at internal checkpoints during long-running work. When the callback returns True, processing stops promptly. Many APIs raise pix4dvortex.proc.StopProcessing (a subclass of RuntimeError, typically with message "Cancelled"); where behavior differs, it is noted in the table below.

Pass None to disable cancellation requests. When no stop function is provided, processing runs to completion unless another error occurs.

Example:

from pix4dvortex import calib, proc

cancel_requested = False

def stop_me() -> bool:
    return cancel_requested

try:
    calibrated_scene = calib.calibrate(
        cameras=projected_cameras,
        settings=calib.Settings(),
        stop_function=stop_me,
    )
except proc.StopProcessing:
    print("Calibration cancelled.")

The table below lists every API that exposes stop_function. It matches the set in Progress callbacks, except that write_pcl() and write_geotiff() support progress reporting but not cooperative cancellation.

Stop functions¶
API	Notes
`make_input_cameras()`	Cooperative cancel during camera creation
`calibrate()`	Raises `StopProcessing` on cancel
`reoptimize()`	Raises `StopProcessing` on cancel
`densification()`	Raises `StopProcessing` on cancel
`gen_pcl()`	Raises `StopProcessing` on cancel
`pcl_merge()`	Raises `StopProcessing` on cancel
`detect_gcp_marks()`	Cooperative cancel during target detection
`gen_segment_masks()`	Cooperative cancel during mask generation
`alignment()`	Cooperative cancel during alignment
`gen_tiled_dsm()`	Raises `StopProcessing` on cancel
`gen_dsm()`	Raises `StopProcessing` on cancel
`gen_tiled_dtm()`	Raises `StopProcessing` on cancel
`gen_dtm()`	Raises `StopProcessing` on cancel
`gen_tiled_orthomosaic()`	Raises `StopProcessing` on cancel
`gen_orthomosaic()`	Raises `StopProcessing` on cancel
`gen_mesh_geometry()`	Raises `StopProcessing` on cancel
`gen_mesh_texture()`	Raises `StopProcessing` on cancel
`gen_textured_mesh_lod()`	Raises `StopProcessing` on cancel
`gen_mesh()`	Raises `StopProcessing` on cancel
`gen_gs()`	Raises `StopProcessing` on cancel
`~pix4dvortex.gsplat._gen_gs_rasters`	Raises `StopProcessing` on cancel
`gen_gs_dsm()`	Raises `StopProcessing` on cancel
`calibrate()`	Raises `StopProcessing` on cancel
`gen_tiled_orthomosaic()`	Raises `StopProcessing` on cancel
`gen_orthomosaic()`	Raises `StopProcessing` on cancel
`write_pcl()`	Cooperative cancel during export
`write_mesh()`	Cooperative cancel during export
`write_mesh()`	Raises `StopProcessing` on cancel
`pix4dvortex.io.obj._write_lod_mesh`	Cooperative cancel during export