cleanup and update readme

.github/workflows/image.yml

@@ -2,7 +2,7 @@ name: Build Docker YOLO3D
 
 on:
   push:
-    branches: main
+    branches: docker
 
 jobs:
   build:

README.md

@@ -1,17 +1,60 @@
-# YOLO For 3D Object Detection
+# YOLO For 3D Object Detectiond
+
+Unofficial implementation of [Mousavian et al](https://arxiv.org/abs/1612.00496) in their paper *3D Bounding Box Estimation Using Deep Learning and Geometry*. YOLO3D uses a different approach, as the detector uses YOLOv5 which previously used Faster-RCNN, and Regressor uses ResNet18/VGG11 which was previously VGG19.
+
+![inference](docs/demo.gif)
+
+## Installation
+For installation you can use virtual environment like anaconda or using docker image. For anaconda follow:
+
+### Ananconda Virtual Env
+Create conda environment
+```
+conda create -n yolo3d python=3.8 numpy
+```
+Install PyTorch and torchvision version 1.8 above. If your GPU doesn't support it, please follow [Nelson Liu blogs](https://github.com/nelson-liu/pytorch-manylinux-binaries). 
+```
+pip install torch==1.8.1 torcvision==0.9.1
+```
+Last, install requirements
+```
+pip install -r requirements.txt
+```
+
+### Docker Engine 
+Docker engine is easy way to install all you need. Pull docker image from repository:
+```
+docker pull ruhyadi/yolo3d:latest
+```
+run docker container from docker image with
+```
+cd ${YOLO3D_DIR}
+./runDocker.sh
+```
+You will get in to docker container interactive terminal. You can run inference code or flask app, follow code below.
+
+### Download Pretrained Weights
+In order to run inference code or resuming training, you can download pretrained ResNet18 or VGG11 model. I have train model with 10 epoch each. You can download model with `resnet18` or `vgg11` for `--weights` arguments.
+```
+cd ${YOLO3D_DIR}/weights
+python get_weights.py --weights resnet18
+```
 
 ## Inference
+For inference with pretrained model you can run code below. It can be run in conda env or docker container. 
 ```
 python inference.py \
     --weights yolov5s.pt \
     --source eval/image_2 \
     --reg_weights weights/resnet_10.pkl \
     --model_list resnet \
-    --output_path runs/detect/ \
+    --output_path runs/ \
     --show_result -- save_result
 ```
+Inference can be run on Colab Notebook, please visit [this link](https://colab.research.google.com/drive/1vhgGRRDqHEqsrqZXBjBJHDFWJk9Pw0qZ?usp=sharing).
 
 ## Training
+YOLO3D model can be train with PyTorch or PyTorch Lightning. In order to train you need API KEY for [comet.ml](https://www.comet.ml) (visualize your training loss/accuracy). Follow comet.ml documentation to get API key.
 ```
 python train.py \
     --epochs 10 \
@@ -20,8 +63,10 @@ python train.py \
     --save_epoch 5 \
     --train_path ./dataset/KITTI/training \
     --model_path ./weights \
-    --select_model resnet18
+    --select_model resnet18 \
+    --api_key xxx
 ```
+In order train with pytorch lightning run code below:
 ```
 !python train_lightning.py \
     --train_path dataset/KITTI/training \
@@ -32,14 +77,10 @@ python train.py \
     --num_workers 2 \
     --gpu 1 \
     --val_split 0.1 \
-    --model_path weights
+    --model_path weights \
+    --api_key xxx
 ```
 
-
-![img01](docs/001.png)
-![img02](docs/002.png)
-![img03](docs/000.png)
-
 ## Reference
 - [YOLOv5 by Ultralytics](https://github.com/ultralytics/yolov5)
 - [shakdem/3D-BoungingBox](https://github.com/skhadem/3D-BoundingBox)

inference.py

@@ -63,7 +63,7 @@ def detect3d(
     ):
 
     # Directory
-    imgs_path = glob.glob(str(source) + '/*')
+    imgs_path = sorted(glob.glob(str(source) + '/*'))
     calib = str(calib_file)
 
     # load model

runDocker.sh

@@ -2,5 +2,5 @@ xhost +local:docker
 XSOCK=/tmp/.X11-unix
 XAUTH=/tmp/.docker.xauth
 xauth nlist $DISPLAY | sed -e 's/^..../ffff/' | xauth -f $XAUTH nmerge -
-docker run -it --gpus all -p 5020:5020 -e DISPLAY=$DISPLAY -v $XSOCK:$XSOCK -v $XAUTH:$XAUTH -e XAUTHORITY=$XAUTH -v ${PWD}:/yolo3d -it ruhyadi/yolo3d:latest
+docker run -it --rm --gpus all -p 5020:5020 -e DISPLAY=$DISPLAY -v $XSOCK:$XSOCK -v $XAUTH:$XAUTH -e XAUTHORITY=$XAUTH -v ${PWD}:/yolo3d -it ruhyadi/yolo3d:latest
 xhost -local:docker

train.py

@@ -50,7 +50,8 @@ def train(
     save_epoch=10,
     train_path=ROOT / 'dataset/KITTI/training',
     model_path=ROOT / 'weights/',
-    select_model='resnet18'
+    select_model='resnet18',
+    api_key=''
     ):
 
     # directory
@@ -72,7 +73,7 @@ def train(
     }
 
     # comet ml experiment
-    experiment = Experiment('IFsibHtChMnB2b5FuZzhiMswT', project_name="YOLO3D")
+    experiment = Experiment(api_key, project_name="YOLO3D")
     experiment.log_parameters(hyper_params)
 
     # data generator
@@ -183,6 +184,7 @@ def parse_opt():
     parser.add_argument('--train_path', type=str, default=ROOT / 'dataset/KITTI/training', help='Training path KITTI')
     parser.add_argument('--model_path', type=str, default=ROOT / 'weights', help='Weights path, for load and save model')
     parser.add_argument('--select_model', type=str, default='resnet18', help='Model selection: {resnet18, vgg11}')
+    parser.add_argument('--api_key', type=str, default='', help='API key for comet.ml')
 
     opt = parser.parse_args()
 

train_lightning.py

@@ -32,11 +32,12 @@ def train(
     gpu=1,
     val_split=0.1,
     model_path=ROOT / 'weights/',
+    api_key=''
     ):
 
     # comet ml
     comet_logger = CometLogger(
-        api_key='IFsibHtChMnB2b5FuZzhiMswT',
+        api_key=api_key,
         project_name="YOLO3D"
         )
 
@@ -92,6 +93,7 @@ def parse_opt():
     parser.add_argument('--gpu', type=int, default=0, help='Numbers of GPU, default=1')
     parser.add_argument('--val_split', type=float, default=0.2, help='Validation split percentage')
     parser.add_argument('--model_path', type=str, default=ROOT / 'weights', help='Weights path, for load and save model')
+    parser.add_argument('--api_key', type=str, default='', help='API key for comet.ml')
 
     opt = parser.parse_args()