xcheck 0.1.0__tar.gz

xcheck-0.1.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: xcheck
+Version: 0.1.0
+Summary: A package for cross-checking radargram layers using dot product similarity.
+Author-email: Your Name <your.email@example.com>
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Requires-Dist: scipy
+Requires-Dist: pandas
+Requires-Dist: cartopy
+
+# XCheck — Consistency-Based Validation of Englacial Layer Annotations
+
+A Python implementation of the radargram layer-matching framework from:
+
+> Hassan, Muhammad Behroze; Tama, Bayu Adhi; Purushotham, Sanjay;
+> Janeja, Vandana P. **XCheck: A Consistency-Based Validation Framework
+> for Englacial Layers Annotations.**
+> <https://par.nsf.gov/biblio/10673248> ·
+> DOI: [10.1109/ICDMW69685.2025.00015](https://doi.org/10.1109/ICDMW69685.2025.00015)
+
+XCheck validates whether annotated englacial layers are *consistent*
+between two radargrams that observe the same ice — either two
+**consecutive** flight segments (overlap found automatically via GPS time)
+or two **intersecting** flight paths (crossing point supplied via a CSV).
+
+---
+
+## Features
+
+- **GPS Overlap Detection**: Automatically finds temporally overlapping segments between two radargrams using log-transformed GPS timestamps.
+- **Data Loading & Masking**: Loads `.mat` radargram and ground truth layer files and converts annotated layers into binary depth masks.
+- **Geometric Alignment**: Adjusts radargram columns by surface elevation before comparison to correct for topographic variation.
+- **Layer Continuity Matching**: Dot-product similarity algorithm that identifies corresponding layers between two radargrams at their crossing or overlap point.
+- **Flexible Input**: Accepts a single radargram pair via CLI flags, a batch CSV of pairs, or a pre-computed intersections CSV.
+- **Visualization**: Map plots of GPS overlap regions and side-by-side mask views with matched layer annotations.
+
+---
+
+## Installation
+
+```bash
+pip install xcheck
+```
+
+### NDH_PythonTools (required)
+
+XCheck uses [NDH_PythonTools](https://github.com/nholschuh/NDH_PythonTools)
+for `.mat` file loading and radar data processing. Because that repository
+is not a standard pip package, it must be installed manually:
+
+```bash
+git clone https://github.com/nholschuh/NDH_PythonTools.git
+```
+
+Then add its **parent directory** to `PYTHONPATH` before running xcheck:
+
+```bash
+# Linux / macOS
+export PYTHONPATH="/path/to/parent/of/NDH_PythonTools"
+
+# Windows PowerShell
+$env:PYTHONPATH = "C:\path\to\parent\of\NDH_PythonTools"
+```
+
+---
+
+## Quick Start
+
+### Layer matching only (no NDH_PythonTools needed)
+
+```python
+import numpy as np
+from xcheck import match_layers_with_dot_product
+
+m1 = np.zeros((6, 5)); m1[[1, 3, 5], :] = 1
+m2 = np.zeros((6, 5)); m2[[1, 3, 5], :] = 1
+
+matches = match_layers_with_dot_product(m1, m2, max_distance=1,
+                                        window_size=3, dp_threshold=1)
+print(matches)  # [(1, 1), (3, 3), (5, 5)]
+```
+
+### Python API (requires NDH_PythonTools + data)
+
+```python
+from xcheck import (
+    load_and_process_radargram,
+    load_log_gps_time,
+    find_overlapping_intervals,
+    extract_and_adjust_mask_columns_for_location,
+    match_layers_with_dot_product,
+)
+
+# Load two consecutive radargrams
+r1, m1, d1 = load_and_process_radargram("Data_20120429_01_026.mat",
+                                         layer_dir="./Nick-layer-data-mat/",
+                                         radar_dir="./Nick-raw-radargram-mat/")
+r2, m2, d2 = load_and_process_radargram("Data_20120429_01_027.mat",
+                                         layer_dir="./Nick-layer-data-mat/",
+                                         radar_dir="./Nick-raw-radargram-mat/")
+
+# Find GPS overlap and derive crossing point from midpoint
+import numpy as np
+log_t1 = load_log_gps_time("./Nick-raw-radargram-mat/Data_20120429_01_026.mat")
+log_t2 = load_log_gps_time("./Nick-raw-radargram-mat/Data_20120429_01_027.mat")
+overlaps1, overlaps2 = find_overlapping_intervals(log_t1, log_t2)
+
+for iv1, iv2 in zip(overlaps1, overlaps2):
+    mid1 = (iv1[0] + iv1[1]) // 2
+    mid2 = (iv2[0] + iv2[1]) // 2
+    mc1 = extract_and_adjust_mask_columns_for_location(
+        r1['Longitude'][mid1], r1['Latitude'][mid1], r1, m1, d1, 20)
+    mc2 = extract_and_adjust_mask_columns_for_location(
+        r2['Longitude'][mid2], r2['Latitude'][mid2], r2, m2, d2, 20)
+    matches = match_layers_with_dot_product(mc1, mc2)
+    print(f"Matched layers: {matches}")
+```
+
+---
+
+## CLI
+
+### Single pair — consecutive (no crossing CSV needed)
+
+```bash
+xcheck --r1 Data_20120429_01_026.mat --r2 Data_20120429_01_027.mat \
+       --layer_dir ./Nick-layer-data-mat/ \
+       --radar_dir ./Nick-raw-radargram-mat/
+```
+
+### Single pair — intersecting (crossing looked up from CSV)
+
+```bash
+xcheck --r1 Data_20120330_01_004.mat --r2 Data_20120511_01_054.mat \
+       --intersections_csv ./Intersections_2012.csv \
+       --layer_dir ./Nick-layer-data-mat/ \
+       --radar_dir ./Nick-raw-radargram-mat/
+```
+
+### Single pair — intersecting with explicit crossing coordinates
+
+```bash
+xcheck --r1 Data_20120330_01_004.mat --r2 Data_20120511_01_054.mat \
+       --lat 78.909416 --lon -61.804612 \
+       --layer_dir ./Nick-layer-data-mat/ \
+       --radar_dir ./Nick-raw-radargram-mat/
+```
+
+### Batch mode (all pairs in a CSV)
+
+```bash
+xcheck --intersections_csv ./Intersections_2012.csv \
+       --layer_dir ./Nick-layer-data-mat/ \
+       --radar_dir ./Nick-raw-radargram-mat/
+```
+
+### All CLI arguments
+
+| Argument | Default | Description |
+|---|---|---|
+| `--r1`, `--r2` | — | Single-pair mode: filenames of the two radargrams |
+| `--lat`, `--lon` | — | Crossing coordinates for single-pair mode |
+| `--csv_path` | — | Batch CSV with columns `Radargram 1`, `Radargram 2`, `Latitude`, `Longitude` |
+| `--intersections_csv` | — | Pre-computed intersections CSV (used alone or to look up coordinates) |
+| `--layer_dir` | required | Directory of layer `.mat` files |
+| `--radar_dir` | required | Directory of raw radargram `.mat` files |
+| `--layer_prefix` | `Layer_` | Filename prefix for layer files |
+| `--cols_side` | 20 / 3 | Columns extracted each side of crossing (consecutive / non-consecutive) |
+| `--max_distance` | 4 / 3 | Max depth-pixel gap between candidate layer rows |
+| `--window_size` | 7 / 3 | Dot product window width (must be odd) |
+| `--dp_threshold` | 4 / 1 | Minimum dot product score to confirm a match |
+| `--plot_overlaps` | off | Plot GPS overlap regions on a map |
+
+Default pairs shown as **consecutive / non-consecutive**.
+
+---
+
+## Default thresholds by radargram type
+
+| Parameter | Consecutive | Non-consecutive |
+|---|---|---|
+| `cols_side` | 20 (41 columns) | 3 (7 columns) |
+| `max_distance` | 4 px | 3 px |
+| `window_size` | 7 | 3 |
+| `dp_threshold` | 4 | 1 |
+
+These are selected automatically. Override any of them via CLI flags.
+
+---
+
+## Methodological note
+
+The GPS overlap detection compares **`log(GPS_time)`** between two
+radargrams with an absolute tolerance of `1e-8`. Because
+`d(log t) ≈ dt/t` and GPS times are ~1×10⁹ seconds, this tolerance
+corresponds to matching raw timestamps within roughly 10 seconds.
+Consecutive flight segments (e.g. `_026.mat` → `_027.mat`) share a
+small tail/head of overlapping traces, which is where the crossing point
+is derived. Non-consecutive intersecting radargrams do not share GPS
+timestamps; their crossing point must be supplied via `--intersections_csv`
+or `--lat`/`--lon`.
+
+---
+
+## Project structure
+
+```
+src/xcheck/
+  xcheck.py      Core algorithms: loading, masking, GPS overlap,
+                 column extraction, layer matching, plotting, CLI
+  __init__.py    Public API exports
+pyproject.toml   Build metadata and dependencies
+README.md
+```
+
+---
+
+## License
+
+MIT

xcheck-0.1.0/README.md

@@ -0,0 +1,210 @@
+# XCheck — Consistency-Based Validation of Englacial Layer Annotations
+
+A Python implementation of the radargram layer-matching framework from:
+
+> Hassan, Muhammad Behroze; Tama, Bayu Adhi; Purushotham, Sanjay;
+> Janeja, Vandana P. **XCheck: A Consistency-Based Validation Framework
+> for Englacial Layers Annotations.**
+> <https://par.nsf.gov/biblio/10673248> ·
+> DOI: [10.1109/ICDMW69685.2025.00015](https://doi.org/10.1109/ICDMW69685.2025.00015)
+
+XCheck validates whether annotated englacial layers are *consistent*
+between two radargrams that observe the same ice — either two
+**consecutive** flight segments (overlap found automatically via GPS time)
+or two **intersecting** flight paths (crossing point supplied via a CSV).
+
+---
+
+## Features
+
+- **GPS Overlap Detection**: Automatically finds temporally overlapping segments between two radargrams using log-transformed GPS timestamps.
+- **Data Loading & Masking**: Loads `.mat` radargram and ground truth layer files and converts annotated layers into binary depth masks.
+- **Geometric Alignment**: Adjusts radargram columns by surface elevation before comparison to correct for topographic variation.
+- **Layer Continuity Matching**: Dot-product similarity algorithm that identifies corresponding layers between two radargrams at their crossing or overlap point.
+- **Flexible Input**: Accepts a single radargram pair via CLI flags, a batch CSV of pairs, or a pre-computed intersections CSV.
+- **Visualization**: Map plots of GPS overlap regions and side-by-side mask views with matched layer annotations.
+
+---
+
+## Installation
+
+```bash
+pip install xcheck
+```
+
+### NDH_PythonTools (required)
+
+XCheck uses [NDH_PythonTools](https://github.com/nholschuh/NDH_PythonTools)
+for `.mat` file loading and radar data processing. Because that repository
+is not a standard pip package, it must be installed manually:
+
+```bash
+git clone https://github.com/nholschuh/NDH_PythonTools.git
+```
+
+Then add its **parent directory** to `PYTHONPATH` before running xcheck:
+
+```bash
+# Linux / macOS
+export PYTHONPATH="/path/to/parent/of/NDH_PythonTools"
+
+# Windows PowerShell
+$env:PYTHONPATH = "C:\path\to\parent\of\NDH_PythonTools"
+```
+
+---
+
+## Quick Start
+
+### Layer matching only (no NDH_PythonTools needed)
+
+```python
+import numpy as np
+from xcheck import match_layers_with_dot_product
+
+m1 = np.zeros((6, 5)); m1[[1, 3, 5], :] = 1
+m2 = np.zeros((6, 5)); m2[[1, 3, 5], :] = 1
+
+matches = match_layers_with_dot_product(m1, m2, max_distance=1,
+                                        window_size=3, dp_threshold=1)
+print(matches)  # [(1, 1), (3, 3), (5, 5)]
+```
+
+### Python API (requires NDH_PythonTools + data)
+
+```python
+from xcheck import (
+    load_and_process_radargram,
+    load_log_gps_time,
+    find_overlapping_intervals,
+    extract_and_adjust_mask_columns_for_location,
+    match_layers_with_dot_product,
+)
+
+# Load two consecutive radargrams
+r1, m1, d1 = load_and_process_radargram("Data_20120429_01_026.mat",
+                                         layer_dir="./Nick-layer-data-mat/",
+                                         radar_dir="./Nick-raw-radargram-mat/")
+r2, m2, d2 = load_and_process_radargram("Data_20120429_01_027.mat",
+                                         layer_dir="./Nick-layer-data-mat/",
+                                         radar_dir="./Nick-raw-radargram-mat/")
+
+# Find GPS overlap and derive crossing point from midpoint
+import numpy as np
+log_t1 = load_log_gps_time("./Nick-raw-radargram-mat/Data_20120429_01_026.mat")
+log_t2 = load_log_gps_time("./Nick-raw-radargram-mat/Data_20120429_01_027.mat")
+overlaps1, overlaps2 = find_overlapping_intervals(log_t1, log_t2)
+
+for iv1, iv2 in zip(overlaps1, overlaps2):
+    mid1 = (iv1[0] + iv1[1]) // 2
+    mid2 = (iv2[0] + iv2[1]) // 2
+    mc1 = extract_and_adjust_mask_columns_for_location(
+        r1['Longitude'][mid1], r1['Latitude'][mid1], r1, m1, d1, 20)
+    mc2 = extract_and_adjust_mask_columns_for_location(
+        r2['Longitude'][mid2], r2['Latitude'][mid2], r2, m2, d2, 20)
+    matches = match_layers_with_dot_product(mc1, mc2)
+    print(f"Matched layers: {matches}")
+```
+
+---
+
+## CLI
+
+### Single pair — consecutive (no crossing CSV needed)
+
+```bash
+xcheck --r1 Data_20120429_01_026.mat --r2 Data_20120429_01_027.mat \
+       --layer_dir ./Nick-layer-data-mat/ \
+       --radar_dir ./Nick-raw-radargram-mat/
+```
+
+### Single pair — intersecting (crossing looked up from CSV)
+
+```bash
+xcheck --r1 Data_20120330_01_004.mat --r2 Data_20120511_01_054.mat \
+       --intersections_csv ./Intersections_2012.csv \
+       --layer_dir ./Nick-layer-data-mat/ \
+       --radar_dir ./Nick-raw-radargram-mat/
+```
+
+### Single pair — intersecting with explicit crossing coordinates
+
+```bash
+xcheck --r1 Data_20120330_01_004.mat --r2 Data_20120511_01_054.mat \
+       --lat 78.909416 --lon -61.804612 \
+       --layer_dir ./Nick-layer-data-mat/ \
+       --radar_dir ./Nick-raw-radargram-mat/
+```
+
+### Batch mode (all pairs in a CSV)
+
+```bash
+xcheck --intersections_csv ./Intersections_2012.csv \
+       --layer_dir ./Nick-layer-data-mat/ \
+       --radar_dir ./Nick-raw-radargram-mat/
+```
+
+### All CLI arguments
+
+| Argument | Default | Description |
+|---|---|---|
+| `--r1`, `--r2` | — | Single-pair mode: filenames of the two radargrams |
+| `--lat`, `--lon` | — | Crossing coordinates for single-pair mode |
+| `--csv_path` | — | Batch CSV with columns `Radargram 1`, `Radargram 2`, `Latitude`, `Longitude` |
+| `--intersections_csv` | — | Pre-computed intersections CSV (used alone or to look up coordinates) |
+| `--layer_dir` | required | Directory of layer `.mat` files |
+| `--radar_dir` | required | Directory of raw radargram `.mat` files |
+| `--layer_prefix` | `Layer_` | Filename prefix for layer files |
+| `--cols_side` | 20 / 3 | Columns extracted each side of crossing (consecutive / non-consecutive) |
+| `--max_distance` | 4 / 3 | Max depth-pixel gap between candidate layer rows |
+| `--window_size` | 7 / 3 | Dot product window width (must be odd) |
+| `--dp_threshold` | 4 / 1 | Minimum dot product score to confirm a match |
+| `--plot_overlaps` | off | Plot GPS overlap regions on a map |
+
+Default pairs shown as **consecutive / non-consecutive**.
+
+---
+
+## Default thresholds by radargram type
+
+| Parameter | Consecutive | Non-consecutive |
+|---|---|---|
+| `cols_side` | 20 (41 columns) | 3 (7 columns) |
+| `max_distance` | 4 px | 3 px |
+| `window_size` | 7 | 3 |
+| `dp_threshold` | 4 | 1 |
+
+These are selected automatically. Override any of them via CLI flags.
+
+---
+
+## Methodological note
+
+The GPS overlap detection compares **`log(GPS_time)`** between two
+radargrams with an absolute tolerance of `1e-8`. Because
+`d(log t) ≈ dt/t` and GPS times are ~1×10⁹ seconds, this tolerance
+corresponds to matching raw timestamps within roughly 10 seconds.
+Consecutive flight segments (e.g. `_026.mat` → `_027.mat`) share a
+small tail/head of overlapping traces, which is where the crossing point
+is derived. Non-consecutive intersecting radargrams do not share GPS
+timestamps; their crossing point must be supplied via `--intersections_csv`
+or `--lat`/`--lon`.
+
+---
+
+## Project structure
+
+```
+src/xcheck/
+  xcheck.py      Core algorithms: loading, masking, GPS overlap,
+                 column extraction, layer matching, plotting, CLI
+  __init__.py    Public API exports
+pyproject.toml   Build metadata and dependencies
+README.md
+```
+
+---
+
+## License
+
+MIT

xcheck-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xcheck"
+version = "0.1.0"
+authors = [
+  { name="Your Name", email="your.email@example.com" },
+]
+description = "A package for cross-checking radargram layers using dot product similarity."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.8"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Physics",
+    "Topic :: Scientific/Engineering :: Image Processing",
+]
+dependencies = [
+    "numpy",
+    "matplotlib",
+    "scipy",
+    "pandas",
+    "cartopy",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.scripts]
+xcheck = "xcheck.xcheck:main"

xcheck-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

xcheck-0.1.0/setup.py

@@ -0,0 +1,4 @@
+from setuptools import setup
+
+if __name__ == "__main__":
+    setup()

xcheck-0.1.0/src/xcheck/__init__.py

@@ -0,0 +1,12 @@
+from .xcheck import (
+    load_and_process_radargram,
+    load_log_gps_time,
+    find_overlapping_intervals,
+    load_data,
+    adjust_column_by_surface_elevation,
+    extract_and_adjust_mask_columns_for_location,
+    match_layers_with_dot_product,
+    plot_overlaps,
+    plot_columns_with_labels,
+    main
+)

xcheck-0.1.0/src/xcheck/xcheck.py

@@ -0,0 +1,304 @@
+import pandas as pd
+import numpy as np
+import os
+import sys
+import types
+import argparse
+import scipy.io
+import matplotlib.pyplot as plt
+import cartopy.crs as ccrs
+from cartopy.mpl.gridliner import LONGITUDE_FORMATTER, LATITUDE_FORMATTER
+
+# Register NDH_PythonTools as a package without executing its __init__.py,
+# which auto-imports all submodules including ones with optional heavy deps (pyvista, etc.)
+def _register_ndh_package():
+    for p in sys.path:
+        candidate = os.path.join(p, 'NDH_PythonTools')
+        if os.path.isdir(candidate):
+            if 'NDH_PythonTools' not in sys.modules:
+                pkg = types.ModuleType('NDH_PythonTools')
+                pkg.__path__ = [candidate]
+                pkg.__package__ = 'NDH_PythonTools'
+                sys.modules['NDH_PythonTools'] = pkg
+            return
+    raise ImportError(
+        "NDH_PythonTools not found on sys.path. "
+        "Clone https://github.com/nholschuh/NDH_PythonTools and add its parent directory to PYTHONPATH."
+    )
+
+_register_ndh_package()
+
+from NDH_PythonTools.loadmat import loadmat
+from NDH_PythonTools.radar_load import radar_load
+
+def load_and_process_radargram(file_name, layer_dir, radar_dir, layer_prefix="Layer_"):
+    """Loads radargram data and ground truth layers, then creates a binary mask."""
+    layer_fn = os.path.join(layer_dir, layer_prefix + file_name)
+    radar_fn = os.path.join(radar_dir, file_name)
+
+    groundtruth = loadmat(layer_fn)
+    groundtruth_dists = groundtruth['layer_info'][()][2]
+    groundtruth_layers = groundtruth['layer_info'][()][5].T
+    radar_data, depth_data = radar_load(radar_fn, 0, 1)
+
+    ground_truth_mask_nick = np.zeros_like(depth_data['new_data'])
+
+    for layer in groundtruth_layers:
+        for idx, depth in enumerate(layer):
+            if not np.isnan(depth):
+                depth_idx = np.argmin(np.abs(depth_data['depth_axis'] - depth))
+                dist_idx = np.argmin(np.abs(radar_data['distance'] - groundtruth_dists[idx]))
+                if 0 <= depth_idx < ground_truth_mask_nick.shape[0] and 0 <= dist_idx < ground_truth_mask_nick.shape[1]:
+                    ground_truth_mask_nick[depth_idx, dist_idx] = 1
+    return radar_data, ground_truth_mask_nick, depth_data
+
+def load_log_gps_time(file_path):
+    """Loads GPS time from a .mat file and returns its natural logarithm."""
+    radar_data = scipy.io.loadmat(file_path)
+    gps_time = radar_data['GPS_time'][0]
+    return np.log(gps_time)
+
+def find_overlapping_intervals(log_gps_time1, log_gps_time2, tolerance=1e-8):
+    """Finds overlapping intervals between two logarithmic GPS time series."""
+    overlap_intervals1, overlap_intervals2 = [], []
+    i, j = 0, 0
+    start_i, start_j = None, None
+
+    while i < len(log_gps_time1) and j < len(log_gps_time2):
+        if abs(log_gps_time1[i] - log_gps_time2[j]) < tolerance:
+            if start_i is None:
+                start_i, start_j = i, j
+            i += 1
+            j += 1
+        else:
+            if start_i is not None:
+                overlap_intervals1.append((start_i, i - 1))
+                overlap_intervals2.append((start_j, j - 1))
+                start_i, start_j = None, None
+            if log_gps_time1[i] < log_gps_time2[j]: i += 1
+            else: j += 1
+    if start_i is not None:
+        overlap_intervals1.append((start_i, i - 1))
+        overlap_intervals2.append((start_j, j - 1))
+    return overlap_intervals1, overlap_intervals2
+
+def load_data(file_path):
+    """Loads latitude and longitude data from a .mat file."""
+    radar_data = scipy.io.loadmat(file_path)
+    return radar_data['Latitude'][0], radar_data['Longitude'][0]
+
+def adjust_column_by_surface_elevation(depth_data, idx):
+    """Calculates the depth index corresponding to the surface elevation."""
+    surface_elevation = depth_data['surface_elev'][idx]
+    return np.argmin(np.abs(depth_data['depth_axis'] - surface_elevation))
+
+def extract_and_adjust_mask_columns_for_location(longitude, latitude, radar_data, mask, depth_data, columns_before_after):
+    """Extracts and adjusts mask columns around a specific geospatial location."""
+    dists = (radar_data['Longitude'] - longitude) ** 2 + (radar_data['Latitude'] - latitude) ** 2
+    center_idx = np.argmin(dists)
+    start = max(0, center_idx - columns_before_after)
+    end = min(mask.shape[1], center_idx + columns_before_after + 1)
+
+    reference_surface_idx = adjust_column_by_surface_elevation(depth_data, center_idx)
+    reference_depth_axis = depth_data['depth_axis']
+    adjusted_cols = []
+
+    for idx in range(start, end):
+        current_surface_idx = adjust_column_by_surface_elevation(depth_data, idx)
+        current_depth_axis = depth_data['depth_axis']
+        depth_diff = reference_depth_axis[reference_surface_idx] - current_depth_axis[current_surface_idx]
+        meters_per_pixel = np.mean(np.diff(current_depth_axis))
+        pixel_shift = int(round(depth_diff / meters_per_pixel))
+        col = mask[:, idx]
+        if pixel_shift > 0:
+            col_shifted = np.pad(col, (pixel_shift, 0), mode='constant')[:len(col)]
+        elif pixel_shift < 0:
+            col_shifted = np.pad(col, (0, -pixel_shift), mode='constant')[-pixel_shift:]
+            if len(col_shifted) > len(col): col_shifted = col_shifted[:len(col)]
+            else: col_shifted = np.pad(col_shifted, (0, len(col) - len(col_shifted)), mode='constant')
+        else: col_shifted = col
+        adjusted_cols.append(col_shifted)
+
+    max_len = max(len(col) for col in adjusted_cols)
+    for i, col in enumerate(adjusted_cols):
+        if len(col) < max_len:
+            adjusted_cols[i] = np.pad(col, (0, max_len - len(col)), 'constant')
+    return np.column_stack(adjusted_cols)
+
+def match_layers_with_dot_product(mask1, mask2, max_distance=4, window_size=7, dp_threshold=4, verbose=True):
+    """Matches layers between two radargram masks using a dot product similarity metric."""
+    if window_size % 2 == 0: raise ValueError("window_size must be odd.")
+    matches, matched1, matched2 = [], set(), set()
+    c1, c2 = mask1.shape[1] // 2, mask2.shape[1] // 2
+    hw = window_size // 2
+    cols1 = slice(max(c1 - hw, 0), min(c1 + hw + 1, mask1.shape[1]))
+    cols2 = slice(max(c2 - hw, 0), min(c2 + hw + 1, mask2.shape[1]))
+
+    for i in range(mask1.shape[0]):
+        if i in matched1 or not np.any(mask1[i, :]): continue
+        best_match, best_dist, best_dp = None, max_distance + 1, -1
+        for j in range(mask2.shape[0]):
+            if j in matched2 or not np.any(mask2[j, :]): continue
+            dist = abs(i - j)
+            if dist <= max_distance:
+                r1, r2 = mask1[i, cols1], mask2[j, cols2]
+                if not (r1[hw] == 1 or np.sum(r1) >= 2): continue
+                if not (r2[hw] == 1 or np.sum(r2) >= 2): continue
+                dp = np.dot(r1, r2)
+                if dp >= dp_threshold and dist < best_dist:
+                    best_match, best_dist, best_dp = j, dist, dp
+        if best_match is not None:
+            matches.append((i, best_match))
+            matched1.add(i); matched2.add(best_match)
+            if verbose: print(f"Match: Layer {i} <-> Layer {best_match}")
+    return matches
+
+def plot_overlaps(lat1, lon1, lat2, lon2, overlap_intervals1, overlap_intervals2):
+    ax = plt.figure(figsize=(20, 10)).add_subplot(1, 1, 1, projection=ccrs.PlateCarree())
+    ax.coastlines()
+    gl = ax.gridlines(draw_labels=True, linewidth=1, color='gray', alpha=0.5, linestyle='--')
+    gl.top_labels = gl.right_labels = False
+    ax.scatter(lon1, lat1, color='blue', s=10, label='Radargram 1')
+    ax.scatter(lon2, lat2, color='red', s=10, label='Radargram 2')
+    for (s1, e1), (s2, e2) in zip(overlap_intervals1, overlap_intervals2):
+        ax.plot(lon1[s1:e1+1], lat1[s1:e1+1], color='yellow', linewidth=2)
+        ax.plot(lon2[s2:e2+1], lat2[s2:e2+1], color='yellow', linewidth=2)
+    ax.legend(); plt.show()
+
+def plot_columns_with_labels(mask1, mask2, matches, columns_before_after, title1="R1", title2="R2"):
+    fig, axs = plt.subplots(1, 2, figsize=(14, 6), sharey=True)
+    x_vals = np.arange(-columns_before_after, columns_before_after + 1)
+    axs[0].imshow(mask1, cmap='gray', aspect='auto', extent=(x_vals[0], x_vals[-1], mask1.shape[0], 0))
+    axs[1].imshow(mask2, cmap='gray', aspect='auto', extent=(x_vals[0], x_vals[-1], mask2.shape[0], 0))
+    for i, j in matches:
+        axs[0].axhline(i, color='red', linestyle='--'); axs[1].axhline(j, color='red', linestyle='--')
+    plt.tight_layout(); plt.show()
+
+def _lookup_intersection(intersections_df, file1, file2):
+    """Returns (lon, lat) for a radargram pair from an intersections DataFrame, or None if not found."""
+    mask = (
+        ((intersections_df['Radargram 1'] == file1) & (intersections_df['Radargram 2'] == file2)) |
+        ((intersections_df['Radargram 2'] == file1) & (intersections_df['Radargram 1'] == file2))
+    )
+    hit = intersections_df[mask]
+    if hit.empty:
+        return None
+    return hit['Longitude'].iloc[0], hit['Latitude'].iloc[0]
+
+
+def _process_pair(file1, file2, lon, lat, args):
+    """Run GPS overlap detection and layer matching.
+
+    Non-consecutive/intersecting: crossing point supplied via lon/lat.
+    Consecutive: no crossing point — midpoint of each GPS overlap interval is used instead.
+    """
+    path1 = os.path.join(args.radar_dir, file1)
+    path2 = os.path.join(args.radar_dir, file2)
+
+    # GPS-based overlap detection
+    log_gps1 = load_log_gps_time(path1)
+    log_gps2 = load_log_gps_time(path2)
+    overlaps1, overlaps2 = find_overlapping_intervals(log_gps1, log_gps2)
+    print(f"{file1} <-> {file2}: {len(overlaps1)} GPS overlap interval(s) found")
+    for k, ((s1, e1), (s2, e2)) in enumerate(zip(overlaps1, overlaps2)):
+        print(f"  Interval {k+1}: R1[{s1}:{e1}]  R2[{s2}:{e2}]  ({e1-s1+1} samples)")
+
+    if args.plot_overlaps:
+        lat1_arr, lon1_arr = load_data(path1)
+        lat2_arr, lon2_arr = load_data(path2)
+        plot_overlaps(lat1_arr, lon1_arr, lat2_arr, lon2_arr, overlaps1, overlaps2)
+
+    r1, m1, d1 = load_and_process_radargram(file1, args.layer_dir, args.radar_dir, args.layer_prefix)
+    r2, m2, d2 = load_and_process_radargram(file2, args.layer_dir, args.radar_dir, args.layer_prefix)
+
+    if lon is not None and lat is not None:
+        # Non-consecutive: use provided intersection coordinates
+        cols   = args.cols_side    if args.cols_side    is not None else 3
+        maxd   = args.max_distance if args.max_distance is not None else 3
+        wsize  = args.window_size  if args.window_size  is not None else 3
+        dpth   = args.dp_threshold if args.dp_threshold is not None else 1
+        mc1 = extract_and_adjust_mask_columns_for_location(lon, lat, r1, m1, d1, cols)
+        mc2 = extract_and_adjust_mask_columns_for_location(lon, lat, r2, m2, d2, cols)
+        matches = match_layers_with_dot_product(mc1, mc2, max_distance=maxd, window_size=wsize, dp_threshold=dpth)
+        print(f"Total Matches: {len(matches)}")
+
+    elif overlaps1:
+        # Consecutive: derive crossing point from midpoint of each GPS overlap interval
+        cols   = args.cols_side    if args.cols_side    is not None else 20
+        maxd   = args.max_distance if args.max_distance is not None else 4
+        wsize  = args.window_size  if args.window_size  is not None else 7
+        dpth   = args.dp_threshold if args.dp_threshold is not None else 4
+        for k, (interval1, interval2) in enumerate(zip(overlaps1, overlaps2)):
+            mid1 = (interval1[0] + interval1[1]) // 2
+            mid2 = (interval2[0] + interval2[1]) // 2
+            mc1 = extract_and_adjust_mask_columns_for_location(r1['Longitude'][mid1], r1['Latitude'][mid1], r1, m1, d1, cols)
+            mc2 = extract_and_adjust_mask_columns_for_location(r2['Longitude'][mid2], r2['Latitude'][mid2], r2, m2, d2, cols)
+            matches = match_layers_with_dot_product(mc1, mc2, max_distance=maxd, window_size=wsize, dp_threshold=dpth)
+            print(f"Overlap interval {k+1} — Total Matches: {len(matches)}")
+
+    else:
+        print(f"No crossing coordinates and no GPS overlap found — skipping layer matching.")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="XCheck CLI")
+    parser.add_argument('--r1', type=str, default=None,
+                        help="First radargram filename (single-pair mode).")
+    parser.add_argument('--r2', type=str, default=None,
+                        help="Second radargram filename (single-pair mode).")
+    parser.add_argument('--lat', type=float, default=None,
+                        help="Crossing latitude for single-pair mode (optional if --intersections_csv is given).")
+    parser.add_argument('--lon', type=float, default=None,
+                        help="Crossing longitude for single-pair mode (optional if --intersections_csv is given).")
+    parser.add_argument('--csv_path', type=str, default=None,
+                        help="CSV with radargram pairs. Must include Longitude/Latitude columns unless --intersections_csv is also provided.")
+    parser.add_argument('--intersections_csv', type=str, default=None,
+                        help="Optional CSV with pre-computed intersection coordinates (columns: Radargram 1, Radargram 2, Latitude, Longitude). "
+                             "When provided alone, all pairs in it are processed. When combined with --csv_path, coordinates are looked up here.")
+    parser.add_argument('--layer_dir', type=str, required=True)
+    parser.add_argument('--radar_dir', type=str, required=True)
+    parser.add_argument('--cols_side', type=int, default=None,
+                        help="Columns extracted each side of crossing (default: 20 for consecutive, 3 for non-consecutive).")
+    parser.add_argument('--max_distance', type=int, default=None,
+                        help="Max depth-pixel gap between candidate layer rows (default: 4 consecutive, 3 non-consecutive).")
+    parser.add_argument('--window_size', type=int, default=None,
+                        help="Odd column window width for dot product (default: 7 consecutive, 3 non-consecutive).")
+    parser.add_argument('--dp_threshold', type=float, default=None,
+                        help="Minimum dot product to count as a match (default: 4 consecutive, 1 non-consecutive).")
+    parser.add_argument('--layer_prefix', type=str, default='Layer_',
+                        help="Filename prefix for layer files (default: 'Layer_')")
+    parser.add_argument('--plot_overlaps', action='store_true', help="Plot GPS overlap regions on a map")
+    args = parser.parse_args()
+
+    # --- Single-pair mode ---
+    if args.r1 and args.r2:
+        intersections_df = pd.read_csv(args.intersections_csv) if args.intersections_csv else None
+        lon, lat = args.lon, args.lat
+        if lon is None and intersections_df is not None:
+            result = _lookup_intersection(intersections_df, args.r1, args.r2)
+            if result is not None:
+                lon, lat = result
+        _process_pair(args.r1, args.r2, lon, lat, args)
+        return
+
+    # --- Batch mode ---
+    if args.csv_path is None and args.intersections_csv is None:
+        parser.error("Provide --r1/--r2 for a single pair, or --csv_path/--intersections_csv for batch mode.")
+
+    intersections_df = pd.read_csv(args.intersections_csv) if args.intersections_csv else None
+    df = pd.read_csv(args.csv_path) if args.csv_path else intersections_df
+
+    for _, row in df.iterrows():
+        file1, file2 = row['Radargram 1'], row['Radargram 2']
+        if intersections_df is not None:
+            result = _lookup_intersection(intersections_df, file1, file2)
+            if result is None:
+                print(f"Skipping {file1} <-> {file2}: no intersection found in --intersections_csv")
+                continue
+            lon, lat = result
+        else:
+            lon, lat = row['Longitude'], row['Latitude']
+        _process_pair(file1, file2, lon, lat, args)
+
+if __name__ == '__main__':
+    main()

xcheck-0.1.0/src/xcheck.egg-info/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: xcheck
+Version: 0.1.0
+Summary: A package for cross-checking radargram layers using dot product similarity.
+Author-email: Your Name <your.email@example.com>
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Requires-Dist: scipy
+Requires-Dist: pandas
+Requires-Dist: cartopy
+
+# XCheck — Consistency-Based Validation of Englacial Layer Annotations
+
+A Python implementation of the radargram layer-matching framework from:
+
+> Hassan, Muhammad Behroze; Tama, Bayu Adhi; Purushotham, Sanjay;
+> Janeja, Vandana P. **XCheck: A Consistency-Based Validation Framework
+> for Englacial Layers Annotations.**
+> <https://par.nsf.gov/biblio/10673248> ·
+> DOI: [10.1109/ICDMW69685.2025.00015](https://doi.org/10.1109/ICDMW69685.2025.00015)
+
+XCheck validates whether annotated englacial layers are *consistent*
+between two radargrams that observe the same ice — either two
+**consecutive** flight segments (overlap found automatically via GPS time)
+or two **intersecting** flight paths (crossing point supplied via a CSV).
+
+---
+
+## Features
+
+- **GPS Overlap Detection**: Automatically finds temporally overlapping segments between two radargrams using log-transformed GPS timestamps.
+- **Data Loading & Masking**: Loads `.mat` radargram and ground truth layer files and converts annotated layers into binary depth masks.
+- **Geometric Alignment**: Adjusts radargram columns by surface elevation before comparison to correct for topographic variation.
+- **Layer Continuity Matching**: Dot-product similarity algorithm that identifies corresponding layers between two radargrams at their crossing or overlap point.
+- **Flexible Input**: Accepts a single radargram pair via CLI flags, a batch CSV of pairs, or a pre-computed intersections CSV.
+- **Visualization**: Map plots of GPS overlap regions and side-by-side mask views with matched layer annotations.
+
+---
+
+## Installation
+
+```bash
+pip install xcheck
+```
+
+### NDH_PythonTools (required)
+
+XCheck uses [NDH_PythonTools](https://github.com/nholschuh/NDH_PythonTools)
+for `.mat` file loading and radar data processing. Because that repository
+is not a standard pip package, it must be installed manually:
+
+```bash
+git clone https://github.com/nholschuh/NDH_PythonTools.git
+```
+
+Then add its **parent directory** to `PYTHONPATH` before running xcheck:
+
+```bash
+# Linux / macOS
+export PYTHONPATH="/path/to/parent/of/NDH_PythonTools"
+
+# Windows PowerShell
+$env:PYTHONPATH = "C:\path\to\parent\of\NDH_PythonTools"
+```
+
+---
+
+## Quick Start
+
+### Layer matching only (no NDH_PythonTools needed)
+
+```python
+import numpy as np
+from xcheck import match_layers_with_dot_product
+
+m1 = np.zeros((6, 5)); m1[[1, 3, 5], :] = 1
+m2 = np.zeros((6, 5)); m2[[1, 3, 5], :] = 1
+
+matches = match_layers_with_dot_product(m1, m2, max_distance=1,
+                                        window_size=3, dp_threshold=1)
+print(matches)  # [(1, 1), (3, 3), (5, 5)]
+```
+
+### Python API (requires NDH_PythonTools + data)
+
+```python
+from xcheck import (
+    load_and_process_radargram,
+    load_log_gps_time,
+    find_overlapping_intervals,
+    extract_and_adjust_mask_columns_for_location,
+    match_layers_with_dot_product,
+)
+
+# Load two consecutive radargrams
+r1, m1, d1 = load_and_process_radargram("Data_20120429_01_026.mat",
+                                         layer_dir="./Nick-layer-data-mat/",
+                                         radar_dir="./Nick-raw-radargram-mat/")
+r2, m2, d2 = load_and_process_radargram("Data_20120429_01_027.mat",
+                                         layer_dir="./Nick-layer-data-mat/",
+                                         radar_dir="./Nick-raw-radargram-mat/")
+
+# Find GPS overlap and derive crossing point from midpoint
+import numpy as np
+log_t1 = load_log_gps_time("./Nick-raw-radargram-mat/Data_20120429_01_026.mat")
+log_t2 = load_log_gps_time("./Nick-raw-radargram-mat/Data_20120429_01_027.mat")
+overlaps1, overlaps2 = find_overlapping_intervals(log_t1, log_t2)
+
+for iv1, iv2 in zip(overlaps1, overlaps2):
+    mid1 = (iv1[0] + iv1[1]) // 2
+    mid2 = (iv2[0] + iv2[1]) // 2
+    mc1 = extract_and_adjust_mask_columns_for_location(
+        r1['Longitude'][mid1], r1['Latitude'][mid1], r1, m1, d1, 20)
+    mc2 = extract_and_adjust_mask_columns_for_location(
+        r2['Longitude'][mid2], r2['Latitude'][mid2], r2, m2, d2, 20)
+    matches = match_layers_with_dot_product(mc1, mc2)
+    print(f"Matched layers: {matches}")
+```
+
+---
+
+## CLI
+
+### Single pair — consecutive (no crossing CSV needed)
+
+```bash
+xcheck --r1 Data_20120429_01_026.mat --r2 Data_20120429_01_027.mat \
+       --layer_dir ./Nick-layer-data-mat/ \
+       --radar_dir ./Nick-raw-radargram-mat/
+```
+
+### Single pair — intersecting (crossing looked up from CSV)
+
+```bash
+xcheck --r1 Data_20120330_01_004.mat --r2 Data_20120511_01_054.mat \
+       --intersections_csv ./Intersections_2012.csv \
+       --layer_dir ./Nick-layer-data-mat/ \
+       --radar_dir ./Nick-raw-radargram-mat/
+```
+
+### Single pair — intersecting with explicit crossing coordinates
+
+```bash
+xcheck --r1 Data_20120330_01_004.mat --r2 Data_20120511_01_054.mat \
+       --lat 78.909416 --lon -61.804612 \
+       --layer_dir ./Nick-layer-data-mat/ \
+       --radar_dir ./Nick-raw-radargram-mat/
+```
+
+### Batch mode (all pairs in a CSV)
+
+```bash
+xcheck --intersections_csv ./Intersections_2012.csv \
+       --layer_dir ./Nick-layer-data-mat/ \
+       --radar_dir ./Nick-raw-radargram-mat/
+```
+
+### All CLI arguments
+
+| Argument | Default | Description |
+|---|---|---|
+| `--r1`, `--r2` | — | Single-pair mode: filenames of the two radargrams |
+| `--lat`, `--lon` | — | Crossing coordinates for single-pair mode |
+| `--csv_path` | — | Batch CSV with columns `Radargram 1`, `Radargram 2`, `Latitude`, `Longitude` |
+| `--intersections_csv` | — | Pre-computed intersections CSV (used alone or to look up coordinates) |
+| `--layer_dir` | required | Directory of layer `.mat` files |
+| `--radar_dir` | required | Directory of raw radargram `.mat` files |
+| `--layer_prefix` | `Layer_` | Filename prefix for layer files |
+| `--cols_side` | 20 / 3 | Columns extracted each side of crossing (consecutive / non-consecutive) |
+| `--max_distance` | 4 / 3 | Max depth-pixel gap between candidate layer rows |
+| `--window_size` | 7 / 3 | Dot product window width (must be odd) |
+| `--dp_threshold` | 4 / 1 | Minimum dot product score to confirm a match |
+| `--plot_overlaps` | off | Plot GPS overlap regions on a map |
+
+Default pairs shown as **consecutive / non-consecutive**.
+
+---
+
+## Default thresholds by radargram type
+
+| Parameter | Consecutive | Non-consecutive |
+|---|---|---|
+| `cols_side` | 20 (41 columns) | 3 (7 columns) |
+| `max_distance` | 4 px | 3 px |
+| `window_size` | 7 | 3 |
+| `dp_threshold` | 4 | 1 |
+
+These are selected automatically. Override any of them via CLI flags.
+
+---
+
+## Methodological note
+
+The GPS overlap detection compares **`log(GPS_time)`** between two
+radargrams with an absolute tolerance of `1e-8`. Because
+`d(log t) ≈ dt/t` and GPS times are ~1×10⁹ seconds, this tolerance
+corresponds to matching raw timestamps within roughly 10 seconds.
+Consecutive flight segments (e.g. `_026.mat` → `_027.mat`) share a
+small tail/head of overlapping traces, which is where the crossing point
+is derived. Non-consecutive intersecting radargrams do not share GPS
+timestamps; their crossing point must be supplied via `--intersections_csv`
+or `--lat`/`--lon`.
+
+---
+
+## Project structure
+
+```
+src/xcheck/
+  xcheck.py      Core algorithms: loading, masking, GPS overlap,
+                 column extraction, layer matching, plotting, CLI
+  __init__.py    Public API exports
+pyproject.toml   Build metadata and dependencies
+README.md
+```
+
+---
+
+## License
+
+MIT

xcheck-0.1.0/src/xcheck.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+setup.py
+src/xcheck/__init__.py
+src/xcheck/xcheck.py
+src/xcheck.egg-info/PKG-INFO
+src/xcheck.egg-info/SOURCES.txt
+src/xcheck.egg-info/dependency_links.txt
+src/xcheck.egg-info/entry_points.txt
+src/xcheck.egg-info/requires.txt
+src/xcheck.egg-info/top_level.txt

xcheck-0.1.0/src/xcheck.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

xcheck-0.1.0/src/xcheck.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+xcheck = xcheck.xcheck:main

xcheck-0.1.0/src/xcheck.egg-info/requires.txt

@@ -0,0 +1,5 @@
+numpy
+matplotlib
+scipy
+pandas
+cartopy

xcheck-0.1.0/src/xcheck.egg-info/top_level.txt

@@ -0,0 +1 @@
+xcheck