baselode 0.1.0__py3-none-any.whl

baselode/__init__.py

@@ -0,0 +1,9 @@
+# Copyright (C) 2026 Darkmine Pty Ltd
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("baselode")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

baselode/datamodel.py

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# Copyright (C) 2026 Darkmine Pty Ltd
+
+# This file is part of baselode.
+
+# baselode is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# baselode is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with baselode.  If not, see <https://www.gnu.org/licenses/>.
+
+"""
+Baselode Open Data Model
+
+Provides a consistent schema for data handling throughout the library.
+
+Individual data loaders apply common column mapping, but also accept user-provided column maps to handle variations in source data.
+"""
+
+HOLE_ID = "hole_id"
+LATITUDE = "latitude"
+LONGITUDE = "longitude"
+ELEVATION = "elevation"
+AZIMUTH = "azimuth"
+DIP = "dip"
+FROM = "from"
+TO = "to"
+MID = "mid"
+PROJECT_ID = "project_id"
+EASTING = "easting"
+NORTHING = "northing"
+CRS = "crs"
+DEPTH = "depth"

baselode/drill/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (C) 2026 Darkmine Pty Ltd
+# SPDX-License-Identifier: GPL-3.0-or-later

baselode/drill/composite.py

@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# Copyright (C) 2026 Darkmine Pty Ltd
+
+# This file is part of baselode.
+
+# baselode is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# baselode is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with baselode.  If not, see <https://www.gnu.org/licenses/>.
+
+"""Compositing and resampling helpers."""
+
+import numpy as np
+import pandas as pd
+
+from baselode.datamodel import EASTING, NORTHING, ELEVATION
+
+
+def composite_intervals(df, value_col, from_col="from", to_col="to", length=1.0, method="average"):
+    if df.empty:
+        return df.copy()
+    df_sorted = df.sort_values(["hole_id", from_col])
+    composites = []
+    for hole_id, group in df_sorted.groupby("hole_id"):
+        start = group[from_col].min()
+        end = group[to_col].max()
+        bins = np.arange(start, end + length, length)
+        for i in range(len(bins) - 1):
+            c_from = bins[i]
+            c_to = bins[i + 1]
+            window = group[(group[from_col] < c_to) & (group[to_col] > c_from)]
+            if window.empty:
+                continue
+            overlap_len = (np.minimum(window[to_col], c_to) - np.maximum(window[from_col], c_from)).clip(lower=0)
+            weights = overlap_len / overlap_len.sum()
+            if method == "sum":
+                val = (window[value_col] * overlap_len).sum()
+            else:
+                val = (window[value_col] * weights).sum()
+            composites.append({"hole_id": hole_id, from_col: c_from, to_col: c_to, value_col: val})
+    return pd.DataFrame(composites)
+
+
+def resample_trace(trace_df, step=1.0):
+    if trace_df.empty:
+        return trace_df.copy()
+    resampled = []
+    for hole_id, group in trace_df.groupby("hole_id"):
+        group_sorted = group.sort_values("md")
+        mds = group_sorted["md"].values
+        start = mds.min()
+        end = mds.max()
+        sample_mds = np.arange(start, end + step, step)
+        res_e = np.interp(sample_mds, mds, group_sorted[EASTING].values)
+        res_n = np.interp(sample_mds, mds, group_sorted[NORTHING].values)
+        res_z = np.interp(sample_mds, mds, group_sorted[ELEVATION].values)
+        for md_val, easting, northing, elevation in zip(sample_mds, res_e, res_n, res_z):
+            resampled.append({"hole_id": hole_id, "md": md_val, EASTING: easting, NORTHING: northing, ELEVATION: elevation})
+    return pd.DataFrame(resampled)
+
+
+def merge_numeric_categorical(numeric_df, categorical_df, on_cols=("hole_id", "from", "to")):
+    if numeric_df.empty and categorical_df.empty:
+        return pd.DataFrame()
+    if numeric_df.empty:
+        return categorical_df.copy()
+    if categorical_df.empty:
+        return numeric_df.copy()
+    return numeric_df.merge(categorical_df, on=list(on_cols), how="outer")

baselode/drill/data.py

@@ -0,0 +1,276 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# Copyright (C) 2026 Darkmine Pty Ltd
+
+# This file is part of baselode.
+
+# baselode is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# baselode is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with baselode.  If not, see <https://www.gnu.org/licenses/>.
+
+"""Data loading and table normalization helpers for drillhole datasets.
+
+Supports CSV, Parquet, or SQL sources and applies column
+standardization towards the baselode open data model, 
+so downstream functions can expect consistent keys.
+"""
+
+import pandas as pd
+import geopandas as gpd
+
+from baselode.datamodel import ( HOLE_ID, LATITUDE, LONGITUDE, ELEVATION, AZIMUTH, DIP, FROM, TO, MID, PROJECT_ID, EASTING, NORTHING, CRS, DEPTH )
+
+
+"""
+Baselode Open Data Model
+
+Provides a consistent schema for data handling throughout the library.
+
+Individual data loaders apply common column mapping, but also accept user-provided column maps to handle variations in source data.
+"""
+
+# Minimum expected columns for drillhole collars
+# The collar forms the basis for hole_id and spatial location, so it is expected to exist in all datasets and be standardized as much as possible.
+BASELODE_DATA_MODEL_DRILL_COLLAR = {
+    # A unique hole identifier across the entire dataset and all future data sets
+    HOLE_ID: str,
+    # The hole ID from the original collar source
+    "datasource_hole_id": str,
+    # The project ID or project code from the original collar source, if available
+    PROJECT_ID: str,
+    # The latitude of the collar, in decimal degrees (WGS84)
+    LATITUDE: float,
+    # The longitude of the collar, in decimal degrees (WGS84)
+    LONGITUDE: float,
+    # The elevation of the collar, in meters above sea level (WGS84)
+    ELEVATION: float,
+    # The easting coordinate of the collar, in meters (projected CRS)
+    EASTING: float,
+    # The northing coordinate of the collar, in meters (projected CRS)
+    NORTHING: float,
+    # The coordinate reference system of the collar coordinates for easting/northing, as an EPSG code or proj string
+    CRS: str
+}
+
+BASELODE_DATA_MODEL_DRILL_SURVEY = {
+    # The unique hole id that maps to the collar and any other data tables
+    HOLE_ID: str,
+    # The depth along the hole where the survey measurement was taken / started
+    DEPTH: float,
+    # The depth along the hole where the survey measurement ended, if applicable (some surveys are point measurements and may not have a 'to' depth)
+    TO: float,
+    # The azimuth of the hole at the survey depth, in degrees from north
+    AZIMUTH: float,
+    # The dip of the hole at the survey depth, in degrees from horizontal (negative values indicate downward inclination)
+    DIP: float
+}
+
+BASELODE_DATA_MODEL_DRILL_ASSAY = {
+    # The unique hole id that maps to the collar and any other data tables
+    HOLE_ID: str,
+    # The depth along the hole where the assay interval starts
+    FROM: float,
+    # The depth along the hole where the assay interval ends
+    TO: float,
+    # The midpoint depth of the assay interval
+    MID: float,
+    # assay value columns are variable and not standardized here. 
+    # Assays may be flattened (one column per assay type) or long (one row per assay type with an additional 'assay_type' column)
+}
+
+
+# This column map is used to make a 'best guess' for mapping common variations in source column names to the baselode data model.
+# It is applied in the standardize_columns function, but users can also provide their own column map to override or extend this mapping as needed.
+# The keys from the input source are normalized to lowercase and stripped of whitespace for more robust matching.
+# this dictionary is stored for human readability,then pivoted to make lookup quicker in code.
+# Be cautious of not mapping a source column to multiple baselode columns, as this can lead to unpredictable results. 
+DEFAULT_COLUMN_MAP = {
+    HOLE_ID: ["hole_id", "holeid", "hole id", "hole-id"],
+    "datasource_hole_id": ["datasource_hole_id", "datasourceholeid", "datasource hole id", "datasource-hole-id", "company_hole_id", "companyholeid", "company hole id", "company-hole-id"],
+    PROJECT_ID: ["project_id", "projectid", "project id", "project-id", "project_code", "projectcode", "project code", "project-code", "companyId", "company_id", "companyid", "company id", "company-id", "dataset", "project"],
+    LATITUDE: ["latitude", "lat"],
+    LONGITUDE: ["longitude", "lon"],
+    ELEVATION: ["elevation", "rl", "elev", "z"],
+    EASTING: ["easting", "x"],
+    NORTHING: ["northing", "y"],
+    CRS: ["crs", "epsg", "projection"],
+    FROM: ["from", "depth_from", "from_depth", "samp_from", "sample_from", "sampfrom", "fromdepth"],
+    TO: ["to", "depth_to", "to_depth", "samp_to", "sample_to", "sampto", "todepth"],
+    AZIMUTH: ["azimuth", "az", "dipdir", "dip_direction"],
+    DIP: ["dip"],
+    "declination": ["declination", "dec"],
+    DEPTH: ["depth", "survey_depth", "surveydepth"]
+}
+
+# Pivot the DEFAULT_COLUMN_MAP for efficient reverse lookup
+# Maps normalized column names -> standardized baselode column names
+_COLUMN_LOOKUP = {}
+for standard_col, variations in DEFAULT_COLUMN_MAP.items():
+    for variation in variations:
+        normalized = variation.lower().strip()
+        _COLUMN_LOOKUP[normalized] = standard_col
+
+
+def _frame(df):
+    if df is None:
+        return pd.DataFrame()
+    if isinstance(df, pd.DataFrame):
+        return df.copy()
+    return pd.DataFrame(df)
+
+
+def standardize_columns(df, column_map=None, source_column_map=None):
+    column_map = column_map or DEFAULT_COLUMN_MAP
+
+    lookup = dict(_COLUMN_LOOKUP)
+    if source_column_map:
+        normalized_map = {
+            str(raw_name).lower().strip(): str(expected_name).lower().strip()
+            for raw_name, expected_name in source_column_map.items()
+            if raw_name is not None and expected_name is not None
+        }
+        lookup.update(normalized_map)
+
+    renamed = {}
+    for col in df.columns:
+        key = col.lower().strip()
+        mapped = lookup.get(key, key)
+        renamed[col] = mapped
+    out = df.rename(columns=renamed)
+    if not out.columns.is_unique:
+        out = out.T.groupby(level=0, sort=False).first().T
+    return out
+
+
+def load_table(source, kind="csv", connection=None, query=None, table=None, column_map=None, source_column_map=None, **kwargs):
+    if isinstance(source, pd.DataFrame):
+        df = source.copy()
+    elif kind == "csv":
+        df = pd.read_csv(source, **kwargs)
+    elif kind == "parquet":
+        df = pd.read_parquet(source, **kwargs)
+    elif kind == "sql":
+        if query is None and table is None:
+            raise ValueError("For SQL sources, provide query or table")
+        if query is not None:
+            df = pd.read_sql_query(query, connection, **kwargs)
+        else:
+            df = pd.read_sql_table(table, connection, **kwargs)
+    else:
+        raise ValueError(f"Unsupported kind: {kind}")
+    return standardize_columns(df, column_map=column_map, source_column_map=source_column_map)
+
+
+def load_collars(source, crs=None, source_column_map=None, keep_all=True, **kwargs):
+    df = load_table(source, source_column_map=source_column_map, **kwargs)
+
+    if HOLE_ID not in df.columns:
+        raise ValueError(f"Collar table missing column: {HOLE_ID}")
+
+    required_cols = set(BASELODE_DATA_MODEL_DRILL_COLLAR.keys())
+
+    has_xy = EASTING in df.columns and NORTHING in df.columns 
+    has_latlon = LATITUDE in df.columns and LONGITUDE in df.columns
+    if not has_xy and has_latlon:
+        required_cols -= {EASTING, NORTHING, CRS}
+    elif has_xy and not has_latlon:
+        required_cols -= {LATITUDE, LONGITUDE}
+        
+    if has_latlon:
+        geom = gpd.points_from_xy(df[LONGITUDE], df[LATITUDE])
+        resolved_crs = crs or "EPSG:4326"
+    else:
+        geom = gpd.points_from_xy(df[EASTING], df[NORTHING])
+        resolved_crs = crs
+
+    # if dataset_hole_id was not populated, copy it from hole_id
+    if "datasource_hole_id" not in df.columns:
+        hole_series = df[HOLE_ID]
+        if isinstance(hole_series, pd.DataFrame):
+            hole_series = hole_series.bfill(axis=1).iloc[:, 0]
+        df["datasource_hole_id"] = hole_series
+
+    for col in sorted(required_cols):
+        if col not in df.columns:
+            raise ValueError(f"Collar table missing column: {col}")
+
+    if not keep_all:
+        df = df[[col for col in BASELODE_DATA_MODEL_DRILL_COLLAR.keys() if col in required_cols]]
+
+    return gpd.GeoDataFrame(df, geometry=geom, crs=resolved_crs)
+
+
+def load_surveys(source, source_column_map=None, keep_all=True, **kwargs):
+    df = load_table(source, source_column_map=source_column_map, **kwargs)
+    required_cols = set(BASELODE_DATA_MODEL_DRILL_SURVEY.keys())
+
+    if TO not in df.columns:
+        required_cols -= {TO}
+
+    required = [HOLE_ID, DEPTH, AZIMUTH, DIP]
+    for col in required:
+        if col not in df.columns:
+            raise ValueError(f"Survey table missing column: {col}")
+
+    if not keep_all:
+        df = df[[col for col in BASELODE_DATA_MODEL_DRILL_SURVEY.keys() if col in required_cols]]
+
+    return df.sort_values([HOLE_ID, DEPTH])
+
+
+def load_assays(source, source_column_map=None, keep_all=True, **kwargs):
+    df = load_table(source, source_column_map=source_column_map, **kwargs)
+    required_cols = set(BASELODE_DATA_MODEL_DRILL_ASSAY.keys())
+
+    required = [HOLE_ID, FROM, TO]
+    for col in required:
+        if col not in df.columns:
+            raise ValueError(f"Assay table missing column: {col}")
+
+    # Calculate midpoint depth
+    df[MID] = 0.5 * (df[FROM] + df[TO])
+
+    if not keep_all:
+        df = df[[col for col in BASELODE_DATA_MODEL_DRILL_ASSAY.keys() if col in required_cols]]
+
+    return df.sort_values([HOLE_ID, FROM, TO])
+
+
+def join_assays_to_traces(assays, traces, on_cols=(HOLE_ID,)):
+    if traces.empty:
+        return assays.copy()
+    merged = assays.merge(traces, on=list(on_cols), how="left", suffixes=("", "_trace"))
+    return merged
+
+
+def filter_by_project(df, project_id=None):
+    if project_id is None or df.empty or PROJECT_ID not in df.columns:
+        return df.copy()
+    return df.loc[df[PROJECT_ID] == project_id].copy()
+
+
+def coerce_numeric(df, columns):
+    out = df.copy()
+    for col in columns:
+        if col in out.columns:
+            out[col] = pd.to_numeric(out[col], errors="coerce")
+    return out
+
+
+def assemble_dataset(collars=None, surveys=None, assays=None, structures=None, metadata=None):
+    return {
+        "collars": _frame(collars),
+        "surveys": _frame(surveys),
+        "assays": _frame(assays),
+        "structures": _frame(structures),
+        "metadata": metadata or {},
+    }

baselode/drill/desurvey.py

@@ -0,0 +1,191 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# Copyright (C) 2026 Darkmine Pty Ltd
+
+# This file is part of baselode.
+
+# baselode is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# baselode is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with baselode.  If not, see <https://www.gnu.org/licenses/>.
+
+"""Desurveying utilities.
+
+Supports multiple methods that trade simplicity for accuracy:
+- minimum_curvature (default): standard industry approach.
+- tangential: keeps the initial station orientation through the segment.
+- balanced_tangential: averages start/end orientations per segment.
+
+All methods output a trace table with x, y, z coordinates at chosen step size,
+plus measured depth and azimuth/dip per vertex. Dependencies are limited to
+pandas and numpy for portability.
+"""
+
+import math
+import pandas as pd
+
+from baselode.datamodel import HOLE_ID, AZIMUTH, DIP, FROM, TO, EASTING, NORTHING, ELEVATION, DEPTH, MID
+
+
+def _direction_cosines(azimuth, dip):
+    az_rad = math.radians(azimuth)
+    dip_rad = math.radians(dip)
+    ca = math.cos(dip_rad) * math.sin(az_rad)
+    cb = math.cos(dip_rad) * math.cos(az_rad)
+    cc = math.sin(dip_rad) * -1
+    return ca, cb, cc
+
+
+def _segment_displacement(delta_md, az0, dip0, az1, dip1, method="minimum_curvature"):
+    ca0, cb0, cc0 = _direction_cosines(az0, dip0)
+    ca1, cb1, cc1 = _direction_cosines(az1, dip1)
+    if method == "tangential":
+        return delta_md * ca0, delta_md * cb0, delta_md * cc0, az0, dip0
+    if method == "balanced_tangential":
+        az_avg = 0.5 * (az0 + az1)
+        dip_avg = 0.5 * (dip0 + dip1)
+        ca_avg, cb_avg, cc_avg = _direction_cosines(az_avg, dip_avg)
+        return delta_md * ca_avg, delta_md * cb_avg, delta_md * cc_avg, az_avg, dip_avg
+
+    # Minimum curvature (default)
+    dogleg = math.acos(max(-1.0, min(1.0, ca0 * ca1 + cb0 * cb1 + cc0 * cc1)))
+    rf = 1.0
+    if dogleg > 1e-6:
+        rf = 2 * math.tan(dogleg / 2) / dogleg
+    dx = 0.5 * delta_md * (ca0 + ca1) * rf
+    dy = 0.5 * delta_md * (cb0 + cb1) * rf
+    dz = 0.5 * delta_md * (cc0 + cc1) * rf
+    return dx, dy, dz, az1, dip1
+
+
+def _desurvey(collars, surveys, step=1.0, method="minimum_curvature"):
+    if collars.empty or surveys.empty:
+        return pd.DataFrame(columns=[HOLE_ID, "md", EASTING, NORTHING, ELEVATION, AZIMUTH, DIP])
+
+    traces = []
+    for hole_id, collar in collars.groupby(HOLE_ID):
+        collar_row = collar.iloc[0]
+        hole_surveys = surveys[surveys[HOLE_ID] == hole_id].sort_values(DEPTH)
+        if hole_surveys.empty:
+            continue
+        x, y, z = float(collar_row.get(EASTING, 0)), float(collar_row.get(NORTHING, 0)), float(collar_row.get(ELEVATION, 0))
+        md_cursor = float(hole_surveys.iloc[0][DEPTH])
+        az_prev = float(hole_surveys.iloc[0][AZIMUTH])
+        dip_prev = float(hole_surveys.iloc[0][DIP])
+        first_record = {HOLE_ID: hole_id, "md": md_cursor, EASTING: x, NORTHING: y, ELEVATION: z, AZIMUTH: az_prev, DIP: dip_prev}
+        traces.append(first_record)
+
+        for idx in range(len(hole_surveys) - 1):
+            s0 = hole_surveys.iloc[idx]
+            s1 = hole_surveys.iloc[idx + 1]
+            md0 = float(s0[DEPTH])
+            md1 = float(s1[DEPTH])
+            delta_md = md1 - md0
+            if delta_md <= 0:
+                continue
+            az0, dip0 = float(s0[AZIMUTH]), float(s0[DIP])
+            az1, dip1 = float(s1[AZIMUTH]), float(s1[DIP])
+
+            segment_steps = max(1, int(math.ceil(delta_md / step)))
+            md_increment = delta_md / segment_steps
+            for step_idx in range(segment_steps):
+                md_cursor += md_increment
+                weight = (md_cursor - md0) / delta_md
+                az_interp = az0 + weight * (az1 - az0)
+                dip_interp = dip0 + weight * (dip1 - dip0)
+                dx, dy, dz, az_for_record, dip_for_record = _segment_displacement(
+                    md_increment,
+                    az0=az0,
+                    dip0=dip0,
+                    az1=az1,
+                    dip1=dip1,
+                    method=method,
+                )
+                x += dx
+                y += dy
+                z += dz
+                record = {
+                    HOLE_ID: hole_id,
+                    "md": md_cursor,
+                    EASTING: x,
+                    NORTHING: y,
+                    ELEVATION: z,
+                    AZIMUTH: az_interp if method == "minimum_curvature" else az_for_record,
+                    DIP: dip_interp if method == "minimum_curvature" else dip_for_record,
+                }
+                traces.append(record)
+    out = pd.DataFrame(traces)
+    return out
+
+
+def minimum_curvature_desurvey(collars, surveys, step=1.0):
+    return _desurvey(collars=collars, surveys=surveys, step=step, method="minimum_curvature")
+
+
+def tangential_desurvey(collars, surveys, step=1.0,):
+    """Simpler desurvey: uses the starting station orientation for each segment."""
+    return _desurvey(collars=collars, surveys=surveys, step=step, method="tangential")
+
+
+def balanced_tangential_desurvey(collars, surveys, step=1.0):
+    """Balanced tangential desurvey using the average of start/end orientations per segment."""
+    return _desurvey(collars=collars, surveys=surveys, step=step, method="balanced_tangential")
+
+
+def attach_assay_positions(assays, traces):
+
+    if assays.empty or traces.empty:
+        return assays.copy()
+
+    traces_sorted = traces.copy()
+    traces_sorted["md"] = pd.to_numeric(traces_sorted["md"], errors="coerce")
+    traces_sorted = traces_sorted[traces_sorted[HOLE_ID].notna() & traces_sorted["md"].notna()]
+    traces_sorted = traces_sorted.sort_values([HOLE_ID, "md"], kind="mergesort").reset_index(drop=True)
+
+    assays_sorted = assays.copy()
+    assays_sorted["from"] = pd.to_numeric(assays_sorted[FROM], errors="coerce")
+    assays_sorted["to"] = pd.to_numeric(assays_sorted[TO], errors="coerce")
+    assays_sorted = assays_sorted[assays_sorted[HOLE_ID].notna()]
+    assays_sorted = assays_sorted.sort_values([HOLE_ID, FROM, TO], kind="mergesort")
+    # Calculate midpoint if not already present (typically added by load_assays)
+    if MID not in assays_sorted.columns:
+        assays_sorted[MID] = 0.5 * (assays_sorted[FROM] + assays_sorted[TO])
+    assays_sorted = assays_sorted[assays_sorted[MID].notna()]
+
+    merged_groups = []
+    for hid, group in assays_sorted.groupby(HOLE_ID, sort=False):
+        tgroup = traces_sorted[traces_sorted[HOLE_ID] == hid]
+        if tgroup.empty:
+            merged_groups.append(group)
+            continue
+        pos_cols = [c for c in ["md", EASTING, NORTHING, ELEVATION, AZIMUTH, DIP] if c in tgroup.columns]
+        tgroup_use = tgroup[[HOLE_ID] + pos_cols].sort_values("md", kind="mergesort")
+        merged = pd.merge_asof(
+            group.sort_values(MID, kind="mergesort"),
+            tgroup_use,
+            left_on=MID,
+            right_on="md",
+            by=HOLE_ID,
+            direction="nearest",
+            suffixes=("", "_trace"),
+        )
+        drop_cols = [col for col in [f"{HOLE_ID}_trace", "hole_id_trace"] if col in merged.columns]
+        if drop_cols:
+            merged = merged.drop(columns=drop_cols)
+        merged_groups.append(merged)
+
+    if not merged_groups:
+        return assays_sorted
+    return pd.concat(merged_groups, ignore_index=True)
+
+
+def build_traces(collars, surveys, step=1.0):
+    return minimum_curvature_desurvey(collars=collars, surveys=surveys, step=step)