.\

cggeomap.pro

top cgGeoMap

Graphics, Map Projections

result = cgGeoMap( [image] [, BOUNDARY=array] [, /CLIP] [, /DISPLAY] [, ELLIPSOID=string] [, GCOLOR=string] [, GEOTIFF=structure] [, /GRID] [, CCOLOR=string] [, /CONTINENTS] [, IMAGE=varies] [, LATLONBOX=array] [, MAP_PROJECTION=string] [, MCOLOR=string] [, /ONIMAGE] [, PALETTE=bytarr] [, /SILENT] [, SUB_RECT=integer] [, /SUCCESS] [, TITLE=string] [, _EXTRA=_EXTRA])

The purpose of this function is to translate a GEOTIFF structure (as returned by QUERY_TIFF or READ_TIFF) into a map coordinate object (cgMap) that can be used to georeference images with a map data coordinate system. The Coyote Library is required.

It is not possible to have a one-to-one mapping between every GeoTIFF file and a map projection in IDL, since IDL has a limited number of map projections and datums available. And, even at that, I have not implemented all of IDL's map projections or datums, only those that I thought were most likely to be encountered in my own work. If you run into a GeoTIFF file that does not work in this code (either because of an error in the code or because it is not supported), please contact me. I am interested in supporting as many GeoTIFF files as possible and I will take pains to do so if I know they are needed.

Return value

A cgMap coordinate object is returned containing the map projection information for the image.

Parameters

image in optional type=various

A GeoTIFF image. This can optionally be the name of a GeoTiff file. If a filename is used, do not pass the geoTiff parameter, as this parameter will be obtained from the GeoTiff file.

Keywords

BOUNDARY out optional type=array

A four-element array giving the boundaries of the map projection in the form [x0,y0,x1,y1]. This is a more convenient way of expressing the range of the map space.

CLIP in optional type=boolean default=0

Set this keyword to display the image (assumes the Display keyword is set) with a two-precent histogram clipping.

DISPLAY in optional type=boolean default=0

Set this keyword to display the image with the map annotations in a resizeable cgWindow.

ELLIPSOID out optional type=string

The name of the ellipsoid used in the GeoTiff file.

GCOLOR in optional type=string default=Gray

The name of a color the map grid should be displayed with. The default is "gray". Color names are those supported by cgColor.

GEOTIFF in optional type=structure

A GeoTIFF structure of geoTags. Normally obtained by calling QUERY_TIFF or READ_TIFF, but will be read from the file if a filename is passed as the first positional parameter. If the geotag is read from the file, it can be passed back to the user by setting this keyword to a named variable.

GRID in optional type=boolean default=0

If a cgMap object is made successfully, then setting this keyword will add a cgMapGrid object to the cgMap object.

CCOLOR in optional type=string default=Charcoal

The name of a color the map continents should be displayed with. The default is "charcoal". Color names are those supported by cgColor.

CONTINENTS in optional type=boolean default=0

If a cgMap object is made successfully, then setting this keyword will add a cgMapContinents object to the cgMap object.

IMAGE out optional type=varies

Set this keyword to a named variable that on exit will contain the image data.

LATLONBOX out optional type=array

A four-element array giving the boundaries of the map projection in the Google Map form of [north, south, east, west]. This is useful when you are creating image overlays to be added to Google Earth.

MAP_PROJECTION out optional type=string

The name of the map projection found in the GeoTiff file.

MCOLOR in optional type=string default=Black

The name of a color the map should be displayed in. (Normally the map border and map title are displayed in this color.)

ONIMAGE in optional type=boolean default=0

Set this keword if the map object is to get its position from the last cgImage command issued.

PALETTE out optional type=bytarr

If the GeoTiff file contains RGB color vectors, and keywords to cgGeoTiff cause the file to be read (e.g, IMAGE or DISPLAY), then this output keyword will contain those vectors in a 3-by-256 byte array.

SILENT in optional type=boolean default=0

IDL cannot map every GeoTiff image to a supported map projection or datum. Normally, if the GeoTIFF image is unsupported, an error message is issued. Setting this keyword will suppress such error messages. If you do this, you MUST check the SUCCESS keyword to see if the program ran successfully. (Of course, it is a good idea to check it in any case!)

SUB_RECT in optional type=integer

Set this keyword to a four-element array, [x, y, width, height], that specifies a rectangular region within the file to extract. Only the rectangular portion of the image selected by this keyword is read and returned. The rectangle is measured in pixels from the lower left corner (right hand coordinate system). If this keyword is not use, the entire image is read.

SUCCESS out optional type=boolean default=0

An output variable that will contain a 1 if the map coordinate object was created successfully. Or to a 0 if it was not created successfully.

TITLE in optional type=string

The title of the map projection.

_EXTRA in optional

Any keyword appropriate for cgImage can be collected and passed along if the DISPLAY keyword is also set.

Examples

To display a GeoTiff image in cgWindow with map annotations:

  file = 'C:\IDL\data\tiff\AF03sep15b.n16-VIg.tif'
  mapCoord = cgGeoMap(file, /Continents, /Grid, /Display)

Author information

Author:

FANNING SOFTWARE CONSULTING:

   David W. Fanning
   1645 Sheely Drive
   Fort Collins, CO 80526 USA
   Phone: 970-221-0438
   E-mail: david@idlcoyote.com
   Coyote's Guide to IDL Programming: http://www.idlcoyote.com/

Copyright:

History:

Modification History:

  Converted from old GeoTIff program in Catalyst Library to run with Coyote Graphics routines.
     9 November 2011. David W. Fanning.
   Assuming meters as unit length if can't find linear measure in file. 1 Dec 2011. DWF.
   Added UTM Zone 18S (projection 29178) for LandSAT MSS images over Amazon. 1 Dec 2011. DWF.
   Added the ability to pass cgImage keywords via the keyword inheritance mechanism. 1 Dec 2011. DWF.
   Added SUB_RECT keyword. 5 Dec 2011. DWF.
   Added ability to read GOES EAST and GOES WEST GeoTiff files  from this NOAA web site:
      http://http://www.osdpd.noaa.gov/ml/gis/index.html. 26 Dec 2011. DWF.
   Modified code to read GeoTiff files created by HEG v2.11 from HDF-EOS2 grid files. 30 Dec 2011. DWF.
   Modified to read multi-dimensional GeoTiff images and reverse the images correct. 12 Jan 2012. DWF.
   Write base filename as title for window if the DISPLAY keyword is set. 22 Feb 2012. DWF.
   Had inexplicably left out CENTER_LATITUDE parameter in Equirectangular projection. 30 July 2012. DWF.
   Added PALETTE keyword to return the RGB color palette present in the file, if any. 16 August 2012. DWF.
   Moved the geotiff argument to a GEOTIFF keyword, as I always expect it to be this way. 6 Sept 2012. DWF.
   Removed UTM/WGS84 warning message in IDL 8.2, as this problem has been fixed in IDL 8.2. 2 Oct 2012. DWF.
   Added BOUNDARY, ELLIPSOID, LATLONBOX, and MAP_PROJECTION output keywords to facilitate
      creating Google Earth overlays. 30 Oct 2012. DWF.
   Small fix to allow true-color TIFF images to be read correctly. 11 Sept 2013. DWF.
   Modified program to look for NSIDC Hughes ellipsoid specified as semi-major axis of 6378273.0 and
      semi-minor axis of 6356889.4 as specified by the GeoTiff tags GEOGSEMIMAJORAXISGEOKEY and
      GEOGSEMIMINORAXISGEOKEY. I do this ONLY for Polar Stereographic map projections.

File attributes

Modification date:	Mon Nov 04 16:58:42 2013
Lines:	1,401
Docformat:	rst rst

Coyote Graphics Map Projection Routines

Date: Fri Nov 29 13:44:27 2013

.\