[[PageOutline]]

= Clients =

It is important for data users to get convenient access to rasdaman functionality, for manifold reasons: users want to stay in their well-known environments (such as QGIS, ESRI, or R); users have additional functionality in their tools which they want to apply on data retrieved from rasdaman; users do not want to learn yet another data language.
To this end, a large and increasing number of tools can access rasdaman today, thereby enabling these with flexible, scalable server-side processing of n-D "Big Array Data".
They largely fall into two categories, rasdaman-provided and "external" third-party tools. Below they are listed and explained.

rasdaman can interface with a large and increasing number of tools. Some clients allow direct query submission, such as rasql and directql. For rapid development of browser clients the raswct toolkit is provided.

Geo tools supported include !OpenLayers, QGIS, ncWMS, THREDDS, GDAL, !MapServer, !ArcGIS; soon: !GeoServer.
Geo standards supported are OGC WMS, WCS, WCPS, and WPS; hence, all clients conforming to these standards can additionally be used for interfacing. All geo semantics is implemented through the petascope component ([http://rasdaman.org/browser/applications/petascope source]) which is implemented as a Java application layer offering OGC Web services.


== Clients coming with rasdaman ==

=== Rasql query language access ===

The following clients allow to submit rasql queries:
* `rasql` is a command-line utility for sending queries and saving results in local files. Invocation example (see `rasql --help` for details):
{{{
rasql -q 'select encode( mr, "png" ) from mr' --out file
}}}
 * To see a list of all collections with arrays in the database:
{{{
rasql -q 'select c from RAS_COLLECTIONNAMES as c' --out string
}}}
* '''rasql queries''' can also be invoked via a Web service by default listening at `localhost:8080/rasdaman/rasql`. To this end, the corresponding servlet needs to be started (see [browser:manuals_and_examples/manuals/doc-guides/inst-guide.pdf Installation Guide]).
 * Syntax: 
{{{
http://{service}/{path}/rasdaman/rasql?params

Example: 
http://www.acme.com/rasdaman?query=select%20rgb.red+rgb.green%20from%20rgb&username=rasguest&password=rasguest
}}}
 * This servlet endpoint accepts KVP requests with the following parameters:
   * ''query=q'' where q is a valid rasql query, appropriately escaped as per http pecification.
   * ''username=u'' where u is the user name for logging into rasdaman (current: ''rasguest'' for retrieval query (select) and ''rasadmin'' for the editable query (insert, update, delete,...).
   * ''password=p'' where p is the password for logging into rasdaman (current: ''rasguest'' for username: ''rasguest'' and ''rasadmin'' for username: ''rasadmin'').
 * To upload data to server, it is needed to attach the data in HTTP message's body and send the POST request to the Servlet endpoint with user have the write permission (e.g: rasadmin). In Linux, one tool can support this feature is cURL.  Syntax: 
{{{
curl -F 'image=@{/Path_To_Image}' '{http://Rasql_Servlet_Endpoint?username=rasadmin&password=rasadmin&query={insert/update query}'
}}}
   * Here is an example:
{{{
Collection: test_mr_test1

Insert file to collection:
curl -F 'image=@/home/rasdaman/rasdaman/systemtest/testcases_services/test_all_wcst_import/test_data/wcps_mr/mr_1.png' 'http://localhost:8080/rasdaman/rasql?username=rasadmin&password=rasadmin&query=insert%20into%20test_mr_test1%20values%20decode(%241)' 

Update file to collection:
curl -F 'image=@/home/rasdaman/rasdaman/systemtest/testcases_services/test_all_wcst_import/test_data/wcps_mr/mr_1.png' 'http://localhost:8080/rasdaman/rasql?username=rasadmin&password=rasadmin&query=update%20test_mr_test1%20set%20test_mr_test1%20assign%20decode(%241)'

}}}

* `directql` is not strictly a client, but a rasdaman server linked directly with the rasql utility (see above). Main purpose is for simplified debugging of the server by allowing command-line invocation of the server engine. ([http://rasdaman.org/browser/applications/directql source] )
* `rview` is a deprecated visual query interface for desktop use (executable). It is still part of the rasdaman package, but not maintained any longer and will soon be phased out. See [wiki:Clients#rviewdeprecated below].

=== python ===

* There is a [https://pypi.python.org/pypi/rasdapy RasdaPy Python package] that allows to connect to rasdaman, send queries and get back results as Python or numpy array.
* An OWSLib fork provides support for WCPS; this [https://github.com/earthserver-eu/geospatial-workflow-with-wcps tutorial] provides examples.

=== Geo clients ===

* '''WCS Web client''': a generic Web client which allows for convenient forms-based input of WCS parameters for WCS Core and Extensions; all WCS extensions are supported, but the client presents only those extensions which are supported by the server addressed. Results can be displayed graphically where feasible. ([http://rasdaman.org/browser/applications/wcs-client source] )
* '''mobile clients''' (contributed by [http://www.consorzio-cometa.it/ COMETA]):
 * native Android app: 
   * Google Play: https://play.google.com/store/apps/details?id=it.infn.ct.earthserverSGmobile
   * source: http://sourceforge.net/p/ctsciencegtwys/mobile/14/tree/trunk/Android/EarthServerSGMobile/
   * To check out the source code:
{{{
svn checkout  svn://svn.code.sf.net/p/ctsciencegtwys/mobile/trunk/Android/EarthServerSGMobile EarthServerSGMobile
}}}
 * Appcelerator Titanium app built for iOS: 
  * App Store: https://itunes.apple.com/us/app/earthserver-sg-mobile/id740603213?ls=1&mt=8
  * source: http://sourceforge.net/p/ctsciencegtwys/mobile/15/tree/trunk/iOS/EarthServer-SG-Mobile/
  * To check out src code:
{{{
svn checkout  svn://svn.code.sf.net/p/ctsciencegtwys/mobile/trunk/iOS/EarthServer-SG-Mobile EarthServer-SG-Mobile
}}}

=== raswct (rasdaman Web Client Toolkit) ===

This JavaScript library allows, by way of input and output widgets, to easily compose a Web client. Simple versions need only HTML, but advanced interfaces can be created. One example for the use of raswct is [http://standards.rasdaman.org standards.rasdaman.org]. See [wiki:raswct/guide documentation] for details.

== Third-party clients ==

=== R (data analysis) ===

'''RRasdaman''' is an R package providing a database interface for rasdaman, i.e.: for submitting rasdaman queries from within R. It is submitted to R and part of this toolset.
See [wiki:RRasdaman installation/setup guide] and [wiki:RRasdamanTutorial tutorial] for more information.

=== NASA !WorldWind (Web-based virtual globe) ===

documentation tbd

=== !OpenLayers and Leaflet (Web-based map navigation) ===

documentation tbd

=== ncWMS (Web-based climate data navigation) ===

documentation tbd

=== QGIS (Web GIS) ===

This plugin enables the direct download, processing, integration and usage of Coverages from an OGC compliant WCPS 1.0 enabled servers within the QGIS software (v2.0+ supported). The plugin has been submitted to the official QGIS plugin repository, approval is pending; in the meantime it can be installed manually:

- get the rasdaman source tree:
{{{
git clone git://rasdaman.org/rasdaman.git
}}}
- the plugin can be found in directory `rasdaman/applications/qgis-wcps`
- copy the `qgis-wcps/QgsWcpsClient1` directory to your `qgis-python-plugin directory`, usually located in `$HOME/.qgis2/python/plugins`: 
{{{
mkdir -p $HOME/.qgis2/python/plugins/
cp -r rasdaman/applications/qgis-wcps/QgsWcpsClient1 $HOME/.qgis2/python/plugins/
}}}
- now you can start QGIS and access the `QgsWcpsClient1` plug-in via the `Qgis Menu → Plugins → WcpsClient1 → WCPS 1.0 Client`

=== !MapServer (Web GIS server) ===

documentation tbd

=== !GeoServer (Web GIS server) ===

documentation tbd

=== GDAL (image processing library) ===

To compile GDAL with rasdaman support:
 1. Get latest GDAL source
 2. Compile and install (in the /home/rasdaman/gdal)
{{{
#!sh
./configure --prefix=/home/rasdaman/gdal --mandir=/home/rasdaman/gdal/share/man --includedir=/home/rasdaman/gdal/include/gdal 
  --with-threads --with-grass=no --with-hide-internal-symbols=yes --with-libtiff=internal --with-geotiff=internal --with-jasper 
  --with-netcdf --with-xerces --with-geos --with-sqlite3 --with-curl --with-pg --with-ogdi --with-python --with-odbc 
  --with-static-proj4=yes --with-spatialite=/usr --with-cfitsio=no --with-epsilon=/usr --with-rasdaman=/home/rasdaman/install
make
make install
}}}
  * '''Note:''' rasdaman should be compiled with `-fPIC`, so make sure to specify `--with-pic` when running `./configure` on rasdaman.
 3. Setup environment
{{{
#!sh
export GDAL_HOME=/home/rasdaman/gdal
export PATH=$PATH:$GDAL_HOME/bin
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$GDAL_HOME/lib
}}}

=== THREDDS (scientific data cataolog) ===

documentation tbd


=== ESRI ArcGIS (GIS tool) ===

documentation tbd