plot-latlong/README

   1                           plot-latlong
   2
   3                            version 0.3
   4
   5                            Jun 10, 2005
   6
   7                   (c) 2003,2004,2005 CAIDA/UCSD
   8
   9   (http://www.caida.org/tools/visualization/plot-latlong/index.xml)
  10
  11                    plot-latlong-info@caida.org
  12                    plot-latlong-bugs@caida.org
  13
  14 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  15 CHANGES
  16
  17  * v0.3 released Jun 10, 2005
  18
  19    - added -i option to specify location of mapinfo file.
  20
  21  * v0.2 released Apr 6, 2004
  22
  23    - added test-gd script for testing the GD installation
  24
  25  * v0.1 released Oct 3, 2003 -- initial release
  26
  27 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  28 DESCRIPTION
  29
  30 plot-latlong is a small command line tool written in perl for plotting
  31 points on geographic maps given a list of latitude/longitude (lat/long)
  32 pairs.  This is aimed at situations in which
  33
  34   * a moderate amount of accuracy and precision is sufficient
  35   * a large number of locations need to be plotted (tens of thousands of
  36     locations can be easily handled)
  37   * the plotting needs to be automatable (from a shell script, for example)
  38   * a lightweight tool (both small and with few dependencies) that just plots
  39     points is sufficient
  40   * ease of modification is important (so that special requirements can be
  41     met)
  42
  43 plot-latlong can handle nonlinear map projections (currently the
  44 Alber/Lambert projection) and is intentionally minimalistic so that it can
  45 serve as a building block.  Users can build upon it in three ways: (1) add
  46 new maps, (2) run the output images through packages like NetPBM to add
  47 titles, etc., and (3) modify the source to change how points are drawn, to
  48 add labels, etc.  plot-latlong can also be used to simply compute the
  49 mapping from lat/long to pixel coordinates (for a given map).  These pixel
  50 coordinates can then be fed to other programs to draw more elaborate
  51 pictures.
  52
  53
  54 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  55 IMPLEMENTED FEATURES
  56
  57 The list of implemented features is intentionally short:
  58
  59   * drawing points at a user-specified size
  60   * printing out just the pixel coordinates of input lat/long pairs
  61   * support for linear projections (the relationship between pixels
  62     and lat/long values is linear)
  63   * support for the Alber/Lambert nonlinear projection
  64
  65 The distribution includes over two dozen maps, covering the continents
  66 and several country groups.  Users can also supply maps to use, so
  67 long as the projection type is supported and the projection parameters
  68 are known.
  69
  70
  71 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  72 CAVEATS
  73
  74 plot-latlong is unsuitable for applications demanding high accuracy.
  75 Accuracy is likely no better than 5-10 miles--and even this is merely a
  76 shot in the dark, since we're not in a position to rigorously determine the
  77 accuracy of the generated plots.  The following factors contribute to
  78 increased inaccuracy:
  79
  80   * the relative coarseness of the supplied maps
  81   * unverified projection parameters for the supplied maps
  82   * the USA maps, which use the Alber/Lambert projection, have parameters
  83     calibrated by eye
  84   * the geodetic datum assumed by the supplied maps is unknown to us
  85     (http://www.colorado.edu/geography/gcraft/notes/datum/datum_f.html)
  86
  87      + lat/long coordinate values are not universal; values are always
  88        specified in some system, the datum, and mismatches in the assumed
  89        datum can lead to the specification of physical locations that are
  90        separated by as much as 1km
  91
  92      + to assess whether plot-latlong will be sufficient for your needs,
  93        you might try comparing the results with those from the
  94        Tiger Map Server (http://tiger.census.gov/cgi-bin/mapbrowse-tbl/)
  95        and MapQuest (http://www.mapquest.com/maps/latlong.adp).
  96
  97
  98 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  99 REQUIREMENTS
 100
 101 The requirements for running plot-latlong are:
 102
 103   * UNIX-like operating system
 104   * perl (http://www.perl.com)
 105   * GD.pm (http://stein.cshl.org/WWW/software/GD/), which in turn requires
 106     (see the README of GD.pm):
 107
 108      + the gd graphics library (http://www.boutell.com/gd/)
 109      + the PNG graphics library (http://www.libpng.org/pub/png/libpng.html)
 110      + the zlib compression library (http://www.gzip.org/zlib/)
 111
 112
 113 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 114 INSTALLATION
 115
 116 No installation, per se, is required, but for the greatest convenience,
 117 it is best to copy some files to your home directory, as in the following:
 118
 119      cp plot-latlong $HOME/bin
 120      cp -R .mapinfo .mapimages $HOME
 121
 122 Assuming $HOME/bin is in your PATH, you can now run plot-latlong from
 123 anywhere.
 124
 125
 126 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 127 USAGE
 128
 129 plot-latlong reads lat/long values from stdin and writes a PNG to
 130 stdout.  The input should contain one pair of lat/long values per line
 131 with the values separated by whitespace.  Each coordinate should be a
 132 decimal value, with negative values indicating south or west.  Blank lines
 133 and lines starting with the pound character ('#') are ignored.
 134
 135 Command line options are
 136
 137   -m <map-name> specifies the name of a map to use (default: the first
 138      map listed in .mapinfo: 'World'); see .mapinfo for the valid map names;
 139      see the file CONFIG for a description of the .mapinfo format
 140
 141   -s <point-size> specifies the size of the points to draw (default: 1);
 142      points are filled squares, and the size is the width in pixels
 143
 144      (NOTE: Points drawn at the default size of 1 pixel may be hard to see
 145             when only a few points are plotted.  Use '-s 10' when plotting
 146             a small number of points.)
 147
 148   -c causes the pixel coordinates of each lat/long to be printed to stderr;
 149      the coordinates (0, 0) are at the upper left corner, and values increase
 150      to the right and down
 151
 152   -i <map-info-file> specifies an alternate location for .mapinfo (other
 153      than in the current directory or $HOME).
 154
 155 Examples:
 156
 157 $ cat locations.txt | ./plot-latlong >plot.png
 158
 159 $ ./plot-latlong -m USA -s 10 >plot.png <<EOF
 160 # san diego
 161 32.8155594 -117.1361008
 162
 163 # miami, fl
 164 25.7707844 -80.2112045
 165
 166 # new york, ny
 167 40.6691055 -73.9439468
 168 EOF
 169
 170 $ cat locations.txt | ./plot-latlong -c >/dev/null 2>xy.txt
 171 $ head xy.txt
 172 33.58 -86.52 250.44 168.946555555556
 173 33.59 -86.96 249.12 168.916611111111
 174 ...
 175
 176
 177 NOTE: You may safely ignore the following warning:
 178
 179              gd-png warning: alpha channel not supported
 180
 181       This warning says that the input map image had transparency information,
 182       which some GD versions don't support.  None of the map images included
 183       in the distribution have transparency, but maps of your own may.
 184       In such cases, use an image editing tool to remove the transparency
 185       information.
 186
 187
 188 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 189 ACKNOWLEDGMENTS
 190
 191 The code for handling the Alber/Lambert map projection is derived from
 192 GTrace v1.0.0beta (http://www.caida.org/tools/visualization/gtrace),
 193 which was written by Ram Periakaruppan.  The included set of maps are also
 194 derived from the GTrace distribution.  GTrace redistributed these maps
 195 with the permission of VisualRoute (http://www.visualroute.com),
 196 the original source of the maps.
 197
 198
 199 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 200 LICENSE
 201
 202 Copyright (C) 2003,2004,2005 The Regents of the University of California.
 203 All Rights Reserved.
 204
 205 Permission to use, copy, modify and distribute any part of this
 206 plot-latlong software package for educational, research and non-profit
 207 purposes, without fee, and without a written agreement is hereby
 208 granted, provided that the above copyright notice, this paragraph
 209 and the following paragraphs appear in all copies.
 210
 211 Those desiring to incorporate this into commercial products or use
 212 for commercial purposes should contact the Technology Transfer
 213 Office, University of California, San Diego, 9500 Gilman Drive, La
 214 Jolla, CA 92093-0910, Ph: (858) 534-5815, FAX: (858) 534-7345.
 215
 216 IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY
 217 PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
 218 DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF THIS
 219 SOFTWARE, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF
 220 THE POSSIBILITY OF SUCH DAMAGE.
 221
 222 THE SOFTWARE PROVIDED HEREIN IS ON AN "AS IS" BASIS, AND THE
 223 UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE,
 224 SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. THE UNIVERSITY
 225 OF CALIFORNIA MAKES NO REPRESENTATIONS AND EXTENDS NO WARRANTIES
 226 OF ANY KIND, EITHER IMPLIED OR EXPRESS, INCLUDING, BUT NOT LIMITED
 227 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A
 228 PARTICULAR PURPOSE, OR THAT THE USE OF THE SOFTWARE WILL NOT INFRINGE
 229 ANY PATENT, TRADEMARK OR OTHER RIGHTS.
 230
 231 The plot-latlong software is developed by the plot-latlong Team at the
 232 University of California, San Diego under the Cooperative Association
 233 for Internet Data Analysis (CAIDA) Program.  Support for this work is
 234 provided by the National Communications System (NCS) via NSF grant
 235 ANI-0221172, entitled "Routing and Peering Analysis for Enhancing
 236 Internet Performance and Security."