Porta Function Overview

Initialization
Porta is initialized through the function init. This function allows for the following:
 * Specification of the cine buffer size (more RAM used = more frames upon freeze)
 * Path setup for supporting firmware, preset and look-up table files
 * Hardware version configuration

If initialization fails, some important things to first look at:
 * Paths are pointing to the proper location
 * Hardware version matches the development platform

Licensing
Porta is designed to be modular in terms of imaging mode functionality. Some functions are licensed and based on 3rd party and/or patented technologies, therefore proper licenses may be required.

For Version 5.0 and higher:
 * The license file should be named "licenses_web.txt" and be placed in the folder specified upon initialization. In order to obtain/purchase licenses, you will need the serial number of your Sonix (or Modulo) device, as well as the System ID that is unique to each hardware module. To retrieve the System ID, simply make a call to getSystemID.

Synchronization Signals
Porta has the ability to interface to and to control the ultrasound BNC ports that come standard on the hardware. Please note that Sonix RP has one input and one output, and the SonixTOUCH Research and Sonix MDP have 2 of each.

More information on this can be found here.

Transducers
The important abilities for Porta to interact with transducers include the following:
 * Retrieve the probe ID from each of the 3 connectors individually
 * Get the name of the probe based on the ID read
 * Select a connector to be active

Once activateProbeConnector has been called, the system is setup to image with the transducer plugged into that port.

Testing Functions
Porta has the ability to test the individual components on the ultrasound electronics in cases where a problem may exist (most notably in case proper initialization fails). Under normal circumstances, all the tests should pass, with the function testElectronicComponent returning true. Since running all the tests (especially power tests) may take a while, custom programs may not want to run the tests at every startup.

Porta also has a function called testProbeElements for testing transducer elements, though it is up to the caller to perform analysis on the data. Porta will only use a built-in Texo SDK scipt to transmit and receive a single element across the transducer. The results of the data must be interpreted externally, and signal quality from each element will vary depending on the probe type and surface that the probe is imaging on, therefore this data should be used with caution.

Imaging Modes
Most of the imaging modes that the main research interface can run are also available in Porta (see licensing information for modes that are not active by default). An imaging mode programs the ultrasound transducer in a generic manner, so that a B image or Pulsed Wave Doppler spectrum can be acquired for example. Each imaging mode has a special purpose, and some are simple extensions of a base mode, such as 4B mode, which is B mode, but having the ability to display up to 4 displays on the screen at the same time so the user can can compare images.

Presets
Presets can be thought of as a subset of parameters that are optimized to a specific clinical application. For instance, the L14-5/38 transducer can be used to scan the breast or thyroid; each of these applications should have a specific preset to optimize the imaging parameters for that body part (and/or body type as well). Each transducer has a generic preset, also known as the master preset. This preset contains the default values that should work well for general scanning in all clinical applications. Sub-presets of each transducer will typically have many less values optimized when compared to the master preset. Many Porta based applications will work just fine with the master preset, however, if the transducer is custom, as is often the case for OEM customers, a custom sub-preset may need to be created with the help of Ultrasonix engineers.

Imaging Pipeline
The imaging pipeline is a generic term used in the Ultrasonix software to denote the actual acquisition of images, or the time in which the ultrasound transducer is transmitting and receiving signal to produce an image. Once a probe and imaging mode are setup, the imaging pipeline can be started by calling runImage. Internally, this tells the ultrasound hardware to start the transmit/receive on the probe, start the DMA process, so frames can be stored into PC memory, and finally wake up a collector thread, which is used in all Ultrasonix software including the reserach interface, Porta and Texo, for detecting new frames. The collector thread searches for a new frame header, which is a 4 byte number at the beginning of each ultrasound frame (or line in spectral modes). The frame counter will reset to 0 when it reaches 16000. Since the cine buffer (the RAM where image data is DMA'ed to) is cyclic, it is important not to stall the collector thread during callbacks, as if the frame counter overwrites itself at the current address, the thread will assume a problem has occurred in the pipeline, and no new frames will be detected, even though the DMA is still occurring. The function stopImage will halt the transmitting of the transducer, and suspend the collector thread. It should also be noted that the collector thread actually looks for the frame ID of the 'next frame to denote that the previous frame has been successfully DMA'ed. The reason for this is that the protocol uses a beginning of frame tag (BOF), and not an end of frame tag (EOF). If the collector thread looked at the BOF for the current frame, the DMA for the various ultrasound lines that make up the frame could still be taking place while the software signaled that a new frame was ready, when it fact it is not. This is OK for most cases, since the first line of the next frame is DMA'ed very quickly after the previous frame, however, in cases where the Max FR parameter is set, this will add a delay in between frames, and an actual frame that has finished being collected will not be notified until after this delay period.

Since Ultrasonix platforms use WinDriver (see Jungo) to communicate with the PCI card that interfaces to the ultrasound electronics, interrupts can technically be set for DMA events. This has been informally tested, and may one day be the method of choice for detecting new ultrasound frames, since the collector thread depends on non-blockage as well as a continuous and steady frame counter.

Callbacks
Porta uses callbacks as interrupts that flag when a new frame or image has been acquired. As discussed in the pipeline, the collector thread will look for the proper ID of a frame that matches a counter to signal that a frame has been acquired. Data collected from the cine buffer is termed Raw Data, and setRawDataCallback can be used to notify when a new frame comes into the cine buffer. This is useful if the custom program uses B image data that needs to be processed prior to scan conversion, or if RF data is required. Processed image data or Display Data is the actual image that the user would see on the screen, and when a new frame is ready, setDisplayCallback can be used for notifications. It should be noted that the internal structure of Porta and other Ultrasonix software only stores a full cine of Raw Data, and not Display Data. Display data is only available once the collector thread has signaled another process to take the data from the cine and perform scan-conversion and other filtering or processing methods, and is offered in a single buffer. Once frozen, the calling program can access Display Data by calling processCineImage and then making the appropriate call to get access to it. This is important to note, because processing of a frame may take some time, depending on the type of frame (B, Color Doppler, etc.) as well as the parameters set (filtering, zoom, etc.).

Parameter Control
Parameters can be a challenge to wrap one's head around, as there are hundreds of parameters that control how imaging is done on the ultrasound system. Thankfully, there are many presets that come with Porta that optimize these parameters so little modification needs to be performed. General functions such as imaging depth, gain and frequency are typical for most applications and therefore Porta based applications will want to make use of these through the parameters interface. The basic steps for changing parameters are as follows:
 * 1) Set the parameter value
 * 2) Check if pipeline is running, stop if so
 * 3) Call updateImagingParams to ensure the tables that get loaded to the hardware are recalculated
 * 4) Call uploadData to actually write the tables to the hardware
 * 5) Call updateDisplayParams to ensure any parameter affecting the processing of the image on the PC will get properly updated
 * 6) If pipeline was running, restart it

This can be slow due to the time it takes to recalculate tables and upload the tables to the hardware. Ultrasonix optimizes this process in it's clinical and research interface software by queueing up parameter changes, and using a worker thread to do the updating. For instance, if the user dials the gain 5 clicks, it may not be important to process each individual click, as this will result in a lag to the user. The worker thread can queue up these clicks, until some timer has expired, then update the final result of 5 clicks at once (ie. if gain were 50% and 1 click = 1%, a 5% change would result at once to the user, not 1% times 5 separate updates).

Parameter Types
There are various types of parameters that Porta and other Ultrasonix software makes use of. Most of the parameters are integer values, however some important ones that may need to be changed include the 8 point gain curve that represents the time-gain-control (or TGC) curve. There are also rectangle parameters for specifying bounding areas, and 3 point curves that represent system gain curves and aperture openings as a function of time.

Display Processing
Display data, as discussed is the actual ultrasound image that the user should see. It has been scan-converted and processed with various mapping curves and filtering techniques to enhance image quality. The size of the display ultrasound image is specified when calling setDisplayDimensions. Note that the larger the dimensions, the slower it will be to process a single frame. Typical Ultrasonix software uses a 640x480 display area. If the processing takes too long, the collector thread will still notify the processing worker thread, however it will be ignored if busy, and the display frame rate will be lower than the acquisition frame rate. Typical display times can be estimated at 10 to 30 milliseconds depending on the type of data and parameters setting.

Two types of display data can be obtained:
 * 1) Greyscale data in 8 bit format
 * 2) RGB data in 32 bit format

Greyscale is probably the best for most cases, however RGB may be desirable for chroma imaging, and a must when acquiring color Doppler data, since Doppler processing has to use a 32 bit color map. Chroma and color maps can be imported through some of Porta's functions.

Image Geometry and Scaling
To make it simpler for drawing overlays on images, Porta implements some useful functions for:
 * Obtaining region-of-interests (ROI)
 * Converting pixel coordinates into ultrasound coordinates and vice-versa
 * Obtaining scaling parameters for making measurements
 * Obtaining GDI based arc rectangles for properly drawing overlays on fan (convex transducers) and phased-array images

Motor Control
Propello is a popular open-source application developed on top of the Porta SDK, that can be used for acquiring volumetric ultrasound data. Apart from Propello, developers can implement their own motor control to volumetric probes by interfacing with the functions and parameters that Porta provides. Both manual and automatic modes can be programmed; where manual mode allows stepping of the motor to specific locations in between imaging, and automatic mode allows for continual sweeping of the transducer back and forth while in a given imaging mode.