# gallantlab/pycortex architecture

> Architecture diagram of the GitHub repository gallantlab/pycortex, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gallantlab/pycortex
- Repository: https://github.com/gallantlab/pycortex

## Overview

##### Project’s Nature and Purpose
- The README emphasizes its use with IPython and demonstrates a demo that uses the cortex.webshow function to render a volume.
- That there is support for multiple visualization modalities (e.g., web-based via “webgl” and quick visualization via “quickflat”) as well as interfaces to popular neuroimaging data sources (e.g., Freesurfer, fMRIPrep, MNI transforms).

##### File Structure
- The top-level “cortex” directory holds the core library. Within it, subdirectories such as “dataset”, “mapper”, “export”, “blender”, “polyutils”, “webgl”, and “quickflat” indicate distinct modules handling different aspects:
- The “dataset” module likely deals with loading and managing neuroimaging data.
- The “mapper” module is probably responsible for constructing surface mappings and performing necessary computations (including sampling and geometric transformations).
- “export” appears to handle rendering output (panels, saving views, GUI panels).
- “webgl” serves up interactive, browser-based visualizations of the rendered surfaces.
- “quickflat” looks to provide quick methods for flat mapping cortical surfaces.
- Other files like “options.py”, “utils.py”, “version.py”, and test files underscore the library’s modularity and emphasis on quality and extensibility.
- The integration of an “OpenCTM” directory (with underlying C code and makefiles) signals that there is a native-code component for handling or compressing mesh data that the Python code leverages—likely through Cython bindings (as seen with .pyx and .pxd files).

##### Extract Key Architectural Themes from the README
- The documentation and examples highlight interactive usage in an IPython environment.
- There is an emphasis on rendering quality and interactive exploration, with multiple examples and a dedicated “docs” directory for user, API, and developer documentation.

a. Main Components:
- Data Loader/Adapter Layer: Represented by the “dataset” module with specialized classes (e.g., braindata, view2D, viewRGB) that load and preprocess neuroimaging data.
- Mapping/Processing Engine: Depicted by the “mapper” module (along with components from “polyutils”) that performs the core task of mapping volumetric data onto cortical surfaces.
- Rendering & Visualization Modules:
- “webgl” for browser-based interactive rendering (uses HTML templates, JavaScript libraries such as Three.js, CTM loaders, etc.).
- “quickflat” for rapid flat-map visualizations.
- “blender” submodule may interface with Blender for advanced visualizations.
- Export and Display Interface: The “export” component handles preparing visuals (panels and saved views) for output.
- Core Library & Utilities: The primary “cortex” package which ties everything together, including options, testing utilities, and versioning.
- External/Native Components: The OpenCTM library and associated C/Cython code segments that manage mesh compression/decompression.
- Supportive Elements: Auxiliary directories for tests, documentation, and examples that, while not directly involved in runtime operations, indicate integration points for continuous integration and quality assurance.

b. Relationships and Data Flow:
- Data flows from input (via neuroimaging data loaders) into the mapping engine where volumetric data is processed.
- The mapping engine interacts with both native code (via OpenCTM for surface mesh handling) and pure Python routines.
- Processed data is then passed to visualization tools (“webgl” and “quickflat”) which output to an IPython environment or web browser.
- The export module may work in tandem with mapping and visualization to generate static views or panels.
- Integration with the external environment (e.g., IPython) is noted in the README demo.

c. Architectural Patterns:
- Layered separation of concerns: Data ingestion, processing/mapping, and rendering are clearly separated.
- Use of modular design: Each directory (dataset, mapper, export, etc.) encapsulates a distinct aspect of the functionality.
- Integration of native code (via C/Cython) to optimize performance-critical computations (e.g., mesh handling).
- Extensibility: The structure, including plugins like “blender”, “quickflat” and “webgl”, shows an architecture designed for easy extension and customization.

d. Relevant Technologies:
- Programming Languages/Frameworks: Python (core library), C/Cython (OpenCTM integration), and JavaScript (for WebGL visualizations, with libraries like Three.js).
- Build and Deployment: Use of setup.py, pyproject.toml, and continuous integration workflows (.github/workflows) indicate modern build and deployment practices.
- Documentation: Sphinx and numpydoc are used for automated documentation generation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library & Utilities
    subgraph "Core Library & Utilities"
        C1["__init__.py"]:::core
        C2["options.py"]:::core
        C3["utils.py"]:::core
        C4["version.py"]:::core
    end

    %% Data Ingestion (Dataset Loader)
    subgraph "Data Ingestion (Dataset Loader)"
        D1["braindata.py"]:::data
        D2["dataset.py"]:::data
        D3["view2D.py"]:::data
        D4["viewRGB.py"]:::data
        D5["views.py"]:::data
    end

    %% Mapping & Processing
    subgraph "Mapping & Processing"
        subgraph "Mapping Engine"
            M1["mapper.py"]:::mapping
            M2["line.py"]:::mapping
            M3["patch.py"]:::mapping
            M4["point.py"]:::mapping
            M5["samplers.py"]:::mapping
            M6["volume.py"]:::mapping
        end
        subgraph "Polyutils"
            P1["surface.py"]:::mapping
            P2["exact_geodesic.py"]:::mapping
        end
    end

    %% Rendering & Visualization
    subgraph "Rendering & Visualization"
        subgraph "WebGL Renderer"
            W1["serve.py"]:::render
            W2["view.py"]:::render
            W3["resources"]:::render
        end
        subgraph "Quick-Flat Visualizer"
            Q1["composite.py"]:::render
            Q2["view.py"]:::render
        end
        subgraph "Blender Integration"
            B1["blendlib.py"]:::render
        end
    end

    %% Export & Display
    subgraph "Export & Display"
        E1["panels.py"]:::export
        E2["save_views.py"]:::export
    end

    %% User Interfaces
    subgraph "User Interfaces"
        UI1["IPython Interface"]:::ui
        UI2["Web Browser"]:::ui
    end

    %% External/Native Components
    subgraph "External/Native Components"
        N1["openctm.c"]:::native
        N2["openctm.h"]:::native
        N3["openctm.pyx"]:::native
        N4["openctm.pxd"]:::native
    end

    %% Connections
    C1 --> D1
    D1 --> M1
    M1 --> W1
    M1 --> Q1
    M1 --> B1
    M1 --> E1
    W1 --> UI1
    W1 --> UI2
    M1 --> N1

    %% Styles
    classDef core fill:#f9f,stroke:#333,stroke-width:2px;
    classDef data fill:#ccf,stroke:#333,stroke-width:2px;
    classDef mapping fill:#cfc,stroke:#333,stroke-width:2px;
    classDef render fill:#fc9,stroke:#333,stroke-width:2px;
    classDef export fill:#cff,stroke:#333,stroke-width:2px;
    classDef native fill:#f99,stroke:#333,stroke-width:2px;
    classDef ui fill:#9cf,stroke:#333,stroke-width:2px;

    class C1,C2,C3,C4 core;
    class D1,D2,D3,D4,D5 data;
    class M1,M2,M3,M4,M5,M6,P1,P2 mapping;
    class W1,W2,W3,Q1,Q2,B1 render;
    class E1,E2 export;
    class N1,N2,N3,N4 native;
    class UI1,UI2 ui;

    %% Click Events for Core Library & Utilities
    click C1 "https://github.com/gallantlab/pycortex/blob/main/cortex/__init__.py"
    click C2 "https://github.com/gallantlab/pycortex/blob/main/cortex/options.py"
    click C3 "https://github.com/gallantlab/pycortex/blob/main/cortex/utils.py"
    click C4 "https://github.com/gallantlab/pycortex/blob/main/cortex/version.py"

    %% Click Events for Data Loader/Adapter
    click D1 "https://github.com/gallantlab/pycortex/blob/main/cortex/dataset/braindata.py"
    click D2 "https://github.com/gallantlab/pycortex/blob/main/cortex/dataset/dataset.py"
    click D3 "https://github.com/gallantlab/pycortex/blob/main/cortex/dataset/view2D.py"
    click D4 "https://github.com/gallantlab/pycortex/blob/main/cortex/dataset/viewRGB.py"
    click D5 "https://github.com/gallantlab/pycortex/blob/main/cortex/dataset/views.py"

    %% Click Events for Mapping Engine
    click M1 "https://github.com/gallantlab/pycortex/blob/main/cortex/mapper/mapper.py"
    click M2 "https://github.com/gallantlab/pycortex/blob/main/cortex/mapper/line.py"
    click M3 "https://github.com/gallantlab/pycortex/blob/main/cortex/mapper/patch.py"
    click M4 "https://github.com/gallantlab/pycortex/blob/main/cortex/mapper/point.py"
    click M5 "https://github.com/gallantlab/pycortex/blob/main/cortex/mapper/samplers.py"
    click M6 "https://github.com/gallantlab/pycortex/blob/main/cortex/mapper/volume.py"

    %% Click Events for Polyutils
    click P1 "https://github.com/gallantlab/pycortex/blob/main/cortex/polyutils/surface.py"
    click P2 "https://github.com/gallantlab/pycortex/blob/main/cortex/polyutils/exact_geodesic.py"

    %% Click Events for WebGL Renderer
    click W1 "https://github.com/gallantlab/pycortex/blob/main/cortex/webgl/serve.py"
    click W2 "https://github.com/gallantlab/pycortex/blob/main/cortex/webgl/view.py"
    click W3 "https://github.com/gallantlab/pycortex/tree/main/cortex/webgl/resources"

    %% Click Events for Quick-Flat Visualizer
    click Q1 "https://github.com/gallantlab/pycortex/blob/main/cortex/quickflat/composite.py"
    click Q2 "https://github.com/gallantlab/pycortex/blob/main/cortex/quickflat/view.py"

    %% Click Events for Blender Integration
    click B1 "https://github.com/gallantlab/pycortex/blob/main/cortex/blender/blendlib.py"

    %% Click Events for Export & Display
    click E1 "https://github.com/gallantlab/pycortex/blob/main/cortex/export/panels.py"
    click E2 "https://github.com/gallantlab/pycortex/blob/main/cortex/export/save_views.py"

    %% Click Events for External/Native Components
    click N1 "https://github.com/gallantlab/pycortex/blob/main/OpenCTM-1.0.3/lib/openctm.c"
    click N2 "https://github.com/gallantlab/pycortex/blob/main/OpenCTM-1.0.3/lib/openctm.h"
    click N3 "https://github.com/gallantlab/pycortex/blob/main/cortex/openctm.pyx"
    click N4 "https://github.com/gallantlab/pycortex/blob/main/cortex/openctm.pxd"
```
