Configuring the CTPClient Application for Clinical Trials

From MircWiki
Revision as of 20:52, 16 July 2018 by Johnperry (talk | contribs) (→‎Export Service Parameters)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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.

1 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 browser 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:

java -jar CTPClient.jar [options]

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

"param=value"

2 The Processing Pipeline

2.1 Import Services

CTPClient has two import mechanisms.

  • Locally stored files can be manually selected.
  • A DICOM Storage SCP can be enabled to receive files from PACS systems or workstations.

2.2 Processing Stages

CTPClient has a fixed processing pipeline consisting of these stages, in this order:

  • DicomFilter
  • DicomDecompressor
  • DicomPixelAnonymizer
  • DicomAnonymizer

The DicomFilter and DicomPixelAnonymizer stages must be explicitly enabled using the parameters described in the next section. The DicomDecompressor stage is run only if the object being processed matches a signature of the DicomPixelAnonymizer; otherwise, the object is not decompressed. See The CTP DICOM Pixel Anonymizer for more information.

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.

2.3 ExportServices

CTPClient has four export services:

  • HttpExportService
  • DicomExportService
  • STOWRSExportService
  • DirectoryStorageService

3 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:

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

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

As mentioned in Building CTPClient, below, a special CTPClient build can be created for specific applications, including application-specific files and configuration parameters.

3.1 Configuration Parameters

The parameters supported by the program are shown below.

3.1.1 Window Display Parameters

  • windowTitle: The text to be shown in the title bar of the CTP Client window. The default is "CTP Client".
  • panelTitle: The text to be shown at the top of the main pane in the CTPClient UI. The default is "CTP Client".
  • helpURL: 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.

3.1.2 Import Service Parameters

  • showBrowseButton: Specifies whether to display a button allowing the user to browse the local disk for images to display. If an scpPort is defined and the showBrowseButton parameter is set to "no", a browse button is not displayed. If the parameter is set to any other value, the dialog button is displayed, whether an scpPort parameter is supplied or not.
  • scpPort: The port on which CTPClient is to start a DICOM Storage SCP to receive objects via the DICOM protocol. If set to any integer greater than zero, CTPClient starts the SCP and accepts transfers from DICOM Storage SCUs. If the parameter is not supplied, or if it is blank or a non-integer value, the SCP is disabled. The default configuration does not enable the SCP.
  • acceptNonImageObjects: 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.
  • dialogEnabled: Specifies whether to provide a dialog for entry of parameters at runtime. If set to "yes", a dialog is constructed from definitions in an XML file. If set to any other value, no dialog is provided.
  • dialogName: The name of an XML file stored on the CTP server in the same directory as the CTPClient being served by the Application Server. If the file is not found on the server, CTPClient looks for the file in the same directory in which the program is running. If that fails, CTPClient looks for the default dialog file built into the application (DIALOG.xml). If the XML file cannot be found, the dialog is disabled, even if the dialogEnabled parameter is set to "yes". Values provided by the user in the dialog are treated as if they were options included in the start command of the program. {See The Dialog XML Schema for a description of how to configure the dialog.)
  • showDialogButton: Specifies whether to display a button allowing the user to display the dialog. If set to "no", a dialog button is not displayed. If set to any other value, the dialog button is displayed.

3.1.3 Processing Pipeline Parameters

  • dfEnabled: 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.
  • dfScriptName: 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 (DF.script) built into the application. If no default script is found, the DicomFilter stage is disabled, even if the dfEnabled parameter is set to "yes".
  • dpaEnabled: 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.
  • dpaScriptName: 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 (DPA.script) built into the application. If no default script is found, the DicomPixelAnonymizer stage is disabled, even if the dpaEnabled parameter is set to "yes".
  • setBurnedInAnnotation: Specifies whether the BurnedInAnnotation element is to be set to "NO" for DICOM objects that match a DicomPixelAnonymizer signature. If set to "yes", the element value is set, if the parameter is missing or has any other value, the element is not modified.
  • daScriptName: 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 (DA.script) built into the application.
  • daLUTName: 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 (LUT.properties) built into the application. If no lookup table is available, an empty lookup table is provided.

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 an anonymizer script modification. The '@' is removed, and the rest of the parameter name is used as the name of a script PARAM. The parameter value (the text after the '=' character) is used as the value for that PARAM. The intent of this feature is to allow a standard script to be tailored for a specific image acquisition site. Note that this feature does not allow element scripts to be modified; it only allows script PARAM values to be changed.

Any parameter name starting with the dollar-sign ( '$' ) is treated as a lookup table modification. The '$' is removed, and the rest of the parameter name is used as the lookup table key. The parameter value (the text after the '=' character) is used as the value for that key. The intent of this feature is to allow a standard lookup table to be tailored for a specific image acquisition site.

For more information on anonymizer parameters and lookup tables, see The CTP DICOM Anonymizer, The CTP DICOM Anonymizer Configurator, and The CTP Lookup Table Editor.

3.1.4 Export Service Parameters

  • httpURL: The URL of the destination HttpImportService. If this parameter is not supplied, or if it is blank, the HttpExportService is disabled. This parameter must be a complete URL, including the protocol (http://IP:port or https://IP:port).
  • showURL: "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 httpURL parameter. The default value is "yes".
  • zip: "yes" to zip files before transmission via HTTP. The default value is "no". This feature is intended only for transmissions to a CTP site with an HttpImportService configured with a zip parameter set to "yes".
  • xnatAuthURL: The URL of the XNAT server's authentication service. If this parameter is not supplied, or if it is blank, no authentication is performed, and the XNAT session cookie is not supplied in transfers. This parameter must be a complete URL, including the protocol (e.g. http://IP:port/data/JSESSION).
  • xnatUsername: The username for authentication on the XNAT server.
  • xnatPassword: The password for authentication on the XNAT server.
  • xnatCookiename: The session cookie name used by the XNAT server. If this parameter is missing, the default name "JSESSIONID" is supplied.
  • dicomURL: The URL of the destination DICOM Storage SCP (e.g. PACS or workstation). If this parameter is not supplied, or if it is blank, the DicomExportService is disabled. This parameter must be a complete URL, including the protocol (e.g. dicom://CalledAET:CallingAET@IP:port).
  • stowURL: The URL of the destination DICOM STOW-RS Service. If this parameter is not supplied, or if it is blank, the DicomSTOWRSExportService is disabled. This parameter must be a complete URL, including the protocol (e.g. http://ip:port).
  • stowUsername: The username to be used when authenticating with the destination DICOM STOW-RS Service. If this parameter is not supplied, or if it is blank, authentication credentials are not supplied when transferring to the destination system.
  • stowPassword: The password to be used when authenticating with the destination DICOM STOW-RS Service.
  • exportDirectory: The path to a directory in which processed files are to be stored. Files are stored with names constructed from their SOPInstanceUIDs. If this parameter is not supplied, or if it is blank, the DirectoryStorageService is disabled.
  • renameFiles: Whether to rename exported files in the form Study_Series_Acquisition_Instance.dcm. If this parameter is not supplied, or if its value is not "yes", files are named by their SOPInstanceUID values.

Note: If CTPClient is configured to export to an HTTP destination that requires authentication, the credentials can be included in the httpURL parameter like this: http://username:password@IPAddress:port. If the credentials are omitted from the URL and the destination requires them, CTPClient displays a dialog allowing the user to enter the credentials at the time of transmission.

3.1.5 Webstart Parameters

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

  • protocol: The protocol to be used for communication with the CTP site's web server.
  • host: The host IP address or domain name (and port) of the CTP site's web server.
  • application: The name of the application ("CTPClient").

3.1.6 Debugging Parameters

When processing very large (typically multi-frame) objects, it may be necessary to allocate more than the default memory to the application using the max-heap-size attribute described in Using the CTP Application Server. To make it easy to see how much memory is in use, a button can be displayed in the application's window footer bar by enabling the showMemory parameter.

  • showMemory: "yes" to display the button. The default is "no".

3.2 Default Configuration

3.2.1 Webstart

For CTPClient instances that are run via Java webstart, it is possible to predefine parameter values in the CTPClient.xsl file stored on the server. This file will be located under the CTP/ROOT directory, typically in a first-generation child called CTPClient, although it is possible to locate it at a lower level, as in CTP/ROOT/MyTrial/CTPClient. The standard CTPClient.xsl file looks like this: 

<?xml version="1.0" encoding="iso-8859-1"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:output method="xml" encoding="utf-8" omit-xml-declaration="yes" />

<xsl:template match="/jnlp">
    <jnlp
        codebase="{environment/protocol}://{environment/host}/{environment/application}" >
        <!-- href="{environment/application}.jnlp" > -->

        <information>
            <title>CTP Client Utility</title>
            <vendor>RSNA</vendor>
            <homepage href="http://mircwiki.rsna.org/index.php?title=CTP-The_RSNA_Clinical_Trial_Processor"/>
            <description>CTP Client Utility</description>
            <description kind="short">Java Web Start program for transmitting data to CTP for clinical trials.</description>
            <!-- <offline-allowed/> -->
        </information>

        <security>
            <all-permissions/>
        </security>

        <resources>
            <j2se version="1.6+"/>
            <jar href="CTPClient.jar"/>
            <jar href="CTP.jar"/>
            <jar href="dcm4che.jar"/>
            <jar href="dcm4che-imageio-rle-2.0.25.jar"/>
            <jar href="jdbm.jar"/>
            <jar href="log4j.jar"/>
            <jar href="util.jar"/>
        </resources>

        <application-desc main-class="client.CTPClient">
            <argument>"protocol=<xsl:value-of select="environment/protocol"/>"</argument>
            <argument>"host=<xsl:value-of select="environment/host"/>"</argument>
            <argument>"application=<xsl:value-of select="environment/application"/>"</argument>
            <xsl:apply-templates select="params/param"/>
        </application-desc>
    </jnlp>
</xsl:template>

<xsl:template match="param">
    <argument>"<xsl:value-of select="."/>"</argument>
</xsl:template>

</xsl:stylesheet>

To predefine parameters, add argument elements to the application-desc element like this: 

        <application-desc main-class="client.CTPClient">
            <argument>"protocol=<xsl:value-of select="environment/protocol"/>"</argument>
            <argument>"host=<xsl:value-of select="environment/host"/>"</argument>
            <argument>"application=<xsl:value-of select="environment/application"/>"</argument>
            <argument>"name1=value1"</argument>
            <argument>"name2=value2"</argument>
            <argument>"name3=value3"</argument>
            ...etc...
            <xsl:apply-templates select="params/param"/>
        </application-desc>

For example: 

        <application-desc main-class="client.CTPClient">
            <argument>"protocol=<xsl:value-of select="environment/protocol"/>"</argument>
            <argument>"host=<xsl:value-of select="environment/host"/>"</argument>
            <argument>"application=<xsl:value-of select="environment/application"/>"</argument>
            <argument>"panelTitle=My Trial CTP Client"</argument>
            <argument>"showBrowseButton=yes"</argument>
            <argument>"dialogName=DIALOG.xml"</argument>
            <argument>"httpURL=http://theURL:80"</argument>
            <argument>"showURL=yes"</argument>
            <argument>"daScriptName=CTPClient.script"</argument>
            <xsl:apply-templates select="params/param"/>
        </application-desc>

Note that by placing the predefined parameters before the xsl:apply-templates instruction, any parameters that are included in the URL itself will override the defaults.

3.2.2 Local

For CTPClient instances that are installed locally, it is possible to predefine parameter values in a properties file. The file must be called config.default, and it must be stored in the same directory as CTPClient.jar. Here is an example: 

windowTitle=My Trial
PanelTitle=My Trial
helpURL=http://ctp.myUniversity.edu/myTrial/help.html
dialogEnabled=yes
dialogName=myTrialDialog.xml
showDialogButton=no
dfEnabled=no
dpaEnabled=yes
daScriptName=myTrialDAScript.script
httpURL=http://ctp.PrincipalInvestigator.org:9999
showURL=no
showBrowseButton=yes

Properties files use the backslash character for escaping special characters, so if a backslash character is required in a property, it must be escaped by a backslash. Even on a Windows system, forward slashes work in specifying file paths in property values.

4 The Dialog XML Schema

When the dialogEnabled parameter is set to "yes", CTPClient loads an XML file to define the contents of a dialog allowing the user to enter values for parameters. The following is an example XML structure specifying three parameters: 

<dialog  title="New Patient" mode="study">
    <h>Site Parameters</h>
    <p>
        Enter the ID value for this site.
    </p>
    <param
        name="@SITEID"
        label="Site ID"
        value=""/>
    <h>Patient Parameters</h>
    <p>
        Enter the ID and name values for this patient.
    </p>
    <param
        name="@SUBJECTID"
        label="Subject ID"
        value=""/>
    <param
        name="@SUBJECTNAME"
        label="Subject Name"
        value=""/>
</dialog>

The title attribute of the root element specifies the title of the popup. The title is also used as the name of the button in the main CTPClient window for displaying the dialog, so it should be fairly short.

The mode attribute of the root element specifies the whether the dialog is to be displayed once for each study transmitted ("study" mode) or once for each click of the Start button ("session" mode). The default is study mode.

The h element specifies a heading. The element has one optional attribute, align, with allowed values left, center, and right, The default is center.

The p element specifies a paragraph. Word wrapping is not provided; lines are broken at newline characters. The element has one optional attribute, align, with allowed values left, center, and right, The default is left.

The param element specifies a parameter whose value is to be entered into the dialog by the user.

  • The name attribute specifies the name of an option parameter.
  • The label attribute specifies the text to be displayed beside the entry field for the parameter.
  • The value attribute specifies the initial value provided in the entry field. If a value was provided by an option parameter when CTPClient was started, that value takes precedence over the value of the value attribute.

Parameter names starting with @ specify PARAM values in DicomAnonymizer scripts.

Parameter names starting with $ specify values in DicomAnonymizer lookup tables.

The param element has an optional readonly attribute. When set to yes, the entry in the table is not editable.

  • If the name attribute is specified and the value attribute is missing or blank, the text displayed is the value of the specified configuration parameter.
  • If the value attribute is not blank, it takes precedence over any configuration parameter specified by the name attribute.
  • Examples:
    <param
        name="@SITEID"
        label="Site ID:"
        readonly="yes"/>
    <param
        label="Note:"
        value="Some readonly text"
        readonly="yes"/>

5 Building CTPClient

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 source/files directory:

  • config.properties
  • DPA.script
  • DA.script

In special situations, default files for the dialog, DicomFilter and DicomAnonymizer lookup table can be provided. The following are the names required by the application:

  • DIALOG.xml
  • DF.script
  • LUT.properties

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

6 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 CTP/ROOT/CTPClient 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 jnlp file.

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

Note: If multiple CTPClient instances are to be supported in one CTP instance, install them in subdirectories of the ROOT directory, like this:

ROOT
TrialX
CTPClient
TrialY
CTPClient
TrialZ
CTPClient

In this situation, the URL to access a trial's CTPClient would include the trial name in the webstart path (e.g. /webstart/TrialY/CTPClient[?params]).

Retrieved from "http://mircwiki.rsna.org/index.php?title=Configuring_the_CTPClient_Application_for_Clinical_Trials&oldid=8039"