= Digitize EEG sensor locations and head shape using 3D scanners =
''Authors: Chinmay Chinara, Wayne Mead, Yash Shashanka Vakilna, Anand Joshi, Takfarinas Medani, Raymundo Cassani, John Mosher, Richard Leahy''

{{{#!wiki important
This page describes the 3D scanner Digitize GUI for the '''legacy''' version <<BR>><<BR>> For the '''2024''' (updated) version, visit: <<BR>>[[https://neuroimage.usc.edu/brainstorm/Tutorials/TutDigitize3dScanner]]
}}}
<<TableOfContents(2,2)>>

== Background ==
This tutorial shows a fast, accurate and automated way of localizing and labeling EEG electrodes from a 3D model that was acquired using [[https://www.revopoint3d.com/products/handheld-3d-scanner-range|Revopoint Range 2]], an affordable and advanced 3D scanner that uses structured light approach for mapping the scalp surface (with the EEG cap on).

The first part of the tutorial covers how to digitize the EEG electrodes from an available 3D model. The second part shows how to use the Revopoint Range 2 3D scanner to capture data.

== Digitize using 3D scanner ==
{{{#!wiki note
Jump to '''[[https://neuroimage.usc.edu/brainstorm/Tutorials/TutDigitize3dScannerLegacy#Acquiring_using_3D_scanner|Acquiring using 3D scanner]]''' section to generate your own data.
}}}
=== Example dataset ===
==== Description ====
This data consists of 3D model of a subject wearing a custom EEG cap [[https://www.ant-neuro.com/products/waveguard-touch|ANT Waveguard 65]] that was captured using the '''Revopoint Range 2''' 3D scanner by the steps mentioned in [[https://neuroimage.usc.edu/brainstorm/Tutorials/TutDigitize3dScanner#Acquiring_using_3D_scanner|Acquiring using 3D scanner]] at The University of Texas Health Science Center at Houston, USA.

==== License ====
This tutorial dataset was obtained at the University of Texas Health Science Center at Houston, USA. It is made available under the [[https://creativecommons.org/licenses/by-nc/4.0/deed.en|Creative Commons Attribution-NonCommercial 4.0 International Public License]]. Any questions regarding the data, please contact: wayne.f.mead@uth.tmc.edu or yash.shashank.vakilna@uth.tmc.edu

==== Files ====
The example dataset can be downloaded from [[https://drive.google.com/file/d/1TyUONrM24NeQukFpkvNDGA-0FaFzgzVz/view?usp=drive_link|here]]. The files that will be imported in this tutorial are the following:

'''sub1_Waveguard_ANT_65/'''

 * '''sub1/sub1_mesh_tex.obj''': The 3D model file.
 * '''sub1/sub1_mesh_tex.jpg''': The texture file associated with the 3D model.
 * '''sub1/sub1_mesh_tex.mtl''': The material file associated with the 3D model.
 * The 3D model has been defaced using [[https://www.meshlab.net/|MeshLab]].

=== Loading the 3D model ===
{{{#!wiki tip
If running from source code, we recommend having '''MATLAB R2018b''' or higher for best performance.
}}}
 1. Create a new protocol called '''Tutorial_Digitizer'''.
 1. Go to '''File>Digitize>3D scanner'''.<<BR>><<BR>> {{attachment:revogui1.png||width="250"}}
 1. Enter the '''Subject ID''' in the pop-up window that opens up. Make sure that it is unique and does not match to any other subject in the same protocol. Name it '''sub1'''.<<BR>><<BR>> {{attachment:revogui2.png||width="300"}}
 1. The subject gets created with the '''Default Anatomy'''.
 1. From the '''Import surfaces...''' window, do the following:
  * File type: '''Wavefront OBJ (*.obj)'''
  * Choose '''sub1_mesh_tex.obj'''
  * Click '''Open'''.<<BR>><<BR>> {{attachment:revogui3_1.png||width="500"}}
  * Adjust the scale factor based on the prompt. This would bring the units of the vertices of the 3D model to the Brainstorm units '''m'''. For this example data, Brainstorm detected that the units were in '''mm''' so choosing '''0.001 '''as the scaling factor would fix the units of the vertices.<<BR>><<BR>> {{attachment:revogui3.png||width="500"}}

 1. The 3D model gets loaded into the protocol for the subject and the Digitize GUI opens up along with the model loaded. The Brainstorm GUI will be hidden during the use of the application and will reappear after exiting the Digitize GUI.<<BR>><<BR>> {{attachment:revogui4.png||width="500"}}
 1. This application allows you to collect:
  * Three head localization coils (HPI) for computing the head coordinate system (optional)
  * Three anatomical landmarks for Sensor-MRI co-registration
  * EEG sensor locations
  * Scalp points for head shape
 1. When complete the coordinates can be saved in a variety of formats including CTF ('''*.pos'''), megDraw ('''*.eeg''') or tab-delimited ASCII text.

=== Configure EEG cap point collection ===
 1. Go to '''File>Edit Settings...'''. This opens up the '''3DScanner configuration''' window. <<BR>><<BR>> {{attachment:revogui5.png||width="500"}}
  * '''Digitize MEG HPI coils:''' This will allow for collection of the positions of the HPI coils. This is important for CTF users since the data collected from the MEG system is saved in HPI coil coordinate system. Users collecting only EEG sensors or just head shape will not collect these points. '''For this example, we set it to 0 as we are just collecting anatomical fiducials'''.
  * '''Number of times to collect the three fiducials:''' These collections will occur at the beginning of the session and will be averaged together to compute the transformation to the HPI or head coordinate system. '''For this example, we set it to 1'''.
  * '''Beep:''' This will generate a beep sound with each point collection (this is often helpful to realize a click while collecting a point from the mesh). '''For this example, we set it to 1'''.

=== Configure EEG montage ===
 1. The next step is to configure EEG montage to select the cap layout we want to select. Brainstorm by default has a bunch of cap layouts already predefined. For this example, we use the '''ANT Waveguard 65''' cap.
 1. Go to '''EEG montage>Add EEG Montage...>Use default EEG cap>ICBM152>ANT>ANT Waveguard 65''' to add load the layout to the '''Coordinates''' section where the collected points will also be updated. <<BR>><<BR>> {{attachment:revogui6.png||width="700"}}

=== Collect the required number of anatomical fiducials ===
 1. Click on the mesh, and press '''Ctrl+P''' to activate collection mode (you will see the mouse cursor change to a crosshair). Click on the desired location on the mesh and '''press key 'C'''' to collect the Nasion, LPA and RPA fiducials in order. Check [[https://neuroimage.usc.edu/brainstorm/CoordinateSystems#Subject_Coordinate_System_.28SCS_.2F_CTF.29|Coordinate Systems]] tutorial for selecting the correct locations. The change can be seen in the '''Coordinates''' panel under each label.
 1. When collecting more than one set of fiducials, an error message is displayed if the difference between the sets is > 5mm
 1. If the MEG HPI coils are not used, then the head coordinate system is computed with the anatomical fiducials and the points are plotted on the 3D point display. Unless the user changes the anatomy for the brainstorm Digitize subject, the default anatomy is used.  It may not match exactly the subject being digitized, but should be a good quality control image to ensure the points are positioned where expected.
 1. Note that the 3D figure is a standard Brainstorm window, where you can use all the mouse operations (rotation, zoom, popup menu) and the keyboard shortcuts (predefined view, screen capture...) introduced in the [[https://neuroimage.usc.edu/brainstorm/Tutorials/ExploreAnatomy#MRI_in_3D|previous tutorials]].
 1. The coordinates are displayed in the coordinate list in '''cm'''
 1. Once the fiducials are collected, the collection automatically moves to EEG positions <<BR>><<BR>> {{attachment:revogui7.png||width="500"}}

=== Collect EEG points ===
 1. Make sure collection mode is active (crosshair visible as per Step-1 in the previous section [[https://neuroimage.usc.edu/brainstorm/Tutorials/TutDigitize3dScannerLegacy#Collect_the_required_number_of_anatomical_fiducials|Collect Anatomical Fiducials]]).
 1. The coordinate list on the left shows the order in which the points should be collected. For this example data, we are going to collect points in the order '''Fpz, T7, T8, Oz,...''' '''all the way to''' '''AFz'''. Click on the desired location on the 3D model and '''press key 'C'''' to collect the point. Once collected, the EEG elctrodes coordinates counter updates in the GUI indicating the next point to be collected. The figures below (top to bottom) show the manual collection of few points Fpz, T7, T8, Oz. <<BR>><<BR>> {{attachment:revogui8.png||width="500"}} <<BR>><<BR>> {{attachment:revogui9.png||width="500"}} <<BR>><<BR>> {{attachment:revogui10.png||width="500"}} <<BR>><<BR>> {{attachment:revogui11.png||width="500"}}
 1. While this is all good, manually marking all the electrodes can be pretty time consuming when done for dense caps like these. You can see that there is this button '''Auto''' which is a feature that enables users to automatically detect and label these electrodes. '''Currently, this is an experimental feature that only supports a few caps so make sure that you verify the results carefully'''.
 1. The way it works is we need a minimal set of manual points as initialization that will help detect the rest of the electrodes. If your cap is supported then hovering on the '''Auto''' button should tell you the set of points that you need to manually collect. For this example, since this cap is supported, on hovering you see that you need to '''collect a minimum of Fpz, T7, T8, Oz''' for the button to be active.<<BR>><<BR>> {{attachment:auto_yes.png||width="400"}} <<BR>><<BR>>If it is not supported you will see a tooltip as under.<<BR>><<BR>> {{attachment:auto_no.png||width="500"}}
 1. Click on '''Auto''' to automatically detect the positions and labels for the sensors on the EEG cap. Click '''Yes''' on the disclaimer that pops up.<<BR>><<BR>> {{attachment:revogui_disclaimer.png||width="400"}} <<BR>><<BR>> {{attachment:revogui12.png||width="500"}}

{{{#!wiki tip
If the electrode detection does not work as expected with those initial marking of electrodes, try to '''manually set few more electrodes''' before pressing the '''Auto''' button.
}}}
=== Edit EEG points ===
If there are any bad detections or misalignments, you can manually select and press '''Delete''' key to delete these points from the Coordinates list and the figure (one at a time). Then in the point selection mode (press '''Ctrl+P''' while on the figure) click on the correct location on the 3D model and '''press key''' '''C''' to remark them manually which also updates in the Coordinates panel. '''Below you can see that FCz is misaligned and how it can be rectified'''.<<BR>><<BR>> {{attachment:edit_eeg.gif||width="600"}}

=== Collect the desired number of head shape points ===
 1. In order to take full advantage of the Sensor-MRI co-registration algorithms in Brainstorm, it is recommended to collect approximately 100-150 points from the head: 5-10 points from the boney part of the nose, 10-15 points across the eyebrows, then an even coverage of the scalp from the eyebrows to the inion. It is NOT recommended to collect points below the inion on the neck, since the shape of the neck can change between lying in the MRI scanner and sitting during point collection. Even coverage is more important that dense coverage.
 1. To automatically choose 150 random points, click on '''Random'''. These can be seen as the green points in the figure and the numbered '''001-150''' in the '''Coordinates '''list on the GUI.<<BR>><<BR>> {{attachment:revogui13.png||width="500"}}
 1. If user wants to add head shape points manually, it can be done by clicking on the figure, and press '''Ctrl+P''' to activate collection mode. Click on the desired location on the 3D model and '''press key 'C'''' to collect. The points '''151-155''' in the figure below were collected manually. <<BR>><<BR>> {{attachment:revogui13_1.png||width="500"}}
 1. Each point is displayed on the 3D points display.
 1. The counter is incremented each time a point is collected and therefore indicates which point will to be collected next.

=== Save ===
 1. The user can save the points to a text file in a variety of formats.
 1. The points can be saved as a '''*.pos''' file for import into CTF datasets or your Brainstorm database. Select '''Save as...''' and confirm the file name and location.
 1. When exiting the program, select '''File > Save and exit''' to ensure the points are saved in the Brainstorm database.

=== View on scalp surface ===
 1. Once saved, go to the functional tab, you can see the channel created under the subject name with all the electrodes assigned. Double click on it to see the electrodes on the default scalp (top row image below). Right click on the channel file, '''MRI Registration>Check''' to see how well the alignment is (bottom row image below). There will be some errors due to the scalp not matching the head shape of the subject.<<BR>><<BR>> {{attachment:revogui14.png||width="500"}}
 1. To align it, right click on the channel file, '''MRI Registration>Refine using head points''' to align it to the default head shape. Refer to  [[https://neuroimage.usc.edu/brainstorm/Tutorials/ChannelFile#Automatic_registration|Automatic Registration]] for more details.<<BR>><<BR>> {{attachment:revogui15.png||width="500"}}

== Acquiring using 3D scanner ==
=== The Hardware ===
Revopoint hardware package comes with the 3D scanner with tripod and a USB to USB-C cable. More details on the hardware can be found [[https://www.revopoint3d.com/pages/handheld-3d-scanner-range2?gad_source=1&gclid=Cj0KCQiAoae5BhCNARIsADVLzZfTqIlo5ySViGtmWObqGSWwp5KbjUmcANTmXzhOZFJkVppVcekxAiMaAq0bEALw_wcB|in their website]].<<BR>> {{attachment:revopoint_range2_scanner.png||width="500"}}

=== System requirements ===
 1. Windows: Windows 10/11 (64-bit)
 1. RAM: 8 GB or better
 1. Processor: Intel Core i5 10th Generation or better
 1. Mac OS X: 10.7+

=== Prepare the EEG cap ===
The EEG cap can be made of shiny materials and these can lead to bad scanning. To reduce the effect of shine make sure to spray it with any commercially available dry shampoo before each subject scan.

=== Prepare the subject ===
 1. Make sure the subject has no glasses on. Since the scanning involves use of flashing white light, the reflections from the glasses could lead to bad scanning.
 1. Minimize structures floating over the cap such as additional wires or hair. If the cap has removable electrodes with exposed wires, scan the cap without electrodes attached. A stocking over the cap can be used if exposed wires cannot be removed.
 1. While the scanning is on, make sure the subject sits as steady as possible and has the eyes closed.

=== Revo Scan software ===
Revopoint uses the '''[[https://www.revopoint3d.com/pages/support-download|Revo Scan]]''' software to do the scanning of a subject wearing EEG cap and generate a 3D model. This model can then be imported into Brainstorm to detect and label the electrodes in it.

==== Installation ====
 1. Download the software from their [[https://www.revopoint3d.com/pages/support-download|webpage]] based on your Operating System (OS).<<BR>><<BR>> {{attachment:revoscan1.png||width="500"}}
 1. Install it by keeping the defaults. After it has finished installing click on '''Complete'''.

==== Start new project ====
 1. Connect the 3D scanner to your PC and launch the '''Revo Scan''' software. It will take few seconds to initialize and show '''Scanner Connected''' as under.<<BR>><<BR>> {{attachment:revoscan3.png||width="500"}}
 1. If you are connecting it for the first time, it might ask for calibration of the device which is a very essential step. Calibrating a Revopoint 3D scanner resets its internal parameters to ensure accurate scanning data and alignment. Follow the onscreen steps and prompts to complete the calibration.
 1. Click on '''New Project''' and give it a '''File Name''' and '''Location'''. Click '''New'''. Make sure to start a new project per subject. <<BR>><<BR>> {{attachment:revoscan4.png||width="400"}}
 1. This should now take you to the scanning window.<<BR>><<BR>> {{attachment:revoscan5.png||width="700"}}

==== Pre-scanning setup (Scan Mode) ====
 1. '''Depth Camera exposure (top left section)''': Use the plus/minus buttons behind the scanner to increase/decrease the exposure. Blue/Red artefacts in this window indicate under/over exposed camera. Use the buttons to adjust the exposure so that there are minimal/no artefacts. For e.g. in the scan below, the exposure of '''1''' was gave underexposed artefacts and increasing it to '''2''' gave good results. This exposure depends largely on the environment your scanning is done in and can vary from case to case.<<BR>><<BR>> {{attachment:revoscan8.png||width="700"}}

 1. '''Scan Settings (right section)''':
  * '''Accuracy:''' High Accuracy
  * '''Tracking Mode:''' Feature Tracking
  * '''Object Type: '''Body
  * '''Color Scanning:''' On
  * '''Base Removal:''' Default (90%)
  * '''Scanning Distance:''' ~ 400 mm to 900 mm<<BR>><<BR>> {{attachment:revoscan9.png||width="200"}}

 1. '''Get a good scanning distance''': Pointing the camera to the subject, move close and away from them. You can see the range meter on the right just to the left of the '''Scan Settings''' going from '''Too Near''' to '''Too Far'''. You want to be in the '''Excellent''' range to get the best results. '''Note/mark this distance to help maintain a scanning range.'''<<BR>><<BR>> {{attachment:revoscan7.png||width="700"}}

==== Scanning ====
From the marked position above, click on the '''Play''' button on the back of the Revopoint to start the scanning. Move the camera continuously with a steady hand, balance speed and stability to improve the quality of your scans. Most scans for the entire head can be accomplished in '''30 seconds'''. The green color on the scanning mesh being generated indicate that the scan is going correctly and in '''Excellent''' range. If otherwise, then pause the scanning at that instant by pressing the '''Play''' button again. There are 2 things that can be done from here:

 * If you want to resume over the same scan, pressing '''Play''' again will resume the scan and automatically start aligning to the already generated scan. This is not recommended as the result might contain a lot of over scanning artefacts.
 * The other option is to click on '''Complete''' button and start a new scan and then later you can choose to merge multiple scans together. This is recommended as this reduces the creation of artefacts.

==== Processing ====
The different buttons available for processing the scanned mesh is shown below.<<BR>><<BR>> {{attachment:revoscan_buttons.png||width="700"}} <<BR>><<BR>>This section does not cover each and every button in details rather the ones that are a minimum requirement for cleaning and processing the scanned 3D model before it can be exported. More details for each of them can be found in the software's [[https://www.revopoint3d.com/pages/support-download?srsltid=AfmBOooBEJmYFCJQeWpPu2k-Erg-99WUwFy0zSIcGq0WJ4Xv7FMdzjB6|User Manual]].

 1. {{attachment:button_fusion.png||width="40"}} '''Fusion''': This merges the raw point cloud mesh to a more unified and accurate point cloud model.
  * '''Fusion Method''': Advanced
  * '''Point distance(mm)''': 1
  * Click on '''Apply'''<<BR>><<BR>> {{attachment:revoscan10.png||width="700"}}
  * Clean the mesh using the clipping tool on the right to remove unwanted mesh area. We do not need any area other than the cap and face.<<BR>><<BR>> {{attachment:revoscan11.png||width="700"}}
 1. {{attachment:button_isolation.png||width="40"}} '''Isolation''': This identifies and removes and floating or noisy points that are isolated from the main point cloud data to make it more clean.
  * '''Isolation Rate''': 50%
  * Click on '''Apply'''
 1. {{attachment:button_overlap.png||width="40"}} '''Overlap Detection''': This is to remove any misalignments or overlapping data in the point cloud for a more accurate and consistent model.
  * '''Overlap distance(mm)''': 3
  * Click on '''Detect'''
 1. {{attachment:button_mesh.png||width="40"}} '''Mesh''': It converts the point cloud data to a solid 3D model.
  * Turn off the color by pressing the color icon {{attachment:iconColor.png||width="30"}} on the top for better visualization of the meshing process
  * '''Quality''': 5.8
  * '''Hole Filling(Auto)''': Turned off
  * Click on '''Apply'''<<BR>><<BR>> {{attachment:revoscan12.png||width="700"}}
 1. {{attachment:button_simplify.png||width="40"}} '''Simplify''': This makes the 3D model more manageable for storage and processing. We do not require a very dense mesh for working with in Brainstorm so anything around 100000-200000 vertices would be sufficient.
  * '''Ratio''': 50%
  * Click on '''Apply'''
 1. {{attachment:button_texture.png||width="40"}} '''Texture Mapping''': Maps the texture to the 3D model
  * Turn on the color back by pressing the grayed out icon {{attachment:iconGray.png||width="30"}} on the top
  * '''Texture''': Color image
  * Click on '''Apply'''<<BR>><<BR>> {{attachment:revoscan13.png||width="700"}}

==== Saving and exporting ====
Click on {{attachment:button_export.png||width="40"}} '''Export>Texture Model''' and save as '''.obj'''. This will save 3 files to the disk:

 * '''.obj''': The 3D model file
 * '''.jpg''': The texture file associated with the 3D model
 * '''.mtl''': The material file associated with the 3D model

== Walkthrough Video ==
=== Digitize using 3D scanner ===
<<HTML(<center><iframe width="640" height="360" src="https://www.youtube.com/embed/65r2j0GRows" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe></center>)>>

== Additional documentation ==
==== Related tutorials ====
 * [[https://neuroimage.usc.edu/brainstorm/Tutorials/TutDigitize|Digitize EEG sensor locations and head shape using Polhemus]]

==== Forum discussions ====
 * [[https://neuroimage.usc.edu/forums/t/digitizing-eeg-sensors-with-3d-scanner-in-brainstorm/47482|Digitizing EEG sensors with 3D scanner in Brainstorm]]
 * [[https://neuroimage.usc.edu/forums/t/import-3d-scanner-digitized-electrode-locations-into-bst/45392|Import 3D scanner digitized electrode locations into BST]]
 * [[https://neuroimage.usc.edu/forums/t/warp-default-anatomy-to-3d-scanner-digitized-eeg-channel-locations/48171/6|Warp default anatomy to 3D scanner digitized EEG channel locations]]

==== Articles ====
 * Simon Homölle, Robert Oostenveld <<BR>> [[https://doi.org/10.1016/j.jneumeth.2019.108378|Using a structured-light 3D scanner to improve EEG source modeling with more accurate electrode positions]]. <<BR>> Journal of Neuroscience Methods, Volume 326, October 2019.