Update README.md

README.md

@@ -15,6 +15,12 @@ tags:
 
 This directory contains the improved v2 artifact classification model with state-of-the-art performance for classifying museum artifacts by both object type and material.
 
+## Hosted Model
+
+The best model is available on Hugging Face at: **[SpyC0der77/artifact-efficientnet](https://huggingface.co/SpyC0der77/artifact-efficientnet)**
+
+You can use the model directly from Hugging Face without downloading it locally.
+
 ## Model Overview
 
 The v2 model is an advanced multi-output neural network that predicts two attributes simultaneously:
@@ -27,72 +33,19 @@ The v2 model is an advanced multi-output neural network that predicts two attrib
 - **Advanced Training**: Incorporates CutMix augmentation, Focal Loss, and mixed precision training
 - **Better Regularization**: Uses dropout and batch normalization for improved generalization
 
-## Quick Start
-
-### Prerequisites
-
-Ensure you have the required dependencies installed:
-
-```bash
-pip install torch>=2.0.0 torchvision>=0.15.0 datasets>=2.0.0 pillow>=9.0.0 timm>=1.0.22 huggingface-hub>=0.15.0
-```
-
-### Basic Inference
+## Architecture & Usage
 
-```python
-import torch
-from PIL import Image
-from torchvision import transforms
-import sys
-import os
-
-# Add the project root to Python path
-sys.path.append(os.path.join(os.path.dirname(__file__), '..', '..'))
-
-from main import load_model, run_inference
-
-# Load the model
-model_path = "model/v2/best_model.pth"
-model, label_mappings = load_model(model_path)
-
-# Prepare image
-image_path = "path/to/your/artifact.jpg"
-image = Image.open(image_path).convert('RGB')
-
-# Preprocessing transform
-transform = transforms.Compose([
-    transforms.Resize(256),
-    transforms.CenterCrop(224),
-    transforms.ToTensor(),
-    transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]),
-])
-
-pixel_values = transform(image).unsqueeze(0)  # Add batch dimension
-
-# Run inference
-device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
-preds_obj, confs_obj, preds_mat, confs_mat = run_inference(model, pixel_values, device)
-
-# Get predictions
-object_pred_id = preds_obj[0].item()
-material_pred_id = preds_mat[0].item()
-object_conf = confs_obj[0].item()
-material_conf = confs_mat[0].item()
-
-# Convert IDs to labels
-object_name = label_mappings['object_name'].get(object_pred_id, f"class_{object_pred_id}")
-material_name = label_mappings['material'].get(material_pred_id, f"class_{material_pred_id}")
-
-print(f"Predicted Object: {object_name} (confidence: {object_conf:.3f})")
-print(f"Predicted Material: {material_name} (confidence: {material_conf:.3f})")
-```
+The v2 model uses an EfficientNet-B0 backbone with an attention mechanism for multi-output classification. It processes RGB images of artifacts and outputs predictions for both object type and material composition.
 
-## Model Files
+### Input
+- **Format**: RGB images (224×224 pixels after preprocessing)
+- **Preprocessing**: Resize to 256×256, center crop to 224×224, normalize with ImageNet statistics
 
-- **`best_model.pth`**: The best performing model checkpoint with trained weights and label mappings
-- **`model_improved.pth`**: Final model after complete training
-- **`checkpoint_epoch_*.pth`**: Intermediate checkpoints saved during training
-- **`train.py`**: Training script used to create this model
+### Output
+- **Object Classification**: Predicts artifact type (e.g., "vase", "statue", "pottery")
+- **Material Classification**: Predicts material composition (e.g., "ceramic", "bronze", "stone")
+- **Confidence Scores**: Probability scores for each prediction
+- **Format**: Dictionary with 'object_name' and 'material' logits
 
 ## Model Architecture
 
@@ -115,38 +68,6 @@ Returns a dictionary with:
 - `'object_name'`: Logits for object classification
 - `'material'`: Logits for material classification
 
-## Evaluation
-
-### Using the Main Evaluation Script
-
-To evaluate the model on the Oriental Museum dataset:
-
-```bash
-# Evaluate on validation set
-python main.py --model_file model/v2/best_model.pth --output eval_results_v2.json
-
-# Evaluate with custom batch size
-python main.py --model_file model/v2/best_model.pth --batch_size 16 --output eval_results_v2.json
-```
-
-### Evaluation Metrics
-
-The evaluation script provides:
-- **Object Classification Accuracy**: Accuracy for object name prediction
-- **Material Classification Accuracy**: Accuracy for material prediction
-- **Overall Accuracy**: Samples where both predictions are correct
-- **Confidence Analysis**: Average confidence for correct vs incorrect predictions
-- **Per-sample Predictions**: Detailed results for each test sample
-
-### Expected Performance
-
-Based on validation during training:
-- Object Classification: ~85-90% accuracy
-- Material Classification: ~80-85% accuracy
-- Overall Accuracy: ~75-80% accuracy
-
-*Note: Actual performance may vary depending on the evaluation dataset and preprocessing.*
-
 ## Training Details
 
 The model was trained with the following configuration:
@@ -171,56 +92,6 @@ The model was trained with the following configuration:
 - **Gradient Scaling**: Prevents gradient underflow
 - **Early Stopping**: Saves best model based on validation accuracy
 
-## Usage Examples
-
-### Batch Inference
-
-```python
-import torch
-from PIL import Image
-from torchvision import transforms
-import sys
-import os
-
-sys.path.append(os.path.join(os.path.dirname(__file__), '..', '..'))
-from main import load_model, run_inference
-
-# Load model
-model, label_mappings = load_model("model/v2/best_model.pth")
-device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
-
-# Load multiple images
-image_paths = ["artifact1.jpg", "artifact2.jpg", "artifact3.jpg"]
-images = []
-
-transform = transforms.Compose([
-    transforms.Resize(256),
-    transforms.CenterCrop(224),
-    transforms.ToTensor(),
-    transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]),
-])
-
-for path in image_paths:
-    img = Image.open(path).convert('RGB')
-    images.append(transform(img))
-
-# Batch tensor
-batch = torch.stack(images)
-
-# Run inference
-preds_obj, confs_obj, preds_mat, confs_mat = run_inference(model, batch, device)
-
-# Process results
-for i, (obj_pred, obj_conf, mat_pred, mat_conf) in enumerate(zip(preds_obj, confs_obj, preds_mat, confs_mat)):
-    obj_name = label_mappings['object_name'].get(obj_pred.item(), f"class_{obj_pred.item()}")
-    mat_name = label_mappings['material'].get(mat_pred.item(), f"class_{mat_pred.item()}")
-
-    print(f"Image {i+1}:")
-    print(f"  Object: {obj_name} ({obj_conf:.3f})")
-    print(f"  Material: {mat_name} ({mat_conf:.3f})")
-```
-
-
 ## Troubleshooting
 
 ### Common Issues