Update README.md

README.md

@@ -11,4 +11,130 @@ tags:
   - historical-images
   - document-analysis
   - die-bombe
----
+---
+
+# YOLOv8 Object Detection Model for *Die Bombe*
+
+## Model Description
+
+This repository contains a fine-tuned **YOLOv8m** object detection model trained on digitized pages of the historical satirical periodical [*Die Bombe*](https://anno.onb.ac.at/info/bom_info.html).
+
+The model is based on the Ultralytics `yolov8m.pt` checkpoint.
+
+## Classes
+
+The annotation schema contains seven categories:
+
+- `Advertisement`
+- `Comic`
+- `Editorial Cartoon`
+- `Headline`
+- `Illustration`
+- `Map`
+- `Photograph`
+
+The training data contain the following numbers of annotated objects:
+
+| Class | Training instances |
+| --- | ---: |
+| Advertisement | 2,596 |
+| Headline | 1,471 |
+| Illustration | 465 |
+| Editorial Cartoon | 140 |
+| Comic | 61 |
+| Photograph | 1 |
+| Map | 0 |
+
+`Photograph` and `Map` are therefore part of the annotation schema but are not meaningfully represented in the trained model.
+
+## Training Data
+
+The model was trained on manually annotated pages of *Die Bombe*.
+
+The dataset was divided into:
+
+- **508 training pages**
+- **106 validation pages**
+
+The training and validation sets contain separate periodical issues.
+
+The annotated training dataset is published separately on Zenodo:
+
+**Dataset:** [Training-Dataset_Bombe_1871-1925]  
+**DOI:** [[10.5281/zenodo.18757852](https://doi.org/10.5281/zenodo.18757852)]
+
+## Training Configuration
+
+Training was performed with Ultralytics YOLOv8 using the following configuration:
+
+| Parameter | Value |
+| --- | --- |
+| Base model | `yolov8m.pt` |
+| Maximum epochs | 100 |
+| Image size | 1280 |
+| Batch size | 4 |
+| Workers | 2 |
+| Patience | 20 |
+| Optimizer | SGD |
+| Initial learning rate (`lr0`) | 0.01 |
+| Cosine learning-rate schedule | `True` |
+| Mosaic augmentation | 1.0 |
+| Cache | `False` |
+| Seed | 0 |
+| Deterministic | `True` |
+
+Early stopping was enabled with a patience value of 20. No further improvement in mAP@0.50–0.95 was observed after epoch 17, and training stopped after epoch 37.
+
+The best-performing checkpoint is provided as `best.pt`.
+
+## Evaluation
+
+The final model was evaluated on the held-out validation set of **106 pages containing 1,004 annotated objects**.
+
+### Overall Results
+
+| Metric | Score |
+| --- | ---: |
+| Precision | 0.836 |
+| Recall | 0.835 |
+| mAP@0.50 | 0.913 |
+| mAP@0.50–0.95 | 0.722 |
+
+### Class-Specific Results
+
+| Class | Instances | Precision | Recall | mAP@0.50 | mAP@0.50–0.95 |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| Advertisement | 505 | 0.930 | 0.935 | 0.967 | 0.879 |
+| Comic | 10 | 0.746 | 0.900 | 0.945 | 0.567 |
+| Editorial Cartoon | 33 | 0.737 | 0.818 | 0.859 | 0.788 |
+| Headline | 341 | 0.953 | 0.827 | 0.961 | 0.703 |
+| Illustration | 115 | 0.814 | 0.696 | 0.832 | 0.673 |
+
+`Photograph` and `Map` do not have meaningful evaluation results because they are not sufficiently represented in the training data.
+
+## Reproducibility
+
+The code and notebooks used for model training, evaluation, and subsequent processing are available in the *Building Character* GitHub repository:
+
+**Code:** https://github.com/lisagollner/Building-Character_Code
+
+The Corpus created with the workflow using this model is distributed over Zenodo:
+
+**Corpus-Title**: Building Character Corpus
+
+**DOI**: [10.5281/zenodo.21918823](https://doi.org/10.5281/zenodo.21918823)
+
+The model was trained using:
+
+- **Ultralytics:** YOLOv8.2.0
+- **Python:** 3.12.13
+- **PyTorch:** 2.4.1+cu121
+- **GPU:** NVIDIA Tesla T4
+
+Additional training configuration is included with the model files.
+
+## License
+
+This model is released under the **GNU Affero General Public License v3.0 (AGPL-3.0)**.
+
+The model was trained using the Ultralytics YOLOv8 framework. Users should consult the applicable Ultralytics and AGPL-3.0 licensing terms when reusing or redistributing the model.