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
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 it 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.
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. To close the embedded mesh scene viewer, the Exit button in the right lower corner needs to be clicked.
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.
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 3D viewer are not stored in a 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 © 2021 Rainer Goebel. All rights reserved.