README.md

---
license: mit
datasets:
- grano1/core_sample_image_data
language:
- en
metrics:
- accuracy
- f1
base_model:
- microsoft/swinv2-tiny-patch4-window16-256
pipeline_tag: image-classification
tags:
- geotechnics
---

# 🪨 Core Sample Main Fraction Classifier

This multi-label classification model was fine-tuned for automated visual analysis of soil core samples, and trained / validated / tested on the `grano1/core_sample_image_data` dataset available via the HuggingFace eco-system. The model aims to predict one of the following four class labels - termed in accordance with DIN 4023 - from cropped core sample images (300x300 pixels):
- 🟤 Clay (T)
- 🤎 Silt (U)
- 🟡 Sand (S)
- ⚪ Gravel (G)

## 📊 Metrics

The following table summarizes selected metrics quantifying the model performance on the test set:

| 📈 Metric                          | Value  |
|------------------------------------|--------|
| Categorical Cross-Entropy Loss     | 0.0946 |
| Accuracy                           | 0.9718 |
| F1-score (macro, aggregated)       | 0.8765 |
| F1-score (weighted, aggregated)    | 0.9712 |

## ⚙️ Hyperparameters

The following table summarizes selected hyperparameters used for training the model:

| Metric                    | Value    |
|---------------------------|----------|
| Batch size                | 8       |
| Optimizer                 | AdamW    |
| Warm-up ratio             | 0.1      |
| Metric for best model     | F1-Score (Macro)  |
| Early stopping patience   | 3        |

## 🚀 Usage

```python
# Load the dataset
data_dataset = load_dataset("grano1/core_sample_image_data")

# Load image processor and model
processor = AutoImageProcessor.from_pretrained("grano1/core_sample_image_main_fraction_model")
model = AutoModelForImageClassification.from_pretrained("grano1/core_sample_image_main_fraction_model")
model.eval()  # Set model to evaluation mode

# Show sample features
data_dataset["test"].features

# Select sample from test set
split = "test"
sample = data_dataset[split][2]  # Pick one sample
image = sample["image"]

# Prepare input for model
inputs = processor(images=image, return_tensors="pt")

# Run inference
with torch.no_grad():
    outputs = model(**inputs)
    logits = outputs.logits
    predicted_class = logits.argmax(dim=1).item()
print(sample)

# Get predicted and true label name
id2label = model.config.id2label
label2id = model.config.label2id
predicted_label_name = id2label[predicted_class]

# Show result
print(f"✅ Predicted label: {predicted_label_name}")
print(f"🧾 True label:      {sample['HB']}")

# Display image
plt.imshow(sample['image'])
plt.axis('off')  # Hide axes
plt.show()
```

## 🔒 Limitations
The `grano1/core_sample_image_data` dataset includes more `HB` labels than the four identified by this model. This may require binning procedures, e.g., fS => S. Instructions can be found in the citation documented below.

## ✨ Citation
If you use this model, please cite:

```bibtex
@inproceedings{Granitzer.2025,
 author = {Granitzer, Andreas-Nizar and Beck, Johannes and Leo, Johannes and Tschuchnigg, Franz},
 title = {Explainable Insight into the Vision-Based Classification of Soil Core Samples from Close-Range Images},
 pages = {228--233},
 editor = {Uzielli, Marco and Phoon, Kok-Kwang},
 booktitle = {Proceedings of the 3rd Workshop on the Future of Machine Learning in Geotechnics (3FOMLIG)},
 year = {2025},
 address = {Florence, Italy}
}