coyote: CGNCDFMAP

Description
The purpose of this function is to translate map projection information
found in a netCDF file into a map coordinate object (cgMap) that can be 
used to georeference images with a map data coordinate system. The Coyote 
Library is required.
Categories
Graphics, Map Projections  
Examples
To create a map coordinate from a netCDF file from NSIDC::
   file = 'C:\IDL\data\netCDF\jun_2004_amsr_e_bt.nc'
   mapCoord = cgNCDFMap(file, /Continents, /Grid)
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/
File_comments
It is not possible to have a one-to-one mapping between every netCDF 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 netCDF 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 netCDF files as possible and I will take pains to do so if
I know they are needed.
History
Converted from old ncdf_Coord program in Catalyst Library to run with Coyote Graphics routines.
   9 November 2011. David W. Fanning.
Copyright
Copyright (c) 2011, Fanning Software Consulting, Inc.
Params
ncdf_filename: in, optional, type=string  
   The name of a netCDF file containing map projection information from
   which a cgMap object can be created.
Keywords
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.   
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.
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.  
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.
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!)
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, default=""                      
     The title of the map projection.
use_latlon: in, optional, type=boolean, default=0
     If this keyword is set, the boundary ranges will be forced to be determined 
     from the latitude and longitude arrays in the file. 
xrange: out, optional, type=double
     The discovered X projected meter range of the map projection.
yrange: out, optional, type=double
     The discovered Y projected meter range of the map projection.