Readme Overhaul

README.md

@@ -1,67 +1,91 @@
+# BrainRender
 
-# Brainrender
-<p align="center">
-  <img width="1200" src="https://raw.githubusercontent.com/brainglobe/brainrender/main/imgs/three_atlases.png">
-</p>
+*A user-friendly python library to create high-quality, 3D neuro-anatomical renderings combining data from publicly available brain atlases with user-generated experimental data.*
 
 [![Python Version](https://img.shields.io/pypi/pyversions/brainrender.svg)](https://pypi.org/project/brainrender)
 [![PyPI](https://img.shields.io/pypi/v/brainrender.svg)](https://pypi.org/project/brainrender)
 [![tests](https://github.com/brainglobe/brainrender/workflows/tests/badge.svg)](https://github.com/brainglobe/brainrender/actions)
 [![codecov](https://codecov.io/gh/brainglobe/brainrender/graph/badge.svg)](https://codecov.io/gh/brainglobe/brainrender)
-[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
-[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/python/black)
+[![Downloads](https://static.pepy.tech/badge/brainrender)](https://pepy.tech/project/brainrender)
 
+&nbsp;
+&nbsp;
 
-**`brainrender` is a python package for the visualization of three dimensional neuro-anatomical data. It can be used to render data from publicly available data set (e.g. Allen Brain atlas) as well as user generated experimental data. The goal of brainrender is to facilitate the exploration and dissemination of neuro-anatomical data by providing a user-friendly platform to create high-quality 3D renderings.**
+![Example gallery](https://iiif.elifesciences.org/lax/65751%2Felife-65751-fig3-v3.tif/full/,1500/0/default.jpg)
 
-## Docs
-:books: [brainrender docs](https://brainglobe.info/documentation/brainrender/index.html)
+From: Claudi et al. (2021) Visualizing anatomically registered data with brainrender. eLife
+
+
+## Documentation
+
+BrainRender is a project of the BrainGlobe Initiative, which is a collaborative effort to develop a suite of Python-based software tools for computational neuroanatomy. A comprehensive online documentation for brainrender can be found on the BrainGlobe website [here](https://brainglobe.info/documentation/brainrender/index.html).
+
+Furthermore, an open-access journal article describing BrainRender has been published in eLife, available [here](https://doi.org/10.7554/eLife.65751).
 
-📖 [brainrender paper](https://doi.org/10.7554/eLife.65751)
 
 ## Installation
-You can [install `brainrender`](https://brainglobe.info/documentation/brainrender/installation.html) with:
+
+From PyPI:
 
 ```
 pip install brainrender
 ```
 
-## Contributing
-Contributions to brainrender are more than welcome. Please see the [developers guide](https://brainglobe.info/community/developers/index.html). Note that some tests are only run locally, by specifying `--runslow --runlocal` in `pytest`.
+If you encounter any issues, please consult our troubleshooting guide [here](https://brainglobe.info/documentation/brainrender/installation.html).
+
+
+## Quickstart
+
+``` python
+from brainrender import Scene
+from brainrender.actors import Neuron
+
+# Display the Allen Brain mouse atlas.
+scene = Scene(atlas_name="allen_mouse_25um")
+
+# Highlight the cerebral cortex.
+scene.add_brain_region("CTX", alpha=0.2, color="green")
+
+# Add a neuron morphological reconstruction,
+# with coordinates pre-registered to the Allen Brain Atlas.
+neuron = Neuron("/path/to/neuron/morphology.swc")
+scene.add(neuron)
+
+# Display the figure.
+scene.render()
+
+# Export to PNG.
+scene.screenshot("figure.png")
+
+# Export to HTML.
+scene.screenshot("figure.html")
 
-## Citing brainrender
-If you use `brainrender` in your work, please cite:
+```
+
+## Citing BrainRender
+
+If you use BrainRender in your scientific work, please cite:
 ```
 Claudi, F., Tyson, A. L., Petrucco, L., Margrie, T.W., Portugues, R.,  Branco, T. (2021) "Visualizing anatomically registered data with Brainrender&quot; <i>eLife</i> 2021;10:e65751 [doi.org/10.7554/eLife.65751](https://doi.org/10.7554/eLife.65751)
 ```
 
-## Examples
-The following images were created for the publication of the [brainrender paper](https://doi.org/10.7554/eLife.65751). References to the original data being visualised can also be found in the paper.
-
-<p align="center">
-<img src='https://raw.githubusercontent.com/brainglobe/brainrender/main/imgs/cellfinder_cells_3.png' width=500 style='margin:auto'></img>
-</p>
-<p align="center">
-<img src='https://raw.githubusercontent.com/brainglobe/brainrender/main/imgs/gene_expression.png' width=500 style='margin:auto'></img>
-</p>
-<p align="center">
-<img src='https://raw.githubusercontent.com/brainglobe/brainrender/main/imgs/human_regions.png' width=500 style='margin:auto'></img>
-</p>
-<p align="center">
-<img src='https://raw.githubusercontent.com/brainglobe/brainrender/main/imgs/injection_2.png' width=500 style='margin:auto'></img>
-</p>
-<p align="center">
-<img src='https://raw.githubusercontent.com/brainglobe/brainrender/main/imgs/mouse_neurons_2.png' width=500 style='margin:auto'></img>
-</p>
-<p align="center">
-<img src='https://raw.githubusercontent.com/brainglobe/brainrender/main/imgs/probes.png' width=500 style='margin:auto'></img>
-</p>
-<p align="center">
-<img src='https://raw.githubusercontent.com/brainglobe/brainrender/main/imgs/zfish_functional_clusters_2.png' width=500 style='margin:auto'></img>
-</p>
-<p align="center">
-<img src='https://raw.githubusercontent.com/brainglobe/brainrender/main/imgs/zfish_neurons.png' width=500 style='margin:auto'></img>
-</p>
-<p align="center">
-<img src='https://raw.githubusercontent.com/brainglobe/brainrender/main/imgs/zfish_regions.png' width=500 style='margin:auto'></img>
-</p>
+BibTeX:
+
+``` bibtex
+@article{Claudi2021,
+author = {Claudi, Federico and Tyson, Adam L. and Petrucco, Luigi and Margrie, Troy W. and Portugues, Ruben and Branco, Tiago},
+doi = {10.7554/eLife.65751},
+issn = {2050084X},
+journal = {eLife},
+pages = {1--16},
+pmid = {33739286},
+title = {{Visualizing anatomically registered data with brainrender}},
+volume = {10},
+year = {2021}
+}
+
+```
+
+## Contributing
+
+Contributions to brainrender are more than welcome. Please see the [developers guide](https://brainglobe.info/community/developers/index.html). Note that some tests are only run locally, by specifying `--runslow --runlocal` in `pytest`.