FOUND is a system that Earth satellites can use to calculate their orbits using pictures taken by the satellite of Earth. It is being developed at Husky Satellite Lab, a CubeSat team at the University of Washington. It will be deployed and tested on HuskySat-2, the team's next mission.

Installation

There are currently two options:

Install Script works well for Windows WSL and Linux but will not work on Apple Silicon.

Docker ensures that FOUND runs the same way on any machine. If your using Apple Silicon, this is the only option.

Setup via Install Script

For Windows users, please download Windows Subsystem for Linux, and use a Linux distribution (Ubuntu by default).
For Linux Ubuntu/Oracle users (uses either apt-get, yum or brew) install this package's dependencies via the Install Script in this repository:

Copy the install script into your environment: Link to install script
Change permissions for the install script to execute (sudo chmod +rwx install.sh)
Run the install script in root/sudo as an executable (sudo ./install.sh)

Setup via Docker

This option requires you to have Docker and Visual Studio Code. To install Docker on your system, visit the official Docker installation guide. If you are using a Linux computer it is reccomended that you install Docker with apt-get instead.
You will need the Dev Containers VScode extension. This can be installed by looking it up in the extension's view or with code --install-extension ms-vscode-remote.remote-containers.

Building FOUND

Clone the repository (git clone https://github.com/UWCubeSat/found.git)
Go into the directory (cd found)
Docker Users: Open FOUND in container (Press F1 and select Dev Containers: Open Folder in Container)
Compile the executable via GNU Make or CMake (below for more information)
Execute the executable (./build/bin/found, Usage below)

Compilation

This repository uses a dual build system, using GNU Make and CMake. Consumers compiling the system should run either:

./build.sh make release.
./build.sh cmake -DCMAKE_BUILD_TYPE=Release

Developers: if your code changes, you must remake your file. The build.sh script abstracts the difference for you. It is run as:

Run GNU Make: ./build.sh make [GNU Make options]
Run CMake: ./build.sh cmake "[CMake Configuration Options]" "[CMake Build Options]"
Clean the build folder: ./build.sh clean
Clean the build and cache folders: ./build.sh clean_all

All valid and useful targets can be found on our notion.

Usage

The main executable, which is found in ./build/bin/found, operates as a standard command-line based program. The usage is:

./build/bin/found <option> [flags]

There are currently two options:

calibration: FOUND needs to know its own camera attitude, but does not find that information. Thus, this step produces a relative attitude based on a reference attitude that is always known, and one measurement of the FOUND camera's attitude. The output is to a .found file that stores this information.
distance: FOUND then uses an image taken from space together with a .found file to figure out the position of the image, and hence the satellite, relative to the Celestial Coordinate System (conversion to lattitude/longitude/altitude is also possible).

To learn more about the different flags, execute ./build/bin/found --help or ./build/bin/found -h.
Developers: FOUND's test suit executable can be found in ./build/bin/found-test.

Example Usage

Here, we present a common usage for this program. After generating the binary via make or simply make compile, execute the command:

./build/bin/found calibration         \
    --reference-orientation "20,0,0"  \
    --local-orientation "50,0,0"      \
    --output-file "example-df.found"

Here's what the flags mean:

A reference attitude is given (degrees) in terms of right ascension, declination and roll.
Another attitude is given for the local orientation, which is the orientation of FOUND.
There is an output file to put our calibrational data in.

You will notice in the your current directory the file example-df.found has now appeared. You cannot directly read this file, but in particular, this file records a required Z rotation of -30 degrees to go from the reference to FOUND's attitude.

We can then use this calibration information to now make some position estimates of our satellite. Execute the command:

./build/bin/found distance                         \
    --image test/common/assets/example_earth1.png  \
    --calibration-data example-df.found            \
    --camera-focal-length 85e-3                    \
    --camera-pixel-size 20e-6                      \
    --reference-orientation 190,0,0

For the distance flags:

The image is just the path to the image we want to use. In this case, we reference an image we use in our test cases
We then specify our calibration data, which we generated from tools.generator (check out [our tools folder](tools) for more information)
We can specify camera parameters, like the focal length (m)
Or the pixel size (m)
We then have our reference orientation, which we need to use in conjunction with our calibration data

Feeding all this information, the program now analyzes the image, the calibration data and the rest of the parameters to give us its estimate, which is seen below:

[INFO 2025-06-11 20:58:06 PDT] Using DataFile for calibration information
[INFO 2025-06-11 20:58:06 PDT] Calculated Position: (1.0456e+07, -67903.8, -972.935) m
[INFO 2025-06-11 20:58:06 PDT] Distance from Earth: 1.04562e+07 m

This is close to the actual position, which is {10378137, 0, 0} m. To be specific, the difference is 0.995379% in magnitude and 1339.65 arcsec in direction (this is especially good since we're using low quality edge detection).

Another thing to point out is the reference orientation, which was {190,0,0}. The image specified in the command was taken at an attitude of {140,0,0}, which if you remember, {190,0,0}-{30,0,0}={140,0,0} (this doesn't general hold, since attitude "subtraction" doesn't actually look like this). This of course is important to specify, otherwise, you'll get the same magnitude, but wrong direction. Should you not want to use the calibration file to do this odd math, you can instead do the equivalent command:

./build/bin/found distance                           \
    --image "test/common/assets/example_earth1.png"  \
    --reference-as-orientation                       \
    --camera-focal-length 85e-3                      \
    --camera-pixel-size 20e-6                        \
    --reference-orientation "140,0,0"

Where --reference-as-orientation tells the program to use whatever --reference-orientation is as the orientation of FOUND.

Lastly, one thing you will not notice is that the temp.found file has changed. In addition to storing calibration infomration, it also stores the calculated positions and their time stamps. This is important for the orbit stage, which is currently not implemented. If you should not want to output to the same file, you can instead do:

./build/bin/found distance                         \
    --image test/common/assets/example_earth1.png  \
    --calibration-data example-df.found            \
    --camera-focal-length 85e-3                    \
    --camera-pixel-size 20e-6                      \
    --reference-orientation 190,0,0                \
    --output-file other.found

Capabilities

FOUND currently has the following components/modules, which all function together produce an position estimates and orbital projections for a given satellite.

Calibration

This is a "simplistic" algorithm, and simply figures out the relative attitude between our local and reference attitude. The main algorithm responsible for this is:

[X] LOST-based Calibration Algorithm (LOST is the reference)

Distance Determination

This algorithm is comprised of 3 main steps

Edge Detection

After images from a satellite are received, their images are parsed to locate Earth's horizon in the image. FOUND is capable of:

[X] Simple Edge Detection via Space/Ether Identification
[ ] Laplacian of Gaussian (LoG) Filtered Edge Detection

Distance Determination

The edge information is then used to evaluate the relative size of Earth in the image and find the distance of the satellite from Earth using principals of scale. FOUND is capable of:

[X] Simple Spherical Planet Distance Determination
[X] Iterative Spherical Planet Distance Determination with SoftMax Activation and Selective Randomization
[ ] Distance Determination with an Ellipsoid Planet Assumption

Vector Generation

The distance information will then be used to form a vector of the satellite relative to Earth's coordinate axes. FOUND is capable of:

[X] Star-Tracker Assisted Vector Generation via LOST-based Calibration
[ ] Feature Detection Assisted Vector Generation (to be developed for future mission)

Orbit Determination

This stage takes multiple vectors of the satellite at different points in the satellite's orbit to project the satellite's future path of travel. FOUND will be capable of:

[ ] Runge-Kutta Based Orbital Prediction
[ ] Lambert's Problem-Based Orbital Prediction

Tools

We have tools that can be used with our main found program. They can be found in [our tools folder](tools).

CMake Integration

This project's code can be integrated with yours via cmake. To use:

include(FetchContent)
 
cmake_minimum_required(VERSION 3.16)
project(test)
 
FetchContent_Declare(
  found
  GIT_REPOSITORY https://github.com/UWCubeSat/found.git
)
 
FetchContent_MakeAvailable(found)
 
add_executable(your_executable ...)
target_link_libraries(test PRIVATE found::found_lib) # Link our library

The library found::found_lib already has all the include statements needed inside of it, so no need to locate them.