yabplot 0.1.0__py3-none-any.whl

yabplot/scene.py

@@ -0,0 +1,124 @@
+import os
+import numpy as np
+import pyvista as pv
+
+def get_shading_preset(style_name):
+    """
+    Returns a dictionary of lighting parameters for pyvista.add_mesh.
+    
+    Styles:
+    - 'default': Balanced, no shine.
+    - 'matte':   (Soft) High ambient, low contrast. Good for reading atlas colors.
+    - 'sculpted':(Hard) Stronger shadows, higher contrast. Good for showing anatomy.
+    - 'glossy':  (Shiny) Wet/Plastic look with specular highlights. 
+    """
+    presets = {
+        'default': {
+            'lighting': True,
+            'specular': 0.0, 
+            'ambient': 0.65, 
+            'diffuse': 0.4, 
+            'specular_power': 15
+        },
+        # very bright shadows
+        'matte': {
+            'lighting': True,
+            'specular': 0.0, 
+            'ambient': 0.75,
+            'diffuse': 0.2, 
+            'specular_power': 0
+        },
+        # slight shime, dark shadows, strong directional light
+        'sculpted': {
+            'lighting': True,
+            'specular': 0.05,
+            'ambient': 0.4,
+            'diffuse': 0.6,
+            'specular_power': 10
+        },
+        # strong shine, sharp highlights
+        'glossy': {
+            'lighting': True,
+            'specular': 0.3,
+            'ambient': 0.4, 
+            'diffuse': 0.6, 
+            'specular_power': 30
+        },
+        # flat 2D
+        'flat': {
+            'lighting': False,
+            'ambient': 1.0, 
+            'diffuse': 0.0, 
+            'specular': 0.0
+        }
+    }
+    
+    if style_name not in presets:
+        print(f"Warning: Style '{style_name}' not found. Using 'default'. Options: {list(presets.keys())}")
+        return presets['default']
+        
+    return presets[style_name]
+
+def get_view_configs(view_names):
+    all_views = {
+        'left_lateral':  {'pos': (-1, 0, 0), 'up': (0, 0, 1), 'side': 'L'},
+        'right_lateral': {'pos': (1, 0, 0),  'up': (0, 0, 1), 'side': 'R'},
+        'left_medial':   {'pos': (1, 0, 0),  'up': (0, 0, 1), 'side': 'L'},
+        'right_medial':  {'pos': (-1, 0, 0), 'up': (0, 0, 1), 'side': 'R'},
+        'superior':      {'pos': (0, 0, 1),  'up': (0, 1, 0), 'side': 'both'},
+        'inferior':      {'pos': (0, 0, -1), 'up': (0, 1, 0), 'side': 'both'},
+        'anterior':      {'pos': (0, 1, 0),  'up': (0, 0, 1), 'side': 'both'},
+        'posterior':     {'pos': (0, -1, 0), 'up': (0, 0, 1), 'side': 'both'}
+    }
+    if view_names is None: return all_views
+    return {k: all_views[k] for k in view_names if k in all_views}
+
+def setup_plotter(sel_views, layout, figsize, display_type, needs_bottom_row=True):
+    n = len(sel_views)
+    if layout is None:
+        if n <= 4: base_layout = (1, n)
+        elif n <= 6: base_layout = (2, 3)
+        else: base_layout = (int(np.ceil(n/4)), 4)
+    else: base_layout = layout
+
+    if needs_bottom_row:
+        nrows, ncols = base_layout[0] + 1, base_layout[1]
+        groups = [(nrows - 1, slice(0, ncols))]
+        row_weights = [1.0]*base_layout[0] + [0.2]
+    else:
+        nrows, ncols = base_layout[0], base_layout[1]
+        groups = None
+        row_weights = None
+
+    plotter = pv.Plotter(shape=(nrows, ncols), groups=groups, row_weights=row_weights,
+                         off_screen=(display_type=='none'), window_size=figsize, border=False)
+    plotter.set_background('white')
+    return plotter, ncols, nrows
+        
+def add_context_to_view(plotter, bmesh, view_side, alpha, color, **kwargs):
+    """
+    Adds context mesh. Lighting parameters are passed via **kwargs.
+    """
+    if not bmesh: return
+    for h, mesh in bmesh.items():
+        if (view_side == 'L' and h == 'rh') or (view_side == 'R' and h == 'lh'): continue
+        plotter.add_mesh(mesh, color=color, opacity=alpha, 
+                         smooth_shading=True, show_edges=False, 
+                         **kwargs)
+
+def set_camera(plotter, view_cfg, zoom=1.0, distance=200):
+    plotter.camera.position = tuple(p * distance for p in view_cfg['pos'])
+    plotter.camera.focal_point = (0, 0, 0)
+    plotter.camera.up = view_cfg['up']
+    plotter.camera.parallel_projection = True
+    plotter.reset_camera()
+    plotter.camera.zoom(zoom)
+
+def finalize_plot(plotter, export_path, display_type):
+    if export_path: plotter.screenshot(export_path, transparent_background=True)
+    
+    if display_type == 'static': plotter.show(jupyter_backend='static')
+    elif display_type == 'interactive': plotter.show(jupyter_backend='trame')
+    elif display_type == 'none': plotter.close()
+    return plotter
+

yabplot/utils.py

@@ -0,0 +1,170 @@
+import os
+import numpy as np
+import pandas as pd
+import nibabel as nib
+import pyvista as pv
+import matplotlib.pyplot as plt
+from importlib.resources import files
+
+def load_gii(gii_path):
+    """Load GIfTI geometry (vertices, faces)."""
+    mesh = nib.load(gii_path)
+    verts = mesh.darrays[0].data
+    faces = mesh.darrays[1].data
+    return verts, faces
+
+def load_gii2pv(gii_path, smooth_i=0, smooth_f=0.1):
+    """
+    Load GIfTI and convert to PyVista format with optional smoothing.
+    
+    Parameters
+    ----------
+    smooth_i : int
+        Number of smoothing iterations (e.g. 15).
+    smooth_f : float
+        Relaxation factor (0.0 to 1.0, e.g. 0.6).
+    """
+    verts, faces = load_gii(gii_path)
+    
+    # create pyvista mesh
+    faces_pv = np.hstack([np.full((faces.shape[0], 1), 3), faces]).flatten().astype(int)
+    mesh = pv.PolyData(verts, faces_pv)
+    
+    # apply smoothing
+    if smooth_i > 0:
+        # use Laplacian smoothing (standard vtkSmoothPolyDataFilter)
+        # note: higher relaxation factors can shrink the mesh significantly
+        # if shrinkage is an issue, could consider mesh.smooth_taubin() instead
+        mesh = mesh.smooth(n_iter=smooth_i, relaxation_factor=smooth_f)
+    
+    return mesh
+
+def make_cortical_mesh(verts, faces, scalars):
+    """Helper to create a PyVista mesh from raw buffers."""
+    faces_pv = np.hstack([np.full((faces.shape[0], 1), 3), faces]).flatten().astype(int)
+    mesh = pv.PolyData(verts, faces_pv)
+    mesh['Data'] = scalars
+    return mesh
+
+def prep_data(data, regions, atlas, category):
+    """Standardize input data to dictionary."""
+    if isinstance(data, pd.DataFrame):
+        if data.shape[1] >= 2:
+            return dict(zip(data.iloc[:, 0], data.iloc[:, 1]))
+    elif isinstance(data, pd.Series):
+        return data.to_dict()
+    elif isinstance(data, dict):
+        return data
+    elif isinstance(data, (list, np.ndarray, tuple)):
+        if len(data) != len(regions):
+            raise ValueError(
+                f"Data length mismatch! Atlas '{atlas}' has {len(regions)} regions, "
+                f"but input data has {len(data)}. "
+                f"For partial data, use a dictionary, pd.Series, or pd.DataFrame. "
+                f"Use `yabplot.get_atlas_regions('{atlas}', '{category}')` to see expected order."
+            )
+        # map strictly by order
+        return dict(zip(regions, data))
+
+    return data
+
+def generate_distinct_colors(n_colors, seed=42):
+    """Generate visually distinct colors using Golden Ratio."""
+    np.random.seed(seed)
+    colors = []
+    hue = np.random.rand()
+    for _ in range(n_colors):
+        hue = (hue + 0.618033988749895) % 1.0
+        colors.append(plt.cm.hsv(hue)[:3])
+    return colors
+
+def parse_lut(lut_path):
+    """parses LUT to color array and name list."""
+
+    # load and sort by ID to ensure strict order (1..N)
+    df = pd.read_csv(lut_path, sep=r'\s+', header=None)
+    df = df.sort_values(by=0)
+    
+    ids = df[0].values
+    names = df[1].tolist()
+    rgb = df.iloc[:, 2:5].values / 255.0
+    
+    max_id = ids.max()
+    
+    lut_colors = np.full((max_id + 1, 3), 0.5) 
+    lut_names_list = ["Unknown"] * (max_id + 1)
+    
+    lut_colors[ids] = rgb
+    for idx, name in zip(ids, names):
+        lut_names_list[idx] = name
+        
+    return ids, lut_colors, lut_names_list, max_id
+
+def map_values_to_surface(data, target_labels, lut_ids, dense_lut_names):
+    """maps data to vertices."""
+    # filter valid regions
+    valid_ids_list = []
+    valid_names_list = []
+    
+    for rid in lut_ids:
+        if rid < len(dense_lut_names):
+            valid_ids_list.append(rid)
+            valid_names_list.append(dense_lut_names[rid])
+    
+    valid_ids = np.array(valid_ids_list)
+    n_regions = len(valid_ids)
+
+    # atlas visualization without data
+    if data is None:
+        return target_labels
+
+    # data mapping
+    max_id = max(target_labels.max(), lut_ids.max())
+    lookup_table = np.full(max_id + 1, np.nan)
+    source_values = np.full(n_regions, np.nan)
+
+    if isinstance(data, dict):
+        for i, name in enumerate(valid_names_list):
+            if name in data:
+                source_values[i] = data[name]            
+    elif isinstance(data, (np.ndarray, list, tuple)):
+        # map by order
+        if len(data) != n_regions:
+            raise ValueError(
+                f"Data length mismatch! The atlas LUT defines {n_regions} regions, "
+                f"but input data has {len(data)}.\n"
+                f"Expected order starts with: {valid_names_list[0:3]}...\n"
+                f"Solution: Use a dictionary for partial data, or check `yabplot.get_atlas_regions`."
+            )
+        source_values = np.array(data)
+    else:
+        raise ValueError("Data must be dict, list, or numpy array.")
+
+    lookup_table[valid_ids] = source_values
+    return lookup_table[target_labels]
+
+def lines_from_streamlines(streamlines):
+    if len(streamlines) == 0: return np.array([]), np.array([]), np.array([])
+    
+    points = np.vstack(streamlines)
+    n_points = [len(s) for s in streamlines]
+    offsets = np.insert(np.cumsum(n_points), 0, 0)[:-1]
+    
+    cells = []
+    for length, offset in zip(n_points, offsets):
+        cells.append(np.hstack([[length], np.arange(offset, offset + length)]))
+    lines = np.hstack(cells)
+    
+    # Calculate tangents
+    tangents = []
+    for s in streamlines:
+        if len(s) < 2: 
+            tangents.append(np.array([[0,0,0]]))
+            continue
+        vecs = np.diff(s, axis=0)
+        vecs = np.vstack([vecs, vecs[-1:]])
+        norms = np.linalg.norm(vecs, axis=1, keepdims=True)
+        norms[norms == 0] = 1
+        tangents.append(vecs / norms)
+        
+    return points, lines, np.vstack(tangents)

yabplot-0.1.0.dist-info/METADATA

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: yabplot
+Version: 0.1.0
+Summary: yet another brain plot
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ipywidgets>=8.1.8
+Requires-Dist: nibabel>=5.3.2
+Requires-Dist: pandas>=2.3.3
+Requires-Dist: pooch>=1.8.2
+Requires-Dist: pyvista>=0.46.4
+Requires-Dist: scikit-image>=0.25.2
+Requires-Dist: trame>=3.12.0
+Requires-Dist: trame-vtk>=2.10.0
+Requires-Dist: trame-vuetify>=3.1.0
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == "docs"
+Requires-Dist: mkdocs-jupyter>=0.25.1; extra == "docs"
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocstrings[python]; extra == "docs"
+Dynamic: license-file
+
+# yabplot: yet another brain plot
+
+![logo](docs/assets/yabplot_logo.png)
+
+[![PyPI version](https://img.shields.io/pypi/v/yabplot.svg)](https://pypi.org/project/yabplot/)
+[![Docs](https://github.com/teanijarv/yabplot/actions/workflows/docs.yml/badge.svg)](https://teanijarv.github.io/yabplot/)
+[![Tests](https://github.com/teanijarv/yabplot/actions/workflows/tests.yml/badge.svg)](https://github.com/teanijarv/yabplot/actions/workflows/tests.yml)
+<!-- [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.XXXXXX.svg)](https://doi.org/10.5281/zenodo.XXXXXX) -->
+
+**yabplot** is a Python library for creating beautiful, publication-quality 3D brain visualizations. it supports plotting cortical regions, subcortical structures, and white matter bundles.
+
+the idea is simple. while there are already amazing visualization tools available, they often focus on specific domains—using one tool for white matter tracts and another for cortical surfaces inevitably leads to inconsistent styles. i wanted a unified, simple-to-use tool that enables me (and hopefully others) to perform most brain visualizations in a single place. recognizing that neuroscience evolves daily, i designed **yabplot** to be modular: it supports standard pre-packaged atlases out of the box, but easily accepts any custom parcellation or tractography dataset you might need.
+
+## features
+
+* **pre-existing atlases:** access many commonly used atlases (schaefer2018, brainnetome, aparc, aseg, musus100, xtract, etc) on demand.
+* **simple to use:** plug-n-play functions for cortex, subcortex, and tracts with a unified API.
+* **custom atlases:** easily use your own parcellations, segmentations (.nii/.gii), or tractograms (.trk).
+* **flexible inputs:** accepts data as dictionaries (for partial mapping) or arrays (for strict mapping).
+
+## installation
+
+```bash
+uv add yabplot
+```
+or
+```bash
+pip install yabplot
+```
+
+dependencies: python 3.11 with ipywidgets, nibabel, pandas, pooch, pyvista, scikit-image, trame, trame-vtk, trame-vuetify
+
+## quick start
+
+please refer to the [documentation](https://teanijarv.github.io/yabplot/) for more comprehensive guides.
+
+```python
+import yabplot as yab
+import numpy as np
+
+# see available cortical atlases
+atlases = yab.get_available_resources(category='cortical')
+
+# see the region names within the aseg atlas
+regions = yab.get_atlas_regions(atlas='aseg', category='subcortical')
+
+# plot data on cortical regions
+data = np.arange(0, 1, 0.001)
+yab.plot_cortical(data=data, atlas='schaefer_1000', figsize=(600, 300),
+                  cmap='viridis', vminmax=[0, 1], style='default',
+                  views=['left_lateral', 'superior', 'right_lateral'])
+
+
+# plot values for specific subcortical regions
+data = {'Left_Amygdala': 0.8, 'Right_Hippocampus': 0.5, 
+        'Right_Thalamus': -0.5, 'Left_Putamen': -1}
+yab.plot_subcortical(data=data, atlas='aseg', figsize=(600, 450), layout=(2, 2),
+                     views=['superior', 'anterior', 'left_lateral', 'right_lateral'], 
+                     cmap='coolwarm', vminmax=[-1, 1], style='matte')
+
+# plot data on white matter bundles
+regions = yab.get_atlas_regions(atlas='xtract_tiny', category='tracts')
+data = np.arange(0, len(regions))
+yab.plot_tracts(data=data, atlas='xtract_tiny', figsize=(600, 300), 
+                views=['superior', 'anterior', 'left_lateral'], nan_color='#cccccc', 
+                bmesh_type='fsaverage', style='default', cmap='plasma')
+
+```
+
+![examples](docs/assets/examples.png)
+
+## acknowledgements
+
+yabplot relies on the extensive work of the neuroimaging community. if you use these atlases in your work, please cite the original authors.

yabplot-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+yabplot/__init__.py,sha256=qWDPpGuPgMJhol88FJ1BlPgnu1kMQQWj-iLUAniUVJQ,308
+yabplot/plotting.py,sha256=UI2fOqNeHIB0_Exj0bltnyUrEhpeNMl7cEJkS9Uzdws,25967
+yabplot/scene.py,sha256=vQ4QxOdQ6uhoMGtz9dxQi5G0E5gip5DR3v3sbjMviaU,4522
+yabplot/utils.py,sha256=ROtBqmTqmhNrdPBUCqp4hWmRv363i-R7xH1SZGHTNNk,5737
+yabplot/data/__init__.py,sha256=jYR5iyJeEk0qRt8jYcaHGy6q6uJQVHFUasj78SH5X64,12047
+yabplot-0.1.0.dist-info/licenses/LICENSE,sha256=bz__yccnNr-Tsjp1iTjk2KBb1EgW4mdkdZCLAU-Yw24,1063
+yabplot-0.1.0.dist-info/METADATA,sha256=NmCvg1vkedOTV-fRdt6hFe7ZjNBsWhTkaOmn5srinS0,4331
+yabplot-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+yabplot-0.1.0.dist-info/top_level.txt,sha256=hrhVrEs-yKkYrOJfuc84JCkuOxJMN2AxEU5jxA1tZco,8
+yabplot-0.1.0.dist-info/RECORD,,

yabplot-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

yabplot-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Toomas Erik Anijärv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+OR OTHER DEALINGS IN THE SOFTWARE.

yabplot-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+yabplot