rsqsim_api.fault.utilities

Geometric utility functions for fault-trace analysis and manipulation.

Provides bearing arithmetic, line operations (strike, dip direction, reversal, smoothing), and helpers for merging nearly-adjacent LineString segments into single traces.

Functions

smallest_difference(value1, value2)

Return the smallest angular difference between two bearings.

normalize_bearing(bearing)

Normalise a bearing to the range [0, 360).

bearing_leq(value, benchmark[, tolerance])

Check whether a bearing is anticlockwise of (less than) another bearing.

bearing_geq(value, benchmark[, tolerance])

Check whether a bearing is clockwise of (greater than) another bearing.

reverse_bearing(bearing)

Return the bearing 180° opposite to the supplied bearing.

reverse_line(line)

Reverse the vertex order of a LineString.

fit_2d_line(x, y)

Fit a straight line to a 2-D point cloud and return the dip angle.

calculate_dip_direction(line)

Calculate the dip direction of a fault-trace LineString in NZTM.

calculate_strike(line[, lt180])

Calculate the strike of a fault-trace LineString in NZTM.

optimize_point_spacing(line, spacing)

Re-sample a LineString to approximately uniform point spacing.

chaikins_corner_cutting(coords[, refinements])

Smooth a polyline using Chaikin's corner-cutting algorithm.

smooth_trace(trace[, n_refinements])

Smooth a fault-trace LineString using Chaikin's corner-cutting algorithm.

straighten(line, strike, damping)

Straighten a 3-D line by damping its across-strike deviations.

align_two_nearly_adjacent_segments(segment_list[, ...])

Snap the closest endpoints of two nearly-adjacent LineStrings to their midpoint.

merge_two_nearly_adjacent_segments(segment_list[, ...])

Merge two nearly-adjacent LineStrings into one by snapping their endpoints.

merge_multiple_nearly_adjacent_segments(segment_list)

Iteratively merge a list of nearly-adjacent LineStrings into one.

Module Contents

rsqsim_api.fault.utilities.smallest_difference(value1, value2)[source]

Return the smallest angular difference between two bearings.

Accounts for the circular nature of bearings so that, for example, the difference between 350° and 10° is 20° rather than 340°.

Parameters:

  • value1 (float or int) – First bearing in degrees.

  • value2 (float or int) – Second bearing in degrees.

Returns:

Smallest non-negative angular difference in degrees (0–180).

Return type:

float

rsqsim_api.fault.utilities.normalize_bearing(bearing)[source]

Normalise a bearing to the range [0, 360).

Parameters:

bearing (float or int) – Input bearing in degrees (any value).

Returns:

Equivalent bearing in the range [0, 360).

Return type:

float

rsqsim_api.fault.utilities.bearing_leq(value, benchmark, tolerance=0.1)[source]

Check whether a bearing is anticlockwise of (less than) another bearing.

Parameters:

  • value (int or float) – The bearing to test, in degrees.

  • benchmark (int or float) – The reference bearing, in degrees.

  • tolerance (int or float, optional) – Angular tolerance in degrees to account for rounding. Defaults to 0.1.

Returns:

True if value is strictly anticlockwise of benchmark (i.e. less than, within tolerance).

Return type:

bool

rsqsim_api.fault.utilities.bearing_geq(value, benchmark, tolerance=0.1)[source]

Check whether a bearing is clockwise of (greater than) another bearing.

Parameters:

  • value (int or float) – The bearing to test, in degrees.

  • benchmark (int or float) – The reference bearing, in degrees.

  • tolerance (int or float, optional) – Angular tolerance in degrees to account for rounding. Defaults to 0.1.

Returns:

True if value is strictly clockwise of benchmark (i.e. greater than, within tolerance).

Return type:

bool

rsqsim_api.fault.utilities.reverse_bearing(bearing)[source]

Return the bearing 180° opposite to the supplied bearing.

Parameters:

bearing (int or float) – Input bearing in degrees; must be in [0, 360].

Returns:

Reversed bearing in the range [0, 360).

Return type:

float

Raises:

AssertionError – If bearing is not a float or int, or is outside [0, 360].

rsqsim_api.fault.utilities.reverse_line(line)[source]

Reverse the vertex order of a LineString.

Works with both 2-D and 3-D (has_z) lines.

Parameters:

line (shapely.geometry.LineString) – Input line to reverse.

Returns:

New line with vertices in the opposite order.

Return type:

shapely.geometry.LineString

Raises:

AssertionError – If line is not a LineString.

rsqsim_api.fault.utilities.fit_2d_line(x, y)[source]

Fit a straight line to a 2-D point cloud and return the dip angle.

Fits both y = f(x) and x = g(y) and selects whichever has the smaller residual, then converts the gradient to a dip angle.

Parameters:

  • x (numpy.ndarray) – x-coordinates of the points.

  • y (numpy.ndarray) – y-coordinates of the points.

Returns:

Dip angle in degrees measured from the horizontal.

Return type:

float

Raises:

AssertionError – If either x or y is not a numpy.ndarray.

rsqsim_api.fault.utilities.calculate_dip_direction(line)[source]

Calculate the dip direction of a fault-trace LineString in NZTM.

Computes the strike of the line (best-fit gradient) and adds 90° to obtain the dip direction. The sign is chosen so that the dip direction is consistent with the majority of vertices being to the right of the strike vector.

Parameters:

line (shapely.geometry.LineString or MultiLineString) – Fault-surface trace in NZTM (EPSG:2193) coordinates. A MultiLineString is first merged into a single line.

Returns:

Dip direction in degrees, range [0, 360).

Return type:

float

Raises:

AssertionError – If line is not a LineString or MultiLineString.

rsqsim_api.fault.utilities.calculate_strike(line, lt180=False)[source]

Calculate the strike of a fault-trace LineString in NZTM.

Fits a best-fit gradient to the trace coordinates and converts it to an azimuthal strike. When lt180 is True the result is reduced to the half-circle convention [0, 180).

Parameters:

  • line (shapely.geometry.LineString or MultiLineString) – Fault-surface trace in NZTM (EPSG:2193) coordinates. A MultiLineString is first merged into a single line.

  • lt180 (bool, optional) – If True, return a strike in [0, 180) instead of [0, 360). Defaults to False.

Returns:

Strike in degrees.

Return type:

float

Raises:

AssertionError – If line is not a LineString or MultiLineString.

rsqsim_api.fault.utilities.optimize_point_spacing(line, spacing)[source]

Re-sample a LineString to approximately uniform point spacing.

Interpolates num_points centre-points along the line, where num_points is chosen to match spacing as closely as possible.

Parameters:

  • line (shapely.geometry.LineString or MultiLineString) – Input line. A MultiLineString is first merged into a single line.

  • spacing (float) – Target point spacing in the same units as the line coordinates (metres for NZTM).

Returns:

  • centre_points (list of shapely.geometry.Point) – Resampled centre points along the line.

  • new_width (float) – Actual spacing used (line length / number of points).

Raises:

AssertionError – If line is not a LineString or MultiLineString, or if spacing is not a positive float.

rsqsim_api.fault.utilities.chaikins_corner_cutting(coords, refinements=5)[source]

Smooth a polyline using Chaikin’s corner-cutting algorithm.

Each refinement pass replaces every edge with two new points at the 1/4 and 3/4 positions, progressively rounding corners.

Parameters:

  • coords (array-like of shape (n, 2) or (n, 3)) – Coordinate array of the polyline vertices.

  • refinements (int, optional) – Number of corner-cutting passes to apply. Defaults to 5.

Returns:

Smoothed coordinate array with approximately n * 2 ** refinements vertices.

Return type:

numpy.ndarray

rsqsim_api.fault.utilities.smooth_trace(trace, n_refinements=5)[source]

Smooth a fault-trace LineString using Chaikin’s corner-cutting algorithm.

Parameters:

  • trace (shapely.geometry.LineString) – Input trace to smooth.

  • n_refinements (int, optional) – Number of corner-cutting passes. Defaults to 5.

Returns:

Smoothed line with approximately len(trace.coords) * 2 ** n_refinements vertices.

Return type:

shapely.geometry.LineString

Raises:

AssertionError – If trace is not a LineString.

rsqsim_api.fault.utilities.straighten(line, strike, damping)[source]

Straighten a 3-D line by damping its across-strike deviations.

Projects each vertex onto the along-strike and across-strike directions, then reconstructs new positions with the across-strike component multiplied by damping.

Parameters:

  • line (shapely.geometry.LineString) – Input 3-D line (z coordinate included in coords).

  • strike (float) – Strike azimuth in degrees used to define the along/across direction.

  • damping (float) – Fractional weight applied to the across-strike displacement (0 = fully straight, 1 = unchanged).

Returns:

New line with reduced across-strike curvature.

Return type:

shapely.geometry.LineString

rsqsim_api.fault.utilities.align_two_nearly_adjacent_segments(segment_list, tolerance=200.0)[source]

Snap the closest endpoints of two nearly-adjacent LineStrings to their midpoint.

Identifies which endpoints of the two segments are closest to each other and replaces both with the midpoint, making the segments exactly adjacent.

Parameters:

  • segment_list (list of shapely.geometry.LineString) – Exactly two line segments.

  • tolerance (float, optional) – Maximum allowable distance (m) between the nearest endpoints for the operation to be valid. Defaults to 200.

Returns:

Two new segments with snapped endpoints.

Return type:

tuple of shapely.geometry.LineString

Raises:

AssertionError – If segment_list does not contain exactly 2 segments, or if the distance between them exceeds tolerance.

rsqsim_api.fault.utilities.merge_two_nearly_adjacent_segments(segment_list, tolerance=200.0)[source]

Merge two nearly-adjacent LineStrings into one by snapping their endpoints.

Calls align_two_nearly_adjacent_segments() to snap the closest endpoints to their midpoint, then merges the result into a single LineString with linemerge().

Parameters:

  • segment_list (list of shapely.geometry.LineString) – Exactly two line segments.

  • tolerance (float, optional) – Maximum allowable gap (m) between segments. Defaults to 200.

Returns:

Merged single line.

Return type:

shapely.geometry.LineString

rsqsim_api.fault.utilities.merge_multiple_nearly_adjacent_segments(segment_list, tolerance=200.0)[source]

Iteratively merge a list of nearly-adjacent LineStrings into one.

Repeatedly merges the first two segments using merge_two_nearly_adjacent_segments() until a single line remains.

Parameters:

  • segment_list (list of shapely.geometry.LineString) – Two or more line segments to merge, ordered along the trace.

  • tolerance (float, optional) – Maximum allowable gap (m) between consecutive segments. Defaults to 200.

Returns:

Single merged line.

Return type:

shapely.geometry.LineString

Raises:

AssertionError – If segment_list contains fewer than 2 segments.