.. post:: 2015-10-06
   :tags: vrt, gis, gdal, ogr, raster, vector, lut, sql, mosaic, reproject
   :category: gis
   :author: Tim Cera
   :location: Gainesville, FL
   :language: en

Virtual Format for GDAL/OGR
---------------------------
TLDR; I use VRTs for everything that I can.

http://www.gdal.org/drv_vrt.html

http://www.gdal.org/gdal_vrttut.html

VRT format is developed by the GDAL/OGR group and is an XML file format that
is used by the GDAL/OGR programs and libraries to transform source GIS datasets
on the fly.

VRT is not an anacronym (I couldn't find an anacronym anyway), but instead it
seems to be letters taken from the word ViRTual.  It can operate on either
rasters or vector datasets without identification in the extension which is
always '.vrt'.  You cannot mix raster and vector data sources in the same VRT
file.  The source datasets can be any format that the local install of GDAL/OGR
can read.

When necessary or expedient you can chain VRTs, for example setting up a raster
mosaicing VRT that uses other VRTs as source datasets.

Raster VRT Start
================
An easy way to setup a foundation VRT for raster datasets is to use the
"gdalbuildvrt" command line tool that is a part of any GDAL install.  The
"gdalbuildvrt" tool extracts necessary information from the raster source
datasets for inclusion into the VRT. Once setup you can add or modify the VRT
as needed.

Raster Look Up Table (LUT)
==========================
The complete VRT I use in this example is :download:`vrts_are_amazing/agwo_2000_03.vrt`

An operation unique to a raster VRT is the ability to display or work with
values from a look up table.  In my work this allows a single integer raster of
land cover codes or soil types to be the source for thousands of VRTs that
represent some characteristic of the source raster through a look up table.

For example, this look up table (incomplete and shown here as an example of the
structure)::

    ...
    <LUT>21:0.358,22:0.03825,23:0.03623,24:0.03221,25:0.02013,26:0.1005,
         ...
         981:0.06757,982:0.1101,983:0.104,984:0.09266,985:0.05831,
         ...
    </LUT>
    ...

will take this integer land cover raster:

    .. image:: vrts_are_amazing/lue.png

    .. image:: vrts_are_amazing/lue_legend.png
        :height: 200px

and make the following float raster of baseflow estimates for 2000-03 on the
fly.

    .. image:: vrts_are_amazing/agwo.png

You would also have to set the type of the VRT to accomodate the real numbers
in the look up table.::

    ...
    <VRTRasterBand dataType="Float32" band="1">
    ...

Vector SQL
==========
VRTs support SQL statements for vector formats that can access and make
calculations against any item in the source dataset.  There are two SQL
dialects.  The GDAL/OGR dialect is available no matter what, but the SQLite
dialect is only available if the GDAL/OGR libraries where compiled to support
it.  Go to http://www.gdal.org/ogr_sql.html for information on the OGR SQL, and
http://www.gdal.org/ogr_sql_sqlite.html for information on the SQLite dialect.
Also if Spatialite support is included when compiling the OGR libraries
additional spatial functions are available with the SQLite dialect.

An example vector VRT that is a mosaic of shapefiles along with development of
a unique ID is :download:`vrts_are_amazing/Final_wsheds_mosaic.vrt`

Vector Selection by Attributes
==============================
A nice use is to create subsets of the source dataset.::

    ...
    <SrcSQL>SELECT * FROM SOURCETABLE WHERE HUC8 = "03080101"</SrcSQL>
    ...

Calculation on Attributes of Vector Features
============================================
Convert "Depth_ft" to a sane system of measures.::

    ...
    <SrcSQL>SELECT Depth_ft*0.3048 AS Depth_m FROM SOURCETABLE</SrcSQL>
    ...

If Spatialite support was included in the OGR libraries you can even have the
SQL command calculate the area.::

    ...
    <SrcSQL dialect="SQLITE">SELECT *,ST_Area(GEOMETRY)*0.00024710439 AS Area_Acre FROM SOURCETABLE</SrcSQL>
    ...

Or dissolve polygons based on attribute values.::

    ...
    <SrcSQL dialect="SQLITE">SELECT ST_Union(GEOMETRY) WHERE HUC_12 LIKE '03080101%' GROUP BY SUBSTR(HUC_12,1,8)</SrcSQL>
    ...

Create VRT from a CSV File
==========================
This is a very simple point VRT using longitude and latitude and attributes
from a CSV file and projecting to the Florida Albers projection (EPSG:3087).::

    <OGRVRTDataSource>
      <OGRVRTWarpedLayer>
        <OGRVRTLayer name="NWIS_Daily_Values_flow_stations">
          <SrcDataSource relativeToVRT="1">NWIS_Daily_Values_flow_stations.csv</SrcDataSource>
          <GeometryType>wkbPoint</GeometryType>
          <LayerSRS>WGS84</LayerSRS>
          <GeometryField encoding="PointFromColumns" x="Longitude" y="Latitude"/>
        </OGRVRTLayer>
        <TargetSRS>EPSG:3087</TargetSRS>
      </OGRVRTWarpedLayer>
    </OGRVRTDataSource>

That is the entire file.  I think that is really cool.

Vector Layer Creation From Other Layers Using SQL
=================================================
The following VRT will create a new polygon layer called "joined" using
Spatiallite ST_INTERSECTS from the other layers within the VRT.  It also
creates a new attribute "total_capacity" which is the total number of beds in
all of the nursing homes in each borough.  Note that this VRT refers to itself
("input.vrt") it order to access the data in the other layers.::

    <OGRVRTDataSource>
        <OGRVRTLayer name="boroughs">
            <SrcDataSource>nybb.shp</SrcDataSource>
            <SrcLayer>nybb</SrcLayer>
        </OGRVRTLayer>
        <OGRVRTLayer name="nursinghomes">
            <SrcDataSource>OEM_NursingHomes_001.shp</SrcDataSource>
            <SrcLayer>OEM_NursingHomes_001</SrcLayer>
        </OGRVRTLayer>
        <OGRVRTLayer name="joined">
            <SrcDataSource>input.vrt</SrcDataSource>
            <SrcSQL dialect="SQLITE">
                SELECT b.BoroName, sum(n.Capacity) as total_capacity from
                boroughs b, nursinghomes n WHERE ST_INTERSECTS(b.geometry,
                n.geometry) group by b.BoroName
            </SrcSQL>
        </OGRVRTLayer>
    </OGRVRTDataSource>

Reprojection
============

You can reproject both raster and vector source datasets.::

    ...
    <SourceSRS>EPSG:3747</TargetSRS>
    ...
    <TargetSRS>EPSG:3087</TargetSRS>
    ...

The SourceSRS and TargetSRS codes come from http://spatialreference.org, but
also can be defined completely with OGC Well Known Text (for example
http://spatialreference.org/ref/epsg/3747/ogcwkt/).

Mosaicing
=========

You can mosaic multiple raster or vector source datasets.  The easiest way to
do this for raster data is to use "gdalbuildvrt" command line tool.

The file :download:`vrts_are_amazing/Final_wsheds_mosaic.vrt` has an example of
how to mosaic vector datasets.