[gdal-dev] Improving the Documentation of Get/SetGeoTransform

[Isaac Gerg]

Hi all,

I've spent some time today working with the SetGeoTransform function today
and want to mention that the documentation doesn't seem quite clear and
maybe even a bit misleading.

In here,
http://www.gdal.org/classGDALDataset.html#f9593cc241e7d140f5f3c4798a43a668,
the transform is mentioned as a 6 element matrix (2x3) and explains the
elements as follows:

*"In a north up image, padfTransform[1] is the pixel width, and
padfTransform[5] is the pixel height. The upper left corner of the upper
left pixel is at position (padfTransform[0],padfTransform[3])."*
*
*
Additionally, in the tutorial,http://www.gdal.org/gdal_tutorial.html, it
says:


    adfGeoTransform[0] /* top left x */
    adfGeoTransform[1] /* w-e pixel resolution */
    adfGeoTransform[2] /* rotation, 0 if image is "north up" */
    adfGeoTransform[3] /* top left y */
    adfGeoTransform[4] /* rotation, 0 if image is "north up" */
    adfGeoTransform[5] /* n-s pixel resolution */

*
*
I believe these comments are not quite true and a little misleading.  Here
is a common example of using SetGeoTransform where the above statement
breaks down.

Suppose you have an imager that collects an image of the surface of the
earth over a small, local area say 50m by 50m.  For ease, let each pixel
represents a 10cm by 10cm box.  Now, say you have the image data in raster
format and want to output a geotiff.  You will have to make a geo transform
that maps from pixel space (in meters) to lat/lon space.  Additionally, your
raster image is rotated by 10 degrees (denoted as alpha and in radians) East
due to the imaging collection parameters.  The matrix you want is something
like the following:

padfTransform[0] = corner lon
padfTransform[1] = cos(alpha)*(scaling)
padfTransform[2] = -sin(alpha)*(scaling)
padfTransform[3] = corner lat
padfTransform[4] = sin(alpha)*(scaling)
padfTransform[5] = cos(alpha)*(scaling)

where scaling maps pixel space to lat/lon space (see
http://en.wikipedia.org/wiki/Geographical_distance#Spherical_Earth_projected_to_a_plane
on
how to compute the scaling factor)

See http://en.wikipedia.org/wiki/Transformation_matrix#Rotation for more
details on my matrix coefs.

I think the documentation would be more clear if it included this
description -- that matrix represents a combination of scaling, rotation,
and transnational components of which most of the them are combined in the
terms, not isolated as the documentation has the reader to believe.

Anyways, I'm not griping, just trying to help.  GDAL's been very useful to
my group and the community has been very responsive.  Thank you for this.

Isaac
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.osgeo.org/pipermail/gdal-dev/attachments/20110712/14b86154/attachment-0001.html