EVOLUTION-MANAGER

Edit File: frmt_rasterlite.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Rasterlite - Rasters in SQLite DB</title>
</head>

<body>

<h1>Rasterlite - Rasters in SQLite DB</h1>

Starting with GDAL 1.7.0, the Rasterlite driver allows reading and creating Rasterlite databases.

 Those databases can be produced by the utilities of the
 <a href="http://www.gaia-gis.it/spatialite">rasterlite</a> distribution,
 such as rasterlite_load, rasterlite_pyramids, .... 
 The driver supports reading grayscale, paletted and RGB images stored as GIF, PNG, TIFF or JPEG tiles.
 The driver also supports reading overviews/pyramids, spatial reference system and spatial extent.

Wavelet compressed tiles are not supported by default by GDAL, unless the <a href="frmt_epsilon.html">EPSILON</a> driver is compiled.

GDAL/OGR must be compiled with OGR SQLite driver support. For read support, linking against spatialite library is not required, but
recent enough sqlite3 library is needed to read rasterlite databases. rasterlite library is not required either.
For write support a new table, linking against spatialite library *is* required.

Although the Rasterlite documentation only mentions GIF, PNG, TIFF, JPEG and WAVELET (EPSILON driver) as
 compression formats for tiles, the driver supports reading and writing internal tiles in any format handled by GDAL.
 Furthermore, the Rasterlite driver also allow reading and writing as many bands and as many band types as supported by
 the driver for the internal tiles.

<h2>Connection string syntax in read mode </h2>

Syntax: 'rasterlitedb_name' or 'RASTERLITE:rasterlitedb_name[,table=raster_table_prefix][,minx=minx_val,miny=miny_val,maxx=maxx_val,maxy=maxy_val][,level=level_number]

where :
<ul>
<li>rasterlitedb_name is the filename of the RasterLite DB.</li>
<li>raster_table_prefix is the prefix of the raster table to open. For each raster, there are 2 corresponding SQLite tables, suffixed with _rasters and _metadata</li>
<li>minx_val,miny_val,maxx_val,maxy_val set a user-defined extent (expressed in coordinate system units) for the raster that can be different from the default extent.</li>
<li>level_number is the level of the pyramid/overview to open, 0 being the base pyramid.</li>
</ul>

<h2>Creation issues</h2>

The driver can create a new database if necessary, create a new raster table if necessary and copy a source dataset into the specified raster table.

If data already exists in the raster table, the new data will be added. You can use the WIPE=YES creation options to erase existing data.

The driver does not support updating a block in an existing raster table. It can only append new data.

Syntax for the name of the output dataset: 'RASTERLITE:rasterlitedb_name,table=raster_table_prefix' or 'rasterlitedb_name'

It is possible to specify only the DB name as in the later form, but only if the database does not already exists. In that case, the raster table name will be base on the DB name itself.

<h3>Creation options</h3>

<ul>
<li>WIPE (=NO by default): Set to YES to erase all preexisting data in the specified table</li>
<li>TILED (=YES by default) : Set to NO if the source dataset must be written as a single tile in the raster table</li>
<li>BLOCKXSIZE=n: Sets tile width, defaults to 256.</li>
<li>BLOCKYSIZE=n: Sets tile height, defaults to 256.</li>
<li>DRIVER=[GTiff/GIF/PNG/JPEG/EPSILON/...] : name of the GDAL driver to use for storing tiles. Defaults to GTiff</li>
<li>COMPRESS=[LZW/JPEG/DEFLATE/...] : (GTiff driver) name of the compression method</li>
<li>PHOTOMETRIC=[RGB/YCbCr/...] : (GTiff driver) photometric interpretation</li>
<li>QUALITY : (JPEG-compressed GTiff, JPEG and WEBP drivers) JPEG/WEBP quality 1-100. Defaults to 75</li>
<li>TARGET : (EPSILON driver) target size reduction as a percentage of the original (0-100). Defaults to 96.</li>
<li>FILTER : (EPSILON driver) Filter ID. Defaults to 'daub97lift'.</li>
</ul>

<h2>Overviews</h2>

The driver supports building (if the dataset is opened in update mode) and reading internal overviews.

If no internal overview is detected, the driver will try using external overviews (.ovr files).

Starting with GDAL 1.10, options can be used for internal overviews building. They can be specified with the
RASTERLITE_OVR_OPTIONS configuration option, as a comma separated list of the above creation options. See below
examples.

Starting with GDAL 1.10, all resampling methods supported by GDAL overviews are available.

<h2>Performance hints</h2>

Some of the performance hints of the OGR SQLite driver apply. In particular setting the OGR_SQLITE_SYNCHRONOUS
configuration option to OFF when creating a dataset or adding overviews might increase performance on some
filesystems.

After having added all the raster tables and building all the needed overview levels, it is advised to run :
<pre>
ogrinfo rasterlitedb.sqlite -sql "VACUUM"
</pre>
in order to optimize the database, and increase read performances afterwards. This is particularly true with big rasterlite datasets.
Note that the operation might take a long time.

<h2>Examples:</h2>

<ul>
<li>Accessing a rasterlite DB with a single raster table :
<pre>
$ gdalinfo rasterlitedb.sqlite -noct
</pre>
Output:
<pre>
Driver: Rasterlite/Rasterlite
Files: rasterlitedb.sqlite
Size is 7200, 7200
Coordinate System is:
GEOGCS["WGS 84",
 DATUM["WGS_1984",
 SPHEROID["WGS 84",6378137,298.257223563,
 AUTHORITY["EPSG","7030"]],
 AUTHORITY["EPSG","6326"]],
 PRIMEM["Greenwich",0,
 AUTHORITY["EPSG","8901"]],
 UNIT["degree",0.01745329251994328,
 AUTHORITY["EPSG","9122"]],
 AUTHORITY["EPSG","4326"]]
Origin = (-5.000000000000000,55.000000000000000)
Pixel Size = (0.002083333333333,-0.002083333333333)
Metadata:
 TILE_FORMAT=GIF
Image Structure Metadata:
 INTERLEAVE=PIXEL
Corner Coordinates:
Upper Left ( -5.0000000, 55.0000000) ( 5d 0'0.00"W, 55d 0'0.00"N)
Lower Left ( -5.0000000, 40.0000000) ( 5d 0'0.00"W, 40d 0'0.00"N)
Upper Right ( 10.0000000, 55.0000000) ( 10d 0'0.00"E, 55d 0'0.00"N)
Lower Right ( 10.0000000, 40.0000000) ( 10d 0'0.00"E, 40d 0'0.00"N)
Center ( 2.5000000, 47.5000000) ( 2d30'0.00"E, 47d30'0.00"N)
Band 1 Block=480x480 Type=Byte, ColorInterp=Palette
 Color Table (RGB with 256 entries)

</pre>
</li>

<li>Listing a multi-raster table DB :
<pre>
$ gdalinfo multirasterdb.sqlite
</pre>
Output:
<pre>
Driver: Rasterlite/Rasterlite
Files:
Size is 512, 512
Coordinate System is `'
Subdatasets:
 SUBDATASET_1_NAME=RASTERLITE:multirasterdb.sqlite,table=raster1
 SUBDATASET_1_DESC=RASTERLITE:multirasterdb.sqlite,table=raster1
 SUBDATASET_2_NAME=RASTERLITE:multirasterdb.sqlite,table=raster2
 SUBDATASET_2_DESC=RASTERLITE:multirasterdb.sqlite,table=raster2
Corner Coordinates:
Upper Left ( 0.0, 0.0)
Lower Left ( 0.0, 512.0)
Upper Right ( 512.0, 0.0)
Lower Right ( 512.0, 512.0)
Center ( 256.0, 256.0)

</pre>
</li>

<li>Accessing a raster table within a multi-raster table DB:
<pre>
$ gdalinfo RASTERLITE:multirasterdb.sqlite,table=raster1
</pre>
</li>

<li>Creating a new rasterlite DB with data encoded in JPEG tiles :
<pre>
$ gdal_translate -of Rasterlite source.tif RASTERLITE:my_db.sqlite,table=source -co DRIVER=JPEG
</pre>
</li>

<li>Creating internal overviews :
<pre>
$ gdaladdo RASTERLITE:my_db.sqlite,table=source 2 4 8 16
</pre>
</li>

<li>Cleaning internal overviews :
<pre>
$ gdaladdo -clean RASTERLITE:my_db.sqlite,table=source
</pre>
</li>

<li>Creating external overviews in a .ovr file:
<pre>
$ gdaladdo -ro RASTERLITE:my_db.sqlite,table=source 2 4 8 16
</pre>
</li>

<li>Creating internal overviews with options (GDAL 1.10 or later):
<pre>
$ gdaladdo RASTERLITE:my_db.sqlite,table=source 2 4 8 16 --config RASTERLITE_OVR_OPTIONS DRIVER=GTiff,COMPRESS=JPEG,PHOTOMETRIC=YCbCr
</pre>
</li>

</ul>

See Also:

<ul>
<li><a href="http://www.gaia-gis.it/spatialite">Spatialite and Rasterlite home page</a></li>
<li><a href="http://www.gaia-gis.it/gaia-sins/rasterlite-docs/rasterlite-man.pdf">Rasterlite manual</a></li>
<li><a href="http://www.gaia-gis.it/gaia-sins/rasterlite-docs/rasterlite-how-to.pdf">Rasterlite howto</a></li>
<li><a href="http://www.gaia-gis.it/spatialite-2.3.1/resources.html">Sample databases</a></li>
<li><a href="http://gdal.org/drv_sqlite.html">OGR SQLite driver</a></li>
</ul>

</body>
</html>