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

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

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)

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)

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
segments = cluster_and_analyze(points, ray, min_points=4)

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 1 0 0 -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