2.30.7.14. pycsamt.map.borehole_align#

Place PCBH boreholes in the 3-D map’s local scene coordinates.

The fence / block / depth-slice / iso-surface builders in pycsamt.map.volume do not work in real easting/northing. They work in a synthetic profile space: x is along-strike distance, y is cross-strike line offset, and z is elevation with depth running downward from a z = 0 (or draped-topography) datum.

A PCBH document, by contrast, carries absolute collar coordinates in its own CRS. Dropping those numbers straight into the scene puts the hole kilometres away from the section. This module bridges the two: it projects each collar into the survey’s SurveyFrame, walks the desurveyed trajectory, and returns per-hole polylines and coloured interval segments already in scene coordinates, plus a note on how the hole sits relative to the imaged volume.

Pure numpy + the PCBH render model — no Plotly / Dash / Qt.

Functions

align_boreholes_to_scene(document, frame, *)

Align every borehole in document to a 3-D map scene.

surface_from_sections(sections)

Build a u -> elevation interpolator from section terrain lines.

Classes

AlignedHole(borehole_id, name, collar_scene, ...)

One borehole placed in the 3-D map scene.

AlignedSegment(borehole_id, family, from_md, ...)

One logged interval as a scene-space polyline.

SceneAlignment(holes, family[, warnings])

Result of aligning a whole document to one scene.
class pycsamt.map.borehole_align.AlignedSegment(borehole_id, family, from_md, to_md, color, points, metadata=<factory>)[source]

Bases: object

One logged interval as a scene-space polyline.

Parameters:
borehole_id: str
family: str
from_md: float
to_md: float
color: str
points: tuple[tuple[float, float, float], ...]
metadata: dict[str, Any]
class pycsamt.map.borehole_align.AlignedHole(borehole_id, name, collar_scene, centerline, segments, display_radius, relation, warnings=(), placed=True)[source]

Bases: object

One borehole placed in the 3-D map scene.

Parameters:
borehole_id: str
name: str
collar_scene: tuple[float, float, float]
centerline: tuple[tuple[float, float, float], ...]
segments: tuple[AlignedSegment, ...]
display_radius: float
relation: str
warnings: tuple[str, ...] = ()
placed: bool = True
class pycsamt.map.borehole_align.SceneAlignment(holes, family, warnings=())[source]

Bases: object

Result of aligning a whole document to one scene.

Parameters:
holes: tuple[AlignedHole, ...]
family: str
warnings: tuple[str, ...] = ()
property placed: tuple[AlignedHole, ...][source]
pycsamt.map.borehole_align.surface_from_sections(sections)[source]

Build a u -> elevation interpolator from section terrain lines.

sections is a list of (u_values, elevation_values) pairs, one per rendered line, in the same local metres as SurveyFrame. Returns None when no finite terrain is available (the caller then falls back to a flat z = 0 datum).

Parameters:

sections (Sequence[tuple[Sequence[float], Sequence[float]]])

Return type:

Callable[[float], float] | None

pycsamt.map.borehole_align.align_boreholes_to_scene(document, frame, *, family='lithology', azimuth_deg=0.0, surface=None, datum='surface', scene_bounds=None, depth_range=None, radius_policy=None, offset_shift=0.0, offset_scale=1.0, lean_deg=0.0, lean_azimuth_deg=0.0, lean_only_vertical=True, sampling_step_md=10.0, selected_ids=None)[source]

Align every borehole in document to a 3-D map scene.

Parameters:

  • document (PCBHDocument)

  • frame (SurveyFrame) – The survey’s local frame (see pycsamt.map.geometry. survey_frame()), fitted from the same stations the scene uses.

  • family (str, default='lithology') – Interval-log family to colour the trajectory by.

  • azimuth_deg (float, default=0) – Scene azimuth, matching VolumeMapOptions.azimuth — the hole’s cross-strike offset is rotated by it exactly as line panels are.

  • surface (callable, optional) – u -> elevation terrain function (see surface_from_sections()). Required for datum='surface'.

  • datum ({'surface', 'collar_z', 'zero'}, default='surface') – Depth reference. surface drapes the collar onto the terrain line, collar_z trusts the PCBH collar elevation, zero puts the collar at z = 0 (matching a no-topography scene).

  • scene_bounds (tuple, optional) – (umin, umax, vmin, vmax, zmin, zmax) of the imaged volume, for the per-hole relation classification.

  • depth_range (tuple, optional) – (lo, hi) metres-below-datum clip applied to the trajectory, matching the scene’s depth filter.

  • radius_policy (DisplayRadiusPolicy, optional) – View-only tube radius policy (physical diameter is never changed).

  • offset_shift (float, default=0) – Cross-strike origin shift, in local metres, applied to every borehole v before offset_scale. The pycsamt.map.volume builders normalise the line panels so the front-most line sits at v = 0 (see pycsamt.map.geometry.normalize_offsets()); pass that same shift here or the holes land in front of / behind their line.

  • offset_scale (float, default=1) – Cross-strike exaggeration matching VolumeMapOptions.line_spacing — the scene stretches the line-to-line axis by this factor, so the hole’s offset must stretch with it.

  • lean_deg (float, default=0) – Apparent lean from vertical, in degrees, applied to holes that have no surveyed deviation (see lean_only_vertical). 0 keeps every hole plumb.

  • lean_azimuth_deg (float, default=0) – Compass bearing (0 = grid north, 90 = east) the leaned hole tips toward.

  • lean_only_vertical (bool, default=True) – When true, only holes whose desurveyed trajectory stays within ~1 m of the collar are leaned; real deviation surveys pass through untouched. Set false to force every hole to lean_deg.

  • sampling_step_md (float, default=10) – Trajectory sampling step in measured depth.

  • selected_ids (set of str, optional) – Highlighted borehole ids (passed through to the render model).

Return type:

SceneAlignment