"""Bundle densities and cores in NiiVue: a Jupyter widget (ipyniivue) or a standalone page.
In a notebook (JupyterLab, Notebook 7, VS Code, Voila)::
from mpat import view
view("derivatives/afq/sub-01/mpat", t1="sub-01_desc-masked_T1w.nii.gz",
bundles=["LeftArcuate", "LeftCorticospinal"])
or as a web page to open in any browser or share: ``mpat.viewer.save_html("bundles.html",
folder, ...)`` with the same options.
Each bundle's density is shown on a log scale, from ``floor`` x its peak (faint) to its peak
(bright), in one colour map for all (``actc`` by default), its opacity falling off with
the density -- in the 3-D view too, where NiiVue ray-marches the density volumes; its core
(written by ``mpat.run``, computed here if missing) is drawn as a tube in its own colour,
which tells the bundles apart. ``glyphs=True`` adds the bundles'
visitation ODFs -- the directions their walkers travel in each voxel, drawn like fODF
glyphs -- on three planes through each core's midpoint. Slices and 3-D render are both
live: click to move the slices, drag in the render to rotate, scroll to zoom.
"""
from __future__ import annotations
import glob
import gzip
import logging
import os.path as op
import struct
import nibabel as nib
import numpy as np
from .core import bundle_core, bundle_files, write_core
log = logging.getLogger("mpat")
# (NiiVue colour map for the density, matching RGBA for the core tube)
PALETTE = [("warm", (255, 196, 40)), ("cool", (60, 230, 255)), ("green", (80, 255, 100)),
("violet", (210, 110, 255)), ("redyell", (255, 90, 40)), ("blue2cyan", (60, 140, 255)),
("gold", (255, 230, 120)), ("bluegrn", (60, 255, 200)), ("hot", (255, 60, 60)),
("electric_blue", (120, 180, 255))]
def _nifti_bytes(arr, affine, dtype=np.uint8):
img = nib.Nifti1Image(np.asarray(arr, dtype), affine)
img.header.set_xyzt_units("mm")
return gzip.compress(img.to_bytes(), compresslevel=6)
DENSITY_RANGE = 1e-6 # density maps are encoded down to this x the peak (the slider's range)
GLYPH_RANGE = 1e-3 # glyph voxels are kept down to this x the peak (mpat.afq.ODF_FLOOR)
def _u8_level(frac, enc_floor):
"""The uint8 level of log_density_u8(..., enc_floor) at frac x the peak."""
return float(1 + 254 * (np.log10(frac) - np.log10(enc_floor)) / -np.log10(enc_floor))
def _bbox_mm(mask, affine):
"""The 8 corners (mm) of a mask's voxel bounding box, or None if it is empty."""
ijk = np.argwhere(mask)
if not len(ijk):
return None
lo, hi = ijk.min(0), ijk.max(0)
corners = np.array([[x, y, z] for x in (lo[0], hi[0]) for y in (lo[1], hi[1]) for z in (lo[2], hi[2])])
return nib.affines.apply_affine(affine, corners)
def _crop_index(shape, affine, box):
"""(lo, hi) voxel indices of a grid covering the world box (mm); the whole grid if None."""
shape = np.array(shape[:3])
if box is None:
return np.zeros(3, int), shape
corners = np.array([[x, y, z] for x in box[:, 0] for y in box[:, 1] for z in box[:, 2]])
ijk = nib.affines.apply_affine(np.linalg.inv(affine), corners)
lo = np.clip(np.floor(ijk.min(0)), 0, shape - 1).astype(int)
hi = np.clip(np.ceil(ijk.max(0)) + 1, lo + 1, shape).astype(int)
return lo, hi
def _shifted(affine, lo):
"""The affine of a grid cropped to start at voxel lo."""
A = np.array(affine, float)
A[:3, 3] = nib.affines.apply_affine(affine, lo)
return A
def log_density_u8(density, floor=1e-3):
"""density -> uint8: 0 below floor x peak, 1..255 for log10(density / peak) in [log10 floor, 0]."""
d = np.clip(np.nan_to_num(np.asarray(density, float)), 0, None)
out = np.zeros(d.shape, np.uint8)
if d.max() > 0:
r = d / d.max()
m = r >= floor
out[m] = np.clip(np.rint(1 + 254 * (np.log10(r[m]) - np.log10(floor)) / -np.log10(floor)), 1, 255)
return out
def scene(folder, bundles=None, t1=None, floor=1e-3, show_density=True, density_opacity=1.0, crop=True,
core_radius=1.2, glyphs=False, glyph_planes=None, glyph_floor=1e-2, glyph_range=GLYPH_RANGE,
glyph_color=None, colormap=None, falloff=2,
glyph_norm=True, max_glyphs=4000, fodf=None, write_missing_cores=True, rois=False,
roi_opacity=1.0):
"""What ``view`` and ``save_html`` draw, as data: volumes and meshes (file bytes plus
display settings, each with its role), glyph sets (voxels and SH coefficients, meshed
per slice by ``glyph_mesh``), the bundles, the point the slices start at (``focus``, mm)
and the 2-D mesh slab.
bundles names to show (default: all)
t1 background image (default: the run's ``*_desc-mpat_dseg``)
floor faintest density shown, as a fraction of each bundle's peak
show_density overlay the density maps (False: cores only, on the background)
colormap NiiVue colour map of every density ("actc", default: black -> blue -> green
-> yellow -> red; "turbo", "jet", "hot", ...). With several bundles, their
densities are one volume: per voxel, the largest of them (each on its own
log scale), which NiiVue draws as one layer, not one per bundle (much
faster); so are their ROIs. "bundle": a volume per bundle instead, each in a
single-hue map in its core's colour
falloff how the density's opacity drops off: 0 at ``floor``, 1 at the peak, raised to
this power (1 linear in log density, 2 default, higher fades more), so the
ray-marched 3-D render is translucent where the density is low (in the slices
too). NiiVue draws every overlay voxel above its threshold fully opaque
whatever the colour map's alpha; this sets its alpha from the density itself
instead (NiiVue's alpha modulation). 0: opaque, as NiiVue draws it, with
``density_opacity``
density_opacity of the density over the background (falloff=0 only: NiiVue ignores a
modulated volume's opacity) (1: opaque; below ``floor`` the
background shows)
crop crop every volume to the content box (the background's non-empty voxels
and every bundle above ``floor``, plus 2 voxels), so views fill their space
core_radius tube radius in mm
glyphs visitation-ODF glyphs: True for every bundle shown, or bundle names
glyph_planes glyphs follow the slices: every voxel of the three slices through the
crosshair that reaches glyph_floor, redrawn as the slices move. None:
start at the first core's midpoint; (x, y, z) in mm: start there;
"all": every voxel at once, fixed (heavy; 2-D views still show one slice)
glyph_floor voxels whose density is below this x the bundle's peak get no glyph
glyph_range voxels down to this x the peak are kept, so a viewer can lower glyph_floor
live (default GLYPH_RANGE, 1e-3; raise it for smaller pages)
glyph_color "direction" (red left-right, green front-back, blue up-down) or "bundle"
(its core's colour); default: direction for one bundle, else bundle
glyph_norm each glyph scaled to its own maximum, as fODF glyphs usually are (False:
size proportional to the visits, the bundle's largest filling its voxel).
Glyphs read best zoomed in on a slice, with show_density=False.
max_glyphs per bundle with glyph_planes="all"; the densest voxels are kept
fodf an SH image on the same grid (e.g. pyAFQ's ``*_model-csd_param-wm_dwimap``):
grey glyphs at the same voxels, a little smaller, for comparison
write_missing_cores compute cores that are not on disk yet and save them next to the maps
rois show each bundle's include ROIs (green) and exclude ROIs (red) as overlay
volumes (ray-marched in 3-D), from the ``_desc-include_mask`` /
``_desc-exclude_mask`` files mpat.run writes
roi_opacity of those overlays (1: opaque)
"""
import json
files = bundle_files(folder)
if bundles:
missing = [b for b in bundles if b not in files]
if missing:
raise ValueError(f"not found under {folder}: {missing}; available: {sorted(files)}")
files = {b: files[b] for b in bundles}
if not files:
raise ValueError(f"no *_bundle-*_desc-density_map.nii.gz under {folder}")
if t1 is None: # the run's tissue labels (0 outside, 1 WM, 2-4 GM / CSF / edge)
cand = sorted(glob.glob(op.join(folder, "**", "*_dseg.nii.gz"), recursive=True),
key=lambda x: "_desc-mpat_dseg" not in x)
t1 = cand[0] if cand else None
S = dict(volumes=[], meshes=[], glyphs=[], bundles=[], focus=None, slab=None, falloff=int(falloff),
subject=op.basename(next(iter(files.values()))["prefix"]).split("_bundle-")[0])
dens = {name: nib.load(f["density"]) for name, f in files.items()}
dens = {name: (img, np.asarray(img.dataobj, np.float32)) for name, img in dens.items()}
ref, _ = next(iter(dens.values()))
back = None
if t1 is not None:
bimg = nib.load(t1)
bdat = np.asarray(bimg.dataobj)
back = (bimg, bdat[..., 0] if bdat.ndim == 4 else bdat)
# the content box (mm), and each grid's crop to it
pts = [_bbox_mm(d >= floor * d.max(), img.affine) for img, d in dens.values() if d.max() > 0]
if back is not None:
pts.append(_bbox_mm(back[1] > 0, back[0].affine))
pts = [p for p in pts if p is not None]
box = None
if crop and pts:
pts = np.concatenate(pts)
margin = 2.0 * float(max(ref.header.get_zooms()[:3]))
box = np.array([pts.min(0) - margin, pts.max(0) + margin])
lo_d, hi_d = _crop_index(ref.shape[:3], ref.affine, box)
cut = tuple(slice(a, b) for a, b in zip(lo_d, hi_d))
A = _shifted(ref.affine, lo_d) # the bundles' grid, cropped
if back is not None:
dseg = "dseg" in op.basename(str(t1))
lo_b, hi_b = _crop_index(back[1].shape, back[0].affine, box)
bc = back[1][tuple(slice(a, b) for a, b in zip(lo_b, hi_b))]
bc_img = nib.Nifti1Image(np.asarray(bc, np.uint8 if dseg else np.float32), _shifted(back[0].affine, lo_b))
bc_img.header.set_xyzt_units("mm")
S["volumes"].append(dict(role="background", name=op.basename(str(t1)).split(".nii")[0] + ".nii.gz",
data=gzip.compress(bc_img.to_bytes(), compresslevel=6),
colormap="gray", opacity=1.0, cal_min=0 if dseg else None,
cal_max=4 if dseg else None))
names = list(files) if glyphs is True else ([glyphs] if isinstance(glyphs, str) else list(glyphs or []))
if glyph_color is None:
glyph_color = "direction" if len(names) == 1 else "bundle"
S["glyph_color"] = glyph_color
every = []
merge = len(files) > 1 and colormap != "bundle" # one density volume: the max over bundles
merged = dict(density=None, include=None, exclude=None)
enc = min(floor, DENSITY_RANGE) # encoded down to DENSITY_RANGE; cal_min shows it from `floor`
for i, (name, f) in enumerate(files.items()):
img, dfull = dens[name]
d = dfull[cut] # cropped; on the grid A
cmap, rgb = PALETTE[i % len(PALETTE)]
cmap = cmap if colormap == "bundle" else (colormap or "actc")
meta = dict(name=name, label=name, rgb=list(rgb), colormap=cmap)
if op.exists(f["prefix"] + "_desc-summary.json"):
with open(f["prefix"] + "_desc-summary.json") as fh:
info = json.load(fh)
meta.update(label=info.get("bundle", name),
expected_streamlines=info.get("result", {}).get("expected_bundle_streamlines"))
S["bundles"].append(meta)
if merge:
u8 = log_density_u8(d, enc)
merged["density"] = u8 if merged["density"] is None else np.maximum(merged["density"], u8)
elif show_density or not S["volumes"]:
S["volumes"].append(dict(role="density", bundle=name, name=f"{name}_logdensity.nii.gz",
data=_nifti_bytes(log_density_u8(d, enc), A), colormap=cmap,
cal_min=_u8_level(floor, enc), cal_max=255, floor=floor, enc_floor=enc,
opacity=density_opacity if (S["volumes"] or not show_density) else 1.0))
if rois: # binary masks: 0 below cal_min (transparent), 1 in the ROI's colour map
for role, cmap_roi in ROI_COLORMAPS.items():
if f.get(role) is None:
continue
m = np.asarray(nib.load(f[role]).dataobj)[cut] > 0
if merge:
merged[role] = m if merged[role] is None else merged[role] | m
elif m.any():
S["volumes"].append(dict(role=role, bundle=name, name=f"{name}_{role}.nii.gz",
data=_nifti_bytes(m, A), colormap=cmap_roi, opacity=roi_opacity,
cal_min=0.5, cal_max=1.0))
if not (f.get("include") or f.get("exclude")):
log.warning("%s: no include / exclude masks on disk (written by mpat.run since 2026-11-06)", name)
# core: written by mpat.run; computed here if missing
trx, xyz = f["prefix"] + "_desc-core.trx", None
if op.exists(trx):
from dipy.io.streamline import load_tractogram
xyz = load_tractogram(trx, "same", bbox_valid_check=False).streamlines[0]
elif f["endpoints"] is not None and dfull.max() > 0:
load = lambda k: (np.asarray(nib.load(f[k]).dataobj) > 0) if f[k] else None # noqa: E731
try:
c = bundle_core(dfull, img.affine, np.asarray(nib.load(f["endpoints"]).dataobj), load("start"),
load("end"), include=np.asarray(nib.load(f["include"]).dataobj) if f["include"] else None)
except ValueError as e:
log.warning("%s: no core (%s)", name, e)
else:
if write_missing_cores:
write_core(c, f["prefix"], img)
xyz = c.xyz
if xyz is not None:
# a triangulated tube: NiiVue's streamline (.tck) renderer draws nothing in some
# WebGL builds, while surfaces always render
S["meshes"].append(dict(role="core", bundle=name, name=f"{name}_core.obj",
data=tube_obj(xyz, core_radius), rgba255=[*rgb, 255], opacity=1.0))
if name not in names or d.max() <= 0: # empty bundles: no glyphs
continue
if f["odf"] is None:
log.warning("%s: no visitation ODF on disk (written by mpat.run since 2026-11-04)", name)
continue
static = isinstance(glyph_planes, str) and glyph_planes == "all"
keep = glyph_floor if static else min(glyph_floor, glyph_range)
ijk = np.argwhere(d >= keep * d.max())
if static and len(ijk) > max_glyphs:
log.warning("%s: %d glyph voxels, showing the densest %d", name, len(ijk), max_glyphs)
ijk = ijk[np.argsort(d[tuple(ijk.T)])[::-1][:max_glyphs]]
every.append(ijk)
if S["focus"] is None: # slices start here; meshes in 2-D: a one-voxel slab
point = (np.asarray(glyph_planes, float) if glyph_planes is not None and not static else
xyz[len(xyz) // 2] if xyz is not None else
nib.affines.apply_affine(A, np.unravel_index(np.argmax(d), d.shape)))
S["focus"] = [float(x) for x in point]
S["slab"] = float(min(img.header.get_zooms()[:3]))
coef = np.asarray(nib.load(f["odf"]).dataobj, np.float32)[tuple((ijk + lo_d).T)]
S["glyphs"].append(dict(role="glyphs", bundle=name, name=f"{name}_glyphs.mz3", opacity=1.0, scale=1.0,
ijk=ijk.astype(np.int32), coef=coef, norm=glyph_norm, floor=glyph_floor,
rel=(d[tuple(ijk.T)] / d.max()).astype(np.float32),
rgb=None if glyph_color == "direction" else list(rgb)))
S["glyph_floor"], S["glyph_range"] = glyph_floor, keep
if merge: # after the background: the density, then the ROIs of every bundle
if merged["density"] is not None and (show_density or back is None):
S["volumes"].append(dict(role="density", bundle="all", name="all_logdensity.nii.gz",
data=_nifti_bytes(merged["density"], A), colormap=cmap,
cal_min=_u8_level(floor, enc), cal_max=255, floor=floor, enc_floor=enc,
opacity=density_opacity if back is not None else 1.0))
for role, cmap_roi in ROI_COLORMAPS.items():
if merged[role] is not None and merged[role].any():
S["volumes"].append(dict(role=role, bundle="all", name=f"all_{role}.nii.gz",
data=_nifti_bytes(merged[role], A), colormap=cmap_roi,
opacity=roi_opacity, cal_min=0.5, cal_max=1.0))
if fodf is not None and every:
fimg = nib.load(fodf)
if fimg.shape[:3] != ref.shape[:3] or not np.allclose(fimg.affine, ref.affine, atol=1e-3):
raise ValueError(f"{fodf} is not on the bundles' grid {ref.shape[:3]}")
ijk, inv = np.unique(np.concatenate(every), axis=0, return_inverse=True)
rel = np.zeros(len(ijk), np.float32) # shown where any bundle's glyph is
np.maximum.at(rel, inv.ravel(), np.concatenate([g["rel"] for g in S["glyphs"]]))
ijk = ijk.astype(np.int32)
S["glyphs"].append(dict(role="fodf", name="fodf_glyphs.mz3", opacity=1.0, scale=0.85, ijk=ijk, norm=True,
floor=glyph_floor, rel=rel, rgb=[150, 150, 150],
coef=np.asarray(fimg.dataobj, np.float32)[tuple((ijk + lo_d).T)]))
for g in S["glyphs"]: # largest radius of the set, for glyph_norm=False
g["vmax"] = float(max(_odf_max(g["coef"]), 1e-30))
if S["glyphs"]:
S["affine"] = np.asarray(A, float).tolist()
S["shape"] = list(d.shape)
if static: # every glyph at once; the slab still shows one slice in 2-D
S["meshes"] += [dict(role=g["role"], bundle=g.get("bundle"), name=g["name"], opacity=g["opacity"],
rgba255=[255, 255, 255, 255], data=glyph_mesh(g, S["affine"]))
for g in S.pop("glyphs")]
S["glyphs"] = []
if S["focus"] is not None: # as NiiVue's crosshair: fraction of the RAS-ordered background grid
bg = nib.as_closest_canonical(bc_img if back is not None else nib.Nifti1Image(d, A))
vox = nib.affines.apply_affine(np.linalg.inv(bg.affine), S["focus"])
S["focus_frac"] = [float(x) for x in np.clip((vox + 0.5) / np.array(bg.shape[:3]), 0, 1)]
return S
def view(folder, height=640, **kwargs):
"""ipyniivue ``NiiVue`` widget with the MPAT bundles under ``folder``: the three slices
and a 3-D render in an equal 2 x 2 grid, cropped to the content (the 3-D view: each
bundle's density ray-marched by NiiVue's volume renderer, from ``floor`` x its peak, in a
lit head cut open towards the camera).
Double-click a view to enlarge it to the whole widget; double-click again for the grid. ``kwargs``: ``scene``'s options (bundles, t1, floor, glyphs, fodf, ...),
then any ``ipyniivue.NiiVue`` option (e.g. back_color=(1, 1, 1, 1))."""
import asyncio
import inspect
from ipyniivue import Mesh, MultiplanarType, NiiVue, ShowRender, SliceType, Volume
own = set(inspect.signature(scene).parameters) - {"folder"}
S = scene(folder, **{k: v for k, v in kwargs.items() if k in own})
nv_options = {k: v for k, v in kwargs.items() if k not in own}
# the three slices and the 3-D render as an equal 2 x 2 grid, using all their space.
# Meshes are not seen through the volume (x-ray 0); the 3-D view cuts the head open, lit,
# on the side facing the camera, and ray-marches the density (and ROI) overlays into it
opts = dict(back_color=(0, 0, 0, 1), slice_type=SliceType.MULTIPLANAR,
multiplanar_show_render=ShowRender.ALWAYS, multiplanar_layout=MultiplanarType.GRID,
multiplanar_equal_size=True, hero_image_fraction=0.0, is_colorbar=False, mesh_xray=0.0,
render_overlay_blend=1.0, clip_plane_color=(0.0, 0.0, 0.0, 0.0), tile_margin=0.0,
multiplanar_pad_pixels=0, is_orient_cube=False, mesh_thickness_on_2d=S["slab"] or 4.0)
opts.update(nv_options)
nv = NiiVue(height=height, **opts)
nv.load_volumes([Volume(data=v["data"], name=v["name"], colormap=v["colormap"], opacity=v["opacity"],
**{k: v[k] for k in ("cal_min", "cal_max") if v[k] is not None})
for v in S["volumes"]])
fixed = [Mesh(data=m["data"], name=m["name"], rgba255=m["rgba255"], opacity=m["opacity"]) for m in S["meshes"]]
shown = {"c": None}
def follow(mm): # glyphs on the three slices through the crosshair
c = tuple(int(x) for x in np.clip(np.rint(nib.affines.apply_affine(np.linalg.inv(S["affine"]), mm)),
0, np.array(S["shape"]) - 1))
if c == shown["c"]:
return
shown["c"] = c
meshes = [Mesh(data=data, name=g["name"], opacity=g["opacity"]) for g in S["glyphs"]
if (data := glyph_mesh(g, S["affine"], c)) is not None]
nv.meshes = [*fixed, *meshes]
def moved(d): # debounced: while scrolling, only the slice you stop on is meshed
shown["mm"] = d["mm"][:3]
if shown.get("timer") is not None:
shown["timer"].cancel()
try:
loop = asyncio.get_event_loop()
except RuntimeError:
loop = None
if loop is not None and loop.is_running():
shown["timer"] = loop.call_later(0.3, lambda: follow(shown["mm"]))
else:
follow(shown["mm"])
if S["glyphs"]:
follow(S["focus"])
nv.on_location_change(moved)
elif fixed:
nv.load_meshes(fixed)
# double-click a view to have it fill the widget; double-click again for the grid.
# ipyniivue reports mouse-ups and crosshair moves only: two quick mouse-ups in one place
# are a double-click; a crosshair move just before says which slice, none means 3-D
import time
click = {"t": 0.0, "pos": None, "view": None, "moved": 0.0}
views = {0: SliceType.AXIAL, 1: SliceType.CORONAL, 2: SliceType.SAGITTAL}
def located(d):
click["moved"], click["view"] = time.monotonic(), d.get("ax_cor_sag")
def released(d):
if d.get("is_dragging"):
return
now, pos = time.monotonic(), tuple(d.get("mouse_pos") or (0, 0))
double = now - click["t"] < 0.45 and click["pos"] is not None and max(
abs(a - b) for a, b in zip(pos, click["pos"])) < 8
click["t"], click["pos"] = now, pos
if not double:
return
click["t"] = 0.0
if nv.opts.slice_type != SliceType.MULTIPLANAR:
nv.set_slice_type(SliceType.MULTIPLANAR)
elif now - click["moved"] < 0.6 and click["view"] in views:
nv.set_slice_type(views[click["view"]])
else:
nv.set_slice_type(SliceType.RENDER)
nv.on_location_change(located)
nv.on_mouse_up(released)
if S["focus"] is not None:
nv.scene.crosshair_pos = S["focus_frac"]
nv.set_clip_planes([[0.0, nv.scene.render_azimuth + 180, -nv.scene.render_elevation]])
nv.on_canvas_attached(lambda *_: nv.set_volume_render_illumination(0.6)) # lit, solid-looking head
# opacity from the density itself (alpha modulation by its own image; see scene's falloff).
# ipyniivue applies modulation only on a change, once the page holds the volume, and
# loads the volumes in order: set it when the last is in, from a cleared state
dens_idx = [i for i, v in enumerate(S["volumes"]) if v["role"] == "density"]
seen = set()
def loaded(*args):
seen.add(len(seen))
if len(seen) < len(S["volumes"]) or not S["falloff"]:
return
seen.clear()
for i in dens_idx:
vol = nv.volumes[i]
vol.modulate_alpha, vol.modulation_image = 0, None
vol.modulate_alpha, vol.modulation_image = S["falloff"], i
nv.on_image_loaded(loaded)
nv.bundle_names = [b["name"] for b in S["bundles"]] # overlay order after the background
return nv
ROI_COLORMAPS = {"include": "green", "exclude": "red"} # NiiVue colour maps of the ROI overlays
NIIVUE_CDN = "https://cdn.jsdelivr.net/npm/@niivue/niivue@0.65.0/dist/niivue.umd.js"
[docs]
def save_html(path, folder, title=None, niivue_js=None, **kwargs):
"""A standalone web page with the same scene as ``view`` (``kwargs``: ``scene``'s
options), with controls for the layout, each bundle's density / core / glyphs, and the
opacities. The data are embedded. NiiVue loads from a CDN, or from ``niivue_js``, a
local ``niivue.umd.js`` (npm package @niivue/niivue, dist/) embedded too, so the page
works offline. Returns the path."""
import base64
import json
from importlib.resources import files as resources
from dipy.data import get_sphere
from .geometry import _sh_basis
S = scene(folder, **kwargs)
b64 = lambda a, t: base64.b64encode(np.ascontiguousarray(a, t).tobytes()).decode() # noqa: E731
for item in S["volumes"] + S["meshes"]:
item["data"] = base64.b64encode(item["data"]).decode()
if S["glyphs"]: # the page meshes the slices through the crosshair itself, as view does
sph = get_sphere(name="symmetric362")
u = np.asarray(sph.vertices, float)
A = np.asarray(S["affine"])[:3, :3]
zooms = np.linalg.norm(A, axis=0)
widths = sorted({g["coef"].shape[1] for g in S["glyphs"]})
S["sphere"] = dict(n=len(u), w=b64(u @ (A / zooms).T, "<f4"), faces=b64(sph.faces, "<u4"),
radius=float(0.5 * zooms.min()), inv_affine=np.linalg.inv(S["affine"]).tolist(),
basis={str(k): b64(_sh_basis(u, k), "<f4") for k in widths})
for g in S["glyphs"]:
g["K"] = int(g["coef"].shape[1])
g["ijk"], g["coef"], g["rel"] = b64(g["ijk"], "<i4"), b64(g["coef"], "<f4"), b64(g["rel"], "<f4")
title = title or f"MPAT \u00b7 {S['subject']}"
if niivue_js is None:
lib = f'<script src="{NIIVUE_CDN}"></script>'
else:
with open(niivue_js) as fh:
lib = "<script>" + fh.read().replace("</script", "<\\/script") + "</script>"
page = (resources("mpat") / "viewer.html").read_text()
page = (page.replace("__TITLE__", title.replace("<", "<")).replace("__NIIVUE__", lib)
.replace("__DATA__", json.dumps(S).replace("</", "<\\/")))
with open(path, "w") as fh:
fh.write(page)
return path
def _odf_max(coef, sphere="symmetric362"):
from dipy.data import get_sphere
from .geometry import _sh_basis
if not len(coef):
return 0.0
B = _sh_basis(np.asarray(get_sphere(name=sphere).vertices, float), coef.shape[1])
return max(float(np.max(np.asarray(coef[s:s + 4096], float) @ B)) for s in range(0, len(coef), 4096))
def glyph_mesh(g, affine, c=None, floor=None):
"""MZ3 bytes of a glyph set (from ``scene``) on the three slices through voxel c (all
voxels if None), where the density reaches ``floor`` x the peak (default: the set's
glyph_floor), or None if there are none there."""
on = np.ones(len(g["ijk"]), bool) if c is None else (g["ijk"] == np.asarray(c)).any(1)
on &= g["rel"] >= (g["floor"] if floor is None else floor)
if not on.any():
return None
return glyph_mz3(g["coef"][on], g["ijk"][on], affine, rgb=g["rgb"], norm=g["norm"], vmax=g["vmax"],
scale=g.get("scale", 1.0))
def glyph_mz3(coef, ijk, affine, rgb=None, norm=True, scale=1.0, sphere="symmetric362", vmax=None):
"""Gzipped MZ3 surface (NiiVue's native mesh format) of ODF glyphs, one per voxel.
coef (n, ncoef) SH coefficients (DIPY descoteaux07, as pyAFQ's fODFs and MPAT's visitation
ODFs); ijk (n, 3) voxel indices; affine voxel -> world (mm). Radii are the ODF clipped
at 0, scaled to each glyph's maximum (norm) or to the largest of all (or vmax), which reaches
``scale`` x half the smallest voxel side. Colour: rgb, or by direction (|x|, |y|, |z|)."""
from dipy.data import get_sphere
from .geometry import _sh_basis
s = get_sphere(name=sphere)
u, faces = np.asarray(s.vertices, float), np.asarray(s.faces, np.int64)
coef, ijk = np.asarray(coef, float).reshape(len(ijk), -1), np.asarray(ijk).reshape(-1, 3)
r = np.maximum(coef @ _sh_basis(u, coef.shape[1]), 0) if len(ijk) else np.zeros((0, len(u)))
m = r.max(1)
keep = m > 0
r, m, ijk = r[keep], m[keep], ijk[keep]
r /= m[:, None] if norm else (vmax or max(m.max(initial=0), 1e-300))
A = np.asarray(affine, float)[:3, :3]
zooms = np.linalg.norm(A, axis=0)
w = u @ (A / zooms).T # glyph directions in world axes
centre = nib.affines.apply_affine(affine, ijk)
verts = (centre[:, None] + (scale * 0.5 * zooms.min()) * r[..., None] * w[None]).reshape(-1, 3)
col = np.abs(w) / np.abs(w).max(1, keepdims=True) * 255 if rgb is None else np.tile(rgb, (len(u), 1))
rgba = np.tile(np.c_[col, np.full(len(u), 255)].astype(np.uint8), (len(ijk), 1))
# drop the triangles collapsed at the centre (where the ODF is ~0), then unused vertices
g, fi = np.nonzero(r[:, faces].max(-1) > 0.02)
tri = faces[fi] + len(u) * g[:, None]
used = np.zeros(len(verts), bool)
used[tri.ravel()] = True
tri = (np.cumsum(used) - 1)[tri]
verts, rgba = verts[used], rgba[used]
return _mz3(tri, verts, rgba)
def _mz3(tri, verts, rgba):
"""Gzipped MZ3 (NiiVue's native mesh format): triangles, vertices, per-vertex RGBA."""
head = struct.pack("<HHIII", 23117, 7, len(tri), len(verts), 0) # faces | vertices | RGBA
body = (np.asarray(tri).astype("<u4").tobytes() + np.asarray(verts).astype("<f4").tobytes()
+ np.asarray(rgba, np.uint8).tobytes())
return gzip.compress(head + body, compresslevel=6)
def tube_obj(xyz, radius=1.0, sides=12):
"""Wavefront OBJ text of a closed tube (triangles) around a polyline -- renders as an
ordinary surface in any NiiVue build, independent of its streamline renderer."""
xyz = np.asarray(xyz, float)
n = len(xyz)
t = np.gradient(xyz, axis=0)
t /= np.maximum(np.linalg.norm(t, axis=1, keepdims=True), 1e-12)
# rotation-minimising frame (double reflection), so the tube does not twist
a = np.cross(t[0], [1.0, 0, 0] if abs(t[0][0]) < 0.9 else [0, 1.0, 0])
U = np.empty((n, 3))
U[0] = a / np.linalg.norm(a)
for i in range(n - 1):
v1 = xyz[i + 1] - xyz[i]
c1 = v1 @ v1
if c1 < 1e-20:
U[i + 1] = U[i]
continue
rL = U[i] - (2 / c1) * (v1 @ U[i]) * v1
tL = t[i] - (2 / c1) * (v1 @ t[i]) * v1
v2 = t[i + 1] - tL
c2 = v2 @ v2
U[i + 1] = rL - (2 / c2) * (v2 @ rL) * v2 if c2 > 1e-20 else rL
V = np.cross(t, U)
ang = 2 * np.pi * np.arange(sides) / sides
ring = xyz[:, None] + radius * (np.cos(ang)[None, :, None] * U[:, None] + np.sin(ang)[None, :, None] * V[:, None])
pts = np.vstack([ring.reshape(-1, 3), xyz[0], xyz[-1]])
faces = []
for i in range(n - 1):
for k in range(sides):
a0, a1 = i * sides + k, i * sides + (k + 1) % sides
b0, b1 = a0 + sides, a1 + sides
faces += [(a0, b0, a1), (a1, b0, b1)]
c0, c1 = n * sides, n * sides + 1
for k in range(sides):
faces.append((c0, (k + 1) % sides, k))
faces.append((c1, (n - 1) * sides + k, (n - 1) * sides + (k + 1) % sides))
lines = [f"v {p[0]:.3f} {p[1]:.3f} {p[2]:.3f}" for p in pts]
lines += [f"f {f[0] + 1} {f[1] + 1} {f[2] + 1}" for f in faces]
return ("\n".join(lines) + "\n").encode()