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
Holocron provides research implementations with PyTorch interfaces. Implementations and training recipes may differ from a paper author's code. This example uses an explicit checkpoint and its preprocessing and labels:
import torch
from PIL import Image
from holocron.models.classification import ResNet18_Checkpoint, resnet18
checkpoint = ResNet18_Checkpoint.IMAGENETTE.value
model = resnet18(checkpoint=checkpoint).eval()
image = Image.open(path_to_an_image).convert("RGB")
input_tensor = checkpoint.transforms()(image).unsqueeze(0)
with torch.inference_mode():
probabilities = model(input_tensor).squeeze(0).softmax(dim=0)
class_idx = probabilities.argmax().item()
label = checkpoint.meta.categories[class_idx]
confidence = probabilities[class_idx].item()
print(label, confidence)An architecture may be available without pretrained weights. See the checkpoint list and loading guide for classification datasets, metrics and weight compatibility, and the support status for other tasks. Most classification checkpoints target Imagenette (10 classes); selected ReXNet variants also provide ImageNet-1K weights (1,000 classes).
Use the checkpoint's preprocessing and category metadata, as shown above.
A matching model name does not make torchvision or timm weights compatible.
To adapt pretrained weights to your own classes, load them before replacing the
classifier; see the transfer-learning guide.
Legacy weight loaders log a warning and keep the affected model's initial
parameters when no weights are available. YOLO26 builders instead raise
ValueError for pretrained=True. No full detection checkpoints are published; a pretrained
classification backbone is not a pretrained detector. Train models without
weights with the reference scripts.
PolyLoss expects raw logits and either torch.int64 class indices or soft
class probabilities. See the loss input guide and runnable example
for tensor shapes, target types and the current ignore_index limitations.
Python 3.11 (or higher) and uv/pip are required to install Holocron.
You can install the last stable release of the package using pypi as follows:
pip install pylocronAlternatively, 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/.- 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
- 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+
- Optimizer: LARS, Lamb, TAdam, AdamP, AdaBelief, Adan, and customized versions (RaLars), AdEMAMix
- Optimizer wrapper: Lookahead, Scout (experimental)
The full package documentation is available here for detailed specifications.
The project includes a minimal demo app using Gradio
You can check the live demo, hosted on 🤗 HuggingFace Spaces 🤗 over here 👇
Reference scripts are provided to train your models using holocron on famous public datasets. Those scripts currently support the following vision tasks:
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.
Pareto-optimal Imagenette checkpoints for accuracy and latency, on CPU or GPU:
| Model | Acc@1 | Params | CPU (ms) | MPS (ms) |
|---|---|---|---|---|
mobileone_s0 |
88.08% | 4.3M | 6.7 | 1.7 |
mobileone_s1 |
91.26% | 3.6M | 11.8 | 1.9 |
mobileone_s2 |
91.31% | 5.9M | 14.4 | 2.4 |
resnet18 |
93.61% | 11.2M | 16.4 | 2.7 |
darknet19 |
93.86% | 19.8M | 19.2 | 3.1 |
rexnet1_0x |
94.39% | 3.5M | 19.8 | 6.5 |
rexnet1_5x |
94.47% | 7.8M | 30.3 | 6.6 |
resnext50_32x4d |
94.55% | 23.0M | 33.2 | 7.4 |
resnet50d |
94.65% | 23.5M | 28.4 | 7.6 |
rexnet1_3x |
94.88% | 5.9M | 26.1 | 8.2 |
rexnet2_0x |
95.24% | 13.8M | 39.5 | 7.7 |
rexnet2_2x |
95.44% | 16.7M | 43.8 | 8.6 |
Median batch-1 latency per architecture at 224×224 on an Apple M3 Pro (one CPU thread, or its GPU via MPS), PyTorch 2.13. See the checkpoint table for all 31 checkpoints and the measurement guide to reproduce on your hardware:
uv sync --locked --extra scripts
uv run --no-sync python scripts/eval_latency.py rexnet1_0x --device cpuIf you wish to deploy containerized environments, you can use the provided Dockerfile to build a docker image:
make build-apiLooking for a boilerplate to deploy a model from Holocron with a REST API? Thanks to the wonderful FastAPI framework, you can do this easily.
Run your API in a docker container as follows:
make start-apiIn order to stop the container, use make stop-api
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()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}
}Any sort of contribution is greatly appreciated!
You can find a short guide in CONTRIBUTING to help grow this project!
Distributed under the Apache 2.0 License. See LICENSE for more information.