kylehounslow/tara repository overview

⁠Tarantula3D: 2D-->S3D Image Conversion Pipeline

⁠Contents

• Dependencies⁠
• Environment Setup⁠
• Training⁠
  • Local Training⁠
  • Cloud Training⁠

⁠Dependencies

• Ubuntu 16.04
  • Note: Most likely works with >16.04 although untested
• Python3.5
• Python venv
• Google ml-engine
• Docker (Coming soon)

⁠Environment Setup

Clone project

git clone https://github.com/Digitalist-USA/tara.git
export PROJECT_ROOT=$PWD/tara 

⁠Option 1: Python3.5 Virtual Environment

⁠Install venv

sudo apt-get install -y python3-venv

⁠Create and activate virtual environment

cd $PROJECT_ROOT
# create a virtual environment named `venv`
python3.5 -m venv venv
source venv/bin/activate

⁠For CPU-only machine

pip install -r requirements.txt

⁠For GPU-enabled machine:

(Skip if CPU-only machine)
Download and install CUDA 9.0:
https://developer.nvidia.com/cuda-90-download-archive⁠
Choose Linux -> x86_64 -> Ubuntu -> 16.04 -> deb (local) and download the Base Installer (1.2GB)
Follow the install instructions provided below the download. eg:

cd ~/Downloads/
sudo dpkg -i cuda-repo-ubuntu1604-9-0-local_9.0.176-1_amd64.deb
sudo apt-key add /var/cuda-repo-9-0-local/7fa2af80.pub
sudo apt-get update
sudo apt-get install -y cuda-toolkit-9-0
# reboot your system for changes to the kernel take effect
sudo reboot now

Install python requirements

# be sure we are in virtual environment
source $PROJECT_ROOT/venv/bin/activate
pip install -r requirements-gpu.txt

⁠Option 2: Docker

Coming soon...

⁠Training

Training can be performed locally or in the cloud. Once a training job is dispatched, it is assigned a unique job_id. A new sub-folder is created under this unique job_id and this is where all model checkpoints, training metadata etc. are saved during training. The new job_id folder will be created locally or in the cloud depending on your .cfg file specification (covered below).

⁠1) Setup Google Cloud SDK

First follow instructions here:
https://cloud.google.com/sdk/docs/#deb⁠
Then be sure to init and authenticate gcloud

gcloud init
gcloud config set project tarantula-3d-project
gcloud auth application-default login

⁠2) Configure training parameters

See here⁠ for instructions on creating training config files

⁠3a) Local Training

python train.py --cfg cfg/my_cfg.cfg

There are two possible setups for local training:

⁠Train locally with local storage

Create your local training directory structure.
This is where the jobs/ and data/ folder will live.

sudo mkdir -p /storage/tarantula3d
chmod 777 /storage/tarantula3d -R
mkdir /storage/tarantula3d/jobs
mkdir /storage/tarantula3d/data

Move your dataset into your data/ folder or create a symlink to another folder

cp -r my_dataset /storage/tarantula3d/data
# alternatively create a symlink
ln -sf /storage/tarantula3d/data/data_folder /path/to/data_folder

In your configfile under the [local] section, point to these local directories.

# ...
[local]
bucket_path=/storage/tarantula3d/
jobs_dir=jobs
train_dirs=data/data_folder/train
eval_dirs=data/data_folder/eval
# ...

⁠Train locally with cloud storage

In your configfile under the [local] section, point to cloud bucket

# ...
[local]
bucket_path=gs://tarantula3d
jobs_dir=jobs
train_dirs=data/data_folder/train
eval_dirs=data/data_folder/eval
# ...

⁠3b) Cloud Training

python train.py --cfg cfg/my_cfg.cfg --cloud