karolmajek/maxdeeplab

1# Using DeepLab22 3In the following, we provide instructions on how to run DeepLab2.4 5## Prerequisites6 7We assume DeepLab2 is successfully installed and the necessary datasets are8configured.9 10*   See [Installation](installation.md).11*   See dataset guides:12    *   [Cityscapes](cityscapes.md).13    *   [KITTI-STEP](kitti_step.md).14    *   [and many more](./).15 16## Running DeepLab217 18DeepLab2 contains several implementations of state-of-the-art methods. In the19following, we discuss all steps from choosing a model, setting up the20configuration to training and evaluating it.21 22### Choosing a model23 24For this tutorial, we use Panoptic-DeepLab, however, running any other model25follows the same steps. For each network architecture, we provide a guide that26contains example configurations and (pretrained) checkpoints. You can find all27guides [here](../projects/). For now, please checkout28[Panoptic-DeepLab](../projects/panoptic_deeplab.md).29 30We will use the Resnet50 model as an example for this guide. If you just want to31run the network without training, please download the corresponding checkpoint32trained by us. If you would like to train the network, please download the33corresponding ImageNet pretrained checkpoint from34[here](../projects/imagenet_pretrained_checkpoints.md).35 36### Defining a configuration37 38When you want to train or evaluate a network, DeepLab2 requires a corresponding39configuration. This configuration contains information about the network40architecture as well as all sorts of hyper-parameters. Fortunately, for almost41all settings we provide default values and example configurations. The42configuration of Panoptic-DeepLab with ResNet50 for the Cityscapes dataset can43be found44[here](../../configs/cityscapes/panoptic_deeplab/resnet50_os32_merge_with_pure_tf_func.textproto).45 46Using our default parameters there are only a few things that needs to be47defined:48 491.  The name of the experiment `experiment_name`. The experiment name is used as50    a folder name to store all experiment related files in.512.  The initial checkpoint `initial_checkpoint`, which can be an empty string52    for none or the path to a checkpoint (e.g., pretrained on ImageNet or fully53    trained by us.)543.  The training dataset `train_dataset_options.file_pattern`, which should55    point to the TfRecords of the Cityscapes train set.564.  The evaluation dataset `eval_dataset_options.file_pattern`, which should57    point to the TfRecords of the Cityscapes val set.585.  If the custom CUDA kernel is successfully compiled, we recommend to set59    `merge_semantic_and_instance_with_tf_op` to true.60 61For a detailed explanation of all the parameters, we refer to the documented62definitions of the proto files. A good starting place is the63[config.proto](../../config.proto). The `ExperimentOptions` are a collection of64all necessary configurations ranging from the model architecture to the training65settings.66 67### Training and Evaluating68 69We currently support four different modes to run DeepLab2:70 71*   Training: This will only train the network based on the provided72    configuration.73*   Evaluation: This will only evaluate the network based on the provided74    configuration.75*   Continuous Evaluation: This mode will constantly monitor a directory for76    newly saved checkpoints that will be evaluated until a timeout. This mode is77    useful when runing separate jobs for training and evaluation (e.g., a multi78    GPU job for training, and a single GPU job for evaluating).79*   Interleaved Training and Evaluation: In this mode, training and evaluation80    will run interleaved. This is not supported for multi GPU jobs.81 82### Putting everything together83 84To run DeepLab2 on GPUs, the following command should be used:85 86```bash87python training/train.py \88    --config_file=${CONFIG_FILE} \89    --mode={train | eval | train_and_eval | continuous_eval} \90    --model_dir=${BASE_MODEL_DIRECTORY} \91    --num_gpus=${NUM_GPUS}92```93 94You can also launch DeepLab2 on TPUS. For this, the TPU address needs to be95specified:96 97```bash98python training/train.py \99    --config_file=${CONFIG_FILE} \100    --mode={train | eval | train_and_eval | continuous_eval} \101    --model_dir=${BASE_MODEL_DIRECTORY} \102    --master=${TPU_ADDRESS}103```104 105For a detailed explanation of each option run:106 107```bash108python training/train.py --help109```110