# eScriptorium Quick Guide

## Documentation and Repositories

* [https://escriptorium.readthedocs.io/en/latest/](https://escriptorium.readthedocs.io/en/latest/)

* https://gitlab.inria.fr/scripta/escriptorium
* eScriptorium UNIGE instance: [https://fondue.unige.ch/](https://fondue.unige.ch/)
* https://gitlab.unige.ch/fondue/escriptorium-fondue

* https://segmonto.github.io/

* https://github.com/mittagessen/kraken/tree/main
* https://github.com/mittagessen/kraken/blob/main/docs/user_guide/training_segmentation.rst
* https://github.com/PonteIneptique/YALTAi
* https://github.com/ultralytics/yolov5

## Models

- Model FoNDUE-GD for mss after the XVI century
- CATMuS Guidelines => Transcription principles (https://catmus-guidelines.github.io/)
- MUFI: The Medieval Unicode Font Initiative (https://mufi.info/q.php?p=mufi)

## Workflow

### Initial settings

1. Create a new project
  * ATTENTION: Currently, **it is not possible to delete or rename a project** => choose a meaningful and sharable name

2. Create new document (= ms)
  * **line offset:** baseline

3. Add images to a document (wait until the upload is finished!)

### Detect layout (Segmentation model for regions and lines)

- **First test**
  - Select first page [checkbox at the top of thumbnail]
  - Segment
    - model : default (blla.mlmodel)
    - Lines Baselines and Masks
    - Horizontal l2r
    - Check Override box
  - Check result [Edit mode : Segmentation panel]

- **Manually correct the segmentation in eScriptorium** [10-100 pages, the more the better]
  - Draw zones [Switch to region mode R]
  - Assign SegmOnto zone names to regions [Set the type on all selected lines/regions T]
    - DropCapitalZone for initials
    - MainZone
    - MarginTextZone
    - NumberingZone
    - QuireMarksZone
    - RunningTitleZone
    - TableZone
    - TitlePageZone
  - Re-segment the corrected images
  - Check and manually correct lines segmentation
    - Check the Toggle automatic reordering on line creation/deletion [little robot]
    - Cut lines if necessary [Cut through lines C]
    - Show order of lines [Toggle ordering display L]
    - Select all lines [ctrl+a]
    - Unlink selected lines from their regions [U]
    - Link selected lines to (the first detected) background region
    - Re-arrange lines [Text view, Toggle sorting mode]
  - Export corrected images as ALTO XML

- **Train the model locally**
  - Create folder and kraken environment

<code>
mkdir /Documents/kraken/
cd /Documents/kraken/
python3 -m venv kraken-env
source kraken-env/bin/activate
pip install kraken
kraken --version
pip install albumentations
</code>

  - Folder structure:

  - Train with kraken (not so good)

<code>
cd ../export_doc1631_averroes_logica_alto_20260325130540/
ls *.png | head -n 8 > train.txt
ls *.png | tail -n 2 > val.txt
realpath $(cat train.txt) > train_abs.txt
realpath $(cat val.txt) > val_abs.txt

ketos segtrain --load /Documents/kraken/blla.mlmodel -t export_doc1631_averroes_logica_alto_20260325130540/train_abs.txt -e export_doc1631_averroes_logica_alto_20260325130540/val_abs.txt -f alto --augment --resize union -N 50 -o averroes_seg
</code>

  - Train with YALTAi and YOLO (recommended)

<code>
pip install YALTAi

cd yaltai_training/
yaltai convert alto-to-yolo Averroes*.xml my-dataset --shuffle 0.1 --segmonto region

yolo task=detect mode=train model=yolov8n.pt data=my-dataset/config.yml epochs=100 batch=4 imgsz=960 device=0

yaltai kraken --device cuda:0 -I "/Documents/kraken/averroes_complete/*.png" --suffix ".xml" segment --yolo runs/detect/train/weights/best.pt -i /Documents/kraken/blla.mlmodel

kraken alto -i Averroes_Logica_JuntSecunda_01-1_2.pdf_page_221.xml Averroes_Logica_JuntSecunda_01-1_2.pdf_page_221_alto.xml

python3 convert-json2ALTO.py 

for f in *.xml; do     sed -i 's|/home/padlina/Documents/kraken/averroes_complete/||g' "$f"; done

zip -j alto_output.zip *.xml
</code>