BrainVoyager v23.0
Embedded Viewers
One way to enrich code segments with results or explanations is to add text, pictures and animations using respective cell types. In order to provide the user with the possibility to interactively explore full 3D datasets, notebooks can also embed 3D viewers. A viewer can be embedded as part of the output of a code cell by issuing the embed_viewer() (or snapshot()) command from a 3D anatomical (VMR) or mesh (SRF) document object. Note that this command is appended to code snippets send to notebooks in case that the Log BV GUI Actions as Code mode of a notebook is enabled; if not desired, code can be send also without the extra embed_viewer() call by turning off the Send viewer widgets option in the Settings dialog.
The screenshot below shows a simple code segment adding a volume map to a VMR document object; the code ends with the doc_vmr.embed_viewer() line. This command will not only grab the current document image and puts it in the output section of the Python code cell, but it will also store the information about the location of the VMR file itself - relative to the location of the notebook - so that the entire volume can be loaded when double-clicking the image at a later time. In case that a volume map (VMP) file was loaded, its name and location is also stored and reloaded when activating the embedded viewer. Note that storing the respective file information in the notebook disentangles what is visible in the BrainVoyager window and what is visible in the notebook, i.e. another (or no) document might be shown in BrainVoyager's user interface than what is inpsected in the notebook. Note also that you can simultaneously activate multiple 3D viewers.
An embedded viewer appears at first like a regular image but it can be brought to life at a later time simply by double-clicking it. The image is then replaced by a 3D viewer inside the respective notebook cell and can be navigated in the same way as in BrainVoyager's main user interface. When finishing exploring the data, another double-click will remove the viewer and replace it again with an image (see image above). In case of a 3D VMR viewer, a new image will be created that reflects the state of the embedded viewer at the moment of double-clicking allowing to adjust the static image. If one wants, however, not to replace but keep the original static image before activating the viewer, one can hold down the SHIFT key when double-clicking the viewer.
The code cell below shows how a 3D viewer for loaded mesh files can be embedded in a code cell by using the embed_viewer() command for a scene objec. The scene.embed_viewer() command will store loaded meshes together with eventually overlaid surface maps.
The image above indicates that double-clicking an image with stored information of one or more meshes, each with potential surface (SMP) overlays will be loaded and made available for interactive inspection inside the respective cell. The 3D surface viewer will show a reduced version of the Tools panel (see right side in the screenshot above). In case that surface maps are overlaid, a Map panel will also be shown that can be used to select individual maps (in case that more than one map is stored in the corresponding SMP file). To close the embedded mesh scene viewer, the Exit button in the right lower corner needs to be clicked (see right side in the screenshot above).
Note. While images and animations (next to code and Markdown text) are stored inside notebook files, the contents of the data files referenced by a volume or surface 3D viewer are not stored in the notebook. At a later time interactive 3D viewing is, thus, only availalbe if the referenced data can be found at the same relative location with respect to the location of the notebook. In case that a notebook is shared (e.g. moved to another computer), the data need to be also copied at the corresponding location - reative to the notebook. If the data is not available, the static image is shown but double-clicking will have no effect.
Copyright © 2023 Rainer Goebel. All rights reserved.