Welcome to DecaVision’s documentation!

This library contains the methods required to build an image classification neural network using transfer learning.

The module can be used to prepare a dataset of images for training, train a classification model built on top of various pretrained models, optimize model hyperparameters using scikit-optimize library and evaluate the accuracy on a test set. The library capitalizes on the concepts of data augmentation, fine tuning and hyperparameter optimization, to achieve high accuracy given small sets of training images.

This library has a few distinguishing features. It is specifically designed to work with Google Colab notebooks and leverage their TPUs, to seamlessly transition from quick iterations of modeling approaches to large-scale training. Functionalities of hyperparmaters tuning and progressive learning are included and easily integrated in the pipeline to reach higher accuracy. Finally, state-of-the art EfficientNet transfer learning models and TensorFlow 2 functionalities are considered to provide high efficiency.

A great way of explaining the library is using an example notebook, which you can find here.

The most recent version of this library adds a feature to leverage unlabelled images in order to improve the performance of image classifiers. This procedure is called semi-supervised learning (SSL) and is discussed in this blog post. The method was also described in a paper and presented at the ACM MMSports 2021 conference.

The library has been updated most recently to also include multilabel image classification.

Installation

This library works best with python 3.7 (because it’s the version used on colab) and it is based on the following dependencies:

• tensorflow 2

• matplotlib

• scikit-optimize

• pillow

• numpy

• pandas

• scikit-learn

• augmentor

• dill

• google-cloud-storage

• pyunpack

• patool

• seaborn

This library is available through the Python Package Installer (PyPI) by typing:

pip install decavision

All the dependencies are installed along with the library, so it is safer to perform the installation in a fresh virtual environment. If you are not working in colab you also need to install tensorflow.

pip install tensorflow>=2.9.2

Contents

This documentation is separated in two distinct parts. The first one explains what the functions made available to you do. The second part shows examples of how to use the code explicitely.

Functions

• Preparing datasets
  • Data augmentation
    • DataAugmentor
  • Make tfrecords
    • TfrecordsGenerator
  • Generate pseudo labels for unlabelled data
    • PseudoLabelGenerator
• Train models
  • Image classification including Multilabel classification
    • ImageClassifier
  • Progressive learning
    • ProgressiveLearner
• Model testing
  • ModelTester
    • ModelTester.classify_images()
    • ModelTester.confusion_matrix()
    • ModelTester.evaluate()
    • ModelTester.generate_classification_report()
    • ModelTester.plot_errors()
  • ModelTesterMultilabel
    • ModelTesterMultilabel.classify_images()
    • ModelTesterMultilabel.create_movie()
    • ModelTesterMultilabel.evaluate()
    • ModelTesterMultilabel.generate_metrics()
• Utils
  • Colab utils
    • authenticate_colab()
    • download_dataset()
  • Training utils
    • CheckpointDownloader
    • custom_loss()
    • f1_score()
  • Data utils
    • check_RGB()
    • create_dir()
    • download_dataset()
    • prepare_image()
    • print_download_progress()
    • split_train()
  • Utils
    • check_PU()
    • check_sep()
    • empty_folder()
    • gcs_bucket()
    • is_gcs()
    • load_classes()
    • load_model_clear()
    • upload_file_gcs()

Examples

• Build a dataset from scratch
  • Splitting a set of images into a training and a validation set
  • Make data augmentation on training images
  • Generate Tfrecord files
• Train and optimize model
  • Training the classification model
  • Saving and exporting the keras model
  • Optimization of the hyperparameters
• Improve a classification model using unlabelled images
  • Preliminary steps
  • Generating pseudo labels
  • Training the student model
• Testing Multilabel image classification model
  • Evaluating the multilabel classification model
  • Plot & Save classified images
  • Create a movie from classified images
  • Generate Classification report and Confusion matrix

Roadmap

Follow the Sport Vision API and our blog at https://medium.com/decathlondevelopers/ for updates.

Support

Pull requests to the library are welcomed. If you have any problem, question or suggestion regarding this library, don’t hesitate to create an issue or contact us at aicanada@decathlon.net.