docs: Added example snippet & Colab ref in README (#202)

* docs: Updated README * docs: Fixed notebooks README
frgfm · Feb 5, 2022 · 67a50c7 · 67a50c7
1 parent 677255f
commit 67a50c7
Show file tree

Hide file tree

Showing 2 changed files with 55 additions and 22 deletions.
diff --git a/README.md b/README.md
@@ -12,27 +12,38 @@ Implementations of recent Deep Learning tricks in Computer Vision, easily paired
 *Source: Wookieepedia*
 
 ## Quick Tour
+[![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)
 
-### PyTorch layers for every need
-- Activation: [HardMish](https://github.com/digantamisra98/H-Mish), [NLReLU](https://arxiv.org/abs/1908.03682), [FReLU](https://arxiv.org/abs/2007.11824)
-- 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)
-- 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)
-- Regularization: [DropBlock](https://arxiv.org/abs/1810.12890)
-- Pooling: [BlurPool2d](https://arxiv.org/abs/1904.11486), [SPP](https://arxiv.org/abs/1406.4729), [ZPool](https://arxiv.org/abs/2010.03045)
-- Attention: [SAM](https://arxiv.org/abs/1807.06521), [LambdaLayer](https://openreview.net/forum?id=xTJEN-ggl1b), [TripletAttention](https://arxiv.org/abs/2010.03045)
-
-### Models for vision tasks
-- 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](<https://arxiv.org/abs/1911.11929>), [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).
-- 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)
-- Semantic Segmentation: [U-Net](https://arxiv.org/abs/1505.04597), [UNet++](https://arxiv.org/abs/1807.10165), [UNet3+](https://arxiv.org/abs/2004.08790)
-
-### Vision-related operations
-- boxes: [Distance-IoU & Complete-IoU losses](https://arxiv.org/abs/1911.08287)
-
-### Trying something else than Adam
-- Optimizer: [LARS](https://arxiv.org/abs/1708.03888), [Lamb](https://arxiv.org/abs/1904.00962), [TAdam](https://arxiv.org/pdf/2003.00179.pdf), [AdamP](https://arxiv.org/pdf/2006.08217), [AdaBelief](https://arxiv.org/abs/2010.07468), and customized versions (RaLars)
-- Optimizer wrapper: [Lookahead](https://arxiv.org/abs/1907.08610), Scout (experimental)
+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:
 
+```python
+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
@@ -64,6 +75,28 @@ git clone https://github.com/frgfm/Holocron.git
 pip install -e Holocron/.
 ```
 
+## Paper references
+
+### PyTorch layers for every need
+- Activation: [HardMish](https://github.com/digantamisra98/H-Mish), [NLReLU](https://arxiv.org/abs/1908.03682), [FReLU](https://arxiv.org/abs/2007.11824)
+- 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)
+- 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)
+- Regularization: [DropBlock](https://arxiv.org/abs/1810.12890)
+- Pooling: [BlurPool2d](https://arxiv.org/abs/1904.11486), [SPP](https://arxiv.org/abs/1406.4729), [ZPool](https://arxiv.org/abs/2010.03045)
+- Attention: [SAM](https://arxiv.org/abs/1807.06521), [LambdaLayer](https://openreview.net/forum?id=xTJEN-ggl1b), [TripletAttention](https://arxiv.org/abs/2010.03045)
+
+### Models for vision tasks
+- 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](<https://arxiv.org/abs/1911.11929>), [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).
+- 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)
+- Semantic Segmentation: [U-Net](https://arxiv.org/abs/1505.04597), [UNet++](https://arxiv.org/abs/1807.10165), [UNet3+](https://arxiv.org/abs/2004.08790)
+
+### Vision-related operations
+- boxes: [Distance-IoU & Complete-IoU losses](https://arxiv.org/abs/1911.08287)
+
+### Trying something else than Adam
+- Optimizer: [LARS](https://arxiv.org/abs/1708.03888), [Lamb](https://arxiv.org/abs/1904.00962), [TAdam](https://arxiv.org/pdf/2003.00179.pdf), [AdamP](https://arxiv.org/pdf/2006.08217), [AdaBelief](https://arxiv.org/abs/2010.07468), and customized versions (RaLars)
+- Optimizer wrapper: [Lookahead](https://arxiv.org/abs/1907.08610), Scout (experimental)
+
 
 
 ## More goodies

diff --git a/notebooks/README.md b/notebooks/README.md
@@ -4,6 +4,6 @@ Here are some notebooks compiled for users to better leverage the library capabi
 
 | Notebook     |      Description      |   |
 |:----------|:-------------|------:|
-| [Quicktour](https://github.com/frgfm/notebooks/blob/master/holocron/quicktour.ipynb) | A presentation of the main features of Holocron | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/frgfm/notebooks/blob/master/holocron/quicktour.ipynb) |
-| [HuggingFace Hub integration](https://github.com/frgfm/notebooks/blob/master/holocron/hf_hub.ipynb) | Use HuggingFace model hub with Holocron | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/frgfm/notebooks/blob/master/holocron/hf_hub.ipynb) |
-| [Image classification](https://github.com/frgfm/notebooks/blob/master/holocron/classification_training.ipynb) | How to train your own image classifier | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/frgfm/notebooks/blob/master/holocron/classification_training.ipynb) |
+| [Quicktour](https://github.com/frgfm/notebooks/blob/main/holocron/quicktour.ipynb) | A presentation of the main features of Holocron | [![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) |
+| [HuggingFace Hub integration](https://github.com/frgfm/notebooks/blob/main/holocron/hf_hub.ipynb) | Use HuggingFace model hub with Holocron | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/frgfm/notebooks/blob/main/holocron/hf_hub.ipynb) |
+| [Image classification](https://github.com/frgfm/notebooks/blob/main/holocron/classification_training.ipynb) | How to train your own image classifier | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/frgfm/notebooks/blob/main/holocron/classification_training.ipynb) |