Last updated $Date: 2012/09/11 17:08:00 $

"shptosvg.pl" is a Perl program (script, whatever) that renders one or
more ESRI Shapefiles in an SVG (Scalable Vector Graphics) file.  The SVG
file created can be subsequently edited with an SVG editor like Inkscape
to ammend the results of the rendering and to add finishing touches.

These external Perl modules (available from CPAN) are required by this
program:

    Geo::ShapeFile
        http://search.cpan.org/~jasonk/Geo-ShapeFile-2.52/lib/Geo/ShapeFile.pm  
    SVG
        http://search.cpan.org/~ronan/SVG-2.49/lib/SVG/Manual.pm
    Geo::Point 
        http://search.cpan.org/~markov/Geo-Point-0.91/lib/Geo/Point.pod
    Geo::Proj4
        http://search.cpan.org/~markov/Geo-Proj4-1.01/lib/Geo/Proj4.pod

The Geo::Proj4 module requires that the Proj4 library be pre-installed.
That can be downloaded from http://trac.osgeo.org/proj

No other external dependencies should exit.

------------------------------------------------------------------------

Manifest:

    shptosvg.pl:   The perl program
    mkogallala.sh: A shellscript containing an example use of the program
    README:        You're reading it now.
    FEATURES:      A list of features in the program
    TODO:          A list of features that may be coming soon, or which
                   may just be pie in the sky.

------------------------------------------------------------------------

Command line arguments and parameters (seen with "-h" option):

Usage: $0 [-x xsize] [-y ysize] [-l] [-p precision] [-d deltamin] [-T srs] [-S srs] [-C xmin,ymin:xmax,ymax] inputspec [inputspec ...]\n" ;

    -l lists the names of the attribute fields in the shapefile and
       then exits.

    -x xsize is image width (in points?); defaults to 576

    -y ysize is image height (in points?) 720

    -T srs is for Target projection spatial reference system in
       Proj4 format; defaults to rectilinear lat/lon

    -S srs is the default Source spatial reference system in Proj4
       format; defaults to rectilinear lat/lon

    -C xmin,ymin:xmax,ymax crops the results to the bounding box
       defined by opposing corners in the target coordinate system

    -p precision is the number of decimal points used in the SVG
       for position coordinates; defaults to 1

    -d deltamin is the minimum change in either x or y from the
       previously plotted point in a line or polygon for the next one
       to be plotted.  This reduces file size by omitting points that
       are very, very close to each other.  Good results are achieved
       with -p1 -d0.5, which are the defaults.

    -v for verbose commentary on stderr as the program runs

    An "inputspec" contains a shapefile path (with or without .shp)
    and a list of processing/rendering options separated by commas
    but no spaces.  (Spaces are okay in some options where needed,
    but not between.)  Options contain a name and a value joined by
    an equal signe: name=value.  Currently supported options:

        Option    Value
        --------  -------------------------------------------------- 
        srs       Source SRS for the shapefile, in Proj4 format

        group     Name of an attribute to group objects by

        grep      Name of an attribute by which to select records for
                  inclusion, and a pcre regex by which to choose them,
                  joined with a tilde.  E.g.: "grep=FIPSCODE~(04)|(35)"
                  might choose records for Arizona and New Mexico if
                  the records has a field named FIPSCODE that contains
                  the state FIPS code.

        ptype     Built-in shape name to plot point data as, or to plot
                  just the center point (vertex centroid) of polygon
                  shapes.  Valid values include "square", "diamond",
                  "star4", and "star5".

        style     Additional or replacement SVG "style" elements for
                  rendering this shapefile E.g.: "style=stroke: #800000;
                  stroke-width: 1.5; fill: #ffff80"

        rad       Radius for the circle drawn for point shapes.
                  Only circles are currently used.

        nodraw    Set to "true" or "1" to inhibit rendering of the
                  shapefile; useful for influencing the scale when
                  rendering other files, as when creating layers
                  separately.

        colorby   An attribute name followed by a list of pcre regexes
                  and color specs; the fill for each shape is set to
                  the color associated with the first matching regex.
                  E.g.: "colorby="RANGE;m/0 to 50/#cfef7f;m/50 to
                  100/#a1f574;m/100 to 200/#95fbcb" In this example,
                  the RANGE field contains strings like "0 to 50".
                  Full-blown regexes are possible, though.

        same      Name of an attribute to set the fill color of the
                  shapes by; all shapes having the same value get the
                  same unique color.  The color sequence is currently
                  hard-coded.  The attribute can be numeric or not.
                  A key legend is created out of view in the SVG image;
                  it can be edited as desired and moved into a suitable
                  position with an SVG editor in post-processing.

        range     Atributename;color1;color2[;log]
                  The range of values in the named attribute are
                  colored with continuous range of colors from color1
                  for the lowest value to color2 for the highest value.
                  The attribute is treated as numeric.  If the optional
                  log option is given, a logarighmic scale is used,
                  linear otherwise.

Example inputspec: 
Rivers.shp,grep="NAME~(Red)|(Brazos)|(Pecos)",style="stroke:#1821DE;stroke-width:1",srs="+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs"