# OCR-D Walkthrough

Agenda: https://hackmd.io/tVlVEqw3Qp6V0yn-x2QbNQ

## Existing repositories

### `core`

...

### `assets`

- Sample files
- for testing tool invocation
- as a reference for input and output formats
- No GT for training or testing on a larger scale
- You are invited to add specific test cases there!

### `spec`

- Specifications for
- File formats
- GT annotation
- Tool APIs
- Recipes for various things
- Easily accessible via https://ocr-d.github.io/

### `ocrd_*`

- Wrappers for existing OCR tools
- Maintained by the coordination project
- Implementing best practices
- Allows for *real* OCR use cases
- **Use them to test your tool!**

## Recommended repository layout

README.md
LICENSE
ocrd-tool.json
ocrd_*/
Dockerfile
setup.py

## GitHub settings

* Add `ocr-d` tag, other tags as sensible
* Fill out the short description
* Enable or at least do not disable issues

### README

- Describes the tool
- Sections:
- Installation
- Including external dependencies!
- Invocation
- Known issues

### `LICENSE`

- Contains the license of your code
- May not be more restrictive than `Apache License 2.0`

### `ocrd-tool.json`

- *Formal* description of your tool
- Used for seamless workflow integration
- Contains information on mandatory **and** optional parameters

### `Dockerfile`

- *Formal* instructions on how to create a Docker image for your tool
- Simple text-based [DSL](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/)

### `ocrd_*/`

- Directory containing the actual source code
- May be either:
- A thin wrapper to another repository providing an API (e.g. `ocrd_kraken`)
- A stand-alone tool (e.g. `ocrd_keraslm`)

## Howtos

- Using the required repository layout gives you many bonuses
- Seamless interaction with the OCR-D stack
- Creating docker images
- Validating your `ocrd-tool.json`
- ...

### Set up a workspace

Sample object: http://deutsches-textarchiv.de/book/show/nzz_hexe_1782
1. Create working directory

   mkdir sample_workspaces

2. Initialize workspace

   ocrd workspace init workshop-test
   cd workshop-test

3. Add images to workspace

   wget "http://media.dwds.de/dta/images/nzz_hexe_1782/nzz_hexe_1782_0001_1600px.jpg"
   ocrd workspace add --file-grp OCR-D-IMG --file-id OCR-D-IMG_0001 --page-id OCR-D-IMG_0001 --mimetype image/jpeg nzz_hexe_1782_0001_1600px.jpg

4. Assign a unique identifier to the METS

ocrd workspace set-id nzz_hexe_1786

5. Validate the workspace

   ocrd workspace validate mets.xml

### Set up a tool chain

In principle, we have two options:
1. Running different tools sequentially

    ocrd-kraken-binarize -l DEBUG \ 
     -I OCR-D-IMG \
     -O OCR-D-IMG-BIN \
     -m mets.xml
    ocrd-tesserocr-segment-region -l DEBUG \
     -I OCR-D-IMG-BIN \
     -O OCR-D-SEG-BLOCK \
     -m mets.xml \
     -p tess_param.json

2. Use `ocrd process` as a meta command

   ocrd process -l DEBUG -m mets.xml \
    "kraken-binarize \
     -I OCR-D-IMG -O OCR-D-IMG-BIN" \
    "tesserocr-segment-region \
     -I OCR-D-IMG-BIN -O OCR-D-SEG-BLOCK \
     -p tess_param.json"

The parameter file is simple:

   {
	"model": "Fraktur"
   }

3. Task: Perform OCR with tesseract!

### Validate your `ocrd-tool.json`

ocrd ocrd-tool ocrd-tool.json validate

### Create a docker image

...