Brayns  0.6.1
Hardware Agnostic Ray-Tracer
UserGuide.md
1 # Brayns user guide
2 
3 ## Basic usage
4 
5 Brayns takes any number of files or folders as argument. To open a single file:
6 ```
7 braynsViewer model.obj
8 ```
9 
10 Alternatively, to open all supported files in a folder:
11 ```
12 braynsViewer ~/datasets/
13 ```
14 
15 ## Neurons
16 
17 ### Loading individual morphologies
18 
19 SWC or H5 morphology files (supported by the
20 [Brion](https://github.com/BlueBrain/Brion) library) can be loaded easily.
21 
22 ```
23 braynsViewer ~/morphologies
24 ```
25 
26 ### Loading a NEURON simulation
27 
28 BlueConfig or CircuitConfig files (supported by the Brion library) can be
29 loaded. The ```--circuit-targets``` command line argument specifies the circuit target
30 (or multiples separated by comma), and the ```--circuit-report``` command line
31 argument specifies the simulation report to be rendered.
32 
33 Example of how to load a circuit with voltages simulation for layer 1 cells:
34 
35 ```
36 braynsViewer ~/circuits/BlueConfig --circuit-targets Layer1 --circuit-report voltages
37 ```
38 
39 ![Layer1](images/Layer1.png)
40 
41 #### Bounding box
42 
43 Defining a bounding box will prevent any geometry located outside of the box
44 from being loaded. The ```--circuit-bounding-box``` command line argument takes six
45 float values. The first three values being the lower bound of the box, and the
46 next three values defining the upper bound.
47 
48 Example of how to define a circuit bounding box:
49 ```
50 braynsViewer ~/circuits/BlueConfig --circuit-bounding-box -100 -100 -100 100 100 100
51 ```
52 
53 #### Density
54 
55 The ```--circuit-density``` command line argument defines how many of the circuit
56 cells should be loaded. For example, if a density of 5 is specified, one cell
57 in 20 will be loaded. Brayns reads the cells in GID order.
58 
59 Example of how to load 10% of the circuit:
60 ```
61 braynsViewer ~/circuits/BlueConfig --circuit-density 10
62 ```
63 
64 ### Loading a NEST simulation
65 
66 The ```--nest-config``` command line argument define the NEST circuit to be loaded by
67 Brayns. The ```--nest-report``` command line argument specifies the report to be
68 rendered. The ```--nest-cache-file``` command line argument needs to be specified in
69 order to generate the cache file that Brayns uses to render the simulation. If
70 the simulation cache file already exists, Brayns connects to it. If it does not,
71  Brayns creates it.
72 
73 ### Options
74 
75 #### Layout
76 When loading several morphologies, Brayns allows the user to position them with
77 a specific layout. Typically, the user might want to visualize cells next to
78 each other. The ```--morphology-layout``` command line argument specifies the number
79 of cells per line, as well as the horizontal and vertical spacing between each
80 of those cells. Units used for the horizontal and vertical spacing are the ones
81 from the H5 and SWC files.
82 
83 ```
84 braynsViewer ~/morphologies --morphology-layout 5 100 100
85 ```
86 
87 #### Section types
88 
89 Brayns allows the user to specify which section type of the morpholoy should be
90 loaded. Sections type are soma, axon, dendrite and apical dendrite. Those types
91 can be combined together by adding their corresponding values (1 for the soma,
92 2 for the Axon, 4 for dendrites and 8 for apical dendrites). For example, if one
93 wants to visualize the somas and the axons, the ```--morphology-section-types```
94 command line argument should then be set to 3.
95 
96 ```
97 braynsViewer ~/morphologies --morphology-section-types 3
98 ```
99 
100 ![SectionTypes](images/SectionTypesAxonSoma.png)
101 
102 ```
103 braynsViewer ~/morphologies --morphology-section-types 5
104 ```
105 
106 ![SectionTypesSomaDendrites](images/SectionTypesAxonDendrites.png)
107 
108 ```
109 braynsViewer ~/morphologies --morphology-section-types 9
110 ```
111 
112 ![SectionTypesSomaApicalDendrites](images/SectionTypesAxonApicalDendrites.png)
113 
114 #### Geometry quality
115 
116 Brayns supports three quality levels for morphologies. The low quality draws
117 one line per section, the medium quality divides the number of segment by 4, and
118 the high quality renders the full morphology.
119 
120 ```
121 braynsViewer ~/morphologies --geometry-quality low
122 ```
123 
124 ![GeometryQualityLow](images/GeometryQualityLow.png)
125 
126 
127 ```
128 braynsViewer ~/morphologies --geometry-quality medium
129 ```
130 
131 ![GeometryQualityMedium](images/GeometryQualityMedium.png)
132 
133 
134 ```
135 braynsViewer ~/morphologies --geometry-quality high
136 ```
137 
138 ![GeometryQualityHigh](images/GeometryQualityHigh.png)
139 
140 #### Radius multiplier
141 
142 The ```--radius-multiplier``` command line parameters specifies the multiplier applied
143 to morphology radii. Typically, a value of 3 multiplies all radii by 3.
144 
145 ```
146 braynsViewer ~/morphologies --radius-multiplier 3
147 ```
148 
149 ![RadiusMultiplier](images/RadiusMultiplier3.png)
150 
151 #### Radius correction
152 
153 The ```--radius-correction``` command line parameters specifies a unique radius
154 applied to all segments of the morphology. The unit is the one of the loaded
155 H5/SWC files.
156 
157 ```
158 braynsViewer ~/morphologies --radius-correction 1
159 ```
160 
161 ![RadiusCorrection](images/RadiusCorrection1.png)
162 
163 #### Color scheme
164 
165 The ```--color-scheme``` command line argument specifies how materials are applied to
166 the morphology. Available values are:
167 
168 | Argument | Description
169 | ---------------------| -------------
170 | neuron-by-id | Each neuron has a different color
171 | neuron-by-segment-id | Somas are white, axons are blue, dendrites are red, and apical dendrites are purple
172 | neuron-by-layer | A different color is assigned for every layer. All neurons belonging to a specific layer as the same color
173 | neuron-by-mtype | Each morphological type has a different color
174 | neuron-by-etype | Each electro-physiologic type has a different color
175 | protein-by-id | Each protein has a different color
176 | protein-atoms | Atoms have standard colors
177 | protein-chains | Each chain has a different color
178 
179 ```
180 braynsViewer ~/morphologies --color-scheme neuron-by-id
181 ```
182 
183 ![ColorSchemeNeuronById](images/ColorSchemeID.png)
184 
185 ```
186 braynsViewer ~/morphologies --color-scheme neuron-by-segment-type
187 ```
188 
189 ![ColorSchemeNeuronBySegmentType](images/ColorSchemeSegmentType.png)
190 
191 #### Realistic somas
192 
193 Command line arguments starting with metaballs tell Brayns to reconstruct somas using the metaballs algorithm. The ```--metaballs-grid-size``` command line
194 argument defines the precision of the generated mesh. The ```--metaballs-threshold```
195 command line argument specifies the threshold for the isosurface defined by
196 function [f(x,y,z) = x^2 + y^2 + z^2]. The ```--metaballs-samples-from-soma```
197 command line argument defines how many samples from around the soma should be
198 considered when generating the mesh.
199 
200 ```
201 braynsViewer ~/morphologies --metaballs-grid-size 60 --metaballs-threshold 1 --metaballs-samples-from-soma 5
202 ```
203 
204 ![EnhancedSomas](images/EnhancedSoma.png)
205 
206 ## Molecules
207 
208 ### Loading a single molecule
209 
210 PDB files can be easily loaded:
211 
212 ```
213 braynsViewer 4IMY.pdb
214 ```
215 
216 ![PDBFile](images/PDBFile.png)
217 
218 ### Loading molecules from folder
219 
220 Loads all PDB file located in the specified folder:
221 
222 ```
223 braynsViewer ~/hiv --color-scheme protein-chains
224 ```
225 
226 ![PDBFolder](images/PDBFolder.png)
227 
228 ## Meshes
229 
230 ### Loading meshes
231 
232 Brayns can load file formats supported by the [assimp](https://github.com/assimp/assimp) library.
233 
234 ```
235 braynsViewer ~/meshes
236 ```
237 
238 ![Mesh](images/Mesh.png)
239 
240 ## Point cloud
241 
242 A XYZ file is a binary encoded list of x,y and z double positions.
243 
244 ```
245 braynsViewer sample.xyz
246 ```
247 
248 ## Cache file
249 
250 In order to accelerate the loading of large scenes, models can be dumped into
251 binary files that can then be reloaded by Brayns. The ```--save-cache-file``` command
252 line argument specifies the filename of the file into which the 3D scene should
253 be saved. The ```--load-cache-file``` command line argument specifies the file to be
254 loaded by Brayns. Note that cache files are only supported by the OSPRay engine.
255 Any other command line parameter defining a data source will be ignored by
256 Brayns.
257 
258 ```
259 braynsViewer --save-cache-file cache
260 braynsViewer --load-cache-file cache
261 ```
262 
263 ## Volumes
264 
265 The ```--volume-file``` command line argument specifies the volume file to load.
266 Brayns currently only supports 8-bit raw volume. The ```--volume-dimensions```
267 command line argument specifies the size of the volume and is always required.
268 The ```--volume-element-spacing``` defines the size of the voxels. The ```--volume-offset```
269 command line argument defines the volume position in world coordinates.
270 
271 ```
272 braynsViewer --volume-file volume.raw --volume-dimensions 512 512 256
273 ```
274 
275 ![Shadows](images/Volume.png)
276 
277 ```
278 braynsViewer --volume-file volume.raw --volume-dimensions 512 512 256 --shadows 1 --soft-shadows 1
279 ```
280 
281 ![Shadows](images/VolumeGI.png)
282 
283 # Rendering parameters
284 
285 ## Engines
286 
287 The ```--engine``` command line argument specifies the underlying rendering engine
288 used by Brayns. Two engines are currently supported:
289 - [OSPRay](http://www.ospray.org/): A Ray Tracing Based Rendering Engine for High-Fidelity Visualization
290 
291 - [OptiX](https://developer.nvidia.com/optix): A software development kit for achieving high performance ray tracing
292 on the GPU
293 
294 ```
295 braynsViewer --engine <ospray|optix>
296 ```
297 
298 ## Renderers
299 
300 The ```--renderer``` command line argument specifies which renderer is used by Brayns.
301 Four renderers are currently supported:
302 
303 | Argument | Description
304 | ----------| -------------
305 | default | Common renderer to all engines. Provides basic features such as phong/blinn shading, shadows, ambient occlusion, light emission, reflection and refraction.
306 | simulation| Same as default with extra features such as support for simulations and volumes.
307 | particle |
308 | proximity | Displays information about element proximity in 3D space. Typically used to find touches between neurons.
309 
310 ## Camera types
311 
312 The ```--camera``` command line argument defines the type of camera to be used
313 by the renderer. Five cameras are currently supported:
314 
315 | Argument | Description
316 | ---------------------| -------------
317 | perspective | Perspective camera
318 | stereo | Side-by-side camera
319 | orthographic | Orthographic camera
320 | panoramic | 360 degrees camera
321 | clipped | Perspective camera allowing clipping planes
322 
323 ```
324 braynsViewer --camera orthographic
325 ```
326 
327 ## Head light
328 
329 The ```--head-light``` command line argument aligns the light direction to the one
330 of the camera. A value of 1 activate the feature, 0 deactivates it.
331 
332 ```
333 braynsViewer --head-light 1
334 ```
335 
336 ## Shadows
337 
338 The ```--shadows``` command line argument determines the intensity of the shadows.
339 A value of 1 activates full shadows, 0 deactivates it. By default, shadows are
340 hard. The ```--soft-Shadows``` command line argument defines the softness of the
341 shadows.
342 
343 ```
344 braynsViewer --shadows 0.3
345 ```
346 
347 ![Shadows](images/Shadows.png)
348 
349 ```
350 braynsViewer --shadows 0.6 --soft-shadows 0.1
351 ```
352 
353 ![SoftShadows](images/SoftShadows.png)
354 
355 ## Ambient occlusion
356 
357 The ```--ambient-occlusion``` command line argument determines the strength of the
358 ambient occlusion. The value is a float between 0 and 1 (0 for no occlusion,
359 and 1 for maximum occlusion).
360 
361 ```
362 braynsViewer --ambient-occlusion 1
363 ```
364 
365 ![AmbientOcclusion](images/AmbientOcclusion.png)