Remote Processing User Guide
Sections:




Overview
Installation Guide: Description of which items should be manually configured for
remote processing to be done.
User Guide: Description of how to properly use the capabilities available for
remote processing.
Tips and Tricks for Remote error checking/debugging
Overview
This documentation should be supplemented with the PIMA User Guide or the PIMA User Quick
Start Guide, since this document shall only go over remote processing and the requirements,
limitations, and capabilities of both the server and client-side installations.
The remote functionality is made available through hosting a server-side distribution of PIMA
which must be started up to facilitate client-server communication. This server-side installation
will be responsible for running the algorithms and will be where the algorithms should be
installed, as well as where algorithm results will be generated.
The client-side is capable of connecting to multiple PIMA servers and the server’s namespace
will be displayed within the PIMA Tools drop-down menu. The corresponding algorithms for
each server will appear when hovering over the server you wish to run on. The client-side
facilitates data synchronization through the available DataSync web service. There is currently
a simple version of this data synchronization; users are strongly encouraged to create their own
data synchronization web service when additional needs are required for the data inputs used.
The client installation of PIMA allows multiple convenience options to pull down generated
results from a server and compress results available for faster downloading.
Remote Processing User Guide
10 MAY 2013
Installation Guide
The following sections describe how to install PIMA for remote capabilities.
Windows Installation
Server Installation Process
The latest PIMA distribution containing PIR2 updates enabling remote client/server
capabilities can be found at http://pima-tools.integrity-apps.com/ in the
pima_dist_3_0_0_win.zip file. Once extracted, the user runs the setup.bat file to being the
installation. Either the PIMA client or the PIMA server can be installed via setup.bat. NOTE:
It is highly recommended to NOT install BOTH the client and server applications on a single
computer.
Apache Tomcat 6.x or higher and Apache Axis2 1.6.2 or higher are prerequisites for the
installation of the PIMA server. If needed, links to the Tomcat packages and the axis2.war
file are available at http://pima-tools.integrity-apps.com/. To install the server:
1. Install Apache Tomcat 6.x or greater, if needed and start Tomcat.
2. Copy the axis2.war file to the %CATALINA_HOME%\webapps directory to deploy the
axis2 servlet, if needed.
3. Begin the server installation by running setup.bat from the PIMA distribution. Select
“Install PIMA server” and press “Next >” (see Figure 1).
Figure 1: First PIMA Setup Screen
The PIMA installer will attempt to fill in the fields for the PIMA home directory, the
location of the webapps Axis2 services directory under Tomcat, the host IP and the
Tomcat port. Ensure that these values are valid for the installation or modify as
appropriate (see Figure 2).
2
Remote Processing User Guide
10 MAY 2013
Figure 2: PIMA Server Installation inputs
Select “Next >” and review your selections on the ensuing panel. If satisfied, select
“Install”.
Figure 3: PIMA Server Installation
The installation process will create and populate all the required PIMA directories
and subdirectories under the PIMA installation folder. It will modify the
%CATALINA_HOME%\conf\web.xml and %CATALINA_HOME%\conf\server.xml
files to support PIMA processing via the PIMA server. It will also copy required
archives (PIMAWebService.aar and PIMADataSync.aar) to
%CATALINA_HOME%\webapps\axis2\WEB-INF\services and logging properties
files (pimaWebServiceLog4j.properties and pimaDataSyncLog4j.properties) to
%CATALINA_HOME%\webapps\axis2\WEB-INF\classes directories respectively.
3
Remote Processing User Guide
10 MAY 2013
After installation, the %CATALINA_HOME% directory structure should look like the
following. Highlighted values are those added by the PIMA installation process.
%CATALINA_HOME%
|---bin
|---conf
|---lib
|---logs
|---temp
|---webapps
|
|---axis2
|
|
|---axis2-web
|
|
|---META-INF
|
|
|---WEB-INF
|
|
|---classes
|
|
|
|---pimaDataSyncLog4j.properties
|
|
|
|---pimaWebServiceLog4j.properties
|
|
|
|---etc…
|
|
|---conf
|
|
|---lib
|
|
|---modules
|
|
|---services
|
|
|---PIMADataSync.aar
|
|
|---PIMAWebServices.aar
|
|
|---etc…
|
|---docs
|
|---examples
|
|---host-manager
|
|---logs
|
|
|---pimawebservice.log
|
|---manager
|
|---ROOT
|---work
4. Increase Tomcat’s maximum Java heap size and set the PIMA_HOME environment
variable. Create a script/batch file where the JAVA_OPTS environment variable is set to
at least 1 MB. JAVA_OPTS is an accessible, pre-defined environment variable used by
Tomcat. Also, set the PIMA_HOME environment variable to the PIMA installation folder.
This will be the value under “PIMA installation folder” as seen in Figure 3. Then from that
same script/batch file call %CATALINA_HOME%\bin\start.bat. For example, the batch
file, start_PIMA_server.bat, could look something like this:
…
set JAVA_OPTS=-Xmx1024m
set CATALINA_HOME=<Tomcat top level directory>
set PIMA_HOME=C:\usr\PIMA
…
%CATALINA_HOME%\bin\start.bat
5. With the environment variables from step 4 set, (re)start the PIMA/Tomcat server.
Requests to the PIMA server will be logged in
%CATALINA_HOME%\webapps\logs\pimawebservice.log. Log levels can be adjusted to
need by modifying:
%CATALINA_HOME%\webapps\WEBINF\classes\pimaWebServiceLog4j.properties
Once the server is running, check to ensure it is functioning properly. Assuming Tomcat
is attached to port 8080, issue the following request from a browser:
4
Remote Processing User Guide
10 MAY 2013
http://localhost:8080/axis2/services/PIMAWebService/listAlgorithms?in=x
Results should look something like those in Figure 4.
Figure 4: Sample Browser Output from PIMA Web Service listAlgorithms Request
6. NOTE: The DataSync.aar is a simple web service that performs data matching between
SICDs and SIDD imagery for client-server data matching. This web service needs a
refKey.txt file at %PIMA_HOME%/data which includes any mapped data files. This
means for each data file that should be run remotely an associated unique ID (which is
the NITF image ID) and a corresponding location should be entered into the refKey.txt
file. We recommend that PiR2 users implement their own databases and create their
own archives for a more robust data matching process. Developers should look to the
Interface Control Document (ICD) for PIR2 and the Software Design Document (SDD)
for additional information on how the DataSync WSDL is defined in order to build a
compliant archive for data matching.
An example refKey.txt:
RS2_20080502_062226730722=X:\jsmith\DetectedForSDA\02MAY08RS0204001_062227_SM0761R_36N006W_001C___DHH_0201_LMC_SICD.
nitf
RS2_20080506_041805949716=X:\jsmith\DetectedForSDA\06MAY08RS0203001_041806_SM0798R_60N030E_001C___QHH_0401_LMC_SICD.
nitf
RS2_20080410_181907469736=X:\jsmith\DetectedForSDA\10APR08RS0211001_181907_SM0763R_36N006W_001C___DHH_0201_LMC_SICD.
nitf
RS2_20080514_182727346445=X:\jsmith\DetectedForSDA\14MAY08RS0211001_182727_SM0759R_36N006W_001C___DHH_0201_LMC_SICD.
nitf
RS2_20080415_061816230661=X:\jsmith\DetectedForSDA\15APR08RS0204001_061816_SM0759R_36N006W_001C___DHH_0201_LMC_SICD.
nitf
5
Remote Processing User Guide
10 MAY 2013
Client Installation Process
1. Install Java for a 64 bit machine
2. Install the latest PIMA distribution which can be found on the website at: http://pimatools.integrity-apps.com/
a. The latest distribution should ask if the installation process is for a server or a
client and be sure to specify “Client” when installing.
3. Then navigate to the scripts directory and start an ELT specific bat file in order to use the
application.
Note: Further documentation can be found from the PIMA website on how to use PIMA
with PIR2 capabilities.
Linux Installation
Server Installation Process
The latest PIMA distribution containing PIR2 updates enabling remote client/server
capabilities can be found at http://pima-tools.integrity-apps.com/ in the
pima_dist_3_0_0_win.zip file. Once extracted, the user runs the setup.bat file to being the
installation. Either the PIMA client or the PIMA server can be installed via setup.bat. NOTE:
It is highly recommended to NOT install BOTH the client and server applications on a single
computer.
Apache Tomcat 6.x or higher and Apache Axis2 1.6.2 or higher are prerequisites for the
installation of the PIMA server. If needed, links to the Tomcat packages and the axis2.war
file are available at http://pima-tools.integrity-apps.com/. To install the server:
1. Install Apache Tomcat 6.x or greater, if needed and start Tomcat.
2. Copy the axis2.war file to the $CATALINA_HOME/webapps directory to deploy the axis2
servlet, if needed.
3. Begin the server installation by running setup.bat from the PIMA distribution. Select
“Install PIMA server” and press “Next >”.
Client Installation Process
4. Install Java for a 64 bit machine
5. Install the latest PIMA distribution which can be found on the website at: http://pimatools.integrity-apps.com/
a. The latest distribution should ask if the installation process is for a server or a
client and be sure to specify “Client” when installing.
6. Then navigate to the scripts directory and start an ELT specific bat file in order to use the
application.
Note: Further documentation can be found from the PIMA website on how to use PIMA
with PIR2 capabilities.
6
Remote Processing User Guide
10 MAY 2013
User Guide
Starting a remote algorithm
The user must take the following steps to run algorithms on remote servers:
1. A PIMA server needs to be accessible to the local PIMA client. See instructions above for
installing a PIMA server and the “Algorithm Installation Guide” for more information on
installing algorithms.
2. To make a server (and all of its algorithms) available an entry should be added to the
properties file located at
%PIMA_HOME%/config/epr.properties
Where %PIMA_HOME% is the PIMA install location. Entries consist of an endpoint reference
and a unique identifier. E.g., consider the following entry:
http://192.168.1.1:8080/axis2/services/PIMAWebService PIMA Remote Server
This entry indicates that the server’s IP is 192.168.1.1, the port being used is 8080, the
server’s unique identifier is “PIMA Remote Server”.
3. Once the %PIMA_HOME%/config/epr.properties file has been modified to point to a valid
PIMA server, the PIMA client can be started in the normal fashion (see PIMA Users Guide).
Upon start-up, the PIMA client will check the epr.properties file for server entries. If it
detects one or more entries, it will immediately attempt to connect to the listed entry(s). If the
attempt to connect to the server fails, on error dialog will appear similar to that in Figure 5.
Only error conditions are reported on failed connection attempts. If no error dialogs appear,
the user can assume that the client has successfully connected to the server(s).
Figure 5: Error Dialog – Cannot Connect to PIMA Server
4. After starting PiR2 (PIMA), choose the remote algorithm to run by browsing to
Tools  MyServer  GroupName  AlgorithmName
7
Remote Processing User Guide
10 MAY 2013
Where AlgorithmName is the name of the algorithm that the user wishes to run and
MyServer is the unique identifier of the server on which AlgorithmName was installed. The
GroupName is the associated company or grouping for this algorithm (e.g. NRL, Demo).
Once the user has selected a remote algorithm, the process to run that algorithm is identical
to running a local algorithm (see PIMA Users Guide). Once the remote algorithm has run to
successful completion, the user will be presented with a series of windows with options to
download the products generated by the remote algorithm.
Figure 6: Remote Algorithm Drop-Down Menu
NOTE: If your server does not appear in the Tools menu or your algorithm does not appear
under “Tools -> MyServer”, go to Setup -> Pima Update and then retry. If the server menu
item and the category (e.g., Demo, NRL) are present but the algorithm is not, the algorithm
may not be PiR2-compliant. See PIMA’s Algorithm Installation Guide regarding how to make
an algorithm fully compliant.
Accessing Remote Results
Transfer Dialog
When an algorithm has completed and there are results available, they can either be
downloaded to a location accessible by the client or uploaded to an IPL. The Transfer Dialog
features thumbnail previews of products and remote compression prior to transferring, and
supports the inclusion of the input data in the transfer. The Transfer Dialog is accessed by
clicking the “Results…” button on the main PIMA GUI (Figure 3).
8
Remote Processing User Guide
10 MAY 2013
Figure 7: Example Status Panel with Available Results
Downloading
In order to download algorithm results, the user must select the “Download” option in the File
Transfer Options step of the Transfer Dialog. Then the user must choose a download directory.
By default the download directory is the one created by PIMA, which exists at
%PIMA_HOME%/data/remote/JOBNAME. For example, if the algorithm being run was “Crop”
and this run marked the 1st time it had been run on the server, then the download directory
would be %PIMA_HOME%/data/remote/Crop_000.
Figure 8: File Transfer Options Dialog
9
Remote Processing User Guide
10 MAY 2013
Uploading
In order to upload algorithm results to IPL, the “Upload” option must be selected. The user must
then enter the output directory, host (IP address), port, username and password for the IPL
account they have set up.
Product Thumbnails
The user can preview remote algorithm results prior to downloading or uploading them by
clicking on the binocular icon (Figure 5). This icon only appears for results which are displayable
(e.g., PNG, JPG, NITF). A thumbnail is then generated and displayed to gain more
understanding of the results available.
Figure 9: Thumbnail Button Icon
Figure 10: Remote Result with Thumbnail Available
Remote Compression
The user has the option to compress their results when their algorithm has finished.
Compression may not be necessary if client network connectivity is good or if the algorithm
products are small. Otherwise the user can request that the results be compressed. When at
least one result is selected, the option to compress is made available. If the user selects
“compress” then the option to include raw data inputs is also made available. Inputs will always
be compressed. The compression done is virtually lossless but small changes can be seen
from the uncompressed versus compressed result files. Compression can only be done on a 64
bit machine.
Figure 11: Selected Results Panel
10
Remote Processing User Guide
10 MAY 2013
If the user selects “compress” then the option to include raw data inputs is also made available.
Inputs will always be compressed.
Figure 12: Compressed Selected Results
Tips and Tricks for Remote Error Checking/Debugging
Unable to Access Remote Plugins:
If the user is trying to access remote plugins and is unable to see any of the server’s configured
through the epr.properties or the associated plugins, users can look at the pima.properties file
located at %PIMA_HOME%/config/pima.properties and determine if the property
pima.remote.plugins is false or true this flag determines whether or not the PIMA installation
should be able to connect with remote plugins that are available. On initial installation, a radio
button determines this setting but if you would like to have your installation not able to access
remote plugins or start accessing remote plugins where it wasn’t previously you can alter this
flag manually.
11