From WikiSonix
Jump to: navigation, search


Propello is a program derived from the Porta SDK, that allows the collection of volume data from motorized ultrasound transducers. Many types of data can be collected, and with the program, users have full control over the motor and sweeping parameters. Some of the more important features included:

  • Two acquisition modes: manual motor movement and automatic motor sweeping
  • Access to pre and post scan-converted B data, color velocity/variance data, bitmapped color data, color RF ensembles, and unfiltered *RF data created from B mode geometry
  • B/Color and RF displays
  • Support for all Ultrasonix 4D transducers
  • Access to basic imaging parameters for B and Color modes
  • 256 MB of cine for volume storage
  • Simple file formats for easy read into MATLAB
  • Imaging based on clinically driven presets

In latin, the word propello is defined as "to drive before one, drive away". The name was chosen for the application because the purpose is to drive the motor on the ultrasound probe.

Installation Steps[edit]

  1. Extract the zip package to any specified drive or folder on the Sonix RP system.
  2. Ensure the dat and fw folders are kept in the same folder as the executable and DLL's
  3. Ensure any application that uses the ultrasound imaging system has been closed
  4. Run propello.exe to start the program

Interface Details[edit]

This section provides a summary of the application components. The main screen is shown below.

Description of interface components:

  1. Probe Information – Detects the transducer, and displays probe information. The application only detects for probes with 3D/4D capability. Other probes will be considered invalid.
  2. Imaging Selection – The data types to collect while imaging.
  3. Capture Method – The method used for controlling the motor.
  4. Controls – Imaging parameters access, and other controls for automatic and manual motor control.
  5. Status – Displays the imaging status, frames per second, volumes per second, and frames acquired.
  6. B-mode display – Displays the B image with optional color Doppler overlay.
  7. RF spectrum display – Displays the center RF line of the transducer.

Motor Controls[edit]

Two types of capture methods, manual and automatic mode. Why have two modes? Automatic mode is nice, because it will automatically acquire volumes into the cine, and do it with some speed, however it does not truly provide full motor control, which is the point of the application. Automatic mode also faces the issue that for every reverse sweep volume acquired, the corresponding frames will skewed the opposite direction, as the motor is continuously moving while acquiring the frame. For this reason, it may not be desired to use the reverse sweep volumes without some sort of alignment algorithm in place.

Manual Mode[edit]

This mode enables manual stepping of the motor to a specific position. The motor can be programmed to go to a Motor Start position, and then moved to that location at any time by pressing Go To Start. At zero degrees, the motor is positioned to one edge of the probe. The range for the start position is from 0 degrees to the probe's field of view (FOV).

The step-by-step motor movement is done through the Move Motor arrow buttons. The number of steps that the motor can move depends on the degrees per step and the FOV of the transducer. By default, each button press will move 8 steps, the actual degrees moved will be reflected in the Motor Location box.

When Go To Start is pressed, the Motor Location is initialized to the start. Every time the motor is moved step-by-step, the location is updated. If for whatever reason the stepping gets out of sync, then the motor should be moved to the start once again.

The imaging pipeline can be run while in manual mode as well. Individual B-mode and RF frames can be acquired during manual motor control by pressing Acquire Image button, this will bring up the Store Data dialog where images can be saved.

Automatic Mode[edit]

This mode allows for automatic sweeping of the motor. In automatic mode, the motor will be sweeping continuously while acquiring images. Once imaging is stopped, all of the frames in the cine buffer can be accessed and stored.

The user has control of two parameters:

  • Degrees per frame
  • Frames per volume

Each of these parameters is bounded internally through the boundaries.xml file in the dat folder. The default values for degrees per frame are 8, 16 and 24 steps per frame, which get translated to degrees per frame on the screen. Note that not all transducers will support 24 steps per frame, as the motor cannot keep up with rotation speed required. The FOV display is updated whenever any of these parameters are changed.

In this mode, the volume starts at an offset of half the FOV from the center. So if the FOV generated is 45°, then the volume will start at 22.5° clockwise from center. Also note that volumes are acquired both frontwards and backwards, so the corresponding frames will be reversed for every 2nd volume. Since the motor is continuously moving, the frame alignment will also be different between frontwards and backwards volumes. See the below figure for an explanation of this.


Acquisition in automatic mode is different than manual mode, in that individual images are not captured, but rather entire volumes of data. When Store Volumes is pressed, the Store Data dialog will be shown, and volumes can be stored from here. Also note that the cine buffer is cleared when:

  • The acquisition is stopped and restarted
  • The degrees per frame or frames per volume is changed
  • Any imaging parameter is modified

Data Storage[edit]

The data storage dialog as shown in Figure 3.1 is used to store individual images as well as full volumes. Three types of data are available for capture:

  • Pre scan-converted B data
  • Post scan-converted B data
  • Unfiltered 20 MHz RF data
  • Color Velocity/Variance data
  • Color RF data
  • Post scan-converted B/Color data

The dialog has slightly different options for manual and automatic mode, as can be seen below:

Single frame Manual mode Automatic mode

Every time an image or volume is stored, an internal counter is incremented and is used default filename plus the extension for convenience purposes. To reset the counter, press Reset Counter. The counter is also automatically reset when the acquisition type changes.

Unlike other RP software, Propello removes the 4 byte frame header when storing data from the cine buffer. This should be taken into consideration if existing MATLAB programs are used to parse pre-scan B and Rf data.

Single Image File Formats[edit]

In manual mode, single frames of the specified image format can be stored. Conforming to the ulterius specification, pre scan-converted Band RF data are stored with extensions .bpr and .rf respectively, and there is also an option to include the ulterius file header. Post scan-converted B data is stored as a bitmap image (.bmp), which can make MATLAB parsing a bit easier. The File Name can be input through typing, or by pressing Choose, which opens up a dialog for selecting a folder. Note that the default filename when entering the dialog will include the internal counter as mentioned previously.

Here is the ulterius based file header that is can be optionally included in single frame acquisitions in Propello:

struct uFileHeader
    int type;	// data type
    int frames;	// number of frames in file (always 1 in Propello)
    int w;		// width (number of scanlines or pixels)
    int h;		// height (number of samples or pixels)
    int ss;		// sample size in bits
    int ulx;	// roi - upper left (x) (unused in Propello)
    int uly;	// roi - upper left (y) (unused in Propello)
    int urx;	// roi - upper right (x) (unused in Propello)
    int ury;	// roi - upper right (y) (unused in Propello)
    int brx;	// roi - bottom right (x) (unused in Propello)
    int bry;	// roi - bottom right (y) (unused in Propello)
    int blx;	// roi - bottom left (x) (unused in Propello)
    int bly;	// roi - bottom left (y) (unused in Propello)
    int probe;	// probe identifier    
    int txf;	// transmit frequency in Hz
    int sf;    	// sampling frequency in Hz
    int dr;		// data rate (always fps)
    int ld;		// line density (number of scanlines at 100% sector)
    int extra; 	// extra information (always 0 in Propello)

Volume File Format[edit]

In automatic mode, volumes are captured and stored in a single .vol file with the header information shown below. The Volume Range can be selected in the Store Data dialog to only store the desired volumes.

Note that the volume files contain stacks of 2D images that can be used to construct the 3D volumes. Saving pre-scan converted data will require two scan conversions (in the x-y and y-z planes) to be applied to the data set for volume reconstruction. Saving post-scan converted data will provide the scan converted 2D images in the x-y plane so that it is only necessary to apply scan conversion in the y-z plane.

struct propelloHeader
	int type;	 	// type of data (0 = pre-scan, 1 = post-scan, 2 = rf)
	int volumes;	        // volumes inside the file
	int fpv;		// frames per volume
	int w; 		        // width of a frame (pixels for post-scan, scanlines for
				// pre-scan or rf data)
	int h; 		        // height of frame (pixels for post-scan, samples for
				// pre-scan or rf data)
	int ss;		        // sample size in bits
	int degPerFr; 	        // degree step between frames

Probe Parameters[edit]

Some probe specific parameters including probe radius, and motor radius specifications from the probe manufacturer can be found in the probes.xml file. The units for the radius, and pitch parameters are reported in microns. A snippet of the parameters used for 3D reconstruction from the probes.xml file for the 4DC7-3 probe is shown below. Alternatively, you can also refer to the probes information panel for probe specific parameters from the manufacturer (see the Probe Information panel below).

    <probe enabled="1" id="16" name="m4DC7-3/40">

From the above, the following parameters can be derived.

probe length = pitch * numElements

probe angle = probe length / probe radius * 180 / PI   (where PI = 3.14...)

frame angle length = ( numLines / linedensity ) * probe angle
angle between frames = volume angle / ( frames per volume - 1 )

angle between scan lines = frame angle length /( number of lines - 1 )

Imaging Parameters[edit]

The imaging parameters available under the controls tab are shown below:


Each control controls B and RF parameters in the following manner:

  • Gain: Adjusts the analog gain applied to both the B and RF data
  • Depth: The depth to acquire B and RF data at
  • Sector: Adjusts the number of scanlines within B and RF frames
  • B-Opt: Optimizes the frequency and receive filters for different tissue types and depths
  • Tx Freq: Adjusts the transmit frequency for both B and RF data
  • Focus Depth: The depth of the focal marker
  • Zoom: Adjusts the zooming level of the post scan-converted B image
  • Map: Adjusts the map curve of the post scan-converted B image to a specific map index

Color Doppler also contains it's own adjustments:

  • Gain: Adjusts the analog gain applied to the color image
  • Tx Freq: The transmit frequency for color image
  • PRF: The pulse repetition period for visualizing different ranges of blood speed
  • Persistence: The level of time-motion filtering applied
  • Mode: Switches between Color Doppler Imaging and Power Doppler Imaging

Additional controls may be added for future versions, for now, just a basic set have been included. Some nice-to-have controls may be TGC, color box width and height, and dynamic range.

Important Imaging Notes[edit]

  1. The General (or master) preset is loaded upon probe detection
  2. Line Density is automatically set to 128 (the native transducer element count) no matter what value the master preset holds. Setting line density to 128 maximizes the frame rate. The faster the frame rate, the faster the motor will move.
  3. RF decimation is automatically set to 1, to acquire 20 MHz RF data, since 40 MHz collection is not always reliable
  4. There is only one focus used because RF mode (the mode that is configured for Propello), only supports 1, and because having more than one focus will slow down the frame rate and volume rate

Supported Probes[edit]

The following probes are currently supported:

  • 4DC7-3/40
  • m4DC7-3/40
  • 4DL14-5/38
  • 4DEC9-5/10



Propello is based on the Porta SDK, an imaging API built by Ultrasonix for custom ultrasound applications. The program was written in C++, using MFC for the graphical and widget toolkit, and was developed using the Visual Studio 6 environment. The source code for the program can be found in Porta versions 4.3 and higher.


The loadvol.m file provides the functionality to read the volume data that is exported from the Propello application into MATLAB. The function inputs are the data path and the volume number to read. The program outputs the imaging parameters from the header file, a description of which is provided above.

function [volume, datatype, numVols, fpV, h, w, ss]  = loadvol(datapath, volN)

The figures below show sample image slices respectively from pre-scan B and post-scan B volumes:


This figure shows an RF line sample from an image slice:


Future Version Development[edit]

Future additions to the application may include:

  • Access to images and volumes in real-time
  • Development of a plugin framework to allow volume rendering engines to be implemented
  • Access to more imaging parameters
  • Support for more 4D transducers such as EV and linear probes
  • One common header for volumes and single images? Maybe alter the Ulterius header slightly?