htwangtw/brainbox

BrainBox is a web application that lets you annotate and segment 3D brain imaging data in real time, collaboratively.

BrainBox - A platform for real-time collaboration in neuroimaging

BrainBox is a Web application for the collaborative curation of neuroimaging data available online. You can share, visualise and annotate MRI brain data in real-time, collaboratively. BrainBox will provide the means to create a layer of collaborative annotation over all the available MRI data without having to rely on a centralised data repository or the necessity of having to install software. This manual annotation step is time-consuming but very important: on its correctness depends that the results of any analysis downstream will be sound and accurate. Join us! Your contribution is invaluable!

You can try BrainBox at https://brainbox.pasteur.fr. Log in with your github account and enter the URL to an MRI file you want to visualise, annotate and edit. You can also click one of the examples.

Motivation

We want to make it easy for anyone to participate in open science by launching or participating in collaborative projects using BrainBox. Automatic image-analysis algorithms still very often fail in tasks which are simple for humans. But the explosion in the number of data sets available prevents individual labs from engaging into time-consuming manual editing. This results in a large proportion of shared data not being analysed, wasting time and funding. BrainBox makes it possible to work collaboratively, using real-time interaction on the Web. Like Wikipedia or Google docs, it allows creating distributed research teams to collaborate real-time in the segmentation and annotation of neuroimaging data. No data needs to be downloaded, no software to be installed. All you need is a Web browser.

Our aim is to make BrainBox into a reliable tool for open, reproducible, collaborative science.

Collaboration

We will be happy to work with anyone who would love to join our effort. While you can see in real-time what your collaborators are writing or drawing on a given data set, you can also chat with them, and ask for help or approval of your work. We want to open this scientific process to everyone with any background including citizen scientists and researchers. Join us! Join our segmentation sprint! In our GitHub issue #42 you find detailed information on how to participate and get credit for your work. Currently, we are trying to complete the dolphin brain! Join our team of BrainMappers

And please also feel free to join our efforts on GitHub! Everybody very welcome!

Curious?

More information about BrainBox can be found in our 3 min video on the OpenNeuroLab’s YouTube channel: “Open Neuroimaging Laboratory” And in several smaller specific videos: “Collaborative editing of brain masks in BrainBox” “Collaborative creation of brain masks in BrainBox”

Join us!

Join our project on github any time You can also e-mail us to get in touch at openneurobrainbox at gmail dot com! Or launch your own collaborative project on BrainBox

We are looking forward to meeting you!

Developer instructions

If you want to work on BrainBox's code, you'll need a local installation:

Non docker developer install instructions

1. install and start mongo database
2. clone the repo and cd to the brainbox directory
3. create a new OAuth application for your local brainbox url (http://localhost:3001 by default). Authorization callback URL: http://localhost:3001/auth/github/callback (this may differ between your development/production instances)
4. drop the .example from github-keys.json.example and paste the keys you created into
5. drop the .example from controller/atlasmakerServer/blacklist.json.example
6. drop the .example from controller/atlasmakerServer/whitelist.json.example
7. drop the .example from cfg.json.example
8. npm install
9. npm run prepare
10. npm run build
11. npm start
12. To check that your code style is like the one we use, enter npm run lint, or you can type eslint before committing, to do that install eslint globally using npm i -g eslint (our code style rules are in the file .eslintrc).

Using Docker to install and run BrainBox

These installation instructions may need to be updated.

1. git clone this repository or download it
2. mv BrainBox brainbox to rename the directory
3. cd to brainbox
4. create a new OAuth application for your local brainbox url (http://localhost:3001 by default). Authorization callback URL: http://localhost:3001/auth/github/callback (this may differ between your development/production instances)
5. drop the .example from github-keys.json.example and paste the keys you created into
6. drop the .example from controller/atlasmakerServer/blacklist.json.example
7. drop the .example from controller/atlasmakerServer/whitelist.json.example
8. drop the .example from cfg.json.example
9. make sure Docker is installed
10. docker-compose up
11. Then open http://localhost:3001 in your browser.

If you wish to set up a development environment, make sure to set DEVELOP to "1" and uncomment the 35729 port mapping to have a livereload server running.

Tests

For Docker users, run npm test.

For non-Docker users you will need to ensure puppeteer can run correctly on your local system (please refer to the documentation for information).

Ensure that you are using mongodb<=4.2 (due to an incompatibility between monk and mongodb 4.4 which prevents to exclude a field in a find request) and node>=12.10 (to enable the recursive option to rmdir). Run the command npm mocha-test.

Depending on your local developing settings, if you develop using secure web sockets, you may need to indicate Node the location of your Certification Authority using export NODE_EXTRA_CA_CERTS="/path/to/rootCA.pem"