datanavigator 1.0.0__tar.gz

datanavigator-1.0.0/.gitignore

@@ -0,0 +1,163 @@
+.vscode/*
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+.venv-dev
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

datanavigator-1.0.0/.readthedocs.yaml

@@ -0,0 +1,29 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats:
+  - pdf
+  - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .

datanavigator-1.0.0/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2024-present Praneeth Namburi <praneeth.namburi@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

datanavigator-1.0.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.1
+Name: datanavigator
+Version: 1.0.0
+Summary: Interactive data visualization for signals, videos, and complex data objects.
+Author-email: Praneeth Namburi <praneeth.namburi@gmail.com>
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Scientific/Engineering
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: matplotlib
+Requires-Dist: opencv-contrib-python
+Requires-Dist: portion
+Requires-Dist: ffmpeg-python
+Requires-Dist: pysampled
+Requires-Dist: decord
+Requires-Dist: tables
+Project-URL: Home, https://github.com/praneethnamburi/datanavigator
+
+# datanavigator
+
+[![src](https://img.shields.io/badge/src-github-blue)](https://github.com/praneethnamburi/datanavigator)
+[![PyPI - Version](https://img.shields.io/pypi/v/datanavigator.svg?logo=pypi&label=PyPI&logoColor=gold)](https://pypi.org/project/datanavigator/)
+[![Documentation Status](https://readthedocs.org/projects/datanavigator/badge/?version=latest)](https://datanavigator.readthedocs.io)
+[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/praneethnamburi/datanavigator/main/LICENSE)
+
+*Interactive data visualization for signals, videos, and complex data objects.*
+
+`datanavigator` is a matplotlib-based toolkit for interactive data visualization that handles signals, videos, and complex data objects. It provides both simple tools for navigating data with minimal programming and a user-friendly API for building sophisticated data interaction applications. This versatility makes it both powerful and accessible, regardless of a user's programming expertise.
+
+## Installation
+
+```sh
+pip install datanavigator
+```
+
+If you encounter dependency issues, use the `requirements.yml` file with conda to either create a new environment or update your existing environment. Then, run the command above to install `datanavigator`.
+
+```sh
+git clone https://github.com/praneethnamburi/datanavigator.git
+cd datanavigator
+conda env create -n env-datanavigator -f requirements.yml
+conda activate env-datanavigator
+pip install datanavigator
+```
+
+## Quickstart
+
+### 1. Browse video frames and extract a clip
+```python
+import datanavigator as dnav
+
+video_browser = dnav.VideoBrowser(dnav.get_example_video())
+# Use the arrow keys to browse through frames.
+# Press Ctrl+K to bring up a list of available keyboard shortcuts
+# To extract a clip, 
+#   1. navigate to the start frame and press 1
+#   2. navigate to the end frame and press 2
+#   3. press e to save the extracted clip
+# run dnav.get_clip_folder() to find the saved video clip
+
+# Or, you can extract a clip from the command line
+clip_path = video_browser.extract_clip(start_frame=100, end_frame=200)
+print(f"Extracted clip saved to: {clip_path}")
+```
+
+### 2. Browse time series data and mark events of interest
+```python
+import datanavigator as dnav
+signal_browser = dnav.EventPickerDemo()
+```
+
+## License
+
+This project is licensed under the MIT License. See the `LICENSE` file for details.
+
+
+## Contact
+
+[Praneeth Namburi](https://praneethnamburi.com)
+
+Project Link: [https://github.com/praneethnamburi/datanavigator](https://github.com/praneethnamburi/datanavigator)
+
+
+## Acknowledgments
+
+This tool was developed as part of the ImmersionToolbox initiative at the [MIT.nano Immersion Lab](https://immersion.mit.edu). Thanks to NCSOFT for supporting this initiative.
+

datanavigator-1.0.0/README.md

@@ -0,0 +1,68 @@
+# datanavigator
+
+[![src](https://img.shields.io/badge/src-github-blue)](https://github.com/praneethnamburi/datanavigator)
+[![PyPI - Version](https://img.shields.io/pypi/v/datanavigator.svg?logo=pypi&label=PyPI&logoColor=gold)](https://pypi.org/project/datanavigator/)
+[![Documentation Status](https://readthedocs.org/projects/datanavigator/badge/?version=latest)](https://datanavigator.readthedocs.io)
+[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/praneethnamburi/datanavigator/main/LICENSE)
+
+*Interactive data visualization for signals, videos, and complex data objects.*
+
+`datanavigator` is a matplotlib-based toolkit for interactive data visualization that handles signals, videos, and complex data objects. It provides both simple tools for navigating data with minimal programming and a user-friendly API for building sophisticated data interaction applications. This versatility makes it both powerful and accessible, regardless of a user's programming expertise.
+
+## Installation
+
+```sh
+pip install datanavigator
+```
+
+If you encounter dependency issues, use the `requirements.yml` file with conda to either create a new environment or update your existing environment. Then, run the command above to install `datanavigator`.
+
+```sh
+git clone https://github.com/praneethnamburi/datanavigator.git
+cd datanavigator
+conda env create -n env-datanavigator -f requirements.yml
+conda activate env-datanavigator
+pip install datanavigator
+```
+
+## Quickstart
+
+### 1. Browse video frames and extract a clip
+```python
+import datanavigator as dnav
+
+video_browser = dnav.VideoBrowser(dnav.get_example_video())
+# Use the arrow keys to browse through frames.
+# Press Ctrl+K to bring up a list of available keyboard shortcuts
+# To extract a clip, 
+#   1. navigate to the start frame and press 1
+#   2. navigate to the end frame and press 2
+#   3. press e to save the extracted clip
+# run dnav.get_clip_folder() to find the saved video clip
+
+# Or, you can extract a clip from the command line
+clip_path = video_browser.extract_clip(start_frame=100, end_frame=200)
+print(f"Extracted clip saved to: {clip_path}")
+```
+
+### 2. Browse time series data and mark events of interest
+```python
+import datanavigator as dnav
+signal_browser = dnav.EventPickerDemo()
+```
+
+## License
+
+This project is licensed under the MIT License. See the `LICENSE` file for details.
+
+
+## Contact
+
+[Praneeth Namburi](https://praneethnamburi.com)
+
+Project Link: [https://github.com/praneethnamburi/datanavigator](https://github.com/praneethnamburi/datanavigator)
+
+
+## Acknowledgments
+
+This tool was developed as part of the ImmersionToolbox initiative at the [MIT.nano Immersion Lab](https://immersion.mit.edu). Thanks to NCSOFT for supporting this initiative.

datanavigator-1.0.0/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-1.0.0/datanavigator/__version__.py

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

datanavigator-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