Add ViT models, HSI Hang2020, inference API, and taxonomic level classification

[Ritesh313]

Summary

This PR adds two major feature sets to the NeonTreeClassification pipeline: expanded model architectures and a complete inference API with taxonomic level support.

---

Commit 1 — New model architectures & DeepForest compatibility groundwork

Breaking changes:

• Default RGB image size changed from 128×128 → 224×224
• Default RGB normalization changed from 0_1 → imagenet
  • For backward compatibility, pass rgb_size=(128, 128) and rgb_norm_method='0_1' explicitly

New features:

• Vision Transformer (ViT) support: vit_b_16, vit_b_32, vit_l_16, vit_l_32
• Hang2020 dual-pathway attention architecture for HSI classification
• model_variant CLI parameter for architecture selection
• Preliminary DeepForest CropModel compatibility methods (normalize(), label_dict persistence, set_label_dict(), get_label_dict()) — WIP
• Multi-output training with auxiliary losses (Hang2020)
• HuggingFace upload script (experimental)
• Better SLURM experiment naming to prevent array job collisions

---

Commit 2 — Inference API & taxonomic level classification

New features:

• Complete neon_tree_classification.inference module with TreeClassifier class
  • TreeClassifier.from_checkpoint() for easy model loading
  • predict() with batch support and image preprocessing pipeline
• Species-level (167 classes) and genus-level (60 classes) classification
• taxonomic_level parameter in DataModule ('species' or 'genus')
• WeightedRandomSampler for class balancing
• Label mapping JSON files for both species and genus
• External test set with species overlap filtering

Documentation:

• New taxonomic_levels.md — comprehensive guide to taxonomic level training and inference
• Updated training.md and train.py

No breaking changes in this commit.

---

Testing

• test_inference.py covers TreeClassifier loading and prediction
• create_label_mappings.py for label validation

[Copilot]

Pull request overview

This PR expands NeonTreeClassification with additional model architectures (ViT for RGB and Hang2020 for HSI), adds an inference API (TreeClassifier) with taxonomic-level (species/genus) support, and updates training/docs/scripts to support the new workflows.

Changes:

• Added ViT RGB model variants and Hang2020 HSI architecture with multi-output (aux loss) training support.
• Introduced neon_tree_classification.inference module (preprocessing, label mappings, registry, predictor API) plus scripts for label mapping creation and HF uploads.
• Added genus-level training support in the DataModule (label mapping + optional balanced sampling) and updated docs/examples accordingly.

Reviewed changes

Copilot reviewed 21 out of 23 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
scripts/upload_to_huggingface.py	New utility to convert/upload checkpoints to HF; writes config/model card and safetensors.
scripts/test_inference.py	New manual inference “test” script for running predictions from HDF5 samples.
scripts/create_label_mappings.py	New script to generate species/genus label mapping JSONs for inference.
sample_plots/test_PSMEM_douglas_fir.png	Adds an example plot asset.
processing/misc/inspect_labels.py	Adds a label/genus inspection script to validate genus extraction assumptions.
notebooks/visualization.ipynb	Updates notebook outputs/cell execution metadata and sample CSV path.
neon_tree_classification/models/rgb_models.py	Adds ViT-based RGB classifier and extends RGB model factory.
neon_tree_classification/models/lightning_modules.py	Adds DeepForest compatibility helpers; adds multi-output loss support for HSI classifier.
neon_tree_classification/models/hsi_models.py	Implements Hang2020 dual-pathway attention architecture and adds it to the factory.
neon_tree_classification/inference/utils.py	Adds utilities for label loading, prediction formatting, checkpoint metadata extraction, etc.
neon_tree_classification/inference/preprocessing.py	Adds image loading/resizing/normalization/tensor preparation pipeline for inference.
neon_tree_classification/inference/predictor.py	Adds TreeClassifier high-level inference API.
neon_tree_classification/inference/model_registry.py	Adds a local registry for known pretrained model metadata and label mapping resolution.
neon_tree_classification/inference/label_mappings/species_labels.json	Adds committed species label mapping used by inference.
neon_tree_classification/inference/label_mappings/genus_labels.json	Adds committed genus label mapping used by inference.
neon_tree_classification/inference/init.py	Exposes inference API/public functions via package imports.
neon_tree_classification/core/dataset.py	Updates default RGB preprocessing (224 + ImageNet) and adds genus mapping support in label validation/lookup.
neon_tree_classification/core/datamodule.py	Adds taxonomic_level and optional WeightedRandomSampler balanced sampling; genus label mapping creation.
examples/train.py	Adds CLI args for model variant, taxonomic level, RGB size/norm; passes idx_to_label for checkpoint metadata.
docs/training.md	Updates baseline result table and notes for new configs.
docs/taxonomic_levels.md	New guide for genus/species training and filtering guidance.
README.md	Updates project status lines and notes.
.gitignore	Adds an extra ignored markdown file entry.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 23 out of 25 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.