_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)sdistance along the strike (arclength along the polyline),ddistance along the dip direction (signed horizontal distance from the polyline) andeelevation (equal toz).(u, v, w)Principal components of
(s, d, e).uandvspan the best-fit plane of the unrolled face,wis 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:
objectUnrolls a wall along a plan-view polyline, plus a PCA of the unrolled points.
Curvilinear coordinates
(s, d, e):sstrike: arclength along the polyline, extrapolated beyond its ends.ddip direction: signed horizontal distance from the polyline,> 0to the left when walking along increasings.fit()orients the polyline so thatdincreases down-dip.eelevation, equal toz.
Corners are mitred: at each interior vertex the offset direction is the bisector, scaled so that
dis the perpendicular distance to both adjacent segment lines. Inside segmentia point isp = V_i + t e_i + d ((1 - t) m_i + t m_{i+1})withtin[0, 1], which is continuous across vertices and invertible whiledstays withinfold_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).uandvspan the best-fit plane of the unrolled face (ualong+s,vupward) andw = u x vis the height above that plane.- Parameters:
- 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
steeppoints (the face, without floor and berms). Without asteepmask 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()).Nonekeeps 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:
salongdirection_xyfromorigin_xy,dto 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
lengtheither side of every bend. The wall line is unchanged, but lines of constantsare then perpendicular to the wall everywhere except withinlengthof a bend, instead of fanning out along each whole segment.- Parameters:
length ({"auto", float}) – Distance from each bend.
"auto"usesmargin * d_max * tan(turn / 2), the shortest length that keeps points up tod_maxfrom the polyline inside the fold limit, with a safetymargin.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:
- 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).
- 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_axesare U, V, W.
- 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.
- 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
tolis 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.