pymeepcl

A Python library for efficient ray tracing operations on COPC (Cloud Optimized Point Cloud) files.

Overview

pymeepcl manages multiple COPC files for efficient spatial queries using ray tracing. It also maintains a cache of loaded point data to speed up subsequent queries. This module makes use of the python bindings of the copc-lib library.

Main Classes

MeeStruct

Manages multiple COPC files for efficient ray tracing operations. Provides a unified interface to work with one or more COPC files, enabling efficient spatial queries using ray tracing.

Key Attributes:

• cache: Cache for storing loaded node point data to reduce disk reads
• files: List of MeeFile objects representing the loaded COPC files
• bounds_copc: Combined global COPC bounding box of all files (tuple of minimums, maximums)
• bounds_las: Combined global LAS bounding box of all files (tuple of minimums, maximums)

Key Methods:

• trace_ray(ray, radius, return_sorted, timer, recursive): Traces a ray through all loaded files and returns points within a cylindrical radius
• add_file(filepath): Adds a new COPC file to the structure
• del_file(filepath): Removes a file from the structure and clears associated cache entries
• update_bounds(): Recalculates the combined global bounds of all loaded files

MeeFile

Represents a single COPC file. Handles reading, indexing, and bounding box logic.

Key Attributes:

• filepath: The path to the COPC file
• reader: The reader object for the COPC file
• config: The configuration object for the COPC file
• las_header: The header object for the LAS file
• node_entries: List of all nodes in the file
• is_indexed: True if the file has been indexed for vectorized intersection tests
• is_octree_indexed: True if the file has been indexed with octree structure
• bounds_copc_min, bounds_copc_max: Global COPC bounds of the file
• bounds_las_min, bounds_las_max: Global LAS bounds of the file

Key Methods:

• intersect_global(ray, radius): Checks if ray hits the root box
• intersect_nodes(ray, radius): Returns nodes intersected by ray, vectorized intersection test
• intersect_nodes_octree(ray, radius): Returns nodes intersected by ray, recursively traverses the file, if a parent node isn't hit the children will not be checked
• build_index(): Constructs numpy arrays for vectorized intersection tests
• build_index_octree(): Constructs octree structure for recursive traversal

Ray

Describes a ray using origin and direction. The direction vector is automatically normalized.

Key Attributes:

• origin: Origin point as list or numpy array of shape (3,)
• direction: Direction vector as list numpy array of shape (3,)

NodeCache

LRU cache for storing loaded node point data to reduce disk reads. Keys are tuples of (filepath, node_key_string), values are copclib.PointData objects.

Key Attributes:

• cache: OrderedDict storing the cached node data
• max_size: Maximum number of nodes to cache (default: 100)

Analysis

Segment

Container for a clustered point segment and its geometric features, including PCA/eigen features and shape descriptors (linearity, planarity, sphericity, omnivariance).

Key Attributes:

• id: Segment identifier
• points: Array of shape (N, 3) containing the point coordinates
• centroid: Center of mass (x, y, z)
• eigenvalues: Array [lambda1, lambda2, lambda3] in descending order
• normal_vector: Eigenvector of smallest eigenvalue
• linearity: Shape descriptor (lam1 - lam2) / lam1
• planarity: Shape descriptor (lam2 - lam3) / lam1
• sphericity: Shape descriptor lam3 / lam1
• omnivariance: Shape descriptor (lam1 * lam2 * lam3)^(1/3)
• equation: Plane equation coefficients in equation attribute (a, b, c, d for ax + by + cz + d = 0)

cluster_and_analyze (deprecated)

Clusters points based on 1D distance along the ray and calculates geometric features for each cluster. This method is being replaced by cluster_and_analyze_ransac which provides more robust plane fitting.

cluster_and_analyze_ransac

Iteratively fits planes to point clouds using RANSAC (Random Sample Consensus) and returns segments with geometric features. For the RANSAC algorythm the PyRANSAC3d library is used.

Function Signature: cluster_and_analyze_ransac(points, threshold=0.1, min_points=10, max_iterations=1000)

Parameters:

• points: (N, 3) array of points
• threshold: Maximum distance for a point to be considered an inlier (default: 0.1)
• min_points: Minimum points required to continue fitting planes (default: 10)
• max_iterations: Maximum RANSAC iterations per plane fit (default: 1000)

Returns:

• List of Segment objects, each containing:
  • Plane equation coefficients in equation attribute (a, b, c, d for ax + by + cz + d = 0)
  • Geometric features (linearity, planarity, sphericity, omnivariance)
  • Points belonging to that plane
  • Leftover points are returned as a segment with id=-1

Usage

Basic Example

from pymeepcl import MeeStruct, Ray
import numpy as np

# Initialize with a file or directory
struct = MeeStruct("path/to/file.copc.laz")
# or
struct = MeeStruct("path/to/directory/")

# Create a ray
ray = Ray(origin=[0, 0, 0], direction=[0, 0, -1])

# Trace the ray and get points within radius
points = struct.trace_ray(ray, radius=1.0, return_sorted=True)

# Cluster and analyze points
from pymeepcl import cluster_and_analyze_ransac
segments = cluster_and_analyze_ransac(points, threshold=0.1, min_points=10, max_iterations=1000)

Command Line

The library can also be used from the command line to trace a single ray and return the points in a specified outputfile:

python pymeepcl.py -i input.copc.laz -p 0 0 0 -d 0 0 -1 -r 1 -o output.xyz

Options:

• -i, --input: Path to COPC file or directory
• -p, --projektionszentrum: Origin point (x, y, z)
• -d, --direction: Direction vector (dx, dy, dz)
• -r, --radius: Cylinder radius (default: 10m)
• -o, --output: Output file path (default: punkte.xyz)
• -R, --recursive: Use recursive octree traversal
• --no-sorted: Do not sort points by distance along the ray

Features

• Ray tracing with cylindrical radius filtering
• Support for multiple COPC files (tiles)
• Caching mechanism for performance optimization
• Optional recursive octree traversal
• Point clustering and geometric analysis (PCA, shape descriptors)
• Vectorized intersection tests for efficient node checking

Utilities

copc_stats.py

A script that generates statistics about the nodes of a COPC file or multiple files.

Usage:

python copc_stats.py -i <input_file_or_directory> [options]

Options:

• -i, --input: Path to one or more COPC files or a directory
• -o, --output: Path to the output CSV file (default: ./statistics_summary.csv)
• -wh, --write_histogram: Directory to save histogram images (optional)
• -sh, --show_histogram: Display histogram on screen (optional)