pyvisor package

Subpackages

Submodules

pyvisor.MediaHandler module

Created on Wed May 25 08:40:38 2016

@author: bgeurten

class pyvisor.MediaHandler.MediaHandler(filename, mode, bufferSize=2000)[source]

Bases: object

Video and image sequence playback handler.

Wraps pims to provide frame-accurate access to movies, Norpix SEQ files, and image sequences. Manages playback state (play/pause, forward/reverse, FPS) and an in-memory frame buffer.

Parameters:

filename (str) – Path to the media file or image glob pattern.
mode (str) – One of "movie", "norpix", or "image".
bufferSize (int) – Maximum number of frames kept in the read-ahead buffer.

decrease_fps()[source]

getFrame(frameNo)[source]

getFrameImage(frameNo)[source]

getFrameMov(frameNo)[source]

getFrameNorpix(frameNo)[source]

get_frame() → ndarray[source]

get_frameNo()[source]

get_time()[source]

increase_fps()[source]

set_current_frame_delta(delta: int)[source]

set_run_forward()[source]

set_run_reverse()[source]

set_stop()[source]

toggle_play()[source]

pyvisor.animal_ethogram_2 module

class pyvisor.animal_ethogram_2.AnimalEthogram2(animal: Animal, n_frames: int)[source]

Bases: object

Frame-level ethogram for a single animal.

Stores a boolean DataFrame where each column is a behaviour and each row is a video frame. Provides methods to assign, delete, and query behaviour states at individual frames.

assign_behaviours(frame: int, behav_labels: List[str])[source]

delete_behaviours(frame_number: int)[source]

get_active_labels_at_frame(frame: int) → List[str][source]: Return list of behaviour labels that are True at frame.

get_formatted_behaviour_labels() → List[str][source]

get_icons(behaviours: List[str])[source]

to_numpy() → ndarray[source]

pyvisor.dataIO module

Created on Wed Jun 1 13:42:07 2016

@author: bgeurten

class pyvisor.dataIO.dataIO(parent)[source]

Bases: object

Data input/output handler for ethogram data.

Supports saving annotations as plain text, Excel, MATLAB, and pickle formats. Also handles autosave with periodic background snapshots and overlay frame/video export.

assignMatrix2animals(data, animals)[source]

autosave()[source]

Start, update, or stop the autosave worker.

Autosave parameters are provided by the parent scorer via the autosave_settings attribute. The expected schema is:

{
    "enabled": bool,
    "interval_seconds": int,
    "directory": str,
}

The worker writes autosave_latest.pkl and autosave_latest.txt into the configured directory at the given interval. When autosave is disabled any existing worker is shut down gracefully.

loadMAT(fpos, animal1, animal2)[source]

loadPickle(fpos, animals)[source]

loadTXT(fpos, animal1, animal2)[source]

loadXLSX(fpos, animal1, animal2)[source]

saveAsMat(fpos, data, behavLabels)[source]

saveAsPy(fpos, data)[source]

saveAsTXT(fpos, data, behavLabels)[source]

saveAsXLSX(fpos, data, behavLabels)[source]

saveOverlayImage(fPos, targetFrame=37)[source]: Save a single frame with behaviour icon overlays.

saveOverlayMovie(fPos, prefix='frame', extension='mp4')[source]

Export the scored video as an actual video file with icon overlays.

If extension is ‘mp4’ or ‘avi’, a proper video file is written using PyAV. For image formats (‘png’, ‘jpeg’, ‘bmp’, ‘tga’) a numbered image sequence is written instead.

stop_autosave()[source]

pyvisor.ethogram module

class pyvisor.ethogram.Ethogram(animals: Dict[int, Animal], n_frames: int, lock: RLock = None)[source]

Bases: object

Container linking all per-animal ethograms with shared state.

Manages the live toggle states (which behaviours the user is currently pressing) and delegates frame-level recording to AnimalEthogram2 instances.

apply_states_at_frame(frame_number: int)[source]

clear_states()[source]

property lock: RLock

toggle_state(label: str)[source]

pyvisor.icon module

Created on Thu Jun 16 13:19:47 2016

@author: bgeurten

class pyvisor.icon.Icon(size=(96, 96), color=(144, 21, 222), alpha=255)[source]

Bases: object

Recolourable icon for behaviour display in the scorer window.

Loads a decal image, tints it to the behaviour’s assigned colour, and converts it to a pygame surface for blitting.

decall2icon()[source]

drawCircle()[source]

getDecallPos()[source]

getMaxDecallSize()[source]

icon2pygame() → <module 'pygame.image' from '/opt/hostedtoolcache/Python/3.11.15/x64/lib/python3.11/site-packages/pygame/image.cpython-311-x86_64-linux-gnu.so'>[source]

invertDecall()[source]

readImage(filename)[source]

pyvisor.icon.write_tmp_icon(path_to_icon, color)[source]

pyvisor.manual_ethology_scorer_2 module

class pyvisor.manual_ethology_scorer_2.ManualEthologyScorer2(animals: Dict[int, Animal], movie_bindings: MovieBindings, selected_device: str, autosave_settings: Dict[str, bool | int | str] | None = None)[source]

Bases: object

Real-time video annotation engine.

Opens a pygame window showing the video with behaviour icon overlays. Processes gamepad/keyboard input to toggle behaviour states and records them frame-by-frame into an Ethogram.

Supports:

Sidecar-based session persistence (auto-save/resume)
Autosave to a configurable directory
F1-toggleable key binding overlay
Visual distinction between live and recorded annotations

property autosave_settings

get_data()[source]

get_labels() → List[str][source]

go()[source]

static image2surf(fPos)[source]

load_movie(filename: str, media_type: str)[source]

refresh_media()[source]

save_data(fpos, mode='text')[source]

save_sidecar()[source]: Persist the current ethogram to a sidecar file next to the video.

pyvisor.paths module

Utility helpers for locating user-specific data directories.

This module centralizes the logic for determining where pyVISOR should store user data such as cached icons, serialized GUI state, and autosave artifacts. It relies on appdirs so that the chosen locations respect platform conventions (~/Library on macOS, %APPDATA% on Windows, etc.).

pyvisor.paths.ensure_autosave_dir() → Path[source]: Ensure and return the directory for autosave data.

pyvisor.paths.ensure_tmp_icon_dir() → Path[source]: Ensure and return the directory for cached, recoloured icons.

pyvisor.paths.ensure_user_data_dir() → Path[source]: Ensure the user data directory exists and return it.

pyvisor.paths.settings_path(filename: str) → Path[source]: Return the path for a settings file stored in the user data dir.

pyvisor.user_input_control module

class pyvisor.user_input_control.UserInputControl2(animals: Dict[int, Animal], movie_bindings: MovieBindings, selected_device: str, movie: MediaHandler, ethogram: Ethogram)[source]

Bases: object

Maps gamepad/keyboard input codes to scorer actions.

Reads the button-to-behaviour assignments from the GUI model and builds a dispatch dictionary. Called from the scorer’s main loop on every pygame input event.

handle_input(input_code: str)[source]

Module contents

pyVISOR — Desktop toolkit for manual ethology scoring.

This package provides a PyQt5-based GUI for annotating animal behaviours in video recordings using gamepads or keyboards, with built-in analysis and export capabilities.