_frame module

_frame.py

Curvilinear wall coordinates.

CurvilinearFrame unrolls a wall along a plan-view polyline and gives two extra sets of coordinates besides (x, y, z):

(s, d, e)

s distance along the strike (arclength along the polyline), d distance along the dip direction (signed horizontal distance from the polyline) and e elevation (equal to z).

(u, v, w)

Principal components of (s, d, e). u and v span the best-fit plane of the unrolled face, w is the height above that plane.

fit_polyline() fits the polyline (fewest straight segments within a tolerance) through an unordered plan-view strip of points.

class pyrockfall._frame.CurvilinearFrame(polyline, pca_mean=None, pca_axes=None, pca_var=None)[source]

Bases: object

Unrolls a wall along a plan-view polyline, plus a PCA of the unrolled points.

Curvilinear coordinates (s, d, e):

  • s strike: arclength along the polyline, extrapolated beyond its ends.

  • d dip direction: signed horizontal distance from the polyline, > 0 to the left when walking along increasing s. fit() orients the polyline so that d increases down-dip.

  • e elevation, equal to z.

Corners are mitred: at each interior vertex the offset direction is the bisector, scaled so that d is the perpendicular distance to both adjacent segment lines. Inside segment i a point is p = V_i + t e_i + d ((1 - t) m_i + t m_{i+1}) with t in [0, 1], which is continuous across vertices and invertible while d stays within fold_limits() (offset lines on the inner side of a bend collapse beyond that).

Principal coordinates (u, v, w): one global PCA of (s, d, e). u and v span the best-fit plane of the unrolled face (u along +s, v upward) and w = u x v is the height above that plane.

Parameters:
  • polyline ((K+1, 2) array-like) – Plan-view vertices of the wall line.

  • pca_mean (array-like, optional) – A previously fitted PCA (see fit_pca()).

  • pca_axes (array-like, optional) – A previously fitted PCA (see fit_pca()).

  • pca_var (array-like, optional) – A previously fitted PCA (see fit_pca()).

classmethod fit(xyz, steep=None, *, tol: float = 1.0, res: float = 0.5, corner_length: str | float | None = 'auto', min_turn: float = 5.0, band_fraction: float = 0.05, min_pts: int = 3, n_iter: int = 2) → CurvilinearFrame[source]

Fit a frame to a wall.

The polyline is fitted to the centreline of the steep points (the face, without floor and berms). Without a steep mask a thin elevation band around the median elevation is used instead.

Parameters:
  • xyz ((N, 3) array-like) – Point coordinates.

  • steep ((N,) bool array, optional) – Points that belong to the face.

  • tol – Passed to fit_polyline().

  • res – Passed to fit_polyline().

  • min_pts – Passed to fit_polyline().

  • n_iter – Passed to fit_polyline().

  • corner_length ({"auto", float, None}) – Length either side of each bend over which the offset direction turns (see refine_corners()). None keeps the fitted polyline as is, so the turn is spread along each whole segment.

  • min_turn (float) – Bends below this angle (degrees) are not refined.

  • band_fraction (float) – Fraction of the points in the elevation band used without steep.

classmethod straight(origin_xy=(0.0, 0.0), direction_xy=(1.0, 0.0)) → CurvilinearFrame[source]

One-segment frame: s along direction_xy from origin_xy, d to its left.

refine_corners(length: str | float = 'auto', *, d_max: float | None = None, min_turn: float = 5.0, margin: float = 1.5) → CurvilinearFrame[source]

Confine the turn of the offset direction to a zone around each bend.

Extra vertices are inserted length either side of every bend. The wall line is unchanged, but lines of constant s are then perpendicular to the wall everywhere except within length of a bend, instead of fanning out along each whole segment.

Parameters:
  • length ({"auto", float}) – Distance from each bend. "auto" uses margin * d_max * tan(turn / 2), the shortest length that keeps points up to d_max from the polyline inside the fold limit, with a safety margin.

  • d_max (float) – Largest |d| of the points (needed for "auto").

  • min_turn (float) – Bends below this angle (degrees) are left alone.

Returns:

A new frame (without PCA; call fit_pca()).

Return type:

CurvilinearFrame

property n_segments: int
property length: float

Total length of the polyline.

turning_angles() → ndarray[source]

Turning angle (radians, >= 0) at each interior vertex.

xyz_to_sde(xyz, return_info: bool = False)[source]

(N, 3) xyz -> (N, 3) sde. Points outside the invertible region get NaN.

With return_info, also returns the number of NaN points and the number of ambiguous points (valid for more than one segment).

sde_to_xyz(sde)[source]

(N, 3) sde -> (N, 3) xyz.

fold_limits() → ndarray[source]

(K, 2) largest |d| per segment on the left (d > 0) and right (d < 0) side before the offset lines fold over (inf where they never do).

diagnostics(xyz) → dict[source]

Quality of the frame for a set of points.

Returns a dict with the number of points outside the invertible region (n_nan), valid for more than one segment (n_ambiguous) and past a fold limit (n_past_fold), plus the tightest fold limit (fold_limit_min).

fit_pca(sde) → CurvilinearFrame[source]

Global PCA of the unrolled points. Rows of pca_axes are U, V, W.

sde_to_uvw(sde)[source]
uvw_to_sde(uvw)[source]
xyz_to_uvw(xyz)[source]
uvw_to_xyz(uvw)[source]
horizontal_angle_uv() → float[source]

Angle (degrees, CCW from U) of horizontal lines within the U-V plane.

Lines of constant elevation on the best-fit plane run along this direction; it is the natural reference for horizontal layering.

save(path) → None[source]

Write the polyline and PCA to a JSON file.

classmethod load(path) → CurvilinearFrame[source]

Read a frame written by save().

pyrockfall._frame.fit_polyline(x, y, tol, res, min_pts=3, max_bins=None, centreline=True, n_iter=2)[source]

Binned fewest-segment polyline through an unordered 2D profile/strip.

Parameters:
  • x (array-like) – Plan-view coordinates of the points.

  • y (array-like) – Plan-view coordinates of the points.

  • tol (float) – Largest orthogonal RMSE allowed per segment.

  • res (float) – Bin width along the profile (breakpoints are snapped to bin edges).

  • min_pts (int) – Minimum number of points per segment.

  • max_bins (int, optional) – Longest segment, in bins.

  • centreline (bool) – Measure the error of the bin centroids (count-weighted) instead of the individual points, so tol is how far the strip’s centreline may stray from each segment, regardless of how wide the strip is.

  • n_iter (int) – Refits that re-bin along the previous polyline instead of along one straight axis, so bins cut the strip square-on at bends and ends.

Returns:

  • vertices ((k+1, 2) ndarray) – Polyline vertices in the input coordinates, ordered by increasing x.

  • bounds (list[int]) – Bin index of each breakpoint.