stk-files 0.0.2__py3-none-any.whl

stk_files/__init__.py

@@ -0,0 +1,77 @@
+from stk_files._gaps import detect_availability, write_availability
+from stk_files._parser import STKParseError
+from stk_files._types import (
+    AttitudeFormat,
+    AzElSequence,
+    CentralBody,
+    CoordinateAxes,
+    EphemerisFormat,
+    EulerSequence,
+    InterpolationMethod,
+    MessageLevel,
+    RotationSequence,
+    SensorFormat,
+    TimeFormat,
+    YPRSequence,
+)
+from stk_files._version import __version__
+from stk_files.attitude import (
+    AttitudeChunkWriter,
+    AttitudeConfig,
+    attitude_writer,
+    read_attitude,
+    write_attitude,
+)
+from stk_files.ephemeris import (
+    EphemerisChunkWriter,
+    EphemerisConfig,
+    ephemeris_writer,
+    read_ephemeris,
+    write_ephemeris,
+)
+from stk_files.interval import Interval, IntervalConfig, read_interval, write_interval
+from stk_files.sensor import (
+    SensorChunkWriter,
+    SensorConfig,
+    read_sensor,
+    sensor_writer,
+    write_sensor,
+)
+
+__all__ = [
+    "AttitudeChunkWriter",
+    "AttitudeConfig",
+    "AttitudeFormat",
+    "AzElSequence",
+    "CentralBody",
+    "CoordinateAxes",
+    "EphemerisChunkWriter",
+    "EphemerisConfig",
+    "EphemerisFormat",
+    "EulerSequence",
+    "InterpolationMethod",
+    "Interval",
+    "IntervalConfig",
+    "MessageLevel",
+    "RotationSequence",
+    "STKParseError",
+    "SensorChunkWriter",
+    "SensorConfig",
+    "SensorFormat",
+    "TimeFormat",
+    "YPRSequence",
+    "__version__",
+    "attitude_writer",
+    "detect_availability",
+    "ephemeris_writer",
+    "read_attitude",
+    "read_ephemeris",
+    "read_interval",
+    "read_sensor",
+    "sensor_writer",
+    "write_attitude",
+    "write_availability",
+    "write_ephemeris",
+    "write_interval",
+    "write_sensor",
+]

stk_files/__main__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from stk_files.cli import main
+
+main()

stk_files/_coerce.py

@@ -0,0 +1,106 @@
+"""Runtime coercion of pandas/polars types to numpy arrays.
+
+Both pandas and polars are optional dependencies. This module uses
+``isinstance`` checks with cached lazy imports so that users who only
+work with numpy never pay for the import cost.
+"""
+
+from __future__ import annotations
+
+import functools
+from typing import Any
+
+import numpy as np
+
+
+@functools.lru_cache(maxsize=1)
+def _pandas_types() -> tuple[Any, Any]:
+    try:
+        import pandas as pd
+
+        return pd.Series, pd.DataFrame
+    except ImportError:  # pragma: no cover
+        return None, None
+
+
+@functools.lru_cache(maxsize=1)
+def _polars_types() -> tuple[Any, Any]:
+    try:
+        import polars as pl
+
+        return pl.Series, pl.DataFrame
+    except ImportError:  # pragma: no cover
+        return None, None
+
+
+def _is_pandas_series(obj: Any) -> bool:
+    cls, _ = _pandas_types()
+    return cls is not None and isinstance(obj, cls)
+
+
+def _is_pandas_dataframe(obj: Any) -> bool:
+    _, cls = _pandas_types()
+    return cls is not None and isinstance(obj, cls)
+
+
+def _is_polars_series(obj: Any) -> bool:
+    cls, _ = _polars_types()
+    return cls is not None and isinstance(obj, cls)
+
+
+def _is_polars_dataframe(obj: Any) -> bool:
+    _, cls = _polars_types()
+    return cls is not None and isinstance(obj, cls)
+
+
+def coerce_times(times: Any) -> Any:
+    """Convert *times* to a numpy datetime64 array.
+
+    Accepted inputs:
+    - ``numpy.ndarray`` of ``datetime64`` — returned as-is
+    - ``pandas.Series`` of datetime — converted via ``.to_numpy(dtype="datetime64[ms]")``
+    - ``polars.Series`` of Datetime/Date — converted via ``.to_numpy()`` then cast
+    """
+    if isinstance(times, np.ndarray):
+        return times
+
+    if _is_pandas_series(times):
+        return times.to_numpy(dtype="datetime64[ms]")
+
+    if _is_polars_series(times):
+        arr = times.to_numpy()
+        if not np.issubdtype(arr.dtype, np.datetime64):
+            arr = arr.astype("datetime64[ms]")
+        return arr
+
+    # Fall through — let numpy try to coerce it
+    return np.asarray(times, dtype="datetime64[ms]")
+
+
+def coerce_data(data: Any) -> Any:
+    """Convert *data* to a 2-D numpy floating-point array.
+
+    Accepted inputs:
+    - ``numpy.ndarray`` — returned as-is
+    - ``pandas.DataFrame`` — converted via ``.to_numpy(dtype=float)``
+    - ``pandas.Series`` — converted via ``.to_numpy(dtype=float)`` then reshaped to column
+    - ``polars.DataFrame`` — converted via ``.to_numpy()`` then cast
+    - ``polars.Series`` — converted via ``.to_numpy()`` then reshaped to column
+    """
+    if isinstance(data, np.ndarray):
+        return data
+
+    if _is_pandas_dataframe(data):
+        return data.to_numpy(dtype=float)
+
+    if _is_pandas_series(data):
+        return data.to_numpy(dtype=float).reshape(-1, 1)
+
+    if _is_polars_dataframe(data):
+        return data.to_numpy().astype(float)
+
+    if _is_polars_series(data):
+        return data.to_numpy().astype(float).reshape(-1, 1)
+
+    # Fall through — let numpy try
+    return np.asarray(data, dtype=float)

stk_files/_formatting.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from stk_files._types import QUATERNION_FORMATS
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+
+# ---------------------------------------------------------------------------
+# Scalar formatters (kept for single-value use in headers, etc.)
+# ---------------------------------------------------------------------------
+
+
+def format_iso_ymd(time: np.datetime64) -> str:
+    """Format as 'YYYY-MM-DDTHH:MM:SS.sss' (23 chars)."""
+    return str(time.astype("datetime64[ms]"))[:23]
+
+
+def format_ep_sec(time: np.datetime64, epoch: np.datetime64) -> str:
+    """Format as epoch seconds with 15.3f width."""
+    dt_ms = (time - epoch) / np.timedelta64(1, "ms")  # type: ignore[operator]
+    return f"{float(dt_ms) / 1e3:15.3f}"
+
+
+def format_quaternion_row(row: np.ndarray) -> str:
+    """Format 4 quaternion components with {:+12.9f}."""
+    return " ".join(f"{float(v):+12.9f}" for v in row)
+
+
+def format_generic_row(row: np.ndarray) -> str:
+    """Format numeric values with {:12f}."""
+    return " ".join(f"{float(v):12f}" for v in row)
+
+
+# ---------------------------------------------------------------------------
+# Vectorized bulk formatters
+# ---------------------------------------------------------------------------
+
+
+def format_iso_ymd_array(times: NDArray[np.datetime64]) -> list[str]:
+    """Vectorized ISO-YMD formatting for an entire array of times."""
+    ms_times = times.astype("datetime64[ms]")
+    return [s[:23] for s in np.datetime_as_string(ms_times, unit="ms").tolist()]
+
+
+def format_ep_sec_array(
+    times: NDArray[np.datetime64],
+    epoch: np.datetime64,
+) -> list[str]:
+    """Vectorized epoch-seconds formatting for an entire array of times."""
+    ms = (times - epoch) / np.timedelta64(1, "ms")
+    return [f"{float(v) / 1e3:15.3f}" for v in ms]
+
+
+def format_quaternion_block(data: NDArray[np.floating]) -> list[str]:
+    """Vectorized quaternion formatting for an entire data array."""
+    cols = [np.char.mod("%+12.9f", data[:, i]) for i in range(data.shape[1])]
+    result = cols[0]
+    for c in cols[1:]:
+        result = np.char.add(np.char.add(result, " "), c)
+    return result.tolist()  # type: ignore[no-any-return]
+
+
+def format_generic_block(data: NDArray[np.floating]) -> list[str]:
+    """Vectorized generic formatting for an entire data array."""
+    cols = [np.char.mod("%12f", data[:, i]) for i in range(data.shape[1])]
+    result = cols[0]
+    for c in cols[1:]:
+        result = np.char.add(np.char.add(result, " "), c)
+    return result.tolist()  # type: ignore[no-any-return]
+
+
+# ---------------------------------------------------------------------------
+# Shared high-level formatters (used by all writer modules)
+# ---------------------------------------------------------------------------
+
+
+def format_times(
+    time_format: str,
+    times: NDArray[np.datetime64],
+    scenario_epoch: np.datetime64 | None = None,
+) -> list[str]:
+    """Format a time array based on the time format setting."""
+    if time_format == "EpSec":
+        if scenario_epoch is None:
+            raise ValueError("EpSec time format requires scenario_epoch")
+        return format_ep_sec_array(times, scenario_epoch)
+    return format_iso_ymd_array(times)
+
+
+def format_data_block(fmt: str, data: NDArray[np.floating]) -> list[str]:
+    """Format a data array using quaternion or generic formatting."""
+    if fmt in QUATERNION_FORMATS:
+        return format_quaternion_block(data)
+    return format_generic_block(data)

stk_files/_gaps.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, TextIO
+
+import numpy as np
+
+from stk_files.interval import Interval, write_interval
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+
+def detect_availability(
+    times: NDArray[np.datetime64],
+    max_gap: np.timedelta64,
+    min_points: int = 2,
+) -> list[tuple[np.datetime64, np.datetime64]]:
+    """Identify contiguous data spans from a sorted time array.
+
+    Returns a list of (start, end) tuples. A new span begins whenever
+    the gap between consecutive timestamps exceeds *max_gap*.  Spans
+    with fewer than *min_points* points are excluded (default 2).
+    """
+    if times.size == 0:
+        return []
+
+    if times.size == 1:
+        if min_points <= 1:
+            return [(times[0], times[0])]
+        return []
+
+    gaps = np.diff(times) > max_gap
+    break_indices = np.where(gaps)[0]
+
+    spans: list[tuple[np.datetime64, np.datetime64]] = []
+    start_idx = 0
+    for brk in break_indices:
+        if brk - start_idx + 1 >= min_points:
+            spans.append((times[start_idx], times[brk]))
+        start_idx = brk + 1
+    if len(times) - start_idx >= min_points:
+        spans.append((times[start_idx], times[-1]))
+    return spans
+
+
+def write_availability(
+    stream: TextIO,
+    times: NDArray[np.datetime64],
+    max_gap: np.timedelta64,
+    min_points: int = 2,
+) -> None:
+    """Write an interval file expressing when data is available.
+
+    Should be called on post-filter times so intervals reflect actual
+    valid data coverage.  Spans with fewer than *min_points* points
+    are excluded.
+    """
+    spans = detect_availability(times, max_gap, min_points=min_points)
+    intervals: list[Interval] = [Interval(s, e) for s, e in spans]
+    write_interval(stream, intervals)

stk_files/_parser.py

@@ -0,0 +1,162 @@
+"""Low-level parsing utilities for reading STK external data files."""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+
+class STKParseError(ValueError):
+    """Raised when an STK file cannot be parsed."""
+
+
+def parse_datetime(value: str) -> np.datetime64:
+    """Parse an ISO-YMD datetime string to ``np.datetime64[ms]``."""
+    return np.datetime64(value.strip(), "ms")
+
+
+def parse_header(
+    lines: list[str],
+    sentinel_prefix: str,
+) -> tuple[dict[str, str], str, int]:
+    """Parse an STK file header.
+
+    Returns ``(header_dict, format_string, first_data_line_index)``.
+    The *sentinel_prefix* is ``"AttitudeTime"`` for attitude/sensor files
+    or ``"Ephemeris"`` for ephemeris files.
+    """
+    if not lines:
+        raise STKParseError("empty file")
+
+    if not lines[0].strip().startswith("stk.v."):
+        raise STKParseError(
+            f"line 1: expected 'stk.v.' version header, got {lines[0]!r}"
+        )
+
+    header: dict[str, str] = {}
+    for idx in range(1, len(lines)):
+        stripped = lines[idx].strip()
+        if not stripped:
+            continue
+        if stripped.startswith("BEGIN "):
+            continue
+        if stripped.startswith(sentinel_prefix):
+            fmt = stripped[len(sentinel_prefix) :]
+            return header, fmt, idx + 1
+        parts = stripped.split(None, 1)
+        if len(parts) == 2:
+            header[parts[0]] = parts[1].strip()
+        elif len(parts) == 1:
+            header[parts[0]] = ""
+
+    raise STKParseError(f"no '{sentinel_prefix}*' data sentinel found in header")
+
+
+def parse_data_section(
+    lines: list[str],
+    start: int,
+    time_format: str,
+    expected_cols: int,
+    scenario_epoch: np.datetime64 | None = None,
+) -> tuple[NDArray[np.datetime64], NDArray[np.floating]]:
+    """Parse the data rows of an STK file into numpy arrays.
+
+    Reads from ``lines[start:]`` until a line starting with ``"END"``
+    is encountered.
+    """
+    time_list: list[np.datetime64] = []
+    data_list: list[list[float]] = []
+
+    for idx in range(start, len(lines)):
+        stripped = lines[idx].strip()
+        if not stripped:
+            continue
+        if stripped.startswith("END"):
+            break
+
+        parts = stripped.split()
+        if len(parts) < 1 + expected_cols:
+            raise STKParseError(
+                f"line {idx + 1}: expected {1 + expected_cols} columns, got {len(parts)}"
+            )
+
+        time_str = parts[0]
+        if time_format == "EpSec":
+            if scenario_epoch is None:
+                raise STKParseError("EpSec data requires a ScenarioEpoch")
+            ms = round(float(time_str) * 1000)
+            time_list.append(scenario_epoch + np.timedelta64(ms, "ms"))
+        else:
+            time_list.append(np.datetime64(time_str, "ms"))
+
+        try:
+            data_list.append([float(x) for x in parts[1 : 1 + expected_cols]])
+        except ValueError as exc:
+            raise STKParseError(f"line {idx + 1}: invalid numeric value: {exc}") from None
+
+    if not time_list:
+        return (
+            np.array([], dtype="datetime64[ms]"),
+            np.empty((0, expected_cols), dtype=np.float64),
+        )
+
+    return (
+        np.array(time_list, dtype="datetime64[ms]"),
+        np.array(data_list, dtype=np.float64),
+    )
+
+
+_QUOTED_RE = re.compile(r'"([^"]*)"')
+
+
+def parse_interval_file(
+    lines: list[str],
+) -> list[tuple[np.datetime64, np.datetime64, str]]:
+    """Parse an STK interval list file.
+
+    Returns a list of ``(start, end, data_string)`` tuples.
+    """
+    if not lines:
+        raise STKParseError("empty file")
+
+    if not lines[0].strip().startswith("stk.v."):
+        raise STKParseError(
+            f"line 1: expected 'stk.v.' version header, got {lines[0]!r}"
+        )
+
+    # Find BEGIN Intervals
+    data_start = -1
+    for idx in range(1, len(lines)):
+        if lines[idx].strip() == "BEGIN Intervals":
+            data_start = idx + 1
+            break
+
+    if data_start < 0:
+        raise STKParseError("no 'BEGIN Intervals' found")
+
+    result: list[tuple[np.datetime64, np.datetime64, str]] = []
+    for idx in range(data_start, len(lines)):
+        stripped = lines[idx].strip()
+        if not stripped:
+            continue
+        if stripped.startswith("END"):
+            break
+
+        match_iter = _QUOTED_RE.finditer(stripped)
+        first = next(match_iter, None)
+        second = next(match_iter, None)
+        if first is None or second is None:
+            raise STKParseError(
+                f"line {idx + 1}: expected two quoted timestamps"
+            )
+        start = np.datetime64(first.group(1), "ms")
+        end = np.datetime64(second.group(1), "ms")
+        after = stripped[second.end() :].strip()
+        result.append((start, end, after))
+
+    return result

stk_files/_types.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from typing import Literal, Union
+
+import numpy as np
+from numpy.typing import NDArray
+
+DateTimeArray = NDArray[np.datetime64]
+
+MessageLevel = Literal["Errors", "Warnings", "Verbose"]
+TimeFormat = Literal["ISO-YMD", "EpSec"]
+CentralBody = Literal["Earth", "Moon"]
+
+CoordinateAxes = Literal[
+    "Fixed",
+    "J2000",
+    "ICRF",
+    "Inertial",
+    "TrueOfDate",
+    "MeanOfDate",
+    "TEMEOfDate",
+    "MeanOfEpoch",
+    "TrueOfEpoch",
+    "TEMEOfEpoch",
+    "AlignmentAtEpoch",
+]
+
+InterpolationMethod = Literal["Lagrange", "Hermite"]
+
+AttitudeFormat = Literal[
+    "Quaternions",
+    "QuatScalarFirst",
+    "EulerAngles",
+    "YPRAngles",
+    "DCM",
+    "ECFVector",
+    "ECIVector",
+]
+
+SensorFormat = Literal[
+    "Quaternions",
+    "QuatScalarFirst",
+    "EulerAngles",
+    "YPRAngles",
+    "AzElAngles",
+    "DCM",
+    "ECFVector",
+    "ECIVector",
+]
+
+EphemerisFormat = Literal[
+    "TimePos",
+    "TimePosVel",
+    "TimePosVelAcc",
+    "LLATimePos",
+    "LLATimePosVel",
+]
+
+EulerSequence = Literal[121, 123, 131, 132, 212, 213, 231, 232, 312, 313, 321, 323]
+YPRSequence = Literal[123, 132, 213, 231, 312, 321]
+AzElSequence = Literal[323, 213]
+RotationSequence = Union[EulerSequence, YPRSequence]
+
+EPOCH_DEPENDENT_AXES: frozenset[str] = frozenset(
+    {
+        "MeanOfEpoch",
+        "TrueOfEpoch",
+        "TEMEOfEpoch",
+        "AlignmentAtEpoch",
+    }
+)
+
+QUATERNION_FORMATS: frozenset[str] = frozenset({"Quaternions", "QuatScalarFirst"})
+ANGLE_FORMATS: frozenset[str] = frozenset({"EulerAngles", "YPRAngles", "AzElAngles"})
+
+ATTITUDE_COLUMNS: dict[str, int] = {
+    "Quaternions": 4,
+    "QuatScalarFirst": 4,
+    "EulerAngles": 3,
+    "YPRAngles": 3,
+    "DCM": 9,
+    "ECFVector": 3,
+    "ECIVector": 3,
+}
+
+SENSOR_COLUMNS: dict[str, int] = {
+    **ATTITUDE_COLUMNS,
+    "AzElAngles": 2,
+}
+
+EPHEMERIS_COLUMNS: dict[str, int] = {
+    "TimePos": 3,
+    "TimePosVel": 6,
+    "TimePosVelAcc": 9,
+    "LLATimePos": 3,
+    "LLATimePosVel": 6,
+}
+
+EULER_SEQUENCES = (121, 123, 131, 132, 212, 213, 231, 232, 312, 313, 321, 323)
+YPR_SEQUENCES = (123, 132, 213, 231, 312, 321)
+AZEL_SEQUENCES = (323, 213)