MuriSuite Installation Instructions

8 minute read

Install MuriSuite

Download the latest release.

Installer Components

Component Description
MuriSuite The main application and its necessary files.
MuriFocus Standalone MuriFocus utility application.
Hardware Utilities Suite of standalone apps to control individual pieces of hardware. Useful for troublshooting.
Varex Shared Libraries Needed *.dll files for Varex panels. Should only be installed if Varex libraries are not/will not be installed on the system. So, non-Varian systems.
Common Libraries Libraries shared between projects must always be installed.

Hardware Drivers

Be sure to install all of the needed hardware drivers (if applicable for your system). This could include, but is not limited to:

  • Galil
  • Basler
  • Point Grey
  • Varian
  • Perkin Elmer
  • Dexela

Visual Studio Redistributables

MuriSuite and associated auxiliary programs need the following Visual Studio Redistributables installed:

:warning: Note: The Visual Studio 2010 redistributable should not be installed if ViVa (Varex/Varian) software is going to be installed. The Varian software has its own version of the 2010 redistributable that it installs and there will be a conflict if the above version is installed.

Visual Studio Redistributable 2013

On some systems it may be necessary to install the Visual Studio 2013 Redistributable. If an error message pops up stating that the files msvcr120.dll and/or msvcp120.dll are missing then this step is necessary.

  1. Navigate to the Visual Studio 2013 Redistribuable download page.
  2. Click Download
  3. On the popup page select: vcredist_x64.exe
  4. Click Next (download should start)
  5. Open the downloaded file and follow the onscreen prompts to complete the installation. A reboot may be necessary to fully complete theinstallation.

Software Graphics Settings

MuriSuite requires OpenGL for part of its image rendering. To ensure that the software works correctly, MuriSuite needs to use an NVIDIA GPU for OpenGL rendering. To do this, follow these steps to change the graphics settings for MuriSuite on Windows 10:

  • Go to Display Settings in Windows 10

image

  • Then select “Graphics Settings”
  • Under “Choose An App”, select “Desktop App” and then “Browse”

image

  • Browse and select MuriSuite.exe

image

  • Next Select “Options” and select “High Performance”

image

Configuration Files

MuriSuite requires many configuration files to work properly. Some are created automatically if they don’t exist and others are not. The most critical file is the hardware-specification.json. This file specifies the hardware configuration of the system and determines what hardware MuriSuite will attempt to connect to at runtime. Below is a table of the required files and where they should be saved. Each file is discussed further in the sections below.

File Name Description Location
hardware-specification.json Hardware configuration file. %PROGRAMDATA%/Xstrahl, Inc/MuriSuite
murisuitedb Application database. %PROGRAMDATA%/Xstrahl, Inc/MuriSuite
murisuite_application_settings.json MuriSuite application specific settings %PROGRAMDATA%/Xstrahl, Inc/MuriSuite
cbct_protocols/ Folder that contains reconstruction protocols (*.cal) %PROGRAMDATA%/Xstrahl, Inc/MuriSuite/cbct_protocols
portal_camera_pixel_size_data.json Portal camera pixel size data %PROGRAMDATA%/Xstrahl, Inc/MuriSuite
‘panel_pixel_size_data.json | Panel pixel size data |%PROGRAMDATA%/Xstrahl, Inc/MuriSuite`    

Hardware Configuration File

The hardware configuration file (hardware-specification.json) is required to run MuriSuite. This file contains system info as well as a list of hardware devices that MuriSuite should connect to. There is an example file in the MuriSuite source directory: <MuriSuite-src>/utilities/common/tests/data. Below is a starter file that can be used. The example below should provide you with the basic SARRP set up that uses the Basler portal camera, Varian x-ray panel, Galil robotics and MP1 x-ray controller. Additionally, the Hardware Configuration Manager utility application can be used to generate this required file.

Portal Camera and Panel Pixel Size Data

Pixel size data for the panel and portal camera need to be determined empiracally for accurate measurements in MuriSuite using the ruler tool. As a starting point, the following files can be used. These files should be placed in the %PROGRAMDATA%/Xstrahl, Inc/MuriSuite directory. See configuration files for more information on where to place these files and how to name them.

Portal Camera Pixel Size Data

{
    "value0": {
        "cereal_class_version": 1,
        "value0": [
            {
                "distance": -26.0,
                "pixels_per_mm": 27.44
            },
            {
                "distance": 0.0,
                "pixels_per_mm": 25.55
            },
            {
                "distance": 26.0,
                "pixels_per_mm": 23.74
            }
        ]
    }
}

Panel Pixel Size Data

{
    "value0": {
        "cereal_class_version": 1,
        "value0": [
            {
                "distance": -50.0,
                "pixels_per_mm": 12.19
            },
            {
                "distance": 0.0,
                "pixels_per_mm": 14.03
            },
            {
                "distance": 50.0,
                "pixels_per_mm": 16.45
            }
        ]
    }
}

Setting Up the Web Camera

You will need to acquire the proper web camera serial number for MuriSuite to properly connect to the camera. Currently, the easiest way to do this is to run the WebCameraUtility application in the MuriSuite solution. At the top there is a combo-box that contains all the available cameras. You should be able to copy and paste this into the serial field of the camera below.

:exclamation: You will need to escape all \ characters in the path; i.e. \\ becomes \\\\ and \ becomes \\. An example path may look something like this:

@device:pnp:\\\\?\\usb#vid_046d&pid_082d&mi_00#9&2c78613c&0&0000#{65e8773d-8f56-11d0-a3b9-00a0c9223196}\\global

Disable a Specific Robotic Axis

MuriSuite 1.8.0 now supports the ability to perform CBCTs, execute beams and home without all axes. This was primarily added to support a specialty system, but is now a feature of MuriSuite. To disable an axis, open the galil_settings.json file in %PROGRAMDATA%/Xstrahl, Inc/MuriSuite and delete the calibration data for the axis that you wish to disable.

Setting Up “Mock” Hardware

“Mock” versions of the Basler camera, Varian panel and MP1 x-ray controller are available. To use mock hardware in MuriSuite (where you don’t have access to real hardware), you first need to replace the section in the hardware-specification.json with the details for the mock hardware.

MockBaslerCamera

Below is a json snippet for what to put into the hardware configuration file. Additionally, you will need to find an image to use that will be displayed in the GUI when x-rays are on. This is how the Basler camera mocks its behavior and is useful for demonstrating functionality locally or at shows.

{
    "cereal_class_version": 1,
    "type": "MockImageStream",
    "role" : "PortalCamera",
    "name": "Basler Portal Camera",
    "model": "acA1920-50gm",
    "manufacturer":"Basler",
    "serial":"22853896",
    "required": true
}

The image needs to be a *.tif image and can be saved anywhere on the system. When MuriSuite is first run, if a MockBaslerCamera is used in the hardware specification, the MockBaslerCamera class will create a settings file in %PROGRAMDATA%/Xstrahl, Inc/MuriSuite called mock_basler_camera_settings.json. The file looks like the following:

{
    "mock_basler_camera_settings": {
        "cereal_class_version": 1,
        "image_path": "C:/ProgramData/Xstrahl, Inc./MuriSuite/mock_basler_placeholder.tif"
    }
}

Set the full path to the image under the image_path.

Example image: fake-basler-image

MockVarianPanel

Below is a json snippet for what to put into the hardware configuration file.

{
    "cereal_class_version": 1,
    "type": "MockImageStream",
    "role" : "PrimaryXrayDetector",
    "name": "Varian Detector Panel",
    "model": "IDK",
    "manufacturer": "Varian",
    "serial": "S8932987DDFSSDF98SD89",
    "required": true
}

Additionally, the mock Varian panel has the ability to show raw projections as the robotics are updated and x-rays are on. To do this, you will need to edit the mock_varian_panel_settings.json file found in %PROGRAMDATA/Xstrahl, Inc/MuriSuite.

{
    "mock_varian_panel_settings": {
        "cereal_class_version": 1,
        "scan_path": "E:/CBCT_Data/PhantomQA_Scans/pancake-ff",
        "number_of_projections": 2
    }
}

The scan_path field needs to be set to a path that contains a CT scan with a raw projections file (projections.raw). The number_of_projections field should be set to the number of projections in the raw file present in the scan. Changing number_of_projections in the settings file will alter how many projections the class will load at startup. In the above example it is set to two to limit the amount of time it takes for MuriSuite to start up. Typical raw projection files are 4 GB in size, so this slows down the MuriSuite start up time which may be a hindrance during development.

MockXrayController

Below is a json snippet of what to add to the hardware configuration file to use the mock x-ray controller. No further set up is required.

{
    "cereal_class_version": 1,
    "type": "MockXrayController",
    "role": "XrayController",
    "name": "MP1",
    "model": "idk",
    "manufacturer":"Gulmay",
    "serial" :"DF0G8SFDS7FS",
    "required": true
}

Example hardware configuration file (hardware-specification.json):

{
    "specification": {
        "cereal_class_version": 1,
        "configuration": "sarrp",
        "product_generation": 4,
        "customer_name": "Xstrahl",
        "product_serial_number": 64,
        "capabilities" : ["cbct", "micro_cbct", "portal_cbct", "phantom_qa", "treatment_planning"],
        "collimators" : ["10x10 mm" , "5x5 mm", "3x9 mm", "3x3 mm", "1 mm", "0.5 mm"],
        "pc_info" : {
                "cereal_class_version" : 1,
                "serial": "234DF98FD75SDRT7219",
                "manufacturer": "Dell",
                "gpus" : [
                ]
        },
        "hardware" : [
            {
                "cereal_class_version": 1,
                "type": "ImageStream",
                "role" : "PortalCamera",
                "name": "Basler Portal Camera",
                "model": "acA1920-50gm",
                "manufacturer":"Basler",
                "serial":"234892879578923",
                "required": true
            },
            {
                "cereal_class_version": 1,
                "type": "WebCamera",
                "role": "WebCamera",
                "name": "Dazzle Video Capture USB Video Device",
                "model": "",
                "manufacturer":"Dazzle",
                "serial":"2342304928304",
                "required": true
            },
            {
                "cereal_class_version": 1,
                "type": "RoboticController",
                "role": "PrimaryRobotics",
                "name": "Galil Robotic Controller",
                "model": "DMC 2182",
                "manufacturer":"Galil",
                "serial":"23498458F8GDH9DH0SDG",
                "required": true,
                "axes" : [
                    "x", "y", "z", "gantry", "theta"
                ]
            },
            {
                "cereal_class_version": 1,
                "type": "ImageStream",
                "role" : "PrimaryXrayDetector",
                "name": "Varian Detector Panel",
                "model": "",
                "manufacturer": "Varian",
                "serial": "S8932987DDFSSDF98SD89",
                "required": true
            },
            {
                "cereal_class_version": 1,
                "type": "XrayController",
                "role": "XrayController",
                "name": "MP1",
                "model": "",
                "manufacturer":"Gulmay",
                "serial" :"DF0G8SFDS7FS",
                "required": true
            }
        ]
    }
}

MuriSuite Database

The murisuitedb file under %PROGRAMDATA%/Xstrahl, Inc/MuriSuite is an SQLite database that holds a variety of important information for the application. Currently, this database is not protected but will be prior to MuriSuite launch. If there is ever a need to edit the contents of this database it is recommended that you use DB Viewer for SQLite. This will allow you to edit the data inside the database (useful for development purposes).

System Status Setup

In the MuriSuite GUI, there is a section called System Status that has the ability to display a 3D model of the SARRP internals. To have this work properly, you need a STL file in the %PROGRAMDATA%/Xstrahl, Inc/MuriSuite directory called sarrp.stl. You can download this file here.

Voxl Considerations

Voxl reconstruction presets must be saved in the %PROGRAMDATA%/Xstrahl, Inc/MuriSuite/cbct_protocols directory. These files can be generated using the Voxl.GUI program’s Export feature. See the Voxl documentation for more information on how to do this.

Also note that the reconstruction engine is automatically selected in MuriSuite. For now, MuriSuite prioritizes using Voxl when available and falls back to using MuriSlice if Voxl is not present. This behavior may change in the future.

Updated: