Using PyPotteryInk

PyPotteryInk takes a scan or a photograph of a pencil pottery drawing and redraws it as clean ink line art, ready for publication. It does this with a generative model that works on the image in small squares (patches), so plates of any size can be processed. This guide follows the four tabs of the app in the order you will normally use them. The Need help? button in the header of the app (Pixel) opens this page.

The workflow at a glance

Hardware Check (once) → Preprocessing (optional) → Model Diagnostics (a few test images) → Batch Processing (the whole collection)

Key terms

Term Meaning
Model The trained “style” the app applies: one is best for Bronze Age drawings, another for painted pottery, and so on. See the Model Zoo.
Patch size The side, in pixels, of the squares the image is cut into (512 by default). Larger patches give the model more context but are slower.
Overlap How many pixels neighbouring patches share (64 by default), so that no seams are visible between them.
Contrast A factor applied to each patch before the model sees it: above 1 makes the pencil stronger, below 1 fainter.
Scale factor Temporarily enlarges (above 1) or shrinks (below 1) the image before processing. The result is always saved at the original size.
Statistics file (.npy) A small file that describes the brightness and contrast of a set of drawings. Preprocessing uses it to make your images resemble them.

Hardware Check

This tab tells you whether your computer is suited to the job. It lists the recommended specifications (an NVIDIA GPU with at least 8 GB of VRAM, minimum 4 GB, or Apple Silicon; 4 or more modern CPU cores; 16 GB of RAM, minimum 8 GB; a fast SSD).

Click Check Hardware and the app shows:

  • an overall verdict, with a one-sentence conclusion: Highly Recommended, Recommended, Limited Use or Not Recommended. A GPU below the minimum gives Not Recommended; any other component below the minimum gives Limited Use;
  • one card each for the GPU, RAM, CPU and disk, with the value found and its status (excellent, adequate or limited);
  • a few tips: use patch size 512 for a good balance of speed and quality, enable FP16 if you have a CUDA GPU, and close other applications to free memory.

The Info button in the header opens a window with the version, the citation to copy, links to the documentation and to GitHub, and the hardware the app detected (the number of CPU cores, and the GPU or CPU Only).

Preprocessing

Drawings differ a lot in brightness and contrast, and the models work best on images that look like the ones they were trained on. This optional tab adjusts your images towards a reference described by a statistics file.

  1. Upload Images to Preprocess: click the area or drag and drop your images (PNG, JPG, JPEG or TIFF).
  2. Upload Statistics File (.npy): choose the reference. The app ships with two, in its own folder:
    • Montale_stats.npy, measured on the dataset used to train the 6h-MCG model;
    • Cimino_stats.npy, measured on the dataset used to train the 6h-MC model.
  3. Output Directory: where the adjusted images are saved (./preprocessed_images by default, created if it does not exist). Browse… opens a folder dialog on the computer that runs the app.
  4. Click Apply Preprocessing. A progress bar follows the work.

Each image is compared with the statistics: only the images that need it are adjusted, the others are saved unchanged. All of them are written to the output directory with their original file name. When it ends, the app reports the total processed, how many images were adjusted and how many needed no adjustment.

Make your own reference

Open Advanced: Calculate Custom Statistics to build a statistics file from your own drawings. Upload a representative set of images (for example the drawings you want your results to resemble), choose where to Save Statistics As (./custom_stats.npy by default) and click Calculate Statistics. The app shows how many images it analyzed, where the file is, and a table with the mean, standard deviation, minimum, maximum and median of every metric. You can then use the new file in the steps above.

Model Diagnostics

Before processing a whole collection, test the model on a few images. This tab runs the model on up to five of your drawings and shows you how the parameters change the result, so you can choose the best ones for the batch.

Set up the test

  1. Select Model: the list shows every available model with its size and description, and Custom Model (Local File)… to use your own .pkl file (it must be trained with the same architecture). A model is downloaded automatically the first time it is used.
  2. Upload Sample Images (Max 5): choose up to five drawings. With more than five the app asks you to select fewer.
  3. Patch Size (512 by default, from 256 to 1024 in steps of 64) and Overlap (64 by default, from 0 to 256 in steps of 16).
  4. Contrast Test Values: the contrast factors to try, separated by commas (0.75, 1.0, 1.5, 2.0 by default). Add or remove values as you like.
  5. Click Run Diagnostics. A progress bar counts the tests: one per image and contrast value.

Read the results

When the test ends, a gallery shows, for every image:

  • a patch map (patches_N.png): how the image is divided into patches with your patch size and overlap;
  • a contrast analysis (contrast_analysis_N.png): one row for every contrast value, with the input at that contrast on the left and the model output on the right.

Click any picture to open it in full screen (Esc or a click outside closes it). Open Diagnostics Folder opens the folder with the files, which also contains a short summary_N.txt per image (file name, size, number of patches, estimated memory).

Look for the row where the lines are complete and clean. As a rule of thumb, pencil lines that disappear call for a higher contrast, and a background that turns into noise for a lower one. That value is the Contrast Scale to use in the batch.

Note

The first time you run a diagnostic or a batch, the app needs its models: the small style model, and once the ~5 GB diffusion backbone (sd-turbo). A progress overlay shows the live download status so the app never looks stuck.

Warning

The diagnostic files are stored in the app’s temp_diagnostics folder and are deleted the next time you run a diagnostic. Copy the ones you want to keep.

Batch Processing

This is the tab where the whole collection is inked.

Set up the batch

1. AI Model & Source Drawings

  • Select Model: as in the diagnostic, with the same option to use a custom .pkl model. Below the list a note says the model will be downloaded if it is not present.
  • Upload Pottery Drawings: click or drag and drop all your images (PNG, JPG, JPEG or TIFF). The number of files selected is shown.

2. Reconstruction Parameters

Parameter Default Range What it does
Patch Size 512 256 to 1024 Size of the squares the image is cut into
Overlap 64 0 to 256 Pixels shared by neighbouring patches
Contrast Scale 1.0 0.5 to 3.0 Contrast applied before the model: above 1 strengthens faint lines
Scale Factor 1 0.25 to 4 Above 1 enlarges the image before processing (better quality, slower), below 1 shrinks it (faster). The output keeps the original size
Use FP16 off Half precision, faster and lighter on memory; works only on NVIDIA GPUs and is ignored elsewhere

3. Output Destination & Execution

  • Output Directory: the folder where the results are saved (./enhanced_pottery by default, relative to the app folder; an absolute path works too). Browse… opens a folder dialog.
  • Click Start Processing.

While it runs

The app uploads the images, checks the model and the diffusion backbone (downloading them if needed), and starts. Two progress bars follow the work: Overall Progress for the images, and Current Image Patches for the patches of the image being processed. If one image fails, the others continue.

The results

At the end the app shows a summary: how many images were Successful and Failed, the Average time per image, the Output directory and the Log file; the Open Output Folder button opens that folder in your file manager. Below it, a gallery shows the first 20 comparison images; click one to see it full screen.

The output directory contains:

<output directory>/
├── <name>.<ext>                   # one image per input, same file name as the input
├── comparisons/
│   └── comparison_<name>.<ext>    # original and result side by side
└── logs/
    └── processing_log_<date>.txt  # settings, sizes, times and failed files

Every result is a grayscale image at the original size of the drawing. If an image is smaller than the patch size, it is padded with white up to the patch size first. Existing files with the same name in the output folder are overwritten, so use a new folder for each run.

Tips

  • Do a diagnostic first. Five images and a handful of contrast values tell you more than a full batch run.
  • Keep the settings consistent. Process a collection with the same model, patch size, overlap and contrast, so the drawings look alike in the publication.
  • Preprocessing needs a statistics file. If the button says to select a .npy file, choose one of the two provided or build your own.
  • Slow? Lower the overlap, use a smaller scale factor, or use FP16 on an NVIDIA GPU. On the CPU alone, run a small batch first to estimate the time.
  • Say you used it. Results come from a generative model: state the model, the number of drawings and the version in your methods, as described in Getting Started.