User Instructions

The purpose of this section is to provide detailed, step-by-step instructions on how to use the important interfaces for our codebase.

Importing YOLOv3

  1. Make sure you activate the conda environment was described in the Installation section:

    >>> conda activate [envname]

  2. In your Python driver script, make sure that the yolov3 filepath is in the Python search path. For example, if the full filepath to the yolov3 repo is /full/path/to/topdir/yolov3/, then you would do this as:

    import sys
sys.path.append('/full/path/to/topdir/')

  3. The yolov3 project uses the Python import system to load all source code in yolov3/src/ and yolov3/utils/ in a heirarchical manner. You may therefore import this codebase as a module; for example:

    import yolov3
darknet = yolov3.src.models.Darknet(<network_cfg_file> , <imgsize>)

Unit Tests

Unit tests are maintained in the yolov3/tests subdirectory. To run these, navigate to the directory that contains yolov3, and run the unittests as a Python package from the shell:

>>> python3 -m yolov3.tests.unittests

Training Example

An example driver script demonstrating proper interface usage for network training is provided in scripts/train.py, together with the scripts/input_train.dat input file.

Note

To run this example, certain options must be set in the inputfile. In particular, please ensure that the following pieces of data exist and are specified in the input file:

  1. targetspath : filepath to the target metadata file
  2. traindir : filepath to the training image dataset
  3. networkcfg : YOLOv3 network configuration file
  4. class_path : filepath to the class names/labels file

Please consult the Code Documentation on the InputFile class for further details on these and other necessary options.

To run this example, do the following:

  1. Edit the scripts/input_train.dat input file so that those settings involving filepaths accurately reflect the data/filepaths on your machine.
  2. Navigate to the directory that contains yolov3, and issue the following shell command to run the script as a package:
>>> python3 -m yolov3.scripts.train yolov3/scripts/input_train.dat

Note

Mulitple-GPU support is currently not available for any part of this software. Please run in either CPU or single-GPU mode only. If you have multiple GPUs on your machine, you may use the CUDA_VISIBLE_DEVICES flag to enforce single-GPU mode, e.g.:

>>> CUDA_VISIBLE_DEVICES=0 python3 -m yolov3.scripts.train yolov3/scripts/input_train.dat

Detection Example

An example driver script demonstrating proper interface usage for network detection/testing is provided in scripts/detect.py, together with the scripts/input_detect.dat input file.

Note

To run this example, certain options must be set in the inputfile. For image detection only, set plot_flag = False and ensure that the following pieces of data exist and are specified in the input file:

  1. imagepath : filepath to image dataset
  2. networkcfg : YOLOv3 network configuration file
  3. networksavefile : PyTorch saved neural network file (.pt)

To additionally run with scoring, set plot_flag = True and ensure that these necessary options are specified in the input file as well:

  1. targetspath : filepath to the target metadata file
  2. class_path : filepath to the class names/labels file
  3. class_mean : filepath to training data class mean statistics
  4. class_sigma : filepath to training data class sigma statistics

For more details, consult the Code Documentation on the InputFile class.

To run this example, do the following:

  1. Edit the scripts/input_detect.dat input file so that those settings involving filepaths accurately reflect the data/filepaths on your machine.
  2. Navigate to the directory that contains yolov3, and issue the following shell command to run the script as a package:
>>> python3 -m yolov3.scripts.detect yolov3/scripts/input_detect.dat

Note

Mulitple-GPU support is currently not available for any part of this software. Please run in either CPU or single-GPU mode only. If you have multiple GPUs on your machine, you may use the CUDA_VISIBLE_DEVICES flag to enforce single-GPU mode, e.g.:

>>> CUDA_VISIBLE_DEVICES=0 python3 -m yolov3.scripts.detect yolov3/scripts/input_detect.dat