DOCSEARCHbyAlgolia
Submit Docs

pycortex

repository·main·Indexed 20 days ago

https://github.com/gallantlab/pycortex

A software library for visualizing volumetric neuroimaging data, such as fMRI, on cortical surfaces. It provides tools for 3D rendering via cortex.webgl, 2D flat projections via cortex.quickflat, and brain alignment through automatic and manual processes in cortex.align. The library supports Linux and macOS, utilizing a flat-file database (filestore) to manage surfaces, transforms, masks, and ROIs.

Tokens
13K
Snippets
35
Records
67
Agent score
69%

What's inside pycortex

  2. What is OpenCTM?

    main
    OpenCTM is a file format, software library, and toolset designed for the compression of 3D triangle meshes. It aims to compress geometry to a fraction of the size of comparable formats like 3DS, STL, COLLADA, and VRML. The library is written in portable C (C99) and is designed to be compatible with both big-endian and little-endian 32/64-bit systems.

  3. Explore the most commonly used pycortex modules

    main

    The cortex package is organized into several specialized modules. The most frequently used modules for visualization and data handling are:

    • cortex.quickflat: High-level functions for creating 2D flat projections of cortical data (e.g., make_figure, add_data, add_rois).
    • cortex.webgl: Tools for interactive 3D visualization (e.g., show, make_static).
    • cortex.dataset: Core data structures for representing brain data, including Dataset, Volume, and Vertex objects (and their 2D/RGB variants).

  5. Understand the segmentation process in pycortex

    main

    Segmentation is the process of identifying boundaries between white matter/gray matter and gray matter/dura. While tools like Caret estimate a single 'fiducial' surface (the midway point between white matter and pia) using a marching cubes algorithm, pycortex provides a more integrated approach.

    Pycortex wraps several Freesurfer segmentation steps to simplify the workflow. Typically, the four functions located in cortex.segment are sufficient to transform an anatomical image into a segmented and flattened surface.

  6. How pycortex surfaces work

    main

    Pycortex operates on triangular mesh geometry. A surface is any file specifying this geometry. To plot cortical data, a subject must have at least the fiducial and flat geometries available.

    Surface Requirements

    • Vertex Consistency: The surface files for a specific subject and hemisphere (left lh or right rh) must have the same number of vertices across all types (e.g., fiducial, inflated, and flat). If they do not match, mapping from fiducial to flatmap will fail.
    • Formats: Supported formats are OFF, VTK, and npz. npz is recommended for highest performance as it is binary and compressed. VTK files must be in v. 1 (ASCII) format.
    • Naming Convention: Inside the filestore, files are named {type}_{hemisphere}.{format} (e.g., fiducial_lh.npz).

    Surface Types

    • fiducial: The undistorted reconstruction in original anatomical space.
    • inflated: An inflated version of the fiducial surface.
    • flat: A 2D flattened version of the surface.

  7. How ROI and Sulcus drawing differ in pycortex

    main

    When using pycortex-roidraw, it is important to distinguish between ROIs and Sulci, as they interact with the pycortex ecosystem differently:

    ROIs (Regions of Interest)

    • Type: Closed curves.
    • Data: Carries per-hemisphere vertex membership.
    • Export: A portable JSON vertex set containing vertex indices, boundary rings, and editable bezier curves.
    • Compatibility: These are independent of the standard Inkscape-based pycortex ROI system. They are not read by get_roi_masks or similar Python API functions. Use them for quick interactive annotation in the viewer.

    Sulci

    • Type: Open curves.
    • Data: Carries no vertex data; they are display geometry only.
    • Export: An overlays.svg fragment (open, unfilled <path> elements in a sulci layer).
    • Compatibility: These are compatible with pycortex's native machinery. Once merged into a subject's overlays.svg, they are read by quickflat, the WebGL viewer, and Inkscape.

  8. How Dataviews work in Pycortex

    main

    Dataviews are the primary objects used to represent neuroimaging data in different spaces. Dataset acts as a container for these views.

    Core Dataview types include:

    • Volume: Volumetric data in original volume space.
    • Vertex: Data projected onto surface vertices.
    • VolumeRGB / VertexRGB: Data containing color channels (Red, Green, Blue, and optionally Alpha).
    • Volume2D / Vertex2D: A pair of volumetric/vertex data displayed using a 2D colormap.

    All dataviews support common keyword arguments for visualization:

    • cmap: Matplotlib colormap name.
    • vmin / vmax: Colormap limits.
    • description: Text shown as a subheading in WebGL views.
    • priority: Order of inclusion in a Dataset.
    • **kwargs: Additional string-based attributes (e.g., options for cortex.quickflat.make_figure).

  9. Understand the purpose and direction of transforms

    main

    In pycortex, transforms are used to align functional data (e.g., fMRI sequences) with the anatomical surfaces. This is necessary because functional scans often have different scan parameters and larger distortions than the T1 anatomical scans used for surface generation.

    Crucial Directionality: All transforms in pycortex always map from fiducial space to functional space.

  10. Choose a brain surface flattening method

    main

    PyCortex supports three methods for transforming a 3D brain surface into a 2D flatmap. Choose based on your requirements for speed versus distortion:

    1. Freesurfer (Recommended): Uses Freesurfer's mris_flatten. Produces high-quality flatmaps with minimal distortion. Time: ~2 hours per hemisphere.
    2. SLIM: An experimental, very fast method using the SLIM algorithm. Tends to have more distortion. Requirement: Requires additional installation of the SLIM dependency.
    3. Blender: Uses Blender's UV unwrapping. Faster than Freesurfer but may introduce more distortion. Time: ~5-15 minutes per hemisphere.

  11. Choose between Dynamic and Static WebGL viewers

    main

    Pycortex provides two modes for interactive 3D brain visualization in a web browser:

    1. Dynamic Viewer: A temporary viewer hosted by the Python process that generated it. This is ideal for real-time interaction and bi-directional communication between Python and JavaScript.
    2. Static Viewer: A viewer saved permanently to disk. It generates a single web page with most resources embedded, making it easy to host on a web server (like nginx) or upload to repositories like Neurovault. This mode is intended for sharing visualizations that persist beyond the lifetime of the Python session.

  12. Understand the subject database structure

    main

    The pycortex filestore organizes subject data into a specific directory hierarchy. A typical subject entry (e.g., S1) contains the following subdirectories and files:

    • anatomicals/: Raw anatomical scans (e.g., raw.nii.gz).
    • cache/: Cached computations like flatmasks and flatpixel data.
    • overlays.svg: SVG files for surface overlays.
    • rois.svg: SVG files defining surface ROIs.
    • surface-info/: Quantifications such as Tissot's Indicatrix and flatmap surface distortion (e.g., distortion[dist_type=areal].npz).
    • surfaces/: Surface files in formats like .gii (e.g., flat_lh.gii, inflated_lh.gii, pia_lh.gii, wm_lh.gii).
    • transforms/: Transformation matrices and reference volumes (e.g., fullhead/matrices.xfm).
    • views/: Stored WebGL view parameters.
    filestore/db
└── S1
    ├── anatomicals
    │   └── raw.nii.gz
    ├── cache
    │   ├── flatmask_1024.npz
    │   ├── flatpixel_fullhead_1024_nearest_l32.npz
    │   ├── flatverts_1024.npz
    │   └── fullhead_linenn.npz
    ├── overlays.svg
    ├── rois.svg
    ├── surface-info
    │   ├── distortion[dist_type=areal].npz
    │   └── distortion[dist_type=metric].npz
    ├── surfaces
    │   ├── flat_lh.gii
    │   ├── flat_rh.gii
    │   ├── inflated_lh.gii
    │   ├── inflated_rh.gii
    │   ├── pia_lh.gii
    │   ├── pia_rh.gii
    │   ├── wm_lh.gii
    │   └── wm_rh.gii
    ├── transforms
    │   ├── fullhead
    │   │   ├── matrices.xfm
    │   │   └── reference.nii.gz
    │   └── retinotopy
    │       ├── matrices.xfm
    │       └── reference.nii.gz
    └── views