Update README.md

README.md

@@ -1,3 +1,142 @@
----
-license: mit
----
+---
+license: mit
+---
+# Package Damage Detection Model
+
+By: Evan Ancheta
+
+## 1. Model Description
+
+### Context
+This project develops a YOLOv11 object detection model that detects damaged and undamaged shipping packages in images. 
+The model predicts bounding boxes around packages and classifies each detected package as either damaged or normal.
+Detecting package damage automatically could help logistics systems identify problems earlier in the shipping process. 
+For example, warehouse monitoring systems could use a model like this to flag packages that may require manual inspection.
+
+### Training Approach
+The model was trained using YOLOv11 object detection within the Ultralytics framework. 
+The model was fine-tuned from pretrained COCO weights and then trained on a custom dataset of package images.
+Using pretrained weights allows the model to reuse general visual features learned from large image datasets before adapting them to the specific task of package damage detection.
+
+### Intended Use Cases
+Potential Applications of this model include:
+
+- warehouse package inspection
+- automated logistics monitoring
+- research experiments involving object detection
+- prototype quality-control systems
+
+This model is intended for research and experimentation and should not be used as a fully automated system without human oversight.
+
+---
+
+## 2. Training Data
+
+### Data Sources
+The dataset used for training was created by combining two pre-annotated package detection datasets from Roboflow Universe:
+
+https://universe.roboflow.com/nani-tmzf6/package-detection-5ozpr  
+https://universe.roboflow.com/roboflow-ngkro/package-detection-e1ssd
+
+These datasets contain images of shipping packages with bounding box annotations identifying package locations and damage conditions.
+
+### Dataset Size
+
+The combined dataset contains approximately **2,787 images**.
+
+### Original Class Labels Across Datasets
+Because the datasets came from different sources, they used slightly different label names. The original labels included:
+
+- Box  
+- Package  
+- Box_broken  
+- Open_package  
+- damaged  
+
+These labels were inconsistent across datasets and required standardization before training.
+
+### Annotation Process
+The dataset preparation process involved several steps:
+
+- combined two pre-annotated datasets  
+- standardized inconsistent class labels across datasets  
+- verified bounding box annotations  
+- reduced the number of classes  
+
+After cleaning and relabeling, the dataset was reduced to two classes representing the condition of each package.
+
+### Final Classes Used for Training
+
+| Class | Count |
+|------|------|
+| normal | 1575 |
+| damaged | 1212 |
+
+The dataset is relatively balanced between damaged and undamaged packages.
+
+### Train / Validation / Test Split
+
+| Split | Ratio | Approximate Images |
+|------|------|-------------------|
+| Train | 70% | ~1951 |
+| Validation | 20% | ~557 |
+| Test | 10% | ~279 |
+
+### Data Augmentation
+
+The following augmentations were applied during training:
+
+| Augmentation | Purpose |
+|--------------|--------|
+| Horizontal flip | simulate packages placed in different orientations |
+| Image rotation | simulate packages rotated on the floor or conveyor |
+| Brightness adjustment | simulate different lighting conditions |
+
+These augmentations help the model generalize better to real-world environments.
+
+### Known Biases and Dataset Limitations
+The dataset contains mostly cardboard shipping boxes photographed under relatively consistent lighting conditions. As a result, the model may perform less reliably when detecting different packaging materials or under significantly different lighting environments. Some types of package damage may also appear less frequently in the dataset.
+
+---
+
+## 3. Training Procedure
+
+- Framework: Ultralytics YOLOv11n
+- Hardware: A100 GPU in Google Colab
+- Epochs: 50
+- Batch Size: 64
+- Image Size: 640x640
+- Patience: 50
+- Training Time: ~7.44 minutes (446.58 seconds)
+- Preprocessing: Augmentations applied at training time (see Data Augmentation section)
+
+---
+
+## 4. Evaluation Results
+
+### Comprehensive Metrics
+
+The YOLOv11 model was evaluated on a held-out validation dataset using standard object detection metrics. 
+These metrics measure how accurately the model detects packages and classifies them as damaged or normal.
+
+| Metric | Value |
+|------|------|
+| Precision | 0.927 |
+| Recall | 0.919 |
+| mAP50 | 0.959 |
+| mAP50-95 | 0.868 |
+
+Overall, the model achieves strong detection performance, with a high mAP50 score indicating that the model is able to accurately detect package locations and classify damage in most cases.
+
+### Per-Class Breakdown
+
+| Class | Images | Instances | Precision | Recall | mAP50 | mAP50-95 |
+|------|------|------|------|------|------|------|
+| all | 499 | 538 | 0.927 | 0.919 | 0.959 | 0.868 |
+| damaged | 329 | 329 | 0.966 | 0.963 | 0.988 | 0.904 |
+| normal | 170 | 209 | 0.887 | 0.876 | 0.930 | 0.832 |
+
+The model performs slightly better at detecting damaged packages than normal ones. This may be because damage features such as dents or torn cardboard create stronger visual cues for the model.
+
+### Visual Examples of Classes
+