pytlidar-cc 0.1.0__tar.gz

pytlidar_cc-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: pytlidar-cc
+Version: 0.1.0
+Summary: CloudCompare plugin that runs PyTLidar TreeQSM on a selected point cloud
+Author: John Hagood
+License-Expression: GPL-3.0-only
+Project-URL: Homepage, https://github.com/Landscape-CV/PyTLidar
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: <3.13,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PyTLidar>=1.0.6
+
+# pytlidar-cc
+
+CloudCompare plugin that runs [PyTLidar](https://github.com/Landscape-CV/PyTLidar)
+TreeQSM on selected point clouds and puts the models back into the scene.
+
+## What you get
+
+One group per fitted model, named after the source cloud:
+
+- `cylinders`: the cylinder start points with `radius`, `length`,
+  `branch_order`, `branch_id` and `surface_coverage` scalar fields.
+- `cylinder mesh`: the cylinders as one triangle mesh, `branch_order` on its
+  vertices for colouring.
+- `stem mesh` when stem triangulation is on.
+- The tree metrics printed to the console.
+
+Everything is in the source cloud's frame and carries its global shift.
+
+## Requirements
+
+- CloudCompare 2.13 or newer with the PythonRuntime plugin. It ships in the
+  Windows installer and in the OpenFields macOS builds
+  (simulation.openfields.fr); otherwise build it from source.
+- PyTLidar 1.0.6 or newer in the plugin's Python environment.
+
+## Install
+
+With the Python environment CloudCompare uses:
+
+```
+python -m pip install PyTLidar ./pytlidar_cc
+```
+
+## Usage
+
+1. Select one or more point clouds (one segmented tree each).
+2. Plugins, PyTLidar, Run PyTLidar.
+3. Adjust the settings, OK.
+
+Settings: generated or custom PatchDiam values (several values per parameter
+runs every combination and the metric picks the best model), an optional
+scalar field filter, stem triangulation, repeat runs and parallel workers,
+and where the model files save.
+
+## Notes
+
+- Model files (the QSM npz, the cylinder, branch and treedata tables and a
+  run_info.json per run) save into one folder per CloudCompare session,
+  under Documents/PyTLidar/results by default; run numbers continue across
+  jobs in a session.
+- TreeQSM is stochastic. Repeat runs puts each model in the scene as its own
+  group with a console summary that flags suspect fits; keep the tree you
+  like.
+- Fits run in worker processes: progress streams to the console and the job
+  can be cancelled from the progress dialog. Parallel runs each use their
+  own memory, so keep workers low for very large clouds.
+- Segment the tree from the plot first (for example with the Treeiso plugin)
+  and clean obvious noise.
+- A running job holds off system idle sleep so fits continue with the
+  screen locked; closing the lid still sleeps as normal.
+
+## License
+
+GPL-3.0-only, like PyTLidar.

pytlidar_cc-0.1.0/README.md

@@ -0,0 +1,64 @@
+# pytlidar-cc
+
+CloudCompare plugin that runs [PyTLidar](https://github.com/Landscape-CV/PyTLidar)
+TreeQSM on selected point clouds and puts the models back into the scene.
+
+## What you get
+
+One group per fitted model, named after the source cloud:
+
+- `cylinders`: the cylinder start points with `radius`, `length`,
+  `branch_order`, `branch_id` and `surface_coverage` scalar fields.
+- `cylinder mesh`: the cylinders as one triangle mesh, `branch_order` on its
+  vertices for colouring.
+- `stem mesh` when stem triangulation is on.
+- The tree metrics printed to the console.
+
+Everything is in the source cloud's frame and carries its global shift.
+
+## Requirements
+
+- CloudCompare 2.13 or newer with the PythonRuntime plugin. It ships in the
+  Windows installer and in the OpenFields macOS builds
+  (simulation.openfields.fr); otherwise build it from source.
+- PyTLidar 1.0.6 or newer in the plugin's Python environment.
+
+## Install
+
+With the Python environment CloudCompare uses:
+
+```
+python -m pip install PyTLidar ./pytlidar_cc
+```
+
+## Usage
+
+1. Select one or more point clouds (one segmented tree each).
+2. Plugins, PyTLidar, Run PyTLidar.
+3. Adjust the settings, OK.
+
+Settings: generated or custom PatchDiam values (several values per parameter
+runs every combination and the metric picks the best model), an optional
+scalar field filter, stem triangulation, repeat runs and parallel workers,
+and where the model files save.
+
+## Notes
+
+- Model files (the QSM npz, the cylinder, branch and treedata tables and a
+  run_info.json per run) save into one folder per CloudCompare session,
+  under Documents/PyTLidar/results by default; run numbers continue across
+  jobs in a session.
+- TreeQSM is stochastic. Repeat runs puts each model in the scene as its own
+  group with a console summary that flags suspect fits; keep the tree you
+  like.
+- Fits run in worker processes: progress streams to the console and the job
+  can be cancelled from the progress dialog. Parallel runs each use their
+  own memory, so keep workers low for very large clouds.
+- Segment the tree from the plot first (for example with the Treeiso plugin)
+  and clean obvious noise.
+- A running job holds off system idle sleep so fits continue with the
+  screen locked; closing the lid still sleeps as normal.
+
+## License
+
+GPL-3.0-only, like PyTLidar.

pytlidar_cc-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pytlidar-cc"
+version = "0.1.0"
+description = "CloudCompare plugin that runs PyTLidar TreeQSM on a selected point cloud"
+readme = "README.md"
+license = "GPL-3.0-only"
+authors = [{ name = "John Hagood" }]
+requires-python = ">=3.10, <3.13"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "PyTLidar>=1.0.6",
+]
+
+[project.entry-points."cloudcompare.plugins"]
+PyTLidar = "pytlidar_cc.plugin:PyTLidarPlugin"
+
+[project.urls]
+Homepage = "https://github.com/Landscape-CV/PyTLidar"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pytlidar_cc = ["assets/*.png"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

pytlidar_cc-0.1.0/setup.cfg

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

pytlidar_cc-0.1.0/src/pytlidar_cc/__init__.py

@@ -0,0 +1,3 @@
+"""CloudCompare plugin adapter for PyTLidar TreeQSM."""
+
+__version__ = "0.1.0"

pytlidar_cc-0.1.0/src/pytlidar_cc/adapter.py

@@ -0,0 +1,137 @@
+"""Conversions from PyTLidar QSM results to CloudCompare objects."""
+
+import sys
+
+import numpy as np
+import pycc
+
+from .mesh import cylinder_mesh
+
+FACETS = 8
+
+
+def cloud_from_cc(cc_cloud):
+    """Nx3 float64 array from a ccPointCloud."""
+    return cc_cloud.points().astype(np.float64)
+
+
+def results_to_cc(cc, source, qsm, offset, label=None):
+    """Add one QSM to the scene and print the treedata summary.
+
+    offset undoes the plugin's mean centring, added in float64 before the
+    float32 cast. label distinguishes the groups of a multi-run job.
+    """
+    cylinder = qsm["cylinder"]
+    starts = np.asarray(cylinder["start"], dtype=np.float64) + offset
+
+    name = f"PyTLidar - {source.getName()}"
+    if label:
+        name = f"{name} ({label})"
+    group = pycc.ccHObject(name)
+    group.addChild(_cylinder_cloud(cylinder, starts, source))
+    if starts.shape[0] > 0:
+        group.addChild(_cylinder_ccmesh(cylinder, starts, source))
+    tri = qsm.get("triangulation")
+    if isinstance(tri, dict) and np.size(tri.get("vert", [])) > 0:
+        group.addChild(_stem_ccmesh(tri, offset, source))
+    cc.addToDB(group)
+    cc.updateUI()
+    _print_tree_data(qsm["treedata"], name)
+
+
+def _make_cloud(name, xyz, source):
+    cloud = pycc.ccPointCloud(np.ascontiguousarray(xyz[:, 0], dtype=np.float32),
+                              np.ascontiguousarray(xyz[:, 1], dtype=np.float32),
+                              np.ascontiguousarray(xyz[:, 2], dtype=np.float32))
+    cloud.setName(name)
+    cloud.copyGlobalShiftAndScale(source)
+    return cloud
+
+
+def _add_scalar_field(cloud, name, values):
+    idx = cloud.addScalarField(name)
+    sf = cloud.getScalarField(idx)
+    sf.asArray()[:] = np.asarray(values, dtype=np.float32).reshape(-1)
+    sf.computeMinAndMax()
+    return idx
+
+
+def _cylinder_cloud(cylinder, starts, source):
+    """Cylinder start points with the per-cylinder attributes as scalar
+    fields, the filterable view of the model."""
+    cloud = _make_cloud("cylinders", starts, source)
+    n = starts.shape[0]
+    if n == 0:
+        return cloud
+
+    for name, key in (("radius", "radius"), ("length", "length"),
+                      ("branch_order", "BranchOrder"), ("branch_id", "branch"),
+                      ("surface_coverage", "SurfCov")):
+        idx = _add_scalar_field(cloud, name, cylinder[key])
+        if name == "radius":
+            cloud.setCurrentDisplayedScalarField(idx)
+    cloud.showSF(True)
+    return cloud
+
+
+def _cylinder_ccmesh(cylinder, starts, source):
+    """Merged triangle mesh of all cylinders, the visual view of the model.
+    branch_order rides on the vertices so the mesh can be coloured by it."""
+    vertices, triangles, vertex_cylinder = cylinder_mesh(
+        starts,
+        np.asarray(cylinder["axis"], dtype=np.float64),
+        np.asarray(cylinder["length"], dtype=np.float64),
+        np.asarray(cylinder["radius"], dtype=np.float64),
+        facets=FACETS,
+    )
+    vcloud = _make_cloud("vertices", vertices, source)
+    idx = _add_scalar_field(vcloud, "branch_order",
+                            np.asarray(cylinder["BranchOrder"])[vertex_cylinder])
+    vcloud.setCurrentDisplayedScalarField(idx)
+
+    mesh = pycc.ccMesh(vcloud)
+    mesh.setName("cylinder mesh")
+    if hasattr(mesh, "reserve"):
+        # Some pycc builds require the triangle capacity up front.
+        mesh.reserve(triangles.shape[0])
+    for a, b, c in triangles:
+        mesh.addTriangle(int(a), int(b), int(c))
+    mesh.addChild(vcloud)
+    return mesh
+
+
+def _stem_ccmesh(tri, offset, source):
+    """The stem triangulation (inputs Tria) as its own mesh, in the same frame
+    as the cylinders."""
+    vertices = np.asarray(tri["vert"], dtype=np.float64) + offset
+    facets = np.asarray(tri["facet"], dtype=np.int64)
+    vcloud = _make_cloud("stem vertices", vertices, source)
+    mesh = pycc.ccMesh(vcloud)
+    mesh.setName("stem mesh")
+    if hasattr(mesh, "reserve"):
+        mesh.reserve(facets.shape[0])
+    for a, b, c in facets:
+        mesh.addTriangle(int(a), int(b), int(c))
+    mesh.addChild(vcloud)
+    return mesh
+
+
+def _print_tree_data(treedata, name):
+    """Tree metrics to the CloudCompare console. tree_data casts every value
+    to float32, so the counts need an explicit int."""
+    lines = [
+        f"--- {name} ---",
+        f"  Total volume:     {float(treedata.get('TotalVolume', 0)):.3f} L",
+        f"  Trunk volume:     {float(treedata.get('TrunkVolume', 0)):.3f} L",
+        f"  Branch volume:    {float(treedata.get('BranchVolume', 0)):.3f} L",
+        f"  Tree height:      {float(treedata.get('TreeHeight', 0)):.2f} m",
+        f"  Trunk length:     {float(treedata.get('TrunkLength', 0)):.2f} m",
+        f"  Branch length:    {float(treedata.get('BranchLength', 0)):.2f} m",
+        f"  DBH (QSM):        {float(treedata.get('DBHqsm', 0)):.4f} m",
+        f"  DBH (cylinder):   {float(treedata.get('DBHcyl', 0)):.4f} m",
+        f"  Branches:         {int(treedata.get('NumberBranches', 0))}",
+        f"  Max branch order: {int(treedata.get('MaxBranchOrder', 0))}",
+        "---",
+    ]
+    sys.stdout.write("\n".join(lines) + "\n")
+    sys.stdout.flush()

pytlidar_cc-0.1.0/src/pytlidar_cc/dialog.py

@@ -0,0 +1,313 @@
+"""Settings dialog for the TreeQSM action.
+
+CloudCompare's PythonRuntime ships its own Qt binding (PyQt5 on current
+builds); importing a second Qt into CloudCompare's process can crash it, so
+that binding is preferred and PySide6 is only a fallback (the combination
+3DFin ships with).
+"""
+
+try:
+    from PyQt5.QtCore import QSettings
+    from PyQt5.QtWidgets import (
+        QApplication, QCheckBox, QComboBox, QDialog, QDialogButtonBox,
+        QDoubleSpinBox, QFileDialog, QFormLayout, QGroupBox, QHBoxLayout,
+        QLabel, QLineEdit, QMessageBox, QProgressDialog, QPushButton,
+        QSpinBox, QVBoxLayout, QWidget,
+    )
+except ImportError:
+    from PySide6.QtCore import QSettings
+    from PySide6.QtWidgets import (
+        QApplication, QCheckBox, QComboBox, QDialog, QDialogButtonBox,
+        QDoubleSpinBox, QFileDialog, QFormLayout, QGroupBox, QHBoxLayout,
+        QLabel, QLineEdit, QMessageBox, QProgressDialog, QPushButton,
+        QSpinBox, QVBoxLayout, QWidget,
+    )
+
+from pathlib import Path
+
+WARNING = (
+    "TreeQSM uses randomised cover sets: every run gives a slightly "
+    "different model.\nProgress appears in the console; the first run also "
+    "compiles the numba kernels."
+)
+
+
+class _JobProgressDialog(QProgressDialog):
+    """Qt emits canceled() on any close of the dialog, screen lock included.
+    Closes are ignored until allow_close() so only the button cancels."""
+
+    def __init__(self, *args):
+        super().__init__(*args)
+        self._closable = False
+
+    def allow_close(self):
+        self._closable = True
+
+    def closeEvent(self, event):
+        if self._closable:
+            event.accept()
+        else:
+            event.ignore()
+
+    def keyPressEvent(self, event):
+        event.ignore()
+
+
+def make_progress_dialog(title):
+    """Non-modal indeterminate progress dialog with a working Cancel."""
+    dlg = _JobProgressDialog(title, "Cancel", 0, 0)
+    dlg.setWindowTitle("PyTLidar")
+    dlg.setMinimumDuration(0)
+    dlg.show()
+    return dlg
+
+
+def parse_diams(text):
+    """Comma-separated PatchDiam values as a list of floats, each in (0, 1].
+
+    Raises ValueError on anything else, including an empty string.
+    """
+    values = [float(v) for v in text.split(",") if v.strip()]
+    if not values or any(not 0.0 < v <= 1.0 for v in values):
+        raise ValueError(f"PatchDiam values must be in (0, 1]: {text!r}")
+    return values
+
+
+def _scalar_field_names(source):
+    return [source.getScalarFieldName(i)
+            for i in range(source.getNumberOfScalarFields())]
+
+
+class _SettingsDialog(QDialog):
+    def __init__(self, clouds, metrics):
+        super().__init__()
+        self.n_clouds = len(clouds)
+        title = (clouds[0].getName() if self.n_clouds == 1
+                 else f"{self.n_clouds} clouds")
+        self.setWindowTitle(f"PyTLidar (TreeQSM): {title}")
+        self.settings = None
+
+        layout = QVBoxLayout(self)
+
+        patch = QGroupBox("PatchDiam")
+        patch_layout = QVBoxLayout(patch)
+        self.custom_check = QCheckBox("Use custom values")
+        self.custom_check.setToolTip(
+            "Off: generate candidate PatchDiam values automatically. "
+            "On: give the values to test, comma separated.")
+        patch_layout.addWidget(self.custom_check)
+
+        self.auto_box = QWidget()
+        auto_form = QFormLayout(self.auto_box)
+        self.n_pd1 = QSpinBox()
+        self.n_pd2min = QSpinBox()
+        self.n_pd2max = QSpinBox()
+        for spin in (self.n_pd1, self.n_pd2min, self.n_pd2max):
+            spin.setRange(1, 3)
+            spin.setValue(1)
+        auto_form.addRow("PatchDiam1 candidates", self.n_pd1)
+        auto_form.addRow("PatchDiam2Min candidates", self.n_pd2min)
+        auto_form.addRow("PatchDiam2Max candidates", self.n_pd2max)
+        patch_layout.addWidget(self.auto_box)
+
+        self.custom_box = QWidget()
+        custom_form = QFormLayout(self.custom_box)
+        self.pd1 = QLineEdit()
+        self.pd2min = QLineEdit()
+        self.pd2max = QLineEdit()
+        for edit, hint in ((self.pd1, "e.g. 0.1"), (self.pd2min, "e.g. 0.02"),
+                           (self.pd2max, "e.g. 0.06")):
+            edit.setPlaceholderText(hint)
+        custom_form.addRow("PatchDiam1", self.pd1)
+        custom_form.addRow("PatchDiam2Min", self.pd2min)
+        custom_form.addRow("PatchDiam2Max", self.pd2max)
+        self.custom_box.hide()
+        patch_layout.addWidget(self.custom_box)
+
+        self.count_label = QLabel("")
+        patch_layout.addWidget(self.count_label)
+
+        self.custom_check.toggled.connect(self.auto_box.setHidden)
+        self.custom_check.toggled.connect(self.custom_box.setVisible)
+        self.custom_check.toggled.connect(self._update_count)
+        for spin in (self.n_pd1, self.n_pd2min, self.n_pd2max):
+            spin.valueChanged.connect(self._update_count)
+        for edit in (self.pd1, self.pd2min, self.pd2max):
+            edit.textChanged.connect(self._update_count)
+        self._update_count()
+        layout.addWidget(patch)
+
+        # Union across the selection; clouds without the chosen field are
+        # not filtered.
+        self.sf_names = []
+        for cloud in clouds:
+            for name in _scalar_field_names(cloud):
+                if name not in self.sf_names:
+                    self.sf_names.append(name)
+        self.sf_check = None
+        if self.sf_names:
+            sf_box = QGroupBox("Point filter")
+            sf_form = QFormLayout(sf_box)
+            self.sf_check = QCheckBox("Filter by scalar field")
+            self.sf_combo = QComboBox()
+            self.sf_combo.addItems(self.sf_names)
+            for i, name in enumerate(self.sf_names):
+                if "intensity" in name.lower():
+                    self.sf_combo.setCurrentIndex(i)
+                    break
+            self.sf_threshold = QDoubleSpinBox()
+            self.sf_threshold.setRange(-1e9, 1e9)
+            self.sf_threshold.setDecimals(3)
+            self.sf_combo.setEnabled(False)
+            self.sf_threshold.setEnabled(False)
+            self.sf_check.toggled.connect(self.sf_combo.setEnabled)
+            self.sf_check.toggled.connect(self.sf_threshold.setEnabled)
+            sf_form.addRow(self.sf_check)
+            sf_form.addRow("Field", self.sf_combo)
+            sf_form.addRow("Keep values at least", self.sf_threshold)
+            layout.addWidget(sf_box)
+
+        metric_form = QFormLayout()
+        self.metric_combo = QComboBox()
+        self.metric_combo.addItems(list(metrics))
+        if "all_mean_dis" in metrics:
+            self.metric_combo.setCurrentText("all_mean_dis")
+        self.metric_combo.setToolTip(
+            "Picks the best model when several PatchDiam combinations run. "
+            "Ignored for a single combination.")
+        metric_form.addRow("Optimal model metric", self.metric_combo)
+        self.tria_check = QCheckBox("Triangulate the stem")
+        self.tria_check.setToolTip(
+            "Model the bottom of the trunk as a triangle mesh, better volume for "
+            "large or buttressed stems. Adds a stem mesh to the output.")
+        metric_form.addRow(self.tria_check)
+        self.runs_spin = QSpinBox()
+        self.runs_spin.setRange(1, 100)
+        self.runs_spin.setValue(1)
+        self.runs_spin.setToolTip(
+            "TreeQSM is stochastic, so repeated runs give different models. "
+            "Each run is added to the scene as its own group; keep the tree "
+            "you like and delete the rest.")
+        metric_form.addRow("Repeat runs", self.runs_spin)
+        self.workers_spin = QSpinBox()
+        self.workers_spin.setRange(1, 8)
+        self.workers_spin.setValue(1)
+        self.workers_spin.setToolTip(
+            "How many runs fit at the same time. Each parallel run uses its "
+            "own memory, so keep this low for very large clouds.")
+        metric_form.addRow("Parallel workers", self.workers_spin)
+        self.runs_spin.valueChanged.connect(self._update_count)
+        self.save_check = QCheckBox("Save model files")
+        self.save_check.setChecked(True)
+        self.save_check.setToolTip(
+            "Writes the QSM archive (npz), the cylinder, branch and treedata "
+            "tables and a run_info.json for each run.")
+        metric_form.addRow(self.save_check)
+        default_dir = QSettings("PyTLidar", "pytlidar-cc").value(
+            "results_dir", str(Path.home() / "Documents" / "PyTLidar" / "results"))
+        self.dir_edit = QLineEdit(str(default_dir))
+        browse = QPushButton("Browse")
+        browse.clicked.connect(self._pick_dir)
+        dir_row = QWidget()
+        dir_lay = QHBoxLayout(dir_row)
+        dir_lay.setContentsMargins(0, 0, 0, 0)
+        dir_lay.addWidget(self.dir_edit)
+        dir_lay.addWidget(browse)
+        self.save_check.toggled.connect(dir_row.setEnabled)
+        metric_form.addRow("Results folder", dir_row)
+        layout.addLayout(metric_form)
+
+        warning = QLabel(WARNING)
+        warning.setWordWrap(True)
+        layout.addWidget(warning)
+
+        self.error_label = QLabel("")
+        self.error_label.setStyleSheet("color: red")
+        self.error_label.setWordWrap(True)
+        layout.addWidget(self.error_label)
+
+        buttons = QDialogButtonBox(QDialogButtonBox.Ok | QDialogButtonBox.Cancel)
+        buttons.accepted.connect(self._validate_and_accept)
+        buttons.rejected.connect(self.reject)
+        layout.addWidget(buttons)
+
+    def _update_count(self):
+        if self.custom_check.isChecked():
+            try:
+                n = (len(parse_diams(self.pd1.text()))
+                     * len(parse_diams(self.pd2min.text()))
+                     * len(parse_diams(self.pd2max.text())))
+            except ValueError:
+                self.count_label.setText("")
+                return
+        else:
+            n = (self.n_pd1.value() * self.n_pd2min.value()
+                 * self.n_pd2max.value())
+        runs = self.runs_spin.value() if hasattr(self, "runs_spin") else 1
+        total = n * runs * self.n_clouds
+        if total == 1:
+            self.count_label.setText("1 model will be fitted.")
+        else:
+            parts = [f"{n} PatchDiam combination(s)"]
+            if runs > 1:
+                parts.append(f"{runs} runs")
+            if self.n_clouds > 1:
+                parts.append(f"{self.n_clouds} clouds")
+            self.count_label.setText(
+                f"{total} models will be fitted ({' x '.join(parts)}); "
+                "the runtime multiplies accordingly.")
+
+    def _pick_dir(self):
+        d = QFileDialog.getExistingDirectory(self, "Results folder",
+                                             self.dir_edit.text())
+        if d:
+            self.dir_edit.setText(d)
+
+    def _validate_and_accept(self):
+        if self.runs_spin.value() > 20:
+            reply = QMessageBox.question(
+                self, "PyTLidar",
+                f"{self.runs_spin.value()} repeat runs, times the PatchDiam "
+                "combinations, is a lot of fitting. Are you sure?")
+            if reply != QMessageBox.StandardButton.Yes:
+                return
+        custom = None
+        if self.custom_check.isChecked():
+            try:
+                custom = (parse_diams(self.pd1.text()),
+                          parse_diams(self.pd2min.text()),
+                          parse_diams(self.pd2max.text()))
+            except ValueError as exc:
+                self.error_label.setText(str(exc))
+                return
+        intensity_sf = None
+        threshold = 0.0
+        if self.sf_check is not None and self.sf_check.isChecked():
+            intensity_sf = self.sf_combo.currentText()
+            threshold = float(self.sf_threshold.value())
+        QSettings("PyTLidar", "pytlidar-cc").setValue(
+            "results_dir", self.dir_edit.text())
+        self.settings = {
+            "custom": custom,
+            "n_patchdiam": (self.n_pd1.value(), self.n_pd2min.value(),
+                            self.n_pd2max.value()),
+            "metric": self.metric_combo.currentText(),
+            "tria": self.tria_check.isChecked(),
+            "runs": self.runs_spin.value(),
+            "workers": self.workers_spin.value(),
+            "save_files": self.save_check.isChecked(),
+            "results_dir": self.dir_edit.text(),
+            "intensity_sf": intensity_sf,
+            "intensity_threshold": threshold,
+        }
+        self.accept()
+
+
+def show_settings_dialog(clouds, metrics):
+    """Modal settings dialog for one job over the selected clouds. Returns
+    the settings dict, or None when the user cancels. CloudCompare's Qt event
+    loop is already running, so QDialog.exec() is enough; no QApplication or
+    QEventLoop needed."""
+    dialog = _SettingsDialog(clouds, metrics)
+    dialog.exec()
+    return dialog.settings

pytlidar_cc-0.1.0/src/pytlidar_cc/mesh.py

@@ -0,0 +1,57 @@
+"""Triangle mesh of a QSM's cylinders.
+
+Pure numpy so it can be tested without CloudCompare. Each cylinder becomes a
+ring of `facets` vertices at both ends and 2 * facets side triangles; the
+rings are oriented by an orthonormal frame built from the cylinder axis.
+"""
+
+import numpy as np
+
+
+def cylinder_mesh(starts, axes, lengths, radii, facets=8):
+    """Mesh the cylinders as one vertex/triangle soup.
+
+    starts, axes: (n, 3). lengths, radii: (n,). Returns (vertices, triangles,
+    vertex_cylinder): vertices is (n * 2 * facets, 3) float64, triangles is
+    (n * 2 * facets, 3) int 0-based indices into vertices, vertex_cylinder
+    maps every vertex to the index of the cylinder it belongs to, for
+    carrying per-cylinder values onto the mesh as scalar fields.
+    """
+    starts = np.asarray(starts, dtype=np.float64).reshape(-1, 3)
+    axes = np.asarray(axes, dtype=np.float64).reshape(-1, 3)
+    lengths = np.asarray(lengths, dtype=np.float64).reshape(-1)
+    radii = np.asarray(radii, dtype=np.float64).reshape(-1)
+    n = starts.shape[0]
+    if n == 0:
+        return (np.zeros((0, 3)), np.zeros((0, 3), dtype=np.int64),
+                np.zeros(0, dtype=np.int64))
+
+    norms = np.linalg.norm(axes, axis=1, keepdims=True)
+    axes = np.where(norms > 1e-12, axes / np.where(norms == 0, 1.0, norms),
+                    [[0.0, 0.0, 1.0]])
+
+    # Frame per cylinder: u, v span the plane of the end rings.
+    ref = np.where(np.abs(axes[:, 2:3]) < 0.9, [[0.0, 0.0, 1.0]],
+                   [[1.0, 0.0, 0.0]])
+    u = np.cross(axes, ref)
+    u /= np.linalg.norm(u, axis=1, keepdims=True)
+    v = np.cross(axes, u)
+
+    theta = 2.0 * np.pi * np.arange(facets) / facets
+    ring = (u[:, None, :] * np.cos(theta)[None, :, None]
+            + v[:, None, :] * np.sin(theta)[None, :, None]) * radii[:, None, None]
+    base = starts[:, None, :] + ring
+    top = (starts + axes * lengths[:, None])[:, None, :] + ring
+    vertices = np.concatenate([base, top], axis=1).reshape(-1, 3)
+
+    # Two triangles per side quad, indices local to one cylinder's block of
+    # 2 * facets vertices (base ring first, then top ring).
+    k = np.arange(facets)
+    kn = (k + 1) % facets
+    quad = np.concatenate([np.stack([k, kn, k + facets], axis=1),
+                           np.stack([kn, kn + facets, k + facets], axis=1)])
+    triangles = (quad[None, :, :]
+                 + (np.arange(n) * 2 * facets)[:, None, None]).reshape(-1, 3)
+
+    vertex_cylinder = np.repeat(np.arange(n), 2 * facets)
+    return vertices, triangles, vertex_cylinder

pytlidar_cc-0.1.0/src/pytlidar_cc/plugin.py

@@ -0,0 +1,366 @@
+"""CloudCompare PythonRuntime plugin entry point for PyTLidar TreeQSM.
+
+Only pycc, numpy and the standard library import at module scope: an import
+error here silently drops the plugin from the Plugins menu. Fits run in
+worker processes using the selected environment's own python, because
+sys.executable is CloudCompare itself in the embedded interpreter.
+"""
+
+import json
+import os
+import pickle
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+import numpy as np
+import pycc
+
+_active_run = {}
+# one results subfolder per CloudCompare session; run numbers continue across jobs
+_session_stamp = None
+_session_runs = {}
+
+
+def _venv_python():
+    for rel in ("bin/python", "bin/python3", "Scripts/python.exe"):
+        candidate = Path(sys.prefix) / rel
+        if candidate.exists():
+            return str(candidate)
+    raise RuntimeError(
+        f"No python executable found under {sys.prefix}. Select a virtual "
+        "environment in the Python plugin settings.")
+
+
+def _worker_env(workers):
+    """Split the machine's threads between parallel workers so they do not
+    fight over cores."""
+    env = os.environ.copy()
+    per = max(1, (os.cpu_count() or 4) // max(1, workers))
+    for var in ("NUMBA_NUM_THREADS", "OMP_NUM_THREADS",
+                "OPENBLAS_NUM_THREADS", "MKL_NUM_THREADS"):
+        env[var] = str(per)
+    return env
+
+
+def _hold_idle_sleep(reason):
+    """Keep the system from idle sleeping until the returned callable runs.
+
+    Every path releases by itself if the process dies: macOS uses a named
+    IOKit power assertion (caffeinate as fallback), Windows the thread
+    execution state, Linux a systemd-inhibit tied to this pid. Best effort,
+    a no-op where none of that works."""
+    if sys.platform == "win32":
+        try:
+            import ctypes
+            ES_CONTINUOUS = 0x80000000
+            ES_SYSTEM_REQUIRED = 0x00000001
+            k32 = ctypes.windll.kernel32
+            if k32.SetThreadExecutionState(ES_CONTINUOUS | ES_SYSTEM_REQUIRED):
+                return lambda: k32.SetThreadExecutionState(ES_CONTINUOUS)
+        except Exception:
+            pass
+        return lambda: None
+    if sys.platform.startswith("linux"):
+        try:
+            proc = subprocess.Popen(
+                ["systemd-inhibit", "--what=idle:sleep", "--who=PyTLidar",
+                 f"--why={reason}", "--mode=block",
+                 "tail", f"--pid={os.getpid()}", "-f", "/dev/null"],
+                stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            return proc.terminate
+        except OSError:
+            return lambda: None
+    if sys.platform != "darwin":
+        return lambda: None
+    try:
+        import ctypes
+        import ctypes.util
+
+        iokit = ctypes.CDLL(ctypes.util.find_library("IOKit"))
+        cf = ctypes.CDLL(ctypes.util.find_library("CoreFoundation"))
+        cf.CFStringCreateWithCString.restype = ctypes.c_void_p
+        cf.CFStringCreateWithCString.argtypes = [
+            ctypes.c_void_p, ctypes.c_char_p, ctypes.c_uint32]
+        cf.CFRelease.argtypes = [ctypes.c_void_p]
+        iokit.IOPMAssertionCreateWithName.argtypes = [
+            ctypes.c_void_p, ctypes.c_uint32, ctypes.c_void_p,
+            ctypes.POINTER(ctypes.c_uint32)]
+        utf8 = 0x08000100
+        a_type = cf.CFStringCreateWithCString(
+            None, b"PreventUserIdleSystemSleep", utf8)
+        a_name = cf.CFStringCreateWithCString(None, reason.encode(), utf8)
+        assertion = ctypes.c_uint32(0)
+        err = iokit.IOPMAssertionCreateWithName(
+            a_type, 255, a_name, ctypes.byref(assertion))
+        cf.CFRelease(a_type)
+        cf.CFRelease(a_name)
+        if err == 0:
+            return lambda: iokit.IOPMAssertionRelease(assertion)
+    except Exception:
+        pass
+    try:
+        proc = subprocess.Popen(
+            ["/usr/bin/caffeinate", "-i", "-w", str(os.getpid())])
+        return proc.terminate
+    except OSError:
+        return lambda: None
+
+
+def _run_stats(model):
+    """(mean dist mm, trunk dist mm, mean surface coverage %) of one model."""
+    pm = model.get("pmdistance")
+    dist = trunk = float("nan")
+    if isinstance(pm, dict):
+        if pm.get("mean") is not None:
+            dist = float(np.ravel(pm["mean"])[0]) * 1000.0
+        if pm.get("TrunkMean") is not None:
+            trunk = float(np.ravel(pm["TrunkMean"])[0]) * 1000.0
+    cov = float("nan")
+    sc = model.get("cylinder", {}).get("SurfCov")
+    if sc is not None and np.size(sc) > 0:
+        cov = float(np.mean(sc)) * 100.0
+    return dist, trunk, cov
+
+
+def _run_treeqsm():
+    cc = pycc.GetInstance()
+    if _active_run:
+        raise RuntimeError("A PyTLidar job is already running; cancel it or "
+                           "wait for it to finish.")
+    clouds = [e for e in cc.getSelectedEntities()
+              if isinstance(e, pycc.ccPointCloud)]
+    if not clouds:
+        raise RuntimeError("Select at least one point cloud.")
+
+    from PyTLidar.pipeline import centre
+    from PyTLidar.Utils import Utils as pt_utils
+
+    from .adapter import cloud_from_cc, results_to_cc
+    from .dialog import make_progress_dialog, QApplication, show_settings_dialog
+
+    settings = show_settings_dialog(clouds, pt_utils.get_all_metrics())
+    if settings is None:
+        return
+
+    runs = max(1, int(settings.get("runs", 1)))
+    workers = max(1, int(settings.get("workers", 1)))
+    global _session_stamp
+    save = bool(settings.get("save_files"))
+    dest = None
+    if save:
+        if _session_stamp is None:
+            _session_stamp = time.strftime("%Y-%m-%d_%H%M")
+        dest = Path(settings["results_dir"]) / _session_stamp
+        dest.mkdir(parents=True, exist_ok=True)
+
+    names = []
+    for i, c in enumerate(clouds):
+        n = re.sub(r"[^\w.-]+", "_", Path(c.getName()).stem) or f"cloud{i}"
+        if n in names:
+            n = f"{n}_{i}"
+        names.append(n)
+
+    job = Path(tempfile.mkdtemp(prefix="pytlidar_cc_"))
+    (job / "settings.json").write_text(json.dumps({
+        "custom": settings["custom"],
+        "n_patchdiam": list(settings["n_patchdiam"]),
+        "metric": settings["metric"],
+        "tria": bool(settings.get("tria")),
+        "save": save,
+        "names": names,
+    }))
+
+    # A cloud that does not look like a tree is skipped, not fatal
+    prepared = {}
+    for ci, source in enumerate(clouds):
+        P = cloud_from_cc(source)
+        if settings["intensity_sf"] is not None:
+            idx = source.getScalarFieldIndexByName(settings["intensity_sf"])
+            if idx >= 0:
+                keep = (source.getScalarField(idx).asArray()
+                        >= settings["intensity_threshold"])
+                P = P[keep]
+        # define_input's stem estimation misbehaves on selections that are
+        # not a tree.
+        if P.shape[0] < 1000 or P[:, 2].max() - P[:, 2].min() < 1.5:
+            sys.stdout.write(f"Skipping {source.getName()}: needs at least 1000 "
+                             "points and 1.5 m of height.\n")
+            continue
+        # Centre on the mean to protect the float32 cylinder arrays from
+        # precision loss; treeqsm returns z in the frame it is given.
+        offset = P.mean(axis=0)
+        P = centre(P, z=False)
+        np.save(job / f"cloud_{ci}.npy", P)
+        prepared[ci] = {"source": source, "offset": offset}
+    if not prepared:
+        shutil.rmtree(job, ignore_errors=True)
+        raise RuntimeError("No usable point cloud in the selection.")
+
+    python = _venv_python()
+    env = _worker_env(workers)
+    tasks = []
+    for ci in prepared:
+        start = _session_runs.get(names[ci], 0)
+        tasks += [(ci, rid) for rid in range(start + 1, start + runs + 1)]
+        _session_runs[names[ci]] = start + runs
+    total = len(tasks)
+    sys.stdout.write(f"Running PyTLidar: {len(prepared)} tree(s) x {runs} run(s), "
+                     f"up to {min(workers, total)} at a time.\n")
+
+    title = (clouds[0].getName() if len(clouds) == 1
+             else f"{len(prepared)} trees")
+    progress = make_progress_dialog(f"PyTLidar (TreeQSM): {title}")
+    state = {"queue": tasks, "procs": {}, "buffers": {}, "done": 0,
+             "failed": [], "summaries": {}, "cancelled": False,
+             "progress": progress,
+             "release_sleep": _hold_idle_sleep("PyTLidar TreeQSM fits")}
+    _active_run.update(state)
+
+    def tag(ci, rid):
+        name = prepared[ci]["source"].getName()
+        return f"{name} run {rid}" if (runs > 1 or rid > 1) else name
+
+    def launch_next():
+        while state["queue"] and len(state["procs"]) < workers:
+            ci, rid = state["queue"].pop(0)
+            proc = subprocess.Popen(
+                [python, "-u", "-m", "pytlidar_cc.worker",
+                 str(job), str(ci), str(rid)],
+                stdout=subprocess.PIPE, stderr=subprocess.STDOUT, env=env)
+            os.set_blocking(proc.stdout.fileno(), False)
+            state["procs"][(ci, rid)] = proc
+            sys.stdout.write(f"[{tag(ci, rid)}] started\n")
+
+    def finish():
+        # closing the dialog would emit canceled(), disconnect first
+        try:
+            progress.canceled.disconnect(cancel)
+        except Exception:
+            pass
+        progress.allow_close()
+        progress.close()
+        try:
+            if state["cancelled"]:
+                for proc in state["procs"].values():
+                    try:
+                        proc.wait(timeout=2)
+                    except Exception:
+                        pass
+                sys.stdout.write("PyTLidar job cancelled.\n")
+                return
+            if state["failed"]:
+                names = ", ".join(tag(ci, rid) for ci, rid in state["failed"])
+                sys.stdout.write(f"Failed fits: {names}, see the lines above.\n")
+            if runs > 1:
+                for ci, rows in sorted(state["summaries"].items()):
+                    if len(rows) < 2:
+                        continue
+                    med_dist = float(np.nanmedian([r[3] for r in rows]))
+                    med_trunk = float(np.nanmedian([r[4] for r in rows]))
+                    sys.stdout.write(f"--- {prepared[ci]['source'].getName()} run summary ---\n")
+                    for rid, vol, branches, dist, trunk, cov in sorted(rows):
+                        mark = ""
+                        if dist > 1.5 * med_dist or trunk > 1.5 * med_trunk:
+                            mark = "  <- fit looks off, check before using"
+                        sys.stdout.write(f"  run {rid}: volume {vol:.0f} L, branches "
+                                         f"{branches}, mean dist {dist:.1f} mm, "
+                                         f"coverage {cov:.0f}%{mark}\n")
+            if dest is not None:
+                sys.stdout.write(f"Model files saved to {dest}\n")
+        finally:
+            state["release_sleep"]()
+            shutil.rmtree(job, ignore_errors=True)
+            _active_run.clear()
+
+    def drain(key, proc):
+        # unbuffered workers can hand over partial lines; emit only whole ones
+        ci, rid = key
+        try:
+            data = os.read(proc.stdout.fileno(), 65536)
+        except (BlockingIOError, OSError):
+            return
+        if not data:
+            return
+        buf = state["buffers"].get(key, "") + data.decode("utf-8", errors="replace")
+        *lines, state["buffers"][key] = buf.split("\n")
+        for ln in lines:
+            if ln.strip():
+                sys.stdout.write(f"[{tag(ci, rid)}] {ln}\n")
+
+    def poll_once():
+        for key, proc in list(state["procs"].items()):
+            ci, rid = key
+            drain(key, proc)
+            rc = proc.poll()
+            if rc is not None:
+                drain(key, proc)
+                leftover = state["buffers"].pop(key, "")
+                if leftover.strip():
+                    sys.stdout.write(f"[{tag(ci, rid)}] {leftover}\n")
+                del state["procs"][key]
+                result = job / f"result_{ci}_{rid}.pkl"
+                if state["cancelled"]:
+                    pass
+                elif rc == 0 and result.exists():
+                    state["done"] += 1
+                    # scene insertion must happen here on the main thread
+                    with open(result, "rb") as f:
+                        model = pickle.load(f)
+                    label = f"run {rid}" if (runs > 1 or rid > 1) else None
+                    results_to_cc(cc, prepared[ci]["source"], model,
+                                  prepared[ci]["offset"], label=label)
+                    td = model["treedata"]
+                    dist, trunk, cov = _run_stats(model)
+                    state["summaries"].setdefault(ci, []).append(
+                        (rid, float(td.get("TotalVolume", 0)),
+                         int(td.get("NumberBranches", 0)), dist, trunk, cov))
+                    del model
+                    if dest is not None:
+                        outdir = job / f"out_{ci}_{rid}"
+                        if outdir.is_dir():
+                            for f in outdir.iterdir():
+                                shutil.move(str(f), dest / f.name)
+                else:
+                    state["failed"].append(key)
+                    sys.stdout.write(f"[{tag(ci, rid)}] failed (exit {rc})\n")
+        if not state["cancelled"]:
+            launch_next()
+        finished = state["done"] + len(state["failed"])
+        progress.setLabelText(
+            f"PyTLidar (TreeQSM): {title}\n{finished}/{total} fits finished, "
+            f"{len(state['procs'])} running")
+
+    def cancel():
+        state["cancelled"] = True
+        state["queue"].clear()
+        for proc in state["procs"].values():
+            proc.kill()
+
+    progress.canceled.connect(cancel)
+    launch_next()
+    # the runtime does not call Python back once this action returns, so
+    # pump the event loop here until the job ends
+    while (state["procs"] or state["queue"]) and not state["cancelled"]:
+        poll_once()
+        QApplication.processEvents()
+        time.sleep(0.05)
+    poll_once()
+    finish()
+
+
+class PyTLidarPlugin(pycc.PythonPluginInterface):
+    def __init__(self):
+        pycc.PythonPluginInterface.__init__(self)
+
+    def getIcon(self):
+        icon = Path(__file__).parent / "assets" / "icon.png"
+        return str(icon.resolve()) if icon.exists() else ""
+
+    def getActions(self):
+        return [pycc.Action(name="Run PyTLidar", icon=self.getIcon(),
+                            target=_run_treeqsm)]

pytlidar_cc-0.1.0/src/pytlidar_cc/worker.py

@@ -0,0 +1,95 @@
+"""One TreeQSM fit per process, driven by the plugin.
+
+python -m pytlidar_cc.worker <job_dir> <cloud_idx> <run_id>, with
+cloud_<idx>.npy and settings.json in the job directory. Writes
+result_<idx>_<run_id>.pkl minus the bulky point/cover/segment data; stdout
+is relayed to CloudCompare's console. With saving on, the classic model
+files and a run_info.json land in out_<idx>_<run_id>/.
+"""
+
+import json
+import pickle
+import shutil
+import sys
+import time
+from pathlib import Path
+
+
+def main(job_dir, cloud_idx, run_id):
+    job = Path(job_dir)
+
+    # The fit builds matplotlib figures; keep the worker headless.
+    import matplotlib
+    matplotlib.use("Agg")
+    import numpy as np
+
+    from PyTLidar.pipeline import build_inputs, calculate_optimal, run_qsm
+
+    settings = json.loads((job / "settings.json").read_text())
+    P = np.load(job / f"cloud_{cloud_idx}.npy")
+    print(f"fitting {P.shape[0]} points", flush=True)
+
+    save = bool(settings.get("save"))
+    name = f"{settings['names'][int(cloud_idx)]}_run{run_id}"
+    common = dict(names=[name], savemat=1 if save else 0,
+                  savetxt=1 if save else 0, plot=0, disp=2, savepdf=0)
+    if settings["custom"] is not None:
+        inputs = build_inputs(P, custom=tuple(settings["custom"]), **common)
+    else:
+        inputs = build_inputs(P, n_patchdiam=tuple(settings["n_patchdiam"]), **common)
+    if not inputs:
+        raise RuntimeError("The cloud is empty.")
+    inputs[0]["Tria"] = 1 if settings.get("tria") else 0
+
+    outdir = job / f"out_{cloud_idx}_{run_id}"
+    outdir.mkdir(exist_ok=True)
+    t0 = time.time()
+    models, _ = run_qsm(P, inputs[0], results_dir=str(outdir))
+    elapsed = time.time() - t0
+    if not models:
+        raise RuntimeError("TreeQSM fitted no cylinders to this cloud.")
+
+    best = 0
+    if len(models) > 1:
+        best, _, _ = calculate_optimal(models, settings["metric"])
+        best = int(best)
+    model = models[best]
+
+    if save:
+        # flatten the results/ subfolder treeqsm creates
+        sub = outdir / "results"
+        if sub.is_dir():
+            for f in sub.iterdir():
+                shutil.move(str(f), outdir / f.name)
+            sub.rmdir()
+        inp = model["rundata"]["inputs"]
+        td = model["treedata"]
+        info = {
+            "source": settings["names"][int(cloud_idx)],
+            "run": int(run_id),
+            "points": int(P.shape[0]),
+            "PatchDiam1": float(np.ravel(inp["PatchDiam1"])[0]),
+            "PatchDiam2Min": float(np.ravel(inp["PatchDiam2Min"])[0]),
+            "PatchDiam2Max": float(np.ravel(inp["PatchDiam2Max"])[0]),
+            "Tria": int(inp.get("Tria", 0)),
+            "metric": settings["metric"],
+            "TotalVolume_L": float(np.ravel(td.get("TotalVolume", 0))[0]),
+            "elapsed_s": round(elapsed, 1),
+            "date": time.strftime("%Y-%m-%d %H:%M:%S"),
+        }
+        try:
+            from importlib.metadata import version
+            info["PyTLidar"] = version("PyTLidar")
+        except Exception:
+            pass
+        (outdir / f"run_info_{name}.json").write_text(json.dumps(info, indent=1))
+
+    for key in ("points", "cover", "segment"):
+        model.pop(key, None)
+    with open(job / f"result_{cloud_idx}_{run_id}.pkl", "wb") as f:
+        pickle.dump(model, f, protocol=4)
+    print("done", flush=True)
+
+
+if __name__ == "__main__":
+    main(sys.argv[1], sys.argv[2], sys.argv[3])

pytlidar_cc-0.1.0/src/pytlidar_cc.egg-info/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: pytlidar-cc
+Version: 0.1.0
+Summary: CloudCompare plugin that runs PyTLidar TreeQSM on a selected point cloud
+Author: John Hagood
+License-Expression: GPL-3.0-only
+Project-URL: Homepage, https://github.com/Landscape-CV/PyTLidar
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: <3.13,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PyTLidar>=1.0.6
+
+# pytlidar-cc
+
+CloudCompare plugin that runs [PyTLidar](https://github.com/Landscape-CV/PyTLidar)
+TreeQSM on selected point clouds and puts the models back into the scene.
+
+## What you get
+
+One group per fitted model, named after the source cloud:
+
+- `cylinders`: the cylinder start points with `radius`, `length`,
+  `branch_order`, `branch_id` and `surface_coverage` scalar fields.
+- `cylinder mesh`: the cylinders as one triangle mesh, `branch_order` on its
+  vertices for colouring.
+- `stem mesh` when stem triangulation is on.
+- The tree metrics printed to the console.
+
+Everything is in the source cloud's frame and carries its global shift.
+
+## Requirements
+
+- CloudCompare 2.13 or newer with the PythonRuntime plugin. It ships in the
+  Windows installer and in the OpenFields macOS builds
+  (simulation.openfields.fr); otherwise build it from source.
+- PyTLidar 1.0.6 or newer in the plugin's Python environment.
+
+## Install
+
+With the Python environment CloudCompare uses:
+
+```
+python -m pip install PyTLidar ./pytlidar_cc
+```
+
+## Usage
+
+1. Select one or more point clouds (one segmented tree each).
+2. Plugins, PyTLidar, Run PyTLidar.
+3. Adjust the settings, OK.
+
+Settings: generated or custom PatchDiam values (several values per parameter
+runs every combination and the metric picks the best model), an optional
+scalar field filter, stem triangulation, repeat runs and parallel workers,
+and where the model files save.
+
+## Notes
+
+- Model files (the QSM npz, the cylinder, branch and treedata tables and a
+  run_info.json per run) save into one folder per CloudCompare session,
+  under Documents/PyTLidar/results by default; run numbers continue across
+  jobs in a session.
+- TreeQSM is stochastic. Repeat runs puts each model in the scene as its own
+  group with a console summary that flags suspect fits; keep the tree you
+  like.
+- Fits run in worker processes: progress streams to the console and the job
+  can be cancelled from the progress dialog. Parallel runs each use their
+  own memory, so keep workers low for very large clouds.
+- Segment the tree from the plot first (for example with the Treeiso plugin)
+  and clean obvious noise.
+- A running job holds off system idle sleep so fits continue with the
+  screen locked; closing the lid still sleeps as normal.
+
+## License
+
+GPL-3.0-only, like PyTLidar.

pytlidar_cc-0.1.0/src/pytlidar_cc.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+src/pytlidar_cc/__init__.py
+src/pytlidar_cc/adapter.py
+src/pytlidar_cc/dialog.py
+src/pytlidar_cc/mesh.py
+src/pytlidar_cc/plugin.py
+src/pytlidar_cc/worker.py
+src/pytlidar_cc.egg-info/PKG-INFO
+src/pytlidar_cc.egg-info/SOURCES.txt
+src/pytlidar_cc.egg-info/dependency_links.txt
+src/pytlidar_cc.egg-info/entry_points.txt
+src/pytlidar_cc.egg-info/requires.txt
+src/pytlidar_cc.egg-info/top_level.txt
+tests/test_mesh.py

pytlidar_cc-0.1.0/src/pytlidar_cc.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pytlidar_cc-0.1.0/src/pytlidar_cc.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[cloudcompare.plugins]
+PyTLidar = pytlidar_cc.plugin:PyTLidarPlugin

pytlidar_cc-0.1.0/src/pytlidar_cc.egg-info/requires.txt

@@ -0,0 +1 @@
+PyTLidar>=1.0.6

pytlidar_cc-0.1.0/src/pytlidar_cc.egg-info/top_level.txt

@@ -0,0 +1 @@
+pytlidar_cc

pytlidar_cc-0.1.0/tests/test_mesh.py

@@ -0,0 +1,66 @@
+import numpy as np
+import pytest
+
+from pytlidar_cc.mesh import cylinder_mesh
+
+
+def test_empty_input():
+    vertices, triangles, vertex_cylinder = cylinder_mesh(
+        np.zeros((0, 3)), np.zeros((0, 3)), np.zeros(0), np.zeros(0))
+    assert vertices.shape == (0, 3)
+    assert triangles.shape == (0, 3)
+    assert vertex_cylinder.shape == (0,)
+
+
+def test_counts_and_index_ranges():
+    n, facets = 3, 8
+    rng = np.random.default_rng(0)
+    starts = rng.normal(size=(n, 3))
+    axes = rng.normal(size=(n, 3))
+    lengths = rng.uniform(0.1, 2.0, n)
+    radii = rng.uniform(0.01, 0.5, n)
+
+    vertices, triangles, vertex_cylinder = cylinder_mesh(
+        starts, axes, lengths, radii, facets=facets)
+
+    assert vertices.shape == (n * 2 * facets, 3)
+    assert triangles.shape == (n * 2 * facets, 3)
+    assert vertex_cylinder.shape == (n * 2 * facets,)
+    assert triangles.min() >= 0
+    assert triangles.max() < len(vertices)
+    # Every triangle stays within its own cylinder's vertex block.
+    tri_cyl = vertex_cylinder[triangles]
+    assert (tri_cyl == tri_cyl[:, :1]).all()
+    assert np.array_equal(np.unique(vertex_cylinder), np.arange(n))
+
+
+def test_vertical_cylinder_geometry():
+    length, radius, facets = 2.0, 0.25, 12
+    vertices, _, _ = cylinder_mesh(
+        np.array([[1.0, -2.0, 5.0]]), np.array([[0.0, 0.0, 1.0]]),
+        np.array([length]), np.array([radius]), facets=facets)
+
+    base, top = vertices[:facets], vertices[facets:]
+    assert np.allclose(base[:, 2], 5.0)
+    assert np.allclose(top[:, 2], 5.0 + length)
+    for ring in (base, top):
+        assert np.allclose(np.hypot(ring[:, 0] - 1.0, ring[:, 1] + 2.0), radius)
+
+
+def test_tilted_cylinder_ring_radius():
+    axis = np.array([[1.0, 1.0, 1.0]]) / np.sqrt(3.0)
+    start = np.array([[0.0, 0.0, 0.0]])
+    radius = 0.1
+    vertices, _, _ = cylinder_mesh(start, axis, np.array([1.0]),
+                                   np.array([radius]), facets=8)
+    # Perpendicular distance of every vertex from the axis line is the radius.
+    along = vertices @ axis[0]
+    perp = vertices - np.outer(along, axis[0])
+    assert np.allclose(np.linalg.norm(perp, axis=1), radius)
+
+
+def test_degenerate_axis_no_nan():
+    vertices, triangles, _ = cylinder_mesh(
+        np.zeros((1, 3)), np.zeros((1, 3)), np.array([1.0]), np.array([0.1]))
+    assert np.isfinite(vertices).all()
+    assert len(triangles) == 16