Skip to main content

Viewer for monochromatic video data

Project description

Monochrome: Viewer for Monochromatic Video Data

docs tests PyPI Supported Python versions

Monochrome is a lightweight and fast video viewer for scientific monochromatic videos with high-dynamic range (float, uint16, etc.).

It is designed for viewing high-speed monochromatic fluorescence video data from scientific cameras and meet our specific needs for cardiac optical mapping data (together with optimap):

  • Support for high-dynamic range (uint16, 32-bit float) data with sliders to adjust intensity range
  • Playback of multiple videos in sync
  • High-speed playback with precise frame-rate control
  • Viewing of optical traces (average intensity in a region of interest over time)
  • Rendering of layers on top of videos with transparency
  • Rendering of point positions over time (e.g. for tracking or optical flow visualization)
  • Exporting videos as a sequence of PNG images or MP4 videos with control over frame rate and frame skipping
  • Cross-platform (Linux, Windows, MacOS)

It is designed to be fast and lightweight, i.e. it uses memory-mapping to load video files to avoid copying the data into RAM.

Installation

There are two ways to install Monochrome: as a standalone application and/or with its Python interface through pip.

In the standalone application, supported video files can be loaded by drag & drop them into the window or by associating the file extension with Monochrome to open them with a double-click. The Python interface allows to load and play videos from Python scripts and Jupyter notebooks.

Standalone Application

Download the relevant executable (Windows, macOS, or Linux) from the latest release page. See the installation instructions for details.

Python Library

The Python library includes all necessary files and does not require the installation of the standalone Monochrome application. Open a terminal window and run the following command:

python -m pip install monochrome-viewer

See the Python installation guide for further details. To start the viewer in standalone mode, run:

python -m monochrome

See the tutorial for an introduction to the Python library, here is a brief overview:

import monochrome as mc
import numpy as np

# Create some video with shape (time, height, width) as a numpy array
video = np.random.rand(500, 256, 256)

# Display the video, see the tutorial for more details and options.
# Monochrome should automatically start and show the video in a loop.
mc.show_video(video, name="First Video", cmap='viridis', vmin=0, vmax=1)

# Play second video in sync with the first (note that the videos should have the same length)
video2 = (np.random.rand(500, 256, 256) * 65535).astype(dtype=np.uint16)
mc.show_video(video2, name="Second Video", comment="This is a uint16 video", bitrange="uint16")
# `bitrange` argument is optional, Monochrome will auto-detect the data type

# Layers can be added on top of video
overlay = np.random.rand(500, 256, 256)
overlay[:, 64:192, :] = np.nan # NaN values will be transparent pixels, see tutorial
mc.show_layer(overlay, parent="Second Video", cmap='PRGn', opacity='centered')

# List of functions:
# mc.show() is a shortcut for mc.show_video()/show_layer()/show_image()/show_file(),
#           it will try to auto-detect the input type and call the appropriate function.
# mc.show_video() to show videos
# mc.show_image() to show single images
# mc.show_layer() to show layers on top of videos/images
# mc.show_points() to visualize point positions over time over videos
# mc.show_flow() to visualize optical flow fields over time
# mc.show_file() to load videos from file in Monochrome
# mc.launch() to start Monochrome from Python

Native Video File Formats

Monochrome supports loading the following video file formats:

  • .npy, NumPy array with shape (time, width, height). The data type can be float (np.float32, np.float64), integer (uint8, uint16, etc.), or boolean.
  • .dat, raw binary file with shape (time, width, height) and data type float32
  • .dat, MultiRecorder file format (used in the cardiac optical mapping community)

Drag & drop the file into the window or associate the file extension with Monochrome to open it with a double-click.

Usage & Key Bindings

Adjust settings for each video in the main control window. To view optical traces (average intensity in a region of interest over time), click in a video. Click and drag to move the region of interest. Right-click to remove the region of interest.

Keyboard shortcuts:

Keybinding         Action               
Ctrl + q Quit Monochrome
Esc or q Close focused recording
Space Play/Pause
Up Increase playback speed (frame skip)
Down Decrease playback speed (frame skip)
0 or r Reset playback to beginning
Left Skip to next frame
Right Skip to previous frame
Shift + Left 10x previous frame
Shift + Right 10x next frame
Ctrl + Left Previous frame in focused recording only
Ctrl + Right Next frame in focused recording only
Ctrl + Left + Shift 10x previous frame in focused recording only
Ctrl + Right + Shift 10x next frame in focused recording only
p Save screenshot of focused recording
s Sync playback of all recordings

Additional Resources

License

Monochrome is licensed under the MIT License.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

monochrome_viewer-2024.11.20.tar.gz (8.6 MB view details)

Uploaded Source

Built Distributions

monochrome_viewer-2024.11.20-py3-none-win_amd64.whl (1.5 MB view details)

Uploaded Python 3 Windows x86-64

monochrome_viewer-2024.11.20-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.3 MB view details)

Uploaded Python 3 manylinux: glibc 2.17+ x86-64

monochrome_viewer-2024.11.20-py3-none-macosx_10_9_universal2.whl (3.8 MB view details)

Uploaded Python 3 macOS 10.9+ universal2 (ARM64, x86-64)

File details

Details for the file monochrome_viewer-2024.11.20.tar.gz.

File metadata

File hashes

Hashes for monochrome_viewer-2024.11.20.tar.gz
Algorithm Hash digest
SHA256 bb88e632fd8e8a8530ba6084a987055ab94b6d6c6871cff827048e86c8c8e2fc
MD5 71297b464cf1c2ed9a565c21cb47a7cf
BLAKE2b-256 a832bc182caafb9dc24479fef940dd4dd09f50b13523d7a4112b3786d5d7139d

See more details on using hashes here.

Provenance

The following attestation bundles were made for monochrome_viewer-2024.11.20.tar.gz:

Publisher: build.yml on sitic/monochrome

Attestations:

File details

Details for the file monochrome_viewer-2024.11.20-py3-none-win_amd64.whl.

File metadata

File hashes

Hashes for monochrome_viewer-2024.11.20-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 b1cae1b2838203f50b450fc1eec4df6397fe5e37a0062f0d63aa2666dd3d8478
MD5 25c669970c65fce20879e2b4c23709c2
BLAKE2b-256 1eae3fbf0a1126a6303cfe185a4e9f92fa55c2cd183002d12c7d88a5d8b563e6

See more details on using hashes here.

Provenance

The following attestation bundles were made for monochrome_viewer-2024.11.20-py3-none-win_amd64.whl:

Publisher: build.yml on sitic/monochrome

Attestations:

File details

Details for the file monochrome_viewer-2024.11.20-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for monochrome_viewer-2024.11.20-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 471d58ddb2974053daaf73705d50f13496a9ce726ba717ffc1edc8ae5d7b3bce
MD5 f4b9baffcac47654f9a6d6838d4d2b86
BLAKE2b-256 aee95ff118b5f59e2a32d5e8caffbfc8ea130fce0f2c18473f130e199979d386

See more details on using hashes here.

Provenance

The following attestation bundles were made for monochrome_viewer-2024.11.20-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: build.yml on sitic/monochrome

Attestations:

File details

Details for the file monochrome_viewer-2024.11.20-py3-none-macosx_10_9_universal2.whl.

File metadata

File hashes

Hashes for monochrome_viewer-2024.11.20-py3-none-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 7181e89c3d69f7745db0aed83ba9adad1aeb804ebbf03b00f1cd198c65573e7a
MD5 b4fbd24469dd9eec0525b5f005f2c6a3
BLAKE2b-256 2a618816bacafb62f070e8a08d28bac42794fbcf1422b1f08f82dd089d552ed2

See more details on using hashes here.

Provenance

The following attestation bundles were made for monochrome_viewer-2024.11.20-py3-none-macosx_10_9_universal2.whl:

Publisher: build.yml on sitic/monochrome

Attestations:

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page