yabplot 0.1.4__tar.gz → 0.2.0__tar.gz

{yabplot-0.1.4/yabplot.egg-info → yabplot-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: yabplot
-Version: 0.1.4
+Version: 0.2.0
 Summary: yet another brain plot
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -55,6 +55,9 @@ pip install yabplot --upgrade # to update
 
 dependencies: python 3.11 with ipywidgets, nibabel, pandas, pooch, pyvista, scikit-image, trame, trame-vtk, trame-vuetify
 
+(Connectome Workbench (`wb_command`) is a requirement to create custom cortical atlases unless you plan to only use pre-loaded atlases; see more in docs)
+
+
 ## quick start
 
 please refer to the [documentation](https://teanijarv.github.io/yabplot/) for more comprehensive guides.
@@ -63,32 +66,41 @@ please refer to the [documentation](https://teanijarv.github.io/yabplot/) for mo
 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')
+# check that you have the latest version
+print(yab.__version__)
+
+# see available atlases and brain meshes
+print(yab.get_available_resources())
+
+# see the region names for a specific atlas
+print(yab.get_atlas_regions(atlas='aseg', category='subcortical'))
+
+# cortical surfaces
+atlas = 'aparc'
+dmap1 = {'L_lateraloccipital': 0.265, 'L_postcentral': 0.086, ...}
+dmap2 = {'L_fusiform': 0.218, 'L_supramarginal': 0.119, ...}
+yab.plot_cortical(data=dmap1, atlas=atlas, vminmax=[-0.1, 0.3], 
+                  bmesh_type='midthickness', views=['left_lateral', 'left_medial'],
+                  figsize=(600, 300), cmap='viridis', proc_vertices='sharp')
+yab.plot_cortical(data=dmap2, atlas=atlas, vminmax=[-0.1, 0.3], 
+                  bmesh_type='swm', views=['left_lateral', 'left_medial'],
+                  figsize=(1200, 600), cmap='viridis', proc_vertices='sharp')
+
+# subcortical structures
+atlas = 'aseg'
+regs = yab.get_atlas_regions(atlas=atlas, category='subcortical')
+data = np.arange(1, len(regs)+1)
+yab.plot_subcortical(data=data, atlas=atlas, vminmax=[2, 14], 
+                     views=['left_lateral', 'superior', 'right_lateral'], 
+                     bmesh_alpha=0.1, figsize=(600, 300), cmap='viridis')
+
+# white matter bundles
+atlas = 'xtract_tiny'
+regs = yab.get_atlas_regions(atlas=atlas, category='tracts')
+data = {reg: np.sin(i) for i, reg in enumerate(regs)}
+yab.plot_tracts(data=data, atlas=atlas, style='matte',
+                views=['left_lateral', 'anterior', 'superior'], bmesh_type='pial',
+                bmesh_alpha=0.1, figsize=(1600, 800), cmap='viridis')
 
 ```
 

{yabplot-0.1.4 → yabplot-0.2.0}/README.md

@@ -32,6 +32,9 @@ pip install yabplot --upgrade # to update
 
 dependencies: python 3.11 with ipywidgets, nibabel, pandas, pooch, pyvista, scikit-image, trame, trame-vtk, trame-vuetify
 
+(Connectome Workbench (`wb_command`) is a requirement to create custom cortical atlases unless you plan to only use pre-loaded atlases; see more in docs)
+
+
 ## quick start
 
 please refer to the [documentation](https://teanijarv.github.io/yabplot/) for more comprehensive guides.
@@ -40,32 +43,41 @@ please refer to the [documentation](https://teanijarv.github.io/yabplot/) for mo
 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')
+# check that you have the latest version
+print(yab.__version__)
+
+# see available atlases and brain meshes
+print(yab.get_available_resources())
+
+# see the region names for a specific atlas
+print(yab.get_atlas_regions(atlas='aseg', category='subcortical'))
+
+# cortical surfaces
+atlas = 'aparc'
+dmap1 = {'L_lateraloccipital': 0.265, 'L_postcentral': 0.086, ...}
+dmap2 = {'L_fusiform': 0.218, 'L_supramarginal': 0.119, ...}
+yab.plot_cortical(data=dmap1, atlas=atlas, vminmax=[-0.1, 0.3], 
+                  bmesh_type='midthickness', views=['left_lateral', 'left_medial'],
+                  figsize=(600, 300), cmap='viridis', proc_vertices='sharp')
+yab.plot_cortical(data=dmap2, atlas=atlas, vminmax=[-0.1, 0.3], 
+                  bmesh_type='swm', views=['left_lateral', 'left_medial'],
+                  figsize=(1200, 600), cmap='viridis', proc_vertices='sharp')
+
+# subcortical structures
+atlas = 'aseg'
+regs = yab.get_atlas_regions(atlas=atlas, category='subcortical')
+data = np.arange(1, len(regs)+1)
+yab.plot_subcortical(data=data, atlas=atlas, vminmax=[2, 14], 
+                     views=['left_lateral', 'superior', 'right_lateral'], 
+                     bmesh_alpha=0.1, figsize=(600, 300), cmap='viridis')
+
+# white matter bundles
+atlas = 'xtract_tiny'
+regs = yab.get_atlas_regions(atlas=atlas, category='tracts')
+data = {reg: np.sin(i) for i, reg in enumerate(regs)}
+yab.plot_tracts(data=data, atlas=atlas, style='matte',
+                views=['left_lateral', 'anterior', 'superior'], bmesh_type='pial',
+                bmesh_alpha=0.1, figsize=(1600, 800), cmap='viridis')
 
 ```
 

{yabplot-0.1.4 → yabplot-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "yabplot"
-version = "0.1.4"
+version = "0.2.0"
 description = "yet another brain plot"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -29,4 +29,4 @@ where = ["."]
 include = ["yabplot*"]
 
 [tool.setuptools.package-data]
-"yabplot" = ["*.txt", "*.json"]
+"yabplot" = ["*.txt", "*.json"]

{yabplot-0.1.4 → yabplot-0.2.0}/tests/test_smoke.py

@@ -23,16 +23,16 @@ def test_plot_cortical():
     """
     Integration test: Downloads 'aparc' and plots it.
     """
-    yab.plot_cortical(atlas='aparc', display_type='none')
+    yab.plot_cortical(atlas='aparc', display_type=None)
 
 def test_plot_subcortical():
     """
     Integration test: Downloads 'aseg' and plots it.
     """
-    yab.plot_subcortical(atlas='aseg', display_type='none')
+    yab.plot_subcortical(atlas='aseg', display_type=None)
 
 def test_plot_tracts():
     """
     Integration test: Downloads 'xtract_tiny' and plots it.
     """
-    yab.plot_tracts(atlas='xtract_tiny', display_type='none')
+    yab.plot_tracts(atlas='xtract_tiny', display_type=None)

{yabplot-0.1.4 → yabplot-0.2.0}/yabplot/__init__.py

@@ -1,7 +1,8 @@
 from importlib.metadata import version, PackageNotFoundError
 
 from .plotting import plot_cortical, plot_subcortical, plot_tracts, clear_tract_cache
-from .data import get_available_resources, get_atlas_regions
+from .data import get_available_resources, get_atlas_regions, get_surface_paths
+from .atlas_builder import build_cortical_atlas, build_subcortical_atlas
 
 try:
     __version__ = version("yabplot")

yabplot-0.2.0/yabplot/atlas_builder.py

@@ -0,0 +1,404 @@
+import os
+import glob
+import numpy as np
+import nibabel as nib
+import scipy.sparse as sp
+import pyvista as pv
+from skimage import measure
+from .wrappers import run_wb_import, run_wb_projection
+from .data import get_surface_paths
+from .plotting import plot_cortical, plot_subcortical
+
+### CORTICAL
+
+def _build_adjacency(surf_path, n_vert=32492):
+    """internal helper to build surface adjacency matrix."""
+    surf = nib.load(surf_path)
+    faces = surf.darrays[1].data.astype(int)
+    edges = np.vstack([faces[:, [0, 1]], faces[:, [1, 2]], faces[:, [2, 0]]])
+    row, col = np.concatenate([edges[:, 0], edges[:, 1]]), np.concatenate([edges[:, 1], edges[:, 0]])
+    return sp.coo_matrix((np.ones(len(row), dtype=int), (row, col)), shape=(n_vert, n_vert)).tocsr()
+
+def build_cortical_atlas(nii_path, wb_txt_path, out_dir, include_list=None, exclude_list=None, atlasname='atlas'):
+    """
+    builds a custom yabplot cortical atlas from a volumetric NIfTI file.
+
+    projects a volumetric NIfTI atlas to standard fsLR32k surfaces using connectome workbench, 
+    cleans the medial wall, and applies majority-vote boundary smoothing to remove voxel artifacts.
+
+    parameters
+    ----------
+    nii_path : str
+        absolute path to the 3D NIfTI volume of the atlas.
+    wb_txt_path : str
+        absolute path to the text file formatted specifically for connectome workbench.
+    out_dir : str
+        directory where the final .csv map and .txt LUT will be saved.
+    include_list : list of str, optional
+        keywords of regions to strictly include. all other regions are ignored.
+    exclude_list : list of str, optional
+        keywords of regions to strictly exclude. all other regions are kept.
+    atlasname : str, optional
+        prefix name for the output files. default is 'atlas'.
+
+    raises
+    ------
+    ValueError
+        if both include_list and exclude_list are provided.
+    """
+    if include_list and exclude_list:
+        raise ValueError("please provide either 'include_list' or 'exclude_list', not both.")
+
+    os.makedirs(out_dir, exist_ok=True)
+    
+    # define intermediate and output paths
+    labeled_nii = os.path.join(out_dir, 'temp_labeled.nii.gz')
+    lh_gii = os.path.join(out_dir, 'lh_temp.label.gii')
+    rh_gii = os.path.join(out_dir, 'rh_temp.label.gii')
+    out_csv = os.path.join(out_dir, f'{atlasname}.csv')
+    out_lut = os.path.join(out_dir, f'{atlasname}.txt')
+
+    # fetch standard fsLR32k surfaces and masks via yabplot data system
+    print("fetching standard surfaces...")
+    lh_mid, rh_mid = get_surface_paths('midthickness', 'bmesh')
+    lh_white, rh_white = get_surface_paths('white', 'bmesh')
+    lh_pial, rh_pial = get_surface_paths('pial', 'bmesh')
+    lh_mask_path, rh_mask_path = get_surface_paths('nomedialwall', 'label')
+
+    # run wb_command wrappers
+    print("running volume-to-surface projection...")
+    run_wb_import(nii_path, wb_txt_path, labeled_nii)
+    run_wb_projection(labeled_nii, lh_mid, lh_gii, lh_white, lh_pial)
+    run_wb_projection(labeled_nii, rh_mid, rh_gii, rh_white, rh_pial)
+
+    # extract LUT and apply include/exclude filtering
+    labels_dict = nib.load(lh_gii).labeltable.get_labels_as_dict()
+    valid_ids = []
+    lut_dict = {} 
+    
+    for rid, name in labels_dict.items():
+        if rid == 0 or name == '???': continue 
+        
+        # filter logic
+        if include_list:
+            if not any(inc in name for inc in include_list):
+                continue
+        elif exclude_list:
+            if any(exc in name for exc in exclude_list):
+                continue
+            
+        clean_name = name.replace(' ', '_').replace('/', '-')
+        np.random.seed(rid)
+        r, g, b = np.random.randint(50, 255, 3) 
+        
+        # store the string in the dictionary instead of writing to a file yet
+        lut_dict[rid] = f"{rid}  {clean_name}  {r}  {g}  {b}  0"
+        valid_ids.append(rid)
+        
+    print(f"found {len(valid_ids)} initial cortical regions. mapping and cleaning...")
+
+    # merge LH and RH, then apply masks
+    data = np.concatenate([
+        nib.load(lh_gii).darrays[0].data.astype(int).flatten(),
+        nib.load(rh_gii).darrays[0].data.astype(int).flatten()
+    ])
+    
+    mask = np.concatenate([
+        nib.load(lh_mask_path).darrays[0].data.astype(int).flatten() != 0,
+        nib.load(rh_mask_path).darrays[0].data.astype(int).flatten() != 0
+    ])
+
+    data[~mask] = 0
+    data[~np.isin(data, valid_ids)] = 0
+
+    # build adjacency and run hole-filling
+    print("building surface adjacency and filling holes...")
+    adj = sp.block_diag((_build_adjacency(lh_mid), _build_adjacency(rh_mid))).tocsr()
+    adj.setdiag(1) 
+    n_vert = len(data)
+
+    for _ in range(20): 
+        holes = (data == 0) & mask
+        if not np.any(holes): break
+        
+        unique, inv = np.unique(data, return_inverse=True)
+        one_hot = sp.coo_matrix((np.ones(n_vert), (np.arange(n_vert), inv)), shape=(n_vert, len(unique))).tocsr()
+        votes = (adj @ one_hot).toarray()
+        
+        zero_idx = np.where(unique == 0)[0][0]
+        votes[:, zero_idx] = 0 
+        
+        winner = np.argmax(votes, axis=1)
+        fill_vals = unique[winner]
+        data[holes] = fill_vals[holes]
+
+    # smooth final boundaries
+    print("smoothing boundaries...")
+    for _ in range(10): 
+        unique, inv = np.unique(data, return_inverse=True)
+        one_hot = sp.coo_matrix((np.ones(n_vert), (np.arange(n_vert), inv)), shape=(n_vert, len(unique))).tocsr()
+        winner = np.argmax((adj @ one_hot).toarray(), axis=1)
+        data = unique[winner]
+        data[~mask] = 0
+
+    # save the final vertex map
+    np.savetxt(out_csv, data, fmt='%i')
+    
+    # find out which regions actually survived the smoothing/masking
+    surviving_ids = np.unique(data)
+    
+    # filter the LUT lines to only include survivors
+    final_lines = []
+    dropped_count = 0
+    
+    for rid, line_str in lut_dict.items():
+        if rid in surviving_ids:
+            final_lines.append(line_str)
+        else:
+            region_name = line_str.split()[1]
+            print(f"[WARNING] {region_name} (id {rid}) lost during smoothing/masking. dropping from lut.")
+            dropped_count += 1
+            
+    # write the perfectly clean file
+    with open(out_lut, 'w') as f:
+        f.write("\n".join(final_lines))
+
+    print(f"final polished atlas saved to: {out_dir}")
+    print(f"saved {len(final_lines)} regions ({dropped_count} empty regions dropped).")
+    
+    # cleanup intermediate Workbench files to save space
+    for temp_file in [labeled_nii, lh_gii, rh_gii]:
+        if os.path.exists(temp_file):
+            os.remove(temp_file)
+
+def qc_custom_cortical_atlas(atlas_dir, atlasname='atlas'):
+    """
+    generates a quality control report for a custom cortical atlas.
+    
+    reads the generated vertex map and lookup table, counts the vertices for each region, 
+    saves a summary text file, and generates individual static plots for every region 
+    to help identify mapping dropouts or anatomical bleed.
+
+    parameters
+    ----------
+    atlas_dir : str
+        absolute path to the custom atlas directory containing the .csv and .txt files.
+    atlasname : str, optional
+        prefix name of the files to check. default is 'atlas'.
+    """
+    
+    csv_path = os.path.join(atlas_dir, f"{atlasname}.csv")
+    lut_path = os.path.join(atlas_dir, f"{atlasname}.txt")
+    qc_dir = os.path.join(atlas_dir, "qc_report")
+    
+    os.makedirs(qc_dir, exist_ok=True)
+    
+    # load the mapped data and the lookup table
+    labels = np.loadtxt(csv_path).astype(int)
+    
+    regions = {}
+    with open(lut_path, 'r') as f:
+        for line in f:
+            parts = line.strip().split()
+            if len(parts) >= 2:
+                regions[int(parts[0])] = parts[1]
+                
+    print(f"starting qc for {len(regions)} regions...\n")
+    
+    report_path = os.path.join(qc_dir, "_vertex_counts.txt")
+    
+    with open(report_path, 'w') as f_out:
+        f_out.write("region_name\tid\tvertex_count\n")
+        f_out.write("-" * 40 + "\n")
+        
+        for rid, name in regions.items():
+            count = np.sum(labels == rid)
+            f_out.write(f"{name}\t{rid}\t{count}\n")
+            
+            print(f"[{name}] id: {rid} | vertices: {count}")
+            
+            if count == 0:
+                print(f"[WARNING] {name} is empty! skipping plot.")
+                continue
+            
+            plot_file = os.path.join(qc_dir, f"{rid:03d}_{name}.png")
+            
+            try:
+                plot_cortical(
+                    data={name: 1},
+                    custom_atlas_path=atlas_dir,
+                    cmap='binary',vminmax=[0, 1],
+                    export_path=plot_file
+                )
+            except Exception as e:
+                print(f"  -> failed to plot {name}: {e}")
+                
+    print(f"\nqc complete! check the '{qc_dir}' folder for the report and images.")
+
+
+### SUBCORTICAL
+
+def build_subcortical_atlas(nii_path, labels_dict, out_dir, include_list=None, exclude_list=None,
+                            smooth_i=15, smooth_f=0.6):
+    """
+    extracts 3D subcortical meshes from a volumetric nifti atlas.
+
+    uses the marching cubes algorithm to generate 3D surface meshes for specific 
+    regions, applies laplacian smoothing to remove voxel artifacts, and saves them as .vtk files.
+
+    parameters
+    ----------
+    nii_path : str
+        absolute path to the 3D nifti volume.
+    labels_dict : dict
+        dictionary mapping integer region IDs to string names (e.g., {1: 'thalamus_l'}).
+    out_dir : str
+        directory where the .vtk mesh files will be saved.
+    include_list : list of str, optional
+        keywords of regions to strictly include. all other regions are ignored.
+    exclude_list : list of str, optional
+        keywords of regions to strictly exclude. all other regions are kept.
+    smooth_i : int, optional
+        number of iterations for laplacian mesh smoothing. default is 15.
+    smooth_f : float, optional
+        relaxation factor for laplacian mesh smoothing (0.0 to 1.0). default is 0.6.
+
+    raises
+    ------
+    ValueError
+        if both include_list and exclude_list are provided.
+    """
+    if include_list and exclude_list:
+        raise ValueError("please provide either 'include_list' or 'exclude_list', not both.")
+        
+    os.makedirs(out_dir, exist_ok=True)
+    
+    # apply the include/exclude filters to the provided dictionary
+    targets = {}
+    for rid, name in labels_dict.items():
+        if include_list:
+            if not any(inc in name for inc in include_list):
+                continue
+        elif exclude_list:
+            if any(exc in name for exc in exclude_list):
+                continue
+                
+        targets[rid] = name
+                    
+    print(f"filtered down to {len(targets)} subcortical regions to extract.")
+
+    # load the nifti volume and its affine matrix
+    img = nib.load(nii_path)
+    data = img.get_fdata()
+    affine = img.affine
+
+    # loop through targets, extract meshes, and save
+    for rid, name in targets.items():
+        # create a binary mask for just this region
+        mask = (data == rid).astype(np.uint8)
+        
+        # skip if empty
+        if np.sum(mask) == 0:
+            print(f"[WARNING] {name} is empty in the volume!")
+            continue
+
+        print(f"extracting: {name} (id {rid})...")
+        
+        # run marching cubes to get raw vertices and faces
+        verts, faces, normals, values = measure.marching_cubes(mask, level=0.5)
+
+        # apply the nifti affine matrix cleanly using nibabel
+        verts_mni = nib.affines.apply_affine(affine, verts)
+
+        # format faces for pyvista: [n_points, p1, p2, p3, n_points, p1, p2, p3...]
+        faces_pv = np.column_stack((np.full(len(faces), 3), faces)).flatten()
+        
+        # create the 3d pyvista mesh
+        mesh = pv.PolyData(verts_mni, faces_pv)
+        
+        # apply laplacian smoothing to melt away the blocky voxel edges
+        mesh = mesh.smooth(n_iter=smooth_i, relaxation_factor=smooth_f)
+        mesh.compute_normals(inplace=True)
+
+        # we remove super small structures which would not be visible
+        if mesh.n_points < 4 or abs(mesh.volume) < 0.01:
+            print(f"[WARNING] {name} is too small to form a 3D mesh (volume: {abs(mesh.volume):.4f} mm³). dropping from atlas.")
+            continue
+        
+        # save as a vtk file
+        out_file = os.path.join(out_dir, f"{name}.vtk")
+        mesh.save(out_file)
+
+    print(f"\nsubcortical atlas successfully saved to: {out_dir}")
+
+def qc_custom_subcortical_atlas(atlas_dir):
+    """
+    generates a quality control report for a custom subcortical atlas.
+    
+    reads the generated .vtk meshes, calculates their geometric properties 
+    (vertices, faces, volume), saves a summary text file, and generates 
+    individual static plots for every region to help identify corrupt meshes 
+    or anatomical artifacts.
+
+    parameters
+    ----------
+    atlas_dir : str
+        absolute path to the custom atlas directory containing the .vtk files.
+    """
+    
+    qc_dir = os.path.join(atlas_dir, "qc_report")
+    os.makedirs(qc_dir, exist_ok=True)
+    
+    # find all vtk files in the atlas directory
+    vtk_files = glob.glob(os.path.join(atlas_dir, "*.vtk"))
+    
+    if not vtk_files:
+        print(f"no .vtk files found in {atlas_dir}. cannot run qc.")
+        return
+        
+    print(f"starting qc for {len(vtk_files)} subcortical meshes...\n")
+    
+    report_path = os.path.join(qc_dir, "_mesh_properties.txt")
+    
+    with open(report_path, 'w') as f_out:
+        # header for our text report
+        f_out.write("region_name\tvertices\tfaces\tvolume_mm3\n")
+        f_out.write("-" * 55 + "\n")
+        
+        for vtk_path in sorted(vtk_files):
+            filename = os.path.basename(vtk_path)
+            region_name = os.path.splitext(filename)[0]
+            
+            # read mesh to extract physical properties
+            try:
+                mesh = pv.read(vtk_path)
+                n_verts = mesh.n_points
+                n_faces = mesh.n_cells
+                volume = mesh.volume
+            except Exception as e:
+                print(f"  -> error reading {filename}: {e}")
+                f_out.write(f"{region_name}\tERROR\tERROR\tERROR\n")
+                continue
+                
+            f_out.write(f"{region_name}\t{n_verts}\t{n_faces}\t{volume:.2f}\n")
+            print(f"[{region_name}] vertices: {n_verts} | volume: {volume:.1f} mm³")
+            
+            # check for empty or severely corrupted meshes
+            if n_verts == 0:
+                print(f"[WARNING] {region_name} mesh is empty! skipping plot.")
+                continue
+            
+            plot_file = os.path.join(qc_dir, f"{region_name}.png")
+            
+            try:
+                plot_subcortical(
+                    data={region_name: 1},
+                    custom_atlas_path=atlas_dir,
+                    cmap='binary', vminmax=[0, 1],
+                    nan_alpha=0.2,
+                    export_path=plot_file
+                )
+            except Exception as e:
+                print(f"  -> failed to plot {region_name}: {e}")
+                
+    print(f"\nqc complete! check the '{qc_dir}' folder for the report and images.")

{yabplot-0.1.4 → yabplot-0.2.0}/yabplot/data/__init__.py

@@ -70,6 +70,52 @@ def get_available_resources(category=None):
         
     return all_resources
 
+def get_surface_paths(name, category):
+    """
+    Fetches and returns the paths to the Left and Right hemisphere files 
+    for a given surface resource (meshes or labels).
+    
+    Parameters
+    ----------
+    name : str
+        Name of the resource (e.g., 'midthickness', 'nomedialwall').
+    category : str
+        Must be 'bmesh' or 'label'.
+        
+    Returns
+    -------
+    tuple
+        (lh_path, rh_path) containing absolute paths to the files.
+    """
+    if category not in ['bmesh', 'label']:
+        raise ValueError("Category must be 'bmesh' or 'label' to fetch surface paths.")
+        
+    # Download/unpack the zip and get the folder path
+    directory = _resolve_resource_path(name, category)
+    
+    lh_path = None
+    rh_path = None
+    
+    # Traverse the unzipped directory to find L and R files
+    for root, dirs, files in os.walk(directory):
+        # Ignore hidden folders like .git or __MACOSX
+        dirs[:] = [d for d in dirs if not d.startswith(('.', '__'))]
+        for file in files:
+            # Ignore hidden files
+            if file.startswith('.'): 
+                continue
+            
+            # Robust checking for Left and Right hemisphere indicators
+            if '.L.' in file or '_L_' in file or 'hemi-L' in file:
+                lh_path = os.path.join(root, file)
+            elif '.R.' in file or '_R_' in file or 'hemi-R' in file:
+                rh_path = os.path.join(root, file)
+                
+    if not lh_path or not rh_path:
+        raise FileNotFoundError(f"Could not locate both Left and Right hemisphere files for '{name}' in {directory}")
+        
+    return lh_path, rh_path
+
 def get_atlas_regions(atlas, category, custom_atlas_path=None):
     """
     Returns the list of region names for a given atlas in the specific order 
@@ -191,7 +237,8 @@ def _resolve_resource_path(name, category, custom_path=None):
             'cortical': 'Cortical parcellations (vertices)',
             'subcortical': 'Subcortical segmentations (volumes)', 
             'tracts': 'White matter bundles (tracts)',
-            'bmesh': 'Brain meshes'
+            'bmesh': 'Brain meshes',
+            'label': 'Surface labels'
         }.get(category, category)
         
         raise ValueError(

{yabplot-0.1.4 → yabplot-0.2.0}/yabplot/data/registry.txt

@@ -5,11 +5,14 @@ cortical-schaefer_200.zip sha256:065ee05afa1881a8884bdecee25a062ddd5fd6283bfeaab
 cortical-schaefer_300.zip sha256:5430c66eaef58f008b9e20dd5c59c670c7f7154b02f4b310dda97250331b6eed https://osf.io/9djtr/download
 cortical-schaefer_400.zip sha256:ae2b7011919d49e9930ee5aed1b19731180427f07f0d1c4497130dd9cd5e878d https://osf.io/pzmc5/download
 cortical-schaefer_1000.zip sha256:a10448f101a874499d41bc62508c3af29120634955f48beb282ece9a4cc2bb0e https://osf.io/j9ygz/download
+cortical-aal3.zip sha256:925e475e099b127925e20e6ec4d179b1a58971f2bc32b2a61f56a479f3e8d4fb https://osf.io/z9jxh/download
 subcortical-aseg.zip sha256:a901a7fc6a39f9bdaf2ef2bafbcde1fbc085b225d99e6730c727650d9be047d5 https://osf.io/5cs7y/download
 subcortical-brainnetome_sc.zip sha256:8301fdf6af109af52a2cf9b06d15486345d457b69cb86169ed38332a34a681c0 https://osf.io/2fsg5/download
 subcortical-jhu.zip sha256:b0ca292589a9f041851dba8159bb605a4657323e4305ba1570a304944b28d0de https://osf.io/x5fhg/download
 subcortical-musus100_dbn.zip sha256:1d865832a35570a8c67f79d5049b58c548d25cf4fe1853164c384193b6712e40 https://osf.io/eutmb/download
 subcortical-tian2020_sc.zip sha256:8b5caf8bf0cdcf8e259a3532fbcb232f8746d68fc734ca9806d10e70cf8707a3 https://osf.io/jrvgp/download
+subcortical-aal3.zip sha256:48abe400656d913cc459ee8766e373cc5eabbeb9e4f770aa7396da3d4a0ab3ca https://osf.io/39ebh/download
+subcortical-aal3_nocer.zip sha256:b87de55861cdd18ddb78934964b0e0855f770560bdc878570fcbb8f27fefb674 https://osf.io/7jdxz/download
 tracts-hcp1065_medium.zip sha256:366bb100074cf7b1e55586e5468653f0c342e42cfdd91dca6d99b6fde82f06ff https://osf.io/kjf8e/download
 tracts-hcp1065_small.zip sha256:020f23059c3a20ee0dda8ad12cd3df99b9fe5d3b37e7a6b9ae34b8a52b4b4346 https://osf.io/ynpa5/download
 tracts-hcp1065_tiny.zip sha256:54380d82f5cd234029c6fc011910e00f0ad859fdb6c22c6aaa6452d055449ae9 https://osf.io/jzk7p/download
@@ -17,5 +20,10 @@ tracts-xtract_large.zip sha256:e2d59e9f90b024018788af87e389f93b2fa9ac21360460196
 tracts-xtract_medium.zip sha256:f095028d3dfc0f974ebef1feffe4006b5bac1366325a784ea2301c56f583b1e7 https://osf.io/7tbjg/download
 tracts-xtract_small.zip sha256:9d3fe2c57acb87e8d13eb40a49a6c2c354dbe1a020122b693e9bf713e57cad5b https://osf.io/bmn3a/download
 tracts-xtract_tiny.zip sha256:469f9ed8ed5ceb7f8e17c9a0a92f1491d540814f832ef56441a7539532111f41 https://osf.io/a73x2/download
-bmesh-conte69.zip sha256:5ba9ffc89ae7f640590a80fc188d277b1b49a34a0bd99c0c9e5cfb52fc963cac https://osf.io/h4ugr/download
-bmesh-fsaverage.zip sha256:bccec9e3fc10ffc9d1cbdb6ad2b0ffd81c93ca0fa8d26fc530d9b4d58dfcd7a0 https://osf.io/sq7am/download
+bmesh-inflated.zip sha256:ba72f9e75f16fe767f6bbcec5c98381f6a20b2f5e2092505b4692844a1686461 https://osf.io/kfzjg/download
+bmesh-midthickness.zip sha256:ef8209853e1dac8804a60b5cde0b653ef2f6c77b6c7536f7acaa69a46dbb06c0 https://osf.io/xaktf/download
+bmesh-pial.zip sha256:5e36ba7883dd2a88485fc45c9166ed48e22db607d45655242961242b51f9f126 https://osf.io/knpg8/download
+bmesh-swm.zip sha256:1a516c070cb63557751d841d5cf75772660872b89ec749ee19c23298d77fa807 https://osf.io/hpbc9/download
+bmesh-very_inflated.zip sha256:8c33a00c718a47f0af118ce2c5804a2adf13d79be05c4665ca26582e3e8dd977 https://osf.io/xp9jr/download
+bmesh-white.zip sha256:b885ac1a4dcdf9e241a97e8d3ca59d7b1c86d8a3ebe17df512993bc5c1c0354a https://osf.io/wfc5t/download
+label-nomedialwall.zip sha256:03bd589b151814a1fc5e48236a78decf1a51791f04c3f4a521d2ed4fb214317b https://osf.io/2rgmc/download

{yabplot-0.1.4 → yabplot-0.2.0}/yabplot/plotting.py

@@ -14,7 +14,8 @@ from .data import (
 from .utils import (
     load_gii, load_gii2pv, prep_data, 
     generate_distinct_colors, parse_lut, map_values_to_surface, 
-    lines_from_streamlines, make_cortical_mesh
+    get_puzzle_pieces, apply_internal_blur, apply_dilation,
+    get_smooth_mask, lines_from_streamlines, make_cortical_mesh
 )
 
 from .scene import (
@@ -26,8 +27,8 @@ from .scene import (
 # --- plot for cortical surface ---
 
 def plot_cortical(data=None, atlas=None, custom_atlas_path=None, views=None, layout=None, 
-                  figsize=(1000, 600), cmap='RdYlBu_r', vminmax=[None, None], 
-                  nan_color=(1.0, 1.0, 1.0), style='default', zoom=1.2, 
+                  bmesh_type='midthickness', figsize=(1000, 600), cmap='coolwarm', vminmax=[None, None], 
+                  nan_color=(1.0, 1.0, 1.0), style='default', zoom=1.2, proc_vertices=None,
                   display_type='static', export_path=None):
     """
     Visualize data on the cortical surface using a specified atlas.
@@ -54,6 +55,9 @@ def plot_cortical(data=None, atlas=None, custom_atlas_path=None, views=None, lay
         or a dictionary of camera configurations. Defaults to all views.
     layout : tuple (rows, cols), optional
         Grid layout for subplots. If None, automatically calculated based on the number of views.
+    bmesh_type : str
+        Name of the background context brain mesh (e.g., 'midthickness', 'white', 'swm', etc). 
+        Default is 'midthickness'.
     figsize : tuple (width, height), optional
         Window size in pixels. Default is (1000, 600).
     cmap : str or matplotlib.colors.Colormap, optional
@@ -67,6 +71,11 @@ def plot_cortical(data=None, atlas=None, custom_atlas_path=None, views=None, lay
         Lighting preset ('default', 'matte', 'glossy', 'sculpted', 'flat').
     zoom : float, optional
         Camera zoom level. >1.0 zooms in, <1.0 zooms out. Default is 1.2.
+    proc_vertices : str or None, optional
+        Whether to process the vertices edges according to geometry of bmesh.
+        Set to None to not perform (default).
+        'blur': Applies simple blurring between different color vertices (low performance impact).
+        'sharp': Applies sharpening of the resolution of different color vertices (high performance impact).
     display_type : {'static', 'interactive', 'none'}, optional
         'static': Returns a static image (good for notebooks).
         'interactive': Opens an interactive viewer.
@@ -80,19 +89,18 @@ def plot_cortical(data=None, atlas=None, custom_atlas_path=None, views=None, lay
         The plotter instance used for rendering.
     """
 
-    # defaults
+    # atlas and categorical check
     if atlas is None and custom_atlas_path is None:
         atlas = 'aparc'
+    is_cat = (data is None)
 
     # load brain mesh
-    bmesh_path = _resolve_resource_path('conte69', 'bmesh')
-    lh_v, lh_f = load_gii(os.path.join(bmesh_path, 'conte69.lh.gii'))
-    rh_v, rh_f = load_gii(os.path.join(bmesh_path, 'conte69.rh.gii'))
+    bmesh_path = _resolve_resource_path(bmesh_type, 'bmesh')
+    lh_v, lh_f = load_gii(os.path.join(bmesh_path, f'fs_LR.32k.L.{bmesh_type}.surf.gii'))
+    rh_v, rh_f = load_gii(os.path.join(bmesh_path, f'fs_LR.32k.R.{bmesh_type}.surf.gii'))
 
-    # resolve atlas path (either download or custom directory)
+    # resolve atlas
     atlas_dir = _resolve_resource_path(atlas, 'cortical', custom_path=custom_atlas_path)
-    
-    # locate files
     check_name = None if custom_atlas_path else atlas
     csv_path, lut_path = _find_cortical_files(atlas_dir, strict_name=check_name)
 
@@ -102,28 +110,43 @@ def plot_cortical(data=None, atlas=None, custom_atlas_path=None, views=None, lay
 
     # map data
     all_vals = map_values_to_surface(data, tar_labels, lut_ids, lut_names)
-    lh_vals = all_vals[:len(lh_v)]
-    rh_vals = all_vals[len(lh_v):]
+    lh_vals_raw = all_vals[:len(lh_v)]
+    rh_vals_raw = all_vals[len(lh_v):]
+
+    # vertices processing
+    results = []
+    for v, f, raw in [(lh_v, lh_f, lh_vals_raw), (rh_v, rh_f, rh_vals_raw)]:
+        if proc_vertices == 'sharp':
+            # razor-sharp puzzle mode
+            base, pieces = get_puzzle_pieces(v, f, raw)
+            results.append((base, pieces))
+        else:
+            # single clipper mode (blur or none)
+            v_proc = apply_internal_blur(f, raw, iterations=3, weight=0.3) if proc_vertices == 'blur' else raw
+            dilated = apply_dilation(f, v_proc, iterations=4)
+            o_guide = get_smooth_mask(f, np.where(np.isnan(raw), 0.0, 1.0), iterations=4)
+            
+            mesh = make_cortical_mesh(v, f, dilated)
+            mesh['Slice_Mask'] = o_guide
+            data_p = mesh.clip_scalar(scalars='Slice_Mask', value=0.5, invert=False)
+            base_p = mesh.clip_scalar(scalars='Slice_Mask', value=0.5, invert=True)
+            if base_p.n_points > 0: base_p['Data'] = np.full(base_p.n_points, np.nan)
+            results.append((base_p, [data_p]))
+    (lh_base, lh_parts), (rh_base, rh_parts) = results
 
     # setup colors
-    is_categorical = (data is None)
     n_colors = 256
-    if is_categorical:
+    if is_cat:
         _lut_colors = lut_colors.copy()
-        _lut_colors[0] = nan_color
+        _lut_colors[0] = nan_color # TODO: check nancolor
         cmap = ListedColormap(_lut_colors)
         n_colors = len(_lut_colors)
         vmin, vmax = 0, max_id
     else:
-        if cmap is None: cmap = 'RdYlBu_r'
         vmin = vminmax[0] if vminmax[0] is not None else np.nanmin(all_vals)
         vmax = vminmax[1] if vminmax[1] is not None else np.nanmax(all_vals)
 
-    # create meshes
-    lh_mesh = make_cortical_mesh(lh_v, lh_f, lh_vals)
-    rh_mesh = make_cortical_mesh(rh_v, rh_f, rh_vals)
-
-    # setup plotter
+    # plotter setup
     sel_views = get_view_configs(views)
     plotter, ncols, nrows = setup_plotter(sel_views, layout, figsize, display_type)
     shading_params = get_shading_preset(style)
@@ -132,46 +155,46 @@ def plot_cortical(data=None, atlas=None, custom_atlas_path=None, views=None, lay
     for i, (name, cfg) in enumerate(sel_views.items()):
         plotter.subplot(i // ncols, i % ncols)
         
-        meshes = []
-        if cfg['side'] in ['L', 'both']: meshes.append(lh_mesh)
-        if cfg['side'] in ['R', 'both']: meshes.append(rh_mesh)
-
-        for mesh in meshes:     
+        view_bases = []
+        view_pieces = []
+        if cfg['side'] in ['L', 'both']:
+            if lh_base.n_points > 0: view_bases.append(lh_base)
+            view_pieces.extend(lh_parts)
+        if cfg['side'] in ['R', 'both']:
+            if rh_base.n_points > 0: view_bases.append(rh_base)
+            view_pieces.extend(rh_parts)
+
+        # brain meshes
+        for b_mesh in view_bases:     
+            plotter.add_mesh(b_mesh, color=nan_color, smooth_shading=True, **shading_params)
+
+        # data vertices
+        for p_mesh in view_pieces:
+            if p_mesh.n_points == 0: continue
+            interp = (proc_vertices == 'blur') # only blur mode uses interpolation
+            
             actor = plotter.add_mesh(
-                mesh,
-                scalars='Data', 
-                cmap=cmap, 
-                clim=(vmin, vmax), 
-                n_colors=n_colors,
-                nan_color=nan_color, 
-                show_scalar_bar=False,
-                rgb=False, 
-                smooth_shading=True,
-                show_edges=False,
-                interpolate_before_map=False,
-                **shading_params
-            )
+                p_mesh, scalars='Data', cmap=cmap, clim=(vmin, vmax), 
+                n_colors=n_colors, nan_color=nan_color, show_scalar_bar=False,
+                smooth_shading=True, interpolate_before_map=interp, **shading_params
+            ) # rgb=False, show_edges=False, interpolate_before_map=False,
             if scalar_bar_mapper is None: scalar_bar_mapper = actor.mapper
 
         set_camera(plotter, cfg, zoom=zoom)
         plotter.hide_axes()
-
-    if not is_categorical and scalar_bar_mapper:
+        
+    if not is_cat and scalar_bar_mapper:
         plotter.subplot(nrows - 1, 0)
-        plotter.add_scalar_bar(mapper=scalar_bar_mapper, title='', n_labels=2,
-                               vertical=False, position_x=0.3, position_y=0.25, 
-                               height=0.5, width=0.4,color='black', 
-                               label_font_size=20)
+        plotter.add_scalar_bar(mapper=scalar_bar_mapper, vertical=False, position_x=0.3, position_y=0.25, height=0.5, width=0.4)
     
     return finalize_plot(plotter, export_path, display_type)
 
 
-
 # --- plot for subcortical structures ---
 
 def plot_subcortical(data=None, atlas=None, custom_atlas_path=None, views=None, layout=None, 
                      figsize=(1000, 600), cmap='coolwarm', vminmax=[None, None], nan_color='#cccccc', 
-                     nan_alpha=1.0, legend=False, style='default', bmesh_type='conte69', 
+                     nan_alpha=1.0, legend=False, style='default', bmesh_type='midthickness', 
                      bmesh_alpha=0.1, bmesh_color='lightgray', zoom=1.2, display_type='static', 
                      export_path=None, custom_atlas_proc=dict(smooth_i=15, smooth_f=0.6)):
     """
@@ -213,8 +236,8 @@ def plot_subcortical(data=None, atlas=None, custom_atlas_path=None, views=None,
     style : str, optional
         Lighting preset ('default', 'matte', 'glossy', 'sculpted', 'flat').
     bmesh_type : str or None, optional
-        Name of the background context brain mesh (e.g., 'conte69'). 
-        Set to None to hide the context brain.
+        Name of the background context brain mesh (e.g., 'midthickness', 'white', 'swm', etc). 
+        Set to None to hide the context brain. Default is 'midthickness'.
     bmesh_alpha : float, optional
         Opacity of the context brain mesh. Default is 0.1.
     bmesh_color : str, optional
@@ -246,8 +269,8 @@ def plot_subcortical(data=None, atlas=None, custom_atlas_path=None, views=None,
     bmesh = {}
     if bmesh_type:
         bmesh_path = _resolve_resource_path(bmesh_type, 'bmesh')
-        for h in ['lh', 'rh']:
-            fpath = os.path.join(bmesh_path, f'{bmesh_type}.{h}.gii')
+        for h in ['L', 'R']:
+            fpath = os.path.join(bmesh_path, f'fs_LR.32k.{h}.{bmesh_type}.surf.gii')
             if os.path.exists(fpath):
                 bmesh[h] = load_gii2pv(fpath)
     
@@ -371,7 +394,7 @@ def clear_tract_cache():
 def plot_tracts(data=None, atlas=None, custom_atlas_path=None, views=None, layout=None, 
                 figsize=(1000, 800), cmap='coolwarm', alpha=1.0, vminmax=[None, None], 
                 nan_color='#BDBDBD', nan_alpha=1.0, legend=False, style='default',
-                bmesh_type='conte69', bmesh_alpha=0.2, bmesh_color='lightgray', 
+                bmesh_type='midthickness', bmesh_alpha=0.2, bmesh_color='lightgray', 
                 zoom=1.2, orientation_coloring=False, display_type='static', 
                 tract_kwargs=dict(render_lines_as_tubes=True, line_width=1.2),
                 export_path=None):
@@ -417,8 +440,8 @@ def plot_tracts(data=None, atlas=None, custom_atlas_path=None, views=None, layou
     style : str, optional
         Lighting preset ('default', 'matte', 'glossy', 'sculpted', 'flat').
     bmesh_type : str or None, optional
-        Name of the background context brain mesh (e.g., 'conte69'). 
-        Set to None to hide the context brain.
+        Name of the background context brain mesh (e.g., 'midthickness', 'white', 'swm', etc). 
+        Set to None to hide the context brain. Default is 'midthickness'.
     bmesh_alpha : float, optional
         Opacity of the context brain mesh. Default is 0.2.
     bmesh_color : str, optional
@@ -472,8 +495,8 @@ def plot_tracts(data=None, atlas=None, custom_atlas_path=None, views=None, layou
     bmesh = {}
     if bmesh_type:
         bmesh_path = _resolve_resource_path(bmesh_type, 'bmesh')
-        for h in ['lh', 'rh']:
-            fpath = os.path.join(bmesh_path, f'{bmesh_type}.{h}.gii')
+        for h in ['L', 'R']:
+            fpath = os.path.join(bmesh_path, f'fs_LR.32k.{h}.{bmesh_type}.surf.gii')
             if os.path.exists(fpath):
                 bmesh[h] = load_gii2pv(fpath)
 

{yabplot-0.1.4 → yabplot-0.2.0}/yabplot/scene.py

@@ -91,7 +91,7 @@ def setup_plotter(sel_views, layout, figsize, display_type, needs_bottom_row=Tru
         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)
+                         off_screen=(display_type=='object'), window_size=figsize, border=False)
     plotter.set_background('white')
     return plotter, ncols, nrows
         
@@ -101,7 +101,7 @@ def add_context_to_view(plotter, bmesh, view_side, alpha, color, **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
+        if (view_side == 'L' and h == 'L') or (view_side == 'R' and h == 'R'): continue
         plotter.add_mesh(mesh, color=color, opacity=alpha, 
                          smooth_shading=True, show_edges=False, 
                          **kwargs)
@@ -115,10 +115,19 @@ def set_camera(plotter, view_cfg, zoom=1.0, distance=200):
     plotter.camera.zoom(zoom)
 
 def finalize_plot(plotter, export_path, display_type):
-    if export_path: plotter.screenshot(export_path, transparent_background=True)
+    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
-
+    if display_type == 'static': 
+        out = plotter.show(jupyter_backend='static')
+        plotter.close()
+    elif display_type == 'interactive': 
+        out = plotter.show(jupyter_backend='trame')
+    elif display_type == 'object': 
+        plotter.render()
+        return plotter
+    else:
+        plotter.close()
+        out = None
+    
+    return out

{yabplot-0.1.4 → yabplot-0.2.0}/yabplot/utils.py

@@ -3,6 +3,7 @@ import numpy as np
 import pandas as pd
 import nibabel as nib
 import pyvista as pv
+import scipy.sparse as sp
 import matplotlib.pyplot as plt
 from importlib.resources import files
 
@@ -143,6 +144,93 @@ def map_values_to_surface(data, target_labels, lut_ids, dense_lut_names):
     lookup_table[valid_ids] = source_values
     return lookup_table[target_labels]
 
+def get_adj(faces, n_v):
+    """build adjacency matrix from faces."""
+    row, col = [], []
+    for tri in faces:
+        row.extend([tri[0], tri[1], tri[2], tri[0], tri[1], tri[2]])
+        col.extend([tri[1], tri[2], tri[0], tri[2], tri[0], tri[1]])
+    adj = sp.csc_matrix((np.ones_like(row), (row, col)), shape=(n_v, n_v))
+    adj.data = np.ones_like(adj.data)
+    return adj
+
+def get_smooth_mask(faces, data, iterations=4):
+    """blur binary mask for guide of geometric slicing."""
+    n_v = len(data)
+    mask = data.astype(np.float64)
+    adj = get_adj(faces, n_v)
+    deg = np.array(adj.sum(axis=1)).flatten()
+    deg[deg == 0] = 1.0 
+    for _ in range(iterations):
+        mask = (mask + (adj.dot(mask) / deg)) / 2.0
+    return mask
+
+def apply_internal_blur(faces, data, iterations=1, weight=0.2):
+    """blur data only on borders where different regions touch."""
+    data_out = np.copy(data)
+    n_v = len(data)
+    adj = get_adj(faces, n_v)
+    rows, cols = adj.nonzero()
+    valid = ~np.isnan(data_out)
+    diff = valid[rows] & valid[cols] & ~np.isclose(data_out[rows], data_out[cols], atol=1e-5)
+    b_verts = np.unique(rows[diff])
+    
+    if len(b_verts) == 0: return data_out
+
+    for _ in range(iterations):
+        temp = np.nan_to_num(data_out, nan=0.0)
+        v_counts = adj.dot(valid.astype(float))
+        v_counts[v_counts == 0] = 1.0
+        n_mean = adj.dot(temp) / v_counts
+        data_out[b_verts] = (1 - weight) * data_out[b_verts] + weight * n_mean[b_verts]
+    return data_out
+
+def apply_dilation(faces, data, iterations=4):
+    """push values into NaN space to keep geometric cut pure."""
+    data_out = np.copy(data)
+    n_v = len(data)
+    adj = get_adj(faces, n_v)
+    for _ in range(iterations):
+        nan_m = np.isnan(data_out)
+        temp = np.nan_to_num(data_out, nan=0.0)
+        v_counts = adj.dot((~nan_m).astype(float))
+        s_neighbors = adj.dot(temp)
+        u_mask = nan_m & (v_counts > 0)
+        data_out[u_mask] = s_neighbors[u_mask] / v_counts[u_mask]
+    return data_out
+
+def get_puzzle_pieces(v, f, raw_vals):
+    """carve out geometric pieces with slight overlap to prevent gaps."""
+    pieces = []
+    valid_mask = ~np.isnan(raw_vals) & (raw_vals != 0.0)
+    u_vals = np.unique(raw_vals[valid_mask])
+    master = make_cortical_mesh(v, f, np.zeros_like(raw_vals))
+
+    for val in u_vals:
+        r_mask = np.where(raw_vals == val, 1.0, 0.0)
+        s_mask = get_smooth_mask(f, r_mask, iterations=4)
+        temp = master.copy()
+        temp['Slice_Mask'] = s_mask
+        # reduce search space
+        patch = temp.threshold(0.01, scalars='Slice_Mask')
+        if patch.n_points > 0:
+            # use 0.48 (slightly expanded) for pieces to seal cracks
+            piece = patch.clip_scalar(scalars='Slice_Mask', value=0.48, invert=False)
+            if piece.n_points > 0:
+                piece['Data'] = np.full(piece.n_points, val)
+                pieces.append(piece)
+    
+    # slice base brain
+    all_mask = np.where(valid_mask, 1.0, 0.0)
+    s_all = get_smooth_mask(f, all_mask, iterations=4)
+    master['Slice_Mask'] = s_all
+    # use 0.52 (slightly contracted) for the hole to ensure colored pieces cover the edge
+    base_p = master.clip_scalar(scalars='Slice_Mask', value=0.52, invert=True)
+    if base_p.n_points > 0:
+        base_p['Data'] = np.full(base_p.n_points, np.nan)
+    
+    return base_p, pieces
+
 def lines_from_streamlines(streamlines):
     if len(streamlines) == 0: return np.array([]), np.array([]), np.array([])
     
@@ -155,7 +243,7 @@ def lines_from_streamlines(streamlines):
         cells.append(np.hstack([[length], np.arange(offset, offset + length)]))
     lines = np.hstack(cells)
     
-    # Calculate tangents
+    # calculate tangents
     tangents = []
     for s in streamlines:
         if len(s) < 2: 

yabplot-0.2.0/yabplot/wrappers.py

@@ -0,0 +1,36 @@
+import subprocess
+import shutil
+import os
+
+def check_workbench():
+    """
+    Checks if Connectome Workbench (wb_command) is installed and available in PATH.
+    
+    Raises
+    ------
+    EnvironmentError
+        If wb_command is not found, providing instructions for installation.
+    """
+    if shutil.which('wb_command') is None:
+        raise EnvironmentError(
+            "Connectome Workbench ('wb_command') was not found in your system PATH.\n"
+            "This is required for volume-to-surface projection (necessary for creating a custom cortical atlas).\n"
+            "Please download it from: https://humanconnectome.org/software/get-connectome-workbench\n"
+            "After installing, ensure the 'bin' folder is added to your PATH environment variable."
+        )
+
+def run_wb_import(input_nii, label_list, output_nii):
+    """Wrapper for wb_command -volume-label-import"""
+    check_workbench()
+    cmd = ["wb_command", "-volume-label-import", input_nii, label_list, output_nii]
+    subprocess.run(cmd, check=True)
+
+def run_wb_projection(input_nii, midthickness, output_gii, white, pial):
+    """Wrapper for wb_command -volume-label-to-surface-mapping (ribbon-constrained)"""
+    check_workbench()
+    cmd = [
+        "wb_command", "-volume-label-to-surface-mapping",
+        input_nii, midthickness, output_gii,
+        "-ribbon-constrained", white, pial
+    ]
+    subprocess.run(cmd, check=True)

{yabplot-0.1.4 → yabplot-0.2.0/yabplot.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: yabplot
-Version: 0.1.4
+Version: 0.2.0
 Summary: yet another brain plot
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -55,6 +55,9 @@ pip install yabplot --upgrade # to update
 
 dependencies: python 3.11 with ipywidgets, nibabel, pandas, pooch, pyvista, scikit-image, trame, trame-vtk, trame-vuetify
 
+(Connectome Workbench (`wb_command`) is a requirement to create custom cortical atlases unless you plan to only use pre-loaded atlases; see more in docs)
+
+
 ## quick start
 
 please refer to the [documentation](https://teanijarv.github.io/yabplot/) for more comprehensive guides.
@@ -63,32 +66,41 @@ please refer to the [documentation](https://teanijarv.github.io/yabplot/) for mo
 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')
+# check that you have the latest version
+print(yab.__version__)
+
+# see available atlases and brain meshes
+print(yab.get_available_resources())
+
+# see the region names for a specific atlas
+print(yab.get_atlas_regions(atlas='aseg', category='subcortical'))
+
+# cortical surfaces
+atlas = 'aparc'
+dmap1 = {'L_lateraloccipital': 0.265, 'L_postcentral': 0.086, ...}
+dmap2 = {'L_fusiform': 0.218, 'L_supramarginal': 0.119, ...}
+yab.plot_cortical(data=dmap1, atlas=atlas, vminmax=[-0.1, 0.3], 
+                  bmesh_type='midthickness', views=['left_lateral', 'left_medial'],
+                  figsize=(600, 300), cmap='viridis', proc_vertices='sharp')
+yab.plot_cortical(data=dmap2, atlas=atlas, vminmax=[-0.1, 0.3], 
+                  bmesh_type='swm', views=['left_lateral', 'left_medial'],
+                  figsize=(1200, 600), cmap='viridis', proc_vertices='sharp')
+
+# subcortical structures
+atlas = 'aseg'
+regs = yab.get_atlas_regions(atlas=atlas, category='subcortical')
+data = np.arange(1, len(regs)+1)
+yab.plot_subcortical(data=data, atlas=atlas, vminmax=[2, 14], 
+                     views=['left_lateral', 'superior', 'right_lateral'], 
+                     bmesh_alpha=0.1, figsize=(600, 300), cmap='viridis')
+
+# white matter bundles
+atlas = 'xtract_tiny'
+regs = yab.get_atlas_regions(atlas=atlas, category='tracts')
+data = {reg: np.sin(i) for i, reg in enumerate(regs)}
+yab.plot_tracts(data=data, atlas=atlas, style='matte',
+                views=['left_lateral', 'anterior', 'superior'], bmesh_type='pial',
+                bmesh_alpha=0.1, figsize=(1600, 800), cmap='viridis')
 
 ```
 

{yabplot-0.1.4 → yabplot-0.2.0}/yabplot.egg-info/SOURCES.txt

@@ -4,9 +4,11 @@ README.md
 pyproject.toml
 tests/test_smoke.py
 yabplot/__init__.py
+yabplot/atlas_builder.py
 yabplot/plotting.py
 yabplot/scene.py
 yabplot/utils.py
+yabplot/wrappers.py
 yabplot.egg-info/PKG-INFO
 yabplot.egg-info/SOURCES.txt
 yabplot.egg-info/dependency_links.txt