p4gcc 0.0.1__tar.gz

p4gcc-0.0.1/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright 2026, The copyright holders according to COPYING.md
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

p4gcc-0.0.1/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: p4gcc
+Version: 0.0.1
+Summary: Run py4dgeo change analysis from CloudCompare
+Maintainer-email: Dominic Kempf <dominic.kempf@iwr.uni-heidelberg.de>
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: py4dgeo>=1.2.1
+Provides-Extra: tests
+Requires-Dist: pytest; extra == "tests"
+Requires-Dist: pytest-cov; extra == "tests"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx_mdinclude; extra == "docs"
+Requires-Dist: sphinx_rtd_theme; extra == "docs"
+Dynamic: license-file
+
+# Welcome to py4dgeo-cloudcompare
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/dokempf/py4dgeo-cloudcompare/ci.yml?branch=main)](https://github.com/dokempf/py4dgeo-cloudcompare/actions/workflows/ci.yml)
+[![Documentation Status](https://readthedocs.org/projects/py4dgeo-cloudcompare/badge/)](https://py4dgeo-cloudcompare.readthedocs.io/)
+[![codecov](https://codecov.io/gh/dokempf/py4dgeo-cloudcompare/branch/main/graph/badge.svg)](https://codecov.io/gh/dokempf/py4dgeo-cloudcompare)
+
+## Installation
+
+The Python package `py4dgeo_cloudcompare` can be installed from PyPI:
+
+```
+python -m pip install py4dgeo_cloudcompare
+```
+
+## Development installation
+
+If you want to contribute to the development of `py4dgeo_cloudcompare`, we recommend
+the following editable installation from this repository:
+
+```
+git clone git@github.com:dokempf/py4dgeo-cloudcompare.git
+cd py4dgeo-cloudcompare
+python -m pip install --editable .[tests]
+```
+
+Having done so, the test suite can be run using `pytest`:
+
+```
+python -m pytest
+```
+
+## CloudCompare plugin
+
+This package provides a Python M3C2 plugin for
+[CloudCompare-PythonRuntime](https://tmontaigu.github.io/CloudCompare-PythonRuntime/getting_started.html#plugin).
+Install the package into the Python environment used by CloudCompare:
+
+```console
+python -m pip install .
+```
+
+After restarting CloudCompare, run
+**Compute M3C2 (py4dgeo)** from the Python action launcher or the Python
+plugins menu. The modeless dialog can be opened before any point clouds are
+loaded. Its pickers update while clouds are loaded into CloudCompare and let
+you assign the reference, compared, and core point clouds. An existing
+selection is used only to choose convenient defaults. The dialog also
+configures normal radii, projection radius and depth,
+registration error, normal orientation, and robust aggregation.
+
+The result is added to CloudCompare as a new point cloud at the core-point
+locations. It displays the signed M3C2 distance and also contains scalar
+fields for the level of detection, cloud spreads and sample counts, computed
+normal components, and selected normal radius. CloudCompare global shifts and
+scales are respected when clouds use different local coordinate systems.
+CloudCompare discovers the plugin through the `cloudcompare.plugins` package
+entry point declared in `pyproject.toml`.
+
+## Acknowledgments
+
+This repository was set up using the [SSC Cookiecutter for Python Packages](https://github.com/ssciwr/cookiecutter-python-package).

p4gcc-0.0.1/README.md

@@ -0,0 +1,62 @@
+# Welcome to py4dgeo-cloudcompare
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/dokempf/py4dgeo-cloudcompare/ci.yml?branch=main)](https://github.com/dokempf/py4dgeo-cloudcompare/actions/workflows/ci.yml)
+[![Documentation Status](https://readthedocs.org/projects/py4dgeo-cloudcompare/badge/)](https://py4dgeo-cloudcompare.readthedocs.io/)
+[![codecov](https://codecov.io/gh/dokempf/py4dgeo-cloudcompare/branch/main/graph/badge.svg)](https://codecov.io/gh/dokempf/py4dgeo-cloudcompare)
+
+## Installation
+
+The Python package `py4dgeo_cloudcompare` can be installed from PyPI:
+
+```
+python -m pip install py4dgeo_cloudcompare
+```
+
+## Development installation
+
+If you want to contribute to the development of `py4dgeo_cloudcompare`, we recommend
+the following editable installation from this repository:
+
+```
+git clone git@github.com:dokempf/py4dgeo-cloudcompare.git
+cd py4dgeo-cloudcompare
+python -m pip install --editable .[tests]
+```
+
+Having done so, the test suite can be run using `pytest`:
+
+```
+python -m pytest
+```
+
+## CloudCompare plugin
+
+This package provides a Python M3C2 plugin for
+[CloudCompare-PythonRuntime](https://tmontaigu.github.io/CloudCompare-PythonRuntime/getting_started.html#plugin).
+Install the package into the Python environment used by CloudCompare:
+
+```console
+python -m pip install .
+```
+
+After restarting CloudCompare, run
+**Compute M3C2 (py4dgeo)** from the Python action launcher or the Python
+plugins menu. The modeless dialog can be opened before any point clouds are
+loaded. Its pickers update while clouds are loaded into CloudCompare and let
+you assign the reference, compared, and core point clouds. An existing
+selection is used only to choose convenient defaults. The dialog also
+configures normal radii, projection radius and depth,
+registration error, normal orientation, and robust aggregation.
+
+The result is added to CloudCompare as a new point cloud at the core-point
+locations. It displays the signed M3C2 distance and also contains scalar
+fields for the level of detection, cloud spreads and sample counts, computed
+normal components, and selected normal radius. CloudCompare global shifts and
+scales are respected when clouds use different local coordinate systems.
+CloudCompare discovers the plugin through the `cloudcompare.plugins` package
+entry point declared in `pyproject.toml`.
+
+## Acknowledgments
+
+This repository was set up using the [SSC Cookiecutter for Python Packages](https://github.com/ssciwr/cookiecutter-python-package).

p4gcc-0.0.1/pyproject.toml

@@ -0,0 +1,59 @@
+# This section describes the requirements of the build/installation
+# process itself. Being able to do this was the original reason to
+# introduce pyproject.toml
+[build-system]
+requires = [
+    "setuptools >=61",
+]
+build-backend = "setuptools.build_meta"
+
+# This section provides general project metadata that is used across
+# a variety of build tools. Notably, the version specified here is the
+# single source of truth for py4dgeo_cloudcompare's version
+[project]
+name = "p4gcc"
+description = "Run py4dgeo change analysis from CloudCompare"
+readme = "README.md"
+maintainers = [
+    { name = "Dominic Kempf", email = "dominic.kempf@iwr.uni-heidelberg.de" },
+]
+version = "0.0.1"
+requires-python = ">=3.10"
+license-files = ["LICEN[CS]E*"]
+license = "MIT"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "py4dgeo>=1.2.1",
+]
+
+[project.entry-points."cloudcompare.plugins"]
+hello = "py4dgeo_cloudcompare.plugin:HelloWorldPlugin"
+m3c2 = "py4dgeo_cloudcompare.m3c2:M3C2Plugin"
+qt_versions = "py4dgeo_cloudcompare.qt_versions:QtVersionsPlugin"
+
+[project.optional-dependencies]
+tests = [
+    "pytest",
+    "pytest-cov",
+]
+docs = [
+    "sphinx",
+    "sphinx_mdinclude",
+    "sphinx_rtd_theme",
+]
+
+
+# The following section contains setuptools-specific configuration
+# options. For a full reference of available options, check the overview
+# at https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# The following is the configuration for the pytest test suite
+[tool.pytest.ini_options]
+testpaths = [
+    "tests",
+]

p4gcc-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

p4gcc-0.0.1/src/p4gcc.egg-info/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: p4gcc
+Version: 0.0.1
+Summary: Run py4dgeo change analysis from CloudCompare
+Maintainer-email: Dominic Kempf <dominic.kempf@iwr.uni-heidelberg.de>
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: py4dgeo>=1.2.1
+Provides-Extra: tests
+Requires-Dist: pytest; extra == "tests"
+Requires-Dist: pytest-cov; extra == "tests"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx_mdinclude; extra == "docs"
+Requires-Dist: sphinx_rtd_theme; extra == "docs"
+Dynamic: license-file
+
+# Welcome to py4dgeo-cloudcompare
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/dokempf/py4dgeo-cloudcompare/ci.yml?branch=main)](https://github.com/dokempf/py4dgeo-cloudcompare/actions/workflows/ci.yml)
+[![Documentation Status](https://readthedocs.org/projects/py4dgeo-cloudcompare/badge/)](https://py4dgeo-cloudcompare.readthedocs.io/)
+[![codecov](https://codecov.io/gh/dokempf/py4dgeo-cloudcompare/branch/main/graph/badge.svg)](https://codecov.io/gh/dokempf/py4dgeo-cloudcompare)
+
+## Installation
+
+The Python package `py4dgeo_cloudcompare` can be installed from PyPI:
+
+```
+python -m pip install py4dgeo_cloudcompare
+```
+
+## Development installation
+
+If you want to contribute to the development of `py4dgeo_cloudcompare`, we recommend
+the following editable installation from this repository:
+
+```
+git clone git@github.com:dokempf/py4dgeo-cloudcompare.git
+cd py4dgeo-cloudcompare
+python -m pip install --editable .[tests]
+```
+
+Having done so, the test suite can be run using `pytest`:
+
+```
+python -m pytest
+```
+
+## CloudCompare plugin
+
+This package provides a Python M3C2 plugin for
+[CloudCompare-PythonRuntime](https://tmontaigu.github.io/CloudCompare-PythonRuntime/getting_started.html#plugin).
+Install the package into the Python environment used by CloudCompare:
+
+```console
+python -m pip install .
+```
+
+After restarting CloudCompare, run
+**Compute M3C2 (py4dgeo)** from the Python action launcher or the Python
+plugins menu. The modeless dialog can be opened before any point clouds are
+loaded. Its pickers update while clouds are loaded into CloudCompare and let
+you assign the reference, compared, and core point clouds. An existing
+selection is used only to choose convenient defaults. The dialog also
+configures normal radii, projection radius and depth,
+registration error, normal orientation, and robust aggregation.
+
+The result is added to CloudCompare as a new point cloud at the core-point
+locations. It displays the signed M3C2 distance and also contains scalar
+fields for the level of detection, cloud spreads and sample counts, computed
+normal components, and selected normal radius. CloudCompare global shifts and
+scales are respected when clouds use different local coordinate systems.
+CloudCompare discovers the plugin through the `cloudcompare.plugins` package
+entry point declared in `pyproject.toml`.
+
+## Acknowledgments
+
+This repository was set up using the [SSC Cookiecutter for Python Packages](https://github.com/ssciwr/cookiecutter-python-package).

p4gcc-0.0.1/src/p4gcc.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE.md
+README.md
+pyproject.toml
+src/p4gcc.egg-info/PKG-INFO
+src/p4gcc.egg-info/SOURCES.txt
+src/p4gcc.egg-info/dependency_links.txt
+src/p4gcc.egg-info/entry_points.txt
+src/p4gcc.egg-info/requires.txt
+src/p4gcc.egg-info/top_level.txt
+src/py4dgeo_cloudcompare/__init__.py
+src/py4dgeo_cloudcompare/m3c2.py
+src/py4dgeo_cloudcompare/plugin.py
+src/py4dgeo_cloudcompare/qt_versions.py
+tests/test_m3c2.py
+tests/test_plugin.py
+tests/test_py4dgeo_cloudcompare.py
+tests/test_qt_versions.py

p4gcc-0.0.1/src/p4gcc.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

p4gcc-0.0.1/src/p4gcc.egg-info/entry_points.txt

@@ -0,0 +1,4 @@
+[cloudcompare.plugins]
+hello = py4dgeo_cloudcompare.plugin:HelloWorldPlugin
+m3c2 = py4dgeo_cloudcompare.m3c2:M3C2Plugin
+qt_versions = py4dgeo_cloudcompare.qt_versions:QtVersionsPlugin

p4gcc-0.0.1/src/p4gcc.egg-info/requires.txt

@@ -0,0 +1,10 @@
+py4dgeo>=1.2.1
+
+[docs]
+sphinx
+sphinx_mdinclude
+sphinx_rtd_theme
+
+[tests]
+pytest
+pytest-cov

p4gcc-0.0.1/src/p4gcc.egg-info/top_level.txt

@@ -0,0 +1 @@
+py4dgeo_cloudcompare

p4gcc-0.0.1/src/py4dgeo_cloudcompare/__init__.py

@@ -0,0 +1,13 @@
+from importlib import metadata
+
+__version__ = metadata.version(__package__)
+del metadata
+
+
+def add_one(x: int):
+    """An example function that increases a number
+
+    :param x: The input parameter to increase
+    :return: The successor of the given number
+    """
+    return x + 1

p4gcc-0.0.1/src/py4dgeo_cloudcompare/m3c2.py

@@ -0,0 +1,424 @@
+"""CloudCompare front end for :class:`py4dgeo.M3C2`.
+
+The imports of py4dgeo and PySide6 deliberately happen when the action is
+executed.  CloudCompare can therefore discover the plugin even while its
+Python environment is still being configured, and the numerical parts of
+this module can be tested without a Qt application.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Sequence
+
+import numpy as np
+import pycc
+
+
+@dataclass(frozen=True)
+class M3C2Parameters:
+    """Parameters exposed by the M3C2 dialog, in py4dgeo units."""
+
+    normal_radii: tuple[float, ...] = (0.5, 1.0, 2.0)
+    cylinder_radius: float = 1.0
+    max_distance: float = 0.0
+    registration_error: float = 0.0
+    orientation_vector: tuple[float, float, float] = (0.0, 0.0, 1.0)
+    robust_aggregation: bool = False
+
+
+@dataclass(frozen=True)
+class M3C2Result:
+    """Numerical result used to construct a CloudCompare point cloud."""
+
+    distances: np.ndarray
+    uncertainties: np.ndarray
+    normals: np.ndarray
+    normal_radii: np.ndarray
+
+
+def parse_normal_radii(value: str) -> tuple[float, ...]:
+    """Parse a comma/semicolon/whitespace separated list of positive radii."""
+
+    tokens = value.replace(";", " ").replace(",", " ").split()
+    if not tokens:
+        raise ValueError("Specify at least one normal radius.")
+    radii = tuple(float(token) for token in tokens)
+    if any(not np.isfinite(radius) or radius <= 0.0 for radius in radii):
+        raise ValueError("Normal radii must be finite and greater than zero.")
+    return radii
+
+
+def calculate_m3c2(
+    reference_points: np.ndarray,
+    compared_points: np.ndarray,
+    core_points: np.ndarray,
+    parameters: M3C2Parameters,
+) -> M3C2Result:
+    """Run py4dgeo M3C2 on three ``(n, 3)`` coordinate arrays."""
+
+    from py4dgeo import Epoch, M3C2
+
+    reference = Epoch(_points_array(reference_points, "reference cloud"))
+    compared = Epoch(_points_array(compared_points, "compared cloud"))
+    core = _points_array(core_points, "core points")
+
+    orientation = np.asarray(parameters.orientation_vector, dtype=np.float64)
+    if orientation.shape != (3,) or not np.isfinite(orientation).all():
+        raise ValueError("The orientation vector must contain three finite values.")
+    if np.linalg.norm(orientation) == 0.0:
+        raise ValueError("The orientation vector must not be zero.")
+    if parameters.cylinder_radius <= 0.0:
+        raise ValueError("The projection cylinder radius must be greater than zero.")
+    if not parameters.normal_radii or any(
+        not np.isfinite(radius) or radius <= 0.0 for radius in parameters.normal_radii
+    ):
+        raise ValueError("Normal radii must be finite and greater than zero.")
+    if parameters.max_distance < 0.0 or parameters.registration_error < 0.0:
+        raise ValueError("Maximum depth and registration error cannot be negative.")
+
+    algorithm = M3C2(
+        epochs=(reference, compared),
+        corepoints=core,
+        cyl_radius=float(parameters.cylinder_radius),
+        normal_radii=list(parameters.normal_radii),
+        max_distance=float(parameters.max_distance),
+        registration_error=float(parameters.registration_error),
+        orientation_vector=orientation,
+        robust_aggr=parameters.robust_aggregation,
+    )
+    distances, uncertainties = algorithm.run()
+    return M3C2Result(
+        distances=np.asarray(distances),
+        uncertainties=uncertainties,
+        normals=np.asarray(algorithm.directions()),
+        normal_radii=np.asarray(algorithm.directions_radii()).reshape(-1),
+    )
+
+
+def _points_array(points: np.ndarray, description: str) -> np.ndarray:
+    array = np.ascontiguousarray(points, dtype=np.float64)
+    if array.ndim != 2 or array.shape[1] != 3 or array.shape[0] == 0:
+        raise ValueError(f"The {description} must be a non-empty (n, 3) array.")
+    if not np.isfinite(array).all():
+        raise ValueError(f"The {description} contains non-finite coordinates.")
+    return array
+
+
+def _cloud_name(cloud: Any) -> str:
+    return str(cloud.getName())
+
+
+def _global_points(cloud: Any) -> np.ndarray:
+    """Return CloudCompare local points in their global coordinate system."""
+
+    points = np.asarray(cloud.points(), dtype=np.float64).copy()
+    shift_value = cloud.getGlobalShift()
+    shift = np.array([shift_value.x, shift_value.y, shift_value.z])
+    scale = float(cloud.getGlobalScale())
+    if scale == 0.0:
+        raise ValueError(f"Cloud '{_cloud_name(cloud)}' has a zero global scale.")
+    # CloudCompare stores local = (global + shift) * scale.
+    return points / scale - shift
+
+
+def _loaded_point_clouds(app: Any) -> list[Any]:
+    """Collect point clouds recursively from CloudCompare's database tree."""
+
+    root = app.dbRootObject()
+    if root is None:
+        return []
+
+    clouds: list[Any] = []
+    pending = [root]
+    while pending:
+        entity = pending.pop()
+        if isinstance(entity, pycc.ccPointCloud):
+            clouds.append(entity)
+        pending.extend(
+            entity.getChild(index)
+            for index in reversed(range(entity.getChildrenNumber()))
+        )
+    return clouds
+
+
+def _preferred_cloud_indices(app: Any, clouds: Sequence[Any]) -> tuple[int, int]:
+    """Use the current selection as defaults without requiring a selection."""
+
+    selected_ids = {
+        entity.getUniqueID()
+        for entity in app.getSelectedEntities()
+        if isinstance(entity, pycc.ccPointCloud)
+    }
+    selected_indices = [
+        index
+        for index, cloud in enumerate(clouds)
+        if cloud.getUniqueID() in selected_ids
+    ]
+    if len(selected_indices) >= 2:
+        return selected_indices[0], selected_indices[1]
+    if len(selected_indices) == 1:
+        other = 0 if selected_indices[0] != 0 else 1
+        return selected_indices[0], other
+    return 0, 1
+
+
+def create_result_cloud(
+    core_cloud: Any,
+    result: M3C2Result,
+    name: str,
+) -> Any:
+    """Create a display-ready CloudCompare cloud with M3C2 scalar fields."""
+
+    local_core_points = np.asarray(core_cloud.points(), dtype=pycc.PointCoordinateType)
+    output = pycc.ccPointCloud(
+        np.ascontiguousarray(local_core_points[:, 0]),
+        np.ascontiguousarray(local_core_points[:, 1]),
+        np.ascontiguousarray(local_core_points[:, 2]),
+    )
+    output.setName(name)
+
+    shift = core_cloud.getGlobalShift()
+    output.setGlobalShift(shift.x, shift.y, shift.z)
+    output.setGlobalScale(core_cloud.getGlobalScale())
+
+    fields = (
+        ("M3C2 distance", result.distances),
+        ("M3C2 LoD", result.uncertainties["lodetection"]),
+        ("M3C2 spread cloud 1", result.uncertainties["spread1"]),
+        ("M3C2 spread cloud 2", result.uncertainties["spread2"]),
+        ("M3C2 samples cloud 1", result.uncertainties["num_samples1"]),
+        ("M3C2 samples cloud 2", result.uncertainties["num_samples2"]),
+        ("M3C2 normal X", result.normals[:, 0]),
+        ("M3C2 normal Y", result.normals[:, 1]),
+        ("M3C2 normal Z", result.normals[:, 2]),
+        ("M3C2 normal radius", result.normal_radii),
+    )
+    distance_index = -1
+    for field_name, values in fields:
+        values = np.asarray(values, dtype=pycc.ScalarType).reshape(-1)
+        if values.size != local_core_points.shape[0]:
+            raise ValueError(f"Result field '{field_name}' has an unexpected size.")
+        index = output.addScalarField(field_name, values)
+        output.getScalarField(index).computeMinAndMax()
+        if field_name == "M3C2 distance":
+            distance_index = index
+
+    output.setCurrentDisplayedScalarField(distance_index)
+    output.showSF(True)
+    output.showSFColorsScale(True)
+    return output
+
+
+class _M3C2Dialog:
+    """Small wrapper that keeps Qt imports local to GUI execution."""
+
+    def __init__(self, app: Any):
+        from PySide6 import QtCore, QtWidgets
+
+        self.QtWidgets = QtWidgets
+        self.app = app
+        self.clouds: list[Any] = []
+        self.dialog = QtWidgets.QDialog(QtWidgets.QApplication.activeWindow())
+        self.dialog.setWindowTitle("py4dgeo M3C2")
+        self.dialog.setMinimumWidth(480)
+        layout = QtWidgets.QVBoxLayout(self.dialog)
+        description = QtWidgets.QLabel(
+            "Compute signed M3C2 distances for selected CloudCompare point clouds."
+        )
+        description.setWordWrap(True)
+        layout.addWidget(description)
+        form = QtWidgets.QFormLayout()
+        layout.addLayout(form)
+
+        self.reference = QtWidgets.QComboBox()
+        self.compared = QtWidgets.QComboBox()
+        self.core = QtWidgets.QComboBox()
+        form.addRow("Reference cloud", self.reference)
+        form.addRow("Compared cloud", self.compared)
+        form.addRow("Core points", self.core)
+        self.cloud_status = QtWidgets.QLabel()
+        self.refresh_button = QtWidgets.QPushButton("Refresh point clouds")
+        self.refresh_button.clicked.connect(self.refresh_clouds)
+        cloud_controls = QtWidgets.QHBoxLayout()
+        cloud_controls.addWidget(self.cloud_status)
+        cloud_controls.addStretch()
+        cloud_controls.addWidget(self.refresh_button)
+        form.addRow("", cloud_controls)
+
+        self.normal_radii = QtWidgets.QLineEdit("0.5, 1.0, 2.0")
+        self.normal_radii.setToolTip("One or more py4dgeo search radii, separated by commas")
+        form.addRow("Normal radii", self.normal_radii)
+        self.cylinder_radius = self._spin(1.0, 1.0e-9)
+        form.addRow("Projection cylinder radius", self.cylinder_radius)
+        self.max_distance = self._spin(0.0, 0.0)
+        self.max_distance.setSpecialValueText("Automatic")
+        form.addRow("Maximum projection depth", self.max_distance)
+        self.registration_error = self._spin(0.0, 0.0)
+        form.addRow("Registration error", self.registration_error)
+
+        orientation = QtWidgets.QHBoxLayout()
+        self.orientation = []
+        for label, initial in zip("XYZ", (0.0, 0.0, 1.0)):
+            orientation.addWidget(QtWidgets.QLabel(label))
+            widget = self._spin(initial, -1.0e12)
+            widget.setMaximum(1.0e12)
+            self.orientation.append(widget)
+            orientation.addWidget(widget)
+        form.addRow("Normal orientation vector", orientation)
+        self.robust = QtWidgets.QCheckBox("Use median and IQR")
+        form.addRow("Robust aggregation", self.robust)
+        self.output_name = QtWidgets.QLineEdit("M3C2 result")
+        form.addRow("Output cloud name", self.output_name)
+
+        buttons = QtWidgets.QDialogButtonBox(
+            QtWidgets.QDialogButtonBox.StandardButton.Ok
+            | QtWidgets.QDialogButtonBox.StandardButton.Cancel
+        )
+        buttons.button(QtWidgets.QDialogButtonBox.StandardButton.Ok).setText("Compute")
+        buttons.accepted.connect(self._validate_and_accept)
+        buttons.rejected.connect(self.dialog.reject)
+        layout.addWidget(buttons)
+        self._align_center = QtCore.Qt.AlignmentFlag.AlignCenter
+        description.setAlignment(self._align_center)
+
+        # Keep the picker synchronized while the modeless dialog is open. This
+        # lets users load point clouds after launching the plugin.
+        self._refresh_timer = QtCore.QTimer(self.dialog)
+        self._refresh_timer.setInterval(1000)
+        self._refresh_timer.timeout.connect(self.refresh_clouds)
+        self._refresh_timer.start()
+        self.refresh_clouds(use_selection_defaults=True)
+
+    @staticmethod
+    def _cloud_label(cloud: Any) -> str:
+        return f"{_cloud_name(cloud)}  [ID {cloud.getUniqueID()}]"
+
+    @staticmethod
+    def _cloud_id(cloud: Any) -> Any:
+        return cloud.getUniqueID()
+
+    def refresh_clouds(self, use_selection_defaults: bool = False) -> None:
+        """Refresh the pickers while preserving the current assignments."""
+
+        combos = (self.reference, self.compared, self.core)
+        selected_ids = []
+        for combo in combos:
+            index = combo.currentIndex()
+            selected_ids.append(
+                self._cloud_id(self.clouds[index])
+                if 0 <= index < len(self.clouds)
+                else None
+            )
+
+        clouds = _loaded_point_clouds(self.app)
+        cloud_ids = [self._cloud_id(cloud) for cloud in clouds]
+        if cloud_ids == [self._cloud_id(cloud) for cloud in self.clouds]:
+            if len(clouds) == 0:
+                self.cloud_status.setText("No point clouds loaded")
+            return
+
+        self.clouds = clouds
+        labels = [self._cloud_label(cloud) for cloud in clouds]
+        if use_selection_defaults and len(clouds) >= 2:
+            reference_index, compared_index = _preferred_cloud_indices(self.app, clouds)
+            default_indices = (reference_index, compared_index, reference_index)
+        else:
+            default_indices = (0, 1, 0)
+
+        for combo, selected_id, default_index in zip(
+            combos, selected_ids, default_indices
+        ):
+            combo.clear()
+            combo.addItems(labels)
+            if selected_id in cloud_ids:
+                combo.setCurrentIndex(cloud_ids.index(selected_id))
+            elif default_index < len(clouds):
+                combo.setCurrentIndex(default_index)
+
+        if len(clouds) == 0:
+            self.cloud_status.setText("No point clouds loaded")
+        elif len(clouds) == 1:
+            self.cloud_status.setText("Load one more point cloud")
+        else:
+            self.cloud_status.setText(f"{len(clouds)} point clouds available")
+
+    def _spin(self, value: float, minimum: float):
+        widget = self.QtWidgets.QDoubleSpinBox()
+        widget.setDecimals(6)
+        widget.setRange(minimum, 1.0e12)
+        widget.setValue(value)
+        return widget
+
+    def _validate_and_accept(self) -> None:
+        self.refresh_clouds()
+        if len(self.clouds) < 2:
+            raise ValueError(
+                "Load at least two point clouds in CloudCompare before computing."
+            )
+        parameters = self.parameters()
+        if np.linalg.norm(parameters.orientation_vector) == 0.0:
+            raise ValueError("The normal orientation vector must not be zero.")
+        if self.reference.currentIndex() == self.compared.currentIndex():
+            raise ValueError("Reference and compared clouds must be different.")
+        if not self.output_name.text().strip():
+            raise ValueError("Specify a name for the output cloud.")
+        self.dialog.accept()
+
+    def show(self) -> None:
+        self.refresh_clouds()
+        self.dialog.show()
+        self.dialog.raise_()
+        self.dialog.activateWindow()
+
+    def parameters(self) -> M3C2Parameters:
+        return M3C2Parameters(
+            normal_radii=parse_normal_radii(self.normal_radii.text()),
+            cylinder_radius=self.cylinder_radius.value(),
+            max_distance=self.max_distance.value(),
+            registration_error=self.registration_error.value(),
+            orientation_vector=tuple(widget.value() for widget in self.orientation),
+            robust_aggregation=self.robust.isChecked(),
+        )
+
+
+class M3C2Plugin(pycc.PythonPluginInterface):
+    """CloudCompare PythonRuntime plugin exposing py4dgeo M3C2."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.app = pycc.GetInstance()
+        self._dialog: _M3C2Dialog | None = None
+
+    def getActions(self):
+        return [pycc.Action(name="Compute M3C2 (py4dgeo)", target=self.run)]
+
+    def run(self) -> None:
+        if self._dialog is None:
+            self._dialog = _M3C2Dialog(self.app)
+            self._dialog.dialog.accepted.connect(self._compute)
+        self._dialog.show()
+
+    def _compute(self) -> None:
+        """Compute from the assignments captured by the modeless dialog."""
+
+        assert self._dialog is not None
+        dialog = self._dialog
+        clouds = dialog.clouds
+        reference = clouds[dialog.reference.currentIndex()]
+        compared = clouds[dialog.compared.currentIndex()]
+        core = clouds[dialog.core.currentIndex()]
+        result = calculate_m3c2(
+            _global_points(reference),
+            _global_points(compared),
+            _global_points(core),
+            dialog.parameters(),
+        )
+        output = create_result_cloud(core, result, dialog.output_name.text().strip())
+        self.app.addToDB(output, updateZoom=False)
+        self.app.redrawAll()
+        print(
+            f"py4dgeo M3C2: added '{dialog.output_name.text().strip()}' "
+            f"with {output.size()} core points"
+        )
+

p4gcc-0.0.1/src/py4dgeo_cloudcompare/plugin.py

@@ -0,0 +1,18 @@
+"""Minimal CloudCompare Python plugin."""
+
+import pycc
+
+
+def hello_world() -> None:
+    """Print a greeting in CloudCompare's Python console."""
+    print("Hello from Python")
+
+
+class HelloWorldPlugin(pycc.PythonPluginInterface):
+    """Expose a Hello World action in CloudCompare."""
+
+    def __init__(self) -> None:
+        super().__init__()
+
+    def getActions(self):
+        return [pycc.Action(name="Hello World", target=hello_world)]

p4gcc-0.0.1/src/py4dgeo_cloudcompare/qt_versions.py

@@ -0,0 +1,20 @@
+"""CloudCompare plugin for reporting the compile-time and runtime Qt versions."""
+
+import pycc
+
+
+def report_qt_versions() -> None:
+    """Print the Qt versions used to build and run CloudCompare."""
+
+    print(f"Qt compile-time version: {pycc.QT_VERSION_STR}")
+    print(f"Qt runtime version: {pycc.qtVersion()}")
+
+
+class QtVersionsPlugin(pycc.PythonPluginInterface):
+    """Expose Qt version information as a separate CloudCompare action."""
+
+    def __init__(self) -> None:
+        super().__init__()
+
+    def getActions(self):
+        return [pycc.Action(name="Report Qt Versions", target=report_qt_versions)]

p4gcc-0.0.1/tests/test_m3c2.py

@@ -0,0 +1,241 @@
+import importlib
+import sys
+from types import ModuleType
+
+import numpy as np
+import pytest
+
+
+class PythonPluginInterface:
+    pass
+
+
+class Action:
+    def __init__(self, *, name, target, icon=None):
+        self.name = name
+        self.target = target
+        self.icon = icon
+
+
+class PointCloud:
+    pass
+
+
+@pytest.fixture
+def m3c2_module(monkeypatch):
+    pycc = ModuleType("pycc")
+    pycc.PythonPluginInterface = PythonPluginInterface
+    pycc.Action = Action
+    pycc.ccPointCloud = PointCloud
+    pycc.PointCoordinateType = np.float32
+    pycc.ScalarType = np.float32
+    pycc.GetInstance = lambda: None
+    monkeypatch.setitem(sys.modules, "pycc", pycc)
+    sys.modules.pop("py4dgeo_cloudcompare.m3c2", None)
+    return importlib.import_module("py4dgeo_cloudcompare.m3c2")
+
+
+def test_parse_normal_radii(m3c2_module):
+    assert m3c2_module.parse_normal_radii("0.5, 1; 2") == (0.5, 1.0, 2.0)
+
+    for invalid in ("", "one", "0", "-1", "nan"):
+        with pytest.raises(ValueError):
+            m3c2_module.parse_normal_radii(invalid)
+
+
+def test_global_points_applies_cloudcompare_shift_and_scale(m3c2_module):
+    class Shift:
+        x, y, z = (-100.0, 50.0, -2.0)
+
+    class Cloud:
+        def points(self):
+            return np.array([[2.0, 4.0, 6.0]], dtype=np.float32)
+
+        def getGlobalShift(self):
+            return Shift()
+
+        def getGlobalScale(self):
+            return 2.0
+
+    # global = local / scale - shift
+    np.testing.assert_allclose(
+        m3c2_module._global_points(Cloud()), [[101.0, -48.0, 5.0]]
+    )
+
+
+def test_loaded_point_clouds_walks_database_tree(m3c2_module):
+    class Group:
+        def __init__(self, *children):
+            self.children = children
+
+        def getChildrenNumber(self):
+            return len(self.children)
+
+        def getChild(self, index):
+            return self.children[index]
+
+    cloud1 = PointCloud()
+    cloud1.getChildrenNumber = lambda: 0
+    cloud2 = PointCloud()
+    cloud2.getChildrenNumber = lambda: 0
+    root = Group(Group(cloud1), cloud2)
+    app = type("App", (), {"dbRootObject": lambda self: root})()
+
+    assert m3c2_module._loaded_point_clouds(app) == [cloud1, cloud2]
+
+
+def test_selection_only_controls_cloud_defaults(m3c2_module):
+    clouds = [PointCloud(), PointCloud(), PointCloud()]
+    for identifier, cloud in enumerate(clouds, start=10):
+        cloud.getUniqueID = lambda identifier=identifier: identifier
+
+    app = type(
+        "App",
+        (),
+        {"getSelectedEntities": lambda self: [clouds[2], clouds[0]]},
+    )()
+    assert m3c2_module._preferred_cloud_indices(app, clouds) == (0, 2)
+
+
+def test_calculate_m3c2_maps_parameters(monkeypatch, m3c2_module):
+    py4dgeo = ModuleType("py4dgeo")
+
+    class Epoch:
+        def __init__(self, points):
+            self.points = points
+
+    class M3C2:
+        last_kwargs = None
+
+        def __init__(self, **kwargs):
+            M3C2.last_kwargs = kwargs
+            self.count = len(kwargs["corepoints"])
+
+        def run(self):
+            dtype = [
+                ("lodetection", float),
+                ("spread1", float),
+                ("spread2", float),
+                ("num_samples1", int),
+                ("num_samples2", int),
+            ]
+            return np.arange(self.count), np.zeros(self.count, dtype=dtype)
+
+        def directions(self):
+            return np.tile([0.0, 0.0, 1.0], (self.count, 1))
+
+        def directions_radii(self):
+            return np.full((self.count, 1), 2.0)
+
+    py4dgeo.Epoch = Epoch
+    py4dgeo.M3C2 = M3C2
+    monkeypatch.setitem(sys.modules, "py4dgeo", py4dgeo)
+
+    points = np.array([[0, 0, 0], [1, 1, 1]], dtype=np.float32)
+    parameters = m3c2_module.M3C2Parameters(
+        normal_radii=(1.0, 2.0),
+        cylinder_radius=3.0,
+        max_distance=4.0,
+        registration_error=0.2,
+        orientation_vector=(0.0, 1.0, 0.0),
+        robust_aggregation=True,
+    )
+    result = m3c2_module.calculate_m3c2(points, points, points, parameters)
+
+    assert M3C2.last_kwargs["cyl_radius"] == 3.0
+    assert M3C2.last_kwargs["normal_radii"] == [1.0, 2.0]
+    assert M3C2.last_kwargs["max_distance"] == 4.0
+    assert M3C2.last_kwargs["registration_error"] == 0.2
+    assert M3C2.last_kwargs["robust_aggr"] is True
+    assert result.distances.tolist() == [0, 1]
+    assert result.normal_radii.tolist() == [2.0, 2.0]
+
+
+def test_plugin_action(m3c2_module):
+    plugin = m3c2_module.M3C2Plugin()
+    actions = plugin.getActions()
+    assert len(actions) == 1
+    assert actions[0].name == "Compute M3C2 (py4dgeo)"
+
+
+def test_plugin_opens_dialog_without_loaded_clouds(monkeypatch, m3c2_module):
+    shown = []
+
+    class Signal:
+        def connect(self, callback):
+            self.callback = callback
+
+    class Dialog:
+        def __init__(self, app):
+            self.app = app
+            self.dialog = type("Widget", (), {"accepted": Signal()})()
+
+        def show(self):
+            shown.append(True)
+
+    monkeypatch.setattr(m3c2_module, "_M3C2Dialog", Dialog)
+    plugin = m3c2_module.M3C2Plugin()
+    plugin.run()
+    assert shown == [True]
+
+
+def test_plugin_run_propagates_dialog_exception(monkeypatch, m3c2_module):
+    error = RuntimeError("dialog failed")
+
+    class Dialog:
+        def __init__(self, app):
+            raise error
+
+    monkeypatch.setattr(m3c2_module, "_M3C2Dialog", Dialog)
+    plugin = m3c2_module.M3C2Plugin()
+
+    with pytest.raises(RuntimeError) as caught:
+        plugin.run()
+
+    assert caught.value is error
+
+
+def test_dialog_validation_propagates_exception(m3c2_module):
+    dialog = type(
+        "Dialog",
+        (),
+        {
+            "clouds": [],
+            "refresh_clouds": lambda self: None,
+        },
+    )()
+
+    with pytest.raises(ValueError, match="Load at least two point clouds"):
+        m3c2_module._M3C2Dialog._validate_and_accept(dialog)
+
+
+def test_plugin_compute_propagates_raw_exception(monkeypatch, m3c2_module):
+    error = RuntimeError("M3C2 failed")
+    cloud = object()
+    combo = type("Combo", (), {"currentIndex": lambda self: 0})()
+    output_name = type("Name", (), {"text": lambda self: "result"})()
+    dialog = type(
+        "Dialog",
+        (),
+        {
+            "clouds": [cloud],
+            "reference": combo,
+            "compared": combo,
+            "core": combo,
+            "output_name": output_name,
+            "parameters": lambda self: m3c2_module.M3C2Parameters(),
+        },
+    )()
+    monkeypatch.setattr(m3c2_module, "_global_points", lambda cloud: np.empty((1, 3)))
+
+    def fail(*args):
+        raise error
+
+    monkeypatch.setattr(m3c2_module, "calculate_m3c2", fail)
+    plugin = m3c2_module.M3C2Plugin()
+    plugin._dialog = dialog
+
+    with pytest.raises(RuntimeError) as caught:
+        plugin._compute()
+
+    assert caught.value is error

p4gcc-0.0.1/tests/test_plugin.py

@@ -0,0 +1,31 @@
+import importlib
+import sys
+from types import ModuleType
+
+
+class PythonPluginInterface:
+    pass
+
+
+class Action:
+    def __init__(self, *, name, target, icon=None):
+        self.name = name
+        self.target = target
+        self.icon = icon
+
+
+def test_hello_world_plugin(monkeypatch, capsys):
+    pycc = ModuleType("pycc")
+    pycc.PythonPluginInterface = PythonPluginInterface
+    pycc.Action = Action
+    monkeypatch.setitem(sys.modules, "pycc", pycc)
+
+    plugin_module = importlib.import_module("py4dgeo_cloudcompare.plugin")
+    plugin = plugin_module.HelloWorldPlugin()
+    actions = plugin.getActions()
+
+    assert len(actions) == 1
+    assert actions[0].name == "Hello World"
+
+    actions[0].target()
+    assert capsys.readouterr().out == "Hello from Python\n"

p4gcc-0.0.1/tests/test_py4dgeo_cloudcompare.py

@@ -0,0 +1,5 @@
+import py4dgeo_cloudcompare
+
+
+def test_py4dgeo_cloudcompare():
+    assert py4dgeo_cloudcompare.add_one(1) == 2

p4gcc-0.0.1/tests/test_qt_versions.py

@@ -0,0 +1,38 @@
+import importlib
+import sys
+from types import ModuleType
+
+
+class PythonPluginInterface:
+    pass
+
+
+class Action:
+    def __init__(self, *, name, target, icon=None):
+        self.name = name
+        self.target = target
+        self.icon = icon
+
+
+def test_qt_versions_plugin_reports_compile_time_and_runtime_versions(
+    monkeypatch, capsys
+):
+    pycc = ModuleType("pycc")
+    pycc.PythonPluginInterface = PythonPluginInterface
+    pycc.Action = Action
+    pycc.QT_VERSION_STR = "6.8.3"
+    pycc.qtVersion = lambda: "6.8.2"
+    monkeypatch.setitem(sys.modules, "pycc", pycc)
+    sys.modules.pop("py4dgeo_cloudcompare.qt_versions", None)
+
+    plugin_module = importlib.import_module("py4dgeo_cloudcompare.qt_versions")
+    actions = plugin_module.QtVersionsPlugin().getActions()
+
+    assert len(actions) == 1
+    assert actions[0].name == "Report Qt Versions"
+
+    actions[0].target()
+    assert capsys.readouterr().out == (
+        "Qt compile-time version: 6.8.3\n"
+        "Qt runtime version: 6.8.2\n"
+    )