.. index::
   pair: Utility; shp2img

.. _shp2img:

*****************************************************************************
 shp2img
*****************************************************************************

:Author: Jeff McKenna
:Contact: jmckenna at gatewaygeomatics.com
:Last Updated: 2016-03-11

.. contents:: Table of Contents
    :depth: 3
    :backlinks: top

Purpose
-----------------------------------------------------------------------------

Creates a map image from a mapfile. Output is by default PNG, but you can specify
other output formats defined in the mapfile.  This is a very useful utility to test your 
mapfile. You can simply provide the path to your mapfile and the name of an output 
image, and an image should be returned. If an image cannot be created an error will 
be displayed at the commandline that should refer to a line number in the mapfile.
   
Syntax
-----------------------------------------------------------------------------
::

    shp2img -m mapfile [-o image] [-e minx miny maxx maxy] [-s sizex sizey]
           [-l "layer1 [layers2...]"] [-i format]
           [-all_debug n] [-map_debug n] [-layer_debug n] [-p n] [-c n] [-d
          layername datavalue]
    -m mapfile: Map file to operate on - required
    -i format: Override the IMAGETYPE value to pick output format
    -o image: output filename (stdout if not provided)
    -e minx miny maxx maxy: extents to render
    -s sizex sizey: output image size
    -l layers: layers to enable - make sure they are quoted and space separated
       if more than one listed
    -all_debug n: Set debug level for map and all layers
    -map_debug n: Set map debug level
    -layer_debug layer_name n: Set layer debug level
    -c n: draw map n number of times
    -p n: pause for n seconds after reading the map
    -d layername datavalue: change DATA value for layer


Example #1 Generate a Map Image
.............................................................................

::
    
    shp2img -m vector_blank.map -o test.png

Result
    A file named 'test.png' is created, that you can drag into your browser to view.  

Example #2 Generate a Map Image with Draw Speeds
.............................................................................

::
    
    shp2img -m gmap75.map -o test2.png -map_debug 3

Result
    A file named 'test2.png' is created, and layer draw speeds are returned such as:

::

    msDrawMap(): rendering using outputformat named png (AGG/PNG).
    msDrawMap(): WMS/WFS set-up and query, 0.000s
    msDrawRasterLayerLow(bathymetry): entering.
    msDrawMap(): Layer 0 (bathymetry), 0.011s
    msDrawMap(): Layer 1 (land_fn), 0.016s
    msDrawMap(): Layer 3 (drain_fn), 0.006s
    msDrawMap(): Layer 4 (drainage), 0.041s
    msDrawMap(): Layer 5 (prov_bound), 0.025s
    msDrawMap(): Layer 6 (fedlimit), 0.001s
    msDrawMap(): Layer 9 (popplace), 0.007s
    msDrawMap(): Drawing Label Cache, 0.004s
    msDrawMap() total time: 0.119s
    msSaveImage(test2.png) total time: 0.034s

Example #3 Generate a Map Image with Debug Information for all Layers
.............................................................................

::
    
    shp2img -m gmap75.map -o test3.png -all_debug 3

Result
    A file named 'test3.png' is created, layer draw speeds are returned, 
    and some warnings that index qix files are not found, such as:

::

    msLoadMap(): 0.002s
    msDrawMap(): rendering using outputformat named png (AGG/PNG).
    msDrawMap(): WMS/WFS set-up and query, 0.000s
    msDrawRasterLayerLow(bathymetry): entering.
    msDrawRasterLayerGDAL(): Entering transform.
    msDrawRasterLayerGDAL(): src=72,418,3077,2308, dst=0,0,400,300
    msDrawRasterLayerGDAL(): source raster PL (72.095,417.533) for dst PL (0,0).
    msDrawRasterLayerGDAL(): red,green,blue,alpha bands = 1,0,0,0
    msDrawMap(): Layer 0 (bathymetry), 0.017s
    msSearchDiskTree(): Search returned no results. Unable to open spatial index for D:\ms4w\a
    pps\gmap\htdocs/.\../data/land_fn.qix. In most cases you can safely ignore this message, o
    therwise check file names and permissions.
    msDrawMap(): Layer 1 (land_fn), 0.020s
    msSearchDiskTree(): Search returned no results. Unable to open spatial index for D:\ms4w\a
    pps\gmap\htdocs/.\../data/drain_fn.qix. In most cases you can safely ignore this message,
    otherwise check file names and permissions.
    msDrawMap(): Layer 3 (drain_fn), 0.009s
    msDrawMap(): Layer 4 (drainage), 0.040s
    msSearchDiskTree(): Search returned no results. Unable to open spatial index for D:\ms4w\a
    pps\gmap\htdocs/.\../data/province.qix. In most cases you can safely ignore this message,
    otherwise check file names and permissions.
    msDrawMap(): Layer 5 (prov_bound), 0.029s
    msSearchDiskTree(): Search returned no results. Unable to open spatial index for D:\ms4w\a
    pps\gmap\htdocs/.\../data/fedlimit.qix. In most cases you can safely ignore this message,
    otherwise check file names and permissions.
    msDrawMap(): Layer 6 (fedlimit), 0.005s
    msDrawMap(): Layer 9 (popplace), 0.007s
    msDrawMap(): Drawing Label Cache, 0.005s
    msDrawMap() total time: 0.142s
    msSaveImage(test3.png) total time: 0.063s
    shp2img total time: 0.209s

Example #4 Generate a Map Image for a Specific Layer
.............................................................................

::
    
    shp2img -m gmap75.map -o test4.png -l "bathymetry" -map_debug 3

Result
    A file named 'test4.png' is created, and layer draw speeds are returned for 
    1 layer only, such as:

::

    msDrawMap(): rendering using outputformat named png (AGG/PNG).
    msDrawMap(): WMS/WFS set-up and query, 0.000s
    msDrawRasterLayerLow(bathymetry): entering.
    msDrawMap(): Layer 0 (bathymetry), 0.013s
    msDrawMap(): Drawing Label Cache, 0.000s
    msDrawMap() total time: 0.018s
    msSaveImage(test4.png) total time: 0.026s
    
Example #5 Generate a Map Image for Specific (Multiple) Layers
.............................................................................

.. NOTE::
   The syntax for specifying multiple layers is: -l "layer1 layer2 layer3 layer4"

::
    
    shp2img -m gmap75.map -o test5.png -l "bathymetry drain_fn" -map_debug 3

Result
    A file named 'test5.png' is created, and layer draw speeds are returned for 
    only the 2 specified layers, such as:

::

    msDrawMap(): rendering using outputformat named png (AGG/PNG).
    msDrawMap(): WMS/WFS set-up and query, 0.000s
    msDrawRasterLayerLow(bathymetry): entering.
    msDrawMap(): Layer 0 (bathymetry), 0.179s
    msDrawMap(): Layer 3 (drain_fn), 0.041s
    msDrawMap(): Drawing Label Cache, 0.000s
    msDrawMap() total time: 0.226s
    msSaveImage(test4.png) total time: 0.027s