---
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.