Readme Overhaul

README.md

@@ -1,67 +1,111 @@
+# 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 ask a question on the [image.sc forum](https://forum.image.sc/tag/brainglobe) tagging your question with `brainglobe`.
+
+
+## Quickstart
+
+``` python
+import random
+
+import numpy as np
+
+from brainrender import Scene
+from brainrender.actors import Points
+
+def get_n_random_points_in_region(region, N):
+    """
+    Gets N random points inside (or on the surface) of a mesh
+    """
+
+    region_bounds = region.mesh.bounds()
+    X = np.random.randint(region_bounds[0], region_bounds[1], size=10000)
+    Y = np.random.randint(region_bounds[2], region_bounds[3], size=10000)
+    Z = np.random.randint(region_bounds[4], region_bounds[5], size=10000)
+    pts = [[x, y, z] for x, y, z in zip(X, Y, Z)]
+
+    ipts = region.mesh.inside_points(pts).coordinates
+    return np.vstack(random.choices(ipts, k=N))
+
+
+# Display the Allen Brain mouse atlas.
+scene = Scene(atlas_name="allen_mouse_25um", title="Cells in primary visual cortex")
+
+# Display a brain region
+primary_visual = scene.add_brain_region("VISp", alpha=0.2)
+
+# Get a numpy array with (fake) coordinates of some labelled cells
+coordinates = get_n_random_points_in_region(primary_visual, 2000)
+
+# Create a Points actor
+cells = Points(coordinates)
+
+# Add to scene
+scene.add(cells)
+
+# Add label to the brain region
+scene.add_label(primary_visual, "Primary visual cortex")
+
+# Display the figure.
+scene.render()
+
+```
 
 ## Citing brainrender
-If you use `brainrender` in your work, please cite:
+
+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`.