sec_interp.core.utils package

Subpackages

Submodules

Module contents

Core Utilities Package.

Organized by functionality: - geometry: Spatial geometry operations - spatial: Distance and azimuth calculations - sampling: Elevation sampling and profiling - parsing: Structural data parsing - rendering: Visualization utilities - io: File I/O and user messages - geology: Geological calculations

sec_interp.core.utils.calculate_apparent_dip(true_strike: float, true_dip: float, line_azimuth: float) → float

Convert true dip to apparent dip in section plane.

The apparent dip is the inclination of a plane measured in a direction not perpendicular to the strike. In a vertical cross-section, the apparent dip depends on the angle between the strike of the plane and the azimuth of the cross-section line.

Formula:

tan(apparent_dip) = tan(true_dip) * sin(alpha)

Where alpha is the angle between the strike of the plane and the direction of the cross-section (section azimuth). alpha = strike - section_azimuth

Parameters:

  • true_strike – Strike of the geological plane (0-360 degrees).

  • true_dip – True dip of the geological plane (0-90 degrees).

  • line_azimuth – Azimuth of the cross-section line (0-360 degrees).

Returns:

Apparent dip in degrees. Positive values indicate dip, negative values might occur depending on quadrant but are typically normalized.

sec_interp.core.utils.calculate_bounds(topo_data: list[tuple[float, float]], geol_data: list[GeologySegment] | None = None) → dict[str, float]

Calculate the bounding box for all profile data with padding.

Calculates the minimum and maximum distance and elevation across topography and optional geological segments.

Parameters:

  • topo_data – List of (distance, elevation) tuples for topography.

  • geol_data – Optional list of geological segments.

Returns:

Bounds containing ‘min_d’, ‘max_d’, ‘min_e’, ‘max_e’ with 5% padding.

sec_interp.core.utils.calculate_drillhole_trajectory(collar_point: qgis.core.QgsPointXY, collar_z: float, survey_data: list[tuple[float, float, float]], section_azimuth: float, densify_step: float = 1.0, total_depth: float = 0.0) → list[tuple[float, float, float, float, float, float]]

Calculate 3D trajectory of a drillhole using survey data.

Uses the tangential method for trajectory calculation with densification to generate intermediate points for continuous interval projection.

Parameters:

  • collar_point – QgsPointXY of collar location (X, Y).

  • collar_z – Elevation of collar (Z).

  • survey_data – List of tuples (depth, azimuth, inclination) sorted by depth.

  • section_azimuth – Azimuth of the section line in degrees.

  • densify_step – Distance in meters between interpolated points (default 1.0m).

  • total_depth – Optional total depth. If greater than last survey depth, trajectory will be extrapolated using last orientation.

Returns:

  • depth: Depth along the hole.

  • x, y, z: 3D coordinates.

  • dist_along_section: Distance along the section line (initially 0.0).

  • offset_from_section: Perpendicular distance from section line (initially 0.0).

Return type:

A list of tuples (depth, x, y, z, dist_along_section, offset_from_section)

sec_interp.core.utils.calculate_interval(data_range: float) → float

Calculate a ‘nice’ interval for axis labels based on the data range.

Parameters:

data_range – The total range of data values (e.g., max_d - min_d).

Returns:

A human-readable interval (e.g., 1, 2, 5, 10, etc.) for grid lines.

sec_interp.core.utils.calculate_line_azimuth(line_geom: qgis.core.QgsGeometry) → float

Calculate the azimuth (compass bearing) of a line geometry.

Calculates the azimuth based on the first two vertices of the line. Returns 0 for points or single-vertex lines.

Parameters:

line_geom – The QGIS line geometry.

Returns:

Azimuth in degrees (0-360).

sec_interp.core.utils.calculate_step_size(geom: qgis.core.QgsGeometry, raster_lyr) → float

Calculate step size based on slope and raster resolution.

Deprecated since version Use: densify_line_by_interval() instead for better precision and simpler code. This function is kept for backward compatibility but may be removed in future versions.

Ensures that sampling occurs at approximately one pixel intervals, accounting for the slope of the line relative to the raster grid.

Parameters:

  • geom – The geometry to sample along.

  • raster_lyr – The raster layer being sampled.

Returns:

Calculated step size in map units.

sec_interp.core.utils.cardinal_to_azimuth(text: str) → float | None

Convert a cardinal direction string to its equivalent azimuth.

Supports: N, NE, E, SE, S, SW, W, NW.

Parameters:

text – The cardinal direction string.

Returns:

The azimuth in degrees (0-360), or None if invalid.

sec_interp.core.utils.create_buffer_geometry(geometry: qgis.core.QgsGeometry, crs: qgis.core.QgsCoordinateReferenceSystem, distance: float, segments: int = 5) → qgis.core.QgsGeometry

Create a buffer around a geometry.

Parameters:

  • geometry – Input geometry.

  • crs – Coordinate Reference System of the geometry.

  • distance – Buffer distance in layer units.

  • segments – Number of segments for the buffer approximation.

Returns:

The buffered geometry.

sec_interp.core.utils.create_coordinate_transform(bounds: dict[str, float], view_w: int, view_h: int, margin: int, vert_exag: float = 1.0) → Callable[[float, float], tuple[float, float]]

Create a coordinate transformation function for screen projection.

Returns a function that transforms data coordinates (distance, elevation) to pixel coordinates (x, y) based on the provided view dimensions.

Parameters:

  • bounds – Dictionary with ‘min_d’, ‘max_d’, ‘min_e’, ‘max_e’.

  • view_w – Screen/view width in pixels.

  • view_h – Screen/view height in pixels.

  • margin – Plot margin in pixels.

  • vert_exag – Vertical exaggeration multiplier (default 1.0).

Returns:

A function transform(dist, elev) -> (x, y) converting data to pixels.

sec_interp.core.utils.create_distance_area(crs: qgis.core.QgsCoordinateReferenceSystem) → qgis.core.QgsDistanceArea

Create and configure a QgsDistanceArea object.

Configures the distance area with the provided CRS, project transform context, and associated ellipsoid for geodesic calculations.

Parameters:

crs – The Coordinate Reference System to use.

Returns:

The configured distance calculation object.

sec_interp.core.utils.create_memory_layer(layer_name: str, layer_type: str, crs: qgis.core.QgsCoordinateReferenceSystem, fields: list[qgis.core.QgsField]) → qgis.core.QgsVectorLayer

Create a temporary memory (scratch) layer.

Parameters:

  • layer_name – Name for the layer.

  • layer_type – QGIS geometry type string (e.g., ‘Point’, ‘LineString’).

  • crs – Coordinate reference system.

  • fields – List of fields for the layer.

Returns:

The created memory layer.

sec_interp.core.utils.create_shapefile_writer(output_path: str | Path, crs: qgis.core.QgsCoordinateReferenceSystem, fields: qgis.core.QgsFields, geometry_type: qgis.core.QgsWkbTypes.GeometryType = qgis.core.QgsWkbTypes.LineString) → qgis.core.QgsVectorFileWriter

Create and initialize a QgsVectorFileWriter for Shapefiles.

Uses the modern create static method for QGIS 3.38+ compatibility.

Parameters:

  • output_path – File system path where the shapefile will be created.

  • crs – The Coordinate Reference System for the new file.

  • fields – The attribute fields definition.

  • geometry_type – The mapping geometry type (default: LineString).

Returns:

An initialized writer object for creating a Shapefile.

Raises:

OSError – If the writer cannot be created or has an initialization error.

sec_interp.core.utils.densify_line_by_interval(geometry: qgis.core.QgsGeometry, interval: float) → qgis.core.QgsGeometry

Densify a line geometry by a specific distance interval.

Parameters:

  • geometry – Line geometry to densify.

  • interval – Maximum distance between vertices.

Returns:

The densified geometry.

sec_interp.core.utils.filter_features_by_buffer(features_layer: QgsVectorLayer, buffer_geometry: QgsGeometry, buffer_crs: QgsCoordinateReferenceSystem | None = None) → list[QgsFeature]

Filter features that intersect with buffer using spatial index.

Parameters:

  • features_layer – Layer containing features to filter.

  • buffer_geometry – Buffer geometry to use for spatial filter.

  • buffer_crs – CRS of the buffer geometry (optional).

Returns:

List of QgsFeature objects that intersect the query buffer.

sec_interp.core.utils.get_line_start_point(geometry: qgis.core.QgsGeometry) → qgis.core.QgsPointXY

Get the start point of a line geometry.

Handles both singlepart and multipart line geometries.

Parameters:

geometry – The line geometry.

Returns:

The first vertex of the first part of the geometry.

sec_interp.core.utils.get_line_vertices(geometry: qgis.core.QgsGeometry) → list[qgis.core.QgsPointXY]

Extract vertices specifically from a line or multiline geometry.

Parameters:

geometry – A QGIS geometry of type LineGeometry.

Returns:

A flat list of vertices.

Raises:

ValueError – If the geometry is null, not a line, or contains no vertices.

sec_interp.core.utils.interpolate_elevation(topo_data: list, distance: float) → float

Interpolate elevation at given distance.

Parameters:

  • topo_data – List of (distance, elevation) tuples.

  • distance – Distance at which to interpolate elevation.

Returns:

The interpolated elevation value.

sec_interp.core.utils.interpolate_intervals_on_trajectory(trajectory: list[tuple], intervals: list[tuple[float, float, Any]], buffer_width: float) → list[tuple[Any, list[tuple[float, float]]]]

Interpolate interval attributes along drillhole trajectory.

Filters and maps geological intervals onto the 3D trajectory points that fall within the specified section buffer.

Parameters:

  • trajectory – List of (depth, x, y, z, dist_along, offset) tuples.

  • intervals – List of (from_depth, to_depth, attribute) tuples.

  • buffer_width – Maximum perpendicular offset to include a point.

Returns:

  • attribute: The metadata/geology associated with the interval.

  • points: List of (distance, elevation) coordinates for rendering.

Return type:

List of tuples containing

sec_interp.core.utils.parse_dip(value: Any) → tuple[float | None, float | None]

Parse a dip value from various formats.

Supports numeric dip (“45”) and field notation with direction (“45 NE”, “22 SW”).

Parameters:

value – The raw dip value.

Returns:

A tuple of (dip_angle, dip_direction_azimuth). Values are None if parsing fails.

sec_interp.core.utils.parse_strike(value: Any) → float | None

Parse a strike value from various formats into an azimuth (0-360).

Supports numeric values, strings, and quadrant notation (e.g., “N 30 E”, “S 45 W”).

Parameters:

value – The raw strike value (string, int, float, or None).

Returns:

Strike in azimuth degrees (0-360) or None if parsing fails.

sec_interp.core.utils.prepare_profile_context(line_lyr: qgis.core.QgsVectorLayer) → tuple[qgis.core.QgsGeometry, qgis.core.QgsPointXY, qgis.core.QgsDistanceArea]

Prepare a common context for profile calculation operations.

Parameters:

line_lyr – The cross-section line vector layer.

Returns:

  • line_geom: The geometry of the section line.

  • line_start: The starting point of the line.

  • distance_area: Fully configured geodesic distance object.

Return type:

A tuple containing

Raises:

ValueError – If the input layer is empty or has invalid geometry.

sec_interp.core.utils.project_trajectory_to_section(trajectory: list[tuple], line_geom: qgis.core.QgsGeometry, line_start: qgis.core.QgsPointXY, distance_area: qgis.core.QgsDistanceArea) → list[tuple[float, float, float, float, float, float]]

Project drillhole trajectory points onto section line.

Parameters:

  • trajectory – List of (depth, x, y, z, _, _) from calculate_drillhole_trajectory.

  • line_geom – QgsGeometry of the section line.

  • line_start – QgsPointXY of the section line start.

  • distance_area – QgsDistanceArea for geodesic measurements.

Returns:

  • depth: Original depth.

  • x, y, z: Original 3D coordinates.

  • dist_along: Projected distance along the section line.

  • offset: Perpendicular offset from the section line.

Return type:

List of tuples (depth, x, y, z, dist_along, offset)

sec_interp.core.utils.sample_elevation_along_line(geometry: QgsGeometry, raster_layer: QgsRasterLayer, band_number: int, distance_area: QgsDistanceArea, reference_point: QgsPointXY | None = None, interval: float | None = None) → list[QgsPointXY]

Sample elevation values along a line geometry from a raster layer.

Densifies the line at raster resolution and samples the elevation at each vertex.

Parameters:

  • geometry – The line geometry to sample along.

  • raster_layer – The source DEM raster layer.

  • band_number – The raster band index to sample.

  • distance_area – Object for geodesic distance calculations.

  • reference_point – Optional start point for distance measurements.

  • interval – Optional sampling interval. If None, uses raster resolution.

Returns:

A list of QgsPointXY objects where x is horizontal distance and y is elevation.