Pycortex Guide

What it does

When your agent uses it

• The user mentions pycortex
• Cortical surfaces
• WebGL brain viewers
• Cortical surface mapping

Example prompts

• “/pycortex-guide”

Requirements

• Python 3

Workflow steps

10 steps, taken from the first numbered list in SKILL.md.

1. 1Volume data shape must match the transform dimensions in the database. Use cortex.db.get_xfm(subject, xfmname) to check expected shape.
2. 2Subject and transform names must exist in cortex.db before creating Volume objects. Import from FreeSurfer first.
3. 3cortex.quickshow is an alias for cortex.quickflat.make_figure — they are the same function.
4. 4Vertex data length must match total vertex count (left + right hemisphere). Single-hemisphere data is auto-padded with zeros.
5. 5vmin/vmax default to 1st/99th percentile of data. Always set explicitly for consistent colorbars across subjects.
6. 6WebGL viewer (webshow) starts a Tornado server — it blocks in scripts. Use in IPython/Jupyter or set autoclose=True.
7. 7The pycortex filestore path is set in cortex.options.config. Check with cortex.database.default_filestore.
8. 8For headless rendering (no display), install with pip install 'pycortex[headless]' and use cortex.export.save_3d_views(..., headless=True).
9. 9cortex.db is a singleton — all operations share the same database instance.
10. 10When saving datasets with pack=True, subject geometry and transforms are embedded in the HDF5 file for portability.

What it can do on your machine

Read from SKILL.md and the folder at commit 93f6855. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Shell commands in SKILL.md call:

  • pip

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md. Its commands use pip, which can reach the network depending on how they are called.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Pycortex Guide loads about 1.6k tokens when it runs, and up to ~12k if it reads all its reference files. Until then it costs about 141 tokens; SKILL.md has 511 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~141

When it runs · the whole SKILL.md, loaded when a task matches

~1.6k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~12k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from NeuroAIHub/BrainPilot at commit 93f6855, republished under its AGPL-3.0 licence (© NeuroAIHub). 511 words, ~1,581 tokens.

name

pycortex-guide

description

Domain-validated guidance for cortical surface visualization and brain surface rendering of fMRI data using pycortex: data types (Volume, Vertex, Dataset), 2D cortical flatmaps, 3D WebGL brain viewers, volume-to-surface mapping, FreeSurfer/fMRIPrep integration, ROI management, and surface analysis. Use this skill whenever the user mentions pycortex, `import cortex`, cortical surfaces, brain flatmaps, WebGL brain viewers, cortical surface mapping, or wants to visualize neuroimaging data on the cortex, even if they don't explicitly name pycortex.

version

1.0.0

authors

Claude (AI-assisted)

review_status

ai-generated

pip install -U setuptools wheel numpy cython
pip install -U pycortex
# With headless rendering support:
pip install -U 'pycortex[headless]'

1. Import subject (FreeSurfer/fMRIPrep)  →  stored in cortex.db
2. Create data objects (Volume/Vertex)    →  wrap arrays with metadata
3. Visualize (quickflat / webgl / export) →  2D flatmaps or 3D viewers
4. Analyze surfaces (curvature, ROIs)     →  surface geometry tools

import cortex

# Create a random volume for demo subject "S1" with transform "fullhead"
vol = cortex.Volume.random("S1", "fullhead")

# 2D flatmap
fig = cortex.quickshow(vol, with_curvature=True, with_rois=True)
fig.savefig("flatmap.png")

# Interactive 3D viewer
cortex.webshow(vol)

# Create volume from your own data (3D numpy array)
import numpy as np
data = np.random.randn(31, 100, 100)  # must match transform shape
vol = cortex.Volume(data, "S1", "fullhead", cmap="RdBu_r", vmin=-2, vmax=2)
cortex.quickshow(vol)

# Save/load datasets
ds = cortex.Dataset(my_map=vol)
ds.save("results.hdf")
ds_loaded = cortex.load("results.hdf")

© NeuroAIHub, AGPL-3.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 7 other files (references) in packages/skills/skills/06_fMRI_Neuroimaging/pycortex-guide of NeuroAIHub/BrainPilot.

• SKILL.md
• references/database-subjects.md
• references/dataset-types.md
• references/freesurfer-fmriprep.md
• references/mapping-transforms.md
• references/mni-utils.md
• references/surface-analysis.md
• references/visualization.md

Open the folder on GitHubat commit 93f6855