
                                Terradue GeoTIFF Uploader (UNKNOWN_BRANCH@r??????; 2014-03-06 11:34:01+0100)
                                                     ----
                                                   2011-2012

Introduction

  GeoTIFF Uploader is a processor for Geo data that converts them to GeoTIFF format/extracts metadata
  and uploads to Geoserver via REST APIs

========================================================================================================================

Install GTU

  GeoTIFF Uploader is a Java tool, so you must have Java installed in order to proceed. Users need at least the
  Java Runtime Environment (JRE), the Java Development Kit (JDK) is a plus.

  [[1]] Extract the distribution archive, i.e. geotiff-uploader-1.0.0-SNAPSHOT-linux-x86_64.tar.gz to the directory you
        wish to install gtu.
        These instructions assume you chose /usr/local/terradue/geotiff-uploader-1.0.0-SNAPSHOT.
        The subdirectory geotiff-uploader-1.0.0-SNAPSHOT will be created from the archive.

  [[2]] Add GTU binaries to your path, e.g. export PATH=/usr/local/terradue/geotiff-uploader-1.0.0-SNAPSHOT/bin:$PATH.

  [[3]] Make sure that JAVA_HOME is set to the location of your JDK, e.g. export JAVA_HOME=/usr/java/jdk1.5.0_02
        and that $JAVA_HOME/bin is in your PATH environment variable.

========================================================================================================================

Run GeoTIFF Uploader from Shell

  Once installed, type the following in a terminal or in a command prompt:

+--------------------------------------+
$ gtu --version
+--------------------------------------+

  It should print out your installed version of GeoTIFF Uploader, for example:

+--------------------------------------+
$ gtu --version
Terradue GeoTIFF Uploader 0.1-SNAPSHOT (r19004; 2012-04-05 09:23:16+0200)
Java version: 1.6.0_29, vendor: Apple Inc.
Java home: /System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home
Default locale: en_US, platform encoding: MacRoman
OS name: "Mac OS X", version: "10.7.3", arch: "x86_64", family: "mac"
+--------------------------------------+

  You are now able to perform Geo data metadata extraction and GeoTIFF conversions, let's have a look at the available
  options:

+--------------------------------------+
$ gtu --help
helpUsage: gtu [options]  Options:
    -b, --basepath   The REST Geoserver base path.
                     Default: geoserver
    -X, --debug      Produce execution debug output.
                     Default: false
    -d, --domain     The REST Geoserver host domain.
    -f, --file       The file has to be converted and uploaded.
    -h, --help       Display help information.
                     Default: false
    -p, --port       The REST Geoserver host port.
                     Default: 80
    -t, --timeout    The REST request timeout (in seconds).
                     Default: 5
    -u, --user       The REST Geoserver credentials [ use the expression
                     ${username}(:${password}) ].
    -v, --version    Display version information.
                     Default: false
+--------------------------------------+

  So, a typical command to perform a NetCDF conversion would be:

+--------------------------------------+
$ gtu -d xxxx.terradue.com \
      -p 8080 \
      -u admin:xxxx \
      -f ~/Downloads/METOFFICE-GLO-SST-L4-NRT-OBS-SST_2011-04-01_2011-04-02\(2\).nc
+--------------------------------------+

  GTU supports the <<<@>>> syntax, which allows you to put all your options into a file and pass this file as parameter,
  let assume for instance the <<<~/doc/gtu.in>>> file:

+--------------------------------------+
-d
xxxx.terradue.com
-p
8080
-u
admin:xxxx
-f
/Users/geouser/Downloads/METOFFICE-GLO-SST-L4-NRT-OBS-SST_2011-04-01_2011-04-02\(2\).nc
+--------------------------------------+

  GTU can be launched using the following command:

+--------------------------------------+
$ gtu @~/doc/gtu.in
+--------------------------------------+

  The command line will print out various actions, and end with the following:

+--------------------------------------+
[INFO] All data processed.
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] Terradue GeoTIFF Uploader SUCCESS
[INFO] Total time: 206s
[INFO] Finished at: Fri Aug 05 11:12:55 CEST 2011
[INFO] Final Memory: 3M/495M
[INFO] ------------------------------------------------------------------------
+--------------------------------------+

* Logs

  All GeoTIFF conversions will be logged not only in the console, but also under <<<$GTU_HOME/logs>>>; a file rolling
  policy is already implemented, so sysadmins don't have to take care of it.

========================================================================================================================

 Using GeoTIFF Uploader APIs

  GeoTIFF Uploader can be used inside your Java applications, all users have to do is:

  * Obtaining a <<<com.terradue.gtuploader.GeoTIFFUploader>>> instance via its related <<<Builder>>> class:

+--------------------------------------+
import com.terradue.gtuploader.GeoTIFFUploader;

...

GeoTIFFUploader uploader = new GeoTIFFUploader.Builder()
                                              .setRestServerHost( "localhost" )
                                              .setRestServerPort( 8080 )
                                              .setRestBasePath( "geoserver" )
                                              .setRequestTimeout( 10 )
                                              .setRestServerUsername( "admin" )
                                              .setRestServerPassword( "admin" )
                                              .newGeoTIFFUploader();
+--------------------------------------+

  * Upload geo data in a <GDAL> supported format:

+--------------------------------------+
try
{
    uploader.convertAndUpload( new File("~/Downloads/METOFFICE-GLO-SST-L4-NRT-OBS-SST_2011-04-01_2011-04-02\(2\).nc") );
}
catch ( GeoTIFFUploadException e )
{
    // handle exception
}
+--------------------------------------+

 * WARNING

  The <GDAL> Java binding is not thread safe so GTU is not as well, make sure clients don't invoke the
  <<<com.terradue.gtuploader.GeoTIFFUploader#uploader.convertAndUpload(java.io.File)>>> method concurrently!
