Spacecraft

The spacecraft asset is the central dynamic object in ASTROLAB. It provides Orekit-backed state queries, propagation configuration, attitude information, physical properties, optional mesh metadata, constraints, and timeline bounds.

Role in the System

Spacecraft assets are used by:

Consumer	Use of spacecraft
2D/3D viewers	Position, velocity, attitude, mesh, orbit color, and time updates.
Coverage analysis	Source endpoint for access to grid points or AOIs.
Link analysis	Source or target endpoint for contact windows and RF geometry.
Power analysis	Parent for solar arrays and batteries; provides eclipse and Sun geometry context.
Lifetime analysis	Initial state, mass, drag/SRP properties, atmosphere and propagation settings.

Spacecraft Data Blocks

flowchart TD
    S["SpacecraftAsset"] --> G["Generic Properties"]
    S --> O["Orbit Definition"]
    S --> W["Orbit Wizard"]
    S --> A["Attitude Properties"]
    S --> M["Mesh Properties"]
    S --> C["Constraints"]
    S --> R["Runtime Propagator"]
    S --> E["Generated Ephemeris"]

Generic Properties

These properties define spacecraft physical behaviour and propagation configuration.

UI/Model field	Meaning	Typical use
asset_id	Spacecraft name.	Display, reports, registry lookup.
mass	Spacecraft mass in kg.	Propagation, drag, SRP, lifetime, power reports.
cd	Drag coefficient.	Drag acceleration and lifetime analysis.
drag_area	Cross-sectional drag area in m2.	Atmospheric drag model.
cr	Reflectivity coefficient.	Solar radiation pressure.
reflectivity_area	SRP area in m2.	Solar radiation pressure and lifetime settings.

Propagator Settings

The spacecraft dialog supports several propagation families.

Propagator	Purpose	Notes
Keplerian	Fast two-body baseline.	Useful for early visualization or simple checks.
Eckstein Hechler	Analytical Earth gravity perturbation model.	Useful for near-circular LEO-style studies where applicable.
DSST Propagator	Semi-analytical long-term propagation.	Recommended for lifetime-style studies and longer spans.
Numerical Propagator	High-fidelity short-term propagation.	More expensive; sensitive to tolerances and force model setup.

Numerical and DSST modes enable the advanced propagation fields:

Field	Meaning
min_step	Minimum integration step size.
max_step	Maximum integration step size.
abs_tol	Absolute integration tolerance.
rel_tol	Relative integration tolerance.
gravity_degree	Gravity field degree.
gravity_order	Gravity field order.
include_drag	Enables atmosphere drag force model.
include_srp	Enables solar radiation pressure.
include_point_masses	Enables Sun/Moon third-body effects where supported.

Environment and Atmosphere

When drag is enabled, the spacecraft environment block selects the atmospheric model and space weather source.

Field	Options currently exposed	Notes
atmosphere_model	NRLMSISE-00, DTM2000, Harris-Priester, Simple Exponential, JB2008	Availability depends on Orekit initializer support and loaded data.
space_weather_source	CSSI Space Weather, Marshall Solar Activity Forecast	Used by atmosphere models that require solar/geomagnetic input.
solar_activity_level	Low, Moderate, High	Intended for forecast-driven scenarios.

State Query Contract

The spacecraft exposes a frame-aware physical interface:

Method	Returns
get_position_at(time, frame_name)	Position vector in meters.
get_velocity_at(time, frame_name)	Velocity vector in m/s.
get_attitude_at(time, frame_name)	Quaternion [w, x, y, z].
get_pose_at(time, frame_name)	Combined position, velocity, and quaternion snapshot.
get_geodetic_at(time)	Latitude, longitude, altitude on the Earth ellipsoid.

The internal quaternion convention is an active rotation using [w, x, y, z], representing model/body orientation expressed in the requested frame.

Ephemeris Behaviour

The spacecraft may generate a bounded ephemeris for faster repeated queries. If an ephemeris exists, state queries use it. If not, ASTROLAB falls back to direct propagation.

flowchart TD
    Q["State query at time t"] --> E{"Ephemeris available?"}
    E -->|Yes| B["BoundedPropagator.propagate(t)"]
    E -->|No| P["Propagator.propagate(t)"]
    B --> S["SpacecraftState"]
    P --> S
    S --> PV["PV in requested frame"]
    S --> ATT["Attitude in requested frame"]
    PV --> POSE["PoseSnapshot"]
    ATT --> POSE

Best Practices

• Use the simplest propagator that answers the study question.
• Use DSST for long-term lifetime-style analysis rather than a very tight numerical propagator.
• Keep drag area, mass, and Cd consistent with the physical spacecraft.
• Use constraints to represent mission rules rather than hard-coding filtering logic in analyses.
• Validate the first few propagated points visually before relying on long reports.