morphoview 0.1.0__py3-none-any.whl

morphoview/__init__.py

@@ -0,0 +1,93 @@
+"""morphoview -- read, analyze and visualize neuronal morphologies.
+
+Quick start::
+
+    import morphoview as nv
+
+    graph = nv.swc_to_graph("cell.swc")
+    print(nv.summary(graph))
+
+    # Matplotlib (portable, always available if matplotlib is installed)
+    from morphoview.backends import mpl
+    mpl.plot_3d(graph, color=nv.get_colormap("3cd2"))
+    mpl.show()
+
+    # VTK (tapered tubes, interactive)
+    from morphoview.backends import vtk
+    vtk.show(graph, colormap=nv.get_colormap("3cd2"), axes=True)
+
+The rendering backends (matplotlib, VTK, vispy) are optional and imported
+lazily, so the core I/O and analysis work with just numpy + networkx.
+"""
+
+from __future__ import annotations
+
+from . import colors, graph, swc, transform
+from .colors import (
+    COLORMAPS,
+    DEFAULT_COLORMAP,
+    STRUCTURE_IDS,
+    STRUCTURE_NAMES,
+    color_for_structure,
+    get_colormap,
+    normalize,
+    structure_name,
+)
+from .graph import (
+    branch_points,
+    combine,
+    graph_to_swc,
+    leaf_nodes,
+    n_branches,
+    n_leaves,
+    soma_distance,
+    soma_pathlen,
+    structure_node_map,
+    summary,
+    swc_to_graph,
+    total_length,
+)
+from .swc import SWC_DTYPE, load_swc, save_swc
+from .transform import apply_transform, mirror, rotate, translate
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # submodules
+    "colors",
+    "graph",
+    "swc",
+    "transform",
+    # colors
+    "COLORMAPS",
+    "DEFAULT_COLORMAP",
+    "STRUCTURE_IDS",
+    "STRUCTURE_NAMES",
+    "color_for_structure",
+    "get_colormap",
+    "normalize",
+    "structure_name",
+    # swc I/O
+    "SWC_DTYPE",
+    "load_swc",
+    "save_swc",
+    # graph
+    "swc_to_graph",
+    "graph_to_swc",
+    "combine",
+    "branch_points",
+    "n_branches",
+    "leaf_nodes",
+    "n_leaves",
+    "total_length",
+    "soma_distance",
+    "soma_pathlen",
+    "structure_node_map",
+    "summary",
+    # transforms
+    "apply_transform",
+    "translate",
+    "rotate",
+    "mirror",
+]

morphoview/backends/__init__.py

@@ -0,0 +1,9 @@
+"""Rendering backends for neuronal morphologies.
+
+Each backend is imported lazily so that the heavy, optional dependencies
+(matplotlib, VTK, vispy) are only required if you actually use them.
+Import the one you need directly, e.g.::
+
+    from morphoview.backends import mpl
+    from morphoview.backends import vtk
+"""

morphoview/backends/movie.py

@@ -0,0 +1,101 @@
+"""Render a rotating movie of a morphology with VTK.
+
+Rotates the neuron about one or more axes and writes each frame, producing
+an animation.  Requires the ``vtk`` package.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, Optional, Tuple
+
+import networkx as nx
+
+from .. import colors, transform
+from . import vtk as vtk_backend
+
+vtk = vtk_backend.vtk
+
+
+def _bounding_center(graph: nx.DiGraph) -> Tuple[float, float, float]:
+    xs = [graph.nodes[n]["x"] for n in graph]
+    ys = [graph.nodes[n]["y"] for n in graph]
+    zs = [graph.nodes[n]["z"] for n in graph]
+    return (
+        (min(xs) + max(xs)) * 0.5,
+        (min(ys) + max(ys)) * 0.5,
+        (min(zs) + max(zs)) * 0.5,
+    )
+
+
+def dump_movie(
+    filename: str,
+    graph: nx.DiGraph,
+    colormap: Optional[Dict[int, colors.RGB]] = None,
+    background: Tuple[float, float, float] = (0, 0, 0),
+    lines: float = 0.0,
+    xrot: float = 0.0,
+    yrot: float = 0.0,
+    zrot: float = 0.0,
+    xangle: float = 0.0,
+    yangle: float = 0.0,
+    zangle: float = 0.0,
+    frames_per_degree: int = 10,
+    framerate: int = 25,
+    size: Tuple[int, int] = (800, 600),
+) -> None:
+    """Write a rotating animation of ``graph`` to ``filename`` (AVI).
+
+    ``xrot/yrot/zrot`` orient the neuron before recording; ``xangle`` etc.
+    are the total sweep in degrees about each axis during the movie.
+    """
+    if colormap is None:
+        colormap = colors.get_colormap(colors.DEFAULT_COLORMAP)
+
+    # Centre the morphology at the origin, then apply the initial orientation.
+    cx, cy, cz = _bounding_center(graph)
+    transform.apply_transform(
+        graph,
+        transform.rotation_translation_matrix(-cx, -cy, -cz, xrot, yrot, zrot),
+    )
+
+    renderer = vtk_backend.make_renderer(
+        graph, colormap=colormap, background=background, lines=lines
+    )
+    actor = renderer.GetActors().GetLastActor()
+    cx, cy, cz = _bounding_center(graph)
+    actor.SetOrigin(cx, cy, cz)
+
+    window = vtk.vtkRenderWindow()
+    window.SetSize(*size)
+    window.AddRenderer(renderer)
+    interactor = vtk.vtkRenderWindowInteractor()
+    interactor.SetRenderWindow(window)
+    window.Render()
+    interactor.Initialize()
+
+    def _step(angle):
+        return (0.0 if angle == 0 else 1.0 / frames_per_degree,
+                int(angle * frames_per_degree))
+
+    dx, xframes = _step(xangle)
+    dy, yframes = _step(yangle)
+    dz, zframes = _step(zangle)
+    frames = max(xframes, yframes, zframes)
+
+    w2if = vtk.vtkWindowToImageFilter()
+    w2if.SetInput(window)
+    w2if.ReadFrontBufferOff()
+    w2if.Update()
+    writer = vtk.vtkAVIWriter()
+    writer.SetRate(framerate)
+    writer.SetInputConnection(w2if.GetOutputPort())
+    writer.SetFileName(filename)
+    writer.Start()
+    for _ in range(frames):
+        actor.RotateX(dx)
+        actor.RotateY(dy)
+        actor.RotateZ(dz)
+        window.Render()
+        w2if.Modified()  # crucial: force the filter to grab the new frame
+        writer.Write()
+    writer.End()

morphoview/backends/mpl.py

@@ -0,0 +1,121 @@
+"""Matplotlib rendering backend.
+
+Lightweight 2-D projections and a 3-D line rendering of a morphology.
+This backend has no interactive picking of individual compartments but is
+the most portable and works well for figures and headless rendering.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+import networkx as nx
+
+from .. import colors
+
+
+def _resolve_color(color, sid, normalized):
+    """Pick a colour for a segment given a fixed colour or a palette."""
+    if isinstance(color, dict):
+        return colors.color_for_structure(normalized, sid)
+    return color
+
+
+def plot_2d(
+    graph: nx.DiGraph,
+    ax=None,
+    proj: str = "xy",
+    color="k",
+    alpha: float = 0.8,
+    linewidth: float = 1.0,
+):
+    """Plot a 2-D projection of the morphology onto two axes.
+
+    ``proj`` selects the plane, e.g. ``"xy"``, ``"xz"`` or ``"yz"``.
+    ``color`` is either a matplotlib colour or a ``{sid: (r, g, b)}``
+    palette (0-255) used to colour each segment by its structure type.
+    """
+    import matplotlib.pyplot as plt
+
+    if len(proj) != 2 or any(c not in "xyz" for c in proj):
+        raise ValueError(f"proj must be two of x/y/z, got {proj!r}")
+
+    if ax is None:
+        _, ax = plt.subplots()
+        ax.set_aspect("equal")
+        ax.set_xlabel(f"{proj[0]} (um)")
+        ax.set_ylabel(f"{proj[1]} (um)")
+
+    normalized = colors.normalize(color) if isinstance(color, dict) else {}
+    a0, a1 = proj[0], proj[1]
+    for n0, n1 in graph.edges():
+        p0, p1 = graph.nodes[n0], graph.nodes[n1]
+        c = _resolve_color(color, p0["s"], normalized)
+        ax.plot(
+            [p0[a0], p1[a0]],
+            [p0[a1], p1[a1]],
+            color=c,
+            alpha=alpha,
+            linewidth=linewidth,
+        )
+    return ax
+
+
+def plot_3d(
+    graph: nx.DiGraph,
+    ax=None,
+    color="k",
+    alpha: float = 0.8,
+    linewidth: float = 1.0,
+):
+    """Plot the morphology as 3-D lines.
+
+    ``color`` may be a matplotlib colour or a ``{sid: (r, g, b)}`` palette.
+    Returns the 3-D axes so callers can add markers or annotations.
+    """
+    import matplotlib.pyplot as plt
+
+    if ax is None:
+        fig = plt.figure()
+        ax = fig.add_subplot(projection="3d")
+        ax.set_xlabel("x (um)")
+        ax.set_ylabel("y (um)")
+        ax.set_zlabel("z (um)")
+
+    normalized = colors.normalize(color) if isinstance(color, dict) else {}
+    for n0, n1 in graph.edges():
+        p0, p1 = graph.nodes[n0], graph.nodes[n1]
+        c = _resolve_color(color, p0["s"], normalized)
+        ax.plot(
+            [p0["x"], p1["x"]],
+            [p0["y"], p1["y"]],
+            [p0["z"], p1["z"]],
+            color=c,
+            alpha=alpha,
+            linewidth=linewidth,
+        )
+    return ax
+
+
+def mark_nodes(
+    graph: nx.DiGraph,
+    nodes: Iterable[int],
+    ax,
+    label: bool = True,
+    color: str = "r",
+    marker: str = "^",
+):
+    """Mark and optionally label a set of nodes on a 3-D axes."""
+    for n in nodes:
+        attr = graph.nodes[n]
+        ax.plot([attr["x"]], [attr["y"]], [attr["z"]], marker=marker, color=color)
+        if label:
+            ax.text(attr["x"], attr["y"], attr["z"], str(n))
+    return ax
+
+
+def show():
+    """Display any open matplotlib figures."""
+    import matplotlib.pyplot as plt
+
+    plt.show()

morphoview/backends/vispy.py

@@ -0,0 +1,41 @@
+"""Vispy rendering backend.
+
+A GPU-accelerated interactive 3-D view using tube visuals.  Requires the
+``vispy`` package (``pip install morphoview[vispy]``).
+"""
+
+from __future__ import annotations
+
+import networkx as nx
+import numpy as np
+
+try:
+    from vispy import scene
+    from vispy.scene import visuals
+except ImportError as exc:  # pragma: no cover - exercised only without vispy
+    raise ImportError(
+        "The vispy backend requires the 'vispy' package. "
+        "Install it with: pip install morphoview[vispy]"
+    ) from exc
+
+
+def show(graph: nx.DiGraph, color="blue", name: str = "Neuron") -> None:
+    """Render a morphology as tubes in an interactive vispy canvas."""
+    canvas = scene.SceneCanvas(title=name, keys="interactive", show=True)
+    view = canvas.central_widget.add_view()
+    view.camera = scene.cameras.TurntableCamera(
+        fov=45, azimuth=-45, parent=view.scene
+    )
+    for n0, n1 in graph.edges():
+        a = graph.nodes[n0]
+        b = graph.nodes[n1]
+        pos0 = np.array((a["x"], a["y"], a["z"]))
+        pos1 = np.array((b["x"], b["y"], b["z"]))
+        mid = 0.5 * (pos0 + pos1)
+        tube = visuals.Tube(
+            points=np.vstack((pos0, mid, pos1)),
+            radius=max(a["r"], 1e-3),
+            color=color,
+        )
+        view.add(tube)
+    canvas.app.run()

morphoview/backends/vtk.py

@@ -0,0 +1,282 @@
+"""VTK rendering backend.
+
+Renders a morphology as tapered tubes (using per-point radii) or as
+fixed-width lines, coloured by structure type.  Supports labelling nodes,
+an optional scale-bar axis, fullscreen display and saving a PNG snapshot.
+
+Requires the ``vtk`` package (``pip install morphoview[vtk]``).
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional, Sequence, Tuple
+
+import networkx as nx
+import numpy as np
+
+from .. import colors
+
+try:
+    import vtk
+    from vtk.util import numpy_support as vtknp
+except ImportError as exc:  # pragma: no cover - exercised only without vtk
+    raise ImportError(
+        "The VTK backend requires the 'vtk' package. "
+        "Install it with: pip install morphoview[vtk]"
+    ) from exc
+
+
+def graph_to_polydata(
+    graph: nx.DiGraph,
+    colormap: Optional[Dict[int, colors.RGB]] = None,
+    lines: bool = False,
+) -> "vtk.vtkPolyData":
+    """Convert a morphology graph into a ``vtkPolyData``.
+
+    When ``lines`` is False the point radii are attached so a tube filter
+    can taper the rendering; segment colours come from ``colormap`` keyed
+    by the parent node's structure id.
+    """
+    if colormap is None:
+        colormap = colors.get_colormap(colors.DEFAULT_COLORMAP)
+
+    node_map = {n: i for i, n in enumerate(graph.nodes())}
+    points = vtk.vtkPoints()
+    points.SetNumberOfPoints(graph.number_of_nodes())
+    for n, i in node_map.items():
+        attr = graph.nodes[n]
+        points.SetPoint(i, (attr["x"], attr["y"], attr["z"]))
+
+    edges = vtk.vtkCellArray()
+    color_arr = vtk.vtkUnsignedCharArray()
+    color_arr.SetName("Colors")
+    color_arr.SetNumberOfComponents(3)
+    color_arr.SetNumberOfTuples(graph.number_of_edges())
+    for i, (n0, n1) in enumerate(graph.edges()):
+        line = vtk.vtkLine()
+        line.GetPointIds().SetId(0, node_map[n0])
+        line.GetPointIds().SetId(1, node_map[n1])
+        edges.InsertNextCell(line)
+        color_arr.SetTuple3(
+            i, *colors.color_for_structure(colormap, graph.nodes[n0]["s"])
+        )
+
+    polydata = vtk.vtkPolyData()
+    polydata.SetPoints(points)
+    polydata.SetLines(edges)
+    polydata.GetCellData().SetScalars(color_arr)
+
+    if not lines:
+        radii = np.array([graph.nodes[n]["r"] for n in node_map], dtype=float)
+        radius_arr = vtknp.numpy_to_vtk(
+            radii, deep=True, array_type=vtk.VTK_FLOAT
+        )
+        radius_arr.SetName("Radius")
+        polydata.GetPointData().AddArray(radius_arr)
+        polydata.GetPointData().SetActiveScalars("Radius")
+        polydata.GetCellData().AddArray(color_arr)
+    return polydata
+
+
+def make_actor(
+    graph: nx.DiGraph,
+    colormap: Optional[Dict[int, colors.RGB]] = None,
+    lines: float = 0.0,
+) -> "vtk.vtkActor":
+    """Build a ``vtkActor`` for a morphology.
+
+    ``lines`` <= 0 renders tapered tubes; a positive value renders
+    fixed-width lines of that width.
+    """
+    polydata = graph_to_polydata(graph, colormap=colormap, lines=lines > 0)
+    mapper = vtk.vtkPolyDataMapper()
+    if lines > 0:
+        mapper.SetInputData(polydata)
+    else:
+        tube = vtk.vtkTubeFilter()
+        tube.SetNumberOfSides(10)
+        tube.SetVaryRadiusToVaryRadiusByAbsoluteScalar()
+        tube.SetInputData(polydata)
+        mapper.SetInputConnection(tube.GetOutputPort())
+        mapper.ScalarVisibilityOn()
+        mapper.SetScalarModeToUseCellFieldData()
+        mapper.SelectColorArray("Colors")
+
+    actor = vtk.vtkActor()
+    actor.SetMapper(mapper)
+    if lines > 0:
+        actor.GetProperty().SetLineWidth(lines)
+    return actor
+
+
+def make_label_actor(
+    graph: nx.DiGraph,
+    label_nodes: Sequence[int],
+    labels: Optional[Sequence[str]] = None,
+    priorities: Optional[Sequence[int]] = None,
+    color: Tuple[float, float, float] = (0, 0, 0),
+) -> "vtk.vtkActor2D":
+    """Build a 2-D label actor placing text at the given nodes."""
+    labels = labels or []
+    priorities = priorities or []
+
+    points = vtk.vtkPoints()
+    label_str = vtk.vtkStringArray()
+    label_str.SetName("Labels")
+    for i, n in enumerate(label_nodes):
+        attr = graph.nodes[n]
+        points.InsertNextPoint((attr["x"], attr["y"], attr["z"]))
+        text = str(labels[i]) if i < len(labels) else str(n)
+        label_str.InsertNextValue(text)
+
+    polydata = vtk.vtkPolyData()
+    polydata.SetPoints(points)
+    polydata.GetPointData().AddArray(label_str)
+
+    hierarchy = vtk.vtkPointSetToLabelHierarchy()
+    hierarchy.SetLabelArrayName(label_str.GetName())
+    hierarchy.GetTextProperty().SetColor(*color)
+    if priorities and len(priorities) == len(label_nodes):
+        parray = vtk.vtkIntArray()
+        parray.SetName("Priorities")
+        for p in priorities:
+            parray.InsertNextValue(p)
+        hierarchy.SetPriorityArrayName(parray.GetName())
+    hierarchy.SetInputData(polydata)
+
+    prop = vtk.vtkTextProperty()
+    prop.SetColor(*color)
+    prop.ItalicOn()
+    mapper = vtk.vtkLabelPlacementMapper()
+    mapper.SetInputConnection(hierarchy.GetOutputPort())
+    mapper.GetRenderStrategy().SetDefaultTextProperty(prop)
+
+    actor = vtk.vtkActor2D()
+    actor.SetMapper(mapper)
+    return actor
+
+
+def _scalebar_axes(renderer, background):
+    color = tuple(1.0 - c for c in background)
+    axes = vtk.vtkCubeAxesActor2D()
+    axes.SetLabelFormat("%3.0f")
+    # A fixed 0-200 um reference cube. Show the two endpoint labels so the
+    # scale is readable; VTK requires >= 1 label per axis (0 warns).
+    axes.SetNumberOfLabels(2)
+    axes.SetBounds(0, 200, 0, 200, 0, 200)
+    axes.SetXLabel("X")
+    axes.SetYLabel("Y")
+    axes.SetZLabel("Z")
+    axes.SetXOrigin(0)
+    axes.SetYOrigin(0)
+    axes.SetZOrigin(0)
+    tprop = vtk.vtkTextProperty()
+    tprop.SetColor(*color)
+    axes.SetAxisLabelTextProperty(tprop)
+    axes.GetProperty().SetColor(*color)
+    axes.SetCamera(renderer.GetActiveCamera())
+    return axes
+
+
+def make_renderer(
+    graphs,
+    colormap: Optional[Dict[int, colors.RGB]] = None,
+    background: Tuple[float, float, float] = (0, 0, 0),
+    lines: float = 0.0,
+    label_nodes: Optional[Sequence[int]] = None,
+    labels: Optional[Sequence[str]] = None,
+    axes: bool = False,
+) -> "vtk.vtkRenderer":
+    """Assemble a ``vtkRenderer`` for one or more morphology graphs.
+
+    ``graphs`` may be a single graph or an iterable of graphs.
+    """
+    if isinstance(graphs, nx.DiGraph):
+        graphs = [graphs]
+    if colormap is None:
+        colormap = colors.get_colormap(colors.DEFAULT_COLORMAP)
+
+    renderer = vtk.vtkRenderer()
+    renderer.SetBackground(*background)
+    for graph in graphs:
+        renderer.AddActor(make_actor(graph, colormap=colormap, lines=lines))
+        if label_nodes:
+            label_color = tuple(1.0 - c for c in background)
+            renderer.AddActor2D(
+                make_label_actor(
+                    graph, label_nodes, labels=labels, color=label_color
+                )
+            )
+    if axes:
+        renderer.AddActor(_scalebar_axes(renderer, background))
+    renderer.ResetCamera()
+    return renderer
+
+
+def show(
+    graphs,
+    colormap: Optional[Dict[int, colors.RGB]] = None,
+    background: Tuple[float, float, float] = (0, 0, 0),
+    lines: float = 0.0,
+    label_nodes: Optional[Sequence[int]] = None,
+    labels: Optional[Sequence[str]] = None,
+    axes: bool = False,
+    fullscreen: bool = False,
+    stereo: bool = False,
+    size: Tuple[int, int] = (1024, 768),
+    save: Optional[str] = None,
+    offscreen: bool = False,
+) -> None:
+    """Render morphologies in an interactive window (or offscreen).
+
+    When ``save`` is given a PNG snapshot is written.  Set ``offscreen``
+    True to render without opening a window (useful for headless PNG
+    export); in that case the interactor loop is skipped.
+    """
+    renderer = make_renderer(
+        graphs,
+        colormap=colormap,
+        background=background,
+        lines=lines,
+        label_nodes=label_nodes,
+        labels=labels,
+        axes=axes,
+    )
+    window = vtk.vtkRenderWindow()
+    window.AddRenderer(renderer)
+    window.SetSize(*size)
+    if offscreen:
+        window.SetOffScreenRendering(1)
+    elif fullscreen:
+        window.FullScreenOn()
+    if stereo and not offscreen:
+        window.GetStereoCapableWindow()
+        window.StereoCapableWindowOn()
+        window.SetStereoRender(1)
+        window.SetStereoTypeToCrystalEyes()
+
+    interactor = None
+    if not offscreen:
+        interactor = vtk.vtkRenderWindowInteractor()
+        interactor.SetRenderWindow(window)
+
+    window.Render()
+
+    if save is not None:
+        _save_png(window, save)
+
+    if interactor is not None:
+        interactor.Initialize()
+        interactor.Start()
+
+
+def _save_png(window, path: str) -> None:
+    w2if = vtk.vtkWindowToImageFilter()
+    w2if.SetInput(window)
+    w2if.SetInputBufferTypeToRGB()
+    w2if.ReadFrontBufferOff()
+    w2if.Update()
+    writer = vtk.vtkPNGWriter()
+    writer.SetFileName(path)
+    writer.SetInputConnection(w2if.GetOutputPort())
+    writer.Write()