An image processing library for moving object detection implemented with GPUs.
Based on a Maximum Likelihood detection algorithm for moving astronomical objects.

KBMOD is a set of Python tools to search astronomical images for moving objects based upon method of maximum likelihood detection. For more information on the KBMOD algorithm see the following papers:

• Fast Algorithms for Slow Moving Asteroids: Constraints on the Distribution of Kuiper Belt Objects by Whidden et. al. (2019)
• Sifting Through the Static: Moving Object Detection in Difference Images by Smotherman et. al. (2021)

To build kbmod The packages required to build the code are:

• Cuda Toolkit >= 8.0
• CMake >= 3.12

Ensure that the NVIDIA's nvcc compiler is available on your system, for example:

nvcc --version

It is possible that the compiler is installed but not discoverable. In that case add its location to PATH. For example, if using bash do export PATH=/path/to/cuda:$PATH. The default location for CUDA Toolkit installation is usually /usr/local/cuda-XY.Z** where XY.Z represent the CUDA Toolkit version that was installed.
If using bash add the appropriate command to ~/.bashrc in order to avoid having to set it repeatedly.

If CUDA Toolkit is not availible on your system follow their offical installation instructions. Optionally, if you use Anaconda virtual environments, the CUDA Toolkit is also availible as conda install cudatoolkit-dev. Depending on the version of drivers on your GPU, you might need to use an older cudatoolkit-dev version.

Clone this repository, including all of its submodules:

git clone --recursive https://github.com/dirac-institute/kbmod.git

Build

cd kbmod
pip install .

This builds the package and all the dependencies required to test, run KBMOD on images and read the results. To use the additional analysis tools available in the analysis module it is necessary to install additional dependencies:

pip install .[analysis]

Note, however, that some of the dependencies in the analysis module require packages and supplementary data that are not installed nor provided by KBMoD.

To verify that the installation was successful run the tests:

cd tests/
python -m unittest

If you want to contribute to the development of KBMOD, it is recommended that you install it in editable mode:

pip install -e .

Changes you make to the Python source files will then take immediate effect. To recompile the C++ code it's easiest to re-install the package in editable mode again.

It is possible to build only the C++ code via cmake.

cmake -B src/kbmod -S .
cmake --build src/kbmod --clean-first

To rebuild, it is sufficient to just re-run the cmake --build command. Optionally, invoke the cmake generated Makefile as make clean && make from the src/kbmod directory.

A short example injecting a simulated object into a stack of images, and then recovering it. This example is also included in tests/test_readme_example.py.

import kbmod.search as kb
import numpy as np

# Create a point spread function
psf = kb.psf(1.5)

# Create fake data with ten 512x512 pixel images.
from kbmod.fake_data_creator import *
ds = FakeDataSet(512, 512, 10)
imgs = ds.stack.get_images()

# Get the timestamp of the first image.
t0 = imgs[0].get_time()
print(f"Image times start at {t0}.")

# Specify an artificial object
flux = 275.0
position = (10.7, 15.3)
velocity = (2, 0)

# Inject object into images
for im in imgs:
    dt = im.get_time() - t0
    im.add_object(position[0] + dt * velocity[0], 
                  position[1] + dt * velocity[1], 
                  flux)

# Create a new image stack with the inserted object.
stack = kb.image_stack(imgs)

# Recover the object by searching a set of trajectories.
search = kb.stack_search(stack)
search.search(
    5,  # Number of search angles to try (-0.1, -0.05, 0.0, 0.05, 0.1)
    5,  # Number of search velocities to try (0, 1, 2, 3, 4)
    -0.1,  # The minimum search angle to test
    0.1,  # The maximum search angle to test
    0,  # The minimum search velocity to test
    4,  # The maximum search velocity to test
    7,  # The minimum number of observations
)

# Get the top 10 results.
results = search.get_results(0, 10)
print(results)

• API Reference
• Search Demo

The software is open source and available under the BSD license.