Python toolbox to transform zebrafish tracking data to tail animations

zf_animator is a Python package used to create visualisation of how swimming data looks from high-speed tracking data. The typical data used should be the tail angle along segments of the tail. The package will convert these tail angles to x- y- coordinates, and interpolate many more points along the range of tracked tail segments. These sets of coordinates will then transform slices of the zebrafish image, producing a stack of .png files that can be rendered into a mp4 file.

Animations of the larval zebrafish postures are warped using a piece wise affine transformation using the interpolated x-y coordinates.

This package can be installed via pip

pip install fish-simulator

Alternatively, you can download and locally install the package.

cd path/to/save/package
git clone clone-latest-tag git@github.com:ThomasMullen/fish_simulator.git
cd ./fish_simulator
python -m build
# go to working project
cd path/to/work/project
# acivate venv
source my_virtual_env/bin/activate
pip install -e path/to/save/package

To convert the .png files to an .mp4 animation requires ffmpeg to be installed on the running computer. This can be install in Ubuntu in the terminal:

sudo apt install ffmpeg

Or with OS X can be installed:

brew install ffmpeg

Check it is installed by running which ffmpeg in the terminal. More details can be found here.

This displays a virtual structure of the fish posture. There are several plots you can perform, with the option of converting to a video. These functions are plot_bout_elapse, plot_skeletal_postures, and plot_skeletal_postures_with_trace. There are passed through the run function. Here is an example.

import numpy as np
from fish_simulator import run

data_arr = np.load("fish_simulator/test/fixtures/swim01.npy")
run(
    data_arr,
    plot_func=plot_skeletal_postures_with_trace,
    dir="path/to/dir/plts",
    vid_fp="path/to/video/anim.mp4",
    line_wid=1
    )

There are two plotting functions using the real larvae: plot_tail_image and plot_tail_image_with_trace.

import numpy as np
from fish_simulator import run, plot_tail_image_with_trace, plot_tail_image

run(
    data_arr,
    # plot_func=plot_tail_image,
    plot_func=plot_tail_image_with_trace,
    dir="path/to/dir/plts",
    vid_fp="path/to/video/anim.mp4",
)

Generate a video from collections of .png files

from utils import make_video

make_video(
    png_dir="path/to/png/files/",
    vid_fname="path/to/video/anim.mp4", 
    framerate=70,
    keep_pngs=True
)