frgfm/Holocron

Implementations of recent Deep Learning tricks in Computer Vision, easily paired up with your favorite framework and model zoo.

Holocrons were information-storage datacron devices used by both the Jedi Order and the Sith that contained ancient lessons or valuable information in holographic form.

Source: Wookieepedia

Quick Tour

This project was created for quality implementations, increased developer flexibility and maximum compatibility with the PyTorch ecosystem. For instance, here is a short snippet to showcase how Holocron models are meant to be used:

from PIL import Image
from torchvision.transforms import Compose, ConvertImageDtype, Normalize, PILToTensor, Resize
from torchvision.transforms.functional import InterpolationMode
from holocron.models.classification import repvgg_a0

# Load your model
model = repvgg_a0(pretrained=True).eval()

# Read your image
img = Image.open(path_to_an_image).convert("RGB")

# Preprocessing
config = model.default_cfg
transform = Compose([
    Resize(config['input_shape'][1:], interpolation=InterpolationMode.BILINEAR),
    PILToTensor(),
    ConvertImageDtype(torch.float32),
    Normalize(config['mean'], config['std'])
])

input_tensor = transform(img).unsqueeze(0)

# Inference
with torch.inference_mode():
    output = model(input_tensor)
print(config['classes'][output.squeeze(0).argmax().item()], output.squeeze(0).softmax(dim=0).max())

Installation

Prerequisites

Python 3.8 (or higher) and pip/conda are required to install Holocron.

Latest stable release

You can install the last stable release of the package using pypi as follows:

pip install pylocron

or using conda:

conda install -c frgfm pylocron

Developer mode

Alternatively, if you wish to use the latest features of the project that haven't made their way to a release yet, you can install the package from source (install Git first):

git clone https://github.com/frgfm/Holocron.git
pip install -e Holocron/.

Paper references

PyTorch layers for every need

• Activation: HardMish, NLReLU, FReLU
• Loss: Focal Loss, MultiLabelCrossEntropy, MixupLoss, ClassBalancedWrapper, ComplementCrossEntropy, MutualChannelLoss, DiceLoss, PolyLoss
• Convolutions: NormConv2d, Add2d, SlimConv2d, PyConv2d, Involution
• Regularization: DropBlock
• Pooling: BlurPool2d, SPP, ZPool
• Attention: SAM, LambdaLayer, TripletAttention

Models for vision tasks

• Image Classification: Res2Net (based on the great implementation from Ross Wightman), Darknet-24, Darknet-19, Darknet-53, CSPDarknet-53, ResNet, ResNeXt, TridentNet, PyConvResNet, ReXNet, SKNet, RepVGG, ConvNeXt, MobileOne.
• Object Detection: YOLOv1, YOLOv2, YOLOv4
• Semantic Segmentation: U-Net, UNet++, UNet3+

Vision-related operations

• boxes: Distance-IoU & Complete-IoU losses

Trying something else than Adam

• Optimizer: LARS, Lamb, TAdam, AdamP, AdaBelief, Adan, and customized versions (RaLars)
• Optimizer wrapper: Lookahead, Scout (experimental)

More goodies

Documentation

The full package documentation is available here for detailed specifications.

Demo app

The project includes a minimal demo app using Gradio

You can check the live demo, hosted on 🤗 HuggingFace Spaces 🤗 over here 👇

Reference scripts

Reference scripts are provided to train your models using holocron on famous public datasets. Those scripts currently support the following vision tasks:

• Image classification
• Object detection
• Semantic segmentation

Latency benchmark

You crave for SOTA performances, but you don't know whether it fits your needs in terms of latency?

In the table below, you will find a latency benchmark for all supported models:

The reported latency for RepVGG models is the one of the reparametrized version

This benchmark was performed over 100 iterations on (224, 224) inputs, on a laptop to better reflect performances that can be expected by common users. The hardware setup includes an Intel(R) Core(TM) i7-10750H for the CPU, and a NVIDIA GeForce RTX 2070 with Max-Q Design for the GPU.

You can run this latency benchmark for any model on your hardware as follows:

python scripts/eval_latency.py rexnet1_0x

All script arguments can be checked using python scripts/eval_latency.py --help

Docker container

If you wish to deploy containerized environments, you can use the provided Dockerfile to build a docker image:

docker build . -t <YOUR_IMAGE_TAG>

Minimal API template

Looking for a boilerplate to deploy a model from Holocron with a REST API? Thanks to the wonderful FastAPI framework, you can do this easily.

Deploy your API locally

Run your API in a docker container as follows:

cd api/
make lock-api
make run-api

In order to stop the container, use make stop-api

What you have deployed

Your API is now running on port 8080, with its documentation http://localhost:8080/redoc and requestable routes:

import requests
with open('/path/to/your/img.jpeg', 'rb') as f:
    data = f.read()
response = requests.post("http://localhost:8080/classification", files={'file': data}).json()

Citation

If you wish to cite this project, feel free to use this BibTeX reference:

@software{Fernandez_Holocron_2020,
author = {Fernandez, François-Guillaume},
month = {5},
title = {{Holocron}},
url = {https://github.com/frgfm/Holocron},
year = {2020}
}

Contributing

Any sort of contribution is greatly appreciated!

You can find a short guide in CONTRIBUTING to help grow this project!

License

Distributed under the Apache 2.0 License. See LICENSE for more information.