Fish Tail Simulator

A Python toolbox for transforming fish tail tracking data into tail animations.

Description

fish_simulator is a Python package used to visualize swimming data from high-speed tracking. The typical data used is the tail angle along segments of the tail. The package converts these tail angles to x-y coordinates and interpolates additional points along the range of tracked tail segments. These sets of coordinates then transform slices of the fish image, producing a stack of .png files that can be rendered into an mp4 file.

Animations of fish postures are created using a piecewise affine transformation with the interpolated x-y coordinates.

Package installation

This package can be installed via PyPi:

pip install fish-simulator

Alternatively, you can download and locally install the package:

cd path/to/save/package
git clone 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

Requires ffmpeg

Installation instructions

To convert the .png files to an .mp4 animation requires ffmpeg to be installed on the running computer. On Ubuntu, install ffmpeg via terminal:

sudo apt install ffmpeg

On macOS, install ffmpeg with Homebrew:

brew install ffmpeg

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

NOTE: Package can run without ffmpeg, but you will not be able to make videos from .png files. To avoid dependency issues, set the vid_fname argument to None.

Fish animation template

Fish image template

Fish template is an image of the larval zebrafish.

Examples

Simple illustrative plot of posture

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.simulator import run, plot_skeletal_postures_with_trace

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

run_ani_swim01.mp4

Larval zebrafish simulation plot

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.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,
    png_dir="path/to/dir/plts",
    vid_fp="path/to/video/anim.mp4",
    fps=700,
)

Generate a video from collections of .png files

from fish_simulator.utils import make_video

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

run_img_swim01.mp4

Citation

@software{Soares_Mullen_Fish_Behaviour_Simulator_2024,
  author = {Soares Mullen, Thomas},
  month = jun,
  title = {{Fish Tail Simulator}},
  version = {0.1.11},
  year = {2024}
}

Acknowledgements

This project has received funding from the European Union’s Horizon 2020 research and innovation programme under the Marie Skłodowska-Curie grant agreement #813457.