3D Boxes From Imagery and Point Clouds

This project aims to find 3D boxes in imagery and point-cloud data.

Given

• High resolution imagery with 3D camera parameters
• Point cloud data such as mobile LiDAR

Find:

• Oriented 3D boxes (aka parallelepipeds, or cuboids) that contain a target class.

The work is part of a Thesis and we plan to make it part of a paper; if you find it useful please check back for a paper to cite:

# Not yet even a preprint; we need this when we make the repo public
@article{liux2018srp,
  title={3D Boxes from Imagery and Point Clouds},
  author={},
  journal={},
  volume={},
  pages={},
  year={2018},
  publisher={}
}

Try It With Docker

Using a prebuilt docker image. If you have CUDA and nvidia-docker:

nvidia-docker run -it -v $CWD:/workspace -p 8888:8888 --name srp jfemiani/srp:cuda8

If you plan to use the CPU only

docker run -it -v $CWD:/workspace -p 8888:8888 --name srp jfemiani/srp:cpu

The script should start a jupyter server, open the link that is displayed in the terminal in order to see the code in action.

Dependencies

PyTorch

PyTorch is a deep learning library that we used to do object detection. Use the link to install the appropriate version for your system before attempting to use this code. For best performance you should have a decent NVIDIA GPU and the CUDA toolkit installed on your system, however you can run the code entirely in CPU if you download a version of torch with no CUDA. This may be necessary if, e.g., you are working on a mac.

Setup

Using PIP:

pip install git+https://github.com/jfemiani/srp-boxes

From source

git clone https://github.com/jfemiani/srp-boxes
cd srp-boxes 
python setup.py install

For development or building models

For development, building models, and doing experiments we use GNU make

git clone https://github.com/jfemiani/srp-boxes
make all
make data

Documentation

Our jupyter notebooks can be used as a tutorial of sorts.

API Documentation is not currently hosted. To build documentation use

cd docs 
make html
browse _build/html/index.html

Data

We build our models on data provided by the Salt River Project (SRP); we will seek permission to make it public. In the meantime, if you want access to the data you will have to send me an email and I will forward it along.

To prepare the data for training: make data