VQScript Example Scripts

VivoQuant includes a powerful scripting engine, VQScript, which allows users to automate workflows, modify data visualizations, and streamline analysis tasks.

This page provides two detailed examples to help users create their own scripts, a brief discussion on finding and fixing errors, followed by a list of pre-installed example scripts available inside VivoQuant.

Saving a Local Dataset as PNG

This tutorial explains how to automate the saving of a PNG image from a dataset already loaded into VivoQuant, using VivoScript. Once you’ve edited the script to work in your environment, try adding it to the Script Shortcuts Toolbar.

Step-by-Step Breakdown

The Script Example will do the following:

1. Initialize the main VivoQuant interfaces: main window, data manager, and min/max tool by assigning them to variables.
2. Define min/max visualization values in an array each for CT and PT datasets.
3. Apply the grayscale (gray) palette to CT and nih_fire2 palette to PT dataset.
4. Apply the min/max range values using the MinMax Tool.
5. Save the image to a specified local path in PNG format.

Script Example: Save Local Dataset as PNG

// Initialize main VivoQuant objects
var mw = VQ.mainWin();
var dm = VQ.dataManager();
var mm = VQ.minMaxTool();

// Define min/max ranges for CT and PT
var ctMinMax = [-1000, 4000];
var ptMinMax = [0, 10];

// Apply color palettes to the first two datasets
dm.setPalette(VQ.index(0), 'gray');        // CT
dm.setPalette(VQ.index(1), 'nih_fire2');    // PT

// Apply min/max values
dm.setMinMaxCache(VQ.index(0), ctMinMax[0], ctMinMax[1]);
dm.setMinMaxCache(VQ.index(1), ptMinMax[0], ptMinMax[1]);
mm.resetValues();
mm.applyValues();

// Save the rendered image to disk
var outFile = 'C:/Users/yourusername/Desktop/vivoscript/Sample.png';
mw.saveImage(outFile, 1);  // '1' = save image plane (e.g.,  0 = MIP, 1 = Sag, 2 = Cor, 3 = Tra)

Loading Data from iPACS and Saving PNG

This tutorial explains how to automate loading CT/PT datasets from an iPACS server and saving the processed view to a PNG file.

Script Example Overview

The Script Example will do the following:

1. Include the iPACS helper library using #include "ipacs.vqs".
2. Initialize the main VivoQuant interfaces (main window, data manager, and min/max tool).
3. Define min/max visualization values for CT and PT datasets.
4. Connect to the iPACS server using the ipacss:// protocol.
5. Specify the project path on the iPACS server.
6. Retrieve all available studies.
7. Iterate through the studies until one containing both CT and PT modalities is found.
8. Unload any previously loaded datasets before loading new ones.
9. Load the CT and PT series into VivoQuant.
10. Apply visualization settings (palettes and min/max ranges).
11. Save the final rendered image to disk using the study UID in the filename.

Script Example: Load Data from iPACS

// Include the iPACS helper library
#include "ipacs.vqs"

// Setup VivoQuant tools
var mw = VQ.mainWin();
var dm = VQ.dataManager();
var mm = VQ.minMaxTool();

// Define min/max settings
var ctMinMax = [-1000, 4000];
var ptMinMax = [0, 10];

// Connect to iPACS server
var url = "ipacss://your-ipacs-server-url";
var prj = "/your-project-path";
var repo = new iPACS(url, prj);

// Search for a study with both CT and PT series
var studies = repo.getStudies();
var found = false;

for (var i = 0; i < studies.length && !found; i++) {
    dm.unloadData(0, -1);  // Unload previous datasets

    var ctSeries = repo.getSeries(studies[i], '-modality', 'CT');
    var ptSeries = repo.getSeries(studies[i], '-modality', 'PT');

    if (ctSeries.length > 0 && ptSeries.length > 0) {
        found = true;

        // Load CT and PT series
        repo.getImages(studies[i], ctSeries[0], 0);
        repo.getImages(studies[i], ptSeries[0], 1);

        // Apply palettes
        dm.setPalette(VQ.index(0), 'gray');
        dm.setPalette(VQ.index(1), 'nih_fire2');

        // Apply min/max ranges
        dm.setMinMaxCache(VQ.index(0), ctMinMax[0], ctMinMax[1]);
        dm.setMinMaxCache(VQ.index(1), ptMinMax[0], ptMinMax[1]);
        mm.resetValues();
        mm.applyValues();

        // Save rendered image
        var uid = studies[i].StudyInstanceUID;
        var outFile = 'C:/Users/yourusername/Desktop/vivoscript/iPACS_' + uid + '.png';
        mw.saveImage(outFile, 4);

        VQ.showMessage("Image saved successfully from study index " + i);
    }
}

if (!found) {
    VQ.showMessage("No study contained both CT and PT series.");
}

Troubleshooting and Debugging Scripts

As you’ve gained familiarity with JavaScript you’ve likely had to find and fix code errors whether they be syntax or logic related as you’ve learned. If you don’t have a lot of debugging experience yet we recommend you read elsewhere for tips like explaining the problem out loud (“rubber ducking”) or splitting code up into smaller and smaller chunks. Many of these primers will also mention using the console log and adding breakpoints or debugging statements to the code.

However, VivoQuant 6 no longer has the experimental debugging feature built into it for adding places where the code will intentionally stop (called breakpoints) for code troubleshooting.

You can create your own kind of “breakpoint” with the VQ.showMessage(); function to understand how far the code has run in its execution and even return and display values back to you that might help with your debugging efforts.

The code will stop running while it shows the message, you can use the message to print values of your code back to you, and once you dismiss by OK the message the code will continue to run.

Let’s lean on “Save Local Dataset as PNG” from our examples above to use VQ.showMessage() to stop the code and show our output path, then create a new line and show one of our values we had set before. You can see that we put our strings in quotes and then use the plus symbol to concatenate the rest of our output.

VQ.showMessage("Output Path: " + outFile + "\n" + "ctMinMax Values " + ctMinMax);

If you added this line as the penultimate one in the example you’d have outFile defined and your message should stop the code from running right before the save operation (adding it too early in your code will result in an error because outFile will not yet be defined).

A few other tips

1. Learn to spot the difference between a Script error and an Application error for VivoQuant for instance a red octagon and error message beginning with VivoQuant is likely a VivoQuant application error whereas a yellow triangle and error message beginning with Script Error is a Script Error. Knowing “where” the problem is located is important to know how to resolve or ask for help.
2. Search the Web for error messages, it’s very likely that someone has had a similar error and posted a solution or a work around.
3. Spelling matters and generally speaking so does case e.g. VQ vs vq.
4. JavaScript doesn’t support named parameters or reordering of parameters. Please consult the VQS documentation for the correct ordering and types for function parameters.
5. Although VivoQuant has an editing window, if you use a dedicated text editor for programming you can set the langauge to JavaScript and use syntax high-lighting for clues. A lot of these editors have other programming quality of life features like auto-completion as well. Editing Scripts in a dedicated editor is easier the more complex the scripts become.

Pre-installed Example Scripts

Included with VivoQuant are 30 VivoScripts that illustrate some of the many ways in which users may use VQScript to streamline their workflows.

These files may be found in the VivoScript folder:

On Windows: C:/Program Files/Perceptive/VivoQuant/VivoScript/.

On Mac: /Applications/VivoQuant.app/Contents/MacOS/VivoScript/

On Linux: /opt/VivoQuant/VivoScript/