Back to <a Tutorials index</a><hr><br>
<h1>Tutorial: building and testing the Planet Earth sample</h1>
In this first tutorial we'll use the following input datasources: please download all them right now. They are <u><i>Open released under a free license, and are available absolutely for free.
<ul>
<li><a Marble 2km</a>: a worldwide synthetic collage of many Landsat scenes.</li>
<li><a Earth I</a>: a worldwide land cover presented with a light, natural palette and supporting Shaded Relief, Water and Drainages.</li>
<li><a ETOPO1</a>: a pre-rendered Global Relief Model released from NOAA.</li>
</ul>
<h3>Step 1.a) creating the TrueMarble Coverage</h3>
<verbatim>
$ rl2tool CREATE -db earth.sqlite -cov TrueMarble -smp UINT8 \
-pxl RGB -cpr JPEG -srid 4326 -res 0.0166666666666667

rl2_tool: request is CREATE
===========================================================
              DB path: earth.sqlite
             Coverage: TrueMarble
          Sample Type: UINT8
           Pixel Type: RGB
      Number of Bands: 3
          Compression: JPEG (lossy)
  Compression Quality: 80
   Tile size (pixels): 512 x 512
                 Srid: 4326
Pixel base resolution: X=0.0166666666666667 Y=0.0166666666666667
===========================================================

     SQLite version:
 SpatiaLite version: 4.2.0-devel
RasterLite2 version: 0.8

Raster Coverage "TrueMarble" successfully created

Operation CREATE successfully completed
$
</verbatim>
<ul>
<li>we'll invoke from the command shell the this CLI tool is specifically intended to administer RasterLite2 datasources.</li>
<li>in this case we'll pass the following arguments (explained one by one):
<ul>
<li><b>CREATE</b> this main keyword intends that we are trying to create a new, empty Coverage.</li>
<li><b>-db earth.sqlite</b> this specifies the target DB-file pathname; in this first example the DB-file doesn't yet exists, so it will be implicitly created at once.</li>
<li><b>-cov TrueMarble</b> this specifies the individual Coverage's name.</li>
<li><b>-smp UINT8</b> this specifies the Coverage's Sample Type.</li>
<li><b>-pxl RGB</b> this specifies the Coverage's Pixel Type.</li>
<li><b>-cpr JPEG</b> this specifies that all Tiles in this Coverage must be JPEG compressed.</li>
<li><b>-srid 4326</b> this specifies the Coverage's SRID.</li>
<li><b>-res 0.0166666666666667</b> this specifies the Coverage's base level resolution.</li>

<li><b>rl2tool</b> reports a full success, so we'll now duly pass to the next step.</li>
</ul>
<h3>Step 1.b) populating the TrueMarble Coverage</h3>
<verbatim>
$ rl2tool IMPORT -db earth.sqlite -cov TrueMarble \
-src TrueMarble.2km.21600x10800.tif -pyr

rl2_tool; request is IMPORT
===========================================================
              DB path: earth.sqlite
    Input Source path: TrueMarble.2km.21600x10800.tif
             Coverage: TrueMarble
              Section: from file name
Immediately building Pyramid Levels
===========================================================

     SQLite version:
 SpatiaLite version: 4.2.0-devel
RasterLite2 version: 0.8

Importing: TrueMarble.2km.21600x10800.tif
------------------
    Image Size (pixels): 21600 x 10800
                   SRID: 4326
       LowerLeft Corner: X=-180.00 Y=-90.00
      UpperRight Corner: X=180.00 Y=90.00
       Pixel resolution: X=0.01666666666666666 Y=0.01666666666666666
  ----------
    Pyramid levels successfully built for: TrueMarble.2km.21600x10800

Operation IMPORT successfully completed
$
</verbatim>
<ul>
<li>same as above; we'll invoke yet another time
<li>in this case we'll pass the following arguments (explained one by one):
<ul>
<li><b>IMPORT</b> this main keyword intends that we are trying to populate an already created Coverage by importing from an external datasource.</li>
<li><b>-db</b> and <b>-cov</b>: same as above.</li>
<li><b>-src TrueMarble.2km.21600x10800.tif</b> this specifies the pathname of the external datasource to be imported.</li>
<li><b>-pyr</b> this specifies that we do actually intend to immediately build any possible Pyramid Level.</li>

</ul>
<h3>Step 2.a) creating the NaturalEarth Coverage</h3>
<verbatim>
$ rl2tool CREATE -db earth.sqlite -cov NaturalEarth -smp UINT8 \
-pxl RGB -cpr JPEG -srid 4326 -res 0.0166666666666667

rl2_tool: request is CREATE
===========================================================
              DB path: earth.sqlite
             Coverage: NaturalEarth
          Sample Type: UINT8
           Pixel Type: RGB
      Number of Bands: 3
          Compression: JPEG (lossy)
  Compression Quality: 80
   Tile size (pixels): 512 x 512
                 Srid: 4326
Pixel base resolution: X=0.0166666666666667 Y=0.0166666666666667
===========================================================

     SQLite version:
 SpatiaLite version: 4.2.0-devel
RasterLite2 version: 0.8

Raster Coverage "NaturalEarth" successfully created

Operation CREATE successfully completed
$
</verbatim>
Not really different from step <b>1.a)</b>: we are simply creating yet another RasterLite2 Coverage within the same DB-file.
<h3>Step 2.b) populating the NaturalEarth Coverage</h3>
<verbatim>
$ rl2tool IMPORT -db earth.sqlite -cov NaturalEarth \
-src NE1_HR_LC_SR_W_DR.tif -pyr

rl2_tool; request is IMPORT
===========================================================
              DB path: earth.sqlite
    Input Source path: NE1_HR_LC_SR_W_DR.tif
             Coverage: NaturalEarth
              Section: from file name
Immediately building Pyramid Levels
===========================================================

     SQLite version:
 SpatiaLite version: 4.2.0-devel
RasterLite2 version: 0.8

Importing: NE1_HR_LC_SR_W_DR.tif
------------------
    Image Size (pixels): 21600 x 10800
                   SRID: 4326
       LowerLeft Corner: X=-180.00 Y=-90.00
      UpperRight Corner: X=180.00 Y=90.00
       Pixel resolution: X=0.01666666666667 Y=0.01666666666667
  ----------
    Pyramid levels successfully built for: NE1_HR_LC_SR_W_DR

Operation IMPORT successfully completed
$
</verbatim>
Exactly the same as in step <b>1.b)</b>
<h3>Step 3.a) creating the Etopo1 Coverage</h3>
<verbatim>
$ rl2tool CREATE -db earth.sqlite -cov Etopo1 -smp UINT8 \
-pxl RGB -cpr JPEG -srid 4326 -res 0.0166666666666667

rl2_tool: request is CREATE
===========================================================
              DB path: earth.sqlite
             Coverage: Etopo1
          Sample Type: UINT8
           Pixel Type: RGB
      Number of Bands: 3
          Compression: JPEG (lossy)
  Compression Quality: 80
   Tile size (pixels): 512 x 512
                 Srid: 4326
Pixel base resolution: X=0.0166666666666667 Y=0.0166666666666667
===========================================================

     SQLite version:
 SpatiaLite version: 4.2.0-devel
RasterLite2 version: 0.8

Raster Coverage "Etopo1" successfully created

Operation CREATE successfully completed
$
</verbatim>
Same as in steps <b>1.a)</b> and <b>2.a)</b>
<h3>Step 3.b) populating the Etopo1 Coverage</h3>
<verbatim>
$ rl2tool IMPORT -db earth.sqlite -cov Etopo1 \
-src color_etopo1_ice_full.tif -pyr

rl2_tool; request is IMPORT
===========================================================
              DB path: earth.sqlite
    Input Source path: color_etopo1_ice_full.tif
             Coverage: Etopo1
              Section: from file name
Immediately building Pyramid Levels
===========================================================

     SQLite version:
 SpatiaLite version: 4.2.0-devel
RasterLite2 version: 0.8

Importing: color_etopo1_ice_full.tif
------------------
    Image Size (pixels): 21600 x 10800
                   SRID: 4326
       LowerLeft Corner: X=-180.01 Y=-89.99
      UpperRight Corner: X=179.99 Y=90.01
       Pixel resolution: X=0.01666666666667 Y=0.01666666666667
  ----------
    Pyramid levels successfully built for: color_etopo1_ice_full

Operation IMPORT successfully completed
$
</verbatim>
Same as in steps <b>1.b)</b> and <b>2.b)</b>
<h3>Step 4) a final artistic touch</h3>
You can now directly check the DB-file using e.g. <b>spatialite_gui</b>; please focus your attention on the <b>raster_coverages</b> table.<br>
This one is a specifically intended to support Raster Coverages, and is the exact equivalent of what <b>geometry_columns</b> is intended to be for Vector Layers.<br><br>
<img alt="raster_coverages #1"><br><br>
As you can easily check, all three Coverages are now nicely registered within the <b>raster_coverages</b> table. Anyway, both the <b>title</b> and <b>abstract</b> columns simply report some unpleasant and meaningless default value.<br><br>
<img alt="raster_coverages #2"><br><br>
You are now simply expected to execute just few UPDATE SQL statements, and finally you'll have all your Coverages supported by appropriate and meaningful <b>title</b> and <b>abstract</b> columns, as shown in this figure.
<h3>Step 5) starting the light-weight WMS server</h3>
RasterLite2 includes a light-weight but almost complete WMS 1.3.0 server. It's a basically simple, zero-admin and absolutely complexity-free component.
<verbatim>
$ wmslite -db earth.sqlite

======================================================
              WmsLite server startup
======================================================
         SQLite version:
     SpatiaLite version: 4.2.0-devel
    RasterLite2 version: 0.8
======================================================
Publishing layer "truemarble"
Publishing layer "naturalearth"
Publishing layer "etopo1"
======================================================
    HTTP micro-server listening on port: 8080
======================================================
</verbatim>
Just execute from the command shell by specifying the pathname of the DB-file you intend to publish, and that's all.<br>
As you can easily check, now the WMS server is listening on <b><i>localhost port and is immediately ready to accept and process standard WMS requests.
<h3>Step 6) directly testing your RasterLite2 Coverages via WMS</h3>
In this first example we'll use the GUI tool directly accompanying RasterLite2 and completely based on the WMS client internally implemented by
<img alt="wms connect #1"><br><br>
You simply have to establish a WMS connection to <b>localhost</b> (aka IP address on the IP port <b>8080</b>.<br><br>
<img alt="wms connect #2"><br><br>
Then you simply have to connect all three Coverages being published as WMS layers, one at each time.<br><br>
<img alt="wms test #1"><br><br>
<img alt="wms test #2"><br><br>
<img alt="wms test #3"><br><br>
You'll be immediately ready to visualize a full interactive WMS Map; and you could obviously switch on and off each layer at your will.<br><br>
<img alt="wms test #4"><br><br>
<img alt="wms test #5"><br><br>
<img alt="wms test #6"><br><br>
And you could eventually play a little bit around while testing and basic capabilities.<br><br>
<hr>
<u>Please note</u>: using the tool isn't at all a strict requirement. WMS is expected to be an universal standard protocol, so you could freely us any WMS client at your discretion.
You simply have to establish a connection to the following URL, and that should be all that is required in order to test the <b>wmslite</b> server.
<verbatim>

</verbatim>
The following figures represents a quick example showing how to connect QGIS to the server.<br><br>
<img alt="QGIS WMS connection #1"><br><br>
<img alt="QGIS WMS connection #2"><br><br>
<img alt="QGIS test"><br><br>
<hr><br>
Back to <a Tutorials index</a>