Virtual Unwrapping Tool for the Vesuvius Challenge, inspired by volume-cartographer (https://github.com/educelab/volume-cartographer).
Note: Python3 is required.
- Clone the repo
git clone https://github.com/MosheLevy20/VolumeAnnotate.git
cd VolumeAnnotate- Install dependencies
pip install -r requirements.txtTo run simply do
python VolumeAnnotate.pyIf everything worked as it's supposed to, you should see a popup that looks like this.
There are two main ways to run the app: using local files, and streaming. If you select local, you can use either a directory with just tifs in it, or a volpkg. If you select a volpkg you will be prompted to select which volume inside it to use.
If you select streaming you will be prompted to choose scroll 1 or 2 (currently only part of scroll 1 is supported, but that should change soon).
Additionally, there is a "mode" menu where you can select which segmentation algorithm to use (currently only "classic" is supported, but the code is set up in such a way to make it easy to add new modes).
Once you launch you should see a window that looks something like this.
On the right side of the screen is the control panel (note that it is resizable by dragging the vertical partition to the left and right). At the top are basic buttons for scrubbing between frames, as well as zooming. The buttons 1-6 also control scrubbing (1 = +1,2 = -1, 3 = +10...), and "I", "O" control zooming in and out. Panning is controlled by the mousewheel (wheel for vertical, shift+wheel for horizontal) or the WASD keys.
To begin segmenting select the "Outline Fragment" mouse mode. You can then place points by clicking on the image; it should look someting like this.
If you don't like the placement of your points, you can move or delete them by selecting the corresponding mouse mode.
Once you are happy with the outline, you can click "Edge Detection" which will attempt to follow the segement down the z-axis for a number of slices (set by the slider).
There are a few formats you can export to. First is volpkg. If you selected a volpkg on startup it will save a new path in the paths directory. If you selected a regular directory of tifs, you will be prompted to name your volpkg and the app will generate it for you. Important note: by creating a new volpkg all the tifs will be copied, so make sure you have space for it. Currently export to volpkg doesn't work while streaming. The next most important export format is pkl. As you segment an autosave pkl file will be generated (yyyymmddhhmmss.pkl), so if the app crashes you can load that pkl back in and continue where you left off. You can manually save pkl files as well. You can also export to OBJ and view your segment in 3d with e.g. MeshLab.
Finally, you can use the "Save 2D Projection" button to virtually unwrap your annotations. There are two options here: "Annotations" just unwraps your annotations, while "Pure Projection" simply takes the pixel values of the points (including the interpolated ones) that you outlined, ignoring the color of your annotations. Below is an example of a virtual unwrapping of the campfire scroll using both options.
There are some miscelaneous buttons and sliders you can try out.