morph-spines-visualizer 0.2.4__py3-none-any.whl

morph_spines_visualizer/__init__.py

@@ -0,0 +1,33 @@
+"""morph_spines."""
+
+from importlib.metadata import version
+
+__version__ = version(__package__)
+
+from morph_spines_visualizer.core.k3d_core import (
+    k3d_version,
+    add_mesh_to_plot,
+    add_mesh_point_cloud_to_plot,
+    add_morphology_to_plot
+)
+
+from morph_spines_visualizer.core.data_loading import (
+    load_spiny_morphology
+)
+
+from morph_spines_visualizer.core.spines import (
+    get_spine_ids_by_section_id,
+    get_section_ids_for_sections_with_spines,
+    get_section_ids_with_spine_counts_for_sections_with_spines,
+    get_spine_counts_for_sections_with_spines
+)
+
+from morph_spines_visualizer.core.k3d_visualization import (
+    visualize_morphology_with_point_cloud,
+    visualization_morphology_with_synapses
+)
+
+from morph_spines_visualizer.utils.mesh_loading import (
+    load_mesh_vertices_and_faces,
+    load_mesh_vertices
+)

morph_spines_visualizer/core/__init__.py

@@ -0,0 +1,8 @@
+from .k3d_core import (
+    add_mesh_point_cloud_to_plot, 
+    add_morphology_to_plot)
+
+from .data_loading import (
+    load_spiny_morphology, 
+    load_mesh_vertices_pyvista
+)

morph_spines_visualizer/core/data_loading.py

@@ -0,0 +1,146 @@
+import pyvista as pv 
+import numpy as np 
+import trimesh
+import os 
+import morph_spines 
+from morph_spines_visualizer.utils import supress
+
+def load_mesh_vertices_and_faces_trimesh(mesh_path: str, scale_factor: float = 1.0):
+    """
+    Load a triangular mesh using trimesh and return its vertices and faces.
+
+    This function reads a mesh file (e.g., .obj, .ply, .stl) using trimesh,
+    optionally scales it, and extracts the vertex coordinates and triangle indices
+    in NumPy array format.
+
+    Args:
+        mesh_path (str): Path to the mesh file to load.
+        scale_factor (float, optional): Scale factor to apply to the mesh coordinates.
+            Defaults to 1.0.
+
+    Returns:
+        tuple[np.ndarray, np.ndarray]:
+            - vertices (np.ndarray of shape (N, 3)): Vertex coordinates (x, y, z)
+            - faces (np.ndarray of shape (M, 3)): Triangle vertex indices
+    """
+    # Load the mesh using trimesh
+    mesh = trimesh.load(mesh_path, process=False)
+
+    # Scale vertices if needed
+    vertices = mesh.vertices * scale_factor
+    faces = mesh.faces
+
+    return vertices.astype(np.float32), faces.astype(np.uint32)
+
+
+def load_mesh_vertices_trimesh(mesh_path: str, scale_factor: float = 1.0):
+    """
+    Load only the vertices of a mesh using trimesh.
+
+    Args:
+        mesh_path (str): Path to the mesh file.
+        scale_factor (float, optional): Scale factor to apply to the mesh coordinates.
+            Defaults to 1.0.
+
+    Returns:
+        np.ndarray: Vertex coordinates (Nx3) in float32.
+    """
+    mesh = trimesh.load(mesh_path, process=False)
+    vertices = mesh.vertices * scale_factor
+    return vertices.astype(np.float32)
+
+def load_mesh_vertices_and_faces_pyvista(mesh_path: str, scale_factor: float = 1.0):
+    """
+    Load a triangular mesh using PyVista and return its vertices and faces.
+
+    This function reads a mesh file (e.g., .obj, .ply, .stl, .vtu, etc.) using PyVista,
+    optionally scales it, and extracts the vertex coordinates and triangle indices
+    in NumPy array format. It is optimized for performance and simplicity compared
+    to K3D’s data loading.
+
+    Args:
+        mesh_path (str): Path to the mesh file to load.
+        scale_factor (float, optional): Scale factor to apply to the mesh coordinates.
+            Defaults to 1.0.
+
+    Returns:
+        tuple[np.ndarray, np.ndarray]:
+            - **vertices** (`np.ndarray` of shape `(N, 3)`): Array of vertex coordinates (x, y, z).
+            - **faces** (`np.ndarray` of shape `(M, 3)`): Array of triangle vertex indices.
+    """
+    # Read mesh using PyVista
+    mesh = pv.read(mesh_path)
+
+    # Scale vertices if needed
+    mesh.points *= scale_factor
+
+    # Extract vertices and faces
+    vertices = mesh.points.astype(np.float32)
+    
+    # PyVista stores faces as [n, v0, v1, v2, n, v0, v1, v2, ...]
+    # So we reshape and drop the leading 'n' (number of vertices per face)
+    faces = mesh.faces.reshape(-1, 4)[:, 1:4].astype(np.uint32)
+
+    return vertices, faces
+
+def load_mesh_vertices_pyvista(mesh_path: str, scale_factor: float = 1.0):
+    """
+    Load only the vertices of a mesh using PyVista.
+
+    This function reads a mesh file (e.g., .obj, .ply, .stl, .vtu, etc.) using PyVista,
+    optionally scales its coordinates, and returns the vertex positions as a NumPy array.
+    It is lightweight and optimized for when face data is not needed.
+
+    Args:
+        mesh_path (str): Path to the mesh file to load.
+        scale_factor (float, optional): Scale factor to apply to the mesh coordinates.
+            Defaults to 1.0.
+
+    Returns:
+        np.ndarray:
+            **vertices** (`np.ndarray` of shape `(N, 3)`): Array of vertex coordinates (x, y, z)
+            in single precision (`float32`).
+    """
+    # Read mesh using PyVista
+    mesh = pv.read(mesh_path)
+
+    # Scale vertices if needed
+    mesh.points *= scale_factor
+
+    # Extract and convert vertices
+    vertices = mesh.points.astype(np.float32)
+
+    return vertices
+
+def load_spiny_morphology(morphology_path: str):
+    """
+    Load a spiny neuronal morphology from a file using the morph-spine libaray.
+
+    This function uses the morph_spines library to load a neuronal morphology
+    that includes spines using the morph-spine library. 
+    The morphology file can be in formats supported by morph_spines (e.g., .swc, .asc).
+
+    Args:
+        morphology_path (str): Path to the morphology file.
+        
+    Returns:
+        morphology: A morphology object containing the spines.
+    Raises:
+        FileNotFoundError: If the morphology file does not exist at `morphology_path`.
+        RuntimeError: If the morphology cannot be loaded by `morph_spines`.
+    """
+    if not os.path.exists(morphology_path):
+        raise FileNotFoundError(f"Morphology file not found: {morphology_path}")
+    
+    # Load morphology using morph_spines
+    try: 
+        import warnings
+        warnings.filterwarnings("ignore", category=DeprecationWarning)
+        warnings.filterwarnings("ignore", category=UserWarning)
+
+        # To suppress the stdout/stderr output from morph_spines loading
+        with supress.SuppressOutput():
+            morphology = morph_spines.load_morphology_with_spines(morphology_path)
+    except Exception as e:
+        raise RuntimeError(f"Failed to load morphology from {morphology_path}: {e}")
+    return morphology

morph_spines_visualizer/core/geometry.py

@@ -0,0 +1,99 @@
+import numpy as np
+from typing import Tuple
+
+def get_section_points(
+    morphology, section_id: int) -> np.ndarray:
+    """
+    Retrieve the 3D points of a specific section in the morphology.
+
+    Args:
+        morphology: A morphology object containing sections with 3D points.
+                    Expected structure: morphology.morphology.sections, where
+                    each section has a `.points` attribute as an array-like of (x, y, z[, r]).
+        section_id (int): The ID of the section to retrieve points from.
+
+    Returns:
+        np.ndarray: An array of shape (N, 3) containing the 3D points of the section.
+    """
+    for section in morphology.morphology.sections:
+        if section.id == section_id:
+            pts = np.asarray(section.points)[:, :3].astype(np.float32)
+            return pts
+    raise ValueError(f"Section ID {section_id} not found in morphology.")
+
+def get_sections_points(morphology):
+    """
+    Extract 3D point coordinates for each section in a neuron morphology.
+
+    Parameters
+    ----------
+    morphology : object
+        A morphology object containing a `.morphology.sections` iterable.
+        Each section is expected to have:
+            - section.points : array-like of shape (N, ≥3)
+            - section.id : unique identifier
+
+    Returns
+    -------
+    dict
+        A dictionary mapping section IDs to Nx3 NumPy arrays of float32
+        coordinates. Sections with fewer than 2 points are skipped.
+
+    Examples
+    --------
+    >>> sections = get_sections_points(morph)
+    >>> sections[12].shape
+    (45, 3)
+    """
+    sections_points = {}
+
+    for section in morphology.morphology.sections:
+        pts = np.asarray(section.points, dtype=np.float32)[:, :3]
+
+        # Skip if section does not contain enough points to define a segment
+        if pts.shape[0] < 2:
+            continue
+
+        sections_points[section.id] = pts
+
+    return sections_points
+
+def compute_morphology_bounds(
+    morphology) -> Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, float]:
+    """
+    Compute the bounding box and related metrics for a neuronal morphology.
+
+    Args:
+        morphology: A morphology object containing sections with 3D points.
+                    Expected structure: morphology.morphology.sections, where
+                    each section has a `.points` attribute as an array-like of (x, y, z[, r]).
+
+    Returns:
+        Tuple containing:
+            - min_pt (np.ndarray): Minimum coordinates [x, y, z] of the bounding box.
+            - max_pt (np.ndarray): Maximum coordinates [x, y, z] of the bounding box.
+            - center (np.ndarray): Center of the bounding box.
+            - extent (np.ndarray): Size of the bounding box along each axis (max - min).
+            - radius (float): Approximate radius for visualization purposes (0.6 * diagonal length).
+    """
+    section_points = {}
+
+    # Collect 3D points from all sections with at least 2 points
+    for section in morphology.morphology.sections:
+        pts = np.asarray(section.points)[:, :3].astype(np.float32)
+        if pts.shape[0] < 2:
+            continue
+        section_points[section.id] = pts
+
+    if not section_points:
+        raise ValueError("Morphology contains no sections with valid points.")
+
+    # Concatenate all vertices to compute bounding box
+    all_vertices = np.concatenate(list(section_points.values()), axis=0)
+    min_pt = all_vertices.min(axis=0)
+    max_pt = all_vertices.max(axis=0)
+    center = (min_pt + max_pt) / 2
+    extent = max_pt - min_pt
+    radius = np.linalg.norm(extent) * 0.6
+
+    return min_pt, max_pt, center, extent, radius

morph_spines_visualizer/core/k3d_core.py

@@ -0,0 +1,171 @@
+import k3d
+import numpy as np
+from typing import Optional
+
+def k3d_version():
+    """
+    Returns the installed version of the k3d library.  
+
+    Returns:
+        str: The instaleld version of the k3d library. 
+    """
+    return k3d.__version__
+
+def add_mesh_to_plot(
+    mesh_vertices: np.ndarray,
+    mesh_faces: np.ndarray,
+    plot: k3d.plot,
+    color: int = 0x00ffcc
+) -> k3d.mesh:
+    """
+    Add a triangular mesh to a K3D plot.
+
+    Args:
+        mesh_vertices (np.ndarray): Nx3 array of vertex coordinates (x, y, z).
+        mesh_faces (np.ndarray): Mx3 array of triangle vertex indices.
+        plot_ (k3d.plot): The K3D plot object to which the mesh will be added.
+        color (int, optional): RGB color of the mesh in 0xRRGGBB format. Defaults to 0x00ffcc.
+
+    Returns:
+        k3d.mesh: The K3D mesh object added to the plot.
+    """
+    # Flatten faces if necessary (K3D expects a 1D array of indices)
+    faces_flat = mesh_faces.flatten()
+
+    mesh_plot = k3d.mesh(
+        mesh_vertices,
+        faces_flat,
+        color=color,
+        opacity=1.0,
+        wireframe=False,
+        flat_shading=True
+    )
+
+    plot += mesh_plot
+    return mesh_plot
+
+def add_point_cloud_to_plot(
+    points: np.ndarray,
+    plot: k3d.plot,
+    point_size: float = 0.15,
+    opacity: float = 0.15,
+    color: int = 0x00ffcc,
+    shader: str = 'flat'
+) -> k3d.points:
+    """
+    Add a 3D point cloud to a K3D plot.
+
+    Args:
+        points (np.ndarray): Nx3 array of points coordinates (x, y, z).
+        plot (k3d.plot): The K3D plot object to which the point cloud will be added.
+        point_size (float, optional): Size of the points. Defaults to 0.15.
+        opacity (float, optional): Opacity of the points. Defaults to 0.15.
+        color (int, optional): RGB color of the points in 0xRRGGBB format. Defaults to 0x00ffcc.
+        shader (str, optional): Shader to use for rendering points ('flat', 'mesh', 'sphere', etc.). 
+        Defaults to 'flat'.
+
+    Returns:
+        k3d.points: The K3D point cloud object added to the plot.
+    """
+    # Create point cloud object
+    point_cloud_plot = k3d.points(
+        points,
+        point_size=point_size,
+        color=color,
+        opacity=opacity
+    )
+
+    # Set shader
+    point_cloud_plot.shader = shader
+
+    # Add to the plot
+    plot += point_cloud_plot
+
+    return point_cloud_plot
+    
+def add_mesh_point_cloud_to_plot(
+    mesh_points: np.ndarray,
+    plot: k3d.plot,
+    point_size: float = 0.15,
+    opacity: float = 0.15,
+    color: int = 0x00ffcc,
+    shader: str = 'flat'
+) -> k3d.points:
+    """
+    Add a 3D point cloud representing mesh vertices to a K3D plot.
+
+    Args:
+        mesh_points (np.ndarray): Nx3 array of vertex coordinates (x, y, z).
+        plot (k3d.plot): The K3D plot object to which the point cloud will be added.
+        point_size (float, optional): Size of the points. Defaults to 0.15.
+        opacity (float, optional): Opacity of the points. Defaults to 0.15.
+        color (int, optional): RGB color of the points in 0xRRGGBB format. Defaults to 0x00ffcc.
+        shader (str, optional): Shader to use for rendering points ('flat', 'mesh', 'sphere', etc.). 
+        Defaults to 'flat'.
+
+    Returns:
+        k3d.points: The K3D point cloud object added to the plot.
+    """
+    # Create point cloud object
+    point_cloud_plot = k3d.points(
+        mesh_points,
+        point_size=point_size,
+        color=color,
+        opacity=opacity
+    )
+
+    # Set shader
+    point_cloud_plot.shader = shader
+
+    # Add to the plot
+    plot += point_cloud_plot
+
+    return point_cloud_plot
+
+def add_morphology_to_plot(
+    morphology,
+    plot: k3d.plot,
+    line_color: int = 0x0000FF
+) -> Optional[k3d.line]:
+    """
+    Add a neuronal morphology to a K3D plot as connected lines.
+
+    Each section in the morphology is drawn as a line, with NaN separators
+    to prevent connecting separate sections.
+
+    Args:
+        morphology: A morphology object containing sections with points.
+                    Expected structure: morphology.morphology.sections,
+                    where each section has a `.points` attribute as an array-like of (x, y, z[, r]).
+        plot (k3d.plot): The K3D plot object to which the morphology lines will be added.
+        line_color (int, optional): RGB color of the morphology lines in 0xRRGGBB format.
+                                    Defaults to 0x0000FF (blue).
+
+    Returns:
+        k3d.line or None: The K3D line object added to the plot, or None if no valid sections exist.
+    """
+    all_points = []
+
+    # Collect all section points, with NaN separators between sections
+    for section in morphology.morphology.sections:
+        pts = np.asarray(section.points)[:, :3].astype(np.float32)
+        if pts.shape[0] < 2:  # skip sections with fewer than 2 points
+            continue
+        
+        all_points.append(pts)
+        
+        # NaN separator to break the line between sections
+        all_points.append(np.array([[np.nan, np.nan, np.nan]], dtype=np.float32))
+
+    # Remove last NaN separator and concatenate
+    if not all_points:
+        return None
+
+    all_points = all_points[:-1]
+    vertices = np.vstack(all_points)
+
+    # Add single line plot for all vertices
+    line_plot = k3d.line(vertices, width=1.0, color=line_color, shader='simple')
+    plot += line_plot
+
+    return line_plot