Update README.md

README.md

@@ -1,3 +1,116 @@
----
-license: apache-2.0
----
+---
+tags:
+- image-classification
+- birder
+- pytorch
+library_name: birder
+license: apache-2.0
+base_model:
+- birder-project/vit_l16_mim
+---
+
+# Model Card for vit_l16_mim-eu-common
+
+A ViT image classification model. The model follows a two-stage training process: first, masked image modeling, then fine-tuned specifically on the `eu-common` dataset.
+
+The species list is derived from the Collins bird guide [^1].
+
+[^1]: Svensson, L., Mullarney, K., & Zetterström, D. (2022). Collins bird guide (3rd ed.). London, England: William Collins.
+
+## Model Details
+
+- **Model Type:** Image classification and detection backbone
+- **Model Stats:**
+    - Params (M): 304.1
+    - Input image size: 256 x 256
+- **Dataset:** eu-common (707 classes)
+
+- **Papers:**
+    - An Image is Worth 16x16 Words: Transformers for Image Recognition at Scale: <https://arxiv.org/abs/2010.11929>
+    - Masked Autoencoders Are Scalable Vision Learners: <https://arxiv.org/abs/2111.06377>
+
+## Model Usage
+
+### Image Classification
+
+```python
+import birder
+from birder.inference.classification import infer_image
+
+(net, model_info) = birder.load_pretrained_model("vit_l16_mim-eu-common", inference=True)
+
+# Get the image size the model was trained on
+size = birder.get_size_from_signature(model_info.signature)
+
+# Create an inference transform
+transform = birder.classification_transform(size, model_info.rgb_stats)
+
+image = "path/to/image.jpeg"  # or a PIL image, must be loaded in RGB format
+(out, _) = infer_image(net, image, transform)
+# out is a NumPy array with shape of (1, 707), representing class probabilities.
+```
+
+### Image Embeddings
+
+```python
+import birder
+from birder.inference.classification import infer_image
+
+(net, model_info) = birder.load_pretrained_model("vit_l16_mim-eu-common", inference=True)
+
+# Get the image size the model was trained on
+size = birder.get_size_from_signature(model_info.signature)
+
+# Create an inference transform
+transform = birder.classification_transform(size, model_info.rgb_stats)
+
+image = "path/to/image.jpeg"  # or a PIL image
+(out, embedding) = infer_image(net, image, transform, return_embedding=True)
+# embedding is a NumPy array with shape of (1, 1024)
+```
+
+### Detection Feature Map
+
+```python
+from PIL import Image
+import birder
+
+(net, model_info) = birder.load_pretrained_model("vit_l16_mim-eu-common", inference=True)
+
+# Get the image size the model was trained on
+size = birder.get_size_from_signature(model_info.signature)
+
+# Create an inference transform
+transform = birder.classification_transform(size, model_info.rgb_stats)
+
+image = Image.open("path/to/image.jpeg")
+features = net.detection_features(transform(image).unsqueeze(0))
+# features is a dict (stage name -> torch.Tensor)
+print([(k, v.size()) for k, v in features.items()])
+# Output example:
+# [('neck', torch.Size([1, 1024, 16, 16]))]
+```
+
+## Citation
+
+```bibtex
+@misc{dosovitskiy2021imageworth16x16words,
+      title={An Image is Worth 16x16 Words: Transformers for Image Recognition at Scale},
+      author={Alexey Dosovitskiy and Lucas Beyer and Alexander Kolesnikov and Dirk Weissenborn and Xiaohua Zhai and Thomas Unterthiner and Mostafa Dehghani and Matthias Minderer and Georg Heigold and Sylvain Gelly and Jakob Uszkoreit and Neil Houlsby},
+      year={2021},
+      eprint={2010.11929},
+      archivePrefix={arXiv},
+      primaryClass={cs.CV},
+      url={https://arxiv.org/abs/2010.11929},
+}
+
+@misc{he2021maskedautoencodersscalablevision,
+      title={Masked Autoencoders Are Scalable Vision Learners},
+      author={Kaiming He and Xinlei Chen and Saining Xie and Yanghao Li and Piotr Dollár and Ross Girshick},
+      year={2021},
+      eprint={2111.06377},
+      archivePrefix={arXiv},
+      primaryClass={cs.CV},
+      url={https://arxiv.org/abs/2111.06377},
+}
+```