spacecoords 0.1.0__py3-none-any.whl

spacecoords/__init__.py

@@ -0,0 +1,44 @@
+"""General purpose convenience functions for different coordinate systems and linear algebra
+functions
+"""
+
+from types import ModuleType
+import importlib.util
+from .version import __version__
+
+from . import linalg
+from . import spherical
+from . import constants
+
+
+def _make_missing_module(name: str, dep: str):
+    class _MissingModule(ModuleType):
+        def __getattr__(self, key):
+            raise ImportError(
+                f"The optional dependency `{dep}` for is missing.\n"
+                f"Install it with `pip install spacecoords[all]` or `pip install {dep}`."
+            )
+
+    return _MissingModule(name)
+
+
+# Optional modules
+if importlib.util.find_spec("astropy") is not None:
+    from . import celestial
+else:
+    astropy = _make_missing_module("celestial", "astropy")
+
+if importlib.util.find_spec("jplephem") is not None:
+    from . import spk_basic
+else:
+    naif_ephemeris = _make_missing_module("spk_basic", "jplephem")
+
+if importlib.util.find_spec("spice") is not None:
+    from . import spice
+else:
+    naif_spice = _make_missing_module("spice", "spiceypy")
+
+if importlib.util.find_spec("requests") is not None:
+    from . import download
+else:
+    download = _make_missing_module("download", "requests")

spacecoords/celestial.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python
+
+"""Coordinate frame transformations and related functions.
+Main usage is the `convert` function that wraps Astropy frame transformations.
+"""
+from typing import Type, Any
+from pathlib import Path
+import numpy as np
+from astropy.time import Time
+import astropy.coordinates as coord
+import astropy.units as units
+import astropy.config as config
+
+from .types import (
+    NDArray_N,
+    NDArray_3,
+    NDArray_6,
+    NDArray_3xN,
+    NDArray_6xN,
+    T,
+)
+
+"""List of astropy frames
+"""
+ASTROPY_FRAMES = {
+    "TEME": "TEME",
+    "ITRS": "ITRS",
+    "ITRF": "ITRS",
+    "ICRS": "ICRS",
+    "ICRF": "ICRS",
+    "GCRS": "GCRS",
+    "GCRF": "GCRS",
+    "HCRS": "HCRS",
+    "HCRF": "HCRS",
+    "HeliocentricMeanEcliptic".upper(): "HeliocentricMeanEcliptic",
+    "GeocentricMeanEcliptic".upper(): "GeocentricMeanEcliptic",
+    "HeliocentricTrueEcliptic".upper(): "HeliocentricTrueEcliptic",
+    "GeocentricTrueEcliptic".upper(): "GeocentricTrueEcliptic",
+    "BarycentricMeanEcliptic".upper(): "BarycentricMeanEcliptic",
+    "BarycentricTrueEcliptic".upper(): "BarycentricTrueEcliptic",
+    "SPICEJ2000": "ICRS",
+}
+
+"""List of frames that are not time-dependant
+"""
+ASTROPY_NOT_OBSTIME = [
+    "ICRS",
+    "BarycentricMeanEcliptic",
+    "BarycentricTrueEcliptic",
+]
+
+
+def get_solarsystem_body_state(
+    body: str,
+    time: Time,
+    kernel_dir: Path,
+    ephemeris: str = "jpl",
+) -> NDArray_6xN | NDArray_6:
+    """
+    
+    This is to not have to remember how to do this astropy config stuff
+    # https://docs.astropy.org/en/stable/api/astropy.coordinates.solar_system_ephemeris.html
+    """
+    with config.set_temp_cache(path=str(kernel_dir), delete=False):
+        pos, vel = coord.get_body_barycentric_posvel(body, time, ephemeris=ephemeris)
+
+    size = len(time)
+    shape: tuple[int, ...] = (6, size) if size > 0 else (6,)
+    state = np.empty(shape, dtype=np.float64)
+    state[:3, ...] = pos.xyz.to(units.m).value
+    state[3:, ...] = vel.d_xyz.to(units.m / units.s).value
+    return state
+
+
+def not_geocentric(frame: str) -> bool:
+    """Check if the given frame name is one of the non-geocentric frames."""
+    frame = frame.upper()
+    return frame in ["ICRS", "ICRF", "HCRS", "HCRF"] or frame.startswith("Heliocentric".upper())
+
+
+def is_geocentric(frame: str) -> bool:
+    """Check if the frame name is a supported geocentric frame"""
+    return not not_geocentric(frame)
+
+
+def convert(
+    t: NDArray_N,
+    states: NDArray_6xN,
+    in_frame: str,
+    out_frame: str,
+    frame_kwargs: dict[str, Any],
+) -> NDArray_6xN:
+    """Perform predefined coordinate transformations using Astropy.
+    Always returns a copy of the array.
+
+    Parameters
+    ----------
+    t
+        Absolute time corresponding to the input states.
+    states
+        Size `(6,n)` matrix of states in SI units where rows 1-3
+        are position and 4-6 are velocity.
+    in_frame
+        Name of the frame the input states are currently in.
+    out_frame
+        Name of the state to transform to.
+    frame_kwargs
+        Any arguments needed for the specific transform detailed by `astropy`
+        in their documentation
+
+    Returns
+    -------
+        Size `(6,n)` matrix of states in SI units where rows
+        1-3 are position and 4-6 are velocity.
+
+    """
+
+    in_frame = in_frame.upper()
+    out_frame = out_frame.upper()
+
+    if in_frame == out_frame:
+        return states.copy()
+
+    if in_frame in ASTROPY_FRAMES:
+        in_frame_ = ASTROPY_FRAMES[in_frame]
+        in_frame_cls = getattr(coord, in_frame_)
+    else:
+        err_str = [
+            f"In frame '{in_frame}' not recognized, ",
+            "please check spelling or perform manual transformation",
+        ]
+        raise ValueError("".join(err_str))
+
+    kw = {}
+    kw.update(frame_kwargs)
+    if in_frame_ not in ASTROPY_NOT_OBSTIME:
+        kw["obstime"] = t
+
+    astropy_states = _convert_to_astropy(states, in_frame_cls, kw)
+
+    if out_frame in ASTROPY_FRAMES:
+        out_frame_ = ASTROPY_FRAMES[out_frame]
+        out_frame_cls = getattr(coord, out_frame_)
+    else:
+        err_str = [
+            f"Out frame '{out_frame}' not recognized, ",
+            "please check spelling or perform manual transformation",
+        ]
+        raise ValueError("".join(err_str))
+
+    kw = {}
+    kw.update(frame_kwargs)
+    if out_frame_ not in ASTROPY_NOT_OBSTIME:
+        kw["obstime"] = t
+
+    out_states = astropy_states.transform_to(out_frame_cls(**kw))
+
+    rets = states.copy()
+    rets[:3, ...] = out_states.cartesian.xyz.to(units.m).value
+    rets[3:, ...] = out_states.velocity.d_xyz.to(units.m / units.s).value
+
+    return rets
+
+
+def _convert_to_astropy(
+    states: NDArray_6xN | NDArray_6,
+    frame: Type[T],
+    frame_kwargs: dict[str, Any],
+) -> T:
+    state_p = coord.CartesianRepresentation(states[:3, ...] * units.m)
+    state_v = coord.CartesianDifferential(states[3:, ...] * units.m / units.s)
+    astropy_states = frame(state_p.with_differentials(state_v), **frame_kwargs)  # type: ignore
+    return astropy_states
+
+
+def geodetic_to_ITRS(
+    lat: NDArray_N | float,
+    lon: NDArray_N | float,
+    alt: NDArray_N | float,
+    degrees: bool = True,
+) -> NDArray_3xN | NDArray_3:
+    """Use `astropy.coordinates.WGS84GeodeticRepresentation` to transform from WGS84 to ITRS."""
+    ang_unit = units.deg if degrees else units.rad
+
+    wgs_cord = coord.WGS84GeodeticRepresentation(
+        lon=lon * ang_unit,
+        lat=lat * ang_unit,
+        height=alt * units.m,
+    )
+    itrs_cord = coord.ITRS(wgs_cord)
+
+    if isinstance(lat, np.ndarray):
+        size = lat.size
+    else:
+        size = 0
+
+    shape: tuple[int, ...] = (6, size) if size > 0 else (6,)
+    state = np.empty(shape, dtype=np.float64)
+    state[:3, ...] = itrs_cord.cartesian.xyz.to(units.m).value
+    state[3:, ...] = itrs_cord.velocity.d_xyz.to(units.m / units.s).value
+
+    return state
+
+
+def ITRS_to_geodetic(
+    state: NDArray_3xN | NDArray_N,
+    degrees: bool = True,
+):
+    """Use `astropy.coordinates.WGS84GeodeticRepresentation` to transform from ITRS to WGS84."""
+    raise NotImplementedError()
+    # ang_unit = units.deg if degrees else units.rad
+    # astropy_states = _convert_to_astropy(state, coord.ITRS)
+    # wgs_cord = coord.WGS84GeodeticRepresentation(astropy_states)
+    #
+    # if isinstance(lat, np.ndarray):
+    #     size = lat.size
+    # else:
+    #     size = 0
+    #
+    # shape: tuple[int, ...] = (6, size) if size > 0 else (6,)
+    # state = np.empty(shape, dtype=np.float64)
+    # state[:3, ...] = itrs_cord.cartesian.xyz.to(units.m).value
+    # state[3:, ...] = itrs_cord.velocity.d_xyz.to(units.m / units.s).value
+    #
+    # return state
+    pass

spacecoords/cli.py

@@ -0,0 +1,22 @@
+import argparse
+
+
+def main():
+    import spacecoords as sc
+
+    parser = argparse.ArgumentParser(description="Download files")
+    subparsers = parser.add_subparsers(help="Available download interfaces", dest="command")
+
+    naif_parser = subparsers.add_parser("naif_kernel", help="Download NAIF Kernels")
+    naif_parser.add_argument(
+        "kernel_type",
+        choices=list(sc.download.KERNEL_PATHS.keys()),
+        help="Type of kernel (determines location on server)",
+    )
+    naif_parser.add_argument("kernel_name", help="Kernel filename")
+    naif_parser.add_argument("output_file", help="Path to output file")
+
+    args = parser.parse_args()
+
+    if args.command == "naif_kernel":
+        sc.download.naif_kernel_main(args)

spacecoords/constants.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python
+
+"""Constants useful for different coordinate systems"""
+
+
+G: float = 6.67430e-11
+"""Newtonian constant of gravitation (m^3 kg^-1 s^-2), CODATA Recommended Values of the Fundamental
+Physical Constants 2022.
+"""
+
+
+class WGS84:
+    """World Geodetic System 1984 constants."""
+
+    a: float = 6378.137 * 1e3
+    """float: semi-major axis parameter in meters of the World Geodetic System 1984 (WGS84)
+    """
+
+    b: float = 6356.7523142 * 1e3
+    """float: semi-minor axis parameter in meters of the World Geodetic System 1984 (WGS84)
+    """
+
+    esq: float = 6.69437999014 * 0.001
+    """float: `esq` parameter in meters of the World Geodetic System 1984 (WGS84)
+    """
+
+    e1sq: float = 6.73949674228 * 0.001
+    """float: `e1sq` parameter in meters of the World Geodetic System 1984 (WGS84)
+    """
+
+    f: float = 1 / 298.257223563
+    """float: `f` parameter of the World Geodetic System 1984 (WGS84)
+    """
+
+
+R_earth: float = 6371.0088e3
+"""float: Radius of the Earth using the International
+Union of Geodesy and Geophysics (IUGG) definition
+"""
+
+
+class WGS72:
+    """World Geodetic System 1972 constants."""
+
+    MU_earth: float = 398600.8 * 1e9
+    """float: Standard gravitational parameter of the Earth using the WGS72 convention.
+    """
+
+    M_earth: float = MU_earth / G
+    """float: Mass of the Earth using the WGS72 convention.
+    """

spacecoords/download.py

@@ -0,0 +1,59 @@
+import sys
+import os
+from pathlib import Path
+import requests
+
+NAIF_URL = "https://naif.jpl.nasa.gov/pub/naif/"
+
+KERNEL_PATHS = {
+    "planetary": "generic_kernels/spk/planets/",
+}
+
+
+def naif_kernel(
+    kernel_path: str,
+    output_file: Path,
+    progress: bool = True,
+    chunk_size: int = 8192,
+):
+    url = NAIF_URL + kernel_path
+    with requests.get(url, stream=True) as r:
+        r.raise_for_status()
+        total_length = r.headers.get("content-length")
+        downloaded = 0
+        if total_length is None:
+            with open(output_file, "wb") as fh:
+                for chunk in r.iter_content(chunk_size=chunk_size):
+                    fh.write(chunk)
+                    if progress:
+                        downloaded += len(chunk)
+                        sys.stdout.write(f"{downloaded / 1024:.1f} KB")
+                        sys.stdout.flush()
+            if progress:
+                print()
+        else:
+            total_length = int(total_length)
+            prog_width = min(os.get_terminal_size()[0] - 10, 100)
+            with open(output_file, "wb") as fh:
+                for chunk in r.iter_content(chunk_size=chunk_size):
+                    if not chunk:
+                        continue
+                    fh.write(chunk)
+                    if progress:
+                        downloaded += len(chunk)
+                        done = int(prog_width * downloaded / total_length)
+                        sys.stdout.write(
+                            f"\r[{'=' * done}{' ' * (prog_width - done)}] "
+                            f"{downloaded / 1024:.1f} KB / {total_length / 1024:.1f} KB"
+                        )
+                        sys.stdout.flush()
+            if progress:
+                print()
+
+
+def naif_kernel_main(args):
+    naif_kernel(
+        kernel_path=KERNEL_PATHS[args.kernel_type] + args.kernel_name,
+        output_file=args.output_file,
+        progress=True,
+    )

spacecoords/frames.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python
+
+"""Transforms between common coordinate frames without any additional dependencies"""
+
+import numpy as np
+from .spherical import sph_to_cart
+from .types import (
+    NDArray_N,
+    NDArray_3,
+    NDArray_3xN,
+)
+
+
+def ned_to_ecef(
+    lat: float,
+    lon: float,
+    ned: NDArray_3xN | NDArray_3,
+    degrees: bool = False,
+) -> NDArray_3xN | NDArray_3:
+    """NED (north/east/down) using geocentric zenith to ECEF coordinate system
+    conversion, not including translation.
+
+    Parameters
+    ----------
+    lat
+        Latitude of the origin in geocentric spherical coordinates
+    lon
+        Longitude of the origin in geocentric spherical coordinates
+    ned
+        (3,n) input matrix of positions in the NED-convention.
+    degrees
+        If `True`, use degrees. Else all angles are given in radians.
+
+    Returns
+    -------
+        (3,) or (3,n) array x,y and z coordinates in ECEF.
+    """
+    enu = np.empty(ned.size, dtype=ned.dtype)
+    enu[0, ...] = ned[1, ...]
+    enu[1, ...] = ned[0, ...]
+    enu[2, ...] = -ned[2, ...]
+    return enu_to_ecef(lat, lon, enu, degrees=degrees)
+
+
+def azel_to_ecef(
+    lat: float,
+    lon: float,
+    az: NDArray_N | float,
+    el: NDArray_N | float,
+    degrees: bool = False,
+) -> NDArray_3xN | NDArray_3:
+    """Radar pointing (az,el) using geocentric zenith to unit vector in
+    ECEF, not including translation.
+
+    Parameters
+    ----------
+    lat
+        Latitude of the origin in geocentric spherical coordinates
+    lon
+        Longitude of the origin in geocentric spherical coordinates
+    az
+        Azimuth of the pointing direction
+    el
+        Elevation of the pointing direction
+    degrees
+        If `True`, use degrees. Else all angles are given in radians.
+
+    Returns
+    -------
+        (3,) or (3,n) array x,y and z coordinates in ECEF.
+    """
+    shape: tuple[int, ...] = (3,)
+
+    if isinstance(az, np.ndarray):
+        if len(az.shape) == 0:
+            az = float(az)
+        elif len(az) > 1:
+            shape = (3, len(az))
+            az = az.flatten()
+        else:
+            az = az[0]
+
+    if isinstance(el, np.ndarray):
+        if len(el.shape) == 0:
+            el = float(el)
+        elif len(el) > 1:
+            shape = (3, len(el))
+            el = el.flatten()
+        else:
+            el = el[0]
+
+    sph = np.empty(shape, dtype=np.float64)
+    sph[0, ...] = az
+    sph[1, ...] = el
+    sph[2, ...] = 1.0
+    enu = sph_to_cart(sph, degrees=degrees)
+    return enu_to_ecef(lat, lon, enu, degrees=degrees)
+
+
+def enu_to_ecef(
+    lat: float,
+    lon: float,
+    enu: NDArray_3 | NDArray_3xN,
+    degrees: bool = False,
+) -> NDArray_3xN | NDArray_3:
+    """Rotate ENU (east/north/up) using geocentric zenith to ECEF coordinate system,
+    not including translation.
+
+    Parameters
+    ----------
+    lat
+        Latitude of the origin in geocentric spherical coordinates
+    lon
+        Longitude of the origin in geocentric spherical coordinates
+    enu
+        (3,n) input matrix of positions in the ENU-convention.
+    degrees
+        If `True`, use degrees. Else all angles are given in radians.
+
+    Returns
+    -------
+        (3,) or (3,n) array x,y and z coordinates in ECEF.
+    """
+    if degrees:
+        lat, lon = np.radians(lat), np.radians(lon)
+
+    mx = np.array(
+        [
+            [-np.sin(lon), -np.sin(lat) * np.cos(lon), np.cos(lat) * np.cos(lon)],
+            [np.cos(lon), -np.sin(lat) * np.sin(lon), np.cos(lat) * np.sin(lon)],
+            [0, np.cos(lat), np.sin(lat)],
+        ]
+    )
+
+    ecef = np.dot(mx, enu)
+    return ecef
+
+
+def ecef_to_enu(
+    lat: float,
+    lon: float,
+    ecef: NDArray_3 | NDArray_3xN,
+    degrees: bool = False,
+) -> NDArray_3xN | NDArray_3:
+    """Rotate ECEF coordinate system to local ENU (east,north,up) using geocentric
+    zenith, not including translation.
+
+    Parameters
+    ----------
+    lat
+        Latitude of the origin in geocentric spherical coordinates
+    lon
+        Longitude of the origin in geocentric spherical coordinates
+    ecef
+        (3,) or (3,n) array x,y and z coordinates in ECEF.
+    degrees
+        If `True`, use degrees. Else all angles are given in radians.
+
+    Returns
+    -------
+        (3,) or (3,n) array x, y and z coordinates in ENU.
+    """
+    if degrees:
+        lat, lon = np.radians(lat), np.radians(lon)
+
+    mx = np.array(
+        [
+            [-np.sin(lon), -np.sin(lat) * np.cos(lon), np.cos(lat) * np.cos(lon)],
+            [np.cos(lon), -np.sin(lat) * np.sin(lon), np.cos(lat) * np.sin(lon)],
+            [0, np.cos(lat), np.sin(lat)],
+        ]
+    )
+    enu = np.dot(np.linalg.inv(mx), ecef)
+    return enu

spacecoords/linalg.py

@@ -0,0 +1,280 @@
+#!/usr/bin/env python
+
+"""Useful utility functions related to linear algebra"""
+
+import numpy as np
+import numpy.typing as npt
+from .types import (
+    NDArray_3,
+    NDArray_3xN,
+    NDArray_N,
+    NDArray_3x3,
+    NDArray_3x3xN,
+    NDArray_2x2,
+    NDArray_NxN,
+)
+
+
+def vector_angle(
+    a: NDArray_3 | NDArray_3xN, b: NDArray_3 | NDArray_3xN, degrees: bool = False
+) -> NDArray_N | float:
+    """Angle between two vectors.
+
+    Parameters
+    ----------
+    a
+        (3, N) or (3,) vector of Cartesian coordinates.
+        This argument is vectorized in the second array dimension.
+    b
+        (3, N) or (3,) vector of Cartesian coordinates.
+        This argument is vectorized in the second array dimension.
+    degrees
+        If `True`, use degrees. Else all angles are given in radians.
+
+    Returns
+    -------
+        (N, ) or float vector of angles between input vectors.
+
+    Notes
+    -----
+    Definition
+        $$
+            \\theta = \\cos^{-1}\\frac{
+                \\langle\\mathbf{a},\\mathbf{b}\\rangle
+            }{
+                |\\mathbf{a}||\\mathbf{b}|
+            }
+        $$
+        where $\\langle\\mathbf{a},\\mathbf{b}\\rangle$ is the dot
+        product and $|\\mathbf{a}|$ denotes the norm.
+
+    """
+    a_norm = np.linalg.norm(a, axis=0)
+    b_norm = np.linalg.norm(b, axis=0)
+
+    if len(a.shape) == 1:
+        proj = np.dot(a, b) / (a_norm * b_norm)
+    elif len(b.shape) == 1:
+        proj = np.dot(b, a) / (a_norm * b_norm)
+    else:
+        assert a.shape == b.shape, "Input shapes do not match"
+        proj = np.sum(a * b, axis=0) / (a_norm * b_norm)
+
+    if len(a.shape) == 1 and len(b.shape) == 1:
+        if proj > 1.0:
+            proj = 1.0
+        elif proj < -1.0:
+            proj = -1.0
+    else:
+        proj[proj > 1.0] = 1.0
+        proj[proj < -1.0] = -1.0
+
+    theta = np.arccos(proj)
+    if degrees:
+        theta = np.degrees(theta)
+
+    return theta
+
+
+def rot_mat_x(
+    theta: NDArray_N | float, dtype: npt.DTypeLike = np.float64, degrees: bool = False
+) -> NDArray_3x3xN | NDArray_3x3:
+    """Compute matrix for rotation of R3 vector through angle theta
+    around the X-axis. For frame rotation, use the transpose.
+
+    Parameters
+    ----------
+    theta
+        Angle to rotate.
+    dtype
+        Numpy datatype of the rotation matrix.
+    degrees
+        If `True`, use degrees. Else all angles are given in radians.
+
+    Returns
+    -------
+        (3, 3) Rotation matrix, or (3, 3, n) tensor if theta is vector input.
+
+    """
+    if degrees:
+        theta = np.radians(theta)
+    size: tuple[int, ...]
+    if isinstance(theta, np.ndarray) and theta.ndim > 0:
+        size = (3, 3, len(theta))
+    else:
+        size = (3, 3)
+
+    ca, sa = np.cos(theta), np.sin(theta)
+    rot = np.zeros(size, dtype=dtype)
+    rot[0, 0, ...] = 1
+    rot[1, 1, ...] = ca
+    rot[1, 2, ...] = -sa
+    rot[2, 1, ...] = sa
+    rot[2, 2, ...] = ca
+    return rot
+
+
+def rot_mat_y(
+    theta: NDArray_N | float, dtype: npt.DTypeLike = np.float64, degrees: bool = False
+) -> NDArray_3x3xN | NDArray_3x3:
+    """Compute matrix for rotation of R3 vector through angle theta
+    around the Y-axis. For frame rotation, use the transpose.
+
+    Parameters
+    ----------
+    theta
+        Angle to rotate.
+    dtype
+        Numpy datatype of the rotation matrix.
+    degrees
+        If `True`, use degrees. Else all angles are given in radians.
+
+    Returns
+    -------
+        (3, 3) Rotation matrix, or (3, 3, n) tensor if theta is vector input.
+
+    """
+    if degrees:
+        theta = np.radians(theta)
+    size: tuple[int, ...]
+    if isinstance(theta, np.ndarray) and theta.ndim > 0:
+        size = (3, 3, len(theta))
+    else:
+        size = (3, 3)
+
+    ca, sa = np.cos(theta), np.sin(theta)
+    rot = np.zeros(size, dtype=dtype)
+    rot[0, 0, ...] = ca
+    rot[0, 2, ...] = sa
+    rot[1, 1, ...] = 1
+    rot[2, 0, ...] = -sa
+    rot[2, 2, ...] = ca
+    return rot
+
+
+def rot_mat_z(
+    theta: NDArray_N | float, dtype: npt.DTypeLike = np.float64, degrees: bool = False
+) -> NDArray_3x3xN | NDArray_3x3:
+    """Compute matrix for rotation of R3 vector through angle theta
+    around the Z-axis. For frame rotation, use the transpose.
+
+    Parameters
+    ----------
+    theta
+        Angle to rotate.
+    dtype
+        Numpy datatype of the rotation matrix.
+    degrees
+        If `True`, use degrees. Else all angles are given in radians.
+
+    Returns
+    -------
+        (3, 3) Rotation matrix, or (3, 3, n) tensor if theta is vector input.
+
+    """
+    if degrees:
+        theta = np.radians(theta)
+    size: tuple[int, ...]
+    if isinstance(theta, np.ndarray) and theta.ndim > 0:
+        size = (3, 3, len(theta))
+    else:
+        size = (3, 3)
+
+    ca, sa = np.cos(theta), np.sin(theta)
+    rot = np.zeros(size, dtype=dtype)
+    rot[0, 0, ...] = ca
+    rot[0, 1, ...] = -sa
+    rot[1, 0, ...] = sa
+    rot[1, 1, ...] = ca
+    rot[2, 2, ...] = 1
+    return rot
+
+
+def rot_mat_2d(
+    theta: float,
+    dtype: npt.DTypeLike = np.float64,
+    degrees: bool = False,
+) -> NDArray_2x2:
+    """Matrix for rotation of R2 vector in the plane through angle theta
+    For frame rotation, use the transpose.
+
+    Parameters
+    ----------
+    theta : float
+        Angle to rotate.
+    dtype : numpy.dtype
+        Numpy datatype of the rotation matrix.
+    degrees : bool
+        If :code:`True`, use degrees. Else all angles are given in radians.
+
+    Returns
+    -------
+    numpy.ndarray
+        (2, 2) Rotation matrix.
+
+    """
+    if degrees:
+        theta = np.radians(theta)
+
+    ca, sa = np.cos(theta), np.sin(theta)
+    return np.array([[ca, -sa], [sa, ca]], dtype=dtype)
+
+
+def scale_mat_2d(
+    x: float,
+    y: float,
+    dtype: npt.DTypeLike = np.float64,
+) -> NDArray_2x2:
+    """Matrix for 2d scaling.
+
+    Parameters
+    ----------
+    x
+        Scaling coefficient for first coordinate axis.
+    y
+        Scaling coefficient for second coordinate axis.
+
+    Returns
+    -------
+        (2, 2) Scaling matrix.
+    """
+    M_scale = np.zeros((2, 2), dtype=dtype)
+    M_scale[0, 0] = x
+    M_scale[1, 1] = y
+    return M_scale
+
+
+def vec_to_vec(vec_in: NDArray_N, vec_out: NDArray_N) -> NDArray_NxN:
+    """Get the rotation matrix that rotates `vec_in` to `vec_out` along the
+    plane containing both. Uses quaternion calculations.
+    """
+    N = len(vec_in)
+    if N != len(vec_out):
+        raise ValueError("Input and output vectors must be same dimensionality.")
+    assert N == 3, "Only implemented for 3d vectors"
+
+    a = vec_in / np.linalg.norm(vec_in)
+    b = vec_out / np.linalg.norm(vec_out)
+
+    adotb = np.dot(a, b)
+    axb = np.cross(a, b)
+    axb_norm = np.linalg.norm(axb)
+
+    # rotation in the plane frame of `vec_in` and `vec_out`
+    G = np.zeros((N, N), dtype=vec_in.dtype)
+    G[0, 0] = adotb
+    G[0, 1] = -axb_norm
+    G[1, 0] = axb_norm
+    G[1, 1] = adotb
+    G[2, 2] = 1
+
+    # inverse of change of basis from standard orthonormal to `vec_in` and `vec_out` plane
+    F = np.zeros((N, N), dtype=vec_in.dtype)
+    F[:, 0] = a
+    F[:, 1] = (b - adotb * a) / np.linalg.norm(b - adotb * a)
+    F[:, 2] = axb
+
+    # go to frame, rotation in plane, leave frame
+    R = F @ G @ np.linalg.inv(F)
+
+    return R

spacecoords/spherical.py

@@ -0,0 +1,185 @@
+#!/usr/bin/env python
+
+"""Functions related to spherical coordinate systems"""
+
+import numpy as np
+from numpy.typing import NDArray
+from .types import NDArray_3, NDArray_3xN, NDArray_N
+
+from . import linalg
+
+CLOSE_TO_POLE_LIMIT = 1e-9**2
+CLOSE_TO_POLE_LIMIT_rad = np.arctan(1 / np.sqrt(CLOSE_TO_POLE_LIMIT))
+
+
+def arctime_to_degrees(minutes: NDArray | float, seconds: NDArray | float) -> NDArray | float:
+    return (minutes + seconds / 60.0) / 60.0
+
+
+def cart_to_sph(vec: NDArray_3 | NDArray_3xN, degrees: bool = False) -> NDArray_3 | NDArray_3xN:
+    """Convert from Cartesian coordinates (east, north, up) to Spherical
+    coordinates (azimuth, elevation, range) in a angle east of north and
+    elevation fashion. Returns azimuth between [-pi, pi] and elevation between
+    [-pi/2, pi/2].
+
+    Parameters
+    ----------
+    vec
+        (3, N) or (3,) vector of Cartesian coordinates (east, north, up).
+        This argument is vectorized in the second array dimension.
+    degrees
+        If `True`, use degrees. Else all angles are given in radians.
+
+    Returns
+    -------
+        (3, N) or (3, ) vector of Spherical coordinates
+        (azimuth, elevation, range).
+
+    Notes
+    -----
+    Azimuth close to pole convention
+        Uses a :code:`CLOSE_TO_POLE_LIMIT` constant when transforming determine
+        if the point is close to the pole and sets the azimuth by definition
+        to 0 "at" the poles for consistency.
+
+    """
+
+    r2_ = vec[0, ...] ** 2 + vec[1, ...] ** 2
+
+    sph = np.empty(vec.shape, dtype=vec.dtype)
+
+    if len(vec.shape) == 1:
+        if r2_ < CLOSE_TO_POLE_LIMIT:
+            sph[0] = 0.0
+            sph[1] = np.sign(vec[2]) * np.pi * 0.5
+        else:
+            sph[0] = np.arctan2(vec[0], vec[1])
+            sph[1] = np.arctan(vec[2] / np.sqrt(r2_))
+    else:
+        inds_ = r2_ < CLOSE_TO_POLE_LIMIT
+        not_inds_ = np.logical_not(inds_)
+
+        sph[0, inds_] = 0.0
+        sph[1, inds_] = np.sign(vec[2, inds_]) * np.pi * 0.5
+        sph[0, not_inds_] = np.arctan2(vec[0, not_inds_], vec[1, not_inds_])
+        sph[1, not_inds_] = np.arctan(vec[2, not_inds_] / np.sqrt(r2_[not_inds_]))
+
+    sph[2, ...] = np.sqrt(r2_ + vec[2, ...] ** 2)
+    if degrees:
+        sph[:2, ...] = np.degrees(sph[:2, ...])
+
+    return sph
+
+
+def sph_to_cart(vec: NDArray_3 | NDArray_3xN, degrees: bool = False) -> NDArray_3 | NDArray_3xN:
+    """Convert from spherical coordinates (azimuth, elevation, range) to
+    Cartesian (east, north, up) in a angle east of north and elevation fashion.
+
+
+    Parameters
+    ----------
+    vec
+        (3, N) or (3,) vector of Cartesian Spherical
+        (azimuth, elevation, range).
+        This argument is vectorized in the second array dimension.
+    degrees
+        If :code:`True`, use degrees. Else all angles are given in radians.
+
+    Returns
+    -------
+        (3, N) or (3, ) vector of Cartesian coordinates (east, north, up).
+
+    """
+
+    _az = vec[0, ...]
+    _el = vec[1, ...]
+    if degrees:
+        _az, _el = np.radians(_az), np.radians(_el)
+    cart = np.empty(vec.shape, dtype=vec.dtype)
+
+    cart[0, ...] = vec[2, ...] * np.sin(_az) * np.cos(_el)
+    cart[1, ...] = vec[2, ...] * np.cos(_az) * np.cos(_el)
+    cart[2, ...] = vec[2, ...] * np.sin(_el)
+
+    return cart
+
+
+def az_el_to_sph(
+    azimuth: NDArray_N | float,
+    elevation: NDArray_N | float,
+) -> NDArray_3xN | NDArray_3:
+    """Convert input azimuth and elevation to spherical coordinates states,
+    i.e a `shape=(3,n)` numpy array.
+    """
+
+    az_len = azimuth.size if isinstance(azimuth, np.ndarray) else None
+    el_len = elevation.size if isinstance(elevation, np.ndarray) else None
+
+    if el_len is not None and az_len is not None:
+        assert el_len == az_len, f"azimuth {az_len} and elevation {el_len} sizes must agree"
+
+    shape: tuple[int] | tuple[int, int]
+    if az_len is not None:
+        shape = (3, az_len)
+    elif el_len is not None:
+        shape = (3, el_len)
+    else:
+        shape = (3,)
+
+    sph = np.empty(shape, dtype=np.float64)
+    sph[0, ...] = azimuth
+    sph[1, ...] = elevation
+    sph[2, ...] = 1.0
+
+    return sph
+
+
+def az_el_point(
+    self, azimuth: NDArray_N | float, elevation: NDArray_N | float, degrees: bool = False
+) -> NDArray_3xN | NDArray_3:
+    """Point beam towards azimuth and elevation coordinate.
+
+    Parameters
+    ----------
+    azimuth : float
+        Azimuth east of north of pointing direction.
+    elevation : float
+        Elevation from horizon of pointing direction.
+    degrees : bool
+        If :code:`True` all input/output angles are in degrees,
+        else they are in radians. Defaults to instance
+        settings :code:`self.radians`.
+
+    """
+    sph = az_el_to_sph(azimuth, elevation)
+    return sph_to_cart(sph, degrees=degrees)
+
+
+def az_el_vs_cart_angle(
+    self,
+    azimuth: NDArray_N | float,
+    elevation: NDArray_N | float,
+    cart: NDArray_3xN | NDArray_3,
+    degrees: bool = False,
+) -> NDArray_N | float:
+    """Get angle between azimuth and elevation and pointing direction.
+
+    Parameters
+    ----------
+    azimuth : float or NDArray
+        Azimuth east of north of pointing direction.
+    elevation : float or NDArray
+        Elevation from horizon of pointing direction.
+    degrees : bool
+        If :code:`True` all input/output angles are in degrees,
+        else they are in radians.
+
+    Returns
+    -------
+    float or NDArray
+        Angle between pointing and given direction.
+
+    """
+    sph = az_el_to_sph(azimuth, elevation)
+    k = sph_to_cart(sph, degrees=degrees)
+    return linalg.vector_angle(cart, k, degrees=degrees)

spacecoords/spice.py

@@ -0,0 +1,8 @@
+"""This does advanced spice things that jplephem can not do
+
+#TODO: impalement what is needed here
+"""
+
+import spiceypy as spice
+
+# spice.furnsh("./cassMetaK.txt")

spacecoords/spk_basic.py

@@ -0,0 +1,71 @@
+from collections import OrderedDict
+import numpy as np
+from jplephem.spk import SPK
+
+"""Mapping from body name to integer id's used by the kernels.
+
+#todo: these can be expanded to get any body probably? and do more than astropy implementation does
+"""
+BODY_NAME_TO_KERNEL_SPEC = OrderedDict(
+    [
+        ("sun", [(0, 10)]),
+        ("mercury", [(0, 1), (1, 199)]),
+        ("venus", [(0, 2), (2, 299)]),
+        ("earth-moon-barycenter", [(0, 3)]),
+        ("earth", [(0, 3), (3, 399)]),
+        ("moon", [(0, 3), (3, 301)]),
+        ("mars", [(0, 4)]),
+        ("jupiter", [(0, 5)]),
+        ("saturn", [(0, 6)]),
+        ("uranus", [(0, 7)]),
+        ("neptune", [(0, 8)]),
+        ("pluto", [(0, 9)]),
+    ]
+)
+
+
+def get_solarsystem_body_states(bodies, epoch, kernel, units=None):
+    """Open a kernel file and get the statates of the given bodies at epoch in ICRS.
+
+    Note: All outputs from kernel computations are in the Barycentric (ICRS) "eternal" frame.
+    """
+    assert SPK is not None, "jplephem package needed to directly interact with kernels"
+    states = {}
+
+    kernel = SPK.open(kernel)
+
+    epoch_ = epoch.tdb  # jplephem uses Barycentric Dynamical Time (TDB)
+    jd1, jd2 = epoch_.jd1, epoch_.jd2
+
+    for body in bodies:
+        body_ = body.lower().strip()
+
+        if body_ not in BODY_NAME_TO_KERNEL_SPEC:
+            raise ValueError(f'Body name "{body}" not recognized')
+
+        states[body] = np.zeros((6,), dtype=np.float64)
+
+        # if there are multiple steps to go from states to
+        # ICRS barycentric, iterate trough and combine
+        for pair in BODY_NAME_TO_KERNEL_SPEC[body_]:
+            spk = kernel[pair]
+            if spk.data_type == 3:
+                # Type 3 kernels contain both position and velocity.
+                posvel = spk.compute(jd1, jd2).flatten()
+            else:
+                pos_, vel_ = spk.compute_and_differentiate(jd1, jd2)
+                posvel = np.zeros((6,), dtype=np.float64)
+                posvel[:3] = pos_
+                posvel[3:] = vel_
+
+            states[body] += posvel
+
+        # units from kernels are usually in km and km/day
+        if units is None:
+            states[body] *= 1e3
+            states[body][3:] /= 86400.0
+        else:
+            states[body] *= units[0]
+            states[body][3:] /= units[1]
+
+    return states

spacecoords/types.py

@@ -0,0 +1,35 @@
+"""
+This module contains convenient type information so that typing can be precise
+but not too verbose in the code itself.
+"""
+from typing import TypeVar
+import numpy.typing as npt
+
+T = TypeVar("T")
+
+NDArray_N = npt.NDArray
+"(n,) shaped ndarray"
+
+NDArray_3 = npt.NDArray
+"(3,) shaped ndarray"
+
+NDArray_6 = npt.NDArray
+"(6,) shaped ndarray"
+
+NDArray_3xN = npt.NDArray
+"(3,n) shaped ndarray"
+
+NDArray_6xN = npt.NDArray
+"(6,n) shaped ndarray"
+
+NDArray_NxN = npt.NDArray
+"(n,n) shaped ndarray"
+
+NDArray_3x3 = npt.NDArray
+"(3,3) shaped ndarray"
+
+NDArray_2x2 = npt.NDArray
+"(2,2) shaped ndarray"
+
+NDArray_3x3xN = npt.NDArray
+"(3,3,n) shaped ndarray"

spacecoords/version.py

@@ -0,0 +1,3 @@
+import importlib.metadata
+
+__version__ = importlib.metadata.version("spacecoords")

spacecoords-0.1.0.dist-info/METADATA

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: spacecoords
+Version: 0.1.0
+Summary: A collection of coordinate transforms for convenient use
+Author-email: Daniel Kastinen <daniel.kastinen@irf.se>
+Maintainer-email: Daniel Kastinen <daniel.kastinen@irf.se>
+License: MIT License
+        
+        Copyright (c) [2025] [Daniel Kastinen]
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Documentation, https://danielk.developer.irf.se/spacecoords/
+Project-URL: Repository, https://github.com/danielk333/spacecoords
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Operating System :: OS Independent
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2
+Provides-Extra: all
+Requires-Dist: astropy>=6; extra == "all"
+Requires-Dist: spiceypy>=8.0.0; extra == "all"
+Requires-Dist: jplephem>=2.23; extra == "all"
+Requires-Dist: requests>=2.20; extra == "all"
+Provides-Extra: develop
+Requires-Dist: pytest; extra == "develop"
+Requires-Dist: pytest-cov; extra == "develop"
+Requires-Dist: flake8; extra == "develop"
+Requires-Dist: wheel; extra == "develop"
+Requires-Dist: build; extra == "develop"
+Requires-Dist: twine; extra == "develop"
+Requires-Dist: auditwheel; extra == "develop"
+Requires-Dist: numpydoc; extra == "develop"
+Requires-Dist: black; extra == "develop"
+Requires-Dist: matplotlib; extra == "develop"
+Requires-Dist: ipykernel; extra == "develop"
+Requires-Dist: mkdocs-material; extra == "develop"
+Requires-Dist: mkdocstrings[python]; extra == "develop"
+Requires-Dist: mkdocs-jupyter; extra == "develop"
+Requires-Dist: mkdocs-gen-files; extra == "develop"
+Requires-Dist: mkdocs-literate-nav; extra == "develop"
+Requires-Dist: mkdocs-section-index; extra == "develop"
+Provides-Extra: tests
+Requires-Dist: pytest; extra == "tests"
+Requires-Dist: pytest-cov; extra == "tests"
+Dynamic: license-file
+
+# spacecoords
+
+A collection of coordinate transforms for convenient use across our applications to avoid
+duplication

spacecoords-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+spacecoords/__init__.py,sha256=Pnio_jaYCpNxzWRde23PFCnk-t_fvq5zavoWT-ObRN0,1230
+spacecoords/celestial.py,sha256=_WEQXv4YGRpa6_9kyWVNMJjcx-pJQG5rvYF6IA25V-E,6657
+spacecoords/cli.py,sha256=Esbbi3-u-xfvXSG5P8QqpT0odElwUreza_J1wmdS5yU,737
+spacecoords/constants.py,sha256=3BTHyhUFMXNzFrzuE-2FaRkEVTFW9khQQdG2IOoyFC0,1375
+spacecoords/download.py,sha256=h1e46ekYJC-TZeP4PpKoEyPSVPNWItWE1z-5PXWyauw,1931
+spacecoords/frames.py,sha256=u5og846ZXVGXyyWPMrRSX3Y82-09dVPd3Jh9uVH1w7Q,4646
+spacecoords/linalg.py,sha256=YT4F0y76_OLk-I0az89i6J3fL4PjIE4Q2I4wByd0Sb0,7189
+spacecoords/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+spacecoords/spherical.py,sha256=x_6pFAyEI-XySui70B9RWJSdKhYponCGX-jFpgh_njk,5589
+spacecoords/spice.py,sha256=CibzR8EopwAwLvtd0BVGkRPjrScILENlLQUU_YcpWMU,164
+spacecoords/spk_basic.py,sha256=CA4cZe6Y8Mw3UfL8X2ZaVFmvxWPnrcWAF6dgn2BeCQk,2335
+spacecoords/types.py,sha256=bDO9YJWNUb1M6IAIgNaNlEvJwJbV3T9Pc0QO_DWTOhQ,644
+spacecoords/version.py,sha256=56qNmktYm-a9EiinIbbIJG-6XTFmNReaWyZTcLJ15SI,83
+spacecoords-0.1.0.dist-info/licenses/LICENSE,sha256=HwPwsjPm8Dw0iFn-o4B6E-X4irUfOlYFHAI3jB2bTWM,1076
+spacecoords-0.1.0.dist-info/METADATA,sha256=RvssUD5fWfrTwtE1pL0OEpohTY0pgp22b1fnDvggKaE,3257
+spacecoords-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+spacecoords-0.1.0.dist-info/entry_points.txt,sha256=lDDxb87uHwAnvKkEVGvBxBbGOfTjYmWXp6BHBYpBjq4,53
+spacecoords-0.1.0.dist-info/top_level.txt,sha256=jknXkDXmkZUa9yRuVhcgbl5Da8LVxQsLofpQiLO0n70,12
+spacecoords-0.1.0.dist-info/RECORD,,

spacecoords-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

spacecoords-0.1.0.dist-info/entry_points.txt

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

spacecoords-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2025] [Daniel Kastinen]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spacecoords-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+spacecoords