[[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 submitted via a '''Web service''', by default listening at `localhost:8080/rasdaman/rasql`. To this end, the corresponding servlet needs to be started (see the [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), rather than following the client/server architecture. Main purpose is simplified debugging of the server by allowing command-line invocation of the server engine. See ([http://rasdaman.org/browser/applications/directql source]).

=== python ===

* The [https://pypi.python.org/pypi/rasdapy rasdapy Python package] (see [http://rasdaman.org/browser/applications/rasdapy rasdapy in rasdaman code base]) allows to connect to rasdaman, send queries, and get back results as python or numpy array. See the [http://tutorial.rasdaman.org/rasdapy-tutorial/ rasdapy tutorial]; a [http://tutorial.rasdaman.org/rasdapy-tutorial/rasdapy.ipynb Jupyter Notebook] can be run on your local system (have a working rasdaman, rasdapy, and Jupyter Notebook). Github hosts [https://jupyter.eofrom.space/hub/home more Jupyter examples].

* An OWSLib fork provides support for WCPS; this [https://github.com/earthserver-eu/geospatial-workflow-with-wcps tutorial] and this [https://github.com/earthserver-eu/EGU_short_course short-course] provide examples.

=== 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.


=== Geo clients ===

* '''WS Web client''': ([http://rasdaman.org/browser/applications/wcs-client source] ) 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. A coverage can be showed its footprint on WebWorldWind globe in `WS Web Client` when it is imported as `2D+ geo-referenced coverage`.

* '''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
}}}


== 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 CRAN.
See [wiki:RRasdaman installation/setup guide] and [wiki:RRasdamanTutorial tutorial] for more information.

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

NASA !WebWorldWind is a highly flexible open-source virtual globe toolkit, programmed in !JavaScript, running in Web browsers. It can be configured to display rasdaman results via OGC WCPS queries.  

For coding instructions, two sources are available: The built-in geo client of rasdaman makes use of !WebWorldWind; further, an example using a WCPS query to display a time series of average chlorophyll concentration is available at [http://earthlook.eecs.jacobs-university.de/demo/application-domain/oceanography.php# Earthlook]. See more about [https://worldwind.arc.nasa.gov/web/examples/ WebWorldWind tutorials].

'''NOTE:''' WebWorldWind with WMS GetMap request does not divide to smaller bounding boxes at very close zoom distance (e.g: 1km above ground). Hence, layers with very high resolution cannot be shown in detail as original input files.

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

Via WMS 1.3, !OpenLayers and Leaflet can connect directly to a rasdaman WMS endpoint.

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

documentation tbd

=== QGIS WCPS plugin ===

QGIS can directly download, process, integrate, and use coverages from rasdaman via plugins [​https://plugins.qgis.org/plugins/QgsWcsClient2/ for WCS] and for [​https://plugins.qgis.org/plugins/QgsWcpsClient1/ WCPS] being part of the official QGIS plugin repository. Alternatively, the source code of the WCPS plugin is [browser:applications/qgis-wcps available from rasdaman]. 

Check these [https://standards.rasdaman.com/demo_qgis.html step-by-step plugin installation instructions]. In a nutshell:

- select QGIS menu `Plugins` → `Manage and Install Plugins` → Search: `wcps` (it returns the plugin `QgsWcpsClient1`) → click `install`
- now you can access the `QgsWcpsClient1` plug-in via the `Qgis Menu → Plugins → WcpsClient1 → WCPS 1.0 Client`
- select `Help` tab from the `QgsWcpsClient1` plug-in window for information about how to connect to a WCPS endpoint.

Another QGIS plugin is [https://github.com/EOX-A/QgsWcsClient2 available on github]. Installing it under Ubuntu is no problem, under Windows there might be an issue with the `lxml` module used by the plugin; if this occurs follow [https://github.com/EOX-A/QgsWcsClient2/issues/8 these instructions].

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

documentation tbd

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

documentation tbd

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

Rasdaman uses GDAL underneath to encode/decode raster data. The library can be installed manually if [http://rasdaman.org/wiki/InstallFromSource#Packagesrequired install from source] or automatically if install rasdaman via [http://doc.rasdaman.org/02_inst-guide.html#build-from-source-guided installer]. 


=== THREDDS (scientific data catalog) ===

documentation tbd


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

Starting version 10.3, ESRI ArcGIS supports WCS 2. Hence, access from ArcGIS to rasdaman via WCS 2 is expected to be possible (in lack of an ArcGIS license we cannot verify).