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
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.
You need Linux or macOS. On Windows, we recommend installing the Windows Subsystem for Linux, then following the Linux instructions
- 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 withmake LOST_DISABLE_ASAN=1
, or setexport 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 invendor/eigen3/Eigen
under the LOST repository.
- 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
- Locate Eigen files and move them to
- Install groff via homebrew
brew install groff
- If you get errors mentioning 'ASAN' or 'AddressSanitizer', try
make clean
and thenmake LOST_DISABLE_ASAN=1
to disable ASAN. See the Linux section above for more details.
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
.
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.
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
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.