_pointcloud module

class pyrockfall._pointcloud.PointCloud(points: ndarray | None = None, *, colors: ndarray | None = None, normals: ndarray | None = None, attrs: Mapping[str, ndarray] | None = None)[source]

Bases: Model

Geometry represented as a point set (no inherent connectivity).

  • points are stored as a NumPy array of shape (N, 3).

  • Per-point attributes live in self.attrs (e.g. ‘colors’, ‘normals’, ‘material_id’). Each must have first dimension N.

Notes

  • This class avoids keeping an internal Open3D object; we construct one transiently only for IO when needed.

property points: NDArray[float64]

(N, D) array view of point coordinates.

clip(min_val: ndarray, max_val: ndarray) → None[source]

Keep only points within an AABB; attributes remain consistent.

has_colors() → bool[source]
has_normals() → bool[source]
segment(ds: float, du: float = 0.0) → List[PointCloud][source]

Split along the strike into contiguous windows of length ds.

The windows are taken on the s coordinate of the curvilinear frame (see Model.sde()), so they follow the wall around bends.

Parameters:
  • ds (float) – Window length along the strike.

  • du (float, default 0) – Overlap between consecutive windows (0 <= du < ds).

Returns:

One point cloud per non-empty window, ordered by increasing s. They share the frame of this point cloud.

Return type:

list[PointCloud]

split(dx: float = 0.5, minPerc: float = 0.05) → List[PointCloud][source]

Split into two parts at the sharpest bend of the wall.

The cut is made at the vertex of the frame’s polyline with the largest turning angle that leaves at least minPerc of the points on each side. A wall without a bend is cut at its median s.

Parameters:
  • dx (float) – Unused; kept for backward compatibility.

  • minPerc (float, default 0.05) – Minimum fraction of points on each side of the cut.

Returns:

[before, after] along increasing s.

Return type:

list[PointCloud]

resolution() → float[source]

Estimate mean nearest-neighbour spacing using 2-NN distances.

Return type:

float

slice(direction: NDArray[float64] | None = None, increment: float | None = None, label: str | None = None, *, frame: CurvilinearFrame | None = None, slice_height_increment: float = -1.0, slice_resolution_factor: float = 5.0, min_points: int = 1, transverse_radius: float | None = None, outlier_fraction: float = 0.0, outlier_radius: float | None = None, method: str = 'interp', refine: bool = True, **kwargs) → Tuple[List[Geometry], NDArray][source]

Slice the point cloud into 2D profiles.

By default the slices follow the strike of the wall: they are surfaces of constant s of the curvilinear frame, increment apart, and each profile is given in (d, e) (distance along the dip direction, elevation). No prior alignment or segmentation of the model is needed, and slabs tile the wall around bends without gaps or overlaps.

Processing outline

  1. Map the points to slicing coordinates (Model._slicing_coords()).

  2. Bin all points to slabs of +-increment/2 around the slice centres.

  3. Build an ordered profile, crest to toe, through each slab (see method).

  4. Predict materials at segment midpoints via KNN classification.

param direction:

None (default) slices along the strike. A vector cuts parallel slices normal to that fixed direction instead; the profile coordinates are then the two remaining axes of the points rotated so that direction is +X.

type direction:

np.ndarray, optional

param increment:

Spacing between consecutive slices.

type increment:

float

param label:

Name of the point attribute holding material IDs.

type label:

str

param frame:

Frame to slice in. Defaults to the frame of the point cloud.

type frame:

CurvilinearFrame, optional

param method:

How the profile is built from the points of a slab.

  • "interp" (default): the slab is a height field over the direction up the face, binned every slice_height_increment, with one node at the median of each bin (profile_from_slab()). Not iterative, and insensitive to stray points. Along the strike the direction up the face is the V axis of the frame; with a fixed direction it is the main direction of each slab.

  • "walk": step through the points from crest to toe (pcWalk()). Can follow a surface that folds back over the face plane, but may stop early.

type method:

{“interp”, “walk”}

param refine:

With "interp": second pass that evens out the node spacing along the profile.

type refine:

bool

param slice_height_increment:

Node spacing of the profile. If not positive, resolution() * slice_resolution_factor is used.

type slice_height_increment:

float

param slice_resolution_factor:

See slice_height_increment.

type slice_resolution_factor:

float

param min_points:

Slabs with fewer points are skipped.

type min_points:

int

param transverse_radius:

Keep only the points of each slab within this distance (along the profile’s horizontal axis) of the slab’s median.

type transverse_radius:

float, optional

param outlier_fraction:

Stray-point filter, applied to each slab in the profile plane. A point is dropped if it has fewer neighbours within outlier_radius than this fraction of the slab’s median. Stray points off the surface (a sparse second layer, isolated points above the crest) otherwise pull the walk away from it. 0 (default) disables the filter; 0.3 is a reasonable value to try. It changes which walks fail rather than removing failures altogether, so check the result.

type outlier_fraction:

float

param outlier_radius:

Radius used to count neighbours. Defaults to 1.25 * resolution().

type outlier_radius:

float, optional

returns:
  • profiles (list[Geometry]) – One profile per valid slice, ordered from crest to toe, with material IDs per segment as attributes.

  • positions (ndarray) – Position of each slice (s, or the distance along direction). With the strike-based slicing, world coordinates of a profile are frame.sde_to_xyz(np.column_stack([np.full(n, s_k), d, e])).

section(increment: float, label: str, *, transverse_radius: float | None = None, initial_direction: tuple[float, float] = (1.0, 0.0), min_points: int = 20, max_nodes: int | None = None, max_iter: int = 20, tol: float = 0.001, max_turn_angle: float | None = np.float64(0.7853981633974483), weight_power: float = 1.0, min_new_fraction: float = 0.1, slice_height_increment: float = 0.5, frame: CurvilinearFrame | None = None, method: str = 'interp')[source]

Extract 2D profiles along the strike of the model.

This is slice() along the strike (direction=None) with the profiles also returned as a 3D point cloud in world coordinates (see Model.section()). The point cloud itself is not modified.

Parameters:
  • increment (float) – Spacing, in the point cloud’s units, between consecutive sections along the strike.

  • label (str) – Name of the point attribute holding material/class IDs.

  • transverse_radius (float, optional) – Half-width, along the dip direction, of the strip of points used for each section (centred on the section’s median). None uses all points of the slab.

  • min_points (int, optional) – Minimum number of points required for a section to be considered valid; sections with fewer points are discarded.

  • slice_height_increment (float, optional) – Node spacing of the profiles (see slice()).

  • method ({"interp", "walk"}, optional) – How each profile is built from its points (see slice()).

  • frame (CurvilinearFrame, optional) – Frame to slice in. Defaults to the frame of the point cloud.

  • initial_direction – Ignored. They controlled the polyline tracing that the curvilinear frame replaces and are kept for backward compatibility.

  • max_nodes – Ignored. They controlled the polyline tracing that the curvilinear frame replaces and are kept for backward compatibility.

  • max_iter – Ignored. They controlled the polyline tracing that the curvilinear frame replaces and are kept for backward compatibility.

  • tol – Ignored. They controlled the polyline tracing that the curvilinear frame replaces and are kept for backward compatibility.

  • max_turn_angle – Ignored. They controlled the polyline tracing that the curvilinear frame replaces and are kept for backward compatibility.

  • weight_power – Ignored. They controlled the polyline tracing that the curvilinear frame replaces and are kept for backward compatibility.

  • min_new_fraction – Ignored. They controlled the polyline tracing that the curvilinear frame replaces and are kept for backward compatibility.

Returns:

  • profiles (list[Geometry]) – One 2D Geometry per section, with node coordinates given as (distance along section, height above section base) and material IDs as attributes.

  • sections_pc (PointCloud) – All section points combined into a single point cloud, in the original global coordinate system, with the material attribute (label) and a “Profile” attribute identifying which section each point belongs to.

Raises:

ValueError – If no valid sections are found.

fillHoles(attributes: Sequence[str] | str = (), *, kinds: Dict[str, str] | None = None, spacing: float | None = None, cell: float | None = None, min_cells: int = 4, use_removed: bool = True, ring_scale: float = 0.5, attr_ring_scale: float = 1.0, max_train: int = 2000, n_closest: int | None = None, variogram: str = 'spherical', attr_variogram: str | None = None, trend_order: int = 1, nlags: int = 20, aniso: float = 10.0, bedding_angle: float = 0.0, geometry_aniso: float = 3.0, shared_variogram: bool = True, others: str = 'nearest', seed: int = 0, return_info: bool = False)[source]

Create points in the missing parts of the point cloud and krige their coordinates and the selected attributes.

The work is done in the (u, v, w) coordinates of the curvilinear frame (see Model.uvw()), where the wall is unrolled onto its best-fit plane: w is a small residual even for a wall with corners, u runs along the strike and v up-dip, so layering is anisotropic along u.

Processing outline

  1. Find the missing parts on an occupancy grid in (u, v): empty cells enclosed by points, plus empty cells that held points taken out with removePoints(). Each connected region is one hole.

  2. Create new points in every hole on a regular (u, v) grid.

  3. Height: remove a polynomial trend from w of the points in a ring around the hole, fit a variogram to the residual, krige it at the new points and add the trend back. Map (u, v, w) back to (x, y, z).

  4. Attributes: integer-valued ones by indicator kriging (a probability per class, corrected to lie in [0, 1] and sum to 1), the others by ordinary kriging.

param attributes:

Per-point attributes to krige at the new points.

type attributes:

sequence of str

param kinds:

name -> "categorical" | "continuous" to override the automatic choice (integer-valued attributes are categorical).

type kinds:

dict, optional

param spacing:

Spacing of the new points. Defaults, for each hole, to the spacing that matches the density of the points around it.

type spacing:

float, optional

param cell:

Cell size of the occupancy grid. Defaults to 5 * resolution().

type cell:

float, optional

param min_cells:

Smallest hole, in cells; smaller gaps are sampling noise.

type min_cells:

int

param use_removed:

Also fill the cells emptied by removePoints().

type use_removed:

bool

param ring_scale:

Width of the ring of points used for the height and for the attributes, as a fraction of the hole’s equivalent diameter.

type ring_scale:

float

param attr_ring_scale:

Width of the ring of points used for the height and for the attributes, as a fraction of the hole’s equivalent diameter.

type attr_ring_scale:

float

param max_train:

Largest number of ring points used per kriging system; the ring is thinned evenly to this number.

type max_train:

int

param n_closest:

None (default) solves one system per hole with all ring points. A number uses only that many nearest ring points per new point.

type n_closest:

int, optional

param variogram:

Variogram model for the height and for the attributes: “spherical”, “exponential”, “gaussian” or “linear”.

type variogram:

str

param attr_variogram:

Variogram model for the height and for the attributes: “spherical”, “exponential”, “gaussian” or “linear”.

type attr_variogram:

str

param trend_order:

Polynomial trend removed from w before kriging.

type trend_order:

{0, 1, 2}

param nlags:

Lag bins of the experimental variograms.

type nlags:

int

param aniso:

Attribute ranges along the layers divided by the range across them (1 = isotropic).

type aniso:

float

param bedding_angle:

Angle (degrees, counter-clockwise) of the layers from horizontal, within the plane of the face.

type bedding_angle:

float

param geometry_aniso:

Same ratio as aniso for the height w: values above 1 assume the shape of the face persists further along the strike (e.g. benches) than up-dip.

type geometry_aniso:

float

param shared_variogram:

Use one variogram for all classes of a categorical attribute.

type shared_variogram:

bool

param others:

Value given to the attributes that are not kriged: that of the nearest existing point, or NaN.

type others:

{“nearest”, “nan”}

param seed:

Random seed for thinning the rings.

type seed:

int

param return_info:

Also return a dict with the holes found and the fitted variograms.

type return_info:

bool

returns:
  • PointCloud – A new point cloud with the existing points followed by the new ones. Extra attributes: "filled" (1 for new points), "hole_id", "kriging_std" (standard deviation of the kriged height); per categorical attribute "<name>_P<class>" and "<name>_Pmax"; per continuous attribute "<name>_std".

  • dict – Only with return_info.