deep-mi / whippersnappy

Python OpenGL Tool for Screenshots of Surface Overlays

WhipperSnapPy

WhipperSnapPY is a small Python OpenGL program to render FreeSurfer and FastSurfer surface models and color overlays and generate screen shots.

Contents:

• Capture 4x4 surface plots (front & back, left and right)
• OpenGL window for interactive visualization

Installation:

The WhipperSnapPy package can be installed from pypi via

python3 -m pip install whippersnappy

Note, that currently no off-screen rendering is natively supported. Even in snap mode an invisible window will be created to render the openGL output and capture the contents to an image. In order to run this on a headless server, inside Docker, or via ssh we recommend to install xvfb and run

sudo apt update && apt install -y python3 python3-pip xvfb libxcb-xinerama0
pip3 install pyopengl glfw pillow numpy pyrr PyQt6
pip3 install whippersnappy
xvfb-run whippersnap ...

Usage:

Local:

After installing the Python package, the whippersnap program can be run using the installed command line tool such as in the following example:

whippersnap -lh $OVERLAY_DIR/$LH_OVERLAY_FILE \
            -rh $OVERLAY_DIR/$RH_OVERLAY_FILE \
            -sd $SURF_SUBJECT_DIR \
            --fmax 4 --fthresh 2 --invert \
            --caption caption.txt \
            -o $OUTPUT_DIR/whippersnappy_image.png \

For more options see whippersnap --help. Note, that adding the --interactive flag will start an interactive GUI that includes a visualization of one hemisphere side and a simple application through which color threshold values can be configured.

Docker:

The whippersnap program can be run within a docker container to capture a snapshot by building the provided Docker image and running a container as follows:

docker build --rm=true -t whippersnappy -f ./Dockerfile .

docker run --rm --init --name my_whippersnappy -v $SURF_SUBJECT_DIR:/surf_subject_dir \
                                               -v $OVERLAY_DIR:/overlay_dir \
                                               -v $OUTPUT_DIR:/output_dir \
                                               --user $(id -u):$(id -g) whippersnappy:latest \
                                               --lh_overlay /overlay_dir/$LH_OVERLAY_FILE \
                                               --rh_overlay /overlay_dir/$RH_OVERLAY_FILE \
                                               --sdir /surf_subject_dir \
                                               --output_path /output_dir/whippersnappy_image.png

In this example: $SURF_SUBJECT_DIR contains the surface files, $OVERLAY_DIR contains the overlays to be loaded on to the surfaces, $OUTPUT_DIR is the local output directory in which the snapshot will be saved, and ${LH/RH}_OVERLAY_FILE point to the specific overlay files to load.

Note: The --init flag to Docker is needed for the xvfb-run tool to be used correctly for off screen rendering.

API Documentation

The API Documentation can be found at https://deep-mi.org/WhipperSnapPy .

Links:

We also invite you to check out our lab webpage at https://deep-mi.org

whippersnappy's Issues

Improving the interactive mode

Description

The GUI that is used in the interactive mode can be improved in various ways. The purpose of this issue is to suggest and discuss future functionalities and improvements.

Here are a few suggestions:

• Adding the ability to zoom using mouse scroll
• Adding a color bar
• Adding a user input window that enables configuring parameters such as thresholds, the overlay/surface to load, lighting intensities, colors, etc.
• Adding the ability to capture a snapshot and save it

Including executable in Python package

Description

At the moment, the main executable (essentially the command line interface application), run_whippersnapper, is excluded from the python package.

This needs to be integrated into and made available with the installable package i.e. exposing a command line tool after the package is installed.

Function docstrings

Description

Proper docstrings for all functions should be added and adapted to the numpy style (see example here).

Flag to switch off phong shading

A flag to switch off phong shading should be added to allow used to get images that are the same as the original whippersnapper (tksurfer based) tool .

PyQt6 breaks sphinx

When switching to PyQt6 instead of 5, we see a weird error in sphinx:
https://github.com/Deep-MI/WhipperSnapPy/actions/runs/8953433413/job/24592104510

It needs to be checked if something is not setup correctly, or what is causing this. Also at the same time PyQT6 needs to be tested to verify that the GUI runs as intended. This may also require to bump pyopengl version to match.

rotation via keys not working in interacrive mode

Description

on Centos 7 in interactive mode, left right keys do not work for rotation.

Steps to Reproduce

start with -i flag and try to rotate object via keys, no reaction.

Closing behaviour of interactive mode

Description

When closing one of the two windows the other one should also close and program should exit, or when esc is pressed.

Steps to Reproduce

Start interactive mode, close one of the windows, the other one will stay active and program will not terminate.