#ifndef DOXYGEN_SKIP
/* $Id: vrt_tutorial.dox 15819 2008-11-27 16:32:15Z warmerdam $ */
#endif /* DOXYGEN_SKIP */
/*!
\page gdal_vrttut GDAL Virtual Format Tutorial
\section gdal_vrttut_intro Introduction
The VRT driver is a format driver for GDAL that allows a virtual GDAL dataset
to be composed from other GDAL datasets with repositioning, and algorithms
potentially applied as well as various kinds of metadata altered or added.
VRT descriptions of datasets can be saved in an XML format normally given the
extension .vrt.
An example of a simple .vrt file referring to a 512x512 dataset with one band
loaded from utm.tif might look like this:
\code
440720.0, 60.0, 0.0, 3751320.0, 0.0, -60.0
Gray
utm.tif
1
\endcode
Many aspects of the VRT file are a direct XML encoding of the
GDAL Data Model which should be reviewed
for understanding of the semantics of various elements.
VRT files can be produced by translating to VRT format. The resulting file can
then be edited to modify mappings, add metadata or other purposes. VRT files
can also be produced programmatically by various means.
This tutorial will cover the .vrt file format (suitable for users editing
.vrt files), and how .vrt files may be created and manipulated programmatically
for developers.
\section gdal_vrttut_format .vrt Format
Virtual files stored on disk are kept in an XML format with the following
elements.
-
VRTDataset: This is the root element for the whole GDAL dataset.
It must have the attributes rasterXSize and rasterYSize describing the width
and height of the dataset in pixels. It may have SRS, GeoTransform,
GCPList, Metadata, and VRTRasterBand subelements.
\code
\endcode
- SRS: This element contains the spatial reference system (coordinate
system) in OGC WKT format. Note that this must be appropriately escaped for
XML, so items like quotes will have the ampersand escape sequences substituted.
As as well WKT, and valid input to the SetFromUserInput() method (such as well
known GEOGCS names, and PROJ.4 format) is also allowed in the SRS element.
\code
PROJCS["NAD27 / UTM zone 11N",GEOGCS["NAD27",DATUM["North_American_Datum_1927",SPHEROID["Clarke 1866",6378206.4,294.9786982139006,AUTHORITY["EPSG","7008"]],AUTHORITY["EPSG","6267"]],PRIMEM["Greenwich",0],UNIT["degree",0.0174532925199433],AUTHORITY["EPSG","4267"]],PROJECTION["Transverse_Mercator"],PARAMETER["latitude_of_origin",0],PARAMETER["central_meridian",-117],PARAMETER["scale_factor",0.9996],PARAMETER["false_easting",500000],PARAMETER["false_northing",0],UNIT["metre",1,AUTHORITY["EPSG","9001"]],AUTHORITY["EPSG","26711"]]
\endcode
- GeoTransform: This element contains a six value affine
geotransformation for the dataset, mapping between pixel/line coordinates
and georeferenced coordinates.
\code
440720.0, 60, 0.0, 3751320.0, 0.0, -60.0
\endcode
- Metadata: This element contains a list of metadata name/value
pairs associated with the VRTDataset as a whole, or a VRTRasterBand. It has
(metadata item) subelements which have a "key" attribute and the value
as the data of the element.
\code
Metadata value
\endcode
- VRTRasterBand: This represents one band of a dataset. It will
have a ataType attribute with the type of the pixel data associated with
this band (use names Byte, UInt16, Int16, UInt32, Int32, Float32, Float64,
CInt16, CInt32, CFloat32 or CFloat64) and the band this element represents
(1 based). This element may have Metadata, ColorInterp, NoDataValue,
ColorTable, and Description subelements as well as the various kinds of
source elements such as SimpleSource. A raster band may have many "sources"
indicating where the actual raster data should be fetched from, and how it
should be mapped into the raster bands pixel space.
- ColorInterp: The data of this element should be the name of
a color interpretation type. One of Gray, Palette, Red, Green, Blue, Alpha,
Hue, Saturation, Lightness, Cyan, Magenta, Yellow, Black, or Unknown.
\code
Gray:
\endcode
- NoDataValue: If this element exists a raster band has a
nodata value associated with, of the value given as data in the element.
\code
-100.0
\endcode
- ColorTable: This element is parent to a set of Entry
elements defining the entries in a color table. Currently only RGBA
color tables are supported with c1 being red, c2 being green, c3 being
blue and c4 being alpha. The entries are ordered and will be assumed
to start from color table entry 0.
\code
\endcode
- Description: This element contains the optional description
of a raster band as it's text value.
\code
Crop Classification Layer
\endcode
- UnitType: This optional element contains the vertical units for
elevation band data. One of "m" for meters or "ft" for feet. Default
assumption is meters.
\code
ft
\endcode
- Offset: This optional element contains the offset that should be
applied when computing "real" pixel values from scaled pixel values on
a raster band. The default is 0.0.
\code
0.0
\endcode
- Scale: This optional element contains the scale that should be
applied when computing "real" pixel values from scaled pixel values on a
raster band. The default is 1.0.
\code
0.0
\endcode
- CategoryNames: This optional element contains a list of Category
subelements with the names of the categories for classified raster band.
\code
Missing
Non-Crop
Wheat
Corn
Soybeans
\endcode
- SimpleSource: The SimpleSource indicates that raster data
should be read from a separate dataset, indicating the dataset, and band to be
read from, and how the data should map into this bands raster space.
The SimpleSource may have the SourceFilename, SourceBand, SrcRect, and DstRect
subelements. The SrcRect element will indicate what rectangle on the indicated
source file should be read, and the DstRect element indicates how that
rectangle of source data should be mapped into the VRTRasterBands space.
The relativeToVRT attribute on the SourceFilename indicates whether the
filename should be interpreted as relative to the .vrt file (value is 1)
or not relative to the .vrt file (value is 0). The default is 0.
Some characteristics of the source band can be specified in the optional
SourceProperties tag to enable the VRT driver to differ the opening of the source
dataset until it really needs to read data from it. This is particularly useful
when building VRTs with a big number of source datasets. The needed parameters are the
raster dimensions, the size of the blocks and the data type. If the SourceProperties
tag is not present, the source dataset will be opened at the same time as the VRT itself.
\code
utm.tif
1
\endcode
- AveragedSource: The AveragedSource is derived from the
SimpleSource and shares the same properties except that it uses an averaging
resampling instead of a nearest neighbour algorithm as in SimpleSource, when
the size of the destination rectangle is not the same as the size of the source
rectangle
- ComplexSource: The ComplexSource is derived from the
SimpleSource (so it shares the SourceFilename, SourceBand, SrcRect and
DestRect elements), but it provides support to rescale and offset
the range of the source values. Certain regions of the source
can be masked by specifying the NODATA value.
The ComplexSource supports adding a custom lookup table to transform
the source values to the destination. The LUT can be specified using
the following form:
\code
[src value 1]:[dest value 1],[src value 2]:[dest value 2],...
\endcode
The intermediary values are calculated using a linear interpolation
between the bounding destination values of the corresponding range.
The ComplexSource supports fetching a color component from a source raster
band that has a color table. The ColorTableComponent value is the index of the
color component to extract : 1 for the red band, 2 for the green band, 3 for
the blue band or 4 for the alpha band.
When transforming the source values the operations are executed
in the following order:
- Nodata masking
- Color table expansion
- Applying the scale ratio
- Applying the scale offset
- Table lookup
\code
utm.tif
1
0
1
1
0:0,2345.12:64,56789.5:128,2364753.02:255
0
\endcode
- KernelFilteredSource: This is a pixel source derived from the
Simple Source (so it shares the SourceFilename, SourceBand, SrcRect and
DestRect elements, but it also passes the data through a simple filtering
kernel specified with the Kernel element. The Kernel element should have
two child elements, Size and Coefs and optionally the boolean attribute
normalized (defaults to false=0). The size must always be an odd number,
and the Coefs must have Size * Size entries separated by spaces.
\code
/debian/home/warmerda/openev/utm.tif
1
3
0.11111111 0.11111111 0.11111111 0.11111111 0.11111111 0.11111111 0.11111111 0.11111111 0.11111111
\endcode
\section gdal_vrttut_vrt .vrt Descriptions for Raw Files
So far we have described how to derive new virtual datasets from existing
files supports by GDAL. However, it is also common to need to utilize
raw binary raster files for which the regular layout of the data is known
but for which no format specific driver exists. This can be accomplished
by writing a .vrt file describing the raw file.
For example, the following .vrt describes a raw raster file containing
floating point complex pixels in a file called l2p3hhsso.img. The
image data starts from the first byte (ImageOffset=0). The byte offset
between pixels is 8 (PixelOffset=8), the size of a CFloat32. The byte offset
from the start of one line to the start of the next is 9376 bytes
(LineOffset=9376) which is the width (1172) times the size of a pixel (8).
\code
l2p3hhsso.img
0
8
9376
MSB
\endcode
Some things to note are that the VRTRasterBand has a subClass specifier
of "VRTRawRasterBand". Also, the VRTRasterBand contains a number of
previously unseen elements but no "source" information. VRTRawRasterBands
may never have sources (ie. SimpleSource), but should contain the following
elements in addition to all the normal "metadata" elements previously
described which are still supported.
- SourceFilename: The name of the raw file containing the
data for this band. The relativeToVRT attribute can be used to indicate
if the SourceFilename is relative to the .vrt file (1) or not (0).
- ImageOffset: The offset in bytes to the beginning of the first
pixel of data of this image band. Defaults to zero.
- PixelOffset: The offset in bytes from the beginning of one
pixel and the next on the same line. In packed single band data this will
be the size of the dataType in bytes.
- LineOffset: The offset in bytes from the beginning of one
scanline of data and the next scanline of data. In packed single band
data this will be PixelOffset * rasterXSize.
- ByteOrder: Defines the byte order of the data on disk.
Either LSB (Least Significant Byte first) such as the natural byte order
on Intel x86 systems or MSB (Most Significant Byte first) such as the natural
byte order on Motorola or Sparc systems. Defaults to being the local machine
order.
A few other notes:
- The image data on disk is assumed to be of the same data type as
the band dataType of the VRTRawRasterBand.
- All the non-source attributes of the VRTRasterBand are supported,
including color tables, metadata, nodata values, and color interpretation.
- The VRTRawRasterBand supports in place update of the raster, whereas
the source based VRTRasterBand is always read-only.
- The OpenEV tool includes a File menu option to input parameters
describing a raw raster file in a GUI and create the corresponding .vrt
file.
- Multiple bands in the one .vrt file can come from the same raw file.
Just ensure that the ImageOffset, PixelOffset, and LineOffset definition
for each band is appropriate for the pixels of that particular band.
Another example, in this case a 400x300 RGB pixel interleaved image.
\code
Red
rgb.raw
0
3
1200
Green
rgb.raw
1
3
1200
Blue
rgb.raw
2
3
1200
\endcode
\section gdal_vrttut_creation Programatic Creation of VRT Datasets
The VRT driver supports several methods of creating VRT datasets. As of
GDAL 1.2.0 the vrtdataset.h include file should be installed with the core
GDAL include files, allowing direct access to the VRT classes. However,
even without that most capabilities remain available through standard GDAL
interfaces.
To create a VRT dataset that is a clone of an existing dataset use the
CreateCopy() method. For example to clone utm.tif into a wrk.vrt file in
C++ the following could be used:
\code
GDALDriver *poDriver = (GDALDriver *) GDALGetDriverByName( "VRT" );
GDALDataset *poSrcDS, *poVRTDS;
poSrcDS = (GDALDataset *) GDALOpenShared( "utm.tif", GA_ReadOnly );
poVRTDS =
poDriver->CreateCopy( "wrk.vrt", poSrcDS, FALSE, NULL, NULL, NULL );
delete poVRTDS;
delete poSrcDS;
\endcode
To create a virtual copy of a dataset with some attributes added or changed
such as metadata or coordinate system that are often hard to change on other
formats, you might do the following. In this case, the virtual dataset is
created "in memory" only by virtual of creating it with an empty filename, and
then used as a modified source to pass to a CreateCopy() written out in TIFF
format.
\code
poVRTDS = poDriver->CreateCopy( "", poSrcDS, FALSE, NULL, NULL, NULL );
poVRTDS->SetMetadataItem( "SourceAgency", "United States Geological Survey");
poVRTDS->SetMetadataItem( "SourceDate", "July 21, 2003" );
poVRTDS->GetRasterBand( 1 )->SetNoDataValue( -999.0 );
GDALDriver *poTIFFDriver = (GDALDriver *) GDALGetDriverByName( "GTiff" );
GDALDataset *poTiffDS;
poTiffDS =
poTIFFDriver->CreateCopy( "wrk.tif", poVRTDS, FALSE, NULL, NULL, NULL );
delete poTiffDS;
\endcode
In this example a virtual dataset is created with the Create() method, and
adding bands and sources programmatically, but still via the "generic" API.
A special attribute of VRT datasets is that sources can be added to the bands
by passing the XML describing the source into SetMetadata() on the special
domain target "new_vrt_sources". The domain target "vrt_sources" may also be
used, in which case any existing sources will be discarded before adding the
new ones. In this example we construct a simple averaging filter source
instead of using the simple source.
\code
// construct XML for simple 3x3 average filter kernel source.
const char *pszFilterSourceXML =
""
" utm.tif11"
" "
" 3"
" 0.111 0.111 0.111 0.111 0.111 0.111 0.111 0.111 0.111"
" "
"";
// Create the virtual dataset.
poVRTDS = poDriver->Create( "", 512, 512, 1, GDT_Byte, NULL );
poVRTDS->GetRasterBand(1)->SetMetadataItem("source_0",pszFilterSourceXML",
"new_vrt_sources");
\endcode
A more general form of this that will produce a 3x3 average filtered clone
of any input datasource might look like the following. In this case we
deliberately set the filtered datasource as in the "vrt_sources" domain
to override the SimpleSource created by the CreateCopy() method. The fact
that we used CreateCopy() ensures that all the other metadata, georeferencing
and so forth is preserved from the source dataset ... the only thing we are
changing is the data source for each band.
\code
int nBand;
GDALDriver *poDriver = (GDALDriver *) GDALGetDriverByName( "VRT" );
GDALDataset *poSrcDS, *poVRTDS;
poSrcDS = (GDALDataset *) GDALOpenShared( pszSourceFilename, GA_ReadOnly );
poVRTDS = poDriver->CreateCopy( "", poSrcDS, FALSE, NULL, NULL, NULL );
for( nBand = 1; nBand <= poVRTDS->GetRasterCount(); nBand++ )
{
char szFilterSourceXML[10000];
GDALRasterBand *poBand = poVRTDS->GetRasterBand( nBand );
sprintf( szFilterSourceXML,
""
" %s1%d"
" "
" 3"
" 0.111 0.111 0.111 0.111 0.111 0.111 0.111 0.111 0.111"
" "
"",
pszSourceFilename, nBand );
poBand->SetMetadataItem( "source_0", szFilterSourceXML, "vrt_sources" );
}
\endcode
Using Derived Bands
A specialized type of band is a 'derived' band which derives its pixel
information from its source bands. With this type of band you must also
specify a pixel function, which has the responsibility of generating the
output raster. Pixel functions are created by an application and then
registered with GDAL using a unique key.
Using derived bands you can create VRT datasets that manipulate bands on
the fly without having to create new band files on disk. For example, you
might want to generate a band using four source bands from a nine band input
dataset (x0, x3, x4, and x8):
\code
band_value = sqrt((x3*x3+x4*x4)/(x0*x8));
\endcode
You could write the pixel function to compute this value and then register
it with GDAL with the name "MyFirstFunction". Then, the following VRT XML
could be used to display this derived band:
\code
>
Magnitude
MyFirstFunction
nine_band.dat
1
nine_band.dat
4
nine_band.dat
5
nine_band.dat
9
\endcode
In addition to the subclass specification (VRTDerivedRasterBand) and
the PixelFunctionType value, there is another new parameter that can come
in handy: SourceTransferType. Typically the source rasters are obtained
using the data type of the derived band. There might be times,
however, when you want the pixel function to have access to
higher resolution source data than the data type being generated.
For example, you might have a derived band of type "Float", which takes
a single source of type "CFloat32" or "CFloat64", and returns the imaginary
portion. To accomplish this, set the SourceTransferType to "CFloat64".
Otherwise the source would be converted to "Float" prior to
calling the pixel function, and the imaginary portion would be lost.
\code
>
Magnitude
MyFirstFunction
"CFloat64"
...
\endcode
Writing Pixel Functions
To register this function with GDAL (prior to accessing any VRT datasets
with derived bands that use this function), an application calls
GDALAddDerivedBandPixelFunc with a key and a GDALDerivedPixelFunc:
\code
GDALAddDerivedBandPixelFunc("MyFirstFunction", TestFunction);
\endcode
A good time to do this is at the beginning of an application when the
GDAL drivers are registered.
GDALDerivedPixelFunc is defined with a signature similar to IRasterIO:
@param papoSources A pointer to packed rasters; one per source. The
datatype of all will be the same, specified in the eSrcType parameter.
@param nSources The number of source rasters.
@param pData The buffer into which the data should be read, or from which
it should be written. This buffer must contain at least nBufXSize *
nBufYSize words of type eBufType. It is organized in left to right,
top to bottom pixel order. Spacing is controlled by the nPixelSpace,
and nLineSpace parameters.
@param nBufXSize The width of the buffer image into which the desired
region is to be read, or from which it is to be written.
@param nBufYSize The height of the buffer image into which the desired
region is to be read, or from which it is to be written.
@param eSrcType The type of the pixel values in the papoSources raster
array.
@param eBufType The type of the pixel values that the pixel function must
generate in the pData data buffer.
@param nPixelSpace The byte offset from the start of one pixel value in
pData to the start of the next pixel value within a scanline. If
defaulted (0) the size of the datatype eBufType is used.
@param nLineSpace The byte offset from the start of one scanline in
pData to the start of the next.
@return CE_Failure on failure, otherwise CE_None.
\code
typedef CPLErr
(*GDALDerivedPixelFunc)(void **papoSources, int nSources, void *pData,
int nXSize, int nYSize,
GDALDataType eSrcType, GDALDataType eBufType,
int nPixelSpace, int nLineSpace);
\endcode
The following is an implementation of the pixel function:
\code
#include "gdal.h"
CPLErr TestFunction(void **papoSources, int nSources, void *pData,
int nXSize, int nYSize,
GDALDataType eSrcType, GDALDataType eBufType,
int nPixelSpace, int nLineSpace)
{
int ii, iLine, iCol;
double pix_val;
double x0, x3, x4, x8;
/* ---- Init ---- */
if (nSources != 4) return CE_Failure;
/* ---- Set pixels ---- */
for( iLine = 0; iLine < nYSize; iLine++ ) {
for( iCol = 0; iCol < nXSize; iCol++ ) {
ii = iLine * nXSize + iCol;
/* Source raster pixels may be obtained with SRCVAL macro */
x0 = SRCVAL(papoSources[0], eSrcType, ii);
x3 = SRCVAL(papoSources[1], eSrcType, ii);
x4 = SRCVAL(papoSources[2], eSrcType, ii);
x8 = SRCVAL(papoSources[3], eSrcType, ii);
pix_val = sqrt((x3*x3+x4*x4)/(x0*x8));
GDALCopyWords(&pix_val, GDT_Float64, 0,
((GByte *)pData) + nLineSpace * iLine +
iCol * nPixelSpace, eBufType, nPixelSpace, 1);
}
}
/* ---- Return success ---- */
return CE_None;
}
\endcode
\section gdal_vrttut_mt Multi-threading issues
When using VRT datasets in a multi-threading environment, you should be
careful to open the VRT dataset by the thread that will use it afterwards. The
reason for that is that the VRT dataset uses GDALOpenShared when opening the
underlying datasets. So, if you open twice the same VRT dataset by the same
thread, both VRT datasets will share the same handles to the underlying
datasets.
*/