If you don't already have a Python distribution, you will need to download one first. We recommend Anaconda, as it includes many of the required packages already.

We also need to install the following Python packages:

• pyQt5
• pyopengl
• lz4
• numba

We can do this from a command console. To do this in Windows, open Anconda Powershell Prompt in administrator mode. (Right click on the program in the start menu and select Run as administrator.) To do this on Mac or Linux just open a terminal. In either case, run the following command in the shell/terminal.

conda install numba lz4 pyopengl pyqt

You can also install these packages from the Anaconda Navigator Program.

You will also need a method to download the Github repository. There are several ways to do this, but perhaps the easiest is to use the programming editor VSCode. Once installed, you can check out the repository using the following procedure in VS Code:

• Open the command palette: Ctrl+Shift+p (Cmd+Shift+p on Mac)
• Type "clone" + Enter, and select Github: Clone
• Enter the following URL into the box: https://github.com/klecknerlab/muvi
• If you wish, change the target directory and click Clone

You have now downloaded the Python repository. We need to install it, which is easiest to do from a console window. If you are using Anaconda, open the Anconda Powershell Prompt from the start menu (it should not be in administrator mode). Then enter the following commands:

cd github\muvi
pip install -e .

Note: This commands assume you cloned the repository into the [USER]\github\muvi directory.

This will install the module in developer mode, which means that it leaves all the files in the original directory, instead of copying them to the Python directory. This is recommended currently, as this code is under active development, and may have frequent updates. Note: If you update the repository or change the code while in developed mode, it will affect the module when imported by other scripts! In this case, this is desirable, but don't delete this directory after installing!

You can now run the examples below from the powershell prompt. If you used the defaults, your muvi directory is ~\github\muvi

If the package is installed in developer mode, any changes to the code in the package folder will immediately affect the module. To update the package, just pull from the master github repository.

To create and view an example volume:

$ cd [MUVI DIR]/examples
$ python generate_gyroid.py
$ muvi gyroid.vti

Alternatively, there is a sample frame from a real experiment in the same directory, it can be viewed with:

$ muvi [MUVI DIR]/samples/sample_frame.vti

Note also that you can drag and drop files into the Muvi Viewer window, which will automatically display them.

The viewer has a few main parts:

• Rendered data: the main portion of the window.
• Data selector: top-right of the window. This allows you to select which data is displayed, and add/remove files. Right click on a data item to get more options. Also, if you select an item (left click on it), it's display options will be shown in the panel below.
• Display options: center-right of the window. This displays all the adjustable options for the rendering of the data. Note that the first tab is specific to the data item you have selected above.
• Playback controls: bottom of the window. Note that playback speed is controlled in the "View" tab of the display options.

If you would like to export an image, you can open the export window with Ctrl+E (Cmd+E on Mac).

You can also hide/show the right panel with Ctrl+/ (Cmd+/ on Mac).

Most of the display options include "tooltips" -- if you hover the cursor over the controls it will give you more information on what it does.

To convert a Phantom CINE file to compressed VTI volume, you need to first generate a XML file which contains the VolumeProperties info. This will allow you to define the number of frames per volume and other important properties.
To do this, copy the samples/muvi_setup.xml file (copied below) to the same directory as your 2D movie source files. If you leave the name as is, it will be automatically used by every file conversion in that directory. Alternatively, if you give it the same name as your source file (apart from the extension), this will be used for that specific file only.

<?xml version="1.0" encoding="UTF-8"?>
<VolumeProperties>
    <!-- Number of frames in a volume -->
    <int name="Nz">256</int>
    <!-- Nx/Ny don't need to be specified, determined automatically -->

    <!-- Number of frames in a scan, must satisfy Ns >= Nz -->
    <int name="Ns">300</int>

    <!-- Dark clip value; default works well for Cine files -->
    <float name="dark_clip">0.005</float>

    <!-- If desired, you can also limit the upper end brightness.  This is the
    level in the raw file which is converted to the brightest value.  The
    default below is the correct value for Phantom cameras.  In most situations
    it should probably be left alone.  Note that you would also need to adjust
    the dark_clip if you change the white_level!
    -->
    <!-- <int name="white_level">4064</int>-->

    <!-- Gamma correction.  If gamma = 2, stored value is sqrt of input -->
    <float name="gamma">2.0</float>

    <!-- Physical size of volume on each axis -->
    <int name="Lx">100</int>
    <int name="Ly">100</int>
    <int name="Lz">100</int>

    <!-- Uncomment these lines if distortion correction will be used.  Note
        that the units of dx/dz are the same as L -->
    <!--
        <int name="dx">200</int>
        <int name="dz">200</int>
    -->

    <!-- Units of L -->
    <str name="units">mm</str>
</VolumeProperties>

Note: If your 3D frames are trigger only during the active scan region,
you can comment out the Ns and Nz entries. The software will automatically determine the volume depth by analyzing the frame timings!

Additionally, there are two utilities in the util directory which are useful for determining the properties of Cine files:

• cine_histo.py: This will sample the input cine file and create a histogram of the brightness levels. Can be used to determine the appropriate dark_clip level. (Although the default is usually sufficient.)
• frame_delta.py: This will analyze the first 1500 frames to try to find the "turn-around" of the laser scanner. Can be used to determine the number of frames in a scan (Ns) and the offset (offset). (Note: this utility is obsolete in practice; if you don't specify Ns or Nz, this analysis is automatic!)

To convert your video file, use the installed muvi_convert shell command to generate the .vti file, and muvi to view it:

$ muvi_convert [INPUT FILE] [OUTPUT FILE]
$ muvi [OUTPUT FILE]

By default, the output filename is the same as the input with an .vti extension. There are also more options in the conversion utility, which you can view with:

$ muvi_convert --help
usage: muvi_convert [-h] [-x XML] [-s START] [-e END] infile [outfile]

Convert a CINE file to a VTI movie

positional arguments:
  infile                Input CINE file
  outfile               Output VTI file

optional arguments:
  -h, --help            show this help message and exit
  -x XML, --xml XML     XML file to use for conversion parameters
  -s START, --start START
                        First volume index to convert (default: 0)
  -e END, --end END     Last volume index to convert (default: all volumes
                        converted)

This project is currently in active development. A number of features are currently planned:

• Volume rendering
• Isosurface viewing
• Mesh overlay
• Tools to generate glyphs (arrows, points, etc.) for overlays
• VTI file writing
• VTI file reading
• VTI reading from other sources
• CINE conversion
• SEQ conversion
• Conversion GUI
• Display perspective correction
• Multichannel support (partial)
• Support for perspective in old "S4D" format
• Perspective correction on volumes in memory (for external processing)
• Image export (high res)
• Movie export
• Asyncronous display code (to avoid hang ups)
• Labeled axes
• Create Wiki with practical examples

Copyright 2023 Dustin Kleckner

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at: http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.