_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:
ModelGeometry 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.
- 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
scoordinate of the curvilinear frame (seeModel.sde()), so they follow the wall around bends.- Parameters:
- Returns:
One point cloud per non-empty window, ordered by increasing
s. They share the frame of this point cloud.- Return type:
- 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:
- Returns:
[before, after]along increasings.- Return type:
- resolution() float[source]¶
Estimate mean nearest-neighbour spacing using 2-NN distances.
- Return type:
- 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
sof 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¶
Map the points to slicing coordinates (
Model._slicing_coords()).Bin all points to slabs of
+-increment/2around the slice centres.Build an ordered profile, crest to toe, through each slab (see method).
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_factoris 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.3is 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 areframe.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 (seeModel.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).
Noneuses 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
Geometryper 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 (seeModel.uvw()), where the wall is unrolled onto its best-fit plane:wis a small residual even for a wall with corners,uruns along the strike andvup-dip, so layering is anisotropic alongu.Processing outline¶
Find the missing parts on an occupancy grid in
(u, v): empty cells enclosed by points, plus empty cells that held points taken out withremovePoints(). Each connected region is one hole.Create new points in every hole on a regular
(u, v)grid.Height: remove a polynomial trend from
wof 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).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
wbefore 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.