EVOLUTION-MANAGER
Edit File: gdal_vrttut.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> <meta http-equiv="X-UA-Compatible" content="IE=9"/> <meta name="generator" content="Doxygen 1.8.5"/> <title>My Project: GDAL Virtual Format Tutorial</title> <link href="tabs.css" rel="stylesheet" type="text/css"/> <script type="text/javascript" src="jquery.js"></script> <script type="text/javascript" src="dynsections.js"></script> <link href="search/search.css" rel="stylesheet" type="text/css"/> <script type="text/javascript" src="search/search.js"></script> <script type="text/javascript"> $(document).ready(function() { searchBox.OnSelectItem(0); }); </script> <link href="doxygen.css" rel="stylesheet" type="text/css" /> </head> <body> <div id="top"><!-- do not remove this div, it is closed by doxygen! --> <div id="titlearea"> <table cellspacing="0" cellpadding="0"> <tbody> <tr style="height: 56px;"> <td style="padding-left: 0.5em;"> <div id="projectname">My Project </div> </td> </tr> </tbody> </table> </div> <!-- end header part --> <!-- Generated by Doxygen 1.8.5 --> <script type="text/javascript"> var searchBox = new SearchBox("searchBox", "search",false,'Search'); </script> <div id="navrow1" class="tabs"> <ul class="tablist"> <li><a href="index.html"><span>Main Page</span></a></li> <li class="current"><a href="pages.html"><span>Related Pages</span></a></li> <li><a href="annotated.html"><span>Classes</span></a></li> <li><a href="files.html"><span>Files</span></a></li> <li> <div id="MSearchBox" class="MSearchBoxInactive"> <span class="left"> <img id="MSearchSelect" src="search/mag_sel.png" onmouseover="return searchBox.OnSearchSelectShow()" onmouseout="return searchBox.OnSearchSelectHide()" alt=""/> <input type="text" id="MSearchField" value="Search" accesskey="S" onfocus="searchBox.OnSearchFieldFocus(true)" onblur="searchBox.OnSearchFieldFocus(false)" onkeyup="searchBox.OnSearchFieldChange(event)"/> </span><span class="right"> <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a> </span> </div> </li> </ul> </div> <!-- window showing the filter options --> <div id="MSearchSelectWindow" onmouseover="return searchBox.OnSearchSelectShow()" onmouseout="return searchBox.OnSearchSelectHide()" onkeydown="return searchBox.OnSearchSelectKey(event)"> <a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Pages</a></div> <!-- iframe showing the search results (closed by default) --> <div id="MSearchResultsWindow"> <iframe src="javascript:void(0)" frameborder="0" name="MSearchResults" id="MSearchResults"> </iframe> </div> </div><!-- top --> <div class="header"> <div class="headertitle"> <div class="title">GDAL Virtual Format Tutorial </div> </div> </div><!--header--> <div class="contents"> <div class="textblock"><h1><a class="anchor" id="gdal_vrttut_intro"></a> Introduction</h1> <p>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.</p> <p>An example of a simple .vrt file referring to a 512x512 dataset with one band loaded from utm.tif might look like this:</p> <div class="fragment"><div class="line"><<a class="code" href="classVRTDataset.html">VRTDataset</a> rasterXSize=<span class="stringliteral">"512"</span> rasterYSize=<span class="stringliteral">"512"</span>></div> <div class="line"> <GeoTransform>440720.0, 60.0, 0.0, 3751320.0, 0.0, -60.0</GeoTransform></div> <div class="line"> <<a class="code" href="classVRTRasterBand.html">VRTRasterBand</a> dataType=<span class="stringliteral">"Byte"</span> band=<span class="stringliteral">"1"</span>></div> <div class="line"> <ColorInterp>Gray</ColorInterp></div> <div class="line"> <SimpleSource></div> <div class="line"> <SourceFilename relativeToVRT=<span class="stringliteral">"1"</span>>utm.tif</SourceFilename></div> <div class="line"> <SourceBand>1</SourceBand></div> <div class="line"> <SrcRect xOff=<span class="stringliteral">"0"</span> yOff=<span class="stringliteral">"0"</span> xSize=<span class="stringliteral">"512"</span> ySize=<span class="stringliteral">"512"</span>/></div> <div class="line"> <DstRect xOff=<span class="stringliteral">"0"</span> yOff=<span class="stringliteral">"0"</span> xSize=<span class="stringliteral">"512"</span> ySize=<span class="stringliteral">"512"</span>/></div> <div class="line"> </SimpleSource></div> <div class="line"> </<a class="code" href="classVRTRasterBand.html">VRTRasterBand</a>></div> <div class="line"></<a class="code" href="classVRTDataset.html">VRTDataset</a>></div> </div><!-- fragment --><p>Many aspects of the VRT file are a direct XML encoding of the <a href="gdal_datamodel.html">GDAL Data Model</a> which should be reviewed for understanding of the semantics of various elements.</p> <p>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.</p> <p>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.</p> <h1><a class="anchor" id="gdal_vrttut_format"></a> .vrt Format</h1> <p>Virtual files stored on disk are kept in an XML format with the following elements.</p> <p><b><a class="el" href="classVRTDataset.html">VRTDataset</a></b>: 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, MaskBand and <a class="el" href="classVRTRasterBand.html">VRTRasterBand</a> subelements.</p> <div class="fragment"><div class="line"><<a class="code" href="classVRTDataset.html">VRTDataset</a> rasterXSize=<span class="stringliteral">"512"</span> rasterYSize=<span class="stringliteral">"512"</span>></div> </div><!-- fragment --><p>The allowed subelements for <a class="el" href="classVRTDataset.html">VRTDataset</a> are :</p> <ul> <li> <p class="startli"><b>SRS</b>: 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.</p> <div class="fragment"><div class="line"><SRS>PROJCS[&quot;NAD27 / UTM zone 11N&quot;,GEOGCS[&quot;NAD27&quot;,DATUM[&quot;North_American_Datum_1927&quot;,SPHEROID[&quot;Clarke 1866&quot;,6378206.4,294.9786982139006,AUTHORITY[&quot;EPSG&quot;,&quot;7008&quot;]],AUTHORITY[&quot;EPSG&quot;,&quot;6267&quot;]],PRIMEM[&quot;Greenwich&quot;,0],UNIT[&quot;degree&quot;,0.0174532925199433],AUTHORITY[&quot;EPSG&quot;,&quot;4267&quot;]],PROJECTION[&quot;Transverse_Mercator&quot;],PARAMETER[&quot;latitude_of_origin&quot;,0],PARAMETER[&quot;central_meridian&quot;,-117],PARAMETER[&quot;scale_factor&quot;,0.9996],PARAMETER[&quot;false_easting&quot;,500000],PARAMETER[&quot;false_northing&quot;,0],UNIT[&quot;metre&quot;,1,AUTHORITY[&quot;EPSG&quot;,&quot;9001&quot;]],AUTHORITY[&quot;EPSG&quot;,&quot;26711&quot;]]</SRS></div> </div><!-- fragment --> <p class="endli"></p> </li> <li> <p class="startli"><b>GeoTransform</b>: This element contains a six value affine geotransformation for the dataset, mapping between pixel/line coordinates and georeferenced coordinates.</p> <p></p> <div class="fragment"><div class="line"><GeoTransform>440720.0, 60, 0.0, 3751320.0, 0.0, -60.0</GeoTransform></div> </div><!-- fragment --> <p class="endli"></p> </li> <li> <p class="startli"><b>GCPList</b>: This element contains a list of Ground Control Points for the dataset, mapping between pixel/line coordinates and georeferenced coordinates. The Projection attribute should contain the SRS of the georeferenced coordinates in the same format as the SRS element.</p> <p></p> <div class="fragment"><div class="line"><GCPList Projection=<span class="stringliteral">"EPSG:4326"</span>></div> <div class="line"> <GCP Id=<span class="stringliteral">"1"</span> Info=<span class="stringliteral">"a"</span> Pixel=<span class="stringliteral">"0.5"</span> Line=<span class="stringliteral">"0.5"</span> X=<span class="stringliteral">"0.0"</span> Y=<span class="stringliteral">"0.0"</span> Z=<span class="stringliteral">"0.0"</span> /></div> <div class="line"> <GCP Id=<span class="stringliteral">"2"</span> Info=<span class="stringliteral">"b"</span> Pixel=<span class="stringliteral">"13.5"</span> Line=<span class="stringliteral">"23.5"</span> X=<span class="stringliteral">"1.0"</span> Y=<span class="stringliteral">"2.0"</span> Z=<span class="stringliteral">"0.0"</span> /></div> <div class="line"></GCPList></div> </div><!-- fragment --> <p class="endli"></p> </li> <li> <p class="startli"><b>Metadata</b>: This element contains a list of metadata name/value pairs associated with the <a class="el" href="classVRTDataset.html">VRTDataset</a> as a whole, or a <a class="el" href="classVRTRasterBand.html">VRTRasterBand</a>. It has <MDI> (metadata item) subelements which have a "key" attribute and the value as the data of the element.</p> <div class="fragment"><div class="line"><Metadata></div> <div class="line"> <MDI key=<span class="stringliteral">"md_key"</span>>Metadata value</MDI></div> <div class="line"></Metadata></div> </div><!-- fragment --> <p class="endli"></p> </li> <li> <p class="startli"><b>MaskBand</b>: (GDAL >= 1.8.0) This element represents a mask band that is shared between all bands on the dataset (see GMF_PER_DATASET in RFC 15). It must contain a single <a class="el" href="classVRTRasterBand.html">VRTRasterBand</a> child element, that is the description of the mask band itself.</p> <div class="fragment"><div class="line"><MaskBand></div> <div class="line"> <<a class="code" href="classVRTRasterBand.html">VRTRasterBand</a> dataType=<span class="stringliteral">"Byte"</span>></div> <div class="line"> <SimpleSource></div> <div class="line"> <SourceFilename relativeToVRT=<span class="stringliteral">"1"</span>>utm.tif</SourceFilename></div> <div class="line"> <SourceBand>mask,1</SourceBand></div> <div class="line"> <SrcRect xOff=<span class="stringliteral">"0"</span> yOff=<span class="stringliteral">"0"</span> xSize=<span class="stringliteral">"512"</span> ySize=<span class="stringliteral">"512"</span>/></div> <div class="line"> <DstRect xOff=<span class="stringliteral">"0"</span> yOff=<span class="stringliteral">"0"</span> xSize=<span class="stringliteral">"512"</span> ySize=<span class="stringliteral">"512"</span>/></div> <div class="line"> </SimpleSource></div> <div class="line"> </<a class="code" href="classVRTRasterBand.html">VRTRasterBand</a>></div> <div class="line"></MaskBand></div> </div><!-- fragment --><p></p> <p class="endli"></p> </li> <li> <p class="startli"><b><a class="el" href="classVRTRasterBand.html">VRTRasterBand</a></b>: This represents one band of a dataset. It will have a dataType 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, HideNoDataValue, ColorTable, Description and MaskBand subelements as well as the various kinds of source elements such as SimpleSource, ComplexSource, etc. 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.</p> <p></p> <p>The allowed subelements for <a class="el" href="classVRTRasterBand.html">VRTRasterBand</a> are :</p> <ul> <li> <p class="startli"><b>ColorInterp</b>: 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.</p> <p></p> <div class="fragment"><div class="line"><ColorInterp>Gray</ColorInterp>: </div> </div><!-- fragment --> <p class="endli"></p> </li> <li> <p class="startli"><b>NoDataValue</b>: If this element exists a raster band has a nodata value associated with, of the value given as data in the element.</p> <div class="fragment"><div class="line"><NoDataValue>-100.0</NoDataValue></div> </div><!-- fragment --> <p class="endli"></p> </li> <li> <p class="startli"><b>HideNoDataValue</b>: If this value is 1, the nodata value will not be reported. Essentially, the caller will not be aware of a nodata pixel when it reads one. Any datasets copied/translated from this will not have a nodata value. This is useful when you want to specify a fixed background value for the dataset. The background will be the value specified by the NoDataValue element.</p> <p>Default value is 0 when this element is absent.</p> <div class="fragment"><div class="line"><HideNoDataValue>1</HideNoDataValue></div> </div><!-- fragment --> <p class="endli"></p> </li> <li> <p class="startli"><b>ColorTable</b>: 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.</p> <div class="fragment"><div class="line"><ColorTable></div> <div class="line"> <Entry c1=<span class="stringliteral">"0"</span> c2=<span class="stringliteral">"0"</span> c3=<span class="stringliteral">"0"</span> c4=<span class="stringliteral">"255"</span>/></div> <div class="line"> <Entry c1=<span class="stringliteral">"145"</span> c2=<span class="stringliteral">"78"</span> c3=<span class="stringliteral">"224"</span> c4=<span class="stringliteral">"255"</span>/></div> <div class="line"></ColorTable></div> </div><!-- fragment --> <p class="endli"></p> </li> <li> <p class="startli"><b>Description</b>: This element contains the optional description of a raster band as it's text value.</p> <div class="fragment"><div class="line"><Description>Crop Classification Layer</Description></div> </div><!-- fragment --> <p class="endli"></p> </li> <li> <p class="startli"><b>UnitType</b>: This optional element contains the vertical units for elevation band data. One of "m" for meters or "ft" for feet. Default assumption is meters.</p> <p></p> <div class="fragment"><div class="line"><UnitType>ft</UnitType></div> </div><!-- fragment --> <p class="endli"></p> </li> <li> <p class="startli"><b>Offset</b>: 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.</p> <p></p> <div class="fragment"><div class="line"><Offset>0.0</Offset></div> </div><!-- fragment --> <p class="endli"></p> </li> <li> <p class="startli"><b>Scale</b>: 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.</p> <p></p> <div class="fragment"><div class="line"><Scale>0.0</Scale></div> </div><!-- fragment --> <p class="endli"></p> </li> <li> <p class="startli"><b>Overview</b>: This optional element describes one overview level for the band. It should have a child SourceFilename and SourceBand element. The SourceFilename may have a relativeToVRT boolean attribute. Multiple elements may be used to describe multiple overviews. </p> <p></p> <div class="fragment"><div class="line"><Overview></div> <div class="line"> <SourceFilename relativeToVRT=<span class="stringliteral">"1"</span>>yellowstone_2.1.ntf.r2</SourceFilename></div> <div class="line"> <SourceBand>1</SourceBand></div> <div class="line"></Overview></div> </div><!-- fragment --> <p class="endli"></p> </li> <li> <p class="startli"><b>CategoryNames</b>: This optional element contains a list of Category subelements with the names of the categories for classified raster band. </p> <p></p> <div class="fragment"><div class="line"><CategoryNames></div> <div class="line"> <Category>Missing</Category></div> <div class="line"> <Category>Non-Crop</Category></div> <div class="line"> <Category>Wheat</Category></div> <div class="line"> <Category>Corn</Category></div> <div class="line"> <Category>Soybeans</Category></div> <div class="line"></CategoryNames></div> </div><!-- fragment --> <p class="endli"></p> </li> <li> <p class="startli"><b>SimpleSource</b>: 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.</p> <p>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.</p> <p>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.</p> <p>Starting with GDAL 1.8.0, the content of the SourceBand subelement can refer to a mask band. For example mask,1 means the the mask band of the first band of the source.</p> <div class="fragment"><div class="line"><SimpleSource></div> <div class="line"> <SourceFilename relativeToVRT=<span class="stringliteral">"1"</span>>utm.tif</SourceFilename></div> <div class="line"> <SourceBand>1</SourceBand></div> <div class="line"> <SourceProperties RasterXSize=<span class="stringliteral">"512"</span> RasterYSize=<span class="stringliteral">"512"</span> DataType=<span class="stringliteral">"Byte"</span> BlockXSize=<span class="stringliteral">"128"</span> BlockYSize=<span class="stringliteral">"128"</span>/></div> <div class="line"> <SrcRect xOff=<span class="stringliteral">"0"</span> yOff=<span class="stringliteral">"0"</span> xSize=<span class="stringliteral">"512"</span> ySize=<span class="stringliteral">"512"</span>/></div> <div class="line"> <DstRect xOff=<span class="stringliteral">"0"</span> yOff=<span class="stringliteral">"0"</span> xSize=<span class="stringliteral">"512"</span> ySize=<span class="stringliteral">"512"</span>/></div> <div class="line"></SimpleSource></div> </div><!-- fragment --> <p class="endli"></p> </li> <li> <p class="startli"><b>AveragedSource</b>: 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</p> <p class="endli"></p> </li> <li> <p class="startli"><b>ComplexSource</b>: 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.</p> <p>Starting with GDAL 1.11, alternatively to linear scaling, non-linear scaling using a power function can be used by specifying the Exponent, SrcMin, SrcMax, DstMin and DstMax elements. If SrcMin and SrcMax are not specified, they are computed from the source minimum and maximum value (which might require analyzing the whole source dataset). Exponent must be positive. (Those 5 values can be set with the -exponent and -scale options of gdal_translate.)</p> <p>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:</p> <div class="fragment"><div class="line"><LUT>[src value 1]:[dest value 1],[src value 2]:[dest value 2],...</LUT></div> </div><!-- fragment --><p>The intermediary values are calculated using a linear interpolation between the bounding destination values of the corresponding range.</p> <p>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.</p> <p>When transforming the source values the operations are executed in the following order:</p> <ol> <li> Nodata masking </li> <li> Color table expansion </li> <li> For linear scaling, applying the scale ratio, then scale offset </li> <li> For non-linear scaling, apply (DstMax-DstMin) * pow( (SrcValue-SrcMin) / (SrcMax-SrcMin), Exponent) + DstMin </li> <li> Table lookup </li> </ol> <div class="fragment"><div class="line"><ComplexSource></div> <div class="line"> <SourceFilename relativeToVRT=<span class="stringliteral">"1"</span>>utm.tif</SourceFilename></div> <div class="line"> <SourceBand>1</SourceBand></div> <div class="line"> <ScaleOffset>0</ScaleOffset></div> <div class="line"> <ScaleRatio>1</ScaleRatio></div> <div class="line"> <ColorTableComponent>1</ColorTableComponent></div> <div class="line"> <LUT>0:0,2345.12:64,56789.5:128,2364753.02:255</LUT></div> <div class="line"> <NODATA>0</NODATA></div> <div class="line"> <SrcRect xOff=<span class="stringliteral">"0"</span> yOff=<span class="stringliteral">"0"</span> xSize=<span class="stringliteral">"512"</span> ySize=<span class="stringliteral">"512"</span>/></div> <div class="line"> <DstRect xOff=<span class="stringliteral">"0"</span> yOff=<span class="stringliteral">"0"</span> xSize=<span class="stringliteral">"512"</span> ySize=<span class="stringliteral">"512"</span>/></div> <div class="line"></ComplexSource></div> </div><!-- fragment --><p>Non-linear scaling:</p> <div class="fragment"><div class="line"><ComplexSource></div> <div class="line"> <SourceFilename relativeToVRT=<span class="stringliteral">"1"</span>>16bit.tif</SourceFilename></div> <div class="line"> <SourceBand>1</SourceBand></div> <div class="line"> <Exponent>0.75</Exponent></div> <div class="line"> <SrcMin>0</SrcMin></div> <div class="line"> <SrcMax>65535</SrcMax></div> <div class="line"> <DstMin>0</DstMin></div> <div class="line"> <DstMax>255</DstMax></div> <div class="line"> <SrcRect xOff=<span class="stringliteral">"0"</span> yOff=<span class="stringliteral">"0"</span> xSize=<span class="stringliteral">"512"</span> ySize=<span class="stringliteral">"512"</span>/></div> <div class="line"> <DstRect xOff=<span class="stringliteral">"0"</span> yOff=<span class="stringliteral">"0"</span> xSize=<span class="stringliteral">"512"</span> ySize=<span class="stringliteral">"512"</span>/></div> <div class="line"></ComplexSource></div> </div><!-- fragment --><p></p> <p class="endli"></p> </li> <li> <p class="startli"><b>KernelFilteredSource</b>: 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.</p> <div class="fragment"><div class="line"><KernelFilteredSource></div> <div class="line"> <SourceFilename>/debian/home/warmerda/openev/utm.tif</SourceFilename></div> <div class="line"> <SourceBand>1</SourceBand></div> <div class="line"> <Kernel normalized=<span class="stringliteral">"1"</span>></div> <div class="line"> <Size>3</Size></div> <div class="line"> <Coefs>0.11111111 0.11111111 0.11111111 0.11111111 0.11111111 0.11111111 0.11111111 0.11111111 0.11111111</Coefs></div> <div class="line"> </Kernel></div> <div class="line"></KernelFilteredSource></div> </div><!-- fragment --> <p class="endli"></p> </li> <li> <p class="startli"><b>MaskBand</b>: (GDAL >= 1.8.0) This element represents a mask band that is specific to the <a class="el" href="classVRTRasterBand.html">VRTRasterBand</a> it contains. It must contain a single <a class="el" href="classVRTRasterBand.html">VRTRasterBand</a> child element, that is the description of the mask band itself. </p> <p class="endli"></p> </li> </ul> <p class="endli"></p> </li> </ul> <h1><a class="anchor" id="gdal_vrttut_vrt"></a> .vrt Descriptions for Raw Files</h1> <p>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.</p> <p>For example, the following .vrt describes a raw raster file containing floating point complex pixels in a file called <em>l2p3hhsso.img</em>. 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).</p> <div class="fragment"><div class="line"><<a class="code" href="classVRTDataset.html">VRTDataset</a> rasterXSize=<span class="stringliteral">"1172"</span> rasterYSize=<span class="stringliteral">"1864"</span>></div> <div class="line"> <<a class="code" href="classVRTRasterBand.html">VRTRasterBand</a> dataType=<span class="stringliteral">"CFloat32"</span> band=<span class="stringliteral">"1"</span> subClass=<span class="stringliteral">"VRTRawRasterBand"</span>></div> <div class="line"> <SourceFilename relativetoVRT=<span class="stringliteral">"1"</span>>l2p3hhsso.img</SourceFilename></div> <div class="line"> <ImageOffset>0</ImageOffset></div> <div class="line"> <PixelOffset>8</PixelOffset></div> <div class="line"> <LineOffset>9376</LineOffset></div> <div class="line"> <ByteOrder>MSB</ByteOrder></div> <div class="line"> </<a class="code" href="classVRTRasterBand.html">VRTRasterBand</a>></div> <div class="line"></<a class="code" href="classVRTDataset.html">VRTDataset</a>></div> </div><!-- fragment --><p>Some things to note are that the <a class="el" href="classVRTRasterBand.html">VRTRasterBand</a> has a subClass specifier of "VRTRawRasterBand". Also, the <a class="el" href="classVRTRawRasterBand.html">VRTRawRasterBand</a> 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.</p> <ul> <li> <p class="startli"><b>SourceFilename</b>: 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).</p> <p class="endli"></p> </li> <li> <p class="startli"><b>ImageOffset</b>: The offset in bytes to the beginning of the first pixel of data of this image band. Defaults to zero.</p> <p class="endli"></p> </li> <li> <p class="startli"><b>PixelOffset</b>: 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 <b>dataType</b> in bytes.</p> <p class="endli"></p> </li> <li> <p class="startli"><b>LineOffset</b>: 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.</p> <p class="endli"></p> </li> <li> <p class="startli"><b>ByteOrder</b>: 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.</p> <p class="endli"></p> </li> </ul> <p>A few other notes:</p> <ul> <li> <p class="startli">The image data on disk is assumed to be of the same data type as the band <b>dataType</b> of the <a class="el" href="classVRTRawRasterBand.html">VRTRawRasterBand</a>.</p> <p class="endli"></p> </li> <li> <p class="startli">All the non-source attributes of the <a class="el" href="classVRTRasterBand.html">VRTRasterBand</a> are supported, including color tables, metadata, nodata values, and color interpretation.</p> <p class="endli"></p> </li> <li> <p class="startli">The <a class="el" href="classVRTRawRasterBand.html">VRTRawRasterBand</a> supports in place update of the raster, whereas the source based <a class="el" href="classVRTRasterBand.html">VRTRasterBand</a> is always read-only.</p> <p class="endli"></p> </li> <li> <p class="startli">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.</p> <p class="endli"></p> </li> <li> <p class="startli">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.</p> <p class="endli"></p> </li> </ul> <p>Another example, in this case a 400x300 RGB pixel interleaved image.</p> <div class="fragment"><div class="line"><<a class="code" href="classVRTDataset.html">VRTDataset</a> rasterXSize=<span class="stringliteral">"400"</span> rasterYSize=<span class="stringliteral">"300"</span>></div> <div class="line"> <<a class="code" href="classVRTRasterBand.html">VRTRasterBand</a> dataType=<span class="stringliteral">"Byte"</span> band=<span class="stringliteral">"1"</span> subClass=<span class="stringliteral">"VRTRawRasterBand"</span>></div> <div class="line"> <ColorInterp>Red</ColorInterp></div> <div class="line"> <SourceFilename relativetoVRT=<span class="stringliteral">"1"</span>>rgb.raw</SourceFilename></div> <div class="line"> <ImageOffset>0</ImageOffset></div> <div class="line"> <PixelOffset>3</PixelOffset></div> <div class="line"> <LineOffset>1200</LineOffset></div> <div class="line"> </<a class="code" href="classVRTRasterBand.html">VRTRasterBand</a>></div> <div class="line"> <<a class="code" href="classVRTRasterBand.html">VRTRasterBand</a> dataType=<span class="stringliteral">"Byte"</span> band=<span class="stringliteral">"2"</span> subClass=<span class="stringliteral">"VRTRawRasterBand"</span>></div> <div class="line"> <ColorInterp>Green</ColorInterp></div> <div class="line"> <SourceFilename relativetoVRT=<span class="stringliteral">"1"</span>>rgb.raw</SourceFilename></div> <div class="line"> <ImageOffset>1</ImageOffset></div> <div class="line"> <PixelOffset>3</PixelOffset></div> <div class="line"> <LineOffset>1200</LineOffset></div> <div class="line"> </<a class="code" href="classVRTRasterBand.html">VRTRasterBand</a>></div> <div class="line"> <<a class="code" href="classVRTRasterBand.html">VRTRasterBand</a> dataType=<span class="stringliteral">"Byte"</span> band=<span class="stringliteral">"3"</span> subClass=<span class="stringliteral">"VRTRawRasterBand"</span>></div> <div class="line"> <ColorInterp>Blue</ColorInterp></div> <div class="line"> <SourceFilename relativetoVRT=<span class="stringliteral">"1"</span>>rgb.raw</SourceFilename></div> <div class="line"> <ImageOffset>2</ImageOffset></div> <div class="line"> <PixelOffset>3</PixelOffset></div> <div class="line"> <LineOffset>1200</LineOffset></div> <div class="line"> </<a class="code" href="classVRTRasterBand.html">VRTRasterBand</a>></div> <div class="line"></<a class="code" href="classVRTDataset.html">VRTDataset</a>></div> </div><!-- fragment --><h1><a class="anchor" id="gdal_vrttut_creation"></a> Programatic Creation of VRT Datasets</h1> <p>The VRT driver supports several methods of creating VRT datasets. As of GDAL 1.2.0 the <a class="el" href="vrtdataset_8h_source.html">vrtdataset.h</a> 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.</p> <p>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:</p> <div class="fragment"><div class="line">GDALDriver *poDriver = (GDALDriver *) GDALGetDriverByName( <span class="stringliteral">"VRT"</span> );</div> <div class="line">GDALDataset *poSrcDS, *poVRTDS;</div> <div class="line"></div> <div class="line">poSrcDS = (GDALDataset *) GDALOpenShared( <span class="stringliteral">"utm.tif"</span>, GA_ReadOnly );</div> <div class="line"></div> <div class="line">poVRTDS = poDriver->CreateCopy( <span class="stringliteral">"wrk.vrt"</span>, poSrcDS, FALSE, NULL, NULL, NULL );</div> <div class="line"></div> <div class="line">GDALClose((GDALDatasetH) poVRTDS);</div> <div class="line">GDALClose((GDALDatasetH) poSrcDS);</div> </div><!-- fragment --><p>Note the use of GDALOpenShared() when opening the source dataset. It is advised to use GDALOpenShared() in this situation so that you are able to release the explicit reference to it before closing the VRT dataset itself. In other words, in the previous example, you could also invert the 2 last lines, whereas if you open the source dataset with GDALOpen(), you'd need to close the VRT dataset before closing the source dataset.</p> <p>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.</p> <div class="fragment"><div class="line">poVRTDS = poDriver->CreateCopy( <span class="stringliteral">""</span>, poSrcDS, FALSE, NULL, NULL, NULL );</div> <div class="line"></div> <div class="line">poVRTDS->SetMetadataItem( <span class="stringliteral">"SourceAgency"</span>, <span class="stringliteral">"United States Geological Survey"</span>);</div> <div class="line">poVRTDS->SetMetadataItem( <span class="stringliteral">"SourceDate"</span>, <span class="stringliteral">"July 21, 2003"</span> );</div> <div class="line"></div> <div class="line">poVRTDS->GetRasterBand( 1 )->SetNoDataValue( -999.0 );</div> <div class="line"></div> <div class="line">GDALDriver *poTIFFDriver = (GDALDriver *) GDALGetDriverByName( <span class="stringliteral">"GTiff"</span> );</div> <div class="line">GDALDataset *poTiffDS;</div> <div class="line"></div> <div class="line">poTiffDS = poTIFFDriver->CreateCopy( <span class="stringliteral">"wrk.tif"</span>, poVRTDS, FALSE, NULL, NULL, NULL );</div> <div class="line"></div> <div class="line">GDALClose((GDALDatasetH) poTiffDS);</div> </div><!-- fragment --><p>In the above example the nodata value is set as -999. You can set the HideNoDataValue element in the VRT dataset's band using SetMetadataItem() on that band.</p> <div class="fragment"><div class="line">poVRTDS->GetRasterBand( 1 )->SetMetadataItem( <span class="stringliteral">"HideNoDataValue"</span> , <span class="stringliteral">"1"</span> );</div> </div><!-- fragment --><p>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 <a class="el" href="classVRTRasterBand.html">VRTRasterBand</a> (but not to <a class="el" href="classVRTRawRasterBand.html">VRTRawRasterBand</a>) 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.</p> <div class="fragment"><div class="line"> <span class="comment">// construct XML for simple 3x3 average filter kernel source.</span></div> <div class="line"> <span class="keyword">const</span> <span class="keywordtype">char</span> *pszFilterSourceXML =</div> <div class="line"><span class="stringliteral">"<KernelFilteredSource>"</span></div> <div class="line"><span class="stringliteral">" <SourceFilename>utm.tif</SourceFilename><SourceBand>1</SourceBand>"</span></div> <div class="line"><span class="stringliteral">" <Kernel>"</span></div> <div class="line"><span class="stringliteral">" <Size>3</Size>"</span></div> <div class="line"><span class="stringliteral">" <Coefs>0.111 0.111 0.111 0.111 0.111 0.111 0.111 0.111 0.111</Coefs>"</span></div> <div class="line"><span class="stringliteral">" </Kernel>"</span></div> <div class="line"><span class="stringliteral">"</KernelFilteredSource>"</span>;</div> <div class="line"></div> <div class="line"> <span class="comment">// Create the virtual dataset. </span></div> <div class="line"> poVRTDS = poDriver->Create( <span class="stringliteral">""</span>, 512, 512, 1, GDT_Byte, NULL );</div> <div class="line"> poVRTDS->GetRasterBand(1)->SetMetadataItem(<span class="stringliteral">"source_0"</span>,pszFilterSourceXML,</div> <div class="line"> <span class="stringliteral">"new_vrt_sources"</span>);</div> </div><!-- fragment --><p>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.</p> <div class="fragment"><div class="line"><span class="keywordtype">int</span> nBand;</div> <div class="line">GDALDriver *poDriver = (GDALDriver *) GDALGetDriverByName( <span class="stringliteral">"VRT"</span> );</div> <div class="line">GDALDataset *poSrcDS, *poVRTDS;</div> <div class="line"></div> <div class="line">poSrcDS = (GDALDataset *) GDALOpenShared( pszSourceFilename, GA_ReadOnly );</div> <div class="line"></div> <div class="line">poVRTDS = poDriver->CreateCopy( <span class="stringliteral">""</span>, poSrcDS, FALSE, NULL, NULL, NULL );</div> <div class="line"></div> <div class="line"><span class="keywordflow">for</span>( nBand = 1; nBand <= poVRTDS->GetRasterCount(); nBand++ )</div> <div class="line">{</div> <div class="line"> <span class="keywordtype">char</span> szFilterSourceXML[10000];</div> <div class="line"></div> <div class="line"> GDALRasterBand *poBand = poVRTDS->GetRasterBand( nBand );</div> <div class="line"></div> <div class="line"> sprintf( szFilterSourceXML, </div> <div class="line"> <span class="stringliteral">"<KernelFilteredSource>"</span></div> <div class="line"> <span class="stringliteral">" <SourceFilename>%s</SourceFilename><SourceBand>%d</SourceBand>"</span></div> <div class="line"> <span class="stringliteral">" <Kernel>"</span></div> <div class="line"> <span class="stringliteral">" <Size>3</Size>"</span></div> <div class="line"> <span class="stringliteral">" <Coefs>0.111 0.111 0.111 0.111 0.111 0.111 0.111 0.111 0.111</Coefs>"</span></div> <div class="line"> <span class="stringliteral">" </Kernel>"</span></div> <div class="line"> <span class="stringliteral">"</KernelFilteredSource>"</span>, </div> <div class="line"> pszSourceFilename, nBand );</div> <div class="line"> </div> <div class="line"> poBand->SetMetadataItem( <span class="stringliteral">"source_0"</span>, szFilterSourceXML, <span class="stringliteral">"vrt_sources"</span> );</div> <div class="line">}</div> </div><!-- fragment --><p>The <a class="el" href="classVRTDataset.html">VRTDataset</a> class is one of the few dataset implementations that supports the AddBand() method. The options passed to the AddBand() method can be used to control the type of the band created (<a class="el" href="classVRTRasterBand.html">VRTRasterBand</a>, <a class="el" href="classVRTRawRasterBand.html">VRTRawRasterBand</a>, <a class="el" href="classVRTDerivedRasterBand.html">VRTDerivedRasterBand</a>), and in the case of the <a class="el" href="classVRTRawRasterBand.html">VRTRawRasterBand</a> to set its various parameters. For standard <a class="el" href="classVRTRasterBand.html">VRTRasterBand</a>, sources should be specified with the above SetMetadata() / SetMetadataItem() examples.</p> <div class="fragment"><div class="line">GDALDriver *poDriver = (GDALDriver *) GDALGetDriverByName( <span class="stringliteral">"VRT"</span> );</div> <div class="line">GDALDataset *poVRTDS;</div> <div class="line"></div> <div class="line">poVRTDS = poDriver->Create( <span class="stringliteral">"out.vrt"</span>, 512, 512, 0, GDT_Byte, NULL );</div> <div class="line"><span class="keywordtype">char</span>** papszOptions = NULL;</div> <div class="line">papszOptions = CSLAddNameValue(papszOptions, <span class="stringliteral">"subclass"</span>, <span class="stringliteral">"VRTRawRasterBand"</span>); <span class="comment">// if not specified, default to VRTRasterBand</span></div> <div class="line">papszOptions = CSLAddNameValue(papszOptions, <span class="stringliteral">"SourceFilename"</span>, <span class="stringliteral">"src.tif"</span>); <span class="comment">// mandatory</span></div> <div class="line">papszOptions = CSLAddNameValue(papszOptions, <span class="stringliteral">"ImageOffset"</span>, <span class="stringliteral">"156"</span>); <span class="comment">// optionnal. default = 0 </span></div> <div class="line">papszOptions = CSLAddNameValue(papszOptions, <span class="stringliteral">"PixelOffset"</span>, <span class="stringliteral">"2"</span>); <span class="comment">// optionnal. default = size of band type </span></div> <div class="line">papszOptions = CSLAddNameValue(papszOptions, <span class="stringliteral">"LineOffset"</span>, <span class="stringliteral">"1024"</span>); <span class="comment">// optionnal. default = size of band type * width </span></div> <div class="line">papszOptions = CSLAddNameValue(papszOptions, <span class="stringliteral">"ByteOrder"</span>, <span class="stringliteral">"LSB"</span>); <span class="comment">// optionnal. default = machine order</span></div> <div class="line">papszOptions = CSLAddNameValue(papszOptions, <span class="stringliteral">"relativeToVRT"</span>, <span class="stringliteral">"true"</span>); <span class="comment">// optionnal. default = false</span></div> <div class="line">poVRTDS->AddBand(GDT_Byte, papszOptions);</div> <div class="line">CSLDestroy(papszOptions);</div> <div class="line"></div> <div class="line"><span class="keyword">delete</span> poVRTDS;</div> </div><!-- fragment --><h2>Using Derived Bands</h2> <p>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.</p> <p>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):</p> <div class="fragment"><div class="line">band_value = sqrt((x3*x3+x4*x4)/(x0*x8));</div> </div><!-- fragment --><p>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:</p> <div class="fragment"><div class="line"><<a class="code" href="classVRTDataset.html">VRTDataset</a> rasterXSize=<span class="stringliteral">"1000"</span> rasterYSize=<span class="stringliteral">"1000"</span>></div> <div class="line"> <<a class="code" href="classVRTRasterBand.html">VRTRasterBand</a> dataType=<span class="stringliteral">"Float32"</span> band=<span class="stringliteral">"1"</span> subClass=<span class="stringliteral">"VRTDerivedRasterBand"</span>></div> <div class="line"> <Description>Magnitude</Description></div> <div class="line"> <PixelFunctionType>MyFirstFunction</PixelFunctionType></div> <div class="line"> <SimpleSource></div> <div class="line"> <SourceFilename relativeToVRT=<span class="stringliteral">"1"</span>>nine_band.dat</SourceFilename></div> <div class="line"> <SourceBand>1</SourceBand></div> <div class="line"> <SrcRect xOff=<span class="stringliteral">"0"</span> yOff=<span class="stringliteral">"0"</span> xSize=<span class="stringliteral">"1000"</span> ySize=<span class="stringliteral">"1000"</span>/></div> <div class="line"> <DstRect xOff=<span class="stringliteral">"0"</span> yOff=<span class="stringliteral">"0"</span> xSize=<span class="stringliteral">"1000"</span> ySize=<span class="stringliteral">"1000"</span>/></div> <div class="line"> </SimpleSource></div> <div class="line"> <SimpleSource></div> <div class="line"> <SourceFilename relativeToVRT=<span class="stringliteral">"1"</span>>nine_band.dat</SourceFilename></div> <div class="line"> <SourceBand>4</SourceBand></div> <div class="line"> <SrcRect xOff=<span class="stringliteral">"0"</span> yOff=<span class="stringliteral">"0"</span> xSize=<span class="stringliteral">"1000"</span> ySize=<span class="stringliteral">"1000"</span>/></div> <div class="line"> <DstRect xOff=<span class="stringliteral">"0"</span> yOff=<span class="stringliteral">"0"</span> xSize=<span class="stringliteral">"1000"</span> ySize=<span class="stringliteral">"1000"</span>/></div> <div class="line"> </SimpleSource></div> <div class="line"> <SimpleSource></div> <div class="line"> <SourceFilename relativeToVRT=<span class="stringliteral">"1"</span>>nine_band.dat</SourceFilename></div> <div class="line"> <SourceBand>5</SourceBand></div> <div class="line"> <SrcRect xOff=<span class="stringliteral">"0"</span> yOff=<span class="stringliteral">"0"</span> xSize=<span class="stringliteral">"1000"</span> ySize=<span class="stringliteral">"1000"</span>/></div> <div class="line"> <DstRect xOff=<span class="stringliteral">"0"</span> yOff=<span class="stringliteral">"0"</span> xSize=<span class="stringliteral">"1000"</span> ySize=<span class="stringliteral">"1000"</span>/></div> <div class="line"> </SimpleSource></div> <div class="line"> <SimpleSource></div> <div class="line"> <SourceFilename relativeToVRT=<span class="stringliteral">"1"</span>>nine_band.dat</SourceFilename></div> <div class="line"> <SourceBand>9</SourceBand></div> <div class="line"> <SrcRect xOff=<span class="stringliteral">"0"</span> yOff=<span class="stringliteral">"0"</span> xSize=<span class="stringliteral">"1000"</span> ySize=<span class="stringliteral">"1000"</span>/></div> <div class="line"> <DstRect xOff=<span class="stringliteral">"0"</span> yOff=<span class="stringliteral">"0"</span> xSize=<span class="stringliteral">"1000"</span> ySize=<span class="stringliteral">"1000"</span>/></div> <div class="line"> </SimpleSource></div> <div class="line"> </<a class="code" href="classVRTRasterBand.html">VRTRasterBand</a>></div> <div class="line"></<a class="code" href="classVRTDataset.html">VRTDataset</a>></div> </div><!-- fragment --><p>In addition to the subclass specification (<a class="el" href="classVRTDerivedRasterBand.html">VRTDerivedRasterBand</a>) 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.</p> <div class="fragment"><div class="line"><<a class="code" href="classVRTDataset.html">VRTDataset</a> rasterXSize=<span class="stringliteral">"1000"</span> rasterYSize=<span class="stringliteral">"1000"</span>></div> <div class="line"> <<a class="code" href="classVRTRasterBand.html">VRTRasterBand</a> dataType=<span class="stringliteral">"Float32"</span> band=<span class="stringliteral">"1"</span> subClass=<span class="stringliteral">"VRTDerivedRasterBand"</span>></div> <div class="line"> <Description>Magnitude</Description></div> <div class="line"> <PixelFunctionType>MyFirstFunction</PixelFunctionType></div> <div class="line"> <SourceTransferType>CFloat64</SourceTransferType></div> <div class="line"> ...</div> </div><!-- fragment --><h3>Writing Pixel Functions</h3> <p>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:</p> <div class="fragment"><div class="line">GDALAddDerivedBandPixelFunc(<span class="stringliteral">"MyFirstFunction"</span>, TestFunction);</div> </div><!-- fragment --><p>A good time to do this is at the beginning of an application when the GDAL drivers are registered.</p> <p>GDALDerivedPixelFunc is defined with a signature similar to IRasterIO:</p> <dl class="params"><dt>Parameters</dt><dd> <table class="params"> <tr><td class="paramname">papoSources</td><td>A pointer to packed rasters; one per source. The datatype of all will be the same, specified in the eSrcType parameter.</td></tr> <tr><td class="paramname">nSources</td><td>The number of source rasters.</td></tr> <tr><td class="paramname">pData</td><td>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.</td></tr> <tr><td class="paramname">nBufXSize</td><td>The width of the buffer image into which the desired region is to be read, or from which it is to be written.</td></tr> <tr><td class="paramname">nBufYSize</td><td>The height of the buffer image into which the desired region is to be read, or from which it is to be written.</td></tr> <tr><td class="paramname">eSrcType</td><td>The type of the pixel values in the papoSources raster array.</td></tr> <tr><td class="paramname">eBufType</td><td>The type of the pixel values that the pixel function must generate in the pData data buffer.</td></tr> <tr><td class="paramname">nPixelSpace</td><td>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.</td></tr> <tr><td class="paramname">nLineSpace</td><td>The byte offset from the start of one scanline in pData to the start of the next.</td></tr> </table> </dd> </dl> <dl class="section return"><dt>Returns</dt><dd>CE_Failure on failure, otherwise CE_None.</dd></dl> <div class="fragment"><div class="line"><span class="keyword">typedef</span> CPLErr</div> <div class="line">(*GDALDerivedPixelFunc)(<span class="keywordtype">void</span> **papoSources, <span class="keywordtype">int</span> nSources, <span class="keywordtype">void</span> *pData,</div> <div class="line"> <span class="keywordtype">int</span> nXSize, <span class="keywordtype">int</span> nYSize,</div> <div class="line"> GDALDataType eSrcType, GDALDataType eBufType,</div> <div class="line"> <span class="keywordtype">int</span> nPixelSpace, <span class="keywordtype">int</span> nLineSpace);</div> </div><!-- fragment --><p>The following is an implementation of the pixel function:</p> <div class="fragment"><div class="line"><span class="preprocessor">#include "gdal.h"</span></div> <div class="line"></div> <div class="line">CPLErr TestFunction(<span class="keywordtype">void</span> **papoSources, <span class="keywordtype">int</span> nSources, <span class="keywordtype">void</span> *pData,</div> <div class="line"> <span class="keywordtype">int</span> nXSize, <span class="keywordtype">int</span> nYSize,</div> <div class="line"> GDALDataType eSrcType, GDALDataType eBufType,</div> <div class="line"> <span class="keywordtype">int</span> nPixelSpace, <span class="keywordtype">int</span> nLineSpace)</div> <div class="line">{</div> <div class="line"> <span class="keywordtype">int</span> ii, iLine, iCol;</div> <div class="line"> <span class="keywordtype">double</span> pix_val;</div> <div class="line"> <span class="keywordtype">double</span> x0, x3, x4, x8;</div> <div class="line"></div> <div class="line"> <span class="comment">// ---- Init ----</span></div> <div class="line"> <span class="keywordflow">if</span> (nSources != 4) <span class="keywordflow">return</span> CE_Failure;</div> <div class="line"></div> <div class="line"> <span class="comment">// ---- Set pixels ----</span></div> <div class="line"> <span class="keywordflow">for</span>( iLine = 0; iLine < nYSize; iLine++ )</div> <div class="line"> {</div> <div class="line"> <span class="keywordflow">for</span>( iCol = 0; iCol < nXSize; iCol++ )</div> <div class="line"> {</div> <div class="line"> ii = iLine * nXSize + iCol;</div> <div class="line"> <span class="comment">/* Source raster pixels may be obtained with SRCVAL macro */</span></div> <div class="line"> x0 = SRCVAL(papoSources[0], eSrcType, ii);</div> <div class="line"> x3 = SRCVAL(papoSources[1], eSrcType, ii);</div> <div class="line"> x4 = SRCVAL(papoSources[2], eSrcType, ii);</div> <div class="line"> x8 = SRCVAL(papoSources[3], eSrcType, ii);</div> <div class="line"></div> <div class="line"> pix_val = sqrt((x3*x3+x4*x4)/(x0*x8));</div> <div class="line"> </div> <div class="line"> GDALCopyWords(&pix_val, GDT_Float64, 0,</div> <div class="line"> ((GByte *)pData) + nLineSpace * iLine + iCol * nPixelSpace,</div> <div class="line"> eBufType, nPixelSpace, 1);</div> <div class="line"> }</div> <div class="line"> }</div> <div class="line"></div> <div class="line"> <span class="comment">// ---- Return success ----</span></div> <div class="line"> <span class="keywordflow">return</span> CE_None;</div> <div class="line">}</div> </div><!-- fragment --><h1><a class="anchor" id="gdal_vrttut_mt"></a> Multi-threading issues</h1> <p>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. </p> </div></div><!-- contents --> <!-- start footer part --> <hr class="footer"/><address class="footer"><small> Generated by  <a href="http://www.doxygen.org/index.html"> <img class="footer" src="doxygen.png" alt="doxygen"/> </a> 1.8.5 </small></address> </body> </html>