gnsskit 0.4.0__py3-none-any.whl

gnsskit/__init__.py

@@ -0,0 +1,76 @@
+"""Shared RTKLIB-based GNSS post-processing tools."""
+
+from importlib.metadata import version
+
+from .kinematic import interpolate
+from .refsys import (
+    GPS_EPOCH,
+    GPST_UTC_OFFSET_S,
+    GRS80,
+    WGS84,
+    Ellipsoid,
+    ENUFrame,
+    enu_diff,
+    gpst_to_local,
+    utc_to_gpst,
+)
+from .rinex import (
+    find_rinex_obs,
+    header_llh,
+    obs_summary,
+    plot_visibility,
+    read_visibility,
+    rinex_span,
+    satellite_stats,
+    signal_stats,
+    trim_rinex,
+)
+from .rtklib import (
+    RtkConfig,
+    navsys_mask,
+    read_header,
+    read_pos,
+    read_ref_pos,
+    run_rnx2rtkp,
+)
+from .static import (
+    baselines_to_df,
+    df_to_baselines,
+    loop_closures,
+    process_baseline,
+    solve_static,
+)
+
+__version__ = version("gnsskit")
+__all__ = [
+    "GPST_UTC_OFFSET_S",
+    "GPS_EPOCH",
+    "GRS80",
+    "WGS84",
+    "ENUFrame",
+    "Ellipsoid",
+    "RtkConfig",
+    "baselines_to_df",
+    "df_to_baselines",
+    "enu_diff",
+    "find_rinex_obs",
+    "gpst_to_local",
+    "header_llh",
+    "interpolate",
+    "loop_closures",
+    "navsys_mask",
+    "obs_summary",
+    "plot_visibility",
+    "process_baseline",
+    "read_header",
+    "read_pos",
+    "read_ref_pos",
+    "read_visibility",
+    "rinex_span",
+    "run_rnx2rtkp",
+    "satellite_stats",
+    "signal_stats",
+    "solve_static",
+    "trim_rinex",
+    "utc_to_gpst",
+]

gnsskit/kinematic/__init__.py

@@ -0,0 +1,5 @@
+"""Kinematic processing: interpolation and averaging of trajectories from .pos solutions."""
+
+from .trajectory import average, interpolate
+
+__all__ = ["average", "interpolate"]

gnsskit/kinematic/trajectory.py

@@ -0,0 +1,84 @@
+"""Sampling a kinematic trajectory (`read_pos` output): at given times or inside windows."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from ..refsys import GPS_EPOCH, enu_diff
+from ..rtklib.pos import POS_COORD_COLS, POS_SD_COLS
+
+
+def interpolate(pos: pd.DataFrame, gps_s: np.ndarray) -> pd.DataFrame:
+    """Linear interpolation of the trajectory at the given times.
+
+    Q is the worse of the two neighbouring epochs, ns the smaller. Times outside the
+    trajectory are not allowed.
+
+    Args:
+        pos: Trajectory from `read_pos`, with at least two epochs.
+        gps_s: Times to interpolate at, seconds since the GPS epoch.
+
+    Returns:
+        DataFrame in the format of `pos`, one row per requested time.
+    """
+    fmt = pos.attrs["format"]
+    t = pos["gps_s"].to_numpy()
+    idx = np.searchsorted(t, gps_s).clip(1, len(pos) - 1)
+    lo, hi = idx - 1, idx
+    q, ratio = pos["Q"].to_numpy(), pos["ratio"].to_numpy()
+    cols = POS_COORD_COLS[fmt] + POS_SD_COLS[fmt]
+    out = pd.DataFrame({c: np.interp(gps_s, t, pos[c]) for c in cols})
+    out["Q"] = np.maximum(q[lo], q[hi])
+    out["ns"] = np.minimum(pos["ns"].to_numpy()[lo], pos["ns"].to_numpy()[hi])
+    out["ratio"] = np.where(q[lo] == 1, ratio[lo], ratio[hi])
+    out["age"] = 0.0
+    out["gps_s"] = gps_s
+    out["t"] = GPS_EPOCH + pd.to_timedelta(gps_s, unit="s")
+    out.attrs["format"] = fmt
+    return out
+
+
+def average(
+    pos: pd.DataFrame, start: pd.Timestamp, end: pd.Timestamp, fix_only: bool = True
+) -> dict[str, float | int | bool]:
+    """Mean position of the llh epochs in [start, end] with the scatter in E, N, U.
+
+    Args:
+        pos: llh trajectory from `read_pos`.
+        start: Window start, GPST.
+        end: Window end, GPST.
+        fix_only: Average the fixed epochs (Q == 1) only.
+
+    Returns:
+        Dict with n_epochs, fix_pct, n_used and, if any epoch is used, fixed, lat, lon, h
+        [deg, deg, m] and sd_e, sd_n, sd_u [m] (sample standard deviations).
+
+    Raises:
+        ValueError: If `pos` is not in llh format.
+    """
+    if pos.attrs.get("format") != "llh":
+        raise ValueError("average needs a llh trajectory (out-solformat=llh)")
+    seg = pos[(pos.t >= start) & (pos.t <= end)]
+    n_all = len(seg)
+    row: dict[str, float | int | bool] = {
+        "n_epochs": n_all,
+        "fix_pct": 100.0 * (seg.Q == 1).sum() / n_all if n_all else 0.0,
+    }
+    if fix_only:
+        seg = seg[seg.Q == 1]
+    row["n_used"] = len(seg)
+    if len(seg):
+        lat, lon, h = seg.lat.mean(), seg.lon.mean(), seg.h.mean()
+        e, n, u = enu_diff(seg.lat, seg.lon, seg.h, lat, lon, h).T
+        ddof = 1 if len(seg) > 1 else 0
+        row |= {
+            "fixed": bool((seg.Q == 1).all()),
+            "lat": lat,
+            "lon": lon,
+            "h": h,
+            "sd_e": e.std(ddof=ddof),
+            "sd_n": n.std(ddof=ddof),
+            "sd_u": u.std(ddof=ddof),
+        }
+    return row

gnsskit/ppp/__init__.py

@@ -0,0 +1,16 @@
+"""Precise Point Positioning (PPP) with RTKLIB. Placeholder: nothing is implemented yet.
+
+Planned scope:
+    - single-receiver static and kinematic solutions with rnx2rtkp (`posmode` "ppp-static",
+      "ppp-kine" or "ppp-fixed"), reusing `gnsskit.rtklib` for configuration, running and
+      reading the .pos output;
+    - helpers for the precise products PPP needs: SP3 orbits, CLK clocks, ANTEX antenna
+      models (satellite and receiver), and optionally DCB/OSB biases and ocean loading;
+    - a PPP preset of `RtkConfig` (dual-frequency iono-free, `sateph="precise"`,
+      `tropopt="est-ztd"`).
+
+To do before the first function:
+    - add "ppp-kine", "ppp-static" and "ppp-fixed" to `PosMode` in `gnsskit.rtklib.config`.
+"""
+
+__all__: list[str] = []

gnsskit/refsys.py

@@ -0,0 +1,308 @@
+"""Reference systems: time (GPST, UTC) and space (ellipsoid, ECEF, geodetic, local ENU).
+
+The default ellipsoid is GRS80, the ellipsoid of ITRS, ETRS89/ETRF2000 and the Italian
+RDN2008. WGS84 has the same semi-major axis and a flattening that differs in the 11th digit:
+the two give the same coordinates to about 0.1 mm.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import cached_property
+from typing import TypeVar
+
+import numpy as np
+import numpy.typing as npt
+import pandas as pd
+
+# =============================================================================
+# Time systems (GPST, UTC)
+# =============================================================================
+
+GPS_EPOCH = pd.Timestamp("1980-01-06")
+GPST_UTC_OFFSET_S = 18  # GPST - UTC leap seconds (valid since 2017)
+
+T = TypeVar("T", pd.Timestamp, pd.Series)
+
+
+def utc_to_gpst(t: T, leap_s: int = GPST_UTC_OFFSET_S) -> T:
+    """Shift UTC time(s) to GPST.
+
+    Args:
+        t: Timestamp or Series of UTC times.
+        leap_s: GPST - UTC [s].
+
+    Returns:
+        The shifted time(s), same type as `t`.
+    """
+    return t + pd.Timedelta(seconds=leap_s)
+
+
+def gpst_to_local(t: T, tz: str = "Europe/Rome", leap_s: int = GPST_UTC_OFFSET_S) -> T:
+    """Convert GPST time(s) to local civil time, with daylight saving time.
+
+    Args:
+        t: Timestamp or Series of GPST times (naive).
+        tz: IANA time zone of the result.
+        leap_s: GPST - UTC [s].
+
+    Returns:
+        The local time(s) as naive datetimes, same type as `t`.
+    """
+    utc = t - pd.Timedelta(seconds=leap_s)
+    if isinstance(utc, pd.Series):
+        return utc.dt.tz_localize("UTC").dt.tz_convert(tz).dt.tz_localize(None)
+    return utc.tz_localize("UTC").tz_convert(tz).tz_localize(None)
+
+
+def gps_seconds(t: pd.Timestamp | pd.Series) -> float | pd.Series:
+    """Seconds since the GPS epoch (1980-01-06), which avoids week roll-over problems.
+
+    Args:
+        t: Timestamp or Series of GPST times.
+
+    Returns:
+        Seconds as a float, or a Series of floats.
+    """
+    return (t - GPS_EPOCH) / pd.Timedelta(seconds=1)
+
+
+# =============================================================================
+# Reference ellipsoids
+# =============================================================================
+
+
+@dataclass(frozen=True)
+class Ellipsoid:
+    """Reference ellipsoid of revolution."""
+
+    a: float  # semi-major axis [m]
+    inv_f: float  # inverse flattening
+
+    @property
+    def e2(self) -> float:
+        """First eccentricity squared."""
+        f = 1 / self.inv_f
+        return f * (2 - f)
+
+
+GRS80 = Ellipsoid(6378137.0, 298.257222101)
+WGS84 = Ellipsoid(6378137.0, 298.257223563)
+
+ArrayLike = float | np.ndarray | pd.Series
+
+
+# =============================================================================
+# Global coordinates: geodetic <-> ECEF
+# =============================================================================
+
+
+def llh_to_ecef(
+    lat: ArrayLike, lon: ArrayLike, h: ArrayLike, ellipsoid: Ellipsoid = GRS80
+) -> np.ndarray:
+    """ECEF coordinates from geodetic coordinates.
+
+    Args:
+        lat: Latitude [deg].
+        lon: Longitude [deg].
+        h: Ellipsoidal height [m].
+        ellipsoid: Reference ellipsoid.
+
+    Returns:
+        Array of shape (..., 3) with X, Y, Z [m].
+    """
+    a, e2 = ellipsoid.a, ellipsoid.e2
+    phi, lam = np.radians(np.asarray(lat, float)), np.radians(np.asarray(lon, float))
+    n = a / np.sqrt(1 - e2 * np.sin(phi) ** 2)
+    h = np.asarray(h, float)
+    return np.stack(
+        [
+            (n + h) * np.cos(phi) * np.cos(lam),
+            (n + h) * np.cos(phi) * np.sin(lam),
+            (n * (1 - e2) + h) * np.sin(phi),
+        ],
+        axis=-1,
+    )
+
+
+def ecef_to_llh(
+    x: ArrayLike, y: ArrayLike, z: ArrayLike, ellipsoid: Ellipsoid = GRS80
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Geodetic coordinates from ECEF coordinates.
+
+    Args:
+        x: ECEF X [m].
+        y: ECEF Y [m].
+        z: ECEF Z [m].
+        ellipsoid: Reference ellipsoid.
+
+    Returns:
+        (lat [deg], lon [deg], ellipsoidal height [m]).
+    """
+    a, e2 = ellipsoid.a, ellipsoid.e2
+    x, y, z = (np.asarray(v, float) for v in (x, y, z))
+    p = np.hypot(x, y)
+    lat = np.arctan2(z, p * (1 - e2))
+    for _ in range(10):  # fixed-point iteration, converges to sub-mm in a few steps
+        n = a / np.sqrt(1 - e2 * np.sin(lat) ** 2)
+        h = p / np.cos(lat) - n
+        lat = np.arctan2(z, p * (1 - e2 * n / (n + h)))
+    return np.degrees(lat), np.degrees(np.arctan2(y, x)), h
+
+
+# =============================================================================
+# Local frames: ENU rotation, ENU frame and small-difference offsets
+# =============================================================================
+
+
+def ecef_to_enu_matrix(lat: float, lon: float) -> np.ndarray:
+    """Rotation matrix from ECEF to local east-north-up.
+
+    Args:
+        lat: Latitude of the local origin [deg].
+        lon: Longitude of the local origin [deg].
+
+    Returns:
+        (3, 3) matrix R, with enu = R @ (ecef difference).
+    """
+    phi, lam = np.radians(lat), np.radians(lon)
+    return np.array(
+        [
+            [-np.sin(lam), np.cos(lam), 0.0],
+            [-np.sin(phi) * np.cos(lam), -np.sin(phi) * np.sin(lam), np.cos(phi)],
+            [np.cos(phi) * np.cos(lam), np.cos(phi) * np.sin(lam), np.sin(phi)],
+        ]
+    )
+
+
+@dataclass(frozen=True, eq=False)
+class ENUFrame:
+    """Local east-north-up frame with origin at a point, tangent to the ellipsoid there.
+
+    Points are shifted to the origin and rotated; vectors (baselines) and covariance matrices
+    are only rotated: enu = R (xyz - origin), denu = R dxyz, C_enu = R C_xyz R^T.
+    Methods take one (3,) array or a stack (n, 3); covariances (3, 3) or (n, 3, 3).
+    The axes are east, north and up of the tangent plane at the origin: for points far
+    from it, "up" is not their local vertical (the two differ by about d / 6371 km rad).
+    """
+
+    origin: np.ndarray  # (3,) ECEF of the origin [m]
+    ellipsoid: Ellipsoid = GRS80
+
+    @classmethod
+    def from_ecef(cls, xyz: npt.ArrayLike, ellipsoid: Ellipsoid = GRS80) -> ENUFrame:
+        """Frame with origin at an ECEF point [m]."""
+        return cls(np.asarray(xyz, float).reshape(3), ellipsoid)
+
+    @classmethod
+    def from_llh(cls, lat: float, lon: float, h: float, ellipsoid: Ellipsoid = GRS80) -> ENUFrame:
+        """Frame with origin at a geodetic point (lat, lon [deg], ellipsoidal h [m])."""
+        return cls(llh_to_ecef(lat, lon, h, ellipsoid), ellipsoid)
+
+    @cached_property
+    def llh(self) -> tuple[float, float, float]:
+        """Geodetic coordinates of the origin: lat, lon [deg], h [m]."""
+        x, y, z = self.origin
+        lat, lon, h = ecef_to_llh(x, y, z, self.ellipsoid)
+        return float(lat), float(lon), float(h)
+
+    @cached_property
+    def rotation(self) -> np.ndarray:
+        """(3, 3) rotation R from ECEF to ENU; its inverse is R^T."""
+        lat, lon, _ = self.llh
+        return ecef_to_enu_matrix(lat, lon)
+
+    # --- points: shift to the origin and rotate ---------------------------------
+
+    def to_enu(self, xyz: npt.ArrayLike) -> np.ndarray:
+        """ENU coordinates [m] of ECEF points [m]."""
+        return self.vector_to_enu(np.asarray(xyz, float) - self.origin)
+
+    def to_ecef(self, enu: npt.ArrayLike) -> np.ndarray:
+        """ECEF coordinates [m] of ENU points [m]."""
+        return self.origin + self.vector_to_ecef(enu)
+
+    def llh_to_enu(self, lat: ArrayLike, lon: ArrayLike, h: ArrayLike) -> np.ndarray:
+        """ENU coordinates [m] of geodetic points (lat, lon [deg], h [m])."""
+        return self.to_enu(llh_to_ecef(lat, lon, h, self.ellipsoid))
+
+    def enu_to_llh(self, enu: npt.ArrayLike) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+        """Geodetic coordinates (lat, lon [deg], h [m]) of ENU points [m]."""
+        xyz = self.to_ecef(enu)
+        return ecef_to_llh(xyz[..., 0], xyz[..., 1], xyz[..., 2], self.ellipsoid)
+
+    # --- vectors and covariances: rotation only ---------------------------------
+
+    def vector_to_enu(self, dxyz: npt.ArrayLike) -> np.ndarray:
+        """ENU components of ECEF vectors (e.g. baselines)."""
+        return np.asarray(dxyz, float) @ self.rotation.T
+
+    def vector_to_ecef(self, denu: npt.ArrayLike) -> np.ndarray:
+        """ECEF components of ENU vectors."""
+        return np.asarray(denu, float) @ self.rotation
+
+    def cov_to_enu(self, cov: npt.ArrayLike) -> np.ndarray:
+        """ENU covariances R C R^T of ECEF covariances."""
+        r = self.rotation
+        return r @ np.asarray(cov, float) @ r.T
+
+    def cov_to_ecef(self, cov: npt.ArrayLike) -> np.ndarray:
+        """ECEF covariances R^T C R of ENU covariances."""
+        r = self.rotation
+        return r.T @ np.asarray(cov, float) @ r
+
+
+def radii(
+    lat_deg: ArrayLike, h: ArrayLike, ellipsoid: Ellipsoid = GRS80
+) -> tuple[np.ndarray, np.ndarray]:
+    """Meridian and prime-vertical radii plus height: (Rm + h, (Rn + h) cos(lat)).
+
+    Multiplying them by a latitude / longitude difference in radians gives metres.
+
+    Args:
+        lat_deg: Latitude [deg].
+        h: Ellipsoidal height [m].
+        ellipsoid: Reference ellipsoid.
+
+    Returns:
+        (Rm + h, (Rn + h) cos(lat)) [m].
+    """
+    phi = np.radians(np.asarray(lat_deg, dtype=float))
+    a, e2 = ellipsoid.a, ellipsoid.e2
+    w = np.sqrt(1 - e2 * np.sin(phi) ** 2)
+    h = np.asarray(h, dtype=float)
+    return a * (1 - e2) / w**3 + h, (a / w + h) * np.cos(phi)
+
+
+def enu_diff(
+    lat: ArrayLike,
+    lon: ArrayLike,
+    h: ArrayLike,
+    lat0: ArrayLike,
+    lon0: ArrayLike,
+    h0: ArrayLike,
+    ellipsoid: Ellipsoid = GRS80,
+) -> np.ndarray:
+    """(E, N, U) offsets of points from reference points, by small-difference approximation.
+
+    Each point gets its own reference point (vectorised), e.g. epochs vs their mean. The
+    error grows as d^2 / (2 R): < 0.01 mm at 10 m, 0.8 mm at 100 m, 8 cm at 1 km. For
+    longer offsets use `ENUFrame`, which is exact.
+
+    Args:
+        lat: Latitude of the points [deg].
+        lon: Longitude of the points [deg].
+        h: Ellipsoidal height of the points [m].
+        lat0: Latitude of the reference points [deg].
+        lon0: Longitude of the reference points [deg].
+        h0: Ellipsoidal height of the reference points [m].
+        ellipsoid: Reference ellipsoid.
+
+    Returns:
+        Array of shape (n, 3) with E, N, U [m].
+    """
+    rm, rn = radii(lat0, h0, ellipsoid)
+    e = np.radians(np.asarray(lon, dtype=float) - np.asarray(lon0, dtype=float)) * rn
+    n = np.radians(np.asarray(lat, dtype=float) - np.asarray(lat0, dtype=float)) * rm
+    u = np.asarray(h, dtype=float) - np.asarray(h0, dtype=float)
+    return np.column_stack([e, n, u])