Open paulbrodersen opened 3 months ago
Thanks @paulbrodersen, much appreciated! Hopefully we will get to improving all of this sometime soon.
Sorry that I have to bail out like this (and pollute your issue tracker in the process with whatever this is), but I have a busy couple of weeks ahead. brainrender
is a neat library, it just needs a little bit more documentation. Best of luck!
I was planning to overhaul the documentation for the
Actor
subclasses. However, this turned out to be more complex than anticipated, so that I have now run out of the time that I am able to contribute for the moment. Below hence three items:I hope some of these will be useful.
A actors.md draft
Objects in 3D renderings are computationally represented as sets of 3D coordinates that form dense meshes, which delineate the surface of the object. Standard neurobiological data formats, however, typically do not specify the surface of their objects directly. For example, an SWC file specifies the morphology of a neuron as a graph of segments, with each segment being represented as a truncated cone with a start point, a diameter at the start point, an end point, and a diameter at the endpoint. So while this specification clearly implies a surface, it does not contain any explicit surface information. Actors in
brainrender
are classes that implement this transformation, i.e. they map user-provided numerical data tovedo Mesh
objects, which can then be rendered.Available actors are:
Point(pos, name, radius, color, alpha, res)
: render a (anterior-posterior, dorsal-vental, medial-lateral) point coordinate as a sphere with a specified name, radius, color, opacity, and resolution. The name is a string used as a handle, when modifying the scene. A color can be a valid matplotlib or VTK color specification, which includes the standard named web colors derived from the CSS Color Module Level 3 standard, hex codes, and RGB tuples. The opacityalpha
is a float between 0 and 1. The integer resolution determines the density of the created mesh. Higher densities result in smoother surfaces (but are computationally more resource intensive).Points(data, name, colors, alpha, radius, res)
: convenience class to render multiplePoint
actors at once. Thedata
argument is either an (N, 3) numpy array or a filepath.radius
andcolors
(plural!) are single floats and valid color specifications, respectively, or lists thereof matching the length of the coordinate array. Due to limitations in upstream packages, however,radius
andcolors
cannot both be sequences. Other parameter specifications are as forPoint
Line(coordinates, color, alpha, linewidth, name)
: render an (N, 3) numpy array of (anterior-posterior, dorsal-vental, medial-lateral) point coordinates as a line.linewidth
is a float; other parameter specifications are as forPoint
.Volume(griddata, voxel_size, cmap, min_quantile, min_value, name, as_surface)
: render volumetric data (e.g. gene expression) from a numpy array or from a .npy file.Neuron(data, color, alpha, neurite_radius, soma_radius, name)
: render neuron morphology data from aMorphoNeuron
object (e.g. instantiated withmorphapi
) or from a .swc file.Streamlines
Cylinder
Ruler
General comments on the documentation
The documentation currently is a weird in-between of a reference and a tutorial, which makes it unhelpful to both audiences, experienced developers and first-time users. Its structure strongly mirrors the structure of the code. However, while it compiles an inventory of available classes and methods, it lacks sufficient detail to be a useful reference. The style is colloquial but it contains no examples and the order in which material is covered doesn't mirror a typical workflow, so it's not a particular useful tutorial either.
To address this tension, I would split the documentation in two: a reference, preferably compiled from overhauled doc-strings, and a guided tour with many, simple examples that covers the topics in the order in which a first time user needs to know about them. For the latter, I would suggest the following structure:
Code comments
General comments
Actor arguments are in dire need of standardisation:
res
,s
)res
parameter even though probably most could/shouldthere are subtle naming differences and inconsistencies:
Point
has thecolor
argument, butPoints
hascolors
even thoughcolors
can be a single color specification. Both have the argumentradius
, which, however, can also be a sequence inPoints
(albeit an undocumented feature)!Actor-specific
Neuron
IIRC, the SWC file standard supports neurite segment start and end thicknesses and soma diameters. As far as I can tell, the implementation, however, does not appear to expect/use that information. If that assessment is mistaken,
neurite_radius
andsoma_radius
should probably be called something else (default_neurite_radius
, etc?).Volume
The
min_quantile
/min_value
argument pair is very difficult to communicate. I would either have a singlethreshold
argument (and let the user compute percentiles). Or, I would followvedo
and havevmin
/vmax
arguments, which would pair better withcmap
and additionally lean on people's familiarity with matplotlib.Streamlines
There is no documentation anywhere on what the basic streamlines data structure entails. Even the
examples/streamlines.py
file downloads data from the ABA. This makes it quite difficult to document the class.ruler
&ruler_from_surface
Why are these functions when all other actors are classes?
Also, I would remove the
unit
andunit_scale
arguments and hardcode "micrometers" asunit
. Currently, coordinates are implicitly in micrometers, but the defaultunit
is the empty string, and theunit_scale
is 1, neither of which communicates this to the user. I would remove the arguments as everything about them is confusing and near-impossible to communicate.Cylinder
Currently, cylinders are hard-coded to be vertical (unless I am missing something). Making the second argument another 3d coordinate (instead of
Scene.root
) would make this class a lot more flexible and easier to explain.