A toolkit for annotating contours and boundaries on the cortical surface.
Noah C. Benson <nben@uw.edu>
The cortex-annotate repository is designed to be an easy-to-use toolkit for
MRI researchers who study the human brain to annotate boundaries and contours on
the cortical surface. Because any two research projects that require boundaries
or annotations are unlikely to be substantially similar, the toolkit is highly
flexible and must be customized using a standard file that combines yaml and
Python.
The cortex-annotate tool has been designed to make publicly storing datasets
of contours straightforward. This design is based on the workflow developed for
the hcp-annot-vc repository. A
typical workflow for the use of cortex-annotate to annotate a single brain
area as part of a project proceeds as follows:
- The project lead forks the
cortex-annotaterepository and edits the forked repository to document relevant metadata (name, description, etc.). This forked repository becomes the main repository for the specific annotation project.- As part of the customization, the project lead will edit the
config/config.yamlfile, which contains all the configuration details for dataset that is to be annotated by the tool. - In particular, this configuration file will include all the relevant Python
code for creating 2D projections or flatmaps of the brain on which the
contours are drawn; see the README in the
configdirectory of this repository for more information.
- As part of the customization, the project lead will edit the
- Once the forked repository has been customized, individual GitHub users will fork the main repository into their own GitHub accounts.
- Each individual user then clones their fork of the main repository on
their local computers and runs the
docker-compose upcommand. This starts a docker container that runs a Jupyter notebook containing the annotation tool itself. The tool reads from theconfig/config.yamlfile to determine how to present the relevant relevant annotation images. - Individual users interact with the annotation tool in the Jupyter notebook
using the mouse and a few keys to click on contours points. These contours
are saved into JSON files in the repository directory; the file names are
specified in the
config/config.yamlfile, and the directory is determined in part by the users's GitHub username. - When a user has finished (or partially finished) annotating the dataset, they
exit the tool and can submit their contours to their GitHub repository using
git commitandgit push. When they are finished with their contours, they can open a pull request to thedatabranch of the main repository in order to submit their annotations back to the project lead. Because the annotations are placed in thedatabranch, themainbranch remains clean and can be quickly forked by new annotators.