cvnpy

Python port of key CVN visualization workflows from cvncode (MATLAB), focused on production-quality:

• flatmap rendering (including Kendrick-style fsaverage cuts)
• inflated-surface rendering
• sphere/surface lookup compatibility
• layered SVG export for downstream overlays (ROIs/labels)

Documentation: https://cvnpy.readthedocs.io/

Current Status

cvnpy is now functional for the visualization path and includes:

• lookup generation + caching
• flat/inflated demos
• stat-map overlays with thresholding
• symmetric color limits
• optional colorbar
• optional bilateral inflated insets
• layered SVG output with stable object IDs
• MATLAB-parity nearest-neighbor vertex-to-image mapping for flatmaps

Repository Layout

• src/cvnpy/core/lookup_images.py: main rendering engine (lookup_images)
• src/cvnpy/io/surfaces.py: surface + patch loading
• src/cvnpy/io/metrics.py: per-vertex metric loading
• src/cvnpy/view/viewpoints.py: named viewpoints (sphere/non-sphere/flat)
• src/cvnpy/render/colormap.py: MATLAB-like colormap conversion (cmapsign4)
• examples/flatmap_demo.py: full flatmap pipeline (PNG + layered SVG)
• examples/inflated_demo.py: inflated-surface rendering demo
• tests/: unit tests for scaffold milestones and colormap behavior

Install

From PyPI, once the first release is published:

python -m pip install cvnpy

For local development:

cd /Users/iancharest/Documents/codex/cvncode/cvnpy
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip setuptools wheel
.venv/bin/python -m pip install -e '.[dev]'

Run tests:

.venv/bin/python -m pytest -q

Data Setup

cvnpy needs a FreeSurfer-style subject surf/ directory.

Option A: Use SUBJECTS_DIR

export SUBJECTS_DIR=/Applications/freesurfer/8.2.0/subjects

Then pass --subject fsaverage (or your subject name).

Option B: Use explicit subject directory

--subject-dir /Users/iancharest/data/nsd_fsaverage

This expects:

/Users/iancharest/data/nsd_fsaverage/
  surf/
    lh.full.flat.patch.3d
    rh.full.flat.patch.3d
    lh.inflated
    rh.inflated
    lh.curv
    rh.curv
    ...

Quick Start

1) Flatmap (single hemi)

.venv/bin/python examples/flatmap_demo.py \
  --subject-dir /Users/iancharest/data/nsd_fsaverage \
  --hemi lh \
  --surftype full.flat.patch.3d \
  --view 0,0,0 \
  --cache-dir /tmp/cvnpy_cache \
  --out out/nsd_lh_flat.png

2) Flatmap (both hemispheres, production defaults)

.venv/bin/python examples/flatmap_demo.py \
  --subject-dir /Users/iancharest/data/nsd_fsaverage \
  --hemi both \
  --surftype full.flat.patch.3d \
  --view 0,0,0 \
  --cache-dir /tmp/cvnpy_cache \
  --out out/nsd_bihemi_flat.png

3) Stat-map overlay from .npy

.venv/bin/python examples/flatmap_demo.py \
  --subject-dir /Users/iancharest/data/nsd_fsaverage \
  --hemi both \
  --surftype full.flat.patch.3d \
  --stat-file /Users/iancharest/Downloads/rcnn-mpnet/encoding/subj01/shared_pred/test_corr.npy \
  --symmetric-clim \
  --absthreshold 0.05 \
  --show-colorbar \
  --cache-dir /tmp/cvnpy_cache \
  --out out/subj01_corr_bihemi.png

4) Add inflated insets

.venv/bin/python examples/flatmap_demo.py \
  --subject-dir /Users/iancharest/data/nsd_fsaverage \
  --hemi both \
  --stat-file /Users/iancharest/Downloads/rcnn-mpnet/encoding/subj01/shared_pred/test_corr.npy \
  --absthreshold 0.05 \
  --show-colorbar \
  --show-insets \
  --inset-viewname lateral \
  --out out/subj01_corr_bihemi_insets.png

5) Layered SVG export

.venv/bin/python examples/flatmap_demo.py \
  --subject-dir /Users/iancharest/data/nsd_fsaverage \
  --hemi both \
  --stat-file /Users/iancharest/Downloads/rcnn-mpnet/encoding/subj01/shared_pred/test_corr.npy \
  --show-colorbar \
  --out out/subj01_corr_bihemi.png \
  --out-svg out/subj01_corr_bihemi.svg

Layered SVG IDs

The SVG contains stable IDs for overlay workflows:

• layers
• curv
• stat
• labels_lh
• labels_rh
• colorbar
• inset_lh and inset_rh (when enabled)

This is designed to support Kendrick-style post-hoc SVG overlays.

Default Colormap

The default data colormap is cmapsign4, ported from:

• knkutils/colormap/cmapsign4.m

You can override with --cmap.

Full Documentation

• Getting Started
• Flatmap Demo Reference
• Inflated Demo Reference
• Python API Reference
• MATLAB to Python Parity Map
• Troubleshooting
• Development and Release

Known Limitations

• Exact pixel-perfect parity with MATLAB outputs is still in progress.
• Some edge/cut configurations may require tuning flatmap options for a given subject.
• Public release requires final confirmation of GitHub organization, PyPI Trusted Publishing setup, and upstream license compatibility.

Citation / Attribution

This project ports concepts and workflows from cvncode and related CVN tooling by Kendrick Kay and collaborators.