astrox-python 0.1.0__py3-none-any.whl

astrox/access.py

@@ -0,0 +1,173 @@
+"""Access analysis functions and access-owned chain fragments."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any
+
+from astrox import components
+from astrox._http import raw
+
+__all__ = [
+    "Connection",
+    "chain",
+    "compute",
+    "connection",
+]
+
+
+def _include_if_supplied(payload: dict[str, Any], wire_key: str, value: Any) -> None:
+    if value is not None:
+        payload[wire_key] = value
+
+
+def _entity_to_wire(entity: components.Entity, *, parameter: str) -> dict[str, Any]:
+    if not isinstance(entity, components.Entity):
+        raise TypeError(f"{parameter} must be an astrox.components.Entity value")
+    return entity.to_wire()
+
+
+def _participant_name(
+    value: components.Entity | components.EntityGroup | str,
+    *,
+    parameter: str,
+) -> str:
+    if isinstance(value, components.Entity):
+        return value.name
+    if isinstance(value, components.EntityGroup):
+        return value.name
+    if isinstance(value, str):
+        return value
+    raise TypeError(f"{parameter} must be an Entity, EntityGroup, or string name")
+
+
+def _participant_to_wire(
+    value: components.Entity | components.EntityGroup,
+    *,
+    parameter: str,
+) -> dict[str, Any]:
+    if isinstance(value, components.Entity):
+        return {"$type": "EntityPath", **value.to_wire()}
+    if isinstance(value, components.EntityGroup):
+        return value.to_wire()
+    raise TypeError(f"{parameter} items must be Entity or EntityGroup values")
+
+
+def _participants_to_wire(
+    values: Sequence[components.Entity | components.EntityGroup],
+) -> list[dict[str, Any]]:
+    if isinstance(values, (str, bytes)) or not isinstance(values, Sequence):
+        raise TypeError("participants must be a sequence of Entity or EntityGroup values")
+    return [
+        _participant_to_wire(value, parameter="participants")
+        for value in values
+    ]
+
+
+def _connections_to_wire(values: Sequence[Connection]) -> list[dict[str, Any]]:
+    if isinstance(values, (str, bytes)) or not isinstance(values, Sequence):
+        raise TypeError("connections must be a sequence of Connection values")
+    items = list(values)
+    if not all(isinstance(item, Connection) for item in items):
+        raise TypeError("connections must be a sequence of Connection values")
+    return [item.to_wire() for item in items]
+
+
+@dataclass(frozen=True, kw_only=True)
+class Connection:
+    """Explicit access-chain connection between named participants."""
+
+    from_participant: components.Entity | components.EntityGroup | str
+    to_participant: components.Entity | components.EntityGroup | str
+    min_uses: int | None = None
+    max_uses: int | None = None
+
+    def to_wire(self) -> dict[str, Any]:
+        """Lower to the ASTROX LinkConnection fragment."""
+        payload: dict[str, Any] = {
+            "FromObject": _participant_name(
+                self.from_participant,
+                parameter="from_participant",
+            ),
+            "ToObject": _participant_name(
+                self.to_participant,
+                parameter="to_participant",
+            ),
+        }
+        _include_if_supplied(payload, "MinUses", self.min_uses)
+        _include_if_supplied(payload, "MaxUses", self.max_uses)
+        return payload
+
+
+def connection(
+    from_participant: components.Entity | components.EntityGroup | str,
+    to_participant: components.Entity | components.EntityGroup | str,
+    *,
+    min_uses: int | None = None,
+    max_uses: int | None = None,
+) -> Connection:
+    """Create an explicit access-chain connection fragment."""
+    _participant_name(from_participant, parameter="from_participant")
+    _participant_name(to_participant, parameter="to_participant")
+    return Connection(
+        from_participant=from_participant,
+        to_participant=to_participant,
+        min_uses=min_uses,
+        max_uses=max_uses,
+    )
+
+
+def compute(
+    *,
+    start: str,
+    stop: str,
+    from_entity: components.Entity,
+    to_entity: components.Entity,
+    step_s: float | None = None,
+    compute_aer: bool | None = None,
+    use_light_time_delay: bool | None = None,
+) -> dict[str, Any]:
+    """Compute direct access between two entities."""
+    payload: dict[str, Any] = {
+        "Start": start,
+        "Stop": stop,
+        "FromObjectPath": _entity_to_wire(from_entity, parameter="from_entity"),
+        "ToObjectPath": _entity_to_wire(to_entity, parameter="to_entity"),
+    }
+    _include_if_supplied(payload, "OutStep", step_s)
+    _include_if_supplied(payload, "ComputeAER", compute_aer)
+    _include_if_supplied(payload, "UseLightTimeDelay", use_light_time_delay)
+
+    return raw.post("/access/AccessComputeV2", json=payload)
+
+
+def chain(
+    *,
+    start: str,
+    stop: str,
+    participants: Sequence[components.Entity | components.EntityGroup],
+    start_participant: components.Entity | components.EntityGroup | str,
+    end_participant: components.Entity | components.EntityGroup | str,
+    connections: Sequence[Connection] | None = None,
+    use_light_time_delay: bool | None = None,
+) -> dict[str, Any]:
+    """Compute access over a named direct or multi-hop participant chain."""
+    payload: dict[str, Any] = {
+        "Start": start,
+        "Stop": stop,
+        "AllObjects": _participants_to_wire(participants),
+        "StartObject": _participant_name(
+            start_participant,
+            parameter="start_participant",
+        ),
+        "EndObject": _participant_name(end_participant, parameter="end_participant"),
+        "Connections": (
+            _connections_to_wire(connections)
+            if connections is not None
+            else None
+        ),
+    }
+    _include_if_supplied(payload, "UseLightTimeDelay", use_light_time_delay)
+
+    return raw.post("/access/ChainCompute", json=payload)

astrox/components/__init__.py

@@ -0,0 +1,202 @@
+"""Public reusable component value objects for ASTROX SDK workflows.
+
+ASTROX uses the word ``Orientation`` at two different levels. Entity
+``Orientation`` fields are coordinate axes definitions from the ``CrdnAxes``
+schema family: VVLH, LVLH, VNC, Fixed, FixedAtEpoch, Composite, and CZML-backed
+axes. Sensor pointing and fixed axes then contain smaller Az/El, quaternion, or
+Euler-angle orientation fragments. The SDK names those two levels separately:
+public constructors and dataclasses use ``Axes`` for entity-level attitude
+frames and ``Rotation`` for the inner Az/El, quaternion, or Euler fragments.
+"""
+
+from __future__ import annotations
+
+from ._axes import (
+    AlignedAndConstrainedAxes,
+    CompositeAxes,
+    CzmlAxes,
+    EntityAxes,
+    FixedAtEpochAxes,
+    FixedAxes,
+    LvlhAxes,
+    VncAxes,
+    VvlhAxes,
+    _axes_reference_name,
+    _axes_to_wire,
+    aligned_and_constrained_axes,
+    composite_axes,
+    czml_axes,
+    fixed_at_epoch_axes,
+    fixed_axes,
+    lvlh_axes,
+    vnc_axes,
+    vvlh_axes,
+)
+from ._constraints import (
+    AzElMaskConstraint,
+    Constraint,
+    ElevationConstraint,
+    RangeConstraint,
+    _constraint_to_wire,
+    az_el_mask_constraint,
+    elevation_constraint,
+    range_constraint,
+)
+from ._objects import Entity, EntityGroup, entity, entity_group
+from ._positions import (
+    BallisticPosition,
+    CentralBodyPosition,
+    CzmlPosition,
+    CzmlPositionSTM,
+    CzmlPositions,
+    EntityPosition,
+    HpopPosition,
+    J2Position,
+    Sgp4Position,
+    SimpleAscentPosition,
+    SitePosition,
+    TwoBodyPosition,
+    _position_to_wire,
+    _site_position_to_wire,
+    ballistic_position,
+    central_body_position,
+    czml_position,
+    czml_positions,
+    hpop_position,
+    j2_position,
+    sgp4_position,
+    simple_ascent_position,
+    site_position,
+    two_body_position,
+)
+from ._rotations import (
+    AzElRotation,
+    EulerRotation,
+    QuaternionRotation,
+    Rotation,
+    _rotation_to_wire,
+    az_el_rotation,
+    euler_rotation,
+    quaternion_rotation,
+)
+from ._sensors import (
+    ConicSensor,
+    EntitySensor,
+    FixedSensorPointing,
+    RectangularSensor,
+    SensorPointing,
+    _sensor_pointing_to_wire,
+    _sensor_to_wire,
+    conic_sensor,
+    fixed_sensor_pointing,
+    rectangular_sensor,
+)
+from ._vgt import (
+    RaDecDirection,
+    VgtAngle,
+    VgtDirection,
+    VgtFixedVector,
+    VgtPlane,
+    VgtPoint,
+    VgtProvider,
+    VgtSystem,
+    VgtVector,
+    XyzDirection,
+    _direction_to_wire,
+    _vector_reference_name,
+    _vgt_to_wire,
+    ra_dec_direction,
+    vgt,
+    vgt_angle,
+    vgt_fixed_vector,
+    vgt_plane,
+    vgt_point,
+    vgt_system,
+    xyz_direction,
+)
+
+__all__ = [
+    "AlignedAndConstrainedAxes",
+    "AzElRotation",
+    "BallisticPosition",
+    "CentralBodyPosition",
+    "AzElMaskConstraint",
+    "ConicSensor",
+    "CompositeAxes",
+    "Constraint",
+    "CzmlPosition",
+    "CzmlPositionSTM",
+    "CzmlPositions",
+    "CzmlAxes",
+    "ElevationConstraint",
+    "Entity",
+    "EntityAxes",
+    "EntityGroup",
+    "EntityPosition",
+    "EntitySensor",
+    "EulerRotation",
+    "FixedAtEpochAxes",
+    "FixedAxes",
+    "FixedSensorPointing",
+    "HpopPosition",
+    "J2Position",
+    "LvlhAxes",
+    "QuaternionRotation",
+    "RangeConstraint",
+    "RectangularSensor",
+    "Rotation",
+    "RaDecDirection",
+    "SensorPointing",
+    "Sgp4Position",
+    "SitePosition",
+    "SimpleAscentPosition",
+    "TwoBodyPosition",
+    "VgtAngle",
+    "VgtDirection",
+    "VgtFixedVector",
+    "VgtPlane",
+    "VgtPoint",
+    "VgtProvider",
+    "VgtSystem",
+    "VgtVector",
+    "VncAxes",
+    "VvlhAxes",
+    "XyzDirection",
+    "aligned_and_constrained_axes",
+    "az_el_rotation",
+    "az_el_mask_constraint",
+    "ballistic_position",
+    "central_body_position",
+    "conic_sensor",
+    "composite_axes",
+    "czml_position",
+    "czml_positions",
+    "czml_axes",
+    "entity",
+    "entity_group",
+    "euler_rotation",
+    "elevation_constraint",
+    "fixed_axes",
+    "fixed_at_epoch_axes",
+    "fixed_sensor_pointing",
+    "hpop_position",
+    "j2_position",
+    "lvlh_axes",
+    "quaternion_rotation",
+    "range_constraint",
+    "ra_dec_direction",
+    "rectangular_sensor",
+    "vgt",
+    "vgt_angle",
+    "vgt_fixed_vector",
+    "vgt_plane",
+    "vgt_point",
+    "vgt_system",
+    "vnc_axes",
+    "vvlh_axes",
+    "xyz_direction",
+    "sgp4_position",
+    "site_position",
+    "simple_ascent_position",
+    "two_body_position",
+]