{"id":14971624,"url":"https://github.com/frgfm/holocron","last_synced_at":"2025-05-15T14:06:18.943Z","repository":{"id":37939937,"uuid":"192422914","full_name":"frgfm/Holocron","owner":"frgfm","description":"PyTorch implementations of recent Computer Vision tricks (ReXNet, RepVGG, Unet3p, YOLOv4, CIoU loss, AdaBelief, PolyLoss, MobileOne). Other additions: AdEMAMix","archived":false,"fork":false,"pushed_at":"2025-03-21T20:17:56.000Z","size":418072,"stargazers_count":328,"open_issues_count":9,"forks_count":48,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-05-15T14:06:11.978Z","etag":null,"topics":["ademamix","computer-vision","cspdarknet53","darknet","deep-learning","object-detection","pytorch","resnet","rexnet","tridentnet","unet-image-segmentation","yolo","yolov4"],"latest_commit_sha":null,"homepage":"https://frgfm.github.io/Holocron/latest","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/frgfm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"frgfm","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2019-06-17T21:45:59.000Z","updated_at":"2025-04-18T09:04:25.000Z","dependencies_parsed_at":"2024-01-28T14:50:50.628Z","dependency_job_id":"178c23c8-aef3-48a4-aa44-7cdf9d6c1628","html_url":"https://github.com/frgfm/Holocron","commit_stats":{"total_commits":349,"total_committers":4,"mean_commits":87.25,"dds":0.09742120343839544,"last_synced_commit":"84f775c3956b71f43ae3392e43a620dd4982c4e4"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frgfm%2FHolocron","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frgfm%2FHolocron/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frgfm%2FHolocron/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frgfm%2FHolocron/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/frgfm","download_url":"https://codeload.github.com/frgfm/Holocron/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254355335,"owners_count":22057354,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ademamix","computer-vision","cspdarknet53","darknet","deep-learning","object-detection","pytorch","resnet","rexnet","tridentnet","unet-image-segmentation","yolo","yolov4"],"created_at":"2024-09-24T13:45:34.098Z","updated_at":"2025-05-15T14:06:13.921Z","avatar_url":"https://github.com/frgfm.png","language":"Python","funding_links":["https://github.com/sponsors/frgfm"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/frgfm/Holocron/releases/download/v0.1.3/holocron_logo_text.png\" width=\"40%\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/frgfm/Holocron/actions/workflows/build.yml\"\u003e\n    \u003cimg alt=\"CI Status\" src=\"https://img.shields.io/github/actions/workflow/status/frgfm/holocron/build.yml?branch=main\u0026label=CI\u0026logo=github\u0026style=flat-square\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/astral-sh/ruff\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Linter-Ruff-FCC21B?style=flat-square\u0026logo=ruff\u0026logoColor=white\" alt=\"ruff\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/astral-sh/ruff\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Formatter-Ruff-FCC21B?style=flat-square\u0026logo=Python\u0026logoColor=white\" alt=\"ruff\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.codacy.com/gh/frgfm/Holocron/dashboard?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=frgfm/Holocron\u0026amp;utm_campaign=Badge_Grade\"\u003e\u003cimg src=\"https://app.codacy.com/project/badge/Grade/49fc8908c44b45d3b64131e49558f1e9\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://codecov.io/gh/frgfm/holocron\"\u003e\n    \u003cimg src=\"https://img.shields.io/codecov/c/github/frgfm/holocron.svg?logo=codecov\u0026style=flat-square\" alt=\"Test coverage percentage\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/pylocron/\"\u003e\n    \u003cimg src=\"https://img.shields.io/pypi/v/pylocron.svg?logo=python\u0026logoColor=fff\u0026style=flat-square\u0026label=PyPI\" alt=\"PyPi Status\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://anaconda.org/frgfm/pylocron\"\u003e\n    \u003cimg src=\"https://img.shields.io/conda/v/frgfm/pylocron.svg?logo=anaconda\u0026label=Conda\u0026logoColor=fff\u0026style=flat-square\" alt=\"Conda Version\"\u003e\n  \u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/pypi/pyversions/pylocron.svg?logo=Python\u0026label=Python\u0026logoColor=fff\u0026style=flat-square\" alt=\"pyversions\"\u003e\n  \u003ca href=\"https://github.com/frgfm/Holocron/blob/main/LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/license/frgfm/Holocron.svg?label=License\u0026logoColor=fff\u0026style=flat-square\" alt=\"License\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://huggingface.co/spaces/frgfm/holocron\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue\" alt=\"Huggingface Spaces\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://colab.research.google.com/github/frgfm/notebooks/blob/main/holocron/quicktour.ipynb\"\u003e\n    \u003cimg src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open in Colab\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://frgfm.github.io/holocron\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/actions/workflow/status/frgfm/holocron/page-build.yml?branch=main\u0026label=Documentation\u0026logo=read-the-docs\u0026logoColor=white\u0026style=flat-square\" alt=\"Documentation Status\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nImplementations of recent Deep Learning tricks in Computer Vision, easily paired up with your favorite framework and model zoo.\n\n\u003e **Holocrons** were information-storage [datacron](https://starwars.fandom.com/wiki/Datacron) devices used by both the [Jedi Order](https://starwars.fandom.com/wiki/Jedi_Order) and the [Sith](https://starwars.fandom.com/wiki/Sith) that contained ancient lessons or valuable information in [holographic](https://starwars.fandom.com/wiki/Hologram) form.\n\n*Source: Wookieepedia*\n\n## Quick Tour\n[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/frgfm/notebooks/blob/main/holocron/quicktour.ipynb)\n\nThis 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:\n\n```python\nfrom PIL import Image\nfrom torchvision.transforms import Compose, ConvertImageDtype, Normalize, PILToTensor, Resize\nfrom torchvision.transforms.functional import InterpolationMode\nfrom holocron.models.classification import repvgg_a0\n\n# Load your model\nmodel = repvgg_a0(pretrained=True).eval()\n\n# Read your image\nimg = Image.open(path_to_an_image).convert(\"RGB\")\n\n# Preprocessing\nconfig = model.default_cfg\ntransform = Compose([\n    Resize(config['input_shape'][1:], interpolation=InterpolationMode.BILINEAR),\n    PILToTensor(),\n    ConvertImageDtype(torch.float32),\n    Normalize(config['mean'], config['std'])\n])\n\ninput_tensor = transform(img).unsqueeze(0)\n\n# Inference\nwith torch.inference_mode():\n    output = model(input_tensor)\nprint(config['classes'][output.squeeze(0).argmax().item()], output.squeeze(0).softmax(dim=0).max())\n```\n\n\n## Installation\n\n### Prerequisites\n\nPython 3.9 (or higher) and [pip](https://pip.pypa.io/en/stable/)/[conda](https://docs.conda.io/en/latest/miniconda.html) are required to install Holocron.\n\n### Latest stable release\n\nYou can install the last stable release of the package using [pypi](https://pypi.org/project/pylocron/) as follows:\n\n```shell\npip install pylocron\n```\n\nor using [conda](https://anaconda.org/frgfm/pylocron):\n\n```shell\nconda install -c frgfm pylocron\n```\n\n### Developer mode\n\nAlternatively, 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](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) first)*:\n\n```shell\ngit clone https://github.com/frgfm/Holocron.git\npip install -e Holocron/.\n```\n\n## Paper references\n\n### PyTorch layers for every need\n- Activation: [HardMish](https://github.com/digantamisra98/H-Mish), [NLReLU](https://arxiv.org/abs/1908.03682), [FReLU](https://arxiv.org/abs/2007.11824)\n- Loss: [Focal Loss](https://arxiv.org/abs/1708.02002), MultiLabelCrossEntropy, [MixupLoss](https://arxiv.org/pdf/1710.09412.pdf), [ClassBalancedWrapper](https://arxiv.org/abs/1901.05555), [ComplementCrossEntropy](https://arxiv.org/abs/2009.02189), [MutualChannelLoss](https://arxiv.org/abs/2002.04264), [DiceLoss](https://arxiv.org/abs/1606.04797), [PolyLoss](https://arxiv.org/abs/2204.12511)\n- Convolutions: [NormConv2d](https://arxiv.org/pdf/2005.05274v2.pdf), [Add2d](https://arxiv.org/pdf/1912.13200.pdf), [SlimConv2d](https://arxiv.org/pdf/2003.07469.pdf), [PyConv2d](https://arxiv.org/abs/2006.11538), [Involution](https://arxiv.org/abs/2103.06255)\n- Regularization: [DropBlock](https://arxiv.org/abs/1810.12890)\n- Pooling: [BlurPool2d](https://arxiv.org/abs/1904.11486), [SPP](https://arxiv.org/abs/1406.4729), [ZPool](https://arxiv.org/abs/2010.03045)\n- Attention: [SAM](https://arxiv.org/abs/1807.06521), [LambdaLayer](https://openreview.net/forum?id=xTJEN-ggl1b), [TripletAttention](https://arxiv.org/abs/2010.03045)\n\n### Models for vision tasks\n- Image Classification: [Res2Net](https://arxiv.org/abs/1904.01169) (based on the great [implementation](https://github.com/rwightman/pytorch-image-models/blob/master/timm/models/res2net.py) from Ross Wightman), [Darknet-24](https://pjreddie.com/media/files/papers/yolo_1.pdf), [Darknet-19](https://pjreddie.com/media/files/papers/YOLO9000.pdf), [Darknet-53](https://pjreddie.com/media/files/papers/YOLOv3.pdf), [CSPDarknet-53](\u003chttps://arxiv.org/abs/1911.11929\u003e), [ResNet](https://arxiv.org/abs/1512.03385), [ResNeXt](https://arxiv.org/abs/1611.05431), [TridentNet](https://arxiv.org/abs/1901.01892), [PyConvResNet](https://arxiv.org/abs/2006.11538), [ReXNet](https://arxiv.org/abs/2007.00992), [SKNet](https://arxiv.org/abs/1903.06586), [RepVGG](https://arxiv.org/abs/2101.03697), [ConvNeXt](https://arxiv.org/abs/2201.03545), [MobileOne](https://arxiv.org/abs/2206.04040).\n- Object Detection: [YOLOv1](https://pjreddie.com/media/files/papers/yolo_1.pdf), [YOLOv2](https://pjreddie.com/media/files/papers/YOLO9000.pdf), [YOLOv4](https://arxiv.org/abs/2004.10934)\n- Semantic Segmentation: [U-Net](https://arxiv.org/abs/1505.04597), [UNet++](https://arxiv.org/abs/1807.10165), [UNet3+](https://arxiv.org/abs/2004.08790)\n\n### Vision-related operations\n- boxes: [Distance-IoU \u0026 Complete-IoU losses](https://arxiv.org/abs/1911.08287)\n\n### Trying something else than Adam\n- Optimizer: [LARS](https://arxiv.org/abs/1708.03888), [Lamb](https://arxiv.org/abs/1904.00962), [TAdam](https://arxiv.org/abs/2003.00179), [AdamP](https://arxiv.org/abs/2006.08217), [AdaBelief](https://arxiv.org/abs/2010.07468), [Adan](https://arxiv.org/abs/2208.06677), and customized versions (RaLars), [AdEMAMix](https://arxiv.org/abs/2409.03137)\n- Optimizer wrapper: [Lookahead](https://arxiv.org/abs/1907.08610), Scout (experimental)\n\n\n\n## More goodies\n\n### Documentation\n\nThe full package documentation is available [here](https://frgfm.github.io/holocron/) for detailed specifications.\n\n### Demo app\n\nThe project includes a minimal demo app using [Gradio](https://gradio.app/)\n\n![demo_app](https://github.com/frgfm/Holocron/releases/download/v0.1.3/holocron_gradio.png)\n\nYou can check the live demo, hosted on :hugs: [HuggingFace Spaces](https://huggingface.co/spaces) :hugs: over here :point_down:\n[![Hugging Face Spaces](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue)](https://huggingface.co/spaces/frgfm/Holocron)\n\n\n### Reference scripts\n\nReference scripts are provided to train your models using holocron on famous public datasets. Those scripts currently support the following vision tasks:\n- [Image classification](references/classification)\n- [Object detection](references/detection)\n- [Semantic segmentation](references/segmentation)\n\n### Latency benchmark\n\nYou crave for SOTA performances, but you don't know whether it fits your needs in terms of latency?\n\nIn the table below, you will find a latency benchmark for all supported models:\n\n| Arch                                                         | GPU mean (std)    | CPU mean (std)     |\n| ------------------------------------------------------------ | ----------------- | ------------------ |\n| [repvgg_a0](https://frgfm.github.io/Holocron/latest/models.html#holocron.models.repvgg_a0)* | 3.14ms (0.87ms)   | 23.28ms (1.21ms)   |\n| [repvgg_a1](https://frgfm.github.io/Holocron/latest/models.html#holocron.models.repvgg_a1)* | 4.13ms (1.00ms)   | 29.61ms (0.46ms)   |\n| [repvgg_a2](https://frgfm.github.io/Holocron/latest/models.html#holocron.models.repvgg_a2)* | 7.35ms (1.11ms)   | 46.87ms (1.27ms)   |\n| [repvgg_b0](https://frgfm.github.io/Holocron/latest/models.html#holocron.models.repvgg_b0)* | 4.23ms (1.04ms)   | 33.16ms (0.58ms)   |\n| [repvgg_b1](https://frgfm.github.io/Holocron/latest/models.html#holocron.models.repvgg_b1)* | 12.48ms (0.96ms)  | 100.66ms (1.46ms)  |\n| [repvgg_b2](https://frgfm.github.io/Holocron/latest/models.html#holocron.models.repvgg_b2)* | 20.12ms (0.31ms)  | 155.90ms (1.59ms)  |\n| [repvgg_b3](https://frgfm.github.io/Holocron/latest/models.html#holocron.models.repvgg_b3)* | 24.94ms (1.70ms)  | 224.68ms (14.27ms) |\n| [rexnet1_0x](https://frgfm.github.io/Holocron/latest/models.html#holocron.models.rexnet1_0x) | 6.01ms (0.26ms)   | 13.66ms (0.21ms)   |\n| [rexnet1_3x](https://frgfm.github.io/Holocron/latest/models.html#holocron.models.rexnet1_3x) | 6.43ms (0.10ms)   | 19.13ms (2.05ms)   |\n| [rexnet1_5x](https://frgfm.github.io/Holocron/latest/models.html#holocron.models.rexnet1_5x) | 6.46ms (0.28ms)   | 21.06ms (0.24ms)   |\n| [rexnet2_0x](https://frgfm.github.io/Holocron/latest/models.html#holocron.models.rexnet2_0x) | 6.75ms (0.21ms)   | 31.77ms (3.28ms)   |\n| [rexnet2_2x](https://frgfm.github.io/Holocron/latest/models.html#holocron.models.rexnet2_2x) | 6.92ms (0.51ms)   | 33.61ms (0.60ms)   |\n| [sknet50](https://frgfm.github.io/Holocron/latest/models.html#holocron.models.sknet50) | 11.40ms (0.38ms)  | 54.03ms (3.35ms)   |\n| [sknet101](https://frgfm.github.io/Holocron/latest/models.html#holocron.models.sknet101) | 23.55 ms (1.11ms) | 94.89ms (5.61ms)   |\n| [sknet152](https://frgfm.github.io/Holocron/latest/models.html#holocron.models.sknet152) | 69.81ms (0.60ms)  | 253.07ms (3.33ms)  |\n| [tridentnet50](https://frgfm.github.io/Holocron/latest/models.html#holocron.models.tridentnet50) | 16.62ms (1.21ms)  | 142.85ms (5.33ms)  |\n| [res2net50_26w_4s](https://frgfm.github.io/Holocron/latest/models.html#holocron.models.res2net50_26w_4s) | 9.25ms (0.22ms)   | 41.84ms (0.80ms)   |\n| [resnet50d](https://frgfm.github.io/Holocron/latest/models.html#holocron.models.resnet50d) | 36.97ms (3.58ms)  | 36.97ms (3.58ms)   |\n| [pyconv_resnet50](https://frgfm.github.io/Holocron/latest/models.html#holocron.models.pyconv_resnet50) | 20.03ms (0.28ms)  | 178.85ms (2.35ms)  |\n| [pyconvhg_resnet50](https://frgfm.github.io/Holocron/latest/models.html#holocron.models.pyconvhg_resnet50) | 38.41ms (0.33ms)  | 301.03ms (12.39ms) |\n| [darknet24](https://frgfm.github.io/Holocron/latest/models.html#holocron.models.darknet24) | 3.94ms (1.08ms)   | 29.39ms (0.78ms)   |\n| [darknet19](https://frgfm.github.io/Holocron/latest/models.html#holocron.models.darknet19) | 3.17ms (0.59ms)   | 26.36ms (2.80ms)   |\n| [darknet53](https://frgfm.github.io/Holocron/latest/models.html#holocron.models.darknet53) | 7.12ms (1.35ms)   | 53.20ms (1.17ms)   |\n| [cspdarknet53](https://frgfm.github.io/Holocron/latest/models.html#holocron.models.cspdarknet53) | 6.41ms (0.21ms)   | 48.05ms (3.68ms)   |\n| [cspdarknet53_mish](https://frgfm.github.io/Holocron/latest/models.html#holocron.models.cspdarknet53_mish) | 6.88ms (0.51ms)   | 67.78ms (2.90ms)   |\n\n**The reported latency for RepVGG models is the one of the reparametrized version**\n\nThis 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](https://ark.intel.com/content/www/us/en/ark/products/201837/intel-core-i710750h-processor-12m-cache-up-to-5-00-ghz.html) for the CPU, and a [NVIDIA GeForce RTX 2070 with Max-Q Design](https://www.nvidia.com/fr-fr/geforce/graphics-cards/rtx-2070/) for the GPU.\n\nYou can run this latency benchmark for any model on your hardware as follows:\n\n```bash\npython scripts/eval_latency.py rexnet1_0x\n```\n\n*All script arguments can be checked using `python scripts/eval_latency.py --help`*\n\n### Docker container\n\nIf you wish to deploy containerized environments, you can use the provided Dockerfile to build a docker image:\n\n```shell\nmake build-api\n```\n\n### Minimal API template\n\nLooking for a boilerplate to deploy a model from Holocron with a REST API? Thanks to the wonderful [FastAPI](https://github.com/tiangolo/fastapi) framework, you can do this easily.\n\n#### Deploy your API locally\n\nRun your API in a docker container as follows:\n\n```shell\nmake start-api\n```\n\n*In order to stop the container, use `make stop-api`*\n\n#### What you have deployed\n\nYour API is now running on port 8080, with its documentation http://localhost:8080/redoc and requestable routes:\n\n```python\nimport requests\nwith open('/path/to/your/img.jpeg', 'rb') as f:\n    data = f.read()\nresponse = requests.post(\"http://localhost:8080/classification\", files={'file': data}).json()\n```\n\n\n\n## Citation\n\nIf you wish to cite this project, feel free to use this [BibTeX](http://www.bibtex.org/) reference:\n\n```bibtex\n@software{Fernandez_Holocron_2020,\nauthor = {Fernandez, François-Guillaume},\nmonth = {5},\ntitle = {{Holocron}},\nurl = {https://github.com/frgfm/Holocron},\nyear = {2020}\n}\n```\n\n\n## Contributing\n\nAny sort of contribution is greatly appreciated!\n\nYou can find a short guide in [`CONTRIBUTING`](CONTRIBUTING.md) to help grow this project!\n\n\n\n## License\n\nDistributed under the Apache 2.0 License. See [`LICENSE`](LICENSE) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrgfm%2Fholocron","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffrgfm%2Fholocron","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrgfm%2Fholocron/lists"}