Janelia Whisker Tracking

Fully automated tracking of single rows of whiskers in high-speed video.

The original source code repository is https://github.com/nclack/whisk/. The original website for this program is now accessible here. A copy of the instructions and the tutorial are available here.

This package has been modernized with updated build systems, Python packaging standards (PEP 517/518), and improved compatibility.

Installation

From PyPI (Recommended)

This package can be installed from PyPI with:

pip install whisk-janelia

For the latest features with FFmpeg support:

pip install whisk-janelia[ffmpeg]

It is recommended to use a virtual environment:

Using venv:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install whisk-janelia

Using uv (faster):

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install whisk-janelia

From Source

To install from source, clone the repository and run the following commands:

git clone https://github.com/vncntprvst/whisk.git
cd whisk

# Create and activate virtual environment
uv venv  # or: python -m venv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
uv pip install -e .  # or: pip install -e .

Post-Installation

After installation, the whisk executables will be available as command-line tools:

• trace - Main whisker tracing executable
• classify - Whisker classification
• measure - Whisker measurements
• whisker_convert - Convert between whisker file formats
• And more...

The Python package automatically handles binary permissions and PATH setup. You can verify the installation by running:

trace --help

The executables are also accessible through the whisk Python module for programmatic use.

Building from Source

For development or custom builds, you can build from source using modern Python packaging tools.

Prerequisites

• CMake 3.15+
• C/C++ compiler (gcc 12+ works, including gcc 14/16; MSVC also supported)
• FFmpeg development libraries (the binaries are currently built against FFmpeg 8.x)
• Python 3.8+

The Qt5 GUI and the MATLAB MEX bindings are optional and off by default: the GUI builds only with -DBUILD_GUI=ON (requires Qt5), and the MATLAB targets require a MATLAB installation. The instructions below build the core command-line tools and the whisk / whiskio / traj shared libraries.

Quick Build

# Clone and navigate to the repository
git clone https://github.com/vncntprvst/whisk.git
cd whisk

# Build using modern Python tools
uv build  # or: python -m build

# Install the built wheel
pip install dist/*.whl

Development Build

For development, you can build and install in editable mode:

# Create virtual environment
uv venv  # or: python -m venv venv
source .venv/bin/activate

# Install in development mode
uv pip install -e .  # or: pip install -e .

Manual CMake Build

The package uses a CMake-based build system for the underlying C/C++ libraries:

For Unix-like systems (Linux/macOS):

1. Install build dependencies:

sudo apt update
sudo apt install cmake pkg-config bison gawk
sudo apt install g++ gdb make ninja-build rsync zip

2. Install FFmpeg development libraries:

sudo apt install libavdevice-dev libavfilter-dev libavformat-dev libavcodec-dev libswresample-dev libswscale-dev libavutil-dev

3. Build the project:

mkdir build
cd build
cmake ..
make

For WSL systems, see: Build and debug C++ with WSL 2

FFmpeg Troubleshooting

If CMake cannot find FFmpeg libraries, you may need to:

1. Set the PKG_CONFIG_PATH: export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH
2. Update library path: export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
3. Run sudo ldconfig to update the dynamic linker cache

Windows Build Instructions:

Windows builds use MSYS2/MinGW (a native MinGW build is produced — no WSL or container required).

1. Install MSYS2.
2. In the MSYS2 terminal, install the toolchain and FFmpeg:

pacman -S --needed base-devel mingw-w64-x86_64-toolchain
pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake mingw-w64-x86_64-ninja mingw-w64-x86_64-ffmpeg

3. Configure and build the core targets from the MinGW64 environment (skip the MATLAB MEX targets, which require MATLAB; the Qt GUI stays off):

cmake -G Ninja -B build -DCMAKE_BUILD_TYPE=Release
ninja -C build whisk traj whiskio trace measure classify classify_radial reclassify report whisker_convert measurements_convert

4. Stage the binaries for the Python package: copy the built *.dll / *.exe from build/ into whisk/bin/, along with the FFmpeg and MinGW runtime DLLs they depend on (resolve them with ldd build/whisk.dll etc. and copy the /mingw64/bin/*.dll dependencies). These bundled DLLs must match the FFmpeg major version the binaries were built against (see whisk/whisk_utils.py, FFMPEG_DLL_RELEASE).

Note: under MinGW the public API is exported via __declspec(dllexport) on _WIN32 (see include/compat.h and src/generated/parameters/param.h), so whisk.dll exports the symbols WhiskiWrap binds through ctypes (e.g. Load_Params_File). GCC 14+ legacy-C warnings are demoted in CMakeLists.txt.

File formats

Whiskers

Whiskers can be stored in either a text or binary format. There is a command line utility, whisker_convert, provided to convert between different supported formats. batch.py can be used to speed up the process of converting many files.

The most detailed description of each format can be found in the corresponding whisker_io_*.c files implimenting the readers/writers for each format.

In general, each whisker segment in a file is comprised of a unique id and a number of data points describing the shape as output from the tracing program.

Measurements

The measurements file stores the features of traced curves used for classification, such as follicle position, angle and whisker length. Additionally, after classification, this file records the determined identity of each traced curve.

Graphical interface

See ui/README for instructions on how to use the graphical user interface.

  ui2.py --help

Community

Chat

Issue Tracker