Visualiser

This Visualiser is a visual tool for displaying, analyzing, and interacting with satellite trajectories, predictions, uncertainties, and crash risk heatmaps in real-time using both 2D and 3D animated views. Consists of two classes:

  • Visualiser2D: visualize the true and predicted trajectories of a satellite in 2D space.

  • Visualiser3D: visualize the true and predicted trajectories of a satellite in 3D space.

def __init__(trajectory_file_path, 
            prediction_file_path, 
            heatmap_file_path=None, 
            measurement_times=None, 
            break_point=0, mode='prewritten'):
  ...

  • Parameters:

    • trajectory_file_path: Path to the file containing the true trajectory.

    • prediction_file_path: Path to the file containing predicted trajectory and uncertainty.

    • heatmap_file_path: (optional) File with angular crash data for heatmap rendering.

    • measurement_times: (optional) Times when measurements are expected.

    • break_point: Distance above Earth’s radius to define a “crash”.

    • mode: 'prewritten' or 'realtime' to control file reading mode.

def setup_plots(self):
  ...

  • Purpose: Initializes the full and zoomed-in plots, Earth circle, legends, and layout.

def init_colorbar(self):
  ...

  • Purpose: Adds a vertical colorbar to indicate heatmap crash likelihood scale.

def on_key_press(self, event):
  ...

  • Purpose: Captures key presses for controlling the view.

  • Keys:

    • 't': Focus on true trajectory.

    • 'p': Focus on predicted trajectory.

    • '+', 'up': Zoom in.

    • '-', 'down': Zoom out.

def read_next_position(self):
  ...

  • Purpose:Generator yielding the next position `(x, y, z) from the trajectory file, converting from spherical to Cartesian coordinates.

def read_next_prediction(self):
  ...

  • Purpose: Reads predicted position and uncertainty from file.

def load_data(self):
  ...

  • Purpose: Continuously feeds data into queues from the trajectory and prediction files.

def direction_of_motion(self, x1, y1, x2, y2):
  ...
  return tangent, normal

  • Purpose: Calculates tangent and normal vectors between two points.

  • Parameters:

    • x1, y1: Position of point 1.

    • x2, y2: Position of point 2.

  • Returns:

    • tangent: Normalized direction vector of motion.

    • normal: Perpendicular to tangent (used in uncertainty rendering).

def load_heatmap_data(self):
  ...

  • Purpose: Parses HEATMAP_FILE to build a time-annotated list of angular crash samples.

def update_heatmap(self, current_time):
  ...

  • Purpose: Generates a radial histogram (360 wedges) showing the density of predicted crash angles up to current_time.

  • Implementation:

    • Computes histogram over [0, 2π].

    • Draws each bin as a colored wedge.

    • Updates the heatmap colorbar scale.

def update(self, frame):
    ...

  • Purpose Updates the satellite trajectory animation for a given frame. This includes:

    • Visualizing new actual and predicted positions

    • Dynamically adjusting zoom view

    • Updating uncertainty regions

    • Rendering measurement points

    • Displaying live crash heatmaps (if enabled)

  • Returns: A list of updated artists (lines, patches, markers) to be redrawn by the animation system.

def visualise(self):
    # Start data loading thread
    data_thread = threading.Thread(target=self.load_data, daemon=True)
    data_thread.start()

    # Load heatmap data
    self.load_heatmap_data()

    # Create animation
    self.ani = animation.FuncAnimation(
        self.fig, self.update,
        frames=1000,
        interval=50,
        blit=False,
        cache_frame_data=False
    )

    plt.tight_layout(rect=[0, 0.03, 1, 0.95])
    plt.show()

  • Purpose: Launches the full visualisation system.

  • Implementations:

    • Starts data loader thread.

    • Loads heatmap data.

    • Creates a Matplotlib animation with update frames.

    • Displays the interactive plot window.

def plot_earth(self, ax):
    u = np.linspace(0, 2 * np.pi, 100)
    v = np.linspace(0, np.pi, 100)
    theta, phi = np.meshgrid(u, v)
    x, y, z = spherical_to_cartesian(self.earth_radius, theta, phi)
    ax.plot_surface(x, y, z, color='gray', alpha=0.3)
    self.add_earth_grid(ax)

  • Purpose: Plots a semi-transparent 3D Earth sphere on the given axis using a spherical mesh.

def add_earth_grid(self, ax):
  ...

  • Purpose: Overlays meridians and parallels on the Earth’s surface for geographic reference, including labeled degree markers.

def set_axes_equal(self, ax):
  ...

  • Purpose: Ensures all 3D axes have equal scaling for correct spatial perception.

def create_uncertainty_tube(self, points, std_devs):
  ...

  • Purpose: Creates a 3D polygonal mesh representing a tube around the predicted trajectory, visualizing spatial uncertainty via standard deviation radii.