Not logged in

Back to RasterLite2 doc index

Basic concepts and Terminology adopted by RasterLite2

Objects Hierarchy: Coverages, Sections and Tiles

  1. the Coverage is the topmost level object.
    A Coverage is a very generic container and is internally articulated into many different Sections (may be, hundredth or even thousand Sections); as a limit case, a Coverage could just contain a single Section.
    All Sections belonging to the same Coverage must always share many relevant properties, i.e.:
    • same SRID (aka Spatial Reference System).
    • same Pixel format (i.e. RGB, or GRAYSCALE or DATAGRID), same Sample type (i.e. UINT8 or UINT16 or DOUBLE) and same Bands Configuration.
    • same Compression and same optional Policies.
    • all these critical parameters will be defined while creating a Coverage.
      Any subsequent attempt to modify such parameters will always be considered a forbidden operation if the Coverage already contains any Tile.
    • a Coverage always has its own Bounding Box (aka BBOX) which simply corresponds to the overall BBOX for all subordinated Sections.
  2. the Section is an intermediate level object.
    A Section usually corresponds to a single image file initially used to populate the Coverage.
    Each Section has its own private BBOX and there is no special constraint about mutual BBOX relationships of different Sections belonging to the same Coverage:
    • Sections aren't required to be strictly adjacent and contiguous; a Coverage is absolutely free to include empty / uncovered areas; in this case they'll be simply considered as full Transparent areas.
    • two or more Sections are absolutely free to partially or completely overlap (please see S1 and S4 in the above figure).
      In this case the Section identified by the higher ID value will always cover any other Section of lower ID value.
    • Sections in the same Coverage aren't required to have the same Width and Height dimensions.
  3. the Tile is the lowermost level object.
    Each Section is always internally stored as a collection of many individual Tiles:
    • All Tiles belonging to the same Coverage must always share the same identical layout: same Pixel Type, Sample Type and Band Configuration; and identical Compression.
    • All Tiles in the same Coverage must always have the same identical Width and Height dimensions:
      • Tiles belonging to the same Section will always form a strictly packed regular grid.
      • in the above figure Sections S1 and S3 are rather exceptional, because their Width and Height dimensions corresponds to an exact multiple of the Tile dimensions.
      • Sections S2 and S4 instead are more realistic examples; when the Section's Width and Height doesn't exactly match the Tile dimension all rightmost and lowermost Tiles will always be only partially filled. The unused portion of such Tiles will simply correspond to a full Transparent area.
    • all Tiles have their individual BBOX; partially populated Tiles will have a reduced BBOX simply representing the portion being effectively populated.
      So the overall extent of all Tiles belonging to the same Section will always exactly match the Section's BBOX.
    • as a general design principle any completely empty Tile (i.e. exactly corresponding to a full Transparent area) will never be physically inserted into the DBMS, thus avoiding to waste unnecessary storage.
    • Tiles will be mostly considered as read only objects: Tiles can be freely inserted (while importing the corresponding Section) but can never be updated or altered in any way once inserted. Anyway this rule has its exceptions (we'll examine this topic in more depth in a following paragraph: Coverage Policies).

Multi-Resolution Pyramid

Coverages and / or Sections could eventually be supported by a Multi-Resolution Pyramid: creating a Pyramid isn't a strictly required operation, anyway this is a very useful and highly recommended option.

Different Physical / Virtual Levels supported by RasterLite2 Pyramids

Interleaving 3

This is the standard default setting (except in the case of MONOCHROME 1-BIT Coverages).
One Pyramid Level every three is physical and the following two are purely virtual.

e.g. resolution 1:1 is physical then 1:2 and 1:4 are virtual.
Resolution 1:8 is physical then 1:16 and 1:32 are virtual and so on.
pyramid interleaving 3

Interleaving 2

Pyramid Levels are alternatively one physical and one purely virtual.

e.g. resolution 1:1 is physical then 1:2 is virtual.
Resolution 1:4 is physical then 1:8 is virtual and so on.
pyramid interleaving 2

Interleaving 1

This is the standard default setting for MONOCHROME 1-BIT Coverages.

All Pyramid Levels are physical; virtual levels are never used.
pyramid interleaving 1

Please note very well: thanks to the Adam7 Tile encoding extensively adopted by RasterLite2, even the base-resolution Level alone will automatically support the first four resolutions (i.e. 1:1, 1:2, 1:8 and 1:16) even when absolutely no Pyramid support is available.
Anyway this doesn't applies to MONOCHROME 1-BIT Coverages; in this specific case the base-level will simply support 1:1 alone and no other further resolution.

Section-based Pyramids

RasterLite2 can handle Pyramids in two different flavours: the first one in based on many individual and independent Pyramids each one strictly supporting just a single Section. Section-based Pyramids are supported for all Coverage types with no exception.

pyramid base-level
The above figure represents the overall layout of a Coverage articulated into several Sections (A, B, C, D, E, F, G and H).

pyramid by section
This second figure shows the corresponding layout of Section-based Pyramids:

Monolithic Pyramid

pyramid monolithic
This third figure (same Coverage / Sections layout as is the previous case) represents the alternative case of a Monolithic Pyramid:

Main differences between Section-based and Monolithic Pyramids

Coverage Policies

Each single Coverage has its own Policies; this is a set of boolean options intended to support a very flexible configuration accordingly to specific requirements.
The current version supports the following Policy Options (future versions of RasterLite2 could easily extend the list by introducing further Options):

the strictResolution Policy Option

When this Option Policy is enabled all Sections being imported into the Coverage mist exactly correspond to the Horizontal and Vertical Pixel Resolution declared when creating the Coverage.
The Resolution check will be intended in the most pedantic and fussy mode: even the slightest difference found will inexorably cause a failure to load.

the mixedResolutions Policy Option

This is exactly the opposite than before: in this case the Coverage itself has no intrinsic Horizontal and Vertical Pixel Resolution, and each single Section being imported will then be absolutely free to declare any possible Resolution.
Please note well: any Coverage declaring the mixedResolutions Option will be always forbidden to support a Pyramid of the Monolithic type; anyways it will still able to support a Pyramid of the alternative Section-based type.

Fallback case: what happens when a Coverage doesn't declare neither strictResolution nor mixedResolutions ?
In the case the permissive resolution check mode will be enabled, substantially corresponding to a relaxed equivalent of strictResolution.
The resolution declared by any Section being imported will still continue to be checked for compatibility, but will evaluated in a permissive way thus allowing to consider small differences (<= 1%) as acceptable.
This will certainly cause some occasional pixel misalignment here and there, but this shouldn't be a real problem for many simple, unsophisticated and not too much demanding applications.

the immutable Policy Option

When this Option Policy is enabled then any Section and any Tile can never be altered in any way after its initial insertion into the DBMS.
Anyway a Section could still be completely removed (this including all subordinated Tiles), and may be re-imported yet another time (e.g. because an updated version of the corresponding input image is now available).

the sectionPaths Policy Option

When this Option Policy is enabled then all Sections will permanently record the input path used to initially import the corresponding image from the filesystem.
Please note: activating this Option may probably be useful on typical standalone Personal / Desktop environments, but will surely imply introducing many dangerous security concerns in server environments, because it will externally disclose many critical details about the layout adopted by the internal filesystem.

the sectionMD5 Policy Option

When this Option Policy is enabled then for each Section being imported the MD5 checksum will be computed on behalf of the input file and will then be permanently recorded as a Section attribute.
A short rationale for using MD5 checksums: file paths may eventually change during the time, because rearranging the directories tree is a very frequent maintenance operation. Even individual file names are potentially subject to suddenly change for same reason.
Anyway an MD5 checksum is an absolute invariant; if the internal file content never changes, the MD5 checksum will always remain exactly the same.
So using MD5 checksums as file identifiers surely is an effective mean allowing to keep full trace of the original files initially imported, even when the corresponding paths could crazily change; and without externally disclose any critical information about the internal filesystem.

the sectionSummary Policy Option

When this Option Policy is enabled then for each Section being imported an XML summary describing the input file will be permanently recorded as a Section attribute.
<?xml version="1.0" encoding="UTF-8"?>
    <SampleFormat>unsigned integer</SampleFormat>
    <PlanarConfiguration>single Raster plane</PlanarConfiguration>
            <RefSysName>NAD83 / UTM zone 16N</RefSysName>
The above sample is an example of an XML Summary produced by RasterLite2.

Annex A: the Adam7 multi-resolution Tile encoding

Many Tile codecs supported by RasterLite2 are completely based on the Adam7 encoding schema; other are not (e.g. the JPEG, PNG and WebP based codecs) simply because an intrinsic rescaling capability is already supplied by the underlying codec.

How Adam7 works

Adam7 animation
  • All pixels require to be are arranged in a more convenient way, so to be immediately accessible in the fastest way accordingly to the Adam7 schema.
  • Recreating the original image at full resolution (1:1) will require 7 subsequent passes (and this explains why it's called Adam7); more limited resolutions will require less passes, accordingly to the following schema:
    • the first pass alone will recreate a reduced image corresponding to the 1:8 resolution.
    • the first 3 passes will recreate a reduced image corresponding to the 1:4 resolution.
    • the first 5 passes will recreate a reduced image corresponding to the 1:2 resolution.
    • and finally, as previously stated, all 7 passes rill recreate the 1:1 image at full resolution.
The following figures will probably help to understand better:

rescaled resolutionAdam7 passaffected pixelsoutput image
1:8 #1 Adam7 pass 1 Adam7 1:8
1:4 #2 Adam7 pass 2 Adam7 1:4
#3 Adam7 pass 3
1:2 #4 Adam7 pass 4 Adam7 1:2
#5 Adam7 pass 5
1:1 #6 Adam7 pass 6 Adam7 1:1
#7 Adam7 pass 7

Further Adam7 optimizations applied by RasterLite2

mapping the conceptual Objects Model into a DBMS layout

ObjectDBMS tableRemarks
Coverage raster_coverages Main Coverages Catalog; this table is the symmetric equivalent of what geometry_columns is in the case of Vector data.
All critical configuration parameters for each Coverage are stored into this table: pixel type, sample type, compression, tile size, SRID and so on.
coverage_policies An auxiliary table storing individual Policy Options for each Coverage.
The main rationale suggesting to place all Policy Options in a separate table is in that future versions of RasterLite2 will presumably add many further supported Policies.
Section <coverage_name>_sections All Sections being loaded into the Coverage will have a corresponding entry into this table.
This including any optional information such as input path, MD5 checksum and section Summary accordingly to Policy Options settings.
This one is a geometry table (Section BBOX) and is supported by a Spatial Index.
Tile <coverage_name>_tiles Both base-level (aka full resolution) and Pyramid Tiles being loaded into the Coverage will have a corresponding entry into this table.
This one is a geometry table (Tile BBOX) and is supported by a Spatial Index.
<coverage_name>_tile_data all odd and even BLOB encoded Tile pixels will be stored into this table.
The main rationale suggesting to adopt a separate table for storing BLOB encoded data is in that this way the heavy BLOBs have their own distinct storage space; and this allows many internal SQL queries to be executed in a noticeably faster way.
(alternative and mutually exclusive layouts)
<coverage_name>_levels This configuration is adopted by any Coverage declaring the strictResolution or permissiveResolution Policy Option.
It's compatible with both Section-based and Monolithic Pyramid.
<coverage_name>_section_levels This second configuration is adopted by any Coverage declaring the mixedResolution Policy Option.
It's only compatible with a Pyramid of the Section-based type, and completely forbids building a Monolithic Pyramid.

Entity-Relation diagram: strictResolution / permissiveResolution

Entity-Relation 1

Entity-Relation diagram: mixedResolutions

Entity-Relation 2

Back to RasterLite2 doc index