open-space-toolkit-astrodynamics 16.2.0__py312-none-manylinux2014_x86_64.whl → 16.4.0__py312-none-manylinux2014_x86_64.whl

ostk/astrodynamics/trajectory/model.pyi

@@ -0,0 +1,259 @@
+from __future__ import annotations
+import ostk.astrodynamics.trajectory
+import ostk.mathematics.curve_fitting
+import ostk.physics.coordinate.spherical
+import ostk.physics.environment.object
+import ostk.physics.time
+import ostk.physics.unit
+import typing
+__all__ = ['Nadir', 'Tabulated', 'TargetScan']
+class Nadir(ostk.astrodynamics.trajectory.Model):
+    """
+    
+                Nadir trajectory model.
+    
+                This model represents a trajectory that follows the nadir direction of an orbit.
+            
+    """
+    __hash__: typing.ClassVar[None] = None
+    def __eq__(self, arg0: Nadir) -> bool:
+        ...
+    def __init__(self, orbit: ostk.astrodynamics.trajectory.Orbit, step_size: ostk.physics.time.Duration = ...) -> None:
+        """
+                        Construct a `Nadir` object from an orbit.
+        
+                        Args:
+                            orbit (Orbit): The orbit.
+                            step_size (Duration): The step size for the trajectory. Defaults to 1e-2 seconds.
+        
+                        Returns:
+                            Nadir: The `Nadir` object.
+        """
+    def __ne__(self, arg0: Nadir) -> bool:
+        ...
+    def __repr__(self) -> str:
+        ...
+    def __str__(self) -> str:
+        ...
+    def calculate_state_at(self, instant: ostk.physics.time.Instant) -> ostk.astrodynamics.trajectory.State:
+        """
+                        Calculate the state at a given instant.
+        
+                        Args:
+                            instant (Instant): The instant.
+        
+                        Returns:
+                            State: The state at the given instant.
+        """
+    def get_orbit(self) -> ostk.astrodynamics.trajectory.Orbit:
+        """
+                        Get the orbit of the nadir model.
+        
+                        Returns:
+                            Orbit: The orbit of the nadir model.
+        """
+    def get_step_size(self) -> ostk.physics.time.Duration:
+        """
+                        Get the step size of the nadir model.
+        
+                        Returns:
+                            Duration: The step size of the nadir model.
+        """
+    def is_defined(self) -> bool:
+        """
+                        Check if the model is defined.
+        
+                        Returns:
+                            bool: True if the model is defined, False otherwise.
+        """
+class Tabulated(ostk.astrodynamics.trajectory.Model):
+    """
+    
+                A trajectory model defined by a set of states.
+    
+            
+    """
+    def __init__(self, states: list[ostk.astrodynamics.trajectory.State], interpolation_type: ostk.mathematics.curve_fitting.Interpolator.Type = ...) -> None:
+        """
+                        Constructor.
+        
+                        Args:
+                            states (Array[State]): The states of the model.
+                            interpolation_type (Interpolator.Type): The type of interpolation to use. Defaults to Linear.
+        """
+    def __repr__(self) -> str:
+        """
+                        Convert the model to a string.
+        
+                        Returns:
+                            str: The string representation of the model.
+        """
+    def __str__(self) -> str:
+        """
+                        Convert the model to a string.
+        
+                        Returns:
+                            str: The string representation of the model.
+        """
+    def calculate_state_at(self, instant: ostk.physics.time.Instant) -> ostk.astrodynamics.trajectory.State:
+        """
+                        Calculate the state of the model at a specific instant.
+        
+                        Args:
+                            instant (Instant): The instant at which to calculate the state.
+        
+                        Returns:
+                            State: The state of the model at the specified instant.
+        """
+    def calculate_states_at(self, instants: list[ostk.physics.time.Instant]) -> list[ostk.astrodynamics.trajectory.State]:
+        """
+                        Calculate the states of the model at the specified instants.
+        
+                        Args:
+                            instants (list[Instant]): The instants at which to calculate the states.
+        
+                        Returns:
+                            list[State]: The states of the model at the specified instants.
+        """
+    def get_first_state(self) -> ostk.astrodynamics.trajectory.State:
+        """
+                        Get the first state of the model.
+        
+                        Returns:
+                            State: The first state of the model.
+        """
+    def get_interpolation_type(self) -> ostk.mathematics.curve_fitting.Interpolator.Type:
+        """
+                        Get the interpolation type of the model.
+        
+                        Returns:
+                            Interpolator.Type: The interpolation type of the model.
+        """
+    def get_interval(self) -> ostk.physics.time.Interval:
+        """
+                        Get the interval of the model.
+        
+                        Returns:
+                            Interval: The interval of the model.
+        """
+    def get_last_state(self) -> ostk.astrodynamics.trajectory.State:
+        """
+                        Get the last state of the model.
+        
+                        Returns:
+                            State: The last state of the model.
+        """
+    def is_defined(self) -> bool:
+        """
+                        Check if the model is defined.
+        
+                        Returns:
+                            bool: True if the model is defined, False otherwise.
+        """
+class TargetScan(ostk.astrodynamics.trajectory.Model):
+    """
+    
+                TargetScan trajectory model.
+    
+                This model represents a trajectory that scans between two target locations on a celestial body.
+            
+    """
+    __hash__: typing.ClassVar[None] = None
+    @staticmethod
+    def from_ground_speed(start_lla: ostk.physics.coordinate.spherical.LLA, end_lla: ostk.physics.coordinate.spherical.LLA, ground_speed: ostk.physics.unit.Derived, start_instant: ostk.physics.time.Instant, celestial: ostk.physics.environment.object.Celestial = ..., step_size: ostk.physics.time.Duration = ...) -> TargetScan:
+        """
+                        Construct a `TargetScan` object from ground speed.
+        
+                        Args:
+                            start_lla (LLA): The starting location.
+                            end_lla (LLA): The ending location.
+                            ground_speed (Derived): The ground speed.
+                            start_instant (Instant): The starting instant.
+                            celestial (Celestial): The celestial body.
+                            step_size (Duration): The step size for the trajectory.
+        
+                        Returns:
+                            TargetScan: The `TargetScan` object.
+        """
+    def __eq__(self, arg0: TargetScan) -> bool:
+        ...
+    def __init__(self, start_lla: ostk.physics.coordinate.spherical.LLA, end_lla: ostk.physics.coordinate.spherical.LLA, start_instant: ostk.physics.time.Instant, end_instant: ostk.physics.time.Instant, celestial: ostk.physics.environment.object.Celestial = ..., step_size: ostk.physics.time.Duration = ...) -> None:
+        """
+                        Construct a `TargetScan` object.
+        
+                        Args:
+                            start_lla (LLA): The starting location.
+                            end_lla (LLA): The ending location.
+                            start_instant (Instant): The starting instant.
+                            end_instant (Instant): The ending instant.
+                            celestial (Celestial): The celestial body. Defaults to Earth.WGS84().
+                            step_size (Duration): The step size for the trajectory. Defaults to 1e-2 seconds.
+        
+                        Returns:
+                            TargetScan: The `TargetScan` object.
+        """
+    def __ne__(self, arg0: TargetScan) -> bool:
+        ...
+    def __repr__(self) -> str:
+        ...
+    def __str__(self) -> str:
+        ...
+    def calculate_state_at(self, instant: ostk.physics.time.Instant) -> ostk.astrodynamics.trajectory.State:
+        """
+                        Calculate the state at a given instant.
+        
+                        Args:
+                            instant (Instant): The instant.
+        
+                        Returns:
+                            State: The state at the given instant.
+        """
+    def get_celestial(self) -> ostk.physics.environment.object.Celestial:
+        """
+                        Get the celestial object of the target scan.
+        
+                        Returns:
+                            Celestial: The celestial object.
+        """
+    def get_end_instant(self) -> ostk.physics.time.Instant:
+        """
+                        Get the ending instant of the target scan.
+        
+                        Returns:
+                            Instant: The ending instant.
+        """
+    def get_end_lla(self) -> ostk.physics.coordinate.spherical.LLA:
+        """
+                        Get the ending LLA of the target scan.
+        
+                        Returns:
+                            LLA: The ending LLA.
+        """
+    def get_start_instant(self) -> ostk.physics.time.Instant:
+        """
+                        Get the starting instant of the target scan.
+        
+                        Returns:
+                            Instant: The starting instant.
+        """
+    def get_start_lla(self) -> ostk.physics.coordinate.spherical.LLA:
+        """
+                        Get the starting LLA of the target scan.
+        
+                        Returns:
+                            LLA: The starting LLA.
+        """
+    def get_step_size(self) -> ostk.physics.time.Duration:
+        """
+                        Get the step size of the target scan.
+        
+                        Returns:
+                            Duration: The step size.
+        """
+    def is_defined(self) -> bool:
+        """
+                        Check if the model is defined.
+        
+                        Returns:
+                            bool: True if the model is defined, False otherwise.
+        """

ostk/astrodynamics/viewer.py

@@ -16,6 +16,7 @@ except ImportError:
 
 from ostk.mathematics.geometry.d3.transformation.rotation import Quaternion
 
+from ostk.physics.environment.object import Celestial
 from ostk.physics.unit import Length
 from ostk.physics.unit import Angle
 from ostk.physics.time import Instant, Interval, Duration
@@ -23,16 +24,20 @@ from ostk.physics.coordinate import Position
 from ostk.physics.coordinate import Frame
 from ostk.physics.coordinate.spherical import LLA
 
+from ostk.astrodynamics import Trajectory
 from ostk.astrodynamics.flight import Profile
 from ostk.astrodynamics.trajectory import Orbit
 from ostk.astrodynamics.trajectory import State
 
 from .converters import coerce_to_datetime
 from .utilities import lla_from_position
+from .utilities import lla_from_state
+from .utilities import position_from_lla
 
 DEFAULT_SATELLITE_IMAGE: str = (
     "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAADJSURBVDhPnZHRDcMgEEMZjVEYpaNklIzSEfLfD4qNnXAJSFWfhO7w2Zc0Tf9QG2rXrEzSUeZLOGm47WoH95x3Hl3jEgilvDgsOQUTqsNl68ezEwn1vae6lceSEEYvvWNT/Rxc4CXQNGadho1NXoJ+9iaqc2xi2xbt23PJCDIB6TQjOC6Bho/sDy3fBQT8PrVhibU7yBFcEPaRxOoeTwbwByCOYf9VGp1BYI1BA+EeHhmfzKbBoJEQwn1yzUZtyspIQUha85MpkNIXB7GizqDEECsAAAAASUVORK5CYII="
 )
+DEFAULT_STEP_DURATION: Duration = Duration.seconds(10.0)
 
 
 @dataclass
@@ -228,14 +233,7 @@ class Viewer:
         satellite = cesiumpy.Satellite(
             position=_generate_sampled_position_from_llas(instants, llas),
             orientation=_generate_sampled_orientation(states),
-            availability=cesiumpy.TimeIntervalCollection(
-                intervals=[
-                    cesiumpy.TimeInterval(
-                        start=coerce_to_datetime(self._interval.get_start()),
-                        stop=coerce_to_datetime(self._interval.get_end()),
-                    ),
-                ],
-            ),
+            availability=self._get_availability(),
             model=cesiumpy.IonResource(
                 asset_id=cesium_asset_id or 0
             ),  # TBM: Should be made more robust
@@ -267,6 +265,158 @@ class Viewer:
 
         return self
 
+    def add_celestial_body_direction(
+        self,
+        profile_or_trajectory: Profile | Trajectory,
+        celestial: Celestial,
+        time_step: Duration | None = None,
+        color: str | None = None,
+    ) -> Viewer:
+        """
+        Add the celestial direction to the viewer.
+
+        Args:
+            profile_or_trajectory (Profile | Trajectory): The profile or trajectory to be added.
+            celestial (Celestial, optional): The celestial body to be used.
+            time_step (Duration): The duration of each step in the grid.
+                Default to None. If None, the default step duration is used.
+            color (str, optional): The color of the celestial body direction.
+                Defaults to None. If None, the color depends on the celestial body (for the Earth, Sun and Moon).
+                Otherwise, use the default color (RED).
+
+        Returns:
+            Viewer: The Viewer.
+        """
+        time_step = time_step or DEFAULT_STEP_DURATION
+        alpha_color: float = 0.5
+        reference_frame: Frame = Frame.GCRF()
+        reference_vector: np.ndarray = np.array([0.0, 0.0, 1.0])
+        instants: list[Instant] = self._interval.generate_grid(time_step)
+        celestial_name: str = str(celestial.access_name())
+
+        if color is None:
+            if celestial_name == "Earth":
+                color = cesiumpy.color.BLUE
+            elif celestial_name == "Moon":
+                color = cesiumpy.color.GREY
+            elif celestial_name == "Sun":
+                color = cesiumpy.color.YELLOW
+            else:
+                color = cesiumpy.color.RED
+
+            # Apply an alpha to the color
+            color = color.with_alpha(alpha_color)
+
+        def _create_celestial_body_direction_state(
+            satellite_state: State,
+            reference_frame: Frame = reference_frame,
+            reference_vector: np.ndarray = reference_vector,
+            celestial: Celestial = celestial,
+        ) -> State:
+            state_in_reference_frame: State = satellite_state.in_frame(reference_frame)
+            return State(
+                instant=state_in_reference_frame.get_instant(),
+                position=state_in_reference_frame.get_position(),
+                velocity=state_in_reference_frame.get_velocity(),
+                attitude=Quaternion.shortest_rotation(
+                    first_vector=_compute_celestial_direction_from_state(
+                        state=satellite_state,
+                        celestial=celestial,
+                        frame=reference_frame,
+                    ),
+                    second_vector=reference_vector,
+                ),
+                angular_velocity=np.zeros(3),
+                attitude_frame=reference_frame,
+            )
+
+        celestial_direction_states: list[State] = list(
+            map(
+                _create_celestial_body_direction_state,
+                profile_or_trajectory.get_states_at(instants),
+            )
+        )
+
+        satellite = cesiumpy.Satellite(
+            position=_generate_sampled_position_from_llas(
+                instants=instants,
+                llas=_generate_llas(celestial_direction_states),
+            ),
+            orientation=_generate_sampled_orientation(celestial_direction_states),
+            availability=self._get_availability(),
+        )
+
+        _cesium_from_ostk_sensor(
+            ConicSensor(
+                name=celestial_name.lower() + "_direction",
+                direction=reference_vector,
+                # Compute the half angle from the celestial body diameter
+                half_angle=Angle.degrees(
+                    _compute_celestial_angular_diameter_from_states(
+                        celestial=celestial,
+                        states=celestial_direction_states,
+                    ).mean()
+                    / 2.0
+                ),
+                length=Length.meters(2.0),
+                color=color,
+            )
+        ).render(
+            viewer=self._viewer,
+            satellite=satellite,
+        )
+
+        return self
+
+    def add_ground_tracks(
+        self,
+        profile_or_trajectory: Profile | Trajectory,
+        time_step: Duration | None = None,
+        show_current_position: bool = True,
+    ) -> Viewer:
+        """
+        Add ground tracks to the viewer.
+
+        Args:
+            profile_or_trajectory (Profile | Trajectory): The profile or trajectory to be added.
+            time_step (Duration, optional): The duration of each step in the grid.
+                Default to None. If None, the default step duration is used.
+            show_current_position (bool, optional): Whether to show the current position as a point. Defaults to True.
+
+        Returns:
+            Viewer: The Viewer.
+        """
+        time_step = time_step or DEFAULT_STEP_DURATION
+
+        instants: list[Instant] = self._interval.generate_grid(time_step)
+        llas: list[LLA] = []
+        ground_track_positions: list[Position] = []
+
+        for state in profile_or_trajectory.get_states_at(instants):
+            satellite_lla: LLA = lla_from_state(state)
+            lla: LLA = LLA(
+                latitude=satellite_lla.get_latitude(),
+                longitude=satellite_lla.get_longitude(),
+                altitude=Length.meters(0.0),
+            )
+            llas.append(lla)
+            ground_track_positions.append(position_from_lla(lla))
+
+        self.add_line(
+            positions=ground_track_positions,
+            size=1,
+            color=cesiumpy.color.GRAY,
+        )
+
+        if show_current_position:
+            self.add_moving_point(
+                instants=instants,
+                llas=llas,
+                color=cesiumpy.color.DARKORANGE,
+            )
+
+        return self
+
     def add_target(
         self,
         position: Position,
@@ -341,6 +491,40 @@ class Viewer:
 
         return self
 
+    def add_moving_point(
+        self,
+        instants: list[Instant],
+        llas: list[LLA],
+        color: str | None = None,
+        size: int | None = None,
+    ) -> Viewer:
+        """
+        Add a moving point to the Viewer.
+
+        Args:
+            instants (list[Instant]): The list of instants.
+            llas (list[LLA]): The list of Longitude, Latitude, Altitude (LLA) coordinates.
+            color (str, optional): The color of the point. Defaults to None. If None, the default color is used.
+            size (int, optional): The size of the point. Defaults to None. If None, the default size is used.
+
+        Returns:
+            Viewer: The Viewer.
+        """
+
+        self._viewer.entities.add(
+            cesiumpy.Point(
+                position=_generate_sampled_position_from_llas(
+                    instants=instants,
+                    llas=llas,
+                ),
+                availability=self._get_availability(),
+                color=color,
+                pixel_size=size,
+            )
+        )
+
+        return self
+
     def add_label(
         self,
         position: Position,
@@ -382,14 +566,21 @@ class Viewer:
 
         return self._viewer.to_html()
 
+    def _get_availability(self) -> cesiumpy.TimeIntervalCollection:
+        """
+        Get the availability of the viewer.
+
+        Returns:
+            cesiumpy.TimeIntervalCollection: The availability of the viewer.
+        """
+        return _cesium_from_ostk_intervals(intervals=[self._interval])
+
     def _repr_html_(self) -> str:
         return self.render()
 
 
 def _generate_llas(states: list[State]) -> list[LLA]:
-    return [
-        lla_from_position(state.get_position(), state.get_instant()) for state in states
-    ]
+    return list(map(lla_from_state, states))
 
 
 def _generate_sampled_position_from_llas(
@@ -454,17 +645,38 @@ def _generate_sampled_position_from_states(
     Returns:
         cesiumpy.SampledPositionProperty: Sampled position property.
     """
+    return _generate_sampled_position_from_positions(
+        instants=[state.get_instant() for state in states],
+        positions=[state.get_position() for state in states],
+    )
+
+
+def _generate_sampled_position_from_positions(
+    instants: list[Instant],
+    positions: list[Position],
+) -> cesiumpy.SampledPositionProperty:
+    """
+    Generate a sampled position property from a list of OSTk positions and instants.
+
+    Args:
+        instants (list[Instant]): A list of OSTk instants.
+        positions (list[Position]): A list of OSTk positions.
+
+    Returns:
+        cesiumpy.SampledPositionProperty: Sampled position property.
+    """
+    frame_itrf: Frame = Frame.ITRF()
 
     return cesiumpy.SampledPositionProperty(
         samples=[
             (
-                coerce_to_datetime(state.get_instant()),
+                coerce_to_datetime(instant),
                 _cesium_from_ostk_position(
-                    position=state.in_frame(Frame.ITRF()).get_position()
+                    position.in_frame(instant=instant, frame=frame_itrf)
                 ),
                 None,
             )
-            for state in states
+            for instant, position in zip(instants, positions)
         ],
     )
 
@@ -547,3 +759,93 @@ def _cesium_from_ostk_sensor(sensor: Sensor) -> cesiumpy.Sensor:
         )
 
     raise NotImplementedError("{sensor.__name__} is not supported yet.")
+
+
+def _compute_celestial_direction_from_state(
+    state: State,
+    celestial: Celestial,
+    frame: Frame | None = None,
+) -> np.ndarray:
+    """
+    Compute the direction of a celestial body from a state.
+
+    Args:
+        state (State): The state of the observer.
+        celestial (Celestial): The celestial body.
+        frame (Frame): The frame in which the celestial body is expressed.
+            Defaults to None. If None, the GCRF frame is used.
+
+    Returns:
+        np.ndarray: The direction of the celestial body (in meters).
+    """
+    frame = frame or Frame.GCRF()
+    return (
+        celestial.get_position_in(
+            frame=frame,
+            instant=state.get_instant(),
+        )
+        .in_meters()
+        .get_coordinates()
+        - state.get_position()
+        .in_frame(
+            frame=frame,
+            instant=state.get_instant(),
+        )
+        .in_meters()
+        .get_coordinates()
+    )
+
+
+def _compute_celestial_angular_diameter_from_states(
+    celestial: Celestial,
+    states: list[State],
+) -> np.ndarray:
+    """
+    Compute the angular diameter of a celestial body from the states of an observer.
+
+    Args:
+        celestial (Celestial): The celestial body.
+        states (list[State]): The states of the observer.
+
+    Returns:
+        np.ndarray: The angular diameter of the celestial body (in degrees).
+
+    Reference:
+        https://en.wikipedia.org/wiki/Angular_diameter
+    """
+    celestial_radius_meters: float = float(celestial.get_equatorial_radius().in_meters())
+    celestial_to_observer_meters: np.ndarray = np.zeros((3, len(states)))
+
+    for i, state in enumerate(states):
+        celestial_to_observer_meters[:, i] = (
+            state.in_frame(celestial.access_frame())
+            .get_position()
+            .in_meters()
+            .get_coordinates()
+        )
+    distances: np.ndarray = np.linalg.norm(celestial_to_observer_meters, axis=0)
+    return np.rad2deg(2 * np.arcsin(celestial_radius_meters / distances))
+
+
+def _cesium_from_ostk_intervals(
+    intervals: list[Interval],
+) -> cesiumpy.TimeIntervalCollection:
+    """
+    Convert a list of OSTk intervals into Cesium TimeIntervalCollection.
+
+    Args:
+        intervals (list[Interval]): List of OSTk intervals.
+
+    Returns:
+        cesiumpy.TimeIntervalCollection: Converted intervals.
+    """
+
+    return cesiumpy.TimeIntervalCollection(
+        intervals=[
+            cesiumpy.TimeInterval(
+                start=coerce_to_datetime(interval.get_start()),
+                stop=coerce_to_datetime(interval.get_end()),
+            )
+            for interval in intervals
+        ],
+    )