***************************************************************************
**  DECODE Readme File                                                   **
**  US Census Bureau                                                     **
**  Tiger Map Server Project                                             ** 
**  Email suggestions and comments to: mapsurf@geo.census.gov                    ** 
***************************************************************************

DESCRIPTION:
------------

The decode program returns the Lon/Lat coordinates for a 
TMS (Tiger Map Server) generated .gif image given the x,y pixel coordinates.
(where the user clicks)

We use this routine to determine the new Lon/Lat when a user
moves to new center when browsing maps.  It has plenty of other
utility as well.


USAGE:
------

-c or -center		Lon/Lat of Map center point
-e or -extent		Map extent in degrees (width and height)
-p or -point		x,y pixel coordinate of gif image
-g or -geometry		Image geometry (width and height)



HOWTO MAKE IT WORK:
-------------------

You have to at least get it to compile on your machine...  It is known
to work on Unix machines.  I have not tried any of the PC C Compilers,
but it should work just fine.   It is just a program (decode.c) and
2 header files.

Generate an image from the TMS and save it (I included dc.gif with this
distribution as an example).  The URL for the map server is:

http://tiger.census.gov/cgi-bin/mapbrowse-tbl (for NetScape Users)
http://tiger.census.gov/cgi-bin/mapbrowse  (for browsers without table support)

The map server will generate a .gif image (map) and if you will notice near
the bottom of the screen you will see:

Enter precise coordinates:

Latitude(deg):     [ -77.020 ]
Longitude(deg):    [  38.890 ]
Map Width(deg):    [ .360 ]
Map Height(deg):   [ .130 ] 
Image Width(pix):  [ 300 ] 
Image Height(pix): [ 400 ] 

Record these values (They are need for decode input)

Save the image (with NetScape, try shift-rightclick) with a .gif extension
to a filename of your choice.  

*Note: You actually dont need the image to decode the LON/LAT of a point.
       I just ask you to download it, because the values (above) are image
       specific.  (meaning that these value belong to a specific image)

To view the image, you can use LView, XView or whatever *OR* you can make it a 
cgi type application (clickable smart image ;)    Find x,y coordinates of the
point where you click.   (in this my case, I click on Suitland, Maryland in
the dc.gif at image pixel coordinates x=230 y=246) and the
program returns (to STDOUT) the LON/LAT (seperated by a space)


Run decode:

%decode -c -77.020 38.890 -e .360 .130 -p 230 246 -g 300 400 
-76.9241 38.8546


Suitland, Maryland is at Lon=-76.9241 Lat=38.8546
(or real close to it... I was just picking a spot on the map.)


Another example (CGI):

Excerpt from mapbrowse (PERL code):

if ((defined($args{"map\.x"})) && (defined($args{"map\.y"})) && (defined($args{"
act"}))){
    # clicked on map--decode coordinates and do something
    if ($args{"act"} =~ /load/) {
        print "Location: http://tiger.census.gov/cgi-bin/mapgen/.gif?";
        print "$query&iht=$iht&iwd=$iwd\n\n";
        exit;
      }
    $cmd = "decode";
    $x = $args{"map\.x"}; $y = $args{"map\.y"};
    $new = `$cmd -c $lon $lat -e $wid $ht -p $x $y -g $iwd $iht`;
    ($ln,$lt) = split(" ",$new);