Back to RasterLite2 Tutorials index
Tutorial: building and testing the Trento sample
In this tutorial we'll use the following input datasources: please download all them right now. They are Open Data released under a free license, and are available absolutely for free. The whole dataset corresponds to a mosaic of seven orthorectified aerial images covering the Town and the Local Council of Trento (Italy). All images were taken during year 2009 and support a rather high resolution (0.5 meters/pixel). Each image is made available as a JPEG image and is supported by a corresponding WorldFile presenting a non-standard .wld file-extension.Step 1) renaming all WorldFiles
RasterLite2 expects that each JPEG datasource should be eventually supported by a WorldFile sharing the same identical name of the main image and presenting .jgw file-extension. This obviously isn't the actual case, so you'll first rename all WorldFiles so to adjust for the expected extension.Step 2) creating the Trento Coverage
$ rl2tool CREATE -db trento.sqlite -cov photo -smp UINT8 -pxl RGB \
-cpr JPEG -srid 25832 -res 0.5 -nd 255,255,255
rl2_tool: request is CREATE
===========================================================
DB path: trento.sqlite
Coverage: photo
Sample Type: UINT8
Pixel Type: RGB
Number of Bands: 3
NO-DATA pixel: 255,255,255
Compression: JPEG (lossy)
Compression Quality: 80
Tile size (pixels): 512 x 512
Srid: 25832
Pixel base resolution: X=0.5 Y=0.5
===========================================================
SQLite version: 3.8.5
SpatiaLite version: 4.2.0-rc1
RasterLite2 version: 0.8
Raster Coverage "photo" successfully created
Operation CREATE successfully completed
$
- Exactly as you already did in the previous planet Earth tutorial you'll invoke rl2tool from the command shell.
- in this case we'll pass the following arguments (explained one by one):
- CREATE this main keyword intends that we are trying to create a new, empty Coverage.
- -db trento.sqlite this specifies the target DB-file pathname; this DB-file doesn't yet exist, so it will be implicitly created at once.
- -cov photo this specifies the individual Coverage's name.
- -smp UINT8 this specifies the Coverage's Sample Type.
- -pxl RGB this specifies the Coverage's Pixel Type.
- -cpr JPEG this specifies that all Tiles in this Coverage must be JPEG compressed.
- -srid 25832 this specifies the Coverage's SRID.
Please note: unhappily this very relevant information seems to be completely ignored in the WEB download page; anyway just a quick glance at the coordinates declared within the WorldFiles leads to the very reasonable assumption that WGS 84 / UTM zone 32N (aka EPSG SRID 32632) should be implicitly intended. An alternative guess could be ETRS89 / UTM zone 32N (aka EPSG SRID 25832): anyway the differences between these two Reference Systems are so slight (at least on the X,Y plane and completely ignoring the Z coordinate) to be safely ignored for any practical purpose . - -res 0.5 this specifies the Coverage's base level resolution.
- -nd 255,255,255 explicitly requests to consider all WHITE pixels to be transparent; this is because the input JPEGs have a rather irregular shape, and contains wide useless white portions.
By declaring any white pixel to be transparent we'll then avoid any further problem arising for partially ovelapping Sections.
Step 3) populating the Trento Coverage
$ rl2tool IMPORT -db trento.sqlite -cov photo -srid 25832 \
-wf -dir . -ext .jpg
rl2_tool; request is IMPORT
===========================================================
DB path: trento.sqlite
Input Directory path: .
File Extension: .jpg
Coverage: photo
Section: from file name
Using the WorldFile
Forced SRID: 25832
Ignoring Pyramid Levels for now
===========================================================
SQLite version: 3.8.5
SpatiaLite version: 4.2.0-rc1
RasterLite2 version: 0.8
Importing: ./bondone_2009.jpg
------------------
Image Size (pixels): 6540 x 6860
SRID: 25832
LowerLeft Corner: X=658501.45 Y=5099307.10
UpperRight Corner: X=661771.25 Y=5102737.04
Pixel resolution: X=0.499969419 Y=0.4999912536
Importing: ./centronord_2009.jpg
------------------
Image Size (pixels): 10660 x 10220
SRID: 25832
LowerLeft Corner: X=660901.46 Y=5102707.02
UpperRight Corner: X=666231.34 Y=5107816.92
Pixel resolution: X=0.499988743 Y=0.4999902152999999
Importing: ./centrosud_2009.jpg
------------------
Image Size (pixels): 10500 x 9200
SRID: 25832
LowerLeft Corner: X=662341.39 Y=5098307.09
UpperRight Corner: X=667591.29 Y=5102906.98
Pixel resolution: X=0.4999904761999999 Y=0.4999880434999999
Importing: ./est_2009.jpg
------------------
Image Size (pixels): 8060 x 7910
SRID: 25832
LowerLeft Corner: X=666081.25 Y=5102846.97
UpperRight Corner: X=670111.27 Y=5106801.75
Pixel resolution: X=0.5000024814 Y=0.4999721871
Importing: ./nord_2009.jpg
------------------
Image Size (pixels): 10602 x 10230
SRID: 25832
LowerLeft Corner: X=660810.60 Y=5107731.93
UpperRight Corner: X=666111.37 Y=5112846.75
Pixel resolution: X=0.4999783496999999 Y=0.4999824046999999
Importing: ./ovest_2009.jpg
------------------
Image Size (pixels): 9230 x 9100
SRID: 25832
LowerLeft Corner: X=656466.25 Y=5102637.04
UpperRight Corner: X=661081.43 Y=5107186.96
Pixel resolution: X=0.5000195015999999 Y=0.4999912087999999
Importing: ./sud_2009.jpg
------------------
Image Size (pixels): 10520 x 9220
SRID: 25832
LowerLeft Corner: X=662451.35 Y=5093856.75
UpperRight Corner: X=667711.26 Y=5098466.75
Pixel resolution: X=0.4999914449 Y=0.5
Operation IMPORT successfully completed
$
- now you'll invoke yet another time rl2tool so to import all JPEG images (aka Sections accordingly to RasterLite2 terminology) in a single pass.
- and you'll pass the following arguments (explained one by one):
- IMPORT this main keyword intends that we are trying to populate an already created Coverage by importing from an external datasource.
- -db and -cov: same as above.
- -wf: this directive instructs rl2tool to search and parse an external WorldFile expected to contain georeferencing informations for each image file to be imported.
- -srid 25832: anyway the WordFile format doesn't support an explicit identification of the intended Reference System; so explicitly declaring some SRID value is strictly required.
- -dir . this specifies the input path of the external datasources to be imported; -dir intends that a whole folder (aka directory) will be searched.
Please note: the special name . (dot) simply intents the current working directory). - -ext .jpg: then all files from the input folder presenting the .jpg file-extension will be automatically imported one after the other.
Step 4) Creating a Monolithic Pyramid
You probably noticed that during the previous step no immediate Pyramid generation was required.This was because we are going to create now a different kind of Pyramid; RasterLite2 allows to choose between two alternative strategies:
- Section-based Pyramid: each single Section within a Coverage will have its own multi-level multi-resolution Pyramid.
Using this approach you'll be free to insert or delete single Sections one at each time without invalidating the overall Pyramid consistency. And each single sub-pyramid could be immediately built when importing a further Section. - Monolithic Pyramid: a single multi-level multi-resolution Pyramid will cover the Coverage as a whole.
Using this second approach each change affecting the underlaying Coverage (i.e. adding or removing a Section) will immediately invalidate the Pyramid consistency; and the Pyramid will then require to be rebuilt from scratch.
$ rl2tool PYRAMIDIZE-MONOLITHIC -db trento.sqlite -cov photo -lev 3
rl2_tool; request is PYRAMIDIZE-MONOLITHIC
===========================================================
DB path: trento.sqlite
Coverage: photo
Pyramid Virtual Levels: 3
===========================================================
SQLite version: 3.8.5
SpatiaLite version: 4.2.0-rc1
RasterLite2 version: 0.8
----------
photo: Monolithic Pyramid Level 1 - Row 1 of 10 successfully built
----------
photo: Monolithic Pyramid Level 1 - Row 2 of 10 successfully built
----------
photo: Monolithic Pyramid Level 1 - Row 3 of 10 successfully built
----------
photo: Monolithic Pyramid Level 1 - Row 4 of 10 successfully built
----------
photo: Monolithic Pyramid Level 1 - Row 5 of 10 successfully built
----------
photo: Monolithic Pyramid Level 1 - Row 6 of 10 successfully built
----------
photo: Monolithic Pyramid Level 1 - Row 7 of 10 successfully built
----------
photo: Monolithic Pyramid Level 1 - Row 8 of 10 successfully built
----------
photo: Monolithic Pyramid Level 1 - Row 9 of 10 successfully built
----------
photo: Monolithic Pyramid Level 1 - Row 10 of 10 successfully built
----------
photo: Monolithic Pyramid Level 2 - Row 1 of 2 successfully built
----------
photo: Monolithic Pyramid Level 2 - Row 2 of 2 successfully built
----------
photo: Monolithic Pyramid Level 3 - Row 1 of 1 successfully built
----------
Monolithic Pyramid levels successfully built for: photo
Operation PYRAMIDIZE-MONOLITHIC successfully completed
$
- now you'll invoke yet another time rl2tool so to build a Monolithic Pyramid.
- and you'll pass the following arguments (explained one by one):
- PYRAMIDIZE-MONOLITHIC this main keyword intends that we are trying to build a Monolithic Pyramid supporting an already populated Coverage.
If any previous Pyramid should eventually already exists it will be implicitly destroyed and rebuilt yet again from scratch. - -db and -cov: same as above.
- -lev 3 this optional directive specifies that every Pyramid Level should support three different resolutions: one physical and two virtual.
- PYRAMIDIZE-MONOLITHIC this main keyword intends that we are trying to build a Monolithic Pyramid supporting an already populated Coverage.
SELECT RL2_SetCoverageInfos('photo', 'Orthophoto 2009', 'Aerial orthophotos; RGB 0.5m/pixel year 2009');
Please remember: always setting a TITLE and an ABSTRACT for any Coverage being creates always is a strongly recommended good practice.
Step 5) Testing the Trento sample
As you've already done in the previous Planet Earth you can now directly test the Trento Coverage by publishing a standard WMS service.You simply have to start the wmslite light-weight server, then connecting some WMS viewer (e.g. LibreWMS) to the service being published on localhost aka IP address 127.0.0.1, port 8080.
Step 6) retrieving Coverage- and Section-level statistics
$ rl2tool CATALOG -db trento.sqlite -cov photo
rl2_tool; request is CATALOG
===========================================================
DB path: trento.sqlite
===========================================================
SQLite version: 3.8.5
SpatiaLite version: 4.2.0-rc1
RasterLite2 version: 0.8
===============================================================================
Coverage: photo
Title: *** missing Title ***
Abstract: *** missing Abstract ***
-------------------------------------------------------------------------------
Sample Type: UINT8
Pixel Type: RGB
Number of Bands: 3
Compression: JPEG (lossy)
Compression Quality: 80
Tile Size (pixels): 512 x 512
Pixel base resolution: X=0.5 Y=0.5
-------------------------------------------------------------------------------
Overall Size (pixels): 27290 x 37980
Srid: 25832 (epsg,25832) ETRS89 / UTM zone 32N
LowerLeftCorner: X=656466.2500097508 Y=5093856.75
UpperRightCorner: X=670111.2700013245 Y=5112846.750008797
-------------------------------------------------------------------------------
NO-DATA Pixel: 255, 255, 255
-------------------------------------------------------------------------------
NO-DATA Pixels Count: 164199958
Valid Pixels Count: 457867754
=========== Band #0 Summary ==========
Min Value: 0
Max Value: 255
Mean Value: 123.3914654950782
Variance: 2005.477819097288
Standard Deviation: 44.78256155131468
=========== Band #1 Summary ==========
Min Value: 0
Max Value: 255
Mean Value: 127.438034312851
Variance: 1605.106033488249
Standard Deviation: 40.0637745786421
=========== Band #2 Summary ==========
Min Value: 0
Max Value: 255
Mean Value: 118.3748520233202
Variance: 1586.230239285422
Standard Deviation: 39.82750606409372
-------------------------------------------------------------------------------
=== Pyramid Level: 0 ==========================
Physical resolution: X=0.5 Y=0.5
Virtual resolution: X=1.0 Y=1.0
Virtual resolution: X=2.0 Y=2.0
Virtual resolution: X=4.0 Y=4.0
Tiles Count: 2397
BLOB Bytes: 424388165
=== Pyramid Level: 1 ==========================
Physical resolution: X=4.0 Y=4.0
Virtual resolution: X=8.0 Y=8.0
Virtual resolution: X=16.0 Y=16.0
Virtual resolution: X=32.0 Y=32.0
Tiles Count: 43
BLOB Bytes: 3142420
=== Pyramid Level: 2 ==========================
Physical resolution: X=32.0 Y=32.0
Virtual resolution: X=64.0 Y=64.0
Virtual resolution: X=127.9999999999999 Y=127.9999999999999
Virtual resolution: X=255.9999999999999 Y=255.9999999999999
Tiles Count: 2
BLOB Bytes: 64692
=== Pyramid Level: 3 ==========================
Physical resolution: X=255.9999999999999 Y=255.9999999999999
Virtual resolution: X=511.9999999999999 Y=511.9999999999999
Virtual resolution: X=1023.999999999999 Y=1023.999999999999
Virtual resolution: X=2047.999999999999 Y=2047.999999999999
Tiles Count: 1
BLOB Bytes: 8154
===============================================================================
Operation CATALOG successfully completed
$
You can invoke rl2tool CATALOG in order to retrieve fine-grained statistical informations about any Coverage; just omitting to specify any Coverage name will then report all Coverages from a DB-file.
$ rl2tool LIST -db trento.sqlite -cov photo -sec sud_2009
rl2_tool; request is LIST
===========================================================
DB path: trento.sqlite
Coverage: photo
Section: sud_2009
===========================================================
SQLite version: 3.8.5
SpatiaLite version: 4.2.0-rc1
RasterLite2 version: 0.8
===============================================================================
Coverage: photo
===============================================================================
-------------------------------------------------------------------------------
Section: (7) sud_2009
-------------------------------------------------------------------------------
Size (pixels): 10520 x 9220
Input Path: ./sud_2009.jpg
LowerLeft corner: X=662451.35 Y=5093856.75
UpperRight corner: X=667711.26 Y=5098466.75
Center Point: X=665081.30 Y=5096161.75
-------------------------------------------------------------------------------
NO-DATA Pixels Count: 48721641
Valid Pixels Count: 55873815
=========== Band #0 Summary ==========
Min Value: 0
Max Value: 255
Mean Value: 127.3124062138946
Variance: 2087.151931900126
Standard Deviation: 45.68535795963654
=========== Band #1 Summary ==========
Min Value: 0
Max Value: 255
Mean Value: 132.3306155844202
Variance: 1633.408543226294
Standard Deviation: 40.41544931367575
=========== Band #2 Summary ==========
Min Value: 0
Max Value: 255
Mean Value: 123.6940782547244
Variance: 1597.50000265527
Standard Deviation: 39.96873781663952
-------------------------------------------------------------------------------
========== Level: 0 ==========
Tiles Count: 399
BLOB Bytes: 54326168
-------------------------------------------------------------------------------
Operation LIST successfully completed
$
And you can invoke rl2tool LIST in order to retrieve fine-grained statistical informations about any Section; just omitting to specify any Section name will then report all Sections from a Coverage.
$ rl2tool MAP -db trento.sqlite -cov photo -outw 480 \
-outh 640 -dst trento.png
rl2_tool; request is MAP
===========================================================
DB path: trento.sqlite
Coverage: photo
Destination Path: trento.png
Image Size: 512 x 640
===========================================================
SQLite version: 3.8.5
SpatiaLite version: 4.2.0-rc1
RasterLite2 version: 0.8
Operation MAP successfully completed
$
By invoking rl2tool MAP you can create a PNG image representing the overall Sections layout within a Coverage:
- -outw 480 -outh 640: these are the dimensions of the PNG image; in this case 480 x 640.
- -dst trento.png: this is the pathname of the PNG image to be created.
Please note: you could eventually just specify the basename (as e.g. in -dst trento) and then a .png extension will be automatically added to the image path.
And this image corresponds to the actual output created by the above rl2tool MAP execution.
Step 7) examining Band Histograms
You could eventually invoke rl2tool HISTOGRAM in order to get the visual representation of any band histogram (i.e. the statistical distribution of pixel values for the given band). You are free to examine band histograms both for a Coverage as a whole or for a single Section; just omitting to specify any Section name will then report all Sections from a Coverage.
$ rl2tool HISTOGRAM -db trento.sqlite -cov photo -bnd 0 \
-dst red_histogram.png
rl2_tool; request is HISTOGRAM
===========================================================
DB path: trento.sqlite
Coverage: photo
Histogram from Coverage-level Statistics
Band Index: 0
Destination: red_histogram.png
===========================================================
SQLite version: 3.8.5
SpatiaLite version: 4.2.0-rc2
RasterLite2 version: 0.9
Operation HISTOGRAM successfully completed
$ rl2tool HISTOGRAM -db trento.sqlite -cov photo -bnd 1 \
-dst green_histogram
rl2_tool; request is HISTOGRAM
===========================================================
DB path: trento.sqlite
Coverage: photo
Histogram from Coverage-level Statistics
Band Index: 1
Destination: green_histogram.png
===========================================================
SQLite version: 3.8.5
SpatiaLite version: 4.2.0-rc2
RasterLite2 version: 0.9
Operation HISTOGRAM successfully completed
$ rl2tool HISTOGRAM -db trento.sqlite -cov photo -bnd 2 \
-dst blue_histogram
rl2_tool; request is HISTOGRAM
===========================================================
DB path: trento.sqlite
Coverage: photo
Histogram from Coverage-level Statistics
Band Index: 2
Destination: blue_histogram.png
===========================================================
SQLite version: 3.8.5
SpatiaLite version: 4.2.0-rc2
RasterLite2 version: 0.9
Operation HISTOGRAM successfully completed
$ rl2tool HISTOGRAM -db trento.sqlite -cov photo -bnd 2 \
-sec est_2009 -dst blue_sec_histogram
rl2_tool; request is HISTOGRAM
===========================================================
DB path: trento.sqlite
Coverage: photo
Section: est_2009
Histogram from Section-level Statistics
Band Index: 2
Destination: blue_sec_histogram
===========================================================
SQLite version: 3.8.5
SpatiaLite version: 4.2.0-rc2
RasterLite2 version: 0.9
Operation HISTOGRAM successfully completed
The following images correspond to the actual output created by the above rl2tool HISTOGRAM executions.
Red Band (index = 0) histogram, whole Coverage
Green Band (index = 1) histogram, whole Coverage
Blue Band (index = 2) histogram, whole Coverage
Blue Band (index = 2) histogram, est_2009 Section alone
Step 8) exporting a selected sub-portion from a Coverage as an image file
You could eventually invoke rl2tool EXPORT in order to create on the local file-system an image file corresponding to a spatially selected portion of the Coverage. And in doing this you are absolutely free to choose anyone of the multiple resolutions available from the Pyramid supporting the Coverage.
$ rl2tool EXPORT -db trento.sqlite -cov photo -outw 640 \
-outh 480 -res 0.5 -cx 664750 -cy 5104750 -dst trento-sub-05.jpg
rl2_tool; request is EXPORT
===========================================================
DB path: trento.sqlite
Coverage: photo
Pixel size: X=0.5 Y=0.5
Image Size: 640 x 480
Output image: trento-sub-05.jpg
Lower-Left Corner: 664590.00 5104630.00
Upper-Right Corner: 664910.00 5104870.00
Center: 664750.00 5104750.00
===========================================================
SQLite version: 3.8.5
SpatiaLite version: 4.2.0-rc2
RasterLite2 version: 0.9
Operation EXPORT successfully completed
$ rl2tool EXPORT -db trento.sqlite -cov photo -outw 640 \
-outh 480 -res 1 -cx 664750 -cy 5104750 -dst trento-sub-1.jpg
rl2_tool; request is EXPORT
===========================================================
DB path: trento.sqlite
Coverage: photo
Pixel size: X=1.0 Y=1.0
Image Size: 640 x 480
Output image: trento-sub-1.jpg
Lower-Left Corner: 664430.00 5104510.00
Upper-Right Corner: 665070.00 5104990.00
Center: 664750.00 5104750.00
===========================================================
SQLite version: 3.8.5
SpatiaLite version: 4.2.0-rc2
RasterLite2 version: 0.9
Operation EXPORT successfully completed
$ rl2tool EXPORT -db trento.sqlite -cov photo -outw 640 \
-outh 480 -res 2 -cx 664750 -cy 5104750 -dst trento-sub-2.jpg
rl2_tool; request is EXPORT
===========================================================
DB path: trento.sqlite
Coverage: photo
Pixel size: X=2.0 Y=2.0
Image Size: 640 x 480
Output image: trento-sub-2.jpg
Lower-Left Corner: 664110.00 5104270.00
Upper-Right Corner: 665390.00 5105230.00
Center: 664750.00 5104750.00
===========================================================
SQLite version: 3.8.5
SpatiaLite version: 4.2.0-rc2
RasterLite2 version: 0.9
Operation EXPORT successfully completed
$ rl2tool EXPORT -db trento.sqlite -cov photo -outw 640 \
-outh 480 -res 4 -cx 664750 -cy 5104750 -dst trento-sub-4.jpg
rl2_tool; request is EXPORT
===========================================================
DB path: trento.sqlite
Coverage: photo
Pixel size: X=4.0 Y=4.0
Image Size: 640 x 480
Output image: trento-sub-4.jpg
Lower-Left Corner: 663470.00 5103790.00
Upper-Right Corner: 666030.00 5105710.00
Center: 664750.00 5104750.00
===========================================================
SQLite version: 3.8.5
SpatiaLite version: 4.2.0-rc2
RasterLite2 version: 0.9
Operation EXPORT successfully completed
$ rl2tool EXPORT -db trento.sqlite -cov photo -outw 640 \
-outh 480 -res 8 -cx 664750 -cy 5104750 -dst trento-sub-8.jpg
rl2_tool; request is EXPORT
===========================================================
DB path: trento.sqlite
Coverage: photo
Pixel size: X=8.0 Y=8.0
Image Size: 640 x 480
Output image: trento-sub-8.jpg
Lower-Left Corner: 662190.00 5102830.00
Upper-Right Corner: 667310.00 5106670.00
Center: 664750.00 5104750.00
===========================================================
SQLite version: 3.8.5
SpatiaLite version: 4.2.0-rc2
RasterLite2 version: 0.9
Operation EXPORT successfully completed
$
- -outw 640 -outh 480: these are the dimensions of the output image to be created; in this case 640 x 480.
- -res 8: this is the selected resolution (expressed in map units / pixel).
Note well: only resolutions closely matching one of the resolution supported by the internal multi-resolution Pyramid will be accepted. - -cx 664750 -cy 5104750: these are the X,Y map coordinates corresponding to the central point of the exported image.
A precisely identified tie point is always strictly required, but this one has not necessarily to coincide with the central point; other valid options could be the upper left corner (-minx -maxy), the upper right corner (-maxx -maxy), the lower left corner (-minx -miny) or the lower right corner (-maxx -miny). - -dst trento-sub-8.jpg: this is the pathname of the output image. The actual format selection is determined by the file extension; valid options are .jpg and .tif for visible images, or .asc (ASCII grid) for coverages of the DataGrid type.
Please note: all exported images will always include some kind of georeferencing. TIFF images will actually be GeoTIFFs, JPEG images will be supported by a companion WordFile; and all ASCII Grids always include internal georeferencing informations.
| Resolution: 0.5 m / pixel (original resolution) |
 |
| Resolution: 1.0 m / pixel (rescaled 1:2) |
 |
| Resolution: 2.0 m / pixel (rescaled 1:4) |
 |
| Resolution: 4.0 m / pixel (rescaled 1:8) |
 |
| Resolution: 8.0 m / pixel (rescaled 1:16) |
 |
Back to RasterLite2 Tutorials index