1.. _rfc-32: 2 3================================================================================ 4RFC 32: gdallocationinfo utility 5================================================================================ 6 7Authors: Frank Warmerdam 8 9Contact: warmerdam@pobox.com 10 11Status: Adopted 12 13Summary 14------- 15 16This document proposes the addition of a new standard commandline 17utility for GDAL to report details about a location (pixel) in a raster. 18 19Rationale 20--------- 21 221) A user has a use case where they would like to be able to identify 23 the VRT file used to satisfy requests for a particular pixel / 24 location. 25 262) Many users have requested a tool to find the value of a location, 27 often expressed in a coordinate system different than that of the 28 image. For instance, "what is the elevation at a given lat/long 29 location?". 30 31The gdallocationinfo utility is intended to address both sorts of 32requests, and hopefully in a way that will have some general value as a 33"raster point query" tool. 34 35gdallocationinfo 36---------------- 37 38Full docs are available at :ref:`gdallocationinfo` 39 40:: 41 42 Usage: gdallocationinfo [--help-general] [-xml] [-lifonly] [-valonlyl] 43 [-b band]* [-l_srs srs_def] [-geoloc] [-wgs84] 44 srcfile x y 45 46The key aspects of the utility are control over the coordinate system of 47the location (-s_srs, -geoloc, -wgs84) and various controls over the 48output format (-xml, -lifonly, -valonly). An example of full output in 49xml might be: 50 51:: 52 53 $ gdallocationinfo -xml -wgs84 utm.vrt -117.5 33.75 54 <Report pixel="217" line="282"> 55 <BandReport band="1"> 56 <LocationInfo> 57 <File>utm.tif</File> 58 </LocationInfo> 59 <Value>16</Value> 60 </BandReport> 61 </Report> 62 63LocationInfo Metadata Domain 64---------------------------- 65 66The pixel values and location transformation logic is all built into 67gdallocationinfo and doesn't require much elaboration. The more exotic 68portion is reporting of "LocationInfo" queried from the datasource. 69 70For our immediate needs the requirement is to have the 71VRTSourcedRasterBand return information on the file(s) overlapping the 72target pixel. But, in theory different drivers might return different 73sorts of information about a location. For instance, a WMS driver might 74issue a GetFeatureInfo for the location and return the result. 75 76The mechanism to query the datasource is a specially named 77GetMetadataItem() request against the "LocationInfo" domain of the 78target band(s). The following requested item name is of the form 79"Pixel_x_y" where x and y are the pixel and line of the pixel being 80queried. 81 82The returned value from this item should either be NULL, or an XML 83documented with the root element "". The contents of the document are 84otherwise undefined as long as they are well formed XML. The VRT driver 85returns a series of xxx entries for each of the files at that location. 86 87eg. 88 89:: 90 91 GDALGetMetadataItem( hBand, "Pixel_100_200", "LocationInfo" ); 92 93might return: 94 95:: 96 97 <LocationInfo> 98 <File>utm.tif</File> 99 </LocationInfo> 100 101Test Suite 102---------- 103 104A test will be introduced in the gdal utilities suite, and the 105gdrivers/vrt.py script for the utility and VRT behavior respectively. 106 107Documentation 108------------- 109 110Documentation for the utility has already been prepared and is 111referenced above. 112 113Implementation 114-------------- 115 116Implementation is already complete, and in trunk. Adjustments can be 117made by Frank Warmerdam as needed due to RFC revisions. 118