calculate_ground_track
Compute satellite ground track coordinates from orbital state vectors to visualize orbital paths over Earth's surface for flight planning and analysis.
Instructions
Calculate ground track from orbital state vectors.
Args: orbital_state: Orbital state (elements or state vector) duration_s: Duration for ground track calculation in seconds time_step_s: Time step for ground track points in seconds
Returns: JSON string with ground track coordinates
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| orbital_state | Yes | ||
| duration_s | Yes | ||
| time_step_s | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- aerospace_mcp/fastmcp_server.py:119-119 (registration)Registers the calculate_ground_track tool function with the FastMCP server using mcp.tool().
mcp.tool(calculate_ground_track) - aerospace_mcp/tools/orbits.py:121-145 (handler)The main tool handler registered with MCP. It wraps the core implementation, handles input/output as JSON strings, and provides error handling and graceful degradation.
def calculate_ground_track( orbital_state: dict, duration_s: float, time_step_s: float = 60.0 ) -> str: """Calculate ground track from orbital state vectors. Args: orbital_state: Orbital state (elements or state vector) duration_s: Duration for ground track calculation in seconds time_step_s: Time step for ground track points in seconds Returns: JSON string with ground track coordinates """ try: from ..integrations.orbits import calculate_ground_track as _ground_track result = _ground_track(orbital_state, duration_s, time_step_s) return json.dumps(result, indent=2) except ImportError: return "Ground track calculation not available - install orbital packages" except Exception as e: logger.error(f"Ground track error: {str(e)}", exc_info=True) return f"Ground track error: {str(e)}" - Core implementation of ground track calculation. Converts orbital state vectors to Earth-fixed latitude, longitude, altitude points, accounting for Earth rotation.
def calculate_ground_track( orbit_states: list[StateVector], time_step_s: float = 60.0 ) -> list[GroundTrack]: """ Calculate ground track from orbit state vectors. Args: orbit_states: List of state vectors time_step_s: Time step between states (seconds) Returns: List of ground track points """ ground_track = [] for i, state in enumerate(orbit_states): r_vec = state.position_m # Convert to latitude/longitude r = vector_magnitude(r_vec) lat = math.asin(r_vec[2] / r) # Account for Earth rotation try: datetime.fromisoformat(state.epoch_utc.replace("Z", "+00:00")) t_since_epoch = i * time_step_s lon = math.atan2(r_vec[1], r_vec[0]) - OMEGA_EARTH * t_since_epoch except Exception: lon = math.atan2(r_vec[1], r_vec[0]) # Normalize longitude to [-180, 180] degrees while lon > math.pi: lon -= 2 * math.pi while lon < -math.pi: lon += 2 * math.pi altitude = r - R_EARTH ground_track.append( GroundTrack( latitude_deg=rad_to_deg(lat), longitude_deg=rad_to_deg(lon), altitude_m=altitude, time_utc=state.epoch_utc, ) ) return ground_track - Dataclass defining the structure of ground track points returned by the tool.
class GroundTrack: """Ground track point.""" latitude_deg: float longitude_deg: float altitude_m: float time_utc: str - Dataclass for input state vectors used in ground track computation.
class StateVector: """Position and velocity state vector.""" position_m: list[float] # Position vector [x, y, z] in meters velocity_ms: list[float] # Velocity vector [vx, vy, vz] in m/s epoch_utc: str # Epoch in UTC ISO format frame: str = "J2000" # Reference frame