keplemon 0.1.9__cp313-cp313-win_amd64.whl → 2.0.2__cp313-cp313-win_amd64.whl

keplemon/__init__.py

@@ -1,17 +1,35 @@
-from keplemon._keplemon.time import load_time_constants  # type: ignore
-from keplemon._keplemon import get_thread_count, set_thread_count  # type: ignore
+from keplemon._keplemon.saal.time_func_interface import load_time_constants  # type: ignore
+from keplemon._keplemon import (  # type: ignore
+    get_thread_count,
+    set_thread_count,
+    set_license_file_path,
+    get_license_file_path,
+    set_jpl_ephemeris_file_path,
+)
 from pathlib import Path
-from shutil import copyfile
 
-current_dir = Path(__file__).parent
 
-# Copy the license file to the current working directory if it doesn't exist
-working_license_path = Path.cwd() / "SGP4_Open_License.txt"
-if not working_license_path.exists():
-    copyfile(current_dir / "SGP4_Open_License.txt", working_license_path)
+PACKAGE_DIRECTORY = Path(__file__).parent
+ASSETS_DIRECTORY = PACKAGE_DIRECTORY / "assets"
+
+# Set the license file directory to the package directory
+set_license_file_path(ASSETS_DIRECTORY.as_posix())
 
 # Load the time constants from the assets directory
-TIME_CONSTANTS_PATH = current_dir / "assets" / "time_constants.dat"
+TIME_CONSTANTS_PATH = ASSETS_DIRECTORY / "time_constants.dat"
 load_time_constants(TIME_CONSTANTS_PATH.as_posix())
 
-__all__ = ["get_thread_count", "set_thread_count", "TIME_CONSTANTS_PATH"]
+# Load the JPL path
+JPL_EPHEMERIS_PATH = ASSETS_DIRECTORY / "JPLcon_1950_2050.405"
+set_jpl_ephemeris_file_path(JPL_EPHEMERIS_PATH.as_posix())
+
+__all__ = [
+    "get_thread_count",
+    "set_thread_count",
+    "TIME_CONSTANTS_PATH",
+    "JPL_EPHEMERIS_PATH",
+    "set_license_file_path",
+    "PACKAGE_DIRECTORY",
+    "ASSETS_DIRECTORY",
+    "get_license_file_path",
+]

keplemon/__init__.pyi

@@ -28,3 +28,27 @@ Path to the default time constants file required by the SAAL binaries
 !!! warning
     This path should never be modified and is only exposed to allow inspection of current data.
 """
+
+#: Path to the parent directory of the package
+PACKAGE_DIRECTORY: Path
+"""Path to the parent directory of the package"""
+
+#: Path to the assets directory containing supporting data files for the package
+ASSETS_DIRECTORY: Path
+"""Path to the assets directory containing supporting data files for the package"""
+
+def set_license_file_path(path: str) -> None:
+    """
+    Set the path to the license file required by the SAAL binaries
+
+    Args:
+        path: Path to the SGP4 license file
+    """
+    ...
+
+def get_license_file_path() -> str:
+    """
+    Returns:
+        Path to the SGP4 license file
+    """
+    ...

keplemon/bodies.pyi

@@ -1,8 +1,20 @@
 # flake8: noqa
-from keplemon.elements import TLE, CartesianState, Ephemeris
+from keplemon.elements import (
+    TLE,
+    CartesianState,
+    Ephemeris,
+    KeplerianState,
+    GeodeticPosition,
+    OrbitPlotData,
+    TopocentricElements,
+    RelativeState,
+    BoreToBodyAngles,
+)
 from keplemon.catalogs import TLECatalog
 from keplemon.time import Epoch, TimeSpan
-from keplemon.events import CloseApproach, CloseApproachReport
+from keplemon.events import CloseApproach, CloseApproachReport, HorizonAccessReport, FieldOfViewReport
+from keplemon.propagation import ForceProperties
+from keplemon.enums import ReferenceFrame
 
 class Earth:
     @staticmethod
@@ -17,16 +29,27 @@ class Earth:
     def get_kem() -> float: ...
 
 class Satellite:
-    satellite_id: int
-    """Number used to distinguish the satellite from other objects.
-    
-    !!! note
-        Every attempt should be made to make this unique to support satellite methods that perform comparisons or
-        bookkeeping.
+
+    id: str
+    """Unique identifier for the satellite."""
+
+    norad_id: int
+    """Number corresponding to the satellite's NORAD catalog ID.
     """
+
+    force_properties: ForceProperties
+    """Force properties of the satellite used for propagation"""
+
     name: str | None
     """Human-readable name of the satellite"""
 
+    keplerian_state: KeplerianState | None
+    """Keplerian state of the satellite at the epoch of the TLE, if available"""
+
+    geodetic_position: GeodeticPosition | None
+    """Geodetic position of the satellite at the epoch of the TLE, if available"""
+
+    def __init__(self) -> None: ...
     @classmethod
     def from_tle(cls, tle: TLE) -> Satellite:
         """
@@ -59,11 +82,52 @@ class Satellite:
         """
         ...
 
+    def get_relative_state_at_epoch(self, other: Satellite, epoch: Epoch) -> RelativeState | None:
+        """
+        Calculate the relative state between this satellite and another satellite at a given epoch.
+
+        Args:
+            other: Secondary satellite to calculate the relative state against
+            epoch: UTC epoch at which the relative state will be calculated
+        """
+        ...
+
+    def get_body_angles_at_epoch(self, other: Satellite, epoch: Epoch) -> BoreToBodyAngles | None:
+        """
+        Calculate the bore-to-body angles between this satellite and another satellite at a given epoch.
+
+        Args:
+            other: Secondary satellite to calculate the bore-to-body angles against
+            epoch: UTC epoch at which the bore-to-body angles will be calculated
+        """
+        ...
+
+    def get_plot_data(self, start: Epoch, end: Epoch, step: TimeSpan) -> OrbitPlotData | None: ...
+    def get_observatory_access_report(
+        self,
+        observatories: list[Observatory],
+        start: Epoch,
+        end: Epoch,
+        min_el: float,
+        min_duration: TimeSpan,
+    ) -> HorizonAccessReport | None:
+        """
+        Calculate horizon access from multiple observatories to this satellite.
+
+        Args:
+            observatories: List of observatories to check for horizon access
+            start: UTC epoch of the start of the report
+            end: UTC epoch of the end of the report
+            min_el: Minimum elevation angle in **_degrees_**
+            min_duration: Minimum duration of access
+
+        Returns:
+            Horizon access report containing accesses from all observatories to the satellite,
+            or None if the satellite ephemeris cannot be generated
+        """
+        ...
+
 class Constellation:
-    """
-    Args:
-        name: Identifier of the constellation
-    """
 
     count: int
     """Number of satellites in the constellation"""
@@ -71,7 +135,8 @@ class Constellation:
     name: str | None
     """Human-readable name of the constellation"""
 
-    def __init__(self, name: str) -> None: ...
+    def __init__(self) -> None: ...
+    def get_plot_data(self, start: Epoch, end: Epoch, step: TimeSpan) -> dict[str, OrbitPlotData]: ...
     @classmethod
     def from_tle_catalog(cls, tle_catalog: TLECatalog) -> Constellation:
         """
@@ -97,7 +162,7 @@ class Constellation:
         start: Epoch,
         end: Epoch,
         step: TimeSpan,
-    ) -> dict[int, Ephemeris]:
+    ) -> dict[str, Ephemeris]:
         """
         Args:
             start: UTC epoch of the start of the ephemeris
@@ -152,7 +217,30 @@ class Constellation:
         """
         ...
 
-    def __getitem__(self, satellite_id: int) -> Satellite: ...
+    def __getitem__(self, satellite_id: str) -> Satellite: ...
+    def __setitem__(self, satellite_id: str, sat: Satellite) -> None: ...
+    def get_horizon_access_report(
+        self,
+        site: Observatory,
+        start: Epoch,
+        end: Epoch,
+        min_el: float,
+        min_duration: TimeSpan,
+    ) -> HorizonAccessReport:
+        """
+        Calculate horizon access to a given observatory.
+
+        Args:
+            site: Observatory to check for horizon access
+            start: UTC epoch of the start of the report
+            end: UTC epoch of the end of the report
+            min_el: Minimum elevation angle in **_degrees_**
+            min_duration: Minimum duration of access
+
+        Returns:
+            Horizon access report for the constellation from the observatory
+        """
+        ...
 
 class Sensor:
     """
@@ -161,7 +249,9 @@ class Sensor:
         angular_noise: Angular noise in **_degrees_**
     """
 
-    name: str
+    id: str
+    """Unique identifier for the sensor."""
+    name: str | None
     angular_noise: float
     range_noise: float | None
     """Range noise in **_kilometers_**"""
@@ -171,18 +261,19 @@ class Sensor:
 
     angular_rate_noise: float | None
     """Angular rate noise in **_degrees per second_**"""
-    def __init__(self, name: str, angular_noise: float) -> None: ...
+    def __init__(self, angular_noise: float) -> None: ...
 
 class Observatory:
     """
     Args:
-        name: Identifier of the observatory
         latitude: Latitude in **_degrees_**
         longitude: Longitude in **_degrees_**
         altitude: Altitude in **_kilometers_**
     """
 
     name: str
+    id: str
+    """Unique identifier for the observatory."""
     latitude: float
     longitude: float
     altitude: float
@@ -190,7 +281,6 @@ class Observatory:
     """List of sensors at the observatory"""
     def __init__(
         self,
-        name: str,
         latitude: float,
         longitude: float,
         altitude: float,
@@ -204,3 +294,84 @@ class Observatory:
             TEME Cartesian state of the observatory in **_kilometers_** and **_kilometers per second_**
         """
         ...
+
+    @classmethod
+    def from_cartesian_state(cls, state: CartesianState) -> Observatory:
+        """
+        Create an observatory from a Cartesian state.
+
+        Args:
+            state: Cartesian state of the observatory
+
+        """
+        ...
+
+    def get_theta(self, epoch: Epoch) -> float:
+        """
+        Calculate the Greenwich angle plus the observatory longitude at a given epoch.
+
+        Args:
+            epoch: UTC epoch for the calculation
+
+        Returns:
+            Greenwich angle plus the observatory longitude in **_radians_**
+        """
+        ...
+
+    def get_horizon_access_report(
+        self,
+        satellite: Satellite,
+        start: Epoch,
+        end: Epoch,
+        min_el: float,
+        min_duration: TimeSpan,
+    ) -> HorizonAccessReport:
+        """
+        Calculate horizon access for a satellite from the observatory.
+
+        Args:
+            satellite: Satellite to check for horizon access
+            start: UTC epoch of the start of the report
+            end: UTC epoch of the end of the report
+            min_el: Minimum elevation angle in **_degrees_**
+            min_duration: Minimum duration of access in **_seconds_**
+
+        Returns:
+            Horizon access report for the satellite from the observatory
+        """
+        ...
+
+    def get_field_of_view_report(
+        self,
+        epoch: Epoch,
+        sensor_direction: TopocentricElements,
+        angular_threshold: float,
+        sats: Constellation,
+        reference_frame: ReferenceFrame,
+    ) -> FieldOfViewReport:
+        """
+        Calculate satellites in the field of view from a given time and direction.
+
+        Args:
+            epoch: UTC epoch of the report
+            sensor_direction: Topocentric direction the sensor is pointing
+            angular_threshold: Angular threshold in **_degrees_**
+            sats: Constellation of satellites to check for being in the field of view
+            reference_frame: Reference frame of the output direction elements
+        """
+        ...
+
+    def get_topocentric_to_satellite(
+        self,
+        epoch: Epoch,
+        sat: Satellite,
+        reference_frame: ReferenceFrame,
+    ) -> TopocentricElements:
+        """
+        Get the topocentric elements of a satellite as seen from the observatory.
+        Args:
+            epoch: UTC epoch of the observation
+            sat: Satellite to observe
+            reference_frame: Reference frame of the output direction elements
+        """
+        ...

keplemon/catalogs.pyi

@@ -1,5 +1,5 @@
 # flake8: noqa
-from keplemon.elements import TLE
+from keplemon.elements import TLE, OrbitPlotData
 
 class TLECatalog:
     count: int
@@ -8,9 +8,10 @@ class TLECatalog:
     @classmethod
     def from_tle_file(cls, filename: str) -> TLECatalog: ...
     def add(self, tle: TLE) -> None: ...
-    def get(self, satellite_id: int) -> TLE: ...
-    def remove(self, satellite_id: int) -> None: ...
-    def keys(self) -> list[int]: ...
+    def get(self, satellite_id: str) -> TLE: ...
+    def remove(self, satellite_id: str) -> None: ...
+    def keys(self) -> list[str]: ...
     def get_count(self) -> int: ...
     def clear(self) -> None: ...
-    def __getitem__(self, satellite_id: int) -> TLE: ...
+    def __getitem__(self, satellite_id: str) -> TLE: ...
+    def get_plot_data(self) -> OrbitPlotData: ...

keplemon/elements.py

@@ -7,6 +7,14 @@ from keplemon._keplemon.elements import (  # type: ignore
     Ephemeris,
     SphericalVector,
     TopocentricElements,
+    HorizonState,
+    HorizonElements,
+    GeodeticPosition,
+    OrbitPlotData,
+    OrbitPlotState,
+    RelativeState,
+    BoreToBodyAngles,
+    TopocentricState,
 )
 
 __all__ = [
@@ -18,4 +26,12 @@ __all__ = [
     "Ephemeris",
     "SphericalVector",
     "TopocentricElements",
+    "HorizonState",
+    "HorizonElements",
+    "GeodeticPosition",
+    "OrbitPlotData",
+    "OrbitPlotState",
+    "RelativeState",
+    "BoreToBodyAngles",
+    "TopocentricState",
 ]

keplemon/elements.pyi

@@ -2,8 +2,112 @@
 from __future__ import annotations
 from keplemon.time import Epoch
 from keplemon.enums import Classification, KeplerianType, ReferenceFrame
-from keplemon.propagation import ForceProperties
 from keplemon.events import CloseApproach
+from keplemon.bodies import Observatory
+
+class RelativeState:
+    epoch: Epoch
+    position: CartesianVector
+    velocity: CartesianVector
+    origin_satellite_id: str
+    secondary_satellite_id: str
+
+class BoreToBodyAngles:
+    earth_angle: float
+    sun_angle: float
+    moon_angle: float
+
+class OrbitPlotData:
+    satellite_id: str
+    epochs: list[str]
+    semi_major_axes: list[float]
+    eccentricities: list[float]
+    inclinations: list[float]
+    raans: list[float]
+    radii: list[float]
+    apogee_radii: list[float]
+    perigee_radii: list[float]
+    latitudes: list[float]
+    longitudes: list[float]
+    altitudes: list[float]
+
+class GeodeticPosition:
+    """
+    Args:
+        latitude: Latitude in **_degrees_**
+        longitude: Longitude in **_degrees_**
+        altitude: Altitude in **_kilometers_**
+    """
+
+    latitude: float
+    """Latitude in **_degrees_**"""
+
+    longitude: float
+    """Longitude in **_degrees_**"""
+
+    altitude: float
+    """Altitude in **_kilometers_**"""
+
+    def __init__(self, latitude: float, longitude: float, altitude: float) -> None: ...
+
+class HorizonElements:
+    """
+    Args:
+        range: Range in **_kilometers_**
+        az: Azimuth in **_degrees_**
+        el: Elevation in **_degrees_**
+        range_rate: Range rate in **_kilometers per second_**
+        az_rate: Azimuth rate in **_degrees per second_**
+        el_rate: Elevation rate in **_degrees per second_**
+    """
+
+    range: float | None
+    azimuth: float
+    elevation: float
+    range_rate: float | None
+    azimuth_rate: float | None
+    elevation_rate: float | None
+
+    def __init__(
+        self,
+        azimuth: float,
+        elevation: float,
+    ) -> None: ...
+
+class HorizonState:
+    """
+    Args:
+        epoch: UTC epoch of the state
+        elements: HorizonElements of the state
+    """
+
+    epoch: Epoch
+    """UTC epoch of the state"""
+
+    elements: HorizonElements
+    """Horizon elements of the state"""
+
+    range: float | None
+    """Range in **_kilometers_**"""
+
+    azimuth: float
+    """Azimuth in **_degrees_**"""
+
+    elevation: float
+    """Elevation in **_degrees_**"""
+
+    range_rate: float | None
+    """Range rate in **_kilometers per second_**"""
+
+    azimuth_rate: float | None
+    """Azimuth rate in **_degrees per second_**"""
+
+    elevation_rate: float | None
+    """Elevation rate in **_degrees per second_**"""
+
+    def __init__(self, epoch: Epoch, elements: HorizonElements) -> None: ...
+    @classmethod
+    def from_topocentric_state(cls, state: TopocentricState, observer: Observatory) -> HorizonState: ...
 
 class KeplerianElements:
     """
@@ -34,7 +138,11 @@ class KeplerianElements:
     ) -> None: ...
 
 class TLE:
-    satellite_id: int
+
+    norad_id: int
+    """NORAD catalog ID of the satellite"""
+
+    satellite_id: str
     """"""
 
     name: str
@@ -88,6 +196,13 @@ class TLE:
     cartesian_state: CartesianState
     """TEME cartesian state of the TLE at epoch"""
 
+    semi_major_axis: float
+    """Average distance from the central body in **_kilometers_**
+    
+    !!! note
+        This is always calculated using Brouwer mean motion and will differ slightly from Kozai-computed SMA.
+    """
+
     @classmethod
     def from_lines(cls, line_1: str, line_2: str, line_3: str | None = None) -> TLE:
         """
@@ -284,8 +399,8 @@ class Ephemeris:
 class TopocentricElements:
     """
     Args:
-        ra: TEME right ascension in **_degrees_**
-        dec: TEME declination in **_degrees_**
+        right_ascension: TEME right ascension in **_degrees_**
+        declination: TEME declination in **_degrees_**
     """
 
     range: float | None
@@ -302,7 +417,7 @@ class TopocentricElements:
     declination_rate: float | None
     """Declination rate in **_degrees per second**"""
 
-    def __init__(self, ra: float, dec: float) -> None: ...
+    def __init__(self, right_ascension: float, declination: float) -> None: ...
     @classmethod
     def from_j2000(cls, epoch: Epoch, ra: float, dec: float) -> TopocentricElements:
         """
@@ -312,3 +427,44 @@ class TopocentricElements:
             dec: J2000 declination in **_degrees_**
         """
         ...
+
+class TopocentricState:
+    """
+    Args:
+        epoch: UTC epoch of the state
+        elements: TopocentricElements of the state
+    """
+
+    epoch: Epoch
+    """UTC epoch of the state"""
+
+    elements: TopocentricElements
+    """Topocentric elements of the state"""
+
+    range: float | None
+    """Range in **_kilometers_**"""
+
+    right_ascension: float
+    """TEME right ascension in **_degrees_**"""
+
+    declination: float
+    """TEME declination in **_degrees_**"""
+
+    range_rate: float | None
+    """Range rate in **_kilometers per second_**"""
+
+    right_ascension_rate: float | None
+    """Right ascension rate in **_degrees per second**"""
+
+    declination_rate: float | None
+    """Declination rate in **_degrees per second**"""
+
+    def __init__(self, epoch: Epoch, elements: TopocentricElements) -> None: ...
+    @classmethod
+    def from_horizon_state(cls, horizon_state: HorizonState, observer: Observatory) -> TopocentricState:
+        """
+        Args:
+            horizon_state: HorizonState of the target
+            observer: Position of the observer
+        """
+        ...

keplemon/estimation.pyi

@@ -13,10 +13,13 @@ class Observation:
     Args:
         sensor: Sensor that made the observation
         epoch: Time of the observation
-        observed_teme_topo: Topocentric elements of the satellite at the time of observation
-        observer_teme_pos: Position of the observer in TEME coordinates
+        observed_teme_topocentric: Topocentric elements of the satellite at the time of observation
+        observer_teme_position: Position of the observer in TEME coordinates
     """
 
+    id: str
+    """Unique identifier for the observation"""
+
     sensor: Sensor
     """Sensor which produced the observation"""
 
@@ -48,8 +51,8 @@ class Observation:
         self,
         sensor: Sensor,
         epoch: Epoch,
-        observed_teme_topo: TopocentricElements,
-        observer_teme_pos: CartesianVector,
+        observed_teme_topocentric: TopocentricElements,
+        observer_teme_position: CartesianVector,
     ) -> None: ...
     def get_residual(self, sat: Satellite) -> ObservationResidual | None:
         """

keplemon/events.py

@@ -1,6 +1,17 @@
 from keplemon._keplemon.events import (  # type: ignore
     CloseApproach,
     CloseApproachReport,
+    HorizonAccess,
+    HorizonAccessReport,
+    FieldOfViewCandidate,
+    FieldOfViewReport,
 )
 
-__all__ = ["CloseApproach", "CloseApproachReport"]
+__all__ = [
+    "CloseApproach",
+    "CloseApproachReport",
+    "HorizonAccess",
+    "HorizonAccessReport",
+    "FieldOfViewCandidate",
+    "FieldOfViewReport",
+]