Metadata-Version: 2.4
Name: cvnpy
Version: 0.1.0
Summary: Python tools for CVN-style cortical flatmap and inflated-surface visualizations
Author: cvnpy contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/Charestlab/cvnpy
Project-URL: Documentation, https://cvnpy.readthedocs.io/
Project-URL: Repository, https://github.com/Charestlab/cvnpy
Project-URL: Issues, https://github.com/Charestlab/cvnpy/issues
Keywords: cortex,flatmap,freesurfer,neuroimaging,visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE.md
Requires-Dist: numpy>=1.25
Requires-Dist: scipy>=1.11
Requires-Dist: nibabel>=5.1
Requires-Dist: matplotlib>=3.8
Requires-Dist: Pillow>=10.0
Requires-Dist: scikit-image>=0.22
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.25; extra == "docs"
Dynamic: license-file

# 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

## 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:

```bash
python -m pip install cvnpy
```

For local development:

```bash
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:

```bash
.venv/bin/python -m pytest -q
```

## Data Setup

`cvnpy` needs a FreeSurfer-style subject `surf/` directory.

### Option A: Use `SUBJECTS_DIR`

```bash
export SUBJECTS_DIR=/Applications/freesurfer/8.2.0/subjects
```

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

### Option B: Use explicit subject directory

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

This expects:

```text
/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)

```bash
.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)

```bash
.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`

```bash
.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

```bash
.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

```bash
.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](docs/GETTING_STARTED.md)
- [Flatmap Demo Reference](docs/FLATMAP_DEMO.md)
- [Inflated Demo Reference](docs/INFLATED_DEMO.md)
- [Python API Reference](docs/API.md)
- [MATLAB to Python Parity Map](docs/MATLAB_PARITY.md)
- [Troubleshooting](docs/TROUBLESHOOTING.md)
- [Development and Release](docs/DEVELOPMENT.md)

## 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.
