Using PyPotteryScan

PyPotteryScan turns a folder of scanned plates into a dataset: one clean image per vessel, plus a catalogue with the text written next to it. You mark the vessels and their labels on each plate, a local OCR model reads the labels, you clean the drawings and check the text, and the app exports everything in one ZIP. This guide follows the app tab by tab, in the order you will use them. Everything is saved automatically inside your project, so you can stop at any time and pick up later.

The workflow at a glance

Projects → 1. Load → 2. Annotate → 3. Process OCR → 4. Clean Drawings → 5. Review Texts → 6. Export → (optional) Parser Studio

The numbered tabs unlock one after the other as you complete each step. When you reopen an existing project, the app unlocks the tabs that match what the project already contains (see Reopening a project).

Key terms

Term	Meaning
Plate	One scanned image, usually a page with several vessel drawings on it.
Drawing	A rectangle you draw around one vessel. It is cut out of the plate and becomes one image in the export. Numbered D1, D2… on each plate.
Text box	A rectangle you draw around a label that belongs to a drawing (an inventory number, a context, a note). Numbered T1, T2… inside its drawing. This is what the OCR reads.
Table/Plate	The name you give to a plate (for example “Plate I” or “1342_004”). It travels with every drawing of that plate into the catalogue.
Cropped / cleaned drawing	The crop of a drawing straight from the plate / the version you erased and straightened in the Clean tab.
Prefix	The name you choose in the Export tab. It starts the name of every exported file.

Projects

Every dataset lives in its own project: a self-contained folder with your scans, annotations, crops, OCR results and few-shot examples. You can keep as many projects as you like and switch between them freely.

Create a project

Click New Project (or Create First Project if the list is empty).
Enter a Project Name (required), for example Monte Bibele 2024.
Optionally add a short description.
Click Create Project. The app opens the 1. Load tab.

The project is stored in the projects folder next to the app, in a folder named after the project plus the creation date and time (for example Monte_Bibele_2024_20260917_101500). Characters other than letters, digits, spaces, - and _ are dropped from the folder name.

Your projects

Each project is a card showing its name, description, creation and modification dates, the number of images, how many plates are annotated, and a progress bar. Click the card, or Open, to work on it. The trash icon deletes the project after a confirmation.

Warning

Deleting a project is irreversible: it removes the images, annotations, crops, OCR results and everything else in its folder.

Reopening a project

Opening a project takes you to the 1. Load tab and restores what was saved. Which tabs are unlocked depends on what exists in the project:

Tab	Unlocked when the project has…
2. Annotate	at least one image
3. Process OCR	at least one annotated plate
4. Clean Drawings	cropped or cleaned drawings
5. Review Texts and 6. Export	saved OCR results

If you skipped OCR there are no saved results, so on reopening Review and Export stay locked until you go through 4. Clean Drawings and click Continue to Review Texts.

Project folder

project_id/
├── original_images/    # your scans (copies of the files you loaded)
├── thumbnails/         # cached thumbnails
├── annotations/        # one JSON file per plate: boxes and metadata
├── cropped_drawings/   # crops of every drawing and text box
├── cleaned_drawings/   # drawings you cleaned
├── ocr_results/        # OCR text and your corrections (JSON)
├── exports/            # created with the project but not used: exports are downloaded by the browser
├── fewshot_examples/   # examples saved by the Parser Studio
└── project.json        # project name, description, dates, progress

1. Load

The Load tab is where the scans enter the project.

Drag and drop image files here, or click Select Files; or click Select Folder to import every image inside a folder. Supported formats are JPEG, PNG, WebP, TIFF and BMP; other files are ignored. When you import a folder, only the files directly inside it are read, not its subfolders.
The files are copied into the project (original_images), so your originals are never modified. If you load a file with the same name as one already in the project, it replaces it.
The Plate Catalog shows a thumbnail of every plate. Add Files and Add Folder bring in more scans at any time, and clicking a plate opens it directly in the Annotate tab.
Start Annotation takes you to the Annotate tab.

Tip

Use one image per plate, at a resolution where the smallest label is still readable at 100%. The crops are cut from the full-resolution image, so the more detail the scan has, the better the drawings and the OCR.

2. Annotate

Here you tell the app what is on each plate. The plate is shown on a canvas; on the right you find the plate’s metadata, the list of its drawings, and the overall progress.

The controls

Prev / Next and the counter (for example 3 / 12) move between plates. A Saved badge confirms every change.
Drawing (D) starts a new drawing box. Delete Box (Del) appears when something is selected. Clear removes every box on the current plate, after a confirmation.
Image Metadata: Table/Plate, Context and Notes for the current plate.
Drawings: a card per drawing (D1, D2…) with the number of texts it has, its size in pixels, a delete button and Add Text (T).
Plate Annotation: the percentage of plates completed. A plate counts as completed when it has at least one drawing and a Table/Plate name.
Finish & Process OCR saves everything and moves on.

Mark the vessels

Click Drawing (D) or press D.
Drag a rectangle around the vessel. Boxes smaller than about 10 pixels on screen are ignored.
The box stays selected. Drag it to move it, or drag its corners and edges to resize it. With a box selected, the arrow keys nudge it by 2 pixels (10 with Shift).

After each box the tool goes back to idle: press D again for the next vessel. Esc cancels the tool or the selection. To delete a drawing, select it (on the canvas or in the list) and press Delete or Backspace, or use its trash button.

Mark the labels

Select the drawing the label belongs to.
Click Add Text (T) on its card, or press T.
Drag a rectangle around the label.

Repeat for every label of the drawing: they are numbered T1, T2… in the order you draw them, and the OCR will read them in that order. If you press T with no drawing selected, the app reminds you to select one first. A text box does not have to be inside the drawing box, so labels printed elsewhere on the plate work as well. Selecting a text box and pressing Delete removes only that box.

Give the plate a name

Fill in Table/Plate (for example Plate I), and optionally Context and Notes. They are saved as you type. The name shows up in the Clean and Review tabs and, in the export, in the table_name column for every drawing of that plate. A plate without a name is not counted as completed in the progress bar.

Finish

Finish & Process OCR needs at least one annotated plate. The app then cuts a crop for every drawing (<plate>_d1.png) and every text box (<plate>_d1_t1.png) and saves it in the project, with a progress overlay, and opens the 3. Process OCR tab.

3. Process OCR

This tab reads the text boxes with the OCR model you chose on first launch.

Run the recognition

Click Start OCR Processing. The app crops every text box from the full-resolution plate and sends them to the local model one by one. You can follow it in three places: the Extraction Progress bar with the counter of text boxes, a status line saying which drawing and box is being read, and the list of Recognized Text Labels, which grows as results arrive, each tagged with its drawing and box (for example plate_1.jpg_d1 · T1).

The Details button opens a log of the run; Copy Extracted Texts copies the results to the clipboard. When the run ends you see Text Extraction Complete!, the results are saved in the project, and Continue to Clean Drawings appears. You can run the recognition again with Re-run OCR Processing: the recognized text is replaced, while the corrections you typed in the Review tab are stored separately and are kept.

If a box cannot be read, its entry shows the error in red and the text is recorded as Error; you can fix it by hand in the Review tab or retry the run. A GPU makes the recognition faster.

Note

The app asks for at least one text box, and for an installed OCR model. Without a text box you are told to draw one in step 2; without a model you are told to use Skip OCR.

Skip OCR

Skip OCR (Manual Input) (after a confirmation) unlocks the next tabs without recognizing anything: you type the label text yourself in the Review tab. It is the right choice when you chose No OCR model on first launch, when the labels are handwritten and unreadable, or when you only need the drawings. You can still come back and click Start OCR Processing at any time.

4. Clean Drawings

Every drawing you marked is opened here at full resolution, one after the other in plate order, so you can remove what does not belong to the vessel (numbers, dimensions, stray marks) before export. The header shows the plate name, the drawing (D1, D2…) and its size in pixels.

Erase

Click Eraser (or press E) and drag over what you want to remove: the area turns white. A circle previews the size of the eraser.

Size slider: 4 to 120 pixels (20 by default). The presets set 6, 16, 32 or 64 pixels. [ and ] change the size by 5 pixels, and with the eraser on, the mouse wheel changes it too.
Undo (Ctrl+Z, Cmd+Z on macOS) goes back up to 30 steps. Revert discards your changes and returns to the original crop.
Zoom: the −, + and reset buttons, the + and - keys, or Ctrl/Alt with the mouse wheel.

Straighten

Tilted scans can be levelled without redrawing anything:

Straighten slider: from −45° to +45° in 0.1° steps, with a live readout.
Micro-adjustments −0.5°, −0.1°, +0.1°, +0.5°, 0° to reset (R), and −90° / +90° to rotate the drawing by a quarter turn.
Grid Guide (G) overlays horizontal and vertical lines over the drawing, to level the rim or the base against them.
Auto-Fit trims the empty white margins around the drawing, leaving a small border.

Confirm

Mark Clean (or M) saves the drawing, adds a green check to it in the All Extracted Drawings grid and moves to the next one. The grid also lets you jump to any drawing, and shows how many are cleaned. ← and → (or Previous / Next) move between drawings without marking them; the work on the drawing you leave is saved, and the eraser is switched off.

Cleaning is optional per drawing: the export uses the cleaned version when it exists and the original crop otherwise. When you are done, Continue to Review Texts.

5. Review Texts

The tab lists every text box of every drawing as a pair: on the left the image of the label, tagged with the plate name and the drawing and box numbers (for example Plate I, D2 - T1); on the right an editable box with the recognized text. Compare and correct.

Click the label image to open it enlarged.
Changes are auto-saved a moment after you stop typing. Only real edits count as corrections: if you change a text and then restore it, the correction is removed.
If you skipped OCR, the boxes start empty and you type each label from the image.
The catalogue keeps both versions: the raw OCR and your corrected text (see Export).

When you are done, Continue to Export.

6. Export

The last tab packages the project. At the top you see four counters: Total Plates, Vessel Drawings, OCR Transcriptions (number of text boxes) and Manual Corrections.

Choose a prefix

Archive Filename Prefix is the name that starts every exported file (ceramic by default). Use only letters, digits, _ and -: any other character is replaced by _. The line below shows the name of the ZIP that will be created, <prefix>_export_<date>.zip.

Download

Download Complete ZIP Package (.zip) renders every drawing and builds the whole package. The file is downloaded by your browser, into your usual downloads folder.
Download Excel (.xlsx) downloads only the catalogue, as a single workbook with two sheets: Catalogue & OCR and ML Bounding Boxes.

What is in the ZIP

<prefix>_export_<date>.zip
├── images/
│   ├── <prefix>_001.jpg          # one JPEG per drawing (quality 95)
│   ├── <prefix>_002.jpg
│   └── ...
├── <prefix>_metadata_<date>.xlsx      # catalogue (sheet "Catalogue & OCR")
├── <prefix>_metadata_<date>.csv       # same catalogue as CSV
├── <prefix>_ml_training_<date>.xlsx   # box coordinates (sheet "Bounding Boxes")
├── <prefix>_ml_training_<date>.csv    # same coordinates as CSV
└── README_export.txt

The images are numbered in plate order, then drawing order. The CSV files are comma-separated, UTF-8 with a byte-order mark so that Excel opens accents correctly, and line breaks inside a text are replaced by spaces.

The catalogue has one row per drawing:

Column	Content
`filename`	the exported image, for example `ceramic_001.jpg`
`original_image`	the plate it came from
`drawing_number`	D number of the drawing on its plate
`table_name`, `context`, `notes`	the metadata of the plate
`ocr_result`	the text as recognized by the OCR; when a drawing has several text boxes, they are joined with `\|`
`ocr_corrected`	the same after your corrections in the Review tab

The ML training file has one row for every drawing box and every text box, with image_name, drawing_number, box_type (vessel or text), x, y, width, height (in pixels of the original plate), label, text_index (for text boxes) and the size of the plate (image_width, image_height). It is meant for training detection models.

After the download, Continue to Few-Shot Parser Studio takes you to the optional last step.

Parser Studio

The Parser Studio turns free text such as MB 2024 US 112 inv. 4501 into fields (Site, Year, US, Inventory…). It is a separate tool, outside the main six steps: it works on a spreadsheet, so you can use it on the catalogue you just exported, or on a previous one.

It uses a small local language model (Qwen3.5-2B) with few-shot learning: you show it a few lines already split into fields, and it applies the same pattern to all the others. Nothing leaves your computer.

Click Choose File and select the .xlsx catalogue. The app reads the first sheet and needs an ocr_corrected column; rows with no text are skipped, and the filename column, if present, is carried along.
The Available fields on the left are Inventory, Site, Year, US, Area, Cut, Sector and Notes. Add Field creates your own.
Use Previous / Next to move between lines (1 / N). The current line is shown as text: select the part that corresponds to a field and pick the field from the small menu that appears. The Current Parsed Data table (Field / Value) shows what you have assigned: the x at the end of a row removes that assignment if you made a mistake (the highlight disappears too), and assigning the same field again replaces the previous one.
Click Add Example to store the line as an example. Added Examples counts them: click its title to open or close the list (closed at the start); Clear All Examples empties the list after a confirmation. If you assigned fields on a line and click Previous, Next or Reset before adding it as an example, the app asks you to confirm, because those assignments would be lost. Examples are saved in the project, so you can reuse them later.
Click Run Parsing. The model is loaded the first time (it may take a moment), then every line is parsed, with a live log. The result is downloaded as parsed_output_<date>.xlsx, sheet Parsed Data: one row per line, one column per field found, plus _ocr_original (the source text) and _filename. A field the model cannot find is left empty.

You need at least one example to run the parser. Start with a handful of varied lines; if a field comes out wrong, add an example that shows it. Always check the result: a language model can misassign a field, especially with abbreviations it has never seen.

Note

If the parsing model could not be downloaded on first launch, Run Parsing tells you so; restart PyPotteryScan with an internet connection to retry the download.

Keyboard shortcuts

Where	Key	Action
Annotate	`D`	New drawing box
Annotate	`T`	New text box for the selected drawing
Annotate	`Delete` / `Backspace`	Delete the selected box
Annotate	`Esc`	Cancel the tool or the selection
Annotate	Arrow keys	Nudge the selected box by 2 px (10 px with `Shift`)
Clean Drawings	`E`	Toggle the eraser
Clean Drawings	`G`	Toggle the alignment grid
Clean Drawings	`R`	Reset the straighten angle to 0°
Clean Drawings	`M`	Mark the drawing as clean
Clean Drawings	`Ctrl+Z`	Undo
Clean Drawings	`[` / `]`	Smaller / larger eraser
Clean Drawings	`+` / `-`	Zoom in / out
Clean Drawings	`←` / `→`	Previous / next drawing
Clean Drawings	Mouse wheel	Eraser size (with the eraser on); `Ctrl`/`Alt` + wheel to zoom

Shortcuts are ignored while you are typing in a text field.

Common mistakes

No Table/Plate name. The plate is not counted as completed and table_name is empty in the catalogue. Fill it in before you leave the plate.
Text box drawn without a drawing. Text boxes belong to a drawing: select it first (or use Add Text on its card).
Forgetting to press D again. After each box the tool goes back to idle.
A box that looks too small. Rectangles under about 10 pixels on screen are discarded; zoom in the browser if the label is tiny.
Loading a file with the same name twice. The second one replaces the first inside the project.
Review and Export locked after reopening a project where you skipped OCR. Open 4. Clean Drawings and click Continue to Review Texts: that unlocks them.
Deleting a project by mistake. There is no undo and no recycle bin.