### Install py4dgeo Development Dependencies

Source: https://py4dgeo.readthedocs.io/en/latest/intro.html

Installs additional Python dependencies required for testing and documentation building when contributing to py4dgeo development. This command should be run after cloning the repository.

```bash
python -m pip install -r requirements-dev.txt

```

--------------------------------

### Download and load point cloud data

Source: https://py4dgeo.readthedocs.io/en/latest/spatial_subsampling.html

Uses pooch to download a point cloud dataset from Zenodo and loads it using py4dgeo. Ensure Numba is installed for faster computations.

```python
# Set up pooch to download data from Zenodo
p = pooch.Pooch(base_url="doi:10.5281/zenodo.18432391/", path=pooch.os_cache("py4dgeo"))
p.load_registry_from_doi()

try:
    # Download and extract the dataset
    p.fetch("trier_sim.zip", processor=pooch.Unzip(members=["trier_sim"]))

    # Define path to the extracted data
    data_path = p.path / "trier_sim.zip.unzip"
    print(f"Data path: {data_path}")

    infile = data_path / "trier_sim_epoch_0.laz"

    epoch1 = py4dgeo.read_from_las(infile)

except Exception as e:
    print(f"Failed to download or extract data: {e}")
```

--------------------------------

### Import py4dgeo and Utilities

Source: https://py4dgeo.readthedocs.io/en/latest/4dobc-analysis.html

Imports necessary modules from py4dgeo and standard libraries for file handling and temporary directory management. Ensure Numba is installed for optimized computations.

```python
import py4dgeo

import tempfile
import shutil

from pathlib import Path
from py4dgeo.util import find_file
```

--------------------------------

### Install plyfile using Conda

Source: https://py4dgeo.readthedocs.io/en/latest/spatial_subsampling.html

This snippet provides instructions to install the 'plyfile' library using Conda, which is necessary for the `save_as_ply` functionality in Vapc.

```python
import sys
!conda install --yes --prefix {sys.prefix} conda-forge::plyfile
```

--------------------------------

### Build py4dgeo from Source

Source: https://py4dgeo.readthedocs.io/en/latest/intro.html

Builds py4dgeo from source using pip. This method allows for editable installations and provides verbose output for debugging. Requires a C++17-compliant compiler.

```bash
git clone --recursive https://github.com/3dgeo-heidelberg/py4dgeo.git
cd py4dgeo
python -m pip install -v --editable .

```

--------------------------------

### Install py4dgeo Release Version

Source: https://py4dgeo.readthedocs.io/en/latest/intro.html

Installs the current release of py4dgeo using pip. Ensure you have Python 3.9+ installed.

```bash
python -m pip install py4dgeo

```

--------------------------------

### Build and Run py4dgeo Docker Image

Source: https://py4dgeo.readthedocs.io/en/latest/intro.html

Builds a Docker image for py4dgeo and runs it, exposing JupyterLab on port 8888. This is useful for exploring the library without local installation.

```bash
docker build -t py4dgeo:latest .
docker run -t -p 8888:8888 py4dgeo:latest

```

--------------------------------

### Import necessary libraries for py4dgeo

Source: https://py4dgeo.readthedocs.io/en/latest/pbm3c2.html

Imports the py4dgeo library along with common data science and plotting libraries. Ensure Numba is installed for faster computations.

```python
import py4dgeo

import matplotlib.pyplot as plt
import numpy as np
import pandas as pd

from py4dgeo.util import find_file
```

--------------------------------

### py4dgeo.segmentation.ObjectByChange.start_epoch

Source: https://py4dgeo.readthedocs.io/en/latest/pythonapi.html

Property representing the index of the start epoch of the change object.

```APIDOC
## py4dgeo.segmentation.ObjectByChange._property _start_epoch

### Description
The index of the start epoch of the change object.
```

--------------------------------

### Define Custom Seed Detection Algorithm

Source: https://py4dgeo.readthedocs.io/en/latest/4dobc-customization.html

Create a new class that inherits from RegionGrowingAlgorithm and overrides the find_seedpoints method to return a custom list of RegionGrowingSeed objects. This example sets a single seed for corepoint 0 covering the entire time interval.

```python
class DifferentSeeds(py4dgeo.RegionGrowingAlgorithm):
    def find_seedpoints(self):
        # Use one seed for corepoint 0 and the entire time interval
        return [RegionGrowingSeed(0, 0, self.analysis.distances.shape[1] - 1)]
```

--------------------------------

### Import py4dgeo and pooch

Source: https://py4dgeo.readthedocs.io/en/latest/spatial_subsampling.html

Import necessary libraries for data handling and downloading.

```python
import py4dgeo
import pooch
```

--------------------------------

### run

Source: https://py4dgeo.readthedocs.io/en/latest/pythonapi.html

Executes the complete PBM3C2 workflow for point cloud registration and correspondence analysis.

```APIDOC
## run

### Description
Execute complete PBM3C2 workflow.

### Parameters
- **epoch0** (epoch0, epoch1Epoch) - Input point cloud epochs with segment_id
- **epoch1** (epoch1Epoch) - Input point cloud epochs with segment_id
- **correspondences_file** (correspondences_filestr) - Path to CSV with training correspondences
- **apply_ids** (array-like) - Segment IDs to find correspondences for (using original IDs)
- **search_radius** (float, optional) - Spatial search radius in meters. Defaults to 3.0.

### Returns
- **DataFrame** - Correspondences with distances and uncertainties (using original IDs)
```

--------------------------------

### Run algorithm with custom Python callback

Source: https://py4dgeo.readthedocs.io/en/latest/customization.html

Instantiate and run the algorithm with the custom callback integrated. This demonstrates how the custom workingset finder is invoked.

```python
CallbackAlgorithm(
    epochs=(epoch1, epoch2),
    corepoints=corepoints,
    cyl_radius=2.0,
    normal_radii=(1.0, 2.0),
).run()
```

--------------------------------

### Download and Load Point Cloud Data

Source: https://py4dgeo.readthedocs.io/en/latest/hierarchical_change_analysis.html

Downloads a sample dataset from Zenodo using pooch and loads two point clouds from LAS files for analysis. Ensure the data path is correctly set after extraction.

```python
# Set up pooch to download data from Zenodo
p = pooch.Pooch(base_url="doi:10.5281/zenodo.18432391/", path=pooch.os_cache("py4dgeo"))
p.load_registry_from_doi()

try:
    # Download and extract the dataset
    p.fetch("trier_sim.zip", processor=pooch.Unzip(members=["trier_sim"]))

    # Define path to the extracted data
    data_path = p.path / "trier_sim.zip.unzip"
    print(f"Data path: {data_path}")

    before_rockfall_file = (
        data_path / "trier_sim_epoch_0.laz"  # Synthetic data of terrain before a simulated rockfall at Trier study site
    )
    after_rockfall_file = (
        data_path / "trier_sim_epoch_1.laz"  # Synthetic data of terrain after a simulated rockfall at Trier study site
    )

    epoch1, epoch2 = py4dgeo.read_from_las(before_rockfall_file, after_rockfall_file)


except Exception as e:
    print(f"Failed to download or extract data: {e}")
```

--------------------------------

### py4dgeo.get_num_threads

Source: https://py4dgeo.readthedocs.io/en/latest/_sources/pythonapi.rst.txt

Gets the current number of threads used by py4dgeo.

```APIDOC
## Function: py4dgeo.get_num_threads

### Description
Retrieves the current number of threads that py4dgeo is configured to use for parallel processing.

### Returns
(Return type is documented within the source, refer to the original documentation for details.)
```

--------------------------------

### Get normal directions

Source: https://py4dgeo.readthedocs.io/en/latest/m3c2.html

Retrieves the normal vectors for each core point, used to determine the direction of surface change.

```python
directions = m3c2.directions()
```

--------------------------------

### Download and Prepare Analysis Data

Source: https://py4dgeo.readthedocs.io/en/latest/4dobc-analysis.html

Fetches the required test data for analysis and sets up a temporary directory to store it. This step is crucial for running the 4D-OBC analysis, assuming an analysis file is available.

```python
# Fetch original test data
test_filename = "synthetic.zip"
original_file = find_file(test_filename)
print(f"File downloaded to: {original_file}")

# Create temporary directory
tmpdir = tempfile.mkdtemp()
zip_file = Path(tmpdir) / test_filename
```

--------------------------------

### Get normal radii used

Source: https://py4dgeo.readthedocs.io/en/latest/m3c2.html

Retrieves the radii used for normal computation at each core point, relevant for multi-scale analysis.

```python
direction_radii = m3c2.directions_radii()
```

--------------------------------

### Copy and Prepare Data for Analysis

Source: https://py4dgeo.readthedocs.io/en/latest/4dobc-analysis.html

Copies a specified test file into a temporary directory and prints the path to the working copy. This is a preliminary step before analysis.

```python
shutil.copy(find_file(test_filename), zip_file)
print(f"Working copy: {zip_file}")
```

--------------------------------

### Import necessary libraries

Source: https://py4dgeo.readthedocs.io/en/latest/customization.html

Imports py4dgeo and numpy for general use, and find_file for data loading.

```python
import py4dgeo

import numpy as np

from py4dgeo.util import find_file
```

--------------------------------

### Instantiate and run M3C2 algorithm

Source: https://py4dgeo.readthedocs.io/en/latest/m3c2.html

Initializes the M3C2 algorithm with specified epochs, core points, and radii, then runs the distance calculation.

```python
m3c2 = py4dgeo.M3C2(
    epochs=(epoch1, epoch2),
    corepoints=corepoints,
    cyl_radius=2.0,
    normal_radii=[0.5, 1.0, 2.0],
)

distances, uncertainties = m3c2.run()
```

--------------------------------

### Instantiate and Run M3C2EP Algorithm

Source: https://py4dgeo.readthedocs.io/en/latest/m3c2ep.html

Instantiates the M3C2EP algorithm with specified epochs, core points, and M3C2 parameters, including alignment matrices. Then, it runs the distance calculation.

```python
m3c2_ep = py4dgeo.M3C2EP(
    epochs=(epoch1, epoch2),
    corepoints=corepoints,
    normal_radii=(0.5, 1.0, 2.0),
    cyl_radius=0.5,
    max_distance=3.0,
    Cxx=Cxx,
    tfM=tfM,
    refPointMov=refPointMov,
)

distances, uncertainties, covariance = m3c2_ep.run()

```

--------------------------------

### load

Source: https://py4dgeo.readthedocs.io/en/latest/pythonapi.html

Constructs an Epoch instance by loading it from a file.

```APIDOC
## load

Construct an Epoch instance by loading it from a file.

### Parameters

*   **filename** (str) - The filename to load the epoch from.
```

--------------------------------

### get_cell_index_start

Source: https://py4dgeo.readthedocs.io/en/latest/cppapi.html

Retrieves the starting index of a cell in a sorted array of point indices and spatial keys. This is useful for locating the beginning of a contiguous block of points belonging to a specific cell.

```APIDOC
## get_cell_index_start

### Description
Returns the first occurrence of the index of a cell in the sorted array of point indices and point spatial keys.

### Method
const

### Parameters
#### Path Parameters
- **key** (SpatialKey) - The spatial key of the query cell
- **bitShift** (SpatialKey) - The bit shift corresponding to the Octree depth level of the query cell
- **start_index** (IndexType) - Start index
- **end_index** (IndexType) - End index

### Returns
- **std::optional<IndexType>** - The index of first occurrence of the cell spatial key
```

--------------------------------

### Instantiate PBM3C2 algorithm

Source: https://py4dgeo.readthedocs.io/en/latest/pbm3c2.html

Initializes the PBM3C2 algorithm with a specified registration error. This parameter influences the algorithm's sensitivity to input data noise.

```python
alg = py4dgeo.PBM3C2(registration_error=0.01)
```

--------------------------------

### Define Core Points for Analysis

Source: https://py4dgeo.readthedocs.io/en/latest/4dobc-creation.html

Sets the core points for the spatiotemporal analysis. In this example, all points from the reference epoch are used as core points. This defines the spatial extent for change detection.

```python
analysis.corepoints = reference_epoch
```

--------------------------------

### Download and prepare test data

Source: https://py4dgeo.readthedocs.io/en/latest/4dobc-customization.html

Fetches test data from an external link and creates a working copy in a temporary directory for analysis.

```python
# Fetch original test data
test_filename = "synthetic.zip"
original_file = find_file(test_filename)
print(f"File downloaded to: {original_file}")

# Create temporary directory
tmpdir = tempfile.mkdtemp()
zip_file = Path(tmpdir) / test_filename

# Copy original file into temporary directory
shutil.copy(find_file(test_filename), zip_file)
print(f"Working copy: {zip_file}")
```

--------------------------------

### Define custom seed sorting criterion

Source: https://py4dgeo.readthedocs.io/en/latest/4dobc-customization.html

Defines a custom function for prioritizing seeds in the 4D-OBC algorithm. This example returns a random score for each seed, leading to a random seed order.

```python
def sorting_criterion(seed):
    # Choose a random score, resulting in random seed order
    return np.random.rand()
```

--------------------------------

### py4dgeo.m3c2.M3C2LikeAlgorithm.run

Source: https://py4dgeo.readthedocs.io/en/latest/pythonapi.html

Executes the M3C2 algorithm.

```APIDOC
## py4dgeo.m3c2.M3C2LikeAlgorithm.run()

### Description
Main entry point for running the algorithm.
```

--------------------------------

### Save Voxels as PLY Mesh

Source: https://py4dgeo.readthedocs.io/en/latest/spatial_subsampling.html

This code saves the occupied voxels as a triangle mesh in a PLY file. It allows specifying the features to store with each voxel and the mode for defining the center of each cube. Requires the 'plyfile' library to be installed.

```python
try:
    outfile_ply = outfile.replace(".laz", ".ply")
    reduced_vapc.save_as_ply(
        outfile=outfile_ply, features=reduced_vapc.out.keys(), mode=reduce_to_mode
    )
    print(f"Results saved to folder: {data_path}")
except:
    print("Failed to save PLY file. Check if 'plyfile' is installed.")
    print("You can try installing it by uncommenting and running the following lines of code in a new cell:")
    print("import sys")
    print("!conda install --yes --prefix {sys.prefix} conda-forge::plyfile")
```

--------------------------------

### Run the Python fallback M3C2 algorithm

Source: https://py4dgeo.readthedocs.io/en/latest/customization.html

Instantiate and run the PythonFallbackM3C2 algorithm with specified parameters. This serves as a reference implementation.

```python
PythonFallbackM3C2(
    epochs=(epoch1, epoch2),
    corepoints=corepoints,
    cyl_radius=2.0,
    normal_radii=(1.0, 2.0),
).run()
```

--------------------------------

### Reduce Vapc and Save as PLY

Source: https://py4dgeo.readthedocs.io/en/latest/hierarchical_change_analysis.html

Reduces a Vapc object to one point per voxel using a specified mode and saves the result as a PLY file, including selected features. This function requires the 'plyfile' library to be installed.

```python
# Let's reduce our point cloud to one point per voxel to ensure that we don't write duplicate voxels.
try:
    reduce_to_mode = "closest_to_voxel_centers"  # other options are "closest_to_centroids", "closest_to_voxel_centers", "centroid", "voxel_center"
    reduced_vapc = voxel_epoch_1_with_significant_change.reduce_to_feature(
        reduce_to_mode
    )

    reduced_vapc.save_as_ply(
        outfile=outfile_ply, features=reduced_vapc.out.keys(), mode=reduce_to_mode
    )
    print(f"Results saved to folder: {data_path}")
except:
    print("Failed to save PLY file. Check if 'plyfile' is installed.")
    print(
        "You can try installing it by uncommenting and running the following lines of code in a new cell:"
    )
    print("import sys")
    print("!conda install --yes --prefix {sys.prefix} conda-forge::plyfile")
```

--------------------------------

### Configure Region Growing Algorithm

Source: https://py4dgeo.readthedocs.io/en/latest/4dobc-analysis.html

Instantiates a RegionGrowingAlgorithm with specified parameters for neighborhood radius, seed subsampling, window width, minimum period, and height threshold. These parameters control the change point detection and region growing process.

```python
algo = py4dgeo.RegionGrowingAlgorithm(
    neighborhood_radius=2.0,
    seed_subsampling=30,
    window_width=6,
    minperiod=3,
    height_threshold=0.05,
)
```

--------------------------------

### KDTree::build_tree

Source: https://py4dgeo.readthedocs.io/en/latest/cppapi.html

Builds the KDTree index, initializing it for searches.

```APIDOC
## KDTree::build_tree

### Description
Build the KDTree index. This initializes the KDTree search index. Calling this method is required before performing any nearest neighbors or radius searches.

### Method
`void build_tree(int leaf)`

### Parameters
* **leaf** (`int`) - The threshold parameter defining at what size the search tree is cutoff. Below the cutoff, a brute force search is performed. This parameter controls a trade-off between search tree build time and query time.
```

--------------------------------

### View ICP algorithm documentation

Source: https://py4dgeo.readthedocs.io/en/latest/registration.html

Opens the documentation for the `py4dgeo.point_to_plane_icp` function, providing details on its parameters and usage.

```python
?py4dgeo.point_to_plane_icp
```

--------------------------------

### Display First 8 Num Samples 1

Source: https://py4dgeo.readthedocs.io/en/latest/m3c2ep.html

Displays the 'num_samples1' component for the first 8 core points, indicating the number of points considered in the first epoch for each core point.

```python
uncertainties["num_samples1"][0:8]

```

--------------------------------

### Output from running algorithm with custom callback

Source: https://py4dgeo.readthedocs.io/en/latest/customization.html

The output shows the results of the algorithm run, including the printed message from the custom workingset finder callback, indicating it was executed.

```text
I was called and returned a single pointI was called and returned a single point
I was called and returned a single point

I was called and returned a single point
I was called and returned a single point
I was called and returned a single point
I was called and returned a single point
I was called and returned a single point
I was called and returned a single point
I was called and returned a single point
```

--------------------------------

### Initialize Spatiotemporal Analysis

Source: https://py4dgeo.readthedocs.io/en/latest/4dobc-analysis.html

Initializes a SpatiotemporalAnalysis object using a provided zip file. This object will be used to perform various spatiotemporal analyses.

```python
analysis = py4dgeo.SpatiotemporalAnalysis(zip_file)
```

--------------------------------

### Import py4dgeo and numpy

Source: https://py4dgeo.readthedocs.io/en/latest/hierarchical_change_analysis.html

Imports necessary libraries for point cloud processing and numerical operations.

```python
import py4dgeo
import numpy as np
import pooch
```

--------------------------------

### Download and locate test data

Source: https://py4dgeo.readthedocs.io/en/latest/customization.html

Fetches the 'usage_data.zip' file from the py4dgeo cache and prints its location. This is a prerequisite for loading point cloud data.

```python
# Fetch original test data
test_filename = "usage_data.zip"
original_file = find_file(test_filename)
print(f"File downloaded to: {original_file}")
```

--------------------------------

### py4dgeo.PBM3C2

Source: https://py4dgeo.readthedocs.io/en/latest/_sources/pythonapi.rst.txt

Implements the PBM3C2 algorithm.

```APIDOC
## Class: py4dgeo.PBM3C2

### Description
Implements the PBM3C2 algorithm, likely a variant or extension of the M3C2 algorithm. This class provides specific functionalities for PBM3C2 computations.

### Members
(Members are documented within the source, refer to the original documentation for details on specific methods and attributes.)
```

--------------------------------

### py4dgeo.fallback.PythonFallbackM3C2.run

Source: https://py4dgeo.readthedocs.io/en/latest/pythonapi.html

Executes the fallback M3C2 algorithm.

```APIDOC
## py4dgeo.fallback.PythonFallbackM3C2.run()

### Description
Main entry point for running the algorithm.
```

--------------------------------

### Run PBM3C2 algorithm

Source: https://py4dgeo.readthedocs.io/en/latest/pbm3c2.html

Executes the PBM3C2 algorithm using two epochs, a correspondence file, and specified application IDs. The search radius controls the neighborhood considered for matching.

```python
correspondences_df = alg.run(
    epoch0=epoch0,
    epoch1=epoch1,
    correspondences_file=find_file("epoch_extended_y.csv"),
    apply_ids=apply_ids,
    search_radius=5.0,
)
```

--------------------------------

### py4dgeo.CloudCompareM3C2

Source: https://py4dgeo.readthedocs.io/en/latest/_sources/pythonapi.rst.txt

Provides M3C2 functionality compatible with CloudCompare.

```APIDOC
## Class: py4dgeo.CloudCompareM3C2

### Description
Provides M3C2 functionality that is compatible with CloudCompare. This class inherits from base classes and includes specific methods for CloudCompare integration.

### Members
(Members are documented within the source, refer to the original documentation for details on specific methods and attributes.)

### Inheritance
(Inheritance details are documented within the source, refer to the original documentation for details.)
```

--------------------------------

### py4dgeo.segmentation.RegionGrowingAlgorithmBase.run

Source: https://py4dgeo.readthedocs.io/en/latest/pythonapi.html

Calculates the segmentation.

```APIDOC
## py4dgeo.segmentation.RegionGrowingAlgorithmBase.run(_analysis_ , _force =False_)

### Description
Calculate the segmentation.

### Parameters
* **_analysis** (_py4dgeo.segmentation.SpatiotemporalAnalysis_): The analysis object we are working with.
* **_force** (bool): Force recalculation of results. If false, some intermediate results will be restored from the analysis object instead of being recalculated.
```

--------------------------------

### Configure M3C2 Algorithm

Source: https://py4dgeo.readthedocs.io/en/latest/4dobc-creation.html

Initializes the M3C2 algorithm with specified parameters. `cyl_radius` and `normal_radii` are key parameters for the M3C2 distance calculation.

```python
analysis.m3c2 = py4dgeo.M3C2(cyl_radius=2.0, normal_radii=[2.0])
```

--------------------------------

### py4dgeo.m3c2.M3C2LikeAlgorithm

Source: https://py4dgeo.readthedocs.io/en/latest/_sources/pythonapi.rst.txt

Base class for M3C2-like algorithms.

```APIDOC
## Class: py4dgeo.m3c2.M3C2LikeAlgorithm

### Description
This is a base class for algorithms that are similar to M3C2. It likely defines common interfaces and functionalities for M3C2-based computations.

### Members
(Members are documented within the source, refer to the original documentation for details on specific methods and attributes.)
```

--------------------------------

### Download and Unzip Data Files

Source: https://py4dgeo.readthedocs.io/en/latest/4dobc-analysis.html

Demonstrates the process of downloading and unzipping various data files (usage_data.zip, synthetic.zip, pbm3c2.zip) from DOIs into a specified cache directory. This is essential for preparing data for analysis.

```shell
Downloading file 'usage_data.zip' from 'doi:10.5281/zenodo.18378272/usage_data.zip' to '/home/docs/.cache/py4dgeo'.
Unzipping contents of '/home/docs/.cache/py4dgeo/usage_data.zip' to '/home/docs/.cache/py4dgeo/extracted'
Downloading file 'synthetic.zip' from 'doi:10.5281/zenodo.18378272/synthetic.zip' to '/home/docs/.cache/py4dgeo'.
Unzipping contents of '/home/docs/.cache/py4dgeo/synthetic.zip' to '/home/docs/.cache/py4dgeo/extracted'
Downloading file 'pbm3c2.zip' from 'doi:10.5281/zenodo.18378272/pbm3c2.zip' to '/home/docs/.cache/py4dgeo'.
Unzipping contents of '/home/docs/.cache/py4dgeo/pbm3c2.zip' to '/home/docs/.cache/py4dgeo/extracted'
```

--------------------------------

### Find and print test data file path

Source: https://py4dgeo.readthedocs.io/en/latest/pbm3c2.html

Locates a specified test file and prints its download path. Useful for verifying data availability.

```python
test_filename = "pbm3c2.zip"
original_file = find_file(test_filename)
print(f"File downloaded to: {original_file}")
```

--------------------------------

### Load test data for analysis

Source: https://py4dgeo.readthedocs.io/en/latest/4dobc-customization.html

Initializes a SpatiotemporalAnalysis object with the provided data file.

```python
# Load test data
analysis = py4dgeo.SpatiotemporalAnalysis(zip_file)
```

--------------------------------

### CallbackExceptionVault

Source: https://py4dgeo.readthedocs.io/en/latest/cppapi.html

A utility to safely run callbacks and manage exceptions.

```APIDOC
## CallbackExceptionVault

### Description

This class provides a mechanism to execute callback functions and safely catch and rethrow any exceptions that occur during their execution.

### Methods

- **run()** - Executes the stored callback function.
- **rethrow()** - Rethrows any caught exception if one exists.

### Fields

- **ptr** - A pointer to the exception object, if an exception was caught.
```

--------------------------------

### Load point cloud epochs

Source: https://py4dgeo.readthedocs.io/en/latest/registration.html

Reads point cloud data from XYZ files into py4dgeo Epoch objects. Ensure the files are correctly located.

```python
# Read XYZ files from the extracted directory
reference_epoch, epoch = py4dgeo.read_from_xyz(
    find_file("plane_horizontal_t1.xyz"), find_file("plane_horizontal_t2.xyz")
)
```

--------------------------------

### Initialize Spatiotemporal Analysis

Source: https://py4dgeo.readthedocs.io/en/latest/4dobc-creation.html

Creates a new spatiotemporal analysis object. Use `force=True` to overwrite an existing analysis file if necessary. This object will store all analysis-related data.

```python
analysis = py4dgeo.SpatiotemporalAnalysis("test.zip", force=True)
```

--------------------------------

### Importing Existing Transformations

Source: https://py4dgeo.readthedocs.io/en/latest/registration.html

Load transformations as numpy arrays and pass them to Epoch.transform. You can define rotation and translation individually or provide a 3x4 matrix to affine_transformation.

```python
epoch.transform(
    rotation=np.array([[1, 0, 0], [0, 1, 0], [0, 0, 1]]),
    translation=np.array([0, 0, 0]),
    reduction_point=np.array([0, 0, 0]),
)
```

--------------------------------

### Load point clouds from XYZ files

Source: https://py4dgeo.readthedocs.io/en/latest/customization.html

Reads two XYZ files into py4dgeo epoch objects. Ensure the files exist in the specified path. This step is crucial for any point cloud processing.

```python
# Read XYZ files from the extracted directory
epoch1, epoch2 = py4dgeo.read_from_xyz(
    find_file("plane_horizontal_t1.xyz"), find_file("plane_horizontal_t2.xyz")
)
```

--------------------------------

### KDTree::create

Source: https://py4dgeo.readthedocs.io/en/latest/cppapi.html

Constructs a KDTree instance from a given point cloud. This is a static factory method.

```APIDOC
## KDTree::create

### Description
Construct instance of KDTree from a given point cloud. This is implemented as a static function instead of a public constructor to ease the implementation of Python bindings.

### Method
`static KDTree create(const EigenPointCloudRef &cloud)`

### Parameters
* **cloud** (`const EigenPointCloudRef&`) - The point cloud to construct the KDTree from.
```

--------------------------------

### Import py4dgeo and C++ bindings

Source: https://py4dgeo.readthedocs.io/en/latest/4dobc-customization.html

Imports the necessary py4dgeo library and its C++ bindings module. Also imports utility modules for data handling.

```python
import py4dgeo
import _py4dgeo  # The C++ bindings module for py4dgeo

import numpy as np
import tempfile
import shutil

from pathlib import Path
from py4dgeo.util import find_file
```

--------------------------------

### Run custom algorithm with constant direction

Source: https://py4dgeo.readthedocs.io/en/latest/customization.html

Instantiates and runs the 'DirectionAlgorithm' with specified epochs, corepoints, and cylinder radius. This demonstrates the usage of the custom algorithm with a fixed search direction.

```python
DirectionAlgorithm(epochs=(epoch1, epoch2), corepoints=corepoints, cyl_radius=5.0).run()
```

--------------------------------

### py4dgeo.m3c2.M3C2LikeAlgorithm

Source: https://py4dgeo.readthedocs.io/en/latest/pythonapi.html

Implements a M3C2-like algorithm for point cloud analysis.

```APIDOC
## py4dgeo.m3c2.M3C2LikeAlgorithm

### Description
An implementation of the M3C2 algorithm.

### Parameters
* **_epochs** (Tuple[Epoch, ...] | None): A tuple of Epoch objects.
* **_corepoints** (ndarray | None): Corepoints for the algorithm.
* **_cyl_radii** (List | None): List of cylinder radii.
* **_cyl_radius** (float | None): Cylinder radius.
* **_max_distance** (float): Maximum distance for calculations. Defaults to 0.0.
* **_registration_error** (float): Registration error. Defaults to 0.0.
* **_robust_aggr** (bool): Whether to use robust aggregation. Defaults to False.
```

--------------------------------

### Run Region Growing with Custom Seeds

Source: https://py4dgeo.readthedocs.io/en/latest/4dobc-customization.html

Instantiate the custom seed detection algorithm and run it on the analysis object. Ensure to invalidate previous results before running the new algorithm.

```python
analysis.invalidate_results()
objects = DifferentSeeds(
    neighborhood_radius=2.0,
    seed_subsampling=20,
).run(analysis)
```

--------------------------------

### Developer API - File System Utilities

Source: https://py4dgeo.readthedocs.io/en/latest/pythonapi.html

Utilities for finding files and checking memory policy in the developer API.

```APIDOC
## Developer API - File System Utilities

### Description
Functions for locating files and checking memory policy status.

### Functions
- `find_file(filename)`: Finds a file in the system.
- `memory_policy_is_minimum()`: Checks if the minimum memory policy is active.
```

--------------------------------

### build_octree

Source: https://py4dgeo.readthedocs.io/en/latest/pythonapi.html

Builds the search octree index.

```APIDOC
## build_octree

Build the search octree index.
```

--------------------------------

### Developer API - RegionGrowingAlgorithmBase

Source: https://py4dgeo.readthedocs.io/en/latest/pythonapi.html

Base class for region growing algorithms in the developer API.

```APIDOC
## Developer API - RegionGrowingAlgorithmBase

### Description
Base class providing common functionality for region growing algorithms.

### Methods
- `RegionGrowingAlgorithmBase.distance_measure(point1, point2)`
- `RegionGrowingAlgorithmBase.filter_objects(objects)`
- `RegionGrowingAlgorithmBase.find_seedpoints(epoch)`
- `RegionGrowingAlgorithmBase.run(epoch, seed_points)`
- `RegionGrowingAlgorithmBase.seed_sorting_scorefunction(seed)`

### Properties
- `RegionGrowingAlgorithmBase.analysis`
```

--------------------------------

### py4dgeo::RegionGrowingAlgorithmData

Source: https://py4dgeo.readthedocs.io/en/latest/cppapi.html

Data structure for region growing algorithms, containing distances, core points, and parameters.

```APIDOC
## py4dgeo::RegionGrowingAlgorithmData

### Description

This structure holds all the necessary data and parameters for the region growing algorithm.

### Fields

- **distances** (EigenSpatiotemporalArrayConstRef) - A reference to the spatiotemporal distances.
- **corepoints** (std::vector<int>) - A list of indices representing core points.
- **radius** (double) - The radius parameter for region growing.
- **seed** (py4dgeo::RegionGrowingSeed) - The seed point for the region growing process.
- **thresholds** (std::vector<double>) - A list of thresholds to be applied.
- **min_segments** (int) - The minimum number of segments required.
- **max_segments** (int) - The maximum number of segments allowed.
```

--------------------------------

### Developer API - M3C2LikeAlgorithm

Source: https://py4dgeo.readthedocs.io/en/latest/pythonapi.html

Interface for M3C2-like algorithms in the developer API.

```APIDOC
## Developer API - M3C2LikeAlgorithm

### Description
An abstract or base interface for algorithms that behave like M3C2.

### Methods
- `M3C2LikeAlgorithm.calculate_distances()`
- `M3C2LikeAlgorithm.callback_distance_calculation()`
- `M3C2LikeAlgorithm.callback_workingset_finder()`
- `M3C2LikeAlgorithm.directions()`
- `M3C2LikeAlgorithm.run()`
```

--------------------------------

### Access uncertainty data (num_samples1)

Source: https://py4dgeo.readthedocs.io/en/latest/m3c2.html

Retrieves the 'num_samples1' uncertainty values, indicating the number of points considered in the first cloud.

```python
uncertainties["num_samples1"]
```

--------------------------------

### Define training and application IDs

Source: https://py4dgeo.readthedocs.io/en/latest/pbm3c2.html

Sets up arrays for training and application segment IDs based on the total number of planes. Used to partition the dataset for learning and testing.

```python
n_planes = 100
n_train = int(0.7 * n_planes)
train_ids = np.arange(n_train)
apply_ids = np.arange(n_train, n_planes)
```

--------------------------------

### Octree::create

Source: https://py4dgeo.readthedocs.io/en/latest/cppapi.html

Constructs an instance of the Octree from a given point cloud.

```APIDOC
## Octree::create

### Description
Construct instance of Octree from a given point cloud. This is implemented as a static function instead of a public constructor to ease the implementation of Python bindings.

### Parameters
* **cloud** (EigenPointCloudRef) - The point cloud to construct the search tree for.

### Returns
An instance of the Octree.
```

--------------------------------

### Define output file path

Source: https://py4dgeo.readthedocs.io/en/latest/spatial_subsampling.html

Sets the output file name for the subsampled point cloud by modifying the input file name.

```python
outfile = str(infile).replace(".laz", "_subsampled.laz")
```

--------------------------------

### Select core points

Source: https://py4dgeo.readthedocs.io/en/latest/m3c2.html

Subsamples the reference point cloud to select core points for analysis. Every 50th point is chosen.

```python
corepoints = epoch1.cloud[::50]
```

--------------------------------

### save

Source: https://py4dgeo.readthedocs.io/en/latest/pythonapi.html

Saves the epoch to a file.

```APIDOC
## save

Save this epoch to a file.

### Parameters

*   **filename** (str) - The filename to save the epoch in.
```

--------------------------------

### py4dgeo.RegionGrowingAlgorithm

Source: https://py4dgeo.readthedocs.io/en/latest/_sources/pythonapi.rst.txt

Implements a region growing algorithm for point cloud segmentation.

```APIDOC
## Class: py4dgeo.RegionGrowingAlgorithm

### Description
Implements a region growing algorithm for point cloud segmentation. This class inherits from base classes and provides specific functionalities for region growing.

### Members
(Members are documented within the source, refer to the original documentation for details on specific methods and attributes.)

### Inheritance
(Inheritance details are documented within the source, refer to the original documentation for details.)
```

--------------------------------

### Display First 8 Distances

Source: https://py4dgeo.readthedocs.io/en/latest/m3c2ep.html

Displays the first 8 calculated distances between the two point clouds for the core points.

```python
distances[0:8]

```

--------------------------------

### Display training correspondence file structure

Source: https://py4dgeo.readthedocs.io/en/latest/pbm3c2.html

Reads and prints the first few rows of a correspondence file to illustrate its structure. This file is crucial for training the PBM3C2 model.

```python
training_sample = pd.read_csv(find_file("epoch_extended_y.csv"), header=None, nrows=3)

print("Training correspondence file structure (first 3 rows):")
print(training_sample.to_string(index=False, header=False))
print("\nFormat explanation:")
print("  - Column 0: Segment ID from epoch 0")
print("  - Column 1: Corresponding segment ID from epoch 1")
print("  - Column 2: Label (1 = correct match, 0 = incorrect match)")
```

--------------------------------

### Import PythonFallbackM3C2 for educational purposes

Source: https://py4dgeo.readthedocs.io/en/latest/customization.html

Import the PythonFallbackM3C2 class, which provides an M3C2 implementation exclusively using Python fallbacks for educational, testing, and debugging.

```python
from py4dgeo.fallback import PythonFallbackM3C2
```

--------------------------------

### py4dgeo.set_py4dgeo_logfile

Source: https://py4dgeo.readthedocs.io/en/latest/_sources/pythonapi.rst.txt

Sets the log file for py4dgeo.

```APIDOC
## Function: py4dgeo.set_py4dgeo_logfile

### Description
Configures the logging for the py4dgeo package by setting the path to the log file.

### Parameters
(Parameters are documented within the source, refer to the original documentation for details.)
```

--------------------------------

### build_tree

Source: https://py4dgeo.readthedocs.io/en/latest/cppapi.html

Builds the Octree index, which is required before performing any nearest neighbors or radius searches. The bounding box can be optionally forced to be cubic, and its corners can be specified.

```APIDOC
## build_tree

### Description
Builds the Octree index. This initializes the Octree search index. Calling this method is required before performing any nearest neighbors or radius searches.

### Parameters
- **force_cubic** (bool) - Optional - If true, the bounding box will be forced to have equal side lengths, resulting in a cubic shape.
- **min_corner** (std::optional<Eigen::Vector3d>) - Optional - Minimum point (lower corner of the bounding box). If not provided, the minimum point is computed automatically from the input data.
- **max_corner** (std::optional<Eigen::Vector3d>) - Optional - Maximum point (upper corner of the bounding box). If not provided, the maximum point is computed automatically from the input data.
```

--------------------------------

### read_from_xyz

Source: https://py4dgeo.readthedocs.io/en/latest/pythonapi.html

Creates an epoch from an XYZ file.

```APIDOC
## read_from_xyz

Create an epoch from an xyz file.

### Parameters

*   **filenames** (*str) - The filename(s) to read from. Each line is expected to contain three space-separated numbers.
*   **xyz_columns** (list) - Column indices for X, Y, and Z coordinates. Defaults to [0, 1, 2].
*   **normal_columns** (list) - Column names for normal vector components. Leave empty if normals are not present.
*   **additional_dimensions** (dict) - Maps names of additional data dimensions in the input dataset to dimensions in the epoch data structure.
*   **additional_dimensions_dtypes** (dict) - Maps names of additional dimensions to their data types.
*   **parse_opts** (**kwargs) - Additional parsing options.
```

--------------------------------

### Applying Transformation to Epoch

Source: https://py4dgeo.readthedocs.io/en/latest/registration.html

Shows how to apply a computed transformation to an epoch object and access the applied transformation.

```APIDOC
## Apply Transformation

### Description
Applies a computed affine transformation to an epoch object and retrieves the transformation details.

### Method
`epoch.transform(trafo)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
epoch.transform(trafo)
```

### Response
#### Success Response (200)
This method modifies the epoch in-place and does not return a value. The transformation is recorded within the epoch object.

### Accessing Transformation
#### Method
`epoch.transformation`

#### Description
Retrieves the transformation that has been applied to the epoch.

#### Response Example
```json
[
  {
    "affine_transformation": [
      [ 1.00000000e+00,  6.34089843e-10, -1.42106695e-05,
       -7.59183919e-03],
      [-1.25012920e-10,  9.99999999e-01,  3.58235678e-05,
        7.09922947e-03],
      [ 1.42106695e-05, -3.58235678e-05,  9.99999999e-01,
        2.11030351e+01],
      [ 0.00000000e+00,  0.00000000e+00,  0.00000000e+00,
        1.00000000e+00]
    ],
    "reduction_point": [0, 0, 0]
  }
]
```
```

--------------------------------

### py4dgeo::KDTree::Adaptor

Source: https://py4dgeo.readthedocs.io/en/latest/cppapi.html

An adaptor class for the KD-tree to access point cloud data.

```APIDOC
## py4dgeo::KDTree::Adaptor

### Description
Provides an interface for the KD-tree to access point cloud data, conforming to the nanoflann library requirements.

### Methods
- **kdtree_get_point_count()**: Returns the total number of points.
- **kdtree_get_pt(size_t idx, float* out_pt) const**: Retrieves the coordinates of a point at a given index.
- **kdtree_get_bbox(float* out_bb) const**: Retrieves the bounding box of the point cloud.
```

--------------------------------

### build_kdtree

Source: https://py4dgeo.readthedocs.io/en/latest/pythonapi.html

Builds the search tree index for efficient nearest neighbor queries.

```APIDOC
## build_kdtree

Build the search tree index.

### Parameters

*   **leaf_size** (int) - An internal optimization parameter. Increasing this value speeds up search tree build time, but slows down query times.
*   **force_rebuild** (bool) - Rebuild the search tree even if it was already built before.
```

--------------------------------

### py4dgeo.fallback.PythonFallbackM3C2

Source: https://py4dgeo.readthedocs.io/en/latest/_sources/pythonapi.rst.txt

A fallback implementation of M3C2 in Python.

```APIDOC
## Class: py4dgeo.fallback.PythonFallbackM3C2

### Description
Provides a fallback implementation of the M3C2 algorithm written purely in Python. This can be used when the optimized version is not available or for debugging purposes.

### Members
(Members are documented within the source, refer to the original documentation for details on specific methods and attributes.)

### Inheritance
(Inheritance details are documented within the source, refer to the original documentation for details.)
```

--------------------------------

### Read XYZ files

Source: https://py4dgeo.readthedocs.io/en/latest/m3c2.html

Reads two point cloud files in XYZ format. Ensure the file paths are correct.

```python
epoch1, epoch2 = py4dgeo.read_from_xyz(
    find_file("plane_horizontal_t1.xyz"), find_file("plane_horizontal_t2.xyz")
)
```

--------------------------------

### Run M3C2 Change Detection Algorithm

Source: https://py4dgeo.readthedocs.io/en/latest/hierarchical_change_analysis.html

Initializes and runs the M3C2 algorithm for change detection between two epochs. Ensure 'epoch1' and 'epoch2' are defined and 'voxel_epoch_1_with_significant_change' is prepared.

```python
m3c2 = py4dgeo.M3C2(
    epochs=(epoch1, epoch2),
    corepoints=voxel_epoch_1_with_significant_change.epoch.cloud,
    cyl_radius=1.0,
    normal_radii=[1.0],
    max_distance=10.0,
)

distances, uncertainties = m3c2.run()
```

--------------------------------

### Load Sensor Orientation from JSON

Source: https://py4dgeo.readthedocs.io/en/latest/m3c2ep.html

Loads sensor orientation information from a JSON file and assigns it to both epochs. This assumes both epochs share the same sensor configuration.

```python
with open(find_file("sps.json"), "r") as load_f:
    scanpos_info_dict = eval(load_f.read())
epoch1.scanpos_info = scanpos_info_dict
epoch2.scanpos_info = scanpos_info_dict

```

--------------------------------

### Output from running Python fallback M3C2 algorithm

Source: https://py4dgeo.readthedocs.io/en/latest/customization.html

The output displays the results obtained from running the M3C2 algorithm using its pure Python fallback implementation.

```text
(array([-0.10269286, -0.10179986, -0.10091512, -0.09819643, -0.09911222]),
 array([(0.00551873, 0.00401036,  5, 0.00485358,  5),
        (0.00255157, 0.00203436, 11, 0.00380835, 11),
        (0.00281475, 0.00259167, 12, 0.0040656 , 11),
        (0.00295429, 0.00328221, 11, 0.00377072, 11),
        (0.0036077 , 0.00356988, 10, 0.0043615 ,  9)],
       dtype=[('lodetection', '<f8'), ('spread1', '<f8'), ('num_samples1', '<i8'), ('spread2', '<f8'), ('num_samples2', '<i8')]))
```

--------------------------------

### loadIndex

Source: https://py4dgeo.readthedocs.io/en/latest/cppapi.html

Loads an Octree index from a provided input stream.

```APIDOC
## loadIndex

### Description
Load the index from a (file) stream.

### Parameters
- **stream** (std::istream &) - The input stream to load the index from.
```

--------------------------------

### Resulting data from custom callback run

Source: https://py4dgeo.readthedocs.io/en/latest/customization.html

The output data structure contains arrays representing the algorithm's results after processing with the custom callback.

```text
(array([0., 0., 0., 0., 0.]),
 array([(nan, nan, 1, nan, 1), (nan, nan, 1, nan, 1),
        (nan, nan, 1, nan, 1), (nan, nan, 1, nan, 1),
        (nan, nan, 1, nan, 1)],
       dtype=[('lodetection', '<f8'), ('spread1', '<f8'), ('num_samples1', '<i8'), ('spread2', '<f8'), ('num_samples2', '<i8')]))
```

--------------------------------

### py4dgeo.regular_corepoint_grid

Source: https://py4dgeo.readthedocs.io/en/latest/_sources/pythonapi.rst.txt

Generates a regular grid of core points.

```APIDOC
## Function: py4dgeo.regular_corepoint_grid

### Description
Generates a regular grid of core points, likely used for sampling or structuring point cloud data.

### Parameters
(Parameters are documented within the source, refer to the original documentation for details.)

### Returns
(Return type is documented within the source, refer to the original documentation for details.)
```

--------------------------------

### py4dgeo.M3C2

Source: https://py4dgeo.readthedocs.io/en/latest/_sources/pythonapi.rst.txt

Implements the M3C2 algorithm for normal and displacement estimation.

```APIDOC
## Class: py4dgeo.M3C2

### Description
Implements the M3C2 algorithm for normal and displacement estimation in point clouds. This class inherits from base classes and provides specific functionalities for M3C2.

### Members
(Members are documented within the source, refer to the original documentation for details on specific methods and attributes.)

### Inheritance
(Inheritance details are documented within the source, refer to the original documentation for details.)
```

--------------------------------

### Developer API - PythonFallbackM3C2

Source: https://py4dgeo.readthedocs.io/en/latest/pythonapi.html

Python implementation fallback for M3C2 in the developer API.

```APIDOC
## Developer API - PythonFallbackM3C2

### Description
A Python-based fallback implementation for the M3C2 algorithm.

### Methods
- `PythonFallbackM3C2.calculate_distances()`
- `PythonFallbackM3C2.callback_distance_calculation()`
- `PythonFallbackM3C2.callback_workingset_finder()`
- `PythonFallbackM3C2.directions()`
- `PythonFallbackM3C2.run()`
```

--------------------------------

### Define Output File Paths

Source: https://py4dgeo.readthedocs.io/en/latest/hierarchical_change_analysis.html

Sets the file paths for saving the results of the hierarchical change analysis in both LAS and PLY formats.

```python
outfile_las = str(before_rockfall_file).replace(
    ".laz", "_hierarchical_change_analysis_result.las"
)
outfile_ply = str(before_rockfall_file).replace(
    ".laz", "_hierarchical_change_analysis_result.ply"
)
```

--------------------------------

### KDTree

Source: https://py4dgeo.readthedocs.io/en/latest/cppapi.html

The KDTree class provides an efficient KD-tree implementation for nearest neighbor and radius searches in 3D point clouds.

```APIDOC
## KDTree

### Description
Represents a KD-tree data structure for efficient spatial searching.

### Public Functions

- `std::size_t kdtree_get_point_count() const`
  Returns the number of points in the KD-tree.

- `double kdtree_get_pt(const IndexType idx, const IndexType dim) const`
  Retrieves the coordinate of a point at a given index and dimension.

- `template<class BBOX>
bool kdtree_get_bbox(BBOX&) const`
  Retrieves the bounding box of the KD-tree.

### Public Members

- `EigenPointCloudRef cloud`
  The point cloud data used to construct the KD-tree.
```

--------------------------------

### C++ Median-IQR Distance Calculation

Source: https://py4dgeo.readthedocs.io/en/latest/callbacks.html

A C++ implementation for point cloud distance using median and interquartile range. This offers a more robust but computationally expensive alternative to the mean-based method.

```cpp
std::tuple<double, DistanceUncertainty> py4dgeo::median_iqr_distance(const DistanceUncertaintyCalculationParameters&)
```

--------------------------------

### Select core points from epoch1

Source: https://py4dgeo.readthedocs.io/en/latest/customization.html

Extracts a subset of points from the first epoch (epoch1) to be used as core points. This is done by selecting every 100th point.

```python
corepoints = epoch1.cloud[::100]
```

--------------------------------

### py4dgeo.segmentation.RegionGrowingAlgorithmBase

Source: https://py4dgeo.readthedocs.io/en/latest/_sources/pythonapi.rst.txt

Base class for region growing segmentation algorithms.

```APIDOC
## Class: py4dgeo.segmentation.RegionGrowingAlgorithmBase

### Description
This is the base class for region growing segmentation algorithms. It defines the fundamental interface and common functionalities for such algorithms.

### Members
(Members are documented within the source, refer to the original documentation for details on specific methods and attributes.)
```