{"id":22853012,"url":"https://github.com/dipterix/threebrain","last_synced_at":"2025-04-05T05:08:35.614Z","repository":{"id":45896085,"uuid":"173986617","full_name":"dipterix/threeBrain","owner":"dipterix","description":"3D Visualization of Brain MRI","archived":false,"fork":false,"pushed_at":"2025-02-01T03:28:22.000Z","size":184650,"stargazers_count":43,"open_issues_count":1,"forks_count":11,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-05T00:28:30.647Z","etag":null,"topics":["brain","ecog","electroencephalography","ieeg","localization","mri-brain","neuroimaging","r","template-brains"],"latest_commit_sha":null,"homepage":"https://dipterix.org/threeBrain/","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dipterix.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-03-05T16:59:20.000Z","updated_at":"2025-02-01T03:26:23.000Z","dependencies_parsed_at":"2023-02-15T00:16:53.939Z","dependency_job_id":"2d0fed44-6df0-43aa-b5a7-bfc29efcea73","html_url":"https://github.com/dipterix/threeBrain","commit_stats":{"total_commits":566,"total_committers":4,"mean_commits":141.5,"dds":0.3568904593639576,"last_synced_commit":"75e77aec2c8becdd22b3e5abe87a18fc8e69a246"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dipterix%2FthreeBrain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dipterix%2FthreeBrain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dipterix%2FthreeBrain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dipterix%2FthreeBrain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dipterix","download_url":"https://codeload.github.com/dipterix/threeBrain/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247289428,"owners_count":20914464,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["brain","ecog","electroencephalography","ieeg","localization","mri-brain","neuroimaging","r","template-brains"],"created_at":"2024-12-13T06:10:18.139Z","updated_at":"2025-04-05T05:08:35.597Z","avatar_url":"https://github.com/dipterix.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [threeBrain - HTML, WebGL based 3D Viewer](https://dipterix.org/threeBrain/index.html)\n\n\u003c!-- badges: start --\u003e\n[![CRAN_Status_Badge](https://www.r-pkg.org/badges/version/threeBrain)](https://cran.r-project.org/package=threeBrain)\n[![R-CMD-check](https://github.com/dipterix/threeBrain/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/dipterix/threeBrain/actions/workflows/R-CMD-check.yaml)\n[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)\n[![DOI-RAVE](https://raw.githubusercontent.com/dipterix/threeBrain/master/inst/doi.svg)](https://doi.org/10.1016/j.neuroimage.2020.117341)\n[![DOI-YAEL](https://img.shields.io/badge/DOI-10.1523%2FENEURO.0328--23.2023-blue?link=https%3A%2F%2Fdoi.org%2F10.1523%2FENEURO.0328-23.2023)](https://doi.org/10.1523/ENEURO.0328-23.2023)\n\u003c!-- badges: end --\u003e\n\n\u003c!-- demo static: start --\u003e\n[\u003cimg src=\"https://github.com/dipterix/threeBrain/blob/master/adhoc/demo.gif?raw=true\" width=\"100%\" /\u003e](https://youtu.be/dSxJqBiw3sk)\n\n\n\n\u003c!-- demo static: end --\u003e\n\n\u003c!-- demo dynamic: start \n\n\u003ciframe width=\"100%\" height=\"500\" src=\"https://www.youtube.com/embed/dSxJqBiw3sk\" title=\"Yet Another Electrode Localization\" frameborder=\"0\" allow=\"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share\" allowfullscreen\u003e\u003c/iframe\u003e\n\n\u003c!-- demo dynamic: end --\u003e\n\n**Key Features**:\n\n* Uses modern browsers, easy to **embed** and **share**\n* Displays MRI, surfaces, and electrodes in the same canvas\n* **Maps multiple subjects** on template brains using `AFNI/SUMA` (standard 141) or `MNI-305` locations\n* **Electrode localization**\n* Volume rendering and surface/electrode **animation**\n* Integration with interactive `R-shiny` framework\n\n[News](https://dipterix.org/threeBrain/news/index.html) | [reference page](https://dipterix.org/threeBrain/reference/index.html) | [keyboard shortcuts](https://dipterix.org/threeBrain/shortcuts.html)\n\n#### System Requirement\n\n* **Web Browsers**: the viewer uses `WegGL2` to render in browsers. Please check [this list](https://caniuse.com/webgl2) to see compatible browsers. As of 2023, **Chrome**, **Firefox**, **Safari**, and **Edge** (not IE) have full supports.\n\n## A. Installation\n\n1. [`R`](https://cran.r-project.org/) and [`RStudio Desktop (Free Version)`](https://posit.co/download/rstudio-desktop/)\n2. Open `RStudio`, enter from its console:\n```r\ninstall.packages(\"threeBrain\", repos = \"https://rave-ieeg.r-universe.dev\")\n```\nIf you want to install `dev` version from *Github*, then use:\n```r\ninstall.packages(\"remotes\")\nremotes::install_github(\"dipterix/threeBrain\")\n```\n3. (Optional) Setups: after installation, in `RStudio` console, type the following command\n```r\nthreeBrain::brain_setup()\n```\nand follow the instructions.\n\n## B. Basic Brain Viewer\n\nOnce finishing setting up of `threeBrain`, there will be a template subject `N27` (Collin's 27) created locally. The location is platform-related. You can find it by running the following command:\n\n```r\nlibrary(threeBrain)\n\ndefault_template_directory()\n#\u003e [1] \"/Users/dipterix/Library/Application Support/\n#\u003e org.R-project.R/R/threeBrain/templates\"\n```\n\n**N27** template folder resides inside of this directory.\n\nLet's view this subject using the `threeBrain` function.\n\n1. Import subject\n```r\nlibrary(threeBrain)\n\nn27_path \u003c- file.path(default_template_directory(), \"N27\")\n\nx \u003c- threeBrain( path = n27_path,\n  subject_code = 'N27', surface_types = 'pial')\n```\n2. Visualize\n```r\nplot(x)       # alternatively, you can use x$plot()`\n```\n\n## C. Subject Setup\n\nThe sample subject (`N27`) is a sample generated by `FreeSurfer` ([download](https://surfer.nmr.mgh.harvard.edu/fswiki/DownloadAndInstall)). If you have any subjects processed by `FreeSurfer`, use function `threeBrain` to visualize. \n\n## D. Add/Render Electrodes\n\nIf you have electrode file, you can import it before calling `plot` function. Please make sure it's in `csv` format.\n```r\nx$set_electrodes(electrodes = \"[PATH to ELECTRODE FILE]\")\n```\nHere is an example of electrode csv file. Only the first five columns (**case-sensitive**) are mandatory: `Electrode (integer)`, `Coord_x`, `Coord_y`, `Coord_z`, and `Label (character)`. `Coord_*` is `tkRAS` location from `FreeSurfer` coordinates.\n```\n| Electrode| Coord_x| Coord_y| Coord_z|Label  | MNI305_x|  MNI305_y|  MNI305_z|SurfaceElectrode |SurfaceType | Radius| VertexNumber|Hemisphere |\n|---------:|-------:|-------:|-------:|:------|--------:|---------:|---------:|:----------------|:-----------|------:|------------:|:----------|\n|         1|    29.0|    -7.8|   -34.6|RMHCH1 | 30.46817| -17.98119| -23.40022|FALSE            |pial        |      2|           -1|left       |\n|         2|    33.8|    -8.0|   -34.2|RMHCH2 | 35.57109| -17.76624| -22.80131|FALSE            |pial        |      2|           -1|left       |\n|         3|    38.0|    -7.5|   -33.5|RMHCH3 | 39.97102| -16.81249| -22.17986|FALSE            |white       |      2|           -1|right      |\n|         4|    42.6|    -6.8|   -33.0|RMHCH4 | 44.79092| -15.73442| -21.82591|FALSE            |smoothwm    |      2|           -1|right      |\n|         5|    47.0|    -6.8|   -32.6|RMHCH5 | 49.45370| -15.35431| -21.31272|FALSE            |pial        |      2|           -1|right      |\n|         ...\n```\n\nTo assign values to electrodes, run\n```r\nx$set_electrode_values(electrodes = \"[PATH to ELECTRODE VALUE FILE]\")\n```\n\nThe electrode value file is also a csv like:\n\n```\n| Electrode| Subject| Project|    Time| ValueName| ValueName2|  ...|\n|---------:|-------:|-------:|-------:|:---------|----------:|-----|\n|         1|     N27|    Demo|       0|A         |   30.46817|  ...|\n|         2|     N27|    Demo|       0|B         |   35.57109|  ...|\n|         3|     N27|    Demo|       0|C         |   39.97102|  ...|\n|         4|     N27|    Demo|       0|D         |   44.79092|  ...|\n|         5|     N27|    Demo|       0|A         |   49.45370|  ...|\n|         ...\n```\n\n`Project` and `Time` are optional. However, if you are also using [`rave`](https://github.com/beauchamplab/rave), please make sure `Project` exists. If you want to show animation, `Time` is necessary and must be numeric. `ValueName?` can be any characters containing letters (`A-Z`, `a-z`), letters (`0-9`) and underscore (`_`).\n\n\n## E. Merge Subjects and Template mapping\n\nIf you have your own subjects with `FreeSurfer` output, for example, I have two subjects `YAB` and `YCQ`. To merge these two subjects and show them on `N27` template,\n```r\nlibrary(threeBrain)\n\n# yab = ... (see section B for import a single subject)\n# ycq = ...\ntemplate_n27 = merge_brain(yab, ycq, template_subject = 'N27')\n\nplot( template_n27 )\n```\nThe viewer will be in `N27` template, and electrodes of these two subjects can be mapped via `MNI305` (for surface and stereo EEG) or `std.141` (for surface-only).\n\n\n## F. Electrode Localization (`YAEL`)\n\n[YAEL (\"Your Advanced Electrode Localizer)](https://doi.org/10.1523/ENEURO.0328-23.2023) has been integrated into [RAVE (R Analysis and Visualization of iEEG)](https://rave.wiki). Please check our website https://rave.wiki\n\n[Here is a `sfN` poster](https://www.dropbox.com/s/st0cw1aro4kmo2e/2022-poster-sfN-Zhengjia-RAVE_poster-07Nov22.pdf?dl=0)\n\n\n## Citation\n\nTo cite `threeBrain` in publications use:\n\n* Wang, Z., Magnotti, J. F., Zhang, X., \u0026 Beauchamp, M. S. (2023). YAEL: Your Advanced Electrode Localizer. Eneuro, 10(10).\n* Magnotti, J. F., Wang, Z., \u0026 Beauchamp, M. S. (2020). RAVE: Comprehensive open-source software for reproducible analysis and visualization of intracranial EEG data. NeuroImage, 223, 117341.\n\nA BibTeX entry for LaTeX users:\n\n```\n@Article{,\n  title = {{YAEL}: Your Advanced Electrode Localizer},\n  author = {Zhengjia Wang and John F. Magnotti and Xiang Zhang and Michael S. Beauchamp},\n  journal = {Eneuro},\n  year = {2023},\n  volume = {10},\n  number = {10},\n  publisher = {Society for Neuroscience},\n  doi = {10.1523/ENEURO.0328-23.2023},\n}\n@Article{,\n  title = {{RAVE}: Comprehensive open-source software for reproducible analysis and visualization of intracranial EEG data},\n  author = {John F. Magnotti and Zhengjia Wang and Michael S. Beauchamp},\n  journal = {NeuroImage},\n  year = {2020},\n  volume = {223},\n  doi = {10.1016/j.neuroimage.2020.117341},\n  pages = {117341},\n}\n```\n\n## License\n\nThe front-end viewer (JavaScript) is licensed under MPL-2.0 free open-source license. Using the generated viewers or incorporating the existing viewers as a whole into your own work \"as-is\" is permissive. \n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdipterix%2Fthreebrain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdipterix%2Fthreebrain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdipterix%2Fthreebrain/lists"}