Add kwargs to load_video(), update IO docs

Author: sitic

docs/conf.py

@@ -76,7 +76,8 @@ def remove_markdown(cell):
     "sphinxcontrib.video",
     "sphinx.ext.viewcode",
     "myst_nb",
-    "sphinx_remove_toctrees"
+    "sphinx_remove_toctrees",
+    "sphinx_design",
 ]
 myst_enable_extensions = [
     "dollarmath"

docs/tutorials/io.ipynb

@@ -101,159 +101,107 @@
     "\n",
     "Additional file formats will be added in the future (and upon request). All files can be imported using the same {func}`load_video` function, with which it is also possible to load only a specific number of frames or range of the data (e.g. from a specific frame to another), see below. \n",
     "\n",
-    "### TIFF Images\n",
+    "````{dropdown} TIFF Stacks\n",
+    ":open:\n",
     "\n",
-    "``optimap`` can read .tif / .tiff (TIFF) saved as an image stack (a single file) or an image series in a folder (8-bit and 16-bit). Simply provide the filename with the .tif or .tiff ending to load a single TIFF stack:"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "tags": [
-     "skip-execution"
-    ]
-   },
-   "outputs": [],
-   "source": [
-    "video = om.load_video('filename.tiff')"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "or the name of the folder containing the images to load a series of .tif images:"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "tags": [
-     "skip-execution"
-    ]
-   },
-   "outputs": [],
-   "source": [
-    "video = om.load_video('folder_containing_tif_images')"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### PNG Images\n",
+    "``optimap`` can read .tif / .tiff (TIFF) saved as an image stack (a single file):\n",
     "\n",
-    "``optimap`` can read a series of .png (PNG) images stored in a folder. Simply provide the name of the folder containing the image series."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "tags": [
-     "skip-execution"
-    ]
-   },
-   "outputs": [],
-   "source": [
-    "video = om.load_video('folder_containing_png_images')"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### SciMedia\n",
+    "```python\n",
+    "video = optimap.load_video(\"example.tif\")\n",
+    "```\n",
+    "````\n",
     "\n",
-    "``optimap`` can read the different SciMedia file formats, including video files acquired with single- and dual-camera systems. To import Scimedia MiCAM ULTIMA video files you only need to provide the filename with the .rsh ending of the header file (assuming it is located in the same location as the .rsd files):"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "tags": [
-     "skip-execution"
-    ]
-   },
-   "outputs": [],
-   "source": [
-    "video = om.load_video('filename.rsh')"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "To import Scimedia MiCAM 05 video files you only need to provide the filename with the .gsh ending of the header file:"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "tags": [
-     "skip-execution"
-    ]
-   },
-   "outputs": [],
-   "source": [
-    "video = om.load_video('filename.gsh')"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### MultiRecorder\n",
     "\n",
-    "``optimap`` can import .dat video files acquired with MultiRecorder (developed by J. Schröder-Schetelig, Max Planck Institute for Dynamics and Self-Organization)."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "tags": [
-     "skip-execution"
-    ]
-   },
-   "outputs": [],
-   "source": [
-    "video = om.load_video('filename.dat')"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### Numpy\n",
+    "````{dropdown} Folder of TIFF/PNG Images\n",
+    "Optimap can read a series of .tif / .tiff (TIFF) or .png (PNG) images stored in a folder. Simply provide the path to folder containing the image series. 16-bit TIFF or PNG images are supported.\n",
+    "    \n",
+    "```python\n",
+    "video = optimap.load_video(\"example_folder\")\n",
+    "```\n",
     "\n",
-    "Videos stored as numpy arrays can easily be imported using:"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "tags": [
-     "skip-execution"
-    ]
-   },
-   "outputs": [],
-   "source": [
-    "video = om.load_video('filename.npy')"
+    "The images filenames in the folder will be sorted in natural order (i.e `frame_2.png` comes before `frame_10.png`) and loaded in that order.\n",
+    "\n",
+    "If a folder contains several image series, use {func}`video.load_image_folder` instead:\n",
+    "```python\n",
+    "video = optimap.load_image_folder(\"example_folder\", prefix=\"frame_\")\n",
+    "```\n",
+    "where `prefix` is the common prefix of the image series filenames.\n",
+    "````\n",
+    "\n",
+    "````{dropdown} SciMedia\n",
+    "Optimap can read the different SciMedia file formats, including video files acquired with single- and dual-camera systems.\n",
+    "\n",
+    "To import Scimedia MiCAM ULTIMA video files provide the path to an .rsh or .rsm file:\n",
+    "\n",
+    "```python\n",
+    "video = optimap.load_video(\"example.rsh\")\n",
+    "```\n",
+    "\n",
+    "See the {class}`video.MiCAM_ULTIMA_Importer` class for more details and options.\n",
+    "\n",
+    "For Scimedia MiCAM 05 video files provide the path to an .gsd or .gsh file:\n",
+    "\n",
+    "```python\n",
+    "video = optimap.load_video(\"example.gsh\")\n",
+    "```\n",
+    "\n",
+    "See the {class}`video.MiCAM05_Importer` class for more details and options.\n",
+    "\n",
+    "For both MiCAM Ultima or MiCam 05 you can load the metadata of the video file with {func}`video.load_metadata`:\n",
+    "```python\n",
+    "metadata = video.load_metadata(\"example.rsh\")\n",
+    "print(metadata)\n",
+    "```\n",
+    "````\n",
+    "\n",
+    "````{dropdown} MultiRecorder\n",
+    "optimap can import .dat video files acquired with MultiRecorder (developed by J. Schröder-Schetelig, Max Planck Institute for Dynamics and Self-Organization).\n",
+    "```python\n",
+    "video = optimap.load_video(\"example.dat\")\n",
+    "```\n",
+    "\n",
+    "See the {class}`video.MultiRecorderImporter` class for more details and options.\n",
+    "\n",
+    "The metadata of the video file can be loaded with {func}`video.load_metadata`:\n",
+    "```python\n",
+    "metadata = video.load_metadata(\"example.dat\")\n",
+    "print(metadata)\n",
+    "```\n",
+    "````\n",
+    "\n",
+    "````{dropdown} NumPy\n",
+    "Videos stored as numpy arrays can easily be imported using:\n",
+    "```python\n",
+    "video = optimap.load_video(\"example.npy\")\n",
+    "```\n",
+    "````\n",
+    "\n",
+    "````{dropdown} MATLAB\n",
+    "Videos stored as arrays in the Matlab file format (.mat) can easily be imported using\n",
+    "    \n",
+    "```python\n",
+    "video = optimap.load_video(\"example.mat\")\n",
+    "```\n",
+    "\n",
+    "This will load the first field in the file. To load a specific field/variable, use the following syntax:\n",
+    "\n",
+    "```python\n",
+    "video = optimap.load_video(\"example.mat\", fieldname=\"field_name\")\n",
+    "```\n",
+    "````"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Matlab\n",
+    "In all cases, it is possible to import only parts of a video to reduce loading times using the following optional arguments:\n",
+    "\n",
+    "* `start_frame`: The first frame to load (default: 0)\n",
+    "* `frames`:  Number of frames to load (default: all)\n",
+    "* `step`:  Load every `step`-th frame (default: 1)\n",
     "\n",
-    "Videos stored as arrays in the Matlab file format (.mat) can easily be imported using:"
+    "For instance, load 1000 frames and only every 2nd frame starting from frame 100:"
    ]
   },
   {
@@ -266,35 +214,28 @@
    },
    "outputs": [],
    "source": [
-    "video = om.load_video('filename.mat')"
+    "video = om.load_video(\"filename.tif\", start_frame=100, frames=1000, step=2)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "It is possible to import only parts of a video, for instance, only 1000 frames and only every 2nd frame starting from frame 100:"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "tags": [
-     "skip-execution"
-    ]
-   },
-   "outputs": [],
-   "source": [
-    "video = om.load_video('filename.npy', start_frame=100, frames=1000, step=2, use_mmap=False)"
+    "This will load frames 100, 102, 104, 106, ..., 2098.\n",
+    "\n",
+    "Additionally, the `use_mmap` argument can be used to load the video using memory mapping. This will load the video as a read-only memory-mapped array, which means that the data is not loaded into memory until it is accessed. This can be useful to reduce memory usage or loading times when working with large or numerous video files.\n",
+    "\n",
+    "```python\n",
+    "video = om.load_video(\"example.npy\", use_mmap=True)\n",
+    "```\n",
+    "\n",
+    "`use_mmap` is disabled by default and only supported for TIFF stacks, MultiRecorder .dat files and NumPy .npy files."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "This option is available for all file formats including image series. Please refer to the Documentation for more information.\n",
-    "\n",
     "## Saving / Exporting Videos\n",
     "\n",
     "The following file formats can be saved / exported with ``optimap``:\n",

optimap/video/_importers.py

@@ -202,6 +202,7 @@ def _read_header(self):
             self._meta["date"] = self._meta["Date created"]
 
     def load_video(self, start_frame=0, frames=None, step=1):
+        """Returns a 3D numpy array containing the loaded video."""
         if frames is not None:
             end_frame = start_frame + frames
             if end_frame > self._Nt:

optimap/video/_load.py

@@ -154,7 +154,7 @@ def load_SciMedia_MiCAMULTIMA_metadata(filename):
     dat = MiCAM_ULTIMA_Importer(filename)
     return dat.get_metadata()
 
-def load_video(path, start_frame=0, frames=None, step=1, use_mmap=False):
+def load_video(path, start_frame=0, frames=None, step=1, use_mmap=False, **kwargs):
     """Loads a video from a file or folder, automatically detecting the file type.
 
     If ``path`` is a folder, it will load a video from a series of images in the folder.
@@ -195,6 +195,8 @@ def load_video(path, start_frame=0, frames=None, step=1, use_mmap=False):
     use_mmap : bool, optional
         If True, uses memory mapping to load the video in read-only mode, defaults to False.
         Only supported for some file types.
+    **kwargs : dict
+        Additional arguments to pass to the video loader function
 
     Returns
     -------
@@ -216,19 +218,19 @@ def load_video(path, start_frame=0, frames=None, step=1, use_mmap=False):
         msg = f"File or folder '{path}' does not exist"
         raise FileNotFoundError(msg)
     elif path.is_dir():
-        return load_image_folder(path, start_frame=start_frame, end_frame=end_frame, step=step)
+        return load_image_folder(path, start_frame=start_frame, end_frame=end_frame, step=step, **kwargs)
     elif suffix in [".tif", ".tiff"]:
-        return load_tiff(path, start_frame=start_frame, end_frame=end_frame, step=step, use_mmap=use_mmap)
+        return load_tiff(path, start_frame=start_frame, end_frame=end_frame, step=step, use_mmap=use_mmap, **kwargs)
     elif suffix in [".mat"]:
-        return load_MATLAB(path, start_frame=start_frame, end_frame=end_frame, step=step)
+        return load_MATLAB(path, start_frame=start_frame, end_frame=end_frame, step=step, **kwargs)
     elif suffix in [".gsd", ".gsh"]:
-        return load_SciMedia_MiCAM05(path, start_frame=start_frame, frames=frames, step=step)
+        return load_SciMedia_MiCAM05(path, start_frame=start_frame, frames=frames, step=step, **kwargs)
     elif suffix in [".rsh", ".rsm", ".rsd"]:
-        return load_SciMedia_MiCAMULTIMA(path, start_frame=start_frame, frames=frames, step=step)
+        return load_SciMedia_MiCAMULTIMA(path, start_frame=start_frame, frames=frames, step=step, **kwargs)
     elif suffix in [".dat"]:
-        return load_MultiRecorder(path, start_frame=start_frame, frames=frames, step=step, use_mmap=use_mmap)
+        return load_MultiRecorder(path, start_frame=start_frame, frames=frames, step=step, use_mmap=use_mmap, **kwargs)
     elif suffix in [".npy"]:
-        return load_numpy(path, start_frame=start_frame, end_frame=end_frame, step=step, use_mmap=use_mmap)
+        return load_numpy(path, start_frame=start_frame, end_frame=end_frame, step=step, use_mmap=use_mmap, **kwargs)
     else:
         msg = f"Unable to find videoloader for file extension {suffix} (for file '{path}')"
         raise ValueError(msg)

setup.py

@@ -87,6 +87,7 @@
             "jupytext",
             "jupyter-cache",
             "sphinx-remove-toctrees",
+            "sphinx-design",
         ],
     },
 )