brainrender 2.2.0__tar.gz → 2.2.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brainrender
-Version: 2.2.0
+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,7 +23,7 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: brainglobe-atlasapi>=2.0.1
-Requires-Dist: cloud-volume>=3.11.0
+Requires-Dist: cloud-volume>=12
 Requires-Dist: brainglobe-space>=1.0.0
 Requires-Dist: brainglobe-utils>=0.5.0
 Requires-Dist: h5py

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

brainrender-2.2.1/brainrender/actors/cylinder.py

@@ -0,0 +1,50 @@
+"""Cylinder actor for brainrender scenes."""
+
+import numpy.typing as npt
+from loguru import logger
+from vedo import Mesh, shapes
+
+from brainrender.actor import Actor
+
+
+class Cylinder(Actor):
+    """Actor representing a cylinder between a point and the brain's surface."""
+
+    def __init__(
+        self,
+        pos: npt.ArrayLike | Mesh | Actor,
+        root: Actor,
+        color: str = "powderblue",
+        alpha: float = 1,
+        radius: float = 350,
+    ) -> None:
+        """
+        Parameters
+        ----------
+        pos
+            AP, DV, ML coordinates. If a Mesh or Actor is passed,
+            the centre of mass is used instead.
+        root
+            Brain root Actor or mesh.
+        color
+            Colour name. Default ``"powderblue"``.
+        alpha
+            Transparency. Default 1.
+        radius
+            Cylinder radius. Default 350.
+        """
+
+        # Get pos
+        if isinstance(pos, Mesh):
+            pos = pos.center_of_mass()
+        elif isinstance(pos, Actor):
+            pos = pos.center
+        logger.debug(f"Creating Cylinder actor at: {pos}")
+
+        # Get point at top of cylinder
+        top = pos.copy()
+        top[1] = root.bounds()[2] - 500
+
+        # Create mesh and Actor
+        mesh = shapes.Cylinder(pos=[top, pos], c=color, r=radius, alpha=alpha)
+        Actor.__init__(self, mesh, name="Cylinder", br_class="Cylinder")

brainrender-2.2.1/brainrender/actors/line.py

@@ -0,0 +1,35 @@
+"""Line actor for brainrender scenes."""
+
+import numpy.typing as npt
+from vedo import shapes
+
+from brainrender.actor import Actor
+
+
+class Line(Actor):
+    """Actor representing a line through a sequence of coordinates."""
+
+    def __init__(
+        self,
+        coordinates: npt.ArrayLike,
+        color: str | tuple = "black",
+        alpha: float = 1,
+        linewidth: float = 2,
+        name: str | None = None,
+    ) -> None:
+        """
+        Parameters
+        ----------
+        coordinates
+            Array of shape (N, 3) with AP, DV, ML coordinates.
+        color
+            CSS colour name, hex code, or RGB tuple. Default ``"black"``.
+        alpha
+            Transparency in range [0, 1]. Default 1.
+        linewidth
+            Line width. Default 2.
+        name
+            Actor name.
+        """
+        mesh = shapes.Line(p0=coordinates, lw=linewidth, c=color, alpha=alpha)
+        Actor.__init__(self, mesh, name=name, br_class="Line")