nwb-video-widgets 0.1.0__py3-none-any.whl

nwb_video_widgets/video_widget.py

@@ -0,0 +1,170 @@
+"""NWB video player widget with configurable grid layout."""
+
+import pathlib
+from typing import Optional
+
+import anywidget
+import traitlets
+
+# Default grid layout: single row with Left, Body, Right cameras
+DEFAULT_GRID_LAYOUT = [["VideoLeftCamera", "VideoBodyCamera", "VideoRightCamera"]]
+
+
+class NWBFileVideoPlayer(anywidget.AnyWidget):
+    """Display videos in a configurable grid layout with synchronized playback.
+
+    Parameters
+    ----------
+    nwbfile_raw : pynwb.NWBFile
+        Raw NWB file containing video ImageSeries in acquisition
+    dandi_asset : dandi.dandiapi.RemoteBlobAsset
+        Asset object for the raw NWB file. The dandiset is derived from
+        the asset's client and dandiset_id attributes.
+    grid_layout : list of list of str, optional
+        Grid layout specifying which videos to display and how to arrange them.
+        Each inner list represents a row, and each string is a video series name.
+        Videos not found in the NWB file are silently skipped.
+        Default: [["VideoLeftCamera", "VideoBodyCamera", "VideoRightCamera"]]
+
+    Example
+    -------
+    Default layout (single row):
+
+    >>> widget = NWBFileVideoPlayer(nwbfile_raw, dandi_asset)
+
+    Custom 2x2 grid:
+
+    >>> widget = NWBFileVideoPlayer(
+    ...     nwbfile_raw, dandi_asset,
+    ...     grid_layout=[
+    ...         ["VideoLeftCamera", "VideoRightCamera"],
+    ...         ["VideoBodyCamera"],
+    ...     ]
+    ... )
+
+    Single video:
+
+    >>> widget = NWBFileVideoPlayer(
+    ...     nwbfile_raw, dandi_asset,
+    ...     grid_layout=[["VideoLeftCamera"]]
+    ... )
+    """
+
+    video_urls = traitlets.Dict({}).tag(sync=True)
+    grid_layout = traitlets.List([]).tag(sync=True)
+    # Timestamps for each video: {video_name: [t0, t1, ...]}
+    # Used to display NWB session time instead of video-relative time
+    video_timestamps = traitlets.Dict({}).tag(sync=True)
+
+    _esm = pathlib.Path(__file__).parent / "video_widget.js"
+    _css = pathlib.Path(__file__).parent / "video_widget.css"
+
+    def __init__(
+        self,
+        nwbfile_raw,
+        dandi_asset,
+        grid_layout: Optional[list[list[str]]] = None,
+        **kwargs,
+    ):
+        video_urls = self.get_video_urls_from_dandi(nwbfile_raw, dandi_asset)
+        video_timestamps = self.get_video_timestamps(nwbfile_raw)
+        layout = grid_layout if grid_layout is not None else DEFAULT_GRID_LAYOUT
+        super().__init__(
+            video_urls=video_urls,
+            grid_layout=layout,
+            video_timestamps=video_timestamps,
+            **kwargs,
+        )
+
+    @staticmethod
+    def get_video_urls_from_dandi(nwbfile_raw, dandi_asset) -> dict[str, str]:
+        """Extract video S3 URLs from raw NWB file using DANDI API.
+
+        Videos in NWB files are stored as ImageSeries with external_file paths.
+        This function finds all ImageSeries with external files and resolves
+        their relative paths to full S3 URLs using the DANDI API.
+
+        Parameters
+        ----------
+        nwbfile_raw : pynwb.NWBFile
+            Raw NWB file containing video ImageSeries in acquisition
+        dandi_asset : dandi.dandiapi.RemoteBlobAsset
+            Asset object for the raw NWB file. The dandiset is derived from
+            the asset's client and dandiset_id attributes.
+
+        Returns
+        -------
+        dict
+            Mapping of video names to S3 URLs.
+            Keys: 'VideoLeftCamera', 'VideoBodyCamera', 'VideoRightCamera'
+
+        Example
+        -------
+        >>> from dandi.dandiapi import DandiAPIClient
+        >>> client = DandiAPIClient()
+        >>> dandiset = client.get_dandiset("000409")
+        >>> dandi_asset = dandiset.get_asset_by_path("sub-.../sub-..._raw.nwb")
+        >>> video_urls = NWBFileVideoPlayer.get_video_urls_from_dandi(
+        ...     nwbfile_raw, dandi_asset
+        ... )
+        """
+        from pathlib import Path
+
+        from pynwb.image import ImageSeries
+
+        # Derive dandiset from dandi_asset
+        dandiset = dandi_asset.client.get_dandiset(dandi_asset.dandiset_id)
+
+        nwb_parent = Path(dandi_asset.path).parent
+        video_urls = {}
+
+        for name, obj in nwbfile_raw.acquisition.items():
+            # Videos are stored as ImageSeries with external_file attribute
+            if isinstance(obj, ImageSeries) and obj.external_file is not None:
+                relative_path = obj.external_file[0].lstrip("./")
+                full_path = str(nwb_parent / relative_path)
+
+                video_asset = dandiset.get_asset_by_path(full_path)
+                if video_asset is not None:
+                    video_urls[name] = video_asset.get_content_url(
+                        follow_redirects=1, strip_query=True
+                    )
+
+        return video_urls
+
+    @staticmethod
+    def get_video_timestamps(nwbfile_raw) -> dict[str, list[float]]:
+        """Extract video timestamps from NWB file ImageSeries.
+
+        Parameters
+        ----------
+        nwbfile_raw : pynwb.NWBFile
+            Raw NWB file containing video ImageSeries in acquisition
+
+        Returns
+        -------
+        dict
+            Mapping of video names to timestamp arrays.
+            Each array contains the NWB session timestamps for each frame.
+        """
+        from pynwb.image import ImageSeries
+
+        video_timestamps = {}
+
+        for name, obj in nwbfile_raw.acquisition.items():
+            if isinstance(obj, ImageSeries) and obj.external_file is not None:
+                # Get timestamps - could be explicit or computed from starting_time + rate
+                if obj.timestamps is not None:
+                    timestamps = obj.timestamps[:]
+                elif obj.starting_time is not None and obj.rate is not None:
+                    # Compute timestamps from starting_time and rate
+                    n_frames = len(obj.external_file) if hasattr(obj, 'dimension') else 1
+                    # For external files, we may not know frame count upfront
+                    # Use a reasonable estimate or just store start/rate info
+                    timestamps = [obj.starting_time]
+                else:
+                    timestamps = [0.0]
+
+                video_timestamps[name] = [float(t) for t in timestamps]
+
+        return video_timestamps

nwb_video_widgets-0.1.0.dist-info/METADATA

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: nwb-video-widgets
+Version: 0.1.0
+Summary: Interactive Jupyter widgets for NWB video and pose visualization
+Project-URL: Homepage, https://github.com/catalystneuro/nwb-video-widgets
+Project-URL: Repository, https://github.com/catalystneuro/nwb-video-widgets
+Author: Heberto Mayorquin
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anywidget,jupyter,neuroscience,nwb,pose,video,widget
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Jupyter
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: anywidget>=0.9.0
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: pynwb
+Provides-Extra: dandi
+Requires-Dist: dandi>=0.60.0; extra == 'dandi'
+Requires-Dist: h5py; extra == 'dandi'
+Requires-Dist: remfile>=0.1.13; extra == 'dandi'
+Provides-Extra: test
+Requires-Dist: opencv-python-headless; extra == 'test'
+Requires-Dist: pytest-cov; extra == 'test'
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# nwb-video-widgets
+
+[![PyPI version](https://badge.fury.io/py/nwb-video-widgets.svg)](https://badge.fury.io/py/nwb-video-widgets)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Interactive Jupyter widgets for NWB video and pose estimation visualization. Built with [anywidget](https://anywidget.dev/) for compatibility across JupyterLab, Jupyter Notebook, VS Code, and Google Colab.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Video Player Widgets](#video-player-widgets)
+- [Pose Estimation Widgets](#pose-estimation-widgets)
+## Installation
+
+For local only NWB file usage:
+
+```bash
+pip install nwb-video-widgets
+```
+
+For DANDI integration and streaming support:
+
+```bash
+pip install nwb-video-widgets[dandi]
+```
+
+## Video Player Widgets
+
+Multi-camera synchronized video player with configurable layout (Row, Column, or Grid).
+
+![Video Widget Demo](assets/video_widget_preprocessed.gif)
+
+**Features:**
+
+- Interactive settings panel for video selection
+- Multiple layout modes (Row, Column, Grid)
+- Synchronized playback across all videos
+- Session time display with NWB timestamps
+
+### DANDI Streaming
+
+Use `NWBDANDIVideoPlayer` for videos hosted on DANDI:
+
+```python
+from dandi.dandiapi import DandiAPIClient
+from nwb_video_widgets import NWBDANDIVideoPlayer
+
+client = DandiAPIClient()
+dandiset = client.get_dandiset("000409", "draft")
+asset = dandiset.get_asset_by_path("sub-NYU-39/sub-NYU-39_ses-..._behavior.nwb")
+
+widget = NWBDANDIVideoPlayer(asset=asset)
+widget
+```
+
+### Local Files
+
+Use `NWBLocalVideoPlayer` for local NWB files:
+
+```python
+from pynwb import read_nwb
+from nwb_video_widgets import NWBLocalVideoPlayer
+
+nwbfile = read_nwb("experiment.nwb")
+widget = NWBLocalVideoPlayer(nwbfile)
+widget
+```
+
+---
+
+## Pose Estimation Widgets
+
+Overlays DeepLabCut keypoints on streaming video with support for camera selection.
+
+![Pose Estimation Widget Demo](assets/pose_estimation_preprocessed.gif)
+
+**Features:**
+
+- Camera selection via settings panel
+- Keypoint visibility toggles (All/None/individual)
+- Label display toggle
+- Session time display (NWB timestamps)
+- Custom keypoint colors via colormap or explicit hex values
+- Supports split files (videos in raw file, pose in processed file)
+
+### DANDI Streaming
+
+Use `NWBDANDIPoseEstimationWidget` for DANDI-hosted files:
+
+```python
+from dandi.dandiapi import DandiAPIClient
+from nwb_video_widgets import NWBDANDIPoseEstimationWidget
+
+client = DandiAPIClient()
+dandiset = client.get_dandiset("000409", "draft")
+
+# Single file (videos + pose in same file)
+asset = dandiset.get_asset_by_path("sub-.../sub-..._combined.nwb")
+widget = NWBDANDIPoseEstimationWidget(asset=asset)
+
+# Or split files (videos in raw, pose in processed)
+raw_asset = dandiset.get_asset_by_path("sub-.../sub-..._desc-raw.nwb")
+processed_asset = dandiset.get_asset_by_path("sub-.../sub-..._desc-processed.nwb")
+widget = NWBDANDIPoseEstimationWidget(
+    asset=processed_asset,
+    video_asset=raw_asset,
+)
+widget
+```
+
+### Local Files
+
+Use `NWBLocalPoseEstimationWidget` for local NWB files:
+
+```python
+from pynwb import read_nwb
+from nwb_video_widgets import NWBLocalPoseEstimationWidget
+
+# Single file
+nwbfile = read_nwb("experiment.nwb")
+widget = NWBLocalPoseEstimationWidget(nwbfile)
+widget
+
+# Or split files
+nwbfile_raw = read_nwb("raw.nwb")
+nwbfile_processed = read_nwb("processed.nwb")
+widget = NWBLocalPoseEstimationWidget(
+    nwbfile=nwbfile_processed,
+    video_nwbfile=nwbfile_raw,
+)
+widget
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `keypoint_colors` | `str` or `dict` | Matplotlib colormap name (e.g., `'tab10'`) or dict mapping keypoint names to hex colors |
+| `default_camera` | `str` | Camera to display initially |
+

nwb_video_widgets-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+nwb_video_widgets/__init__.py,sha256=4m-AlratOMO31jFrnWQSRqU2duXHMs7ZI3Iogs-hbAs,616
+nwb_video_widgets/_utils.py,sha256=kXcgjbq8mdgR0P4drPRy_Wrag3F5Od_7Ysikrr_VQMk,10566
+nwb_video_widgets/dandi_pose_widget.py,sha256=Tk_ZnqZIRIJzIAghuc1OEh0tmP9tMDP8UVDzZ4CoySg,13511
+nwb_video_widgets/dandi_video_widget.py,sha256=OaaJrNe0IoQ8X-fkDddIa6GfpCjsYZoso3-OAJEruTA,5020
+nwb_video_widgets/local_pose_widget.py,sha256=6yrm3qoRf0C1s2CFQXTv9xCUG9NrDm4_mEv2Z8_QYww,12774
+nwb_video_widgets/local_video_widget.py,sha256=c1RRTGkOdbtEBFHUw8FzHbpezWCdRPGauhXW72sTozM,4325
+nwb_video_widgets/pose_widget.css,sha256=nTaPfxr-6TC2IlcjNf0jVHDEqG3dx0i5jF1mtf1tzPo,15172
+nwb_video_widgets/pose_widget.js,sha256=zoXoLI1j63BOvngQ-Riufy7ae297VUidXW1KA7Z2TjI,26888
+nwb_video_widgets/video_widget.css,sha256=h6G67yoRNaVR9obRZWJ8xgo6KBKbzuRfUgDPKCYlBFo,11893
+nwb_video_widgets/video_widget.js,sha256=chqvXBD4p_9GEOvakVZHQqEz7WZwlzfNo0-toI_ix2Y,20235
+nwb_video_widgets/video_widget.py,sha256=glRQOBquOHDFeKC_aW_fMvJGqqh90AsMRWzMGSokonA,6252
+nwb_video_widgets-0.1.0.dist-info/METADATA,sha256=wh2Hie2ItnAEnHc31M0Uf8KRL3g7KsjMGUGecd9Xll4,5177
+nwb_video_widgets-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+nwb_video_widgets-0.1.0.dist-info/licenses/LICENSE,sha256=9Xuwwu2OWDAyD-b0_T2W-E13CysuHPPHYu7aNSOtIMI,1070
+nwb_video_widgets-0.1.0.dist-info/RECORD,,

nwb_video_widgets-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

nwb_video_widgets-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CatalystNeuro
+
+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.