BrainVoyager Python Developer Guide 0.9

VMR General Commands

VMR document objects expose specific commands to handle e.g. spatial transformations (e.g. brain normalization), creation and access of volume time course (VTC) data as well as access to meshes. Here preprocessing, spatial transformation and voxel and mesh access commands are described.

snapshot()

Description: Creates a snapshot of the current VMR viewer and embeds it in the output section of the current cell of the notebook that executes the command. This command saves a screenshot image of the VMR view but also stores the paths to the VMR and associated map files. If double-clicked, a VMR viewer is started embedded in the notebook loading the previously stored VMR and map files (if still available at their original location). Double-clicking the embedded viewer ends the interactive exploration, grabs the current view as an image and shows it at the viewer location. If this command is not called from a notebook, it is ignored.

deface() → bool

Description: Defaces the calling DocPyBV VMR document. The anatomical data must have a voxel size of 1.0mm in all dimensions. Native and MNI space is supported. In native space, the VMR is temporarily brought into MNI space to obtain a MNI affine transformation matrix, which is applied backwards to locate the MNI defacing mask in native space. In MNI space, the MNI defacing mask is applied as is and the data set must have x, y, and z dimensions of 256. After defacing, the current VMR document is saved under the file name '[original-name]_defaced.vmr". The return value indicates success or failure of the defacing operation.

transform_to_std_sag(str out_vmr_sag_filename) → bool

Description: Reorients the data of the calling DocPyBV VMR document into BrainVoyager's standard "sagittal" orientation and radiological convention (right-is-left) producing a new VMR output file using the provided file name. If the VMR data is already in sagittal standard orientation, the operation is ignored. The standard sagittal orientation is important since it is assumed by subsequent transformation functions such as MNI and Talairach transformation. Note that the command does not change the intensity values of the VMR data since only 90 degree rotations and axis flips are performed. The boolean return value indicates whether the command could be performed successfully. If there is a V16 file availabel with the same name as the calling VMR document, the same spatial transformation will be also applied to the V16 data set. Note. In case that the VMR document is already oriented in BrainVoyager's standard sagittal orientation, no output file is produced and value 'False' is returned.
out_vmr_sag_filename (str): String specifying the name of the resulting VMR file after reorientation (recommended: "[name]_SAG.vmr").

transform_to_std_isovoxel(int interpolation_method, str out_vmr_iso_filename) → bool

Description: Resamples the data of the calling VMR document producing a new VMR output file with a resolution of 1.0 millimeter in all 3 dimensions located in a 256 framing box. This is the recommended resolution (and framing cube) for standard VMR analyses. In case that another spatial resolution (or framing cube) is desired, e.g. for sub-millimeter analyses, the "transform_to_iso_voxel()" command can be used (see below). The boolean return value indicates whether the command could be performed successfully. If there is a V16 file availabel with the same name as the calling VMR document, the same spatial transformation will be also applied to the V16 data set. Note. In case that the VMR document has already a iso-voxel resolution of 1mm, no output file is produced and value 'False' is returned.
interpolation_method (int): Integer specifying the interpolation method: if the provided value is 1, trilinear interpolation will be used, if the value is 2, cubic spline interpolation will be used and if the value is 3, sinc interpolation will be used.
out_vmr_iso_filename (str): String specifying the name of the resulting VMR file after resampling (recommended: "[name]_ISO.vmr") or "[name]_ISO-1mm.vmr")

transform_to_isovoxel(float target_res, int framing_cube_dim, int interpolation_method, str out_vmr_iso_filename) → bool

Description: Resamples the data of the calling VMR document producing a new output file with a resolution as specified with the targetResolution parameter in all 3 dimensions in a bounding box with dimensions as specified in the framingCubeDimension parameter. The boolean return value indicates whether the command could be performed successfully. If there is a V16 file availabel with the same name as the calling VMR document, the same spatial transformation will be also applied to the V16 data set.
target_res (float): Float value specifying the target resolution. This is especially useful for high-resolution data from ultra-high field scanners when one wants to match the resolution (or an integral resolution factor) of sub-millimeter functional data; if, for example, the functional data is 0.8 mm and the VMR was measured at 0.6 mm (with or without equal resolution in all dimensions), one could resample the VMR data to 0.8 or to 0.4 (resolution factor 2) millimeter iso-voxel data.
framing_cube_dim (int): Integer specifying the framing dimensions of the output VMR data. For sub-millimeter data, a framing cube dimension larger than 256 might be necessary such as 384 or 512.
interpolation_method (int): Integer specifying the interpolation method: if the provided value is 1, trilinear interpolation will be used, if the value is 2, cubic spline interpolation will be used and if the value is 3, sinc interpolation will be used.
out_vmr_iso_filename (str): String specifying the name of the resulting VMR file after resampling (recommended: "[name]_ISO-[resolution].vmr").

correct_intensity_inhomogeneities() → bool

Description: Corrects spatial intensity inhomogeneities of the calling VMR by estimating and removing a low-frequency 3D 'bias' field; the procedure applies the correction to the 2-byte int data of an attached V16 dataset. If the corresponding V16 dataset is not loaded or can not be loaded from disk using the same name as the VMR (except the .v16 extension), the process will not execute. The command launches an iterative process (3 cycles as default). The boolean return value indicates whether the command could be executed successfully. If successful, a new inhomogeneity corrected VMR file is stored to disk with a name based on the original VMR document: "[input-name]_IIHC.vmr". Besides the resulting VMR file, also a .V16 version ("[input-name]_IIHC.v16") will be saved as well as a brain mask file with the name: "[input-name]_BrainMask.vmr". This command is recommended to be executed after creation of a VMR document. Note that this operation also includes a brain extraction step, i.e. the resulting VMR document is usually ready for brain normalization and grey-white matter segmentation. Note that the command operates "in-place", i.e. the original VMR document holds the resulting data after running successfully and can be directly used for subsequent processing without the need ot load the created VMR data file from disk.

correct_intensity_inhomogeneities_ext(bool include_brain_extraction, int n_cycles, float tissue_range_thresh, float intensity_thresh, int fit_polynom_order) → bool

Description: Corrects spatial intensity inhomogeneities of the calling VMR by estimating and removing a low-frequency 3D 'bias' field; the procedure applies the correction to the 2-byte int data of an attached V16 dataset. If the corresponding V16 dataset is not loaded or can not be loaded from disk using the same name as the VMR (except the .v16 extension), the process will not execute. The command launches an iterative process with a number of repetitions specified in the "n_cycles" parameter. The boolean return value indicates whether the command could be executed successfully. If successful, a new inhomogeneity corrected VMR file is stored to disk with a name based on the original VMR document: "[input-name]_IIHC.vmr". Besides the resulting VMR file, also a .V16 version ("[input-name]_IIHC.v16") will be saved as well as a brain mask file with the name: "[input-name]_BrainMask.vmr". This command is recommended to be executed after creation of a VMR document. if the parameter "include_brain_extraction" is set to True, a brain extraction step, is performed before the iterative intensity inhomogeneity process; the resulting VMR document is then usually ready for brain normalization and grey-white matter segmentation. Note that the command operates "in-place", i.e. the original VMR document holds the resulting data after running successfully and can be directly used for subsequent processing without the need ot load the created VMR data file from disk.
include_brain_extraction (bool): This boolean parameter indicates whether a 'skull stripping' step will be performed at the begin of the process ('True', recommended) or not.
n_cycles (int): The number of iterations used to fit and correct a bias field. The bias field is defined by estimating white matter tissue, which will usually improve (includes more white matter voxels) over performed iterations.
tissue_range_thresh (float): Threshold to detect whether regions contain one or two (WM and GM) tissue types, recommended: 0.25
intensity_thresh (float): hreshold to separate higher (WM) from lower (GM) intensiites in regions, recommended: 0.3
fit_polynom_order (int): Order of polynom to fit 3D bias field in labelled WM voxel, recommended: 3

normalize_to_mni_space() → bool

Description: Performs automatic brain normalization to MNI space using template matching. To work successfully, the calling VMR document should contain brain extracted and inhomogeneity corrected data (see "correct_intensity_inhomogeneities()" command above). The boolean return value indicates whether the command could be executed successfully. If successful, a new VMR file with the data in MNI-152 space are stored to disk under a name that is based on the input VMR document: "[input-name]_MNI.vmr". The generated MNI transformation matrix is stored to disk in the TRF file "[input-name]_TO_MNI_a12.trf"; furthermore the files "[input-name]_TO_MNIColin27_a12.trf" and "[input-name]_TO_ICBM452_a12.trf" are stored that can be used to transform the native space VMR also to related spaces, namely to the Colin-27 and ICBM-452 MNI space. These TRF files can also be used to apply the MNI transformation to other VMRs in the same native space and they can be used when transforming functional data into MNI space (see "create_vtc_in_mni_space()" command). The original VMR document is closed and the resulting MNI file is loaded into the BrainVoyager workspace. The loaded MNI file is made the current document and can be accessed using the "active_document" property of the BrainVoyager (PyBV) application object.

auto_acpc_tal_transformation() → bool

Description: Performs automatic brain normalization to ACPC and Talairach space by detecting the mid-sagittal plane, the AC and PC points and the borders of the cerebrum. To work successfully, the calling VMR document should contain brain extracted and inhomogeneity corrected data (see "CorrectIntensityInhomogeneities" command above). The boolean return value indicates whether the command could be executed successfully. If successful, two new VMR files with the data in AC-PC and Talairach space are stored to disk under a name that is based on the input VMR document: "[input-name]_aACPC.vmr" and "[input-name]_aTAL.vmr". An additional file is created and stored to disk containing the detected Talairach fiducial coordinates ("[input-name]_aACPC.tal"); furthermore, two spatial transformation files are stored containing parameters to rotate the input data into the mid-sagittal plane ("[input-name]_ToMSP.trf") and on into ACPC space ("[input-name]_aACPC.trf"). The letter "a" in the file names indicates "automatic" transformation. The ACPC TRF and ACPC TAL files can also be used to apply the ACPC / Talairach transformation to other VMRs in the same native space and as part of the transformation of functional data into ACPC and Talairach space (see "CreateVTCInACPCSpace" and "CreateVTCInTALSpace" command). The original VMR document is closed and the TAL VMR file is loaded into the BrainVoyager workspace. The Talairach file is made the current document and can be accessed using the "ActiveDocument" command of the BrainVoyager application object.

get_voxel_intensity(int x, int y, int z) → int

Description: Returns the intensity value at the provided voxel coordinates of the calling VMR document. Note that this command is slow and is thus not recommended for looping over all voxels of a VMR document. For such applications, the BrainVoyager data access (bv) module should be used.
x (int): Integer specifying the x coordinate of the referenced voxel. The x axis is interpreted as in Talairach / MNI space running from left to right (if VMR in BrainVoyager's standard orientation).
y (int): Integer specifying the y coordinate of the referenced voxel. The y axis is interpreted as in Talairach / MNI space running from posterior to anterior (if VMR in BrainVoyager's standard orientation).
z (int): Integer specifying the z coordinate of the referenced voxel. The z axis is interpreted as in Talairach / MNI space running from inferior to superior (if VMR in BrainVoyager's standard orientation).

set_voxel_intensity(int x, int y, int z, int value)

Description: Sets the provided intensity value at the specified voxel coordinates of the calling VMR document. Note that this command is slow and is thus not recommended for looping over all voxels of a VMR document. For such applications, the BrainVoyager data access (bv) module should be used.
x (int): Integer specifying the x coordinate of the referenced voxel. The x axis is interpreted as in Talairach / MNI space running from left to right (if VMR in BrainVoyager's standard orientation).
y (int): Integer specifying the y coordinate of the referenced voxel. The y axis is interpreted as in Talairach / MNI space running from posterior to anterior (if VMR in BrainVoyager's standard orientation).
z (int): Integer specifying the z coordinate of the referenced voxel. The z axis is interpreted as in Talairach / MNI space running from inferior to superior (if VMR in BrainVoyager's standard orientation).
value (int): Integer specifying the new intensity value to be set at the referenced voxel. The integer should be in the range 0-225 (values between 226-255 are used for drawing colors). If a provided value is smaller than 0 or larger than 255 it will be ignored.

create_mesh_scene() → MeshScenePyBV

Description: In case that no mesh scene is currently attached to the VMR document, a MeshScenePyBV object will be created and returned. If a MeshScenePyBV object is already attached to the current VMR document, it will be returned. The visible part of a MeshScene object is a 3D Viewer (OpenGL) window. The obtained MeshScene object can be used e.g. to load head and cortex mesh files, which are displayed in the 3D Viewer (see topic Mesh Scene Commands).

Update3DViewer()

Description: Updates the 3D Viewer (OpenGL) window attached to the calling document. This command is useful to update the visualization of a 3D Viewer window, e.g. after changing the appearance of the mesh(es) it contains. Since the 3D viewer usually runs in auto-update mode, this command is usually not needed.