Vesuvius Kintsugi is a tool designed for the Vesuvius Challenge (https://scrollprize.org/) aimed at facilitating labeling 3D voxel data extracted from the Herculaneum scrolls. This tool alleviates the complexities of annotating 3D segments by providing an intuitive interface for manual segmentation and labeling of the "ink crackles", crucial for the creation of ground truth datasets necessary for machine learning ink detection models.
POUR GOLD INTO THE CRACKLES!
- A graphical user interface that enables users to navigate through 3D Zarr data, H5FS 3D images and a folder with multiple TIFFs (experimental).
- Tools for labeling including brush, eraser, and flood fill (3D bucket).
- Toggle visibility of labels, barrier masks, and original images.
- Adjust the transparency of label and barrier overlays.
- Undo feature to revert the last action.
- Switch between editing labels and barrier masks.
- A 3D flood fill algorithm to segment contiguous structures within the data.
- Configurable settings such as intensity threshold, bucket layer selection, and maximum propagation steps for precise control.
- Edit barrier masks to prevent the flood fill algorithm from propagating into restricted areas.
- Loading and saving of Zarr formatted data directly from and to disk.
- Efficient support of H5FS 3D images.
- Tooltips provide guidance for each control.
- A help window offers detailed tool usage instructions.
- The interface is designed to be user-friendly and intuitive.
- A small Zarr dataset of cropped letters from Scroll 1 to practice labeling
Before using Vesuvius Kintsugi, ensure that the necessary dependencies are installed.
- You can either create a virtual environment with
$ pip install pipenv
and then, install the dependencies
$ pipenv install
- alternatively, you can install directly the dependencies with:
$ pip install -r requirements.txt
Run the main Python script to launch the Vesuvius Kintsugi interface:
$ pipenv shell # if you are using a virtual environment
$ python kintsugi.py
Use the provided buttons to load Zarr data or folders containing TIFF (experimental), navigate through slices, label regions, and save your work. The interface supports various annotation strategies suitable for different types of 3D structures.
You can also load H5FS files running the script with the following command line arguments:
$ python kintsugi.py --h5fs-file=/path/to/file.h5 --axes=zxy --roi=3070-3900,2770-3100,1500-2000
Region of interest (--roi
) is specified in original dataset coordinates (and the axes sequence matches dataset too), one must take care not to specify too big a volume, because it all goes into memory.
With --axes
, one can specify what kind of axes sequence the original dataset has. This will be mapped so that z
will be zoomable (depth), x
will be horizontal and y
will be vertical.
Directly customize the pencil size, flood fill threshold, and maximum propagation steps from the UI to tailor the tool's behavior to your specific data and labeling needs.
We encourage contributions to enhance the functionality of Vesuvius Kintsugi.
- kglspl: Special thanks to kglspl for his outstanding contributions!
Dr. Giorgio Angelotti
For any inquiries or further information, please contact me at giorgio.angelotti@isae-supaero.fr
This project is licensed under the MIT License - see the LICENSE file for details.