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

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)}"

aerospace_mcp/integrations/orbits.py:440-487 (handler)

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

aerospace_mcp/integrations/orbits.py:55-62 (schema)

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

aerospace_mcp/integrations/orbits.py:34-40 (schema)

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

Aerospace MCP