LOST: Open-source Star Tracker

LOST is star tracker software for small, low-power, low-cost satellites. It is being developed in the Husky Satellite Lab, a CubeSat team at the University of Washington.

In depth code documentation is available on this repo's Doxygen Page

Building LOST

When making an actual, physical star tracker, you will most likely need to pick out the specific parts of LOST you want and make lots of changes. However, there's a LOST binary you can use to test and benchmark things quickly.

Local installation

You need Linux or macOS. On Windows, we recommend installing the Windows Subsystem for Linux, then following the Linux instructions

Linux Prerequisites

A C++ compiler, such as g++. On Debian, apt install g++
GNU Make. On Debian, apt install make
Groff, to generate help text. apt install groff
(Recommended) ASAN (Address Sanitizer). We use this to catch memory errors early. apt install libasan. (If you wish to use LOST without the address sanitizer, build it with make LOST_DISABLE_ASAN=1, or set export LOST_DISABLE_ASAN=1 in your ~/.bashrc file to disable it every time you build).
Git. On Debian, apt install git
Cairo, to read and write PNGs as well as draw on them for debugging and demo purposes. You won't need this on your CubeSat. On Debian, apt install libcairo2-dev. Elsewhere, follow the instructions here: https://www.cairographics.org/download/ under the Binary Packages section.
Eigen3, a header-only linear algebra and numerical methods library. On Debian, apt install libeigen3-dev. Elsewhere, download the latest stable release from https://eigen.tuxfamily.org/. You can install it system-wide, or just extract it so that the main folder is in vendor/eigen3/Eigen under the LOST repository.

macOS Prerequisites

Download Homebrew, run /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" in terminal
Install cairo via homebrew brew install cairo
Install Eigen via homebrew brew install eigen
- Locate Eigen files and move them to vendor/eigen3/Eigen under the LOST repository
Install groff via homebrew brew install groff
If you get errors mentioning 'ASAN' or 'AddressSanitizer', try make clean and then make LOST_DISABLE_ASAN=1 to disable ASAN. See the Linux section above for more details.

Building

Clone this repository (git clone https://github.com/uwcubesat/lost), then cd lost, then make will compile everything. Then you can just run ./lost and play around with the options!

If you're developing LOST, you need to re-run make every time you edit any of the source code before running ./lost.

Usage

Run LOST via the ./lost executable followed by the appropriate arguments. Executing./lost with no arguments will bring up a usage guide and options to see possible arguments.

Generating a false image

Here's an example command line to generate a false image, plot it to raw-input.png, and all the stars in the catalog to input.png:

./lost pipeline \
  --generate 1 \
  --plot-raw-input raw-input.png \
  --plot-input input.png

We name the image outputs of this command as input.png because they will be used as image inputs to the star identification pipeline. The above command utilizes many of the default values for the parameters. All of these parameters can be explicitly set by using the appropriate flags:

./lost pipeline \
  --generate 1 \
  --generate-x-resolution 1024 \
  --generate-y-resolution 1024 \
  --fov 30 \
  --generate-reference-brightness 100 \
  --generate-spread-stddev 1 \
  --generate-read-noise-stddev 0.05 \
  --generate-ra 88 \
  --generate-de 7 \
  --generate-roll 0 \
  --plot-raw-input raw-input.png \
  --plot-input annotated-input.png

Identifying a real image

Here's how to identify a real image:

Download https://markasoftware.com/img_7660.png
Generate a database named my-database.dat by running:

./lost database \
  --max-stars 5000 \
  --kvector \
  --kvector-min-distance 0.2 \
  --kvector-max-distance 15 \
  --kvector-distance-bins 10000 \
  --output my-database.dat

Identify the image by running:

./lost pipeline \
  --png img_7660.png \
  --focal-length 49 \
  --pixel-size 22.2 \
  --centroid-algo cog \
  --centroid-mag-filter 5 \
  --database my-database.dat \
  --star-id-algo py \
  --angular-tolerance 0.05 \
  --false-stars 1000 \
  --max-mismatch-prob 0.0001 \
  --attitude-algo dqm \
  --print-attitude attitude.txt \
  --plot-output annotated-7660.png

This will print the attitude (right ascension, declination, roll) to the file attitude.txt, and write an annotated image to annotated-7660.png.

When identifying a different image, some parameters must be changed. Most important is the camera's pixel size and focal length, which quantify how "zoomed-in" the camera is. The pixel size (22.2μm in the example) is the side length, in micrometers, of each pixel. This is commonly given on a sensor datasheet. Usually in the 1μm-10μm range (The example uses 22.2 because it was resized). Next is the focal length, in millimeters, which is usually found in the lens documentation (49mm in the example). If either of these parameters is wrong, the star identification has a high probability of mismatch. Any statistical guarantees of the algorithms break down completely when the camera parameters are not known accurately.

The centroid magnitude filter may also need to be adjusted, depending on the resolution and noisiness of your images. If the output file has many centroids (red boxes) where there are no visible stars, then the filter should be increased. If there are many stars without centroids, the filter should be decreased.

UWCubeSat / lost