ReadMe.md 6.35 KB
Newer Older
Satrajit Ghosh's avatar
Satrajit Ghosh committed
1

Roberto Toro's avatar
Roberto Toro committed
2
[![CircleCI](https://circleci.com/gh/neuroanatomy/BrainBox/tree/master.svg?style=shield)](https://circleci.com/gh/neuroanatomy/BrainBox/tree/master) [![Join the chat at https://gitter.im/OpenNeuroLab-Brainbox/Lobby](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/OpenNeuroLab-Brainbox/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
Roberto Toro's avatar
Roberto Toro committed
3

r03ert0's avatar
r03ert0 committed
4
# BrainBox - A platform for real-time collaboration in neuroimaging
Roberto Toro's avatar
Roberto Toro committed
5

The Gitter Badger's avatar
The Gitter Badger committed
6 7
[![Join the chat at https://gitter.im/OpenNeuroLab-Brainbox/Lobby](https://badges.gitter.im/OpenNeuroLab-Brainbox/Lobby.svg)](https://gitter.im/OpenNeuroLab-Brainbox/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

Roberto Toro's avatar
Roberto Toro committed
8
BrainBox is a Web application for the collaborative curation of neuroimaging data
katjaq's avatar
katjaq committed
9 10
 available online. You can share, visualise and annotate MRI brain
 data in real-time, collaboratively. BrainBox will provide the means to create a
11 12
 layer of collaborative annotation over all the available MRI data without
 having to rely on a centralised data repository or the necessity of
katjaq's avatar
katjaq committed
13 14 15 16
 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!**
17

katjaq's avatar
katjaq committed
18
You can try BrainBox at http://brainbox.pasteur.fr. Log in with your github
19
account and enter the URL to an MRI file you want to visualise, annotate
20 21
and edit. You can also click one of the examples.

katja heuer's avatar
katja heuer committed
22 23
![](https://user-images.githubusercontent.com/6297454/32104270-96db0afa-bb1b-11e7-8911-786d420c308a.png)

24

katjaq's avatar
katjaq committed
25 26
#### Motivation  

katja heuer's avatar
katja heuer committed
27
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.
katjaq's avatar
katjaq committed
28 29 30 31 32 33 34
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  

katja heuer's avatar
katja heuer committed
35 36
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!
katja heuer's avatar
katja heuer committed
37
**Join our segmentation sprint!** In our [GitHub issue #42](https://github.com/neuroanatomy/BrainBox/issues/177) 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](https://github.com/neuroanatomy/BrainBox/blob/master/BrainMappers.md)
katjaq's avatar
katjaq committed
38

katja heuer's avatar
katja heuer committed
39
And please also feel free to join our efforts on GitHub! Everybody very welcome!
katjaq's avatar
katjaq committed
40 41 42 43 44 45 46 47 48 49


#### Curious?  

More information about BrainBox can be found in our 3 min video on the OpenNeuroLab’s YouTube channel:
[“Open Neuroimaging Laboratory”](https://m.youtube.com/watch?v=kwsLoVKnw24)
And in several smaller specific videos:
[“Collaborative editing of brain masks in BrainBox”](https://m.youtube.com/watch?v=bFHXS-lya5M)
[“Collaborative creation of brain masks in BrainBox”](https://m.youtube.com/watch?v=mN0vGpy5kFg)

katja heuer's avatar
katja heuer committed
50 51 52 53 54 55
<!--
<a href="http://www.youtube.com/watch?feature=player_embedded&v=kwsLoVKnw24
" target="_blank"><img src="http://img.youtube.com/vi/kwsLoVKnw24/0.jpg" 
alt="IMAGE ALT TEXT HERE" width="640" height="480" border="10" /></a>
-->

katjaq's avatar
katjaq committed
56 57
#### Join us!  

katja heuer's avatar
katja heuer committed
58
Join our project on github any time
katjaq's avatar
katjaq committed
59 60 61 62
You can also e-mail us to get in touch at openneurobrainbox at gmail dot com!
Or launch your own collaborative project on [BrainBox](http://brainbox.pasteur.fr/project/new)


katja heuer's avatar
katja heuer committed
63
**We are looking forward to meeting you!**
katjaq's avatar
katjaq committed
64 65


katjaq's avatar
katjaq committed
66

67
# Developer instructions
Roberto Toro's avatar
Roberto Toro committed
68 69

If you want to work on BrainBox's code, you'll need a local installation:
Satrajit Ghosh's avatar
Satrajit Ghosh committed
70

katjaq's avatar
katjaq committed
71 72 73 74 75 76 77

## Non docker developer install instructions

1. install and start `mongo` database
2. clone the repo and `cd` to the brainbox directory
4. [create a new OAuth application](https://github.com/settings/applications/new) for your local brainbox url (http://localhost:3000 by default)
5. paste the keys into the github-keys.json.example file, and drop the .example
78 79
6. drop the `.example` from `controller/atlasmakerServer/blacklist.json.example`
7. drop the `.example` from `controller/atlasmakerServer/whitelist.json.example`
katjaq's avatar
katjaq committed
80 81 82 83 84 85 86 87 88
8. drop the `.example` from `blacklist.json.example`
9. drop the `.example` from `whitelist.json.example`
10. `npm install`
11. `npm run prepare`
12. `npm run build`
13. `npm start`
14. 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`).


89
## Using Docker to install and run BrainBox
katjaq's avatar
katjaq committed
90
These installation instructions may need to be updated.  
91

Satrajit Ghosh's avatar
Satrajit Ghosh committed
92
1. `git clone` this repository or download it
93
2. `mv BrainBox brainbox` to rename the directory
94
3. `cd` to brainbox
95
4. [create a new OAuth application](https://github.com/settings/applications/new) for your local brainbox url (http://localhost:3000 by default)
Dylan Nielson's avatar
Dylan Nielson committed
96
5. paste the keys into the github-keys.json.example file, change the `callbackURL` to `"http://localhost:3000/auth/github/callback"` and drop the .example
97 98
6. drop the `.example` from `controller/atlasmakerServer/blacklist.json.example`
7. drop the `.example` from `controller/atlasmakerServer/whitelist.json.example`
99 100 101
7. make sure Docker is installed
8. `docker-compose up`
9. Then open `http://localhost:3000` in your browser.
102

iain8's avatar
iain8 committed
103 104 105 106 107 108

## Tests

For Docker users first start the containers with `docker-compose up -d`, then 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](https://github.com/GoogleChrome/puppeteer) for information). Then run the command `npm mocha-test`.
109