Sep 18, 2025
Version 1
BrainTRACE Registration V.1
- sena oten1,
- Shawn Hervey-Jumper1,
- David Brang2
- 1University of California San Francisco;
- 2University of Michigan
Protocol Citation: sena oten, Shawn Hervey-Jumper, David Brang 2025. BrainTRACE Registration. protocols.io https://dx.doi.org/10.17504/protocols.io.rm7vzj295lx1/v1
License: This is an open access protocol distributed under the terms of the Creative Commons Attribution License, which permits unrestricted use, distribution, and reproduction in any medium, provided the original author and source are credited
Protocol status: Working
We use this protocol and it's working
Created: August 13, 2024
Last Modified: September 18, 2025
Protocol Integer ID: 105226
Keywords: localizing intraoperative electrocorticography, available in neurosurgical workflow, neurosurgical workflow, intraoperative electrocorticography, registration braintrace, subdural grids in patient, guided intraoperative localization, subdural grid, electrode arrays on patient, intraoperative localization, cortical vascular reconstruction, braintrace, intraoperative photograph, need for neuroanatomical context, neuroanatomical context, weighted mri, validation across tumor case, using imaging, brain tumor, specific 3d cortical surface, clinical mapping, electrode array, guided grid initialization, expert rater
Funders Acknowledgements:
NIH Grant
Grant ID: R01DC020717
NIH Grant
Grant ID: R01NS137850
Disclaimer
DISCLAIMER – FOR INFORMATIONAL PURPOSES ONLY; USE AT YOUR OWN RISK
The protocol content here is for informational purposes only and does not constitute legal, medical, clinical, or safety advice, or otherwise; content added to protocols.io is not peer reviewed and may not have undergone a formal approval of any kind. Information presented in this protocol should not substitute for independent professional judgment, advice, diagnosis, or treatment. Any action you take or refrain from taking using or relying upon the information presented here is strictly at your own risk. You agree that neither the Company nor any of the authors, contributors, administrators, or anyone else associated with protocols.io, can be held responsible for your use of the information contained in or linked to this protocol or any of our Sites/Apps and Services.
Abstract
BrainTRACE is a freely available, MATLAB-based workflow for localizing intraoperative electrocorticography (ECoG) subdural grids in patients with brain tumors when post-operative imaging is impractical. The tool fuses pre-operative T1-weighted MRI, cortical vascular reconstructions, and intraoperative photographs to place electrode arrays on patient-specific 3D cortical surfaces. Its GUI supports anatomical/vascular landmark–guided grid initialization, optional import of neuronavigation fiducials, alignment of “grid-on/off” photos, manual per-contact refinement, and BIDS-compliant coordinate export. In validation across tumor cases, expert raters achieved high inter-rater reliability (ICC ≈ 0.93) with mean deviations of ~4 mm from consensus, while novice variability underscores the need for neuroanatomical context. BrainTRACE enables accurate, photograph-guided intraoperative localization to support clinical mapping and research in oncology and epilepsy, using imaging routinely available in neurosurgical workflows.
Troubleshooting
Using FreeSurfer for BrainTRACE (optional)
Open Freeview from Terminal using the bash command terminal
Select your volume file. The brain extraction and T1 have a grayscale color map. The vasculature should be loaded up on a heat map.
Review your images on the FreeSurfer software.
Using the BrainTRACE Software
Download the BrainTRACE software and run it as an app on MATLAB.
The BrainTRACE software accepts both a 2D surface cortical reconstruction and a brain-extracted 3D volumetric model. Users may use a variety of image processing tools to obtain these images. The recommended processing to obtain these images is: (1) using FreeSurfer’s brain extraction tool, (2) ANTs brain extraction tool, or (3) using FreeSurfer’s recon-all-clinical tool.
Adding pial surfaces from recon-all-clinical toolFrom 25 to 35 steps
Select your pial surface. Once you have selected your pial surface (.pial) file from from the recon-all-clinical tool, the GUI will then give a prompt saying "File not found." Click "ok". (Left Side pial surface reconstructions are labeled lh.pial. Right side pial surface reconstructions are labeled rh.pial. Choose the area of interest for your needs. Both lobes can also be loaded into the software.
This will then guide you back into your files for you to select a brain.mgz to match.
This should show you your 3D image on the BrainTRACE software. The GUI will then prompt you to input a dura shrink factor. The dura added on top of the brain is analogous to a shrink wrap around the brain so that when the electrodes are added, they do not fall into the sulci of the brain. Instead, when the electrodes are added, they will sit on top of the dura. The Dura Shrink Factor should be kept at 0.3.
You should end up with a screen similar to the image below.
Using the Brain Grid Software (continued)
Once the file has been selected, use your cursor to rotate around the brain. Further viewing selections, such as zoom in, zoom out, pan, restore, and save, are located in the upper right-hand corner.
Users may toggle elements of display using by clicking the files or control-clicking.
Users no longer need to view the dura and may close the dura view by control-clicking on the dura element.
Users who would like to adjust the isothreshold value for viewing the sulcal anatomy can do so by right clicking on the Brain display element and selecting "Rethreshold MGZ file."
Adding a Vasculature Reconstruction
Users should also use Freeview to preview the vasculature. The color map should be changed to a heat map for optimal viewing. The vasculature should be in bright yellow color. If you hover over or click on any voxel coordinate on the image, you should see an intensity value. These values are important for finding a threshold on your reconstruction image that includes only the vasculature and not the tissue.
The GUI will once again show the user an estimate of where the isovalue threshold should be. In general, this value should be adjusted by the user for optimal anatomically accurate modeling and reduction of artifacts.
Once the threshold value is selected, the GUI will then prompt the user for a transparency value. This is a value of opacity between 0 and 1, with 0 being completely transparent and 1 being completely opaque.
The Vasculature element can be renamed by right-clicking on the "Additional Model #" that represents the vasculature and selecting "Rename."
Adding Electrode Grid Coordinates from Neuronavigation Devices
To add coordinate points onto the cortical surface of the brain, select "Load Additional File" on the upper left side of the GUI.
The coordinates should be formatted onto a .csv file with X, Y, Z coordinates.
Once the threshold value is selected, the GUI will then prompt the user for a transparency value. This is a value of opacity between 0 and 1, with 0 being completely transparent and 1 being completely opaque.
Users should end up with a screen similar to the one below with the brain and coordinate elements selected. Confirm with intraoperative photographs and neuronavigation screenshots that the coordinates are placed correctly.
Adding an Electrode Grid to the Cortical Reconstruction
Select an electrode grid from the dropdown menu or create a grid by pressing the Create Grid button on the left side of the grid.
If creating a new grid, select the "Create Grid" button and create the grid on the pop-up window. You can adjust the label, number of rows, number of columns, the spacing (mm) between, and the positioning of electrode 1. Once the Grid Options have been selected, click on the Generate Grid button.
You can deselect some numbers on the grid contacts if the grid used was not in a rectangle or if some contacts were not positioned on the brain. If so, users can either choose to maintain the original numbering of the electrodes or have the numbering change with the de-selections.
Once the desired grid has been made, select "save." The new electrode grid should be saved on the dropdown menu with the other preset grids.
When the desired electrode grid is selected from the dropdown menu, select the "Place Grid" button. The GUI will prompt you to choose a name for the grid.
The GUI will prompt you to either place the grid based on coordinates or from a point on the model.
Selecting a point on the model14 steps
Select the "Model" button on the pop-up menu. The GUI will prompt you to choose which electrode you would like to place on the model.
The screen will go back to the model. Click on the point where you want the chosen electrode on the grid to land. The rest of the electrodes will be placed relative to that electrode. The grid placement should be chosen with visual anatomic or vascular correspondence to the intraoperative photos. This may take a short amount of time to load.
Adjusting the Location of the Electrode Grid
Once the grid has been roughly placed, millimetric adjustments should be made using the “move electrode grid” controls. This will place the electrode grid at the approximate position, but will not immediately find the vertices on the brain that are closest to each individual electrode.
If the grid needs to be rotated, users should use the “rotate electrode grid” function. Users may rotate the grid at the center of the coordinates, or may pick a single point of rotation the grid along. The latter is useful when one point on the electrode grid has been placed anatomically in the correct location and should not be moved.
While making coordinate adjustments, the grid may lose some of the cardinal axes and some electrode contacts may fall inside the brain while making these movements. Once the electrode grid is placed at a close approximation to the intraoperative image, users should select the option to snap the electrode to the dura to counteract the electrode contacts that have fallen into the tissue.
Adding Multiple Grids
Adding additional grids can be done the same way as adding the initial grid. Grid names can be relabeled on the display elements by right clicking. Grids can also be recolored this way for ease of distinguishing them apart. It is important for users to define which grid they are trying to manipulate on the localization. This can be done by right-clicking on a grid and marking it as the active grid. The current active grid will have an asterisk (*) by its name on the display elements box.
Tips and Troubleshooting
Tip 1: Users can use photo editing platforms (i.e. photoshop, pixlr, etc.) to overlay images of the cortex with and without the electrode grids. For visualization, it can be useful to position the photographs at the same angle as the model. Drawing on the photographs can also be useful to pinpoint exact electrodes and sulci.
Example intraoperative photograph with drawings of vasculature, sulci, and electrodes
Example intraoperative photograph with drawings of electrodes
Example intraoperative photograph with electrodes
Troubleshooting: Error opening up .pial or .mgz files: Do not use any spaces in your folder pathways. It can create an error.
Troubleshooting: Electrodes are getting distorted or are falling into the cortex: To fix this, click snap the electrode to the dura
Troubleshooting: Coordinates from Neuronavigation make the grid look raised up: To fix this, make sure that the screenshots taken were not taken from above the skull. In instances where screenshots were taken where the grid is placed under the dura and is not visible from the intraoperative images, the coordinates taken from the neural navigation tool will distort your grid.
Troubleshooting: The electrode coordinates are not matching up anatomically: This is because there is no way to know the exact boundaries of the brain if we are using arbitrary binary thresholds. The relative curvature of the brain is not going to exactly match the curvature in an intraoperative setting. During surgery, once the skull is taken off, the brain may deform or protrude out if there is intracranial pressure. This additional curvature is not modeled in the preop MRI 3D reconstruction of the brain. To adjust for this, users can change the electrode grid spacing to make the contacts line up with the anatomical locations of the sulci and vasculature.
Tip 2: Image Alignment: aligning intraoperative photos with and without a grid is helpful for determining the exact anatomical location of the grip points. An image alignment tool can be found on our GitHub page attached.
Saving and Exporting Coordinates
Users can save their work by clicking Session --> Save on the upper left-hand corner
Users can export the grid coordinates by clicking "grid coordinates" --> "export grid coordinates". This will save the coordinates as a .csv file. Users can also click "grid coordinates" --> "show grid coordinates" to view the coordinates in real-time. These will show up on the command window in MATLAB.