mascaf.cgal¶

Optional CGAL-backed native preprocessing for MASCAF.

Provides Python wrappers around three compiled C++ executables:

mesh_repair — attempt to produce a watertight mesh.
mesh_simplify — reduce mesh face count.
mesh_skeletonize — extract a mean-curvature skeleton as a polylines file.

The executables are built separately from the cpp/ directory using CMake and vcpkg. See Skeletonization for setup instructions.

Classes¶

CGALConfig: Locate executables and configure CMake.
CGALBuilder: Run CMake configure/build and discover executables.
CGALOperator: High-level Python methods for each CGAL operation.
CGALCommandResult: Immutable record of a completed CGAL subprocess invocation.

exception mascaf.cgal.CGALError[source]¶

Bases: RuntimeError

Base exception for all CGAL integration errors.

exception mascaf.cgal.CGALBuildError[source]¶

Bases: CGALError

Raised when a CMake configure or build step fails.

class mascaf.cgal.CGALCommandResult(operation, command, input_path, output_path, stdout, stderr, returncode)[source]¶

Bases: object

Immutable record of a completed CGAL executable invocation.

Parameters:

operation (str)
command (tuple[str, ...])
input_path (Path)
output_path (Path)
stdout (str)
stderr (str)
returncode (int)

operation¶

Name of the CGAL operation (e.g. "mesh_skeletonize").

Type:: str

command¶

Full command line that was executed.

Type:: tuple[str, ]

input_path¶

Path to the input file passed to the executable.

Type:: Path

output_path¶

Path to the output file produced by the executable.

Type:: Path

stdout¶

Captured standard output from the process.

Type:: str

stderr¶

Captured standard error from the process.

Type:: str

returncode¶

Exit code returned by the process.

Type:: int

operation: str¶

command: tuple[str, ...]¶

input_path: Path¶

output_path: Path¶

stdout: str¶

stderr: str¶

returncode: int¶

__init__(operation, command, input_path, output_path, stdout, stderr, returncode)¶

Parameters:

operation (str)
command (tuple[str, ...])
input_path (Path)
output_path (Path)
stdout (str)
stderr (str)
returncode (int)

Return type:

None

class mascaf.cgal.CGALConfig(cpp_dir=<factory>, executable_dir=None, build_dir=None, cmake_executable='cmake', vcpkg_toolchain_file=None, build_configs=('Release', 'Debug', 'RelWithDebInfo', 'MinSizeRel'), executable_suffix='')[source]¶

Bases: object

Configuration for locating and invoking CGAL executables and CMake.

Parameters:

cpp_dir (Path)
executable_dir (Path | None)
build_dir (Path | None)
cmake_executable (str)
vcpkg_toolchain_file (Path | None)
build_configs (tuple[str, ...])
executable_suffix (str)

cpp_dir¶

Root of the native C++ source tree (default: <repo>/cpp/).

Type:: Path

executable_dir¶

Explicit directory to search first for compiled executables. If None, the search falls back to build subdirectories and the MASCAF_CGAL_BIN_DIR environment variable.

Type:: Path or None

build_dir¶

CMake build directory. If None, resolved from MASCAF_CGAL_BUILD_DIR or <cpp_dir>/build.

Type:: Path or None

cmake_executable¶

Name or full path of the cmake executable (default: "cmake").

Type:: str

vcpkg_toolchain_file¶

Path to the vcpkg CMake toolchain file. Auto-detected from VCPKG_ROOT if not set.

Type:: Path or None

build_configs¶

CMake build configurations to search when looking for executables (default: Release, Debug, RelWithDebInfo, MinSizeRel).

Type:: tuple[str, ]

executable_suffix¶

Platform-specific suffix appended to executable names (".exe" on Windows, "" elsewhere).

Type:: str

cpp_dir: Path¶

executable_dir: Path | None = None¶

build_dir: Path | None = None¶

cmake_executable: str = 'cmake'¶

vcpkg_toolchain_file: Path | None = None¶

build_configs: tuple[str, ...] = ('Release', 'Debug', 'RelWithDebInfo', 'MinSizeRel')¶

executable_suffix: str = ''¶

classmethod from_overrides(*, cpp_dir=None, executable_dir=None, build_dir=None, cmake_executable='cmake', vcpkg_toolchain_file=None)[source]¶

Construct a CGALConfig from optional keyword overrides.

Any argument left as None falls back to the class default. This is the preferred factory when building a config from CLI arguments or environment variables.

Return type:

CGALConfig

Parameters:

cpp_dir (str | Path | None)
executable_dir (str | Path | None)
build_dir (str | Path | None)
cmake_executable (str)
vcpkg_toolchain_file (str | Path | None)

default_build_dir()[source]¶

Return the effective CMake build directory.

Priority order:

build_dir set on this config instance.
MASCAF_CGAL_BUILD_DIR environment variable.
<cpp_dir>/build (fallback).

Return type:: Path

__init__(cpp_dir=<factory>, executable_dir=None, build_dir=None, cmake_executable='cmake', vcpkg_toolchain_file=None, build_configs=('Release', 'Debug', 'RelWithDebInfo', 'MinSizeRel'), executable_suffix='')¶

Parameters:

cpp_dir (Path)
executable_dir (Path | None)
build_dir (Path | None)
cmake_executable (str)
vcpkg_toolchain_file (Path | None)
build_configs (tuple[str, ...])
executable_suffix (str)

Return type:

None

class mascaf.cgal.CGALBuilder(config=None, **config_kwargs)[source]¶

Bases: object

Handles CMake configure/build orchestration and executable discovery.

CGALBuilder knows how to:

Construct the cmake configure and build commands from a CGALConfig.
Search a prioritised list of directories for compiled CGAL executables.
Run subprocesses and surface errors cleanly.

Parameters:

config (CGALConfig | None) – Configuration to use. If None, a default CGALConfig is constructed, optionally accepting extra keyword arguments that are forwarded to CGALConfig.from_overrides().
**config_kwargs – Forwarded to CGALConfig.from_overrides() when config is None.

__init__(config=None, **config_kwargs)[source]¶

Parameters:: config (CGALConfig | None)
Return type:: None

executable_filename(operation)[source]¶

Return the platform-appropriate filename for a CGAL executable.

Parameters:: operation (str) – Base name of the operation (e.g. "mesh_skeletonize").
Returns:: Filename with the platform suffix applied.
Return type:: str

candidate_build_dirs()[source]¶

Return an ordered list of directories likely to contain build output.

Includes the build root itself plus each configured build-type subdirectory (e.g. build/Release).

Return type:: list[Path]

candidate_executable_dirs()[source]¶

Return a deduplicated, priority-ordered list of directories to search for CGAL executables.

Priority order:

CGALConfig.executable_dir (if set).
MASCAF_CGAL_BIN_DIR environment variable (if set).
Each candidate build directory from candidate_build_dirs().
CGALConfig.cpp_dir itself.

Return type:: list[Path]

resolve_executable(operation)[source]¶

Locate the compiled executable for operation.

Parameters:: operation (str) – Base name of the operation (e.g. "mesh_skeletonize").
Returns:: Absolute path to the first matching executable found.
Return type:: Path
Raises:: CGALExecutableNotFoundError – If the executable is not found in any candidate directory.

configure_command(*, build_dir=None, build_type='Release', generator=None)[source]¶

Build the cmake configure command without running it.

Parameters:

build_dir (str | Path | None) – Override the build directory for this call.
build_type (str) – CMake build type (default: "Release").
generator (str | None) – Optional CMake generator string (e.g. "Ninja").

Returns:

The full command as a list of strings, suitable for subprocess.run().

Return type:

list[str]

build_command(*, build_dir=None, config='Release', target=None)[source]¶

Build the cmake --build command without running it.

Parameters:

build_dir (str | Path | None) – Override the build directory for this call.
config (str) – CMake build configuration (default: "Release").
target (str | None) – Optional build target (e.g. "mesh_skeletonize").

Returns:

The full command as a list of strings.

Return type:

list[str]

run_configure(*, build_dir=None, build_type='Release', generator=None, check=True)[source]¶

Run the CMake configure step.

Parameters:

build_dir (str | Path | None) – Override the build directory for this call.
build_type (str) – CMake build type (default: "Release").
generator (str | None) – Optional CMake generator string.
check (bool) – If True (default), raise CGALBuildError on failure.

Returns:

The completed process record.

Return type:

CompletedProcess[str]

run_build(*, build_dir=None, config='Release', target=None, check=True)[source]¶

Run the CMake build step.

Parameters:

build_dir (str | Path | None) – Override the build directory for this call.
config (str) – CMake build configuration (default: "Release").
target (str | None) – Optional build target to pass to --target.
check (bool) – If True (default), raise CGALBuildError on failure.

Returns:

The completed process record.

Return type:

CompletedProcess[str]

exception mascaf.cgal.CGALExecutableNotFoundError[source]¶

Bases: CGALError

Raised when a required CGAL executable cannot be located.

mascaf.cgal.CGALMeshProcessor¶: alias of CGALOperator

class mascaf.cgal.CGALOperator(config=None, builder=None, **config_kwargs)[source]¶

Bases: object

High-level interface for running CGAL mesh operations.

CGALOperator wraps the three native CGAL executables (mesh_repair, mesh_simplify, mesh_skeletonize) and exposes them as Python methods. Each method resolves the executable, assembles the argument list, runs the process, and returns a CGALCommandResult.

Parameters:

config (CGALConfig | None) – Configuration used to locate executables and set up CMake. If None, a default config is constructed.
builder (CGALBuilder | None) – Provide a pre-built CGALBuilder instead of constructing one from config.
**config_kwargs – Forwarded to CGALConfig.from_overrides() when neither config nor builder is supplied.

__init__(config=None, builder=None, **config_kwargs)[source]¶

Parameters:

config (CGALConfig | None)
builder (CGALBuilder | None)

Return type:

None

repair(input_path, output_path)[source]¶

Run CGAL mesh repair on input_path, writing result to output_path.

Mesh repair fills holes and attempts to produce a valid, watertight triangle mesh suitable for skeletonization.

Parameters:

input_path (str | Path) – Path to the input mesh file (OBJ recommended).
output_path (str | Path) – Path where the repaired mesh will be written.

Returns:

Record of the completed operation.

Return type:

CGALCommandResult

simplify(input_path, output_path, target)[source]¶

Run CGAL mesh simplification on input_path.

Parameters:

input_path (str | Path) – Path to the input mesh file.
output_path (str | Path) – Path where the simplified mesh will be written.
target (int | float) – Simplification target. Values >= 1 are treated as an absolute face count; values in (0, 1) are treated as a ratio of the original face count.

Returns:

Record of the completed operation.

Return type:

CGALCommandResult

Raises:

ValueError – If target is not a positive number.

skeletonize(input_path, output_path, quality_speed_tradeoff=0.5, medially_centered_speed_tradeoff=5.0)[source]¶

Run CGAL mean-curvature skeleton extraction on input_path.

The output is a .polylines.txt file compatible with mascaf.SkeletonGraph.from_txt().

Parameters:

input_path (str | Path) – Path to the input mesh file (must be a closed triangle mesh).
output_path (str | Path) – Path where the skeleton polylines file will be written.
quality_speed_tradeoff (float) – CGAL quality_speed_tradeoff parameter (w_H). Controls the quality–speed balance; higher values favour quality. Default: 0.5.
medially_centered_speed_tradeoff (float) – CGAL medially_centered_speed_tradeoff parameter (w_M). Higher values push the skeleton toward the medial axis. Default: 5.0.

Returns:

Record of the completed operation.

Return type:

CGALCommandResult

suggest_skeletonization_parameters(input_path=None)[source]¶

Return suggested skeletonization parameters for a mesh.

Note

This method currently returns fixed placeholder values. Automatic parameter tuning based on mesh properties is planned for a future release.

Parameters:: input_path (str | Path | None) – Path to the mesh file (reserved for future use).
Returns:: Dictionary with keys quality_speed_tradeoff, medially_centered_speed_tradeoff, and source.
Return type:: dict[str, float | str]