Metadata-Version: 2.4
Name: whisk-janelia
Version: 1.2.4
Summary: Fully automated tracking of single rows of whiskers in high-speed video.
Home-page: https://github.com/nclack/whisk/
Author: Nathan Clack
Maintainer: clackn, cxrodgers, mitchclough, vncntprvst
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/nclack/whisk/
Project-URL: Repository, https://github.com/vncntprvst/whisk
Project-URL: Issues, https://github.com/nclack/whisk/issues
Project-URL: Documentation, https://wikis.janelia.org/display/WT/Whisker+Tracking
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Provides-Extra: ffmpeg
Requires-Dist: requests<3,>=2.24; extra == "ffmpeg"
Dynamic: home-page
Dynamic: license-file

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](http://openwiki.janelia.org/wiki/display/MyersLab/Whisker+Tracking) for this program is now accessible [here](https://wikis.janelia.org/display/WT/Whisker+Tracking).
A copy of the instructions and the tutorial are available [here](https://github.com/wanglab-neuro/whisk-dockerfile/tree/main/context/wiki).

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:

```bash
pip install whisk-janelia
```

For the latest features with FFmpeg support:
```bash
pip install whisk-janelia[ffmpeg]
```

It is recommended to use a virtual environment:

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

**Using uv (faster):**
```bash
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:

```bash
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:

```bash
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

```bash
# 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:

```bash
# 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:

```bash
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:

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

3. Build the project:

```bash
mkdir build
cd build
cmake ..
make
```

For WSL systems, see: [Build and debug C++ with WSL 2](https://devblogs.microsoft.com/cppblog/build-and-debug-c-with-wsl-2-distributions-and-visual-studio-2022/)

### 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](https://www.msys2.org/).
2. In the MSYS2 terminal, install the toolchain and FFmpeg:

```bash
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):

```bash
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](https://discord.gg/Y7QJerr)

[Issue Tracker](https://github.com/nclack/whisk/issues)

