dirac-institute / kbmod Goto Github PK

KBMOD (Kernel-Based Moving Object Detection)

License: BSD 2-Clause "Simplified" License

Python 8.99% Jupyter Notebook 88.21% C++ 2.46% Cuda 0.31% CMake 0.03%

kbmod's Introduction

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)

Current documentation, including instructions for installation, can be found here.

Requirements

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 available on your system follow their official installation instructions. Optionally, if you use Anaconda virtual environments, the CUDA Toolkit is also available as conda install cudatoolkit-dev. Depending on the version of drivers on your GPU, you might need to use an older cudatoolkit-dev version.

Installation

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

For Developers

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.

If you want to build the documentation you must have pandoc which seems not installable by pip. See Pandoc, or if you are using conda:

conda install pandoc

Building the documentation in docs/build/html using sphinx:

pip install .[docs]
sphinx-build -t html docs/source docs/build

Or you can use the make to call sphinx:

cd docs
make clean html

Usage

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
from kbmod.candidate_generator import KBMODV1Search
import numpy as np

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

# Create fake data with ten 512x512 pixel images and starting at MJD of 57130.2.
from kbmod.fake_data.fake_data_creator import *
fake_times = create_fake_times(10, t0=57130.2)
ds = FakeDataSet(512, 512, fake_times)
imgs = ds.stack.get_images()

# Get the timestamp of the first image.
t0 = imgs[0].get_obstime()
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_obstime() - t0
    add_fake_object(
        im,
        position[0] + dt * velocity[0],
        position[1] + dt * velocity[1],
        flux,
        psf,
    )

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

# Generate a set of trajectories to test from each pixel.
gen = KBMODV1Search(
    5,  # Number of search velocities to try (0, 0.8, 1.6, 2.4, 3.2)
    0,  # The minimum search velocity to test (inclusive)
    4,  # The maximum search velocity to test (exclusive)
    5,  # Number of search angles to try (-0.1, -0.06, -0.02, 0.02, 0.6)
    -0.1,  # The minimum search angle to test (inclusive)
    0.1,  # The maximum search angle to test (exclusive)
)
candidates = [trj for trj in gen]

# Do the actual search.
search = kb.StackSearch(stack)
search.search(
    strategy,
    7,  # The minimum number of observations
)

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