Plus applications user manual  2.9.0.e3e8b4a
Software library for tracked ultrasound image acquisition, calibration, and processing.
Freehand tracked ultrasound calibration application (fCal)

This algorithm computes transformation between a phantom object coordinate system (Phantom) and the coordinate system of tracking marker attached to the object (Reference) by point matching. Point coordinates are defined in the Phantom coordinate system and coordinates of the same points are also acquired in the Reference coordinate system by using a tracked stylus (StylusTip).


Coordinate system definitions used by fCal


  1. Select the Device set from the Ultrasound display and then select fcal from the options that appear.
  2. Open a command session from within the directory where fCal.exe is kept and enter "fCal.exe" in the command line (you can also just double-click on fCal.exe).
  3. Select the configuration file corresponding to your hardware setup
  4. Optionally edit the configuration file (to change IP address, port numbers, etc.)
  5. Click Connect
  6. Wait for all of the devices to connect
  7. Check that the instruments (Probe and Stylus) can be seen by the camera. This can be done by looking within the interface for a small box on the left that will either say "missing" or "OK". The tool state box can be detached so that it is visible during all steps by clicking on the little button in its corner.

Stylus Calibration

  1. Click "Start"
  2. Before the startup timer elapses move the stylus tip into a chosen position. Make sure to not move the tip of the stylus after the timer elapsed.
  3. Swivel the stylus while keeping the tip at the same position until all the points have been collected. Slower movement and larger swivel angle range gives more accurate calibration.


Phantom Registration

Prerequisites: Stylus calibration performed

  1. Click "Start Landmark Detection"
  2. Place the tip of the calibrated stylus on the phantom at the first landmark point and slowly swivel the stylus until it is detected. Alternatively, place the tip of the stylus at the indicated point and keep it there while clicking "Record Point".
  3. Repeat the previous step for each landmark (in the order specified in the configuration file, typically from #1 to #8) until all landmark points are recorded. All recorded points are shown in green, the next expected point position (available only if a few points have been recorded already) are shown in orange.

See demo video at:


Temporal Calibration

  1. Click "Start"
  2. Start moving the tracked ultrasound transducer up-and-down with a periodic motion along a line, while imaging the bottom of the water tank (see more details at Temporal calibration). Make sure that the periodic motion pattern starts before the startup timer is elapsed.
  3. Continue the periodic motion until the calibration completes.
  1. Click "Show plots" to verify that the motion was periodic and after time offset compensation the position signals are aligned accurately.

See demo video at:

Spatial Calibration

Prerequisites: Stylus calibration, Phantom calibration, Temporal calibration performed

For calibration of curvilinear transducers the speed of sound setting in the ultrasound system shall match the actual speed of sound in the liquid where the calibration is performed in (otherwise the image will be distorted after scan conversion). Either set the speed of sound to in the ultrasound machine (to about 1490m/s, corresponding to speed of sound in room temperature water), or use a mixture in that the speed of sound is 1540m/s (the typical speed in soft tissue, assumed by most ultrasound imaging systems). 9% by volume mixture of ethylene glycol and water, degassed, could be a suitable mixture - see Goldstein et al. "Design of Quality Assurance for Sonographic Prostate Brachytherapy Needle Guides", 2002.

Set a low gain value and adjust dynamic range on your ultrasound machine to make the image mostly black, with only the wires visible. Try to use a water tank large enough so that the bottom (or reflection from the bottom or sides) is not visible in the image. It is better to make the wire intersections appear as small, barely visible gray points than large, very bright spots for two reasons. 1. Wire intersection positions cannot be determined accurately if the it appears as a large bright blob. 2. If the image is too bright then the calibration algorithm may detect too many point candidates and the application may slow down or may appear to hang for minutes.

  1. Click "Start"
  2. Move the transducer into a position where all the phantom wires are visible. Green dots should appear over the wire points in the image, which indicates that the wire positions are successully detected. If fCal appears to hang (due to too many potential wire intersection points are detected in the image) then lower the gain settings on your ultrasound system.
  3. Keep the probe approximately orthogonal to the wires to have optimal image quality and move it slowly. There is no need to tilt or rotate the probe, only translate between the front and back face of the phantom and optionally move slightly up&down and left&right so that the fiducial positions throughout the calibration are distributed over the region of interest that will later be used for imaging.
  4. Once the calibration has been done, the result transformation matrix and the errors appear in the toolbox, and the Show devices checkbox becomes enabled
  5. Check Show devices to see the devices in 3D
  6. You can save the results by clicking the Save results button


Running fCal in simulation mode (for testing only)

Start fCal by executing fCal.exe After startup, the Configuration toolbox appears.

Stylus calibration

  1. Select the Device set named "TEST Simulation mode for Stylus calibration" from the drop-down box and click Connect
  2. Switch to Stylus calibration toolbox by clicking its tab on the left side of the application window
  3. Click Start button The simulation begins, the acquired points appear on the canvas on the right side as small blue dots. The green bar on the bottom shows the progress. When all the points are aquired, the calibration runs, and the results appear in the toolbox. Also the stylus tip appears on the canvas as a green sphere, and the stylus is displayed. It moves around as the simulator feeds the new positions to it.
  4. The results can be saved by clicking on Save results button as a new XML file

Go back to the Configuration toolbox and click Disconnect to make the new connection possible.

Phantom registration

  1. Select the Device set named "TEST Simulation mode for Phantom registration" from the drop-down box and click Connect
  2. Switch to Phantom registration toolbox by clicking its tab on the left side of the application window The phantom appears in the 3D window in the middle of the toolbox It can be rotated (left click and drag), zoomed (right click and drag or mouse wheel) and moved around (middle button + drag). The red dot shows the first landmark to record.
  3. Click record point The first recorded landmark appears along with the stylus on the main canvas in the right side of the screen.
  4. Continue clicking on Record point button After the 3rd recorded point, the phantom registration runs on the already acquired data and it appears on its approximate position. It will move slightly when additional points are recorded. (Click Undo to make the last point disappear or Reset to start over)
  5. After the 8th recorded point, the Save results button becomes active, clicking on which the result can be saved in a new XML file

Go back to the Configuration toolbox and click Disconnect to make the new connection possible.

Spatial calibration

  1. Select the Device set named "Saved dataset for both video and tracking (fCal)" from the drop-down box and click Connect
  2. Switch to Freehand calibration toolbox by clicking on its tab on the left side of the application window The video source shows up in the main canvas (By clicking the Edit segmentation parameters button - the "edit-like" button in the line of Segmentation parameters - a dialog appears in which the segmentation parameters can be changed)
  3. Click Start button to start calibration The calibration begins, the segmented points appear as green dots on the image. The green bar on the bottom shows the progress. When it finishes, the result matrix and the errors are displayed on the toolbox.
  4. Show devices checkbox becomes enabled. Clicking on it changes display mode so the tools are displayed in the main canvas instead of the image 5.The results can be saved by clicking on Save results button as a new XML file

Frequently asked questions

What are the differences between the different calibration phantom versions?

fCal-2.x is recommended for small field of view (up to about 10cm imaging depth). fCal-3.x is recommended for larger field of view. See more information at Phantom definition .

I get large (>1mm) stylus calibration error - what's wrong?

Typical stylus calibration error is typically less than 0.5mm. If you have higher error then check the followings:

I get large (>2-3mm) probe spatial calibration error - what's wrong?

Typical calibration error is 0.8-1.5mm, which can go down to <0.5mm with an optimal setup.

If you have larger error check the followings:

The axes of the ImageToProbeTransform (calibration matrix) are not orthogonal

The probe calibration algorithm determines the ImageToProbeTransform axes independently, therefore if there is an error in the calibration procedure then the computed coordinate axes may not be orthogonal.

How to detect: when the computed axes are not orthogonal fCal displays a warning message and the "User image to probe transform matrix orthogonality test failed" warning message is logged.

Root cause: most frequently the root cause of the problem is that the phantom description does not match the actual phantom geometry (the wire positions in the phantom are not the same as the actual wire positions) or it may be caused by having a large number of fiducial line intersection point detection errors (the calibration algorithm can remove a limited number of outliers if they are very different from the true positions and the outliers are less than about 5-10% of the data).


  1. Check that the phantom description matches the actual phantom wiring
  2. Check that the fiducial line intersection points are correctly detected on the images. Adjust the segmentation parameters, if necessary.
  3. Performs all the checks listed in the "I get large (>2-3mm) calibration error..." section

Plus can enforce the ImageToProbe matrix to be orthogonal. To enable this feature, add two attributes to the vtkPlusProbeCalibrationAlgo element: OptimizationMethod="2D" and IsotropicPixelSpacing="TRUE". Set IsotropicPixelSpacing to false if you use a linear probe and you calibrate in a liquid in that the speed of sound is not the same as the setting in the ultrasound scanner (e.g., speed of sound in water is about 1490m/s, speed of sound by default on most ultrasound scanners is set to 1540m/s).

No points can be collected during stylus calibration

If the stylus has been calibrated already (e.g., with the NDI toolviewer) then the stylus position remains the same when the stylus is pivoted around its tip. The stylus calibration method requires unique positions, therefore the algorithm will not work if it is attempted to apply on an already calibrated stylus.

If the stylus has been already calibrated outside PLUS then just add the following calibration matrix to the CoordinateDefinitions element in the device set configuration file:

<Transform From="StylusTip" To="Stylus" Matrix="1 0 0 0   0 1 0 0   0 0 1 0   0 0 0 1" /> 

then in fCal simply skip the stylus calibration step.

There is a misalignment along the M-U (marked-unmarked) axis after spatial calibration

This is probably caused by inaccurate stylus or phantom calibration. If you use an electromagnetic tracker then place the sensor as close to the needle tip as possible. If possible, use a thick needle (with a sensor near the tip of the needle) as stylus.

Configuration settings

Example configuration file PlusDeviceSet_fCal_SonixTouch_L14-5_Ascension3DG_2.0.xml

<PlusConfiguration version="2.3">
<DataCollection StartupDelaySec="1.0" >
Name="fCal: Ultrasonix US (L14-5 probe) + Ascension3DG tracker (Probe, Reference, Stylus) - fCal Phantom 2.1"
Description="Ascension3DG sensors should be plugged in to the Ascension3DG DriveBay mounted on Ultrasonix US in the following order from to leftmost slot (Transducer 1) to the right: 1 Probe, 2 Reference, 3 Stylus." />
ToolReferenceFrame="Tracker" >
<DataSource Type="Tool" Id="Probe" PortName="0" />
<DataSource Type="Tool" Id="Reference" PortName="1" />
<DataSource Type="Tool" Id="Stylus" PortName="2" />
<OutputChannel Id="TrackerStream" >
<DataSource Id="Probe"/>
<DataSource Id="Reference"/>
<DataSource Id="Stylus"/>
AutoClipEnabled="TRUE" >
<DataSource Type="Video" Id="Video" PortName="B" PortUsImageOrientation="UF" />
<OutputChannel Id="VideoStream" VideoDataSourceId="Video"/>
Type="VirtualMixer" >
<InputChannel Id="TrackerStream" />
<InputChannel Id="VideoStream" />
<OutputChannel Id="TrackedVideoStream"/>
<Transform From="Image" To="TransducerOriginPixel"
Matrix="1 0 0 -410
0 1 0 5
0 0 1 0
0 0 0 1"
Date="2011.12.06 17:57:00" Error="0.0" />
<Rendering WorldCoordinateFrame="Reference">
<DisplayableObject Type="Model" ObjectCoordinateFrame="TransducerOrigin" Id="ProbeModel"
-1 0 0 29.7
0 -1 0 1.5
0 0 1 -14
0 0 0 1" />
<DisplayableObject Type="Model" ObjectCoordinateFrame="Reference" Id="Volume"/>
<DisplayableObject Type="Model" ObjectCoordinateFrame="StylusTip" Id="StylusModel" File="Stylus_Example.stl" />
<DisplayableObject Id="PhantomModel" Type="Model" ObjectCoordinateFrame="Phantom"
1 0 0 -35.0
0 1 0 -10.0
0 0 1 -5.0
0 0 0 1" />
<DisplayableObject Type="Image" ObjectCoordinateFrame="Image" Id="LiveImage"/>
ClipRectangleOrigin="27 27"
ClipRectangleSize="766 562"
/> <PhantomDefinition>
Institution="Queen's University PerkLab"
<Pattern Type="NWire">
<Wire Name="7:G1_g1" EndPointFront="30.0 0.0 0.0" EndPointBack="30.0 0.0 40.0" />
<Wire Name="8:L1_h1" EndPointFront="55.0 0.0 0.0" EndPointBack="35.0 0.0 40.0" />
<Wire Name="9:M1_m1" EndPointFront="60.0 0.0 0.0" EndPointBack="60.0 0.0 40.0" />
<Pattern Type="NWire">
<Wire Name="4:G3_g3" EndPointFront="30.0 10.0 0.0" EndPointBack="30.0 10.0 40.0" />
<Wire Name="5:H3_l3" EndPointFront="35.0 10.0 0.0" EndPointBack="55.0 10.0 40.0" />
<Wire Name="6:M3_m3" EndPointFront="60.0 10.0 0.0" EndPointBack="60.0 10.0 40.0" />
<Pattern Type="NWire">
<Wire Name="1:H5_h5" EndPointFront="35.0 20.0 0.0" EndPointBack="35.0 20.0 40.0" />
<Wire Name="2:L5_i5" EndPointFront="55.0 20.0 0.0" EndPointBack="40.0 20.0 40.0" />
<Wire Name="3:M5_m5" EndPointFront="60.0 20.0 0.0" EndPointBack="60.0 20.0 40.0" />
<Landmark Name="#1" Position="-32.53 -5.25 45.0" />
<Landmark Name="#2" Position="-32.53 -5.25 5.0" />
<Landmark Name="#3" Position="-32.53 19.75 -5.0" />
<Landmark Name="#4" Position="-32.53 19.75 45.0" />
<Landmark Name="#5" Position="105.47 -5.25 -5.0" />
<Landmark Name="#6" Position="105.47 -5.25 45.0" />
<Landmark Name="#7" Position="105.47 14.75 -5.0" />
<Landmark Name="#8" Position="105.47 19.75 45.0" />
<Landmark Name="#9" Position=" -3.53 -9.25 45.0" />
<Landmark Name="#10" Position=" 41.47 -9.25 45.0" />
<Landmark Name="#11" Position=" 86.47 -9.25 45.0" />
<Landmark Name="#12" Position=" 96.47 -9.25 30.0" />
<Landmark Name="#13" Position=" 86.47 -9.25 -5.0" />
<Landmark Name="#14" Position=" 21.47 -9.25 -5.0" />
<Landmark Name="#15" Position=" -3.53 -9.25 -5.0" />
<Landmark Name="#16" Position="-13.53 -9.25 10.0" />
<VolumeReconstruction OutputSpacing="0.5 0.5 0.5"
ClipRectangleOrigin="0 0" ClipRectangleSize="820 616"
Interpolation="LINEAR" Optimization="FULL" CompoundingMode="MEAN" FillHoles="OFF" />
FreeHandStartupDelaySec="5" />
ObjectPivotPointCoordinateFrame="StylusTip" />
StylusTipMaximumDisplacementThresholdMm="1.8" />
ReferenceCoordinateFrame="Reference" />