datanavigator 1.0.0__py3-none-any.whl

datanavigator/__init__.py

@@ -0,0 +1,133 @@
+r"""
+Interactive data visualization for signals, videos, and complex data objects.
+
+Browsers
+
+- :py:class:`GenericBrowser`: Generic class to browse data. Meant to be extended.
+- :py:class:`SignalBrowser`: Browse an array of pysampled.Data elements, or 2D arrays.
+- :py:class:`PlotBrowser`: Scroll through an array of complex data where a plotting function is defined for each element.
+- :py:class:`VideoBrowser`: Scroll through the frames of a video.
+- :py:class:`VideoPlotBrowser`: Browse through video and 1D signals synced to the video side by side.
+- :py:class:`ComponentBrowser`: Browse signals (e.g., from periodic motion) as scatterplots of components (e.g., from UMAP, PCA).
+
+
+Point tracking
+
+- :py:class:`Video`: Extended VideoReader class with additional functionalities (helper for VideoPointAnnotator).
+- :py:class:`VideoAnnotation`: Manage one point annotation layer in a video.
+- :py:class:`VideoAnnotations`: Manager for multiple video annotation layers.
+- :py:class:`VideoPointAnnotator`: Annotate points in a video.
+
+Optical flow
+
+- :py:func:`lucas_kanade`: Track points in a video using the Lucas-Kanade algorithm.
+- :py:func:`lucas_kanade_rstc`: Track points in a video using Lucas-Kanade with reverse sigmoid tracking correction.
+- :py:func:`test_lucas_kanade_rstc`: Test function for Lucas-Kanade with reverse sigmoid tracking correction.
+
+Assets
+
+- :py:class:`Button`: Custom button widget with a 'name' state.
+- :py:class:`StateButton`: Button widget that stores a number/coordinate state.
+- :py:class:`ToggleButton`: Button widget with a toggle state.
+- :py:class:`Selector`: Select points in a plot using the lasso selection widget.
+- :py:class:`StateVariable`: Manage state variables with multiple states.
+- :py:class:`EventData`: Manage the data from one event type in one trial.
+- :py:class:`Event`: Manage selection of a sequence of events.
+
+Assetcontainers
+
+- :py:class:`AssetContainer`: Container for managing assets such as buttons, memory slots, etc.
+- :py:class:`Buttons`: Manager for buttons in a matplotlib figure or GUI.
+- :py:class:`Selectors`: Manager for selector objects for picking points on line2D objects.
+- :py:class:`MemorySlots`: Manager for memory slots to store and navigate positions.
+- :py:class:`StateVariables`: Manager for state variables.
+- :py:class:`Events`: Manager for event objects.
+"""
+import os
+import sys
+import shutil
+
+from .__version__ import __version__
+
+from ._config import (
+    get_cache_folder,
+    get_clip_folder,
+    set_cache_folder,
+    set_clip_folder,
+)
+from .assets import (
+    AssetContainer,
+    Button,
+    Buttons,
+    MemorySlots,
+    Selector,
+    Selectors,
+    StateButton,
+    StateVariable,
+    StateVariables,
+    ToggleButton,
+)
+from .events import portion, Event, EventData, Events
+
+from .core import GenericBrowser
+from .plots import PlotBrowser
+from .signals import SignalBrowser
+from .videos import VideoBrowser, VideoPlotBrowser
+from .components import ComponentBrowser
+
+from .opticalflow import lucas_kanade, lucas_kanade_rstc
+from .pointtracking import VideoAnnotation, VideoAnnotations, VideoPointAnnotator
+
+from .utils import (
+    TextView,
+    Video,
+    get_palette,
+    is_path_exists_or_creatable,
+    is_video,
+    ticks_from_times,
+)
+
+from .examples import (
+    get_example_video,
+    EventPickerDemo,
+    ButtonDemo,
+    SelectorDemo,
+)
+
+
+def _check_ffmpeg():
+    def check_command(command):
+        """Check if a command is available in the system's PATH."""
+        return shutil.which(command) is not None
+
+    def print_install_instructions():
+        """Print installation instructions for ffmpeg and ffprobe."""
+        if sys.platform.startswith("win"):
+            print("\nFFmpeg is not installed or not in PATH.")
+            print("Download it from: https://ffmpeg.org/download.html")
+            print("After installation, add FFmpeg's 'bin' folder to the system PATH.")
+        else:
+            print("\nFFmpeg is not installed or not in PATH.")
+            print("On Debian/Ubuntu, install it with: sudo apt install ffmpeg")
+            print("On macOS, install it with: brew install ffmpeg")
+            print("On Fedora, install it with: sudo dnf install ffmpeg")
+            print("On Arch Linux, install it with: sudo pacman -S ffmpeg")
+
+    # Check if ffmpeg and ffprobe are available
+    ffmpeg_found = check_command("ffmpeg")
+
+    if not ffmpeg_found:
+        print("Cound not find ffmpeg.")
+        print_install_instructions()
+
+
+def _check_clip_folder():
+    if not os.path.exists(get_clip_folder()):
+        folder = os.getcwd()
+        print(f"Using the current working directory-{folder}-for storing video clips.")
+        set_clip_folder(folder)
+        print("To change, use datanavigator.set_clip_folder(<folder_name>)")
+
+
+_check_ffmpeg()
+_check_clip_folder()

datanavigator/__version__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

datanavigator/_config.py

@@ -0,0 +1,53 @@
+"""
+This module provides functions to set and get the paths for the clip and cache folders.
+
+The clip folder is used to store video clips, for example, when using VideoBrowser. 
+The cache folder is used by the :py:mod:`datanavigator.examples` to write json file containing marked events.
+"""
+
+import os
+import logging
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+
+# Use environment variables for default paths
+CLIP_FOLDER: str = os.getenv("CLIP_FOLDER", "C:\\data\\_clipcollection")
+CACHE_FOLDER: str = os.getenv("CACHE_FOLDER", "C:\\data\\_cache")
+
+
+def set_clip_folder(folder: str) -> None:
+    """Set the path for storing video clips."""
+    if not os.path.exists(folder):
+        raise ValueError(f"The provided folder path does not exist: {folder}")
+
+    global CLIP_FOLDER
+    CLIP_FOLDER = folder
+    logging.info(f"Clip folder set to: {CLIP_FOLDER}")
+
+    global CACHE_FOLDER
+    if not os.path.exists(CACHE_FOLDER):
+        logging.info(
+            "Setting the cache folder to be the same as the clip folder. To change, use set_cache_folder(<folder_name>)."
+        )
+        CACHE_FOLDER = folder
+
+
+def get_clip_folder() -> str:
+    """Get the current path of the clip folder."""
+    return CLIP_FOLDER
+
+
+def set_cache_folder(folder: str) -> None:
+    """Set the path for the cache folder."""
+    if not os.path.exists(folder):
+        raise ValueError(f"The provided folder path does not exist: {folder}")
+
+    global CACHE_FOLDER
+    CACHE_FOLDER = folder
+    logging.info(f"Cache folder set to: {CACHE_FOLDER}")
+
+
+def get_cache_folder() -> str:
+    """Get the current path of the cache folder."""
+    return CACHE_FOLDER

datanavigator/assets.py

@@ -0,0 +1,362 @@
+"""
+This module provides classes and functions for managing various assets such as buttons, selectors, and state variables in a graphical user interface.
+
+Classes:
+    Button - Add a 'name' state to a matplotlib widget button.
+    StateButton - Store a number/coordinate in a button.
+    ToggleButton - Add a toggle button to a matplotlib figure.
+    Selector - Select points in a plot using the lasso selection widget.
+    StateVariable - Manage state variables with multiple states.
+
+    AssetContainer - Container for managing assets such as buttons, memory slots, etc.
+    
+    Buttons - Manager for buttons in a matplotlib figure or GUI.
+    Selectors - Manager for selector objects for picking points on line2D objects.
+    MemorySlots - Manager for memory slots to store and navigate positions.
+    StateVariables - Manager for state variables.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from matplotlib import lines as mlines
+from matplotlib import pyplot as plt
+from matplotlib.path import Path as mPath
+from matplotlib.widgets import Button as ButtonWidget
+from matplotlib.widgets import LassoSelector as LassoSelectorWidget
+from typing import Any, Callable, List, Optional, Union
+
+from .utils import TextView
+
+
+class Button(ButtonWidget):
+    """Add a 'name' state to a matplotlib widget button."""
+
+    def __init__(self, ax, name: str, **kwargs) -> None:
+        super().__init__(ax, name, **kwargs)
+        self.name = name
+
+
+class StateButton(Button):
+    """Store a number/coordinate in a button."""
+
+    def __init__(self, ax, name: str, start_state: Any, **kwargs) -> None:
+        super().__init__(ax, name, **kwargs)
+        self.state = start_state  # stores something in the state
+
+
+class ToggleButton(StateButton):
+    """
+    Add a toggle button to a matplotlib figure.
+
+    For example usage, see PlotBrowser.
+    """
+
+    def __init__(self, ax, name: str, start_state: bool = True, **kwargs) -> None:
+        super().__init__(ax, name, start_state, **kwargs)
+        self.on_clicked(self.toggle)
+        self.set_text()
+
+    def set_text(self) -> None:
+        """Set the text of the toggle button."""
+        self.label._text = f"{self.name}={self.state}"
+
+    def toggle(self, event=None) -> None:
+        """Toggle the state of the button."""
+        self.state = not self.state
+        self.set_text()
+
+    def set_state(self, state: bool) -> None:
+        """Set the state of the button."""
+        assert isinstance(state, bool)
+        self.state = state
+        self.set_text()
+
+
+class Selector:
+    """
+    Select points in a plot using the lasso selection widget.
+
+    Indices of selected points are stored in self.sel.
+
+    Example:
+        f, ax = plt.subplots(1, 1)
+        ph, = ax.plot(np.random.rand(20))
+        plt.show(block=False)
+        ls = gui.Lasso(ph)
+        ls.start()
+        -- play around with selecting points --
+        ls.stop() -> disconnects the events
+    """
+
+    def __init__(self, plot_handle: mlines.Line2D) -> None:
+        """Initialize the selector with a plot handle."""
+        assert isinstance(plot_handle, mlines.Line2D)
+        self.plot_handle = plot_handle
+        self.xdata, self.ydata = plot_handle.get_data()
+        self.ax = plot_handle.axes
+        (self.overlay_handle,) = self.ax.plot([], [], ".")
+        self.sel = np.zeros(self.xdata.shape, dtype=bool)
+        self.is_active = False
+
+    def get_data(self) -> np.ndarray:
+        """Get the data points of the plot."""
+        return np.vstack((self.xdata, self.ydata)).T
+
+    def onselect(self, verts: List[tuple]) -> None:
+        """Select if not previously selected; Unselect if previously selected."""
+        selected_ind = mPath(verts).contains_points(self.get_data())
+        self.sel = np.logical_xor(selected_ind, self.sel)
+        sel_x = list(self.xdata[self.sel])
+        sel_y = list(self.ydata[self.sel])
+        self.overlay_handle.set_data(sel_x, sel_y)
+        plt.draw()
+
+    def start(self, event=None) -> None:
+        """Start the lasso selection."""
+        self.lasso = LassoSelectorWidget(self.plot_handle.axes, self.onselect)
+        self.is_active = True
+
+    def stop(self, event=None) -> None:
+        """Stop the lasso selection."""
+        self.lasso.disconnect_events()
+        self.is_active = False
+
+    def toggle(self, event=None) -> None:
+        """Toggle the lasso selection."""
+        if self.is_active:
+            self.stop(event)
+        else:
+            self.start(event)
+
+
+class AssetContainer:
+    """
+    Container for assets such as a button, memoryslot, etc.
+
+    Args:
+        parent (Any): matplotlib figure, or something that has a 'figure' attribute that is a figure.
+    """
+
+    def __init__(self, parent: Any) -> None:
+        self._list: List[Any] = []  # list of assets
+        self.parent = parent
+
+    def __len__(self) -> int:
+        return len(self._list)
+
+    @property
+    def names(self) -> List[str]:
+        return [x.name for x in self._list]
+
+    def __getitem__(self, key: Union[int, str]) -> Any:
+        """Return an asset by the name key or by position in the list."""
+        if not self._has_names():
+            assert isinstance(key, int)
+
+        if isinstance(key, int) and key not in self.names:
+            return self._list[key]
+
+        return {x.name: x for x in self._list}[key]
+
+    def _has_names(self) -> bool:
+        try:
+            self.names
+            return True
+        except AttributeError:
+            return False
+
+    def add(self, asset: Any) -> Any:
+        """Add an asset to the container."""
+        if hasattr(asset, "name"):
+            assert asset.name not in self.names
+        self._list.append(asset)
+        return asset
+
+    def __contains__(self, item: str) -> bool:
+        """Check if an asset with the given name exists in the container."""
+        return item in self.names
+
+
+class Buttons(AssetContainer):
+    """Manager for buttons in a matplotlib figure or GUI (see GenericBrowser for example)."""
+
+    def add(
+        self,
+        text: str = "Button",
+        action_func: Optional[Union[Callable, List[Callable]]] = None,
+        pos: Optional[tuple] = None,
+        w: float = 0.25,
+        h: float = 0.05,
+        buf: float = 0.01,
+        type_: str = "Push",
+        **kwargs,
+    ) -> Button:
+        """
+        Add a button to the parent figure / object.
+
+        If pos is provided, then w, h, and buf will be ignored.
+        """
+        assert type_ in ("Push", "Toggle")
+        nbtn = len(self)
+        if pos is None:  # start adding at the top left corner
+            parent_fig = self.parent.figure
+            mul_factor = 6.4 / parent_fig.get_size_inches()[0]
+
+            btn_w = w * mul_factor
+            btn_h = h * mul_factor
+            btn_buf = buf
+            pos = (
+                btn_buf,
+                (1 - btn_buf) - ((btn_buf + btn_h) * (nbtn + 1)),
+                btn_w,
+                btn_h,
+            )
+
+        if type_ == "Toggle":
+            b = ToggleButton(plt.axes(pos), text, **kwargs)
+        else:
+            b = Button(plt.axes(pos), text, **kwargs)
+
+        if action_func is not None:  # more than one can be attached
+            if isinstance(action_func, (list, tuple)):
+                for af in action_func:
+                    b.on_clicked(af)
+            else:
+                b.on_clicked(action_func)
+
+        return super().add(b)
+
+
+class Selectors(AssetContainer):
+    """Manager for selector objects - for picking points on line2D objects."""
+
+    def add(self, plot_handle: mlines.Line2D) -> Selector:
+        """Add a selector to the container."""
+        return super().add(Selector(plot_handle))
+
+
+class MemorySlots(AssetContainer):
+    """Manager for memory slots to store and navigate positions."""
+
+    def __init__(self, parent: Any) -> None:
+        super().__init__(parent)
+        self._list = self.initialize()
+        self._memtext = None
+
+    @staticmethod
+    def initialize() -> dict:
+        """Initialize memory slots."""
+        return {str(k): None for k in range(1, 10)}
+
+    def disable(self) -> None:
+        """Disable memory slots."""
+        self._list = {}
+
+    def enable(self) -> None:
+        """Enable memory slots."""
+        self._list = self.initialize()
+
+    def show(self, pos: str = "bottom left") -> None:
+        """Show memory slot text."""
+        self._memtext = TextView(self._list, fax=self.parent.figure, pos=pos)
+
+    def update(self, key: str) -> None:
+        """
+        Handle memory slot updates.
+
+        Initiate when None, go to the slot if it exists, free slot if pressed when it exists.
+        key is the event.key triggered by a callback.
+        """
+        if self._list[key] is None:
+            self._list[key] = self.parent._current_idx
+            self.update_display()
+        elif self._list[key] == self.parent._current_idx:
+            self._list[key] = None
+            self.update_display()
+        else:
+            self.parent._current_idx = self._list[key]
+            self.parent.update()
+
+    def update_display(self) -> None:
+        """Refresh memory slot text if it is not hidden."""
+        if self._memtext is not None:
+            self._memtext.update(self._list)
+
+    def hide(self) -> None:
+        """Hide the memory slot text."""
+        if self._memtext is not None:
+            self._memtext._text.remove()
+        self._memtext = None
+
+    def is_enabled(self) -> bool:
+        """Check if memory slots are enabled."""
+        return bool(self._list)
+
+
+class StateVariable:
+    """Manage state variables with multiple states."""
+
+    def __init__(self, name: str, states: list) -> None:
+        self.name = name
+        self.states = list(states)
+        self._current_state_idx = 0
+
+    @property
+    def current_state(self) -> Any:
+        """Get the current state."""
+        return self.states[self._current_state_idx]
+
+    def n_states(self) -> int:
+        """Get the number of states."""
+        return len(self.states)
+
+    def cycle(self) -> None:
+        """Cycle to the next state."""
+        self._current_state_idx = (self._current_state_idx + 1) % self.n_states()
+
+    def cycle_back(self) -> None:
+        """Cycle to the previous state."""
+        self._current_state_idx = (self._current_state_idx - 1) % self.n_states()
+
+    def set_state(self, state: Union[int, str]) -> None:
+        """Set the state."""
+        if isinstance(state, int):
+            assert 0 <= state < self.n_states()
+            self._current_state_idx = state
+        if isinstance(state, str):
+            assert state in self.states
+            self._current_state_idx = self.states.index(state)
+
+
+class StateVariables(AssetContainer):
+    """Manager for state variables."""
+
+    def __init__(self, parent: Any) -> None:
+        super().__init__(parent)
+        self._text = None
+
+    def asdict(self) -> dict:
+        """Return state variables as a dictionary."""
+        return {x.name: x.states for x in self._list}
+
+    def add(self, name: str, states: list) -> StateVariable:
+        """Add a state variable to the container."""
+        assert name not in self.names
+        return super().add(StateVariable(name, states))
+
+    def _get_display_text(self) -> List[str]:
+        """Get the display text for state variables."""
+        return ["State variables:"] + [
+            f"{x.name} - {x.current_state}" for x in self._list
+        ]
+
+    def show(self, pos: str = "bottom right") -> None:
+        """Show state variables text."""
+        self._text = TextView(self._get_display_text(), fax=self.parent.figure, pos=pos)
+
+    def update_display(self, draw: bool = True) -> None:
+        """Update the display of state variables."""
+        self._text.update(self._get_display_text())
+        if draw:
+            plt.draw()