{
  "cells": [
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "%matplotlib inline"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n\n# Tutorial 2: Types of Surfaces\n\nThis tutorial covers what types of surfaces that can be plotted with \n``surfplot``. \n\n## Types of surfaces\n\nPut briefly, ``surfplot`` can take file paths to any valid surface file(s) \nwith geometry data. Under the hood, :class:`~surfplot.plotting.Plot` runs \n:func:`brainspace.mesh.mesh_io.read_surface` to load files. Typically, these\nwill be Freesurfer or GIFTI files. \n\n:class:`~brainspace.plottingPlot` can also read instances of \n:class:`brainspace.vtk_interface.wrappers.data_object.BSPolyData`, which are \nreturned by :func:`read_surface`. So, pre-loaded surfaces with \n:func:`read_surface` can be plotted as well.\n\nBeyond that, ``surfplot`` is invariant to the actual brain surfaces you wish\nto use. Common human surfaces include `fsaverage` surfaces packaged with \nFreesurfer, and Human Connectome Project `fsLR` surfaces ([downloadable here](https://balsa.wustl.edu/reference/show/pkXDZ)). Several different \nhuman surfaces can also all be found on OSF [here](https://osf.io/4mw3a/). \nNon-human surfaces can also be plotted, such as the [NMTv2 Macaque surfaces](https://afni.nimh.nih.gov/pub/dist/doc/htmldoc/nonhuman/macaque_tempatl/template_nmtv2.html).\n\nNote that throughout these tutorials, surfaces are automatically fetched using\n``neuromaps`` or  ``Brainspace`` to avoid having to specify local files. It\nis also possible to [fetch fsaverage surfaces](https://nilearn.github.io/modules/generated/nilearn.datasets.fetch_surf_fsaverage.html#nilearn.datasets.fetch_surf_fsaverage)\nusing ``nilearn``. These are all great options to automically get surfaces in\nyour workflow, and make reproducibility and portability of your code a bit \nmore feasible.\n\n<div class=\"alert alert-info\"><h4>Note</h4><p>Make sure to *always* use the correct surface for your data. Double check \n    the number of vertices in both your data and the surfaces you are using for\n    plotting.</p></div>\n\nIn `sphx_glr_auto_examples_plot_tutorial_01.py` we plotted `fsLR` \nsurfaces. For the sake of demonstration, let's plot Freesurfer's `fsaverage` \nhere, again using ``neuromaps`` fetching functions.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from neuromaps.datasets import fetch_fsaverage\nfrom surfplot import Plot\n\nsurfaces = fetch_fsaverage(density='164k')\nlh, rh = surfaces['inflated']\n\n# make figure\np = Plot(lh, rh)\nfig = p.build()\nfig.show()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Brightness\n\nBy default, :class:`~brainspace.plotting.Plot` will plot a medium-gray surface, \ntypical of most surface plotting packages like Connectome Workbench. The \nbrightness of the blank surface can be adjusted using the `brightness` \nparameter, if desired. Values range from 0 (black) to 1 (white). For example:  \n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "p = Plot(lh, rh, brightness=.8)\nfig = p.build()\nfig.show()"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.8.15"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}