This repo serves as a test bed for simulating interesting Near-Earth spacecraft missions from a guidance and controls perspective.

⚠️ Note: This project is primarily developed and tested on macOS. While Windows build instructions are provided, they have not been thoroughly verified. Users may encounter platform-specific issues when building on Windows.

Overview

At the moment, this simulation implements a basic satellite dynamics model in Low Earth Orbit (LEO), including:

• Full 6-DOF rigid body dynamics
• Quaternion-based attitude representation (inertial to body frame quaternion that evolves with inertial trajectory)
• Coordinate frame transformations between:
  • GCRS (Geocentric Celestial Reference System) - An inertial frame aligned with the Earth's equator, ideal for LEO satellite navigation
  • ITRS (International Terrestrial Reference System) - Earth-fixed frame, also known as ECEF
  • LLA (Latitude, Longitude, Altitude) coordinates

The GCRS frame serves as our primary inertial reference frame (equivalent to ECI for most applications), with its xy-plane aligned with the Earth's equator. This makes it particularly well-suited for LEO satellite applications since most orbital perturbations are symmetric about the equator.

Dependencies

Core Dependencies	Version	Description
	17+	Core language
	3.10+	Build system
	3.x	Linear algebra (included as submodule)
	Latest	Astronomy routines
	Latest	Testing framework

Platform-Specific Setup

macOS

brew install cmake googletest

Linux (Ubuntu/Debian)

sudo apt-get install cmake libgtest-dev

Windows

1. Install CMake
2. Install Google Test
3. Install Visual Studio with C++ development tools

Visualization

Python Dependencies	Version
	3.7+
	Latest
	Latest
	Latest
	Latest

Building and Running

1. Clone the repository and initialize submodules:

git clone https://github.com/Natsoulas/Earthbound.git
cd Earthbound
git submodule update --init --recursive

2. Create and enter build directory:

mkdir build && cd build

3. Configure and build the project:

macOS/Linux

cmake ..
make

Windows (using Visual Studio)

cmake -G "Visual Studio 17 2022" ..
cmake --build . --config Release

4. Run the simulation:

macOS/Linux

./Earthbound

Windows

.\Release\Earthbound.exe

This will generate output files in the output directory containing the simulation results.

Running Tests

The project uses Google Test for unit testing. To run the tests:

1. Build the tests (they are built automatically with the main project):

cmake ..
make

2. Run all tests:

macOS/Linux

./bin/unit_tests

Windows

.\bin\Release\unit_tests.exe

Individual test suites can be run using Google Test filters:

./bin/unit_tests --gtest_filter=TestSuiteName.TestName  # macOS/Linux
.\bin\Release\unit_tests.exe --gtest_filter=TestSuiteName.TestName  # Windows

Visualization

To visualize the simulation results:

1. Install the required Python packages:

pip install numpy pandas matplotlib cartopy

2. Run the visualization script:

python viz/plotMissionDashboard.py

This will generate several plots:

• Orbital trajectory in 3D
• Ground track overlaid on a map
• Time history of key state variables
• Attitude quaternion evolution

The plots will be saved in the plots directory by default.

Example Dashboard

Configuration

Simulation parameters can be modified in the include/config/simpleSat.hpp file, including:

• Initial orbital elements
• Simulation duration and time step
• Spacecraft physical properties
• Output file settings