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