Update README.md

README.md

@@ -14,26 +14,26 @@ tags:
 - geotechnics
 ---
 
-# Core Sample Main Fraction Classifier
+# 🪨 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 from cropped core sample images (300x300 pixels):
-- Clay (T)
-- Silt (U)
-- Sand (S)
-- Gravel (G)
+- 🟤 Clay (T)
+- 🤎 Silt (U)
+- 🟡 Sand (S)
+- ⚪ Gravel (G)
 
-## Metrics
+## 📊 Metrics
 
 The following table summarizes selected metrics quantifying the model performance on the test set:
 
-| Metric                             | Value  |
+| 📈 Metric                          | Value  |
 |------------------------------------|--------|
 | Categorical Cross-Entropy Loss     | 0.0998 |
 | Accuracy                           | 0.9606 |
 | F1-score (macro, aggregated)       | 0.8195 |
 | F1-score (weighted, aggregated)    | 0.9597 |
 
-## Hyperparameters
+## ⚙️ Hyperparameters
 
 The following table summarizes selected hyperparameters used for training the model:
 
@@ -45,11 +45,53 @@ The following table summarizes selected hyperparameters used for training the mo
 | Metric for best model     | Cat. CE  |
 | Early stopping patience   | 3        |
 
-## Usage
+## 🚀 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"]
+label = sample["HB"]
+
+# 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 `HB` more labels than the four identified by the model. This may require binning procedures, e.g., fS => S. Details can be found in the citation documented below.
 
 ## ✨ Citation
 If you use this model, please cite: