| --- |
| pipeline_tag: image-classification |
| library_name: pytorch |
| license: apache-2.0 |
| tags: |
| - image-classification |
| - computer-vision |
| - convnext |
| - cactus |
| - trichocereus |
| --- |
| |
| # Trichocereus Cactus Classifier |
|
|
| ConvNeXt Small image classifier for three *Trichocereus* species, three cactus |
| lookalikes, and a limited `unknown` category trained from other plants. |
|
|
| This model repository is published under the Apache-2.0 license. Training images are |
| not included; they remain subject to the terms and attribution requirements of their |
| respective source observations. Source image license and attribution records are kept |
| in the project dataset manifest. |
|
|
| ## Model details |
|
|
| - Architecture: Torchvision ConvNeXt Small, initialized from pretrained ImageNet |
| weights and fine-tuned for seven classes. |
| - Input: RGB image, resized to 256 pixels on the shorter side, center-cropped to |
| 224 × 224, converted to a tensor, and normalized with ImageNet mean and standard |
| deviation. |
| - Output: scores for each class, sorted from highest to lowest. |
| - Classes: `miss_cereus_repandus`, `miss_myrtillocactus_geometrizans`, |
| `miss_pilosocereus_pachycladus`, `trichocereus_bridgesii`, |
| `trichocereus_pachanoi`, `trichocereus_peruvianus`, and `unknown`. |
|
|
| This is a custom PyTorch/Torchvision model. It is not a Transformers `AutoModel` and |
| requires the included `inference.py` loader. The model files can be hosted on the Hub; |
| the Hub does not require a model to use Transformers. |
|
|
| ## Evaluation |
|
|
| On the held-out test split of 169 images, the model achieved **87.6% accuracy** and |
| **0.874 macro F1**. For the sampled unknown-plant examples, unknown recall was **95.7%** |
| (22 of 23), with **0% known-class rejection** (0 of 146). The validation-selected |
| additional confidence threshold was 0.00, so no extra low-confidence rejection is |
| applied. |
|
|
| The `unknown` class represents only the sampled other cacti, succulents, and plants. |
| It does not represent every possible out-of-scope image. In particular, non-plant |
| objects can receive a confident cactus prediction. Scores are softmax outputs and are |
| not calibrated probabilities. |
|
|
| Detailed held-out metrics and validation threshold analysis are included in |
| `test-metrics.json` and `calibration.json`. |
|
|
| ## Dataset and training |
|
|
| The training dataset was assembled from research-grade iNaturalist observations. |
| Splits were grouped by observation to reduce leakage between training and evaluation. |
| Source image license and attribution records are kept in the project dataset manifest; |
| those records and the images themselves are not included here. |
|
|
| Training, dataset preparation, and export code: [cactus-classifier](https://github.com/joeressler/cactus-classifier). |
| For a FastAPI and HTMX application that serves this classifier, see |
| [cactus-server](https://github.com/joeressler/cactus-server). |
|
|
| ## Inference |
|
|
| Install dependencies from `requirements.txt`, then download this repository with the |
| Hugging Face Hub client and pass an image to the custom loader: |
|
|
| ```python |
| from huggingface_hub import snapshot_download |
| from PIL import Image |
| |
| from inference import load_model, predict |
| |
| model_dir = snapshot_download("YOUR_USERNAME/cactus-classifier") |
| model, preprocess, class_names, device = load_model(model_dir) |
| |
| with Image.open("cactus.jpg") as image: |
| scores = predict(image, model, preprocess, class_names, device) |
| |
| print(scores[0]) |
| ``` |
|
|
| Replace `YOUR_USERNAME/cactus-classifier` with the final Hub repository ID. |
|
|
