Installing optimap¶

optimap is available for Windows, Mac OSX, and Linux. Pre-built binaries can be installed using pip, see below. You can find more detailed installation instructions in our Installation Guide. You can find the latest version of our source code at github.com/cardiacvision/optimap.

optimap requires Python 3.8 or later. To install Python we recommend installing the Anaconda distribution, which includes Python and many useful packages for scientific computing, or by installing Python directly.

Tip

optimap relies heavily on NumPy and Matplotlib. We recommend the Scientific Python Lectures and the Python Data Science Handbook for an introduction to Python and these libraries.

Installing pre-built binaries (macOS, Windows, Linux)¶

The easiest way to install optimap is using pip in the command line:

pip install "opticalmapping[all]"

Note

pip install opticalmapping will install the core functionality of optimap. However, the OpenCV and dependencies are not installed by default which are required for the optimap.motion and optimap.video modules. To install these dependencies use pip install "opticalmapping[all]" or install OpenCV manually.

If you do not have pip or Python installed you will first have to install these packages.

To use GPU-accelerated motion tracking algorithms a CUDA-enabled version of OpenCV is required, which is currently not available on PyPI. See OpenCV with CUDA support for more information.

To update optimap to the latest version run

pip install --upgrade "opticalmapping[all]"`

Installing from source¶

To install optimap from source, clone the GitHub repository and run pip install . in the root directory:

git clone https://github.com/cardiacvision/optimap.git
cd optimap
pip install .

See Contributing for more details.

Overview of optimap¶

optimap consists of the following modules:

optimap.video

Functions for loading, viewing, filtering, saving and exporting videos.

optimap.image

Functions for loading, saving, and displaying images, and for creating masks.

optimap.trace

Functions for extracting time-series from videos.

optimap.motion

Motion estimation and compensation functions for optical mapping data.

optimap.phase

Functions for computing, filtering, and analyzing phase maps from videos, and for detecting phase singularities.

optimap.utils

General utility functions.

Some of the most important functions are also imported into the top-level namespace:

optimap

optimap - An open-source Python toolbox for processing optical mapping and fluorescence imaging data.

for convenience.

See the tutorials listed below for an introduction to the main features of optimap and the API reference for a complete list of functions and classes.

Using optimap¶

We highly recommend using Visual Studio Code for working with optimap. Visual Studio Code is a free and open-source editor with excellent support for Python and Jupyter notebooks.

In particular, we recommend using regular .py files with automatic code cells by typing # %%. This allows you to run code cells directly from the editor, as shown below:

code cells

See the Visual Studio Code documentation for more information. Code cells are also supported in other editors such as PyCharm and Spyder.

Purists who would like to run their .py scripts in the command line You could run the Python script in a terminal with python3 basics.py from the folder where the file is located. Alternatively, one can start Python in the command line (by typing in python3.9 and pressing ‘Enter’) and type in the above command and press ‘Enter’.

plot viewer

Monochrome¶

Monochrome is a separate project to view high-dynamic range monochromatic videos, such as those produced by optical mapping. It can be used as a standalone application or as a Python library. Monochrome is not required to use optimap, but it can be useful for viewing optical mapping data in addition to the functions provided by optimap.

Interactive Plots¶

Working with remote Jupyter notebooks

The interactive plotting functions in optimap may not work as expected when using Jupyter Notebook on a remote server (i.e., not on your local computer). This is because the interactive plots require a local display to work properly.

optimap uses Matplotlib for plotting. The following functions require an interactive Matplotlib backend:

optimap.video.show_video(video[, ...])

Simple video player based on matplotlib's animate function.

optimap.video.show_videos(videos[, ...])

Video player for n side-by-side videos based on matplotlib's animate function.

optimap.video.show_video_pair(video1, video2)

Video player for two videos side-by-side based on matplotlib's animate function.

optimap.video.show_video_overlay(base, overlay)

Play a video with an overlay.

optimap.trace.select_positions(image[, ...])

Interactive selection of positions on an image.

optimap.trace.select_traces(video[, size, ...])

Interactive selection/plotting of traces from a video.

optimap.trace.compare_traces(videos[, ...])

Compare traces of multiple videos.

optimap.motion.play_displacements(video, vectors)

Simple video player with displacement vectors displayed as arrows.

optimap.motion.play_displacements_points(...)

Simple video player with displacement vectors displayed as points.

We strongly recommend using the Qt matplotlib backend for interactive plotting. optimap will attempt to automatically switch to the Qt backend for these functions and switch back to the inline backend afterwards (if applicable).

Note

optimap.utils.disable_interactive_backend_switching() can be used to disable the interactive backend switching if it causes problems. Please report any issues you encounter.

Alternatively, you can manually switch to the Qt backend by running the following code before calling any of the functions listed above:

import matplotlib.pyplot as plt
plt.switch_backend('QtAgg')  # or 'QtCairo'

How to cite¶

A publication about optimap is currently in preparation. In the meantime, please cite the following DOI and paper if you use optimap in your research: Lebert and Christoph[1], Lebert et al.[2].