brainrender 2.1.20__tar.gz → 2.2.1__tar.gz

{brainrender-2.1.20 → brainrender-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brainrender
-Version: 2.1.20
+Version: 2.2.1
 Summary: Visualisation and exploration of brain atlases and other anatomical data
 Author-email: "Federico Claudi, Adam Tyson, Luigi Petrucco" <hello@brainglobe.info>
 License: BSD-3-Clause
@@ -23,11 +23,13 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: brainglobe-atlasapi>=2.0.1
+Requires-Dist: cloud-volume>=12
 Requires-Dist: brainglobe-space>=1.0.0
 Requires-Dist: brainglobe-utils>=0.5.0
 Requires-Dist: h5py
 Requires-Dist: k3d
 Requires-Dist: loguru
+Requires-Dist: meshio
 Requires-Dist: morphapi>=0.3.3
 Requires-Dist: msgpack
 Requires-Dist: myterial
@@ -55,18 +57,22 @@ Requires-Dist: jupyter; extra == "nb"
 Requires-Dist: k3d; extra == "nb"
 Dynamic: license-file
 
-# brainrender
-
-*A user-friendly python library to create high-quality, 3D neuro-anatomical renderings combining data from publicly available brain atlases with user-generated experimental data.*
-
-[![Python Version](https://img.shields.io/pypi/pyversions/brainrender.svg)](https://pypi.org/project/brainrender)
-[![PyPI](https://img.shields.io/pypi/v/brainrender.svg)](https://pypi.org/project/brainrender)
+[![Docs](https://img.shields.io/badge/Docs-brainrender-blue)](https://brainglobe.info/documentation/brainrender/index.html)
+[![Get in Touch](https://img.shields.io/badge/Get%20in%20Touch-BrainGlobe-blue)](https://brainglobe.info/contact.html)
+[![DOI](https://img.shields.io/badge/DOI-10.7554%2FeLife.65751-green)](https://doi.org/10.7554/eLife.65751)
+[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
 [![tests](https://github.com/brainglobe/brainrender/workflows/tests/badge.svg)](https://github.com/brainglobe/brainrender/actions)
 [![codecov](https://codecov.io/gh/brainglobe/brainrender/graph/badge.svg)](https://codecov.io/gh/brainglobe/brainrender)
+[![Python Version](https://img.shields.io/pypi/pyversions/brainrender.svg)](https://pypi.org/project/brainrender)
+[![PyPI](https://img.shields.io/pypi/v/brainrender.svg)](https://pypi.org/project/brainrender)
 [![Downloads](https://static.pepy.tech/badge/brainrender)](https://pepy.tech/project/brainrender)
-[![image.sc forum](https://img.shields.io/badge/dynamic/json.svg?label=forum&url=https%3A%2F%2Fforum.image.sc%2Ftags%2Fbrainglobe.json&query=%24.topic_list.tags.0.topic_count&colorB=brightgreen&suffix=%20topics&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAYAAAAfSC3RAAABPklEQVR42m3SyyqFURTA8Y2BER0TDyExZ+aSPIKUlPIITFzKeQWXwhBlQrmFgUzMMFLKZeguBu5y+//17dP3nc5vuPdee6299gohUYYaDGOyyACq4JmQVoFujOMR77hNfOAGM+hBOQqB9TjHD36xhAa04RCuuXeKOvwHVWIKL9jCK2bRiV284QgL8MwEjAneeo9VNOEaBhzALGtoRy02cIcWhE34jj5YxgW+E5Z4iTPkMYpPLCNY3hdOYEfNbKYdmNngZ1jyEzw7h7AIb3fRTQ95OAZ6yQpGYHMMtOTgouktYwxuXsHgWLLl+4x++Kx1FJrjLTagA77bTPvYgw1rRqY56e+w7GNYsqX6JfPwi7aR+Y5SA+BXtKIRfkfJAYgj14tpOF6+I46c4/cAM3UhM3JxyKsxiOIhH0IO6SH/A1Kb1WBeUjbkAAAAAElFTkSuQmCC)](https://forum.image.sc/tag/brainglobe)
-[![Bluesky](https://img.shields.io/badge/Bluesky-0285FF?logo=bluesky&logoColor=fff)](https://bsky.app/profile/brainglobe.info)
-[![Mastodon](https://img.shields.io/badge/Mastodon-6364FF?logo=mastodon&logoColor=fff)](https://mastodon.online/@brainglobe)
+[![Code style: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/format.json)](https://github.com/astral-sh/ruff)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-green?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
+[![Contributions Welcome](https://img.shields.io/badge/Contributions-Welcome-green.svg)](https://brainglobe.info/community/developers/index.html)
+
+# brainrender
+
+*A user-friendly python library to create high-quality, 3D neuro-anatomical renderings combining data from publicly available brain atlases with user-generated experimental data.*
 
 &nbsp;
 &nbsp;

{brainrender-2.1.20 → brainrender-2.2.1}/README.md

@@ -1,15 +1,19 @@
-# brainrender
-
-*A user-friendly python library to create high-quality, 3D neuro-anatomical renderings combining data from publicly available brain atlases with user-generated experimental data.*
-
-[![Python Version](https://img.shields.io/pypi/pyversions/brainrender.svg)](https://pypi.org/project/brainrender)
-[![PyPI](https://img.shields.io/pypi/v/brainrender.svg)](https://pypi.org/project/brainrender)
+[![Docs](https://img.shields.io/badge/Docs-brainrender-blue)](https://brainglobe.info/documentation/brainrender/index.html)
+[![Get in Touch](https://img.shields.io/badge/Get%20in%20Touch-BrainGlobe-blue)](https://brainglobe.info/contact.html)
+[![DOI](https://img.shields.io/badge/DOI-10.7554%2FeLife.65751-green)](https://doi.org/10.7554/eLife.65751)
+[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
 [![tests](https://github.com/brainglobe/brainrender/workflows/tests/badge.svg)](https://github.com/brainglobe/brainrender/actions)
 [![codecov](https://codecov.io/gh/brainglobe/brainrender/graph/badge.svg)](https://codecov.io/gh/brainglobe/brainrender)
+[![Python Version](https://img.shields.io/pypi/pyversions/brainrender.svg)](https://pypi.org/project/brainrender)
+[![PyPI](https://img.shields.io/pypi/v/brainrender.svg)](https://pypi.org/project/brainrender)
 [![Downloads](https://static.pepy.tech/badge/brainrender)](https://pepy.tech/project/brainrender)
-[![image.sc forum](https://img.shields.io/badge/dynamic/json.svg?label=forum&url=https%3A%2F%2Fforum.image.sc%2Ftags%2Fbrainglobe.json&query=%24.topic_list.tags.0.topic_count&colorB=brightgreen&suffix=%20topics&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAYAAAAfSC3RAAABPklEQVR42m3SyyqFURTA8Y2BER0TDyExZ+aSPIKUlPIITFzKeQWXwhBlQrmFgUzMMFLKZeguBu5y+//17dP3nc5vuPdee6299gohUYYaDGOyyACq4JmQVoFujOMR77hNfOAGM+hBOQqB9TjHD36xhAa04RCuuXeKOvwHVWIKL9jCK2bRiV284QgL8MwEjAneeo9VNOEaBhzALGtoRy02cIcWhE34jj5YxgW+E5Z4iTPkMYpPLCNY3hdOYEfNbKYdmNngZ1jyEzw7h7AIb3fRTQ95OAZ6yQpGYHMMtOTgouktYwxuXsHgWLLl+4x++Kx1FJrjLTagA77bTPvYgw1rRqY56e+w7GNYsqX6JfPwi7aR+Y5SA+BXtKIRfkfJAYgj14tpOF6+I46c4/cAM3UhM3JxyKsxiOIhH0IO6SH/A1Kb1WBeUjbkAAAAAElFTkSuQmCC)](https://forum.image.sc/tag/brainglobe)
-[![Bluesky](https://img.shields.io/badge/Bluesky-0285FF?logo=bluesky&logoColor=fff)](https://bsky.app/profile/brainglobe.info)
-[![Mastodon](https://img.shields.io/badge/Mastodon-6364FF?logo=mastodon&logoColor=fff)](https://mastodon.online/@brainglobe)
+[![Code style: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/format.json)](https://github.com/astral-sh/ruff)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-green?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
+[![Contributions Welcome](https://img.shields.io/badge/Contributions-Welcome-green.svg)](https://brainglobe.info/community/developers/index.html)
+
+# brainrender
+
+*A user-friendly python library to create high-quality, 3D neuro-anatomical renderings combining data from publicly available brain atlases with user-generated experimental data.*
 
  
  

brainrender-2.2.1/brainrender/_colors.py

@@ -0,0 +1,131 @@
+"""Color mapping and palette utilities for brainrender."""
+
+import random
+
+import matplotlib as mpl
+import numpy as np
+import numpy.typing as npt
+from vedo.colors import colors as vcolors
+from vedo.colors import get_color as getColor
+
+
+def map_color(
+    value: float,
+    name: str = "jet",
+    vmin: float | None = None,
+    vmax: float | None = None,
+) -> tuple[float, float, float]:
+    """
+    Map a scalar value in ``[vmin, vmax]`` to an RGB colour.
+
+    Parameters
+    ----------
+    value
+        Scalar value to transform into a colour.
+    name
+        Colormap name or matplotlib colormap. Default ``"jet"``.
+    vmin
+        Lower bound of the value range.
+    vmax
+        Upper bound of the value range.
+
+    Returns
+    -------
+    tuple of float
+        ``(r, g, b)`` colour.
+
+    Raises
+    ------
+    ValueError
+        If ``vmax`` is smaller than ``vmin``.
+    """
+    if vmax < vmin:
+        raise ValueError("vmax should be larger than vmin")
+
+    mp = mpl.colormaps.get_cmap(name)
+
+    value -= vmin
+    value /= vmax - vmin
+    if value > 0.999:
+        value = 0.999
+    elif value < 0:
+        value = 0
+    return mp(value)[0:3]
+
+
+def make_palette(N: int, *colors: str) -> list[npt.NDArray]:
+    """
+    Generate N colours interpolated across the given input colours.
+
+    Adapted from vedo's ``make_palette`` function. Interpolation is
+    performed in RGB space.
+
+    Parameters
+    ----------
+    N
+        Number of output colours.
+    *colors
+        Input colours. Any number between 1 and N is accepted.
+
+    Returns
+    -------
+    list of numpy.ndarray
+        List of ``(r, g, b)`` colour arrays.
+
+    Raises
+    ------
+    ValueError
+        If no colours are passed or more colours than N are passed.
+    """
+    N = int(N)
+
+    N_input_colors = len(colors)
+    if not N_input_colors:
+        raise ValueError("No colors where passed to make_palette")
+    if N_input_colors > N:
+        raise ValueError(
+            "More input colors than out colors (N) where passed to make_palette"
+        )
+
+    if N_input_colors == N:
+        return colors
+    else:
+        # Get how many colors for each pair of colors we are interpolating over
+        fractions = [
+            N // N_input_colors + (1 if x < N % N_input_colors else 0)
+            for x in range(N_input_colors)
+        ]
+
+        # Get pairs of colors
+        cs = [np.array(getColor(col)) for col in colors]
+        cs += [cs[-1]]
+
+        output = []
+        for n, (c1, c2) in enumerate(zip(cs, cs[1:])):
+            cols = []
+            for f in np.linspace(0, 1, fractions[n], endpoint=True):
+                c = c1 * (1 - f) + c2 * f
+                cols.append(c)
+            output.extend(cols)
+        return output
+
+
+def get_random_colors(n_colors: int = 1) -> str | list[str]:
+    """
+    Return one or more random colour names from vedo's colour palette.
+
+    Parameters
+    ----------
+    n_colors
+        Number of colours to return. Default 1.
+
+    Returns
+    -------
+    str or list of str
+        A single colour name if ``n_colors == 1``, otherwise a list.
+    """
+    col_names = list(vcolors.keys())
+    if n_colors == 1:
+        return random.choice(col_names)
+    else:
+        return list(random.choices(col_names, k=n_colors))

brainrender-2.2.1/brainrender/_io.py

@@ -0,0 +1,185 @@
+"""File I/O and network utilities for brainrender."""
+
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, ParamSpec, TypeVar
+
+import requests
+from vedo import Mesh, Volume, load
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def connected_to_internet(
+    url: str = "http://www.google.com/",
+    timeout: int = 5,
+) -> bool:
+    """
+    Check that there is an internet connection.
+
+    Parameters
+    ----------
+    url
+        URL to use for testing. Default ``"http://www.google.com/"``.
+    timeout
+        Timeout in seconds. Default 5.
+
+    Returns
+    -------
+    bool
+        ``True`` if an internet connection is available, otherwise ``False``.
+    """
+
+    try:
+        _ = requests.get(url, timeout=timeout)
+        return True
+    except requests.ConnectionError:  # pragma: no cover
+        print("No internet connection available.")  # pragma: no cover
+    return False
+
+
+def fail_on_no_connection(func: Callable[P, R]) -> Callable[P, R]:
+    """
+    Decorator that raises an error if no internet connection is available.
+
+    Parameters
+    ----------
+    func
+        Function to wrap.
+
+    Returns
+    -------
+    collections.abc.Callable
+
+    Raises
+    ------
+    ConnectionError
+        If no internet connection is found.
+    """
+    if not connected_to_internet():  # pragma: no cover
+        raise ConnectionError(
+            "No internet connection found."
+        )  # pragma: no cover
+
+    def inner(*args: Any, **kwargs: Any) -> Any:
+        return func(*args, **kwargs)
+
+    return inner
+
+
+def request(url: str) -> requests.Response:
+    """
+    Send a GET request to a URL.
+
+    Parameters
+    ----------
+    url
+        URL to request.
+
+    Returns
+    -------
+    requests.Response
+
+    Raises
+    ------
+    ConnectionError
+        If no internet connection is found.
+    ValueError
+        If the request fails.
+    """
+    if not connected_to_internet():  # pragma: no cover
+        raise ConnectionError(
+            "No internet connection found."
+        )  # pragma: no cover
+
+    response = requests.get(url)
+    if response.ok:
+        return response
+    else:  # pragma: no cover
+        exception_string = "URL request failed: {}".format(
+            response.reason
+        )  # pragma: no cover
+    raise ValueError(exception_string)
+
+
+def check_file_exists(
+    func: Callable[P, R],
+) -> Callable[P, R]:  # pragma: no cover
+    """
+    Decorator that raises an error if a function's first argument
+    is not a path to an existing file.
+
+    Parameters
+    ----------
+    func
+        Function to wrap.
+
+    Returns
+    -------
+    collections.abc.Callable
+
+    Raises
+    ------
+    FileNotFoundError
+        If the file does not exist.
+    """
+
+    def inner(*args: Any, **kwargs: Any) -> Any:
+        if not Path(args[0]).exists():
+            raise FileNotFoundError(
+                f"File {args[0]} not found"
+            )  # pragma: no cover
+        return func(*args, **kwargs)
+
+    return inner
+
+
+@check_file_exists
+def load_mesh_from_file(
+    filepath: str | Path,
+    color: str | None = None,
+    alpha: float | None = None,
+) -> Mesh | Volume:
+    """
+    Load a mesh or volume from a file (e.g. .obj, .stl).
+
+    Parameters
+    ----------
+    filepath
+        Path to the mesh file.
+    color
+        Colour to apply to the mesh.
+    alpha
+        Transparency to apply to the mesh.
+
+    Returns
+    -------
+    vedo.Mesh or vedo.Volume
+    """
+    actor = load(str(filepath))
+    actor.c(color).alpha(alpha)
+    return actor
+
+
+def convert_meshio_to_vedo(meshio_mesh, color=None, alpha=None):
+    """
+    Convert a meshio mesh to a vedo mesh.
+
+    Parameters
+    ----------
+    meshio_mesh : meshio.Mesh
+        The meshio mesh to convert.
+    color : str, optional
+        The color to apply to the mesh. Default is None.
+    alpha : float, optional
+        The transparency to apply to the mesh. Default is None.
+
+    Returns
+    -------
+    vedo.Mesh
+        The converted vedo mesh.
+    """
+    actor = Mesh([meshio_mesh.points, meshio_mesh.cells_dict["triangle"]])
+    actor.c(color).alpha(alpha)
+    return actor

brainrender-2.2.1/brainrender/_utils.py

@@ -0,0 +1,82 @@
+"""General utility helpers for file system traversal and list manipulation."""
+
+from pathlib import Path
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+def listdir(fld: str | Path) -> list[str]:
+    """
+    List the files into a folder with the complete file path instead of the relative file path like os.listdir.
+
+    Parameters
+    ----------
+    fld
+        Path to the folder.
+
+    Returns
+    -------
+    list of str
+    """
+    return [str(f) for f in Path(fld).glob("**/*") if f.is_file()]
+
+
+def get_subdirs(folderpath: str | Path) -> list[str]:
+    """
+    Return all subdirectories in a given folder.
+
+    Parameters
+    ----------
+    folderpath
+        Path to the folder.
+
+    Returns
+    -------
+    list of str
+    """
+    return [str(f) for f in Path(folderpath).glob("**/*") if f.is_dir()]
+
+
+def listify(obj: T | list[T] | tuple[T, ...]) -> list[T]:
+    """
+    Ensure the object is a list.
+
+    Parameters
+    ----------
+    obj
+        Object to listify.
+
+    Returns
+    -------
+    list
+    """
+    if isinstance(obj, list):
+        return obj
+    elif isinstance(obj, tuple):
+        return list(obj)
+    else:
+        return [obj]
+
+
+def return_list_smart(lst: list[T]) -> list[T] | T | None:
+    """
+    Return a list, single element, or None depending on list length.
+
+    Parameters
+    ----------
+    lst
+        Input list.
+
+    Returns
+    -------
+    list, Any, or None
+        The list if length > 1, the single item if length == 1,
+        or None if empty.
+    """
+    if len(lst) > 1:
+        return lst
+    elif len(lst) == 1:
+        return lst[0]
+    else:
+        return None

brainrender-2.2.1/brainrender/_video.py

@@ -0,0 +1,60 @@
+"""Thin wrapper around vedo.Video for rendering brainrender scenes to video."""
+
+import os
+from typing import Any
+
+from loguru import logger
+from myterial import amber_light
+from rich import print
+from vedo import Video as VtkVideo
+
+
+class Video(VtkVideo):
+    def __init__(
+        self,
+        *args: Any,
+        fmt: str = "mp4",
+        size: str = "1620x1050",
+        **kwargs: Any,
+    ) -> None:
+        """
+        Store screenshots as frames and merge them into a video on close.
+
+        Parameters
+        ----------
+        *args
+            Positional arguments forwarded to ``vedo.Video``.
+        fmt
+            Video format. Default ``"mp4"``.
+        size
+            Frame size in pixels. Default ``"1620x1050"``.
+        **kwargs
+            Keyword arguments forwarded to ``vedo.Video``.
+        """
+        super().__init__(*args, **kwargs)
+        self.format = fmt
+        self.size = size
+
+    def close(self) -> tuple[int, str]:
+        """
+        Render the video and write to file.
+
+        Returns
+        -------
+        tuple
+            The FFmpeg exit code and the executed command string.
+        """
+        print(f"[{amber_light}]Saving video")
+        logger.debug(f"[{amber_light}]Saving video")
+
+        fld = os.path.join(self.tmp_dir.name, "%d.png")
+        fps = int(self.fps)
+        name = f"{self.name}.{self.format}"
+        fmt = "-vcodec libx264 -crf 28 -pix_fmt yuv420p"
+        if self.size:
+            fmt += f" -s {self.size}"
+
+        command = f'ffmpeg -hide_banner -loglevel panic -y -r {fps} -start_number 0 -i "{fld}" {fmt} "{name}"'
+        out = os.system(command)
+        self.tmp_dir.cleanup()
+        return out, command