View source for Configuring the CTPClient Application for Clinical Trials

The CTPClient application is a program for anonymizing images and transmitting them from image acquisition sites to principal investigator sites in clinical trials. This article describes how to configure, distribute, and run the program. The intended audience for this article is clinical trial administrators and their software minions.

==Running CTPClient==
CTPClient can be launched via the Java webstart mechanism, thus removing the necessity for installing CTP applications at the image acquisition sites. When run via webstart, the user accesses a URL on the principal investigator's CTP site, and the CTP site then downloads CTPClient and starts it. The recommended method for launching CTPClient via webstart is to use the CTP Application Server on the CTP site. For general information on the Application Server, see [[Using the CTP Application Server]].

CTPClient can also be launched as a stand-alone application installed on the client computer. When run stand-alone, the program is started by double-clicking the program's icon or by launching a command window and entering the command:

:<b><tt>java -jar CTPClient.jar [options]</tt></b>

where [options] is a series of quoted parameters, each in the form:

:<b><tt>"param=value"</tt></b>

==The Processing Pipeline==
CTPClient has a fixed processing pipeline consisting of these stages, in this order:
* DicomFilter
* DicomPixelAnonymizer
* DicomAnonymizer
* HttpExportService

The DicomFilter and DicomPixelAnonymizer stages must be explicitly enabled using the parameters described below. The DicomAnonymizer is always enabled.

No default script is provided for the DicomFilter.

Default scripts are provided for the DicomPixelAnonymizer and the DicomAnonymizer. 

No default lookup table is provided for the DicomAnonymizer.

As mentioned in [[#Building CTPClient|Building CTPClient]], below, for specific applications, a special CTPClient build can be done, including application-specific filter scripts and configuration parameters.

==Run-time Configuration==
CTPClient is designed to be configured by setting the [options] parameters for the transmitting site. When run via webstart, these parameters can be supplied by query parameters in the URL, as in this example:

:<b><tt>http://ctp.university.edu/webstart/CTPClient?param1=value1&param2=value2</tt></b>

Note that when a value includes whitespace or any other characters that are illegal in a URL, the value must be URL-encoded.

The parameters supported by the program are:

*<b><tt><font size=4>windowTitle</font></tt></b>: The text to be shown in the title bar of the CTP Client window. The default is "CTP Client".
*<b><tt><font size=4>panelTitle</font></tt></b>: The text to be shown at the top of the main pane in the CTPClient UI. The default is "CTP Client".
*<b><tt><font size=4>helpURL</font></tt></b>: The URL to be accessed when the user clicks the Help button on the CTPClient UI. If this parameter is missing, the Help button is not displayed.


*<b><tt><font size=4>acceptNonImageObjects</font></tt></b>: Specifies whether non-image objects are to be selected for processing. If set to "yes", all objects are accepted. If set to any other value, only images are accepted. The default configuration only accepts image objects.


*<b><tt><font size=4>dfEnabled</font></tt></b>: Specifies whether to use the DicomFilter to select objects for processing. If set to "yes", objects are selected using the DicomFilter script. If set to any other value, no filtering is done.
*<b><tt><font size=4>dfScriptName</font></tt></b>: The name of a DicomFilter script file stored on the CTP server in the same directory as the CTPClient being served by the Application Server. When present, CTPClient downloads the script file from the server. When not present, CTPClient looks for the default script (<b><tt>DF.script</tt></b>) built into the application. If no default script is found, the DicomFilter stage is disabled, even if the dfEnabled parameter is set to "yes".


*<b><tt><font size=4>dpaEnabled</font></tt></b>: Specifies whether the DicomPixelAnonymizer is to be included in the processing of objects. If set to "yes", objects are processed using the DicomPixelAnonymizer script. If set to any other value, no pixel anonymization is done.
*<b><tt><font size=4>dpaScriptName</font></tt></b>: The name of a DicomPixelAnonymizer script file stored on the CTP server in the same directory as the CTPClient being served by the Application Server. When present, CTPClient downloads the script file from the server. When not present, CTPClient looks for the default script (<b><tt>DPA.script</tt></b>) built into the application. If no default script is found, the DicomPixelAnonymizer stage is disabled, even if the dpaEnabled parameter is set to "yes".


*<b><tt><font size=4>daScriptName</font></tt></b>: The name of a DicomAnonymizer script file stored on the CTP server in the same directory as the CTPClient being served by the Application Server. When present, CTPClient downloads the script file from the server. When not present, CTPClient uses the default script (<b><tt>DA.script</tt></b>) built into the application.
*<b><tt><font size=4>daLUTName</font></tt></b>: The name of a DicomAnonymizer lookup table file stored on the CTP server in the same directory as the CTPClient being served by the Application Server. When present, CTPClient downloads the lookup table file from the server. When not present, CTPClient looks for the default lookup table (<b><tt>LUT.properties</tt></b>) built into the application. If no lookup table is available, an empty lookup table is provided.


*<b><tt><font size=4>url</font></tt></b>: The URL of the destination HttpImportService.
*<b><tt><font size=4>showURL</font></tt></b>: "yes" to display a UI field for entering the URL of the destination HttpImportService. "no" to suppress the UI field, thus forcing the URL to be the value of the <b><tt>url</tt></b> parameter. The default value is "yes".


In addition to the standard parameters above, CTPClient supports special parameters for modifying the DicomAnonymizer script parameters and lookup table entries. 

Any parameter name starting with the at-sign ( '@' ) is treated as the name of an anonymizer script parameter, and the parameter value is substituted for the value of the parameter in the script. The intent of this feature is to allow a standard script to be tailored for a specific image acquisition site.

Any parameter name starting with the dollar-sign ( '$' ) is treated as the name of an anonymizer lookup table parameter, and the parameter value is substituted for the value of the parameter in the lookup table. The intent of this feature is to allow a standard lookup table to be tailored for a specific image acquisition site.

The Application Server supplies three parameters automatically when starting CTPClient. These are used by CTPClient to contact the server when the <b><tt>dfScriptName</tt></b>, <b><tt>dpaScriptName</tt></b>, <b><tt>daScriptName</tt></b> or <b><tt>daLUTName</tt></b> parameters are supplied. If CTPClient is not started via webstart and the project requires that these files be obtained from a server, the parameters must be supplied explicitly.

*<b><tt><font size=4>protocol</font></tt></b>: The protocol to be used for communication with the CTP site's web server.
*<b><tt><font size=4>host</font></tt></b>: The host IP address or domain name (and port) of the CTP site's web server.
*<b><tt><font size=4>application</font></tt></b>: The name of the application ("<b><tt>CTPClient</tt></b>").

==Building CTPClient==
The CTPClient <b><tt>jar</tt></b> file contains default configuration files, including:
* config.properties
* DA.script
* LUT.properties

In some trials, it may be desired to build a special version of CTPClient with pre-configured values in the configuration files.

The source code for CTPClient is on GitHub at https://github.com/johnperry/CTPClient.

The default configuration files are located in the <b><tt>source/files</tt></b> directory.

The program is built using <b><tt>ant</tt></b>. After the build is complete, a zip file containing all the files necessary for deployment is located in the <b><tt>products</tt></b> directory.

==Deploying CTPClient on the CTP Application Server==
As described in [[Using the CTP Application Server]], all the files for CTPClient must be placed in the <b><tt>CTP/ROOT/CTPClient</tt></b> directory. The latest version is encapsulated in a zip file on the RSNA MIRC site at http://mirc.rsna.org/download/CTPClient.zip. 

Included in the zip file is the XSL file required by the Application Server for automatic creation of the webstart <b><tt>jnlp</tt></b> file.

To deploy CTPClient, create the CTP/ROOT/CTPClient directory and copy all the files from the zip file into it.