kbiw 0.1.1

KB Image Workflow Tool

KB Image Workflow Tool

About this software

Kbiw converts image files in digitisation batches to JP2 (JPEG 2000 Part 1) format using the Grok codec. It clones the structure of the input directory, and then replicates it in the output directory. The JP2 images are then subjected to the following quality checks:

1. Pixel comparison between each pair of source and destination images (using libvips and pyvips).
2. Check of extracted technical properties (using jpylyzer) against a user-defined Schematron profile.

The software also generates checksums of all converted images.

Dependencies

• Python (tested with versions 3.12.3 and 3.14.5)
• Grok JPEG 2000 codec (tested with version ??)
• Libvips

Installation of dependencies

Grok (all platforms)

1. Download the latest binaries of the Grok image compression software for your platform from:

   https://github.com/GrokImageCompression/grok/releases

2. Extract the ZIP file to your local file system, and make a note of the installation location. You'll need to enter this later in the kbiw configuration file.

Libvips

Linux (Ubuntu, Linux Mint)

Install libvips using:

sudo apt install libvips-dev --no-install-recommends

macOS

TODO

Windows

1. Download the latest release from the build-win64-mxe repository. For a 64 bit Windows system you need the ZIP file that follows the "vips-dev-x64-all-x.y.z.zip" naming pattern (e.g. vips-dev-x64-all-8.18.2.zip).

2. Extract the ZIP file to your local file system, and make a note of the installation location (e.g. "C:\vips-dev"). You'll need to enter this later in the kbiw configuration file.

ExifTool

Linux (Ubuntu, Linux Mint)

Install ExifTool using:

sudo apt install libimage-exiftool-perl

macOS

TODO

Windows

1. Download the 64-bit Windows executable from the ExifTool website.

2. Extract the ZIP file to your local file system.

3. In the extracted folder, rename the ExifTool executable ("exiftool(-k).exe") to "exiftool.exe.

4. Make a note of the full path to the executable (e.g. "C:\exiftool\exiftool.exe"). You'll need to enter this later in the kbiw configuration file.

Installation of kbiw

As of 2026, uv appears to be the most straightforward tool for installing Python applications on a variety of platforms (Linux, MacOS, Windows).

uv installation

First, check if uv is installed on your system by typing the uv command in a terminal:

uv

If this results in a help message, uv is installed, and you can skip directly to the "imgquad installation" section below. If not, you first need to install uv.

On Linux and MacOS you can install uv with the following command:

curl -LsSf https://astral.sh/uv/install.sh | sh

Alternatively, you can use wget if your system doesn't have curl installed:

wget -qO- https://astral.sh/uv/install.sh | sh

To install uv on Windows, open a Powershell terminal, and run the following command:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Regardless of the operating system, in some cases the installation script will update your system's configuration to make the location of the uv executable globally accessible. If this happens, just close your current terminal, and open a new one for these changes to take effect. Pay attention to the screen output of the installation script for any details on this.

kbiw installation

Use the following command to install kbiw (all platforms):

uv tool install kbiw

Then run kbiw once:

kbiw

Depending on your system, kbiw will now create a configuration folder (see next section).

Configuration

Before you can use kbiw, you need to edit the configuration file, which is located in the configuration folder. The configuration folder has the name "kbiw", and its location depends on your operating system:

• For Linux and MacOS, the configuration folder is a subdirectory of the location defined by the environment variable $XDG_CONFIG_HOME. If this variable is not set, it will be a subdirectory of the .config directory in the user's home folder (e.g. /home/johan/.config/kbiw). Note that the .config directory is hidden by default.
• For Windows, the configuration folder is a subdirectory of of the AppData\Local folder (e.g. C:\Users\johan\AppData\Local\kbiw).

Open the configuration file ("config.json") in a text editor, and edit the following values:

Variable	Meaning	Examples
grokDir	Grok installation directory	C:/Grok (Windows); ~/grok (Linux)
exifToolExecutable	ExifTool executable	C:/exiftool/exiftool.exe (Windows); /bin/exiftool (Linux)
vipsBinDir	Libvips binary dir (only needed on Windows, ignored on Linux/macOS)	C:/vips-dev/bin (Windows)

Here's an example for a Windows system:

{
  "grokDir": "`C:/Grok",
  "exifToolExecutable": "C:/exiftool/exiftool.exe",
  "vipsBinDir": "C:/vips-dev/bin",
  :
}

upgrade kbiw

Use the following command to upgrade an existing kbiw installation to the latest version:

uv tool upgrade kbiw

Licensing

KBiw is released under the Apache License, Version 2.0. Parts of the code were inspired by the Bodeleian's Image Processing library.