pylocron 0.3.0

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.v2 import Compose, ConvertImageDtype, Normalize, PILToTensor, Resize
from torchvision.transforms.v2.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.11 (or higher) and uv/pip 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

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), AdEMAMix
• 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

YOLO training status

YOLOv4's training implementation has been repaired and verified with regression tests and a reproducible CPU fixed-batch learning check. With a frozen pretrained Imagenette CSPDarknet53-Mish backbone, it produces correctly labeled detections with IoUs of 0.81 and 0.79 on two synthetic examples, with finite losses and gradients and a saved checkpoint. See the detection guide for the command, matched control, and CUDA/VOC smoke recipe.

Full CUDA/VOC training on the repaired implementation remains pending; the synthetic result does not establish dataset accuracy or reproduce the paper. YOLOv1/v2 loss behavior is unchanged, with regression coverage for shared inference changes. YOLOv3 is not implemented as a detector; the Darknet-53 classification backbone is available. No pretrained detection checkpoints are published.

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:

make build-api

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:

make start-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.