The Map Server executable generates maps from GIS data according to input parameters. It is used for providing a map service from a web server using GCI or FastCGI interface, and it may also be invoked from a command line to generate images without a web server setup.
When used in the GCI or FastCGI environment on a web server, the map server receives an HTTP GET request in the OpenGIS WMS format and returns an image which contains the map image requested by the user. The map server is usually invoked from a simple wrapper script, which hides details of the GIS data setup and map server invocation options, presenting the web application with a logical view of the map generation service. A sample script called GlmScript on Unix/Linux platforms and GlmScript.pl on Windows is provided. Refer to Appendix A: Web Server Installation Notes on page 125 for information more information on the setup script.
The map server supports several OpenGIS WMS request types: GetMap for generating map images, GetFeatureInfo and GetLocationInfo for coordinate conversion and elevation queries, and GetCapabilities for querying capabilities and available datasets.
The map server executable also provides command line options for generating map images and executing other queries without a web server setup, as well as miscellaneous setup and debugging options.
What follows is a description of the command line options of the Map Server executable. It is called GlmMap and is located in the <glg_dir>/bin directory.
All errors produced by the Map Server executable (usually data-related errors) are printed to the standard error (which can be redirected to a file if desired) and also logged into the glm_error.log file in the directory defined by the GLM_ERROR_LOG, GLG_ERROR_LOG or GLG_DIR environment variables. The environment variables are searched in the order above, and if the log file directory is not defined, the current directory is used.
The Map Server uses GLG library, and if there are any GLG errors (such as setting a non-existing resource by an application using the Map Server API) , they are logged in the glg_error.log file, whose location is controlled by the GLG_ERROR_LOG or GLG_DIR environment variables.
By default, the Map Server errors are also written into the generated image, so the user can see what went wrong. This behavior can be toggled.
The Map Server executable. Depending on the command line options, it functions both as an executable to generate map images and perform map queries, as well as the executable for the various data file manipulation utilities.
While most of the command line options differ depending on the desired function, the following two options transcend all uses:
Specifies a file from which to read command line arguments. This option is useful on Windows, where an invocation of the Map Server executable often exceeds the maximum command length.
Defines how verbose the Map Server should be. If verbosity level is set to positive integer value from 1 to 6, diagnostic information will be generated. If verbosity level is set to a negative integer value from -1 to -6, the performance and timing output will be produced. If verbosity level is set to 1001 or 1002, tile extent information is displayed in the generated images for the GetMap requests. The verbosity level of 0 disables all diagnostic output.
The verbosity output is printed to the standard error, the higher the number, the more output is generated. Errors and information are also displayed in the generated image (unless the IERRORS parameter of the map generation request is set to 0) and logged into the glm_error.log file. By default, the verbosity is set to 0.
The -generate option is used to generate map images and execute map queries in the stand-alone mode, either in the CGI environment or from the command line.
The following command line options can be defined after -generate to specify map query parameters:
Defines the location of the Server Dataset File (SDF) to be used by the Map Server. If no root directory is specified within the SDF, the path of the SDF itself will be used as the root.
Specifies whether or not to run in the CGI mode. This options is utilized when run with a CGI (Common Gateway Interface) capable web server. Only the GET method for http requests is supported. In this mode, all map request information (besides the dataset file) will be obtained from the QUERY_STRING environment variable. In order to request a map image when running in this mode, all request information must be appended to the URL, for example:
http://my_web_server.com/cgi-bin/GlmScript?option1=value&Here, GlmScript is a script which invokes the Map Server with the proper dataset file. The options appended to the URL are passed to the Map Server via the QUERY_STRING environment variable. The options are described in Map Query String on page 54. See Examples of OpenGIS map query strings on page 59 for examples.
Windows Note : On Windows, the script is called GlmScript.pl . If the IIS web server is used instead of apache, the cgi-bin directory will be called Scripts .
Same as the - cgi option, except that it enables the FastCGI mode for web servers that support it. In the FastCGI mode, the map server executable does not exit after processing each map request. Instead, it is reused to process other map requests, which makes more efficient use of system resources and map server's tile cache. This results in significant performance increase for map requests that use the same map data tiles.
This mode is transparent to the end user, and the map server is invoked using the same URL as in the CGI mode. If this option is used with a set up that does not support FastCGI, the map server will automatically use the standard CGI mode as a fallback.
The web servers that support FastCGI mode provide a set of parameters to fine-tune the use of the map server in this mode. These parameters define how many of the map server processes may be used and how often they are restarted to avoid memory fragmentation and other potential problems. The FastCGI mode can also be used for distributing the load, off-loading the map server to a remote machine to free the web server. Refer to the FastCGI documentation for more information about potential usage and web server configurations.
This option supplies the OpenGIS map query string when the Map Server executable is used in a stand-alone mode to generate image from a command line, without a web server which supplies the query string in CGI or FastCGI mode. The query string is defined with a series of tokens. Each token is separated with an ampersand (`&' symbol) and those tokens which have values associated with them have their values defined with an equality (=). For example, option1=value1&option2=value2 defines two options each of which has a value associated with it. Refer to Map Query String on page 54 for the query string format information. See Examples of OpenGIS map query strings on page 59 for examples.
Defines an output file for the generated image for the stand-alone usage. This option is only used when the Map Server is not run in the CGI or FastCGI mode, because in these modes the image is outputted to the standard output with the appropriate HTML header. If this option is set to "-", the standard output is used.
The map query string contains all information (other than the dataset file) for generating a map image. The format of the map query string follows the OpenGIS WMS map query standard. The
-oGISreg
command line parameter provides a query string for the stand-alone use of the map server. When the map server is used in the CGI or FastCGI mode, the query string's tokens are provided via the parameters of the map server URL and passed to the map server executable using the standard CGI or FastCGI mechanisms. What follows is a description of valid tokens and their possible values.
Defines the version of the OpenGIS protocol to use. The following versions are supported:
Defines the type of request. The OpenGIS VMS standard version 1.3.0 requires a conforming map server to support at least the GetMap and GetCapabilities requests. The following request types are supported by the GLG Map Server:
GetMap - generates a map image.
GetFeatureInfo - queries information at the X/Y image location defined by the I and J parameters of the request. The type of the returned information (i.e. elevation, lat/lon coordinates, etc.) is defined by the INFO_TYPE parameter.
GetLocationInfo - queries information at a lat/lon location defined by the LON_LAT parameter of the request. The type of returned information (i.e. elevation, lat/lon coordinates, etc.) is defined by the INFO_TYPE parameter.
GetCapabilities - queries information about the capabilities of the Map Server, including a list of layers available in the map server's data directory.
Defines the Spatial Reference System, which specifies the projection to use. Projections are the way the earth is seen. To view the earth as a three dimensional sphere, the Orthographic projection is used. To view the earth as a flat rectangle, the Rectangular projection is used. The SRS codes are defined by the OpenGIS standard. The following SRS projection codes are supported:
EPSG:4326
- rectangular projection, lat/lon
CRS:84
- rectangular projection, lon/lat coordinate order
AUTO:42003,9001,<lon>,<lat>
- orthographic projection with center at lon/lat. The specified lon/lat center will be displayed at the center of the image.
AUTO2:42003,<scale_factor>,<lon>,<lat> - orthographic projection with center at lon/lat and scale factor defining the ratio of the BBOX or EXTENT units to the coordinate system units.
For example, the SRS projection code AUTO2:42003,1.,-97,38 defines an orthographic projection where the point with longitude=-97 degrees and lattitude=38 degrees is displayed at the center of the image.
The SRS projection code SRS=AUTO2:42003,0.3048006096012192,-97,38 defines a similar orthographic projection, but with bounding box units defined in US feet (scale factor = 0.3048006096012192).
Defines the extent of the image. This token is provided to conform with the OpenGIS standard. The EXTENT token is also provided and is simpler to use.
If the rectangular projection is being used, the first two values are the minimum longitude and latitude, respectively, and the last two values are the maximum longitude and latitude, respectively.
If the orthographic projection is being used, the first two values are the minimum horizontal and vertical extent in meters (e.g. the equatorial radius is 6378136 and the polar radius is 6356752) and the last two values are the maximum horizontal and vertical extent in meters. The maximum values must be opposites of the minimum values. If AUTO2 SRS projection is used, the bounding box units are multiplied by the scale factor to convert them to different units.
Defines the counter-clock-wise map rotation angle in degrees for rectangular projections, ignored for orthographic projections.
Defines the background color to be rendered in the map image. The color is a hexadecimal value, such as 0xffffff (white), where the most significant 16 bits (the first two characters) define the red component of the color, the middle 16 bits (middle two characters) defines the green component and the least significant 16 bits (last two chars) define the blue component.
Defines the styles to use. This token exists to conform with the OpenGIS standard and must be set to "default". STYLES is reserved for future extensions.
Defines the file format of the output image for the GetMap request. Must be set to either " image/jpeg " or " image/jpg ".
Defines the layers to turn on in the generated image for the GetMap request. The list must be a comma separated list of layer names or aliases defined in the Server Dataset (SDF) file. For example, the string "earth,cities" specified the earth and cities layers to be rendered.
If default is used as a layer name, all layers that are on by default (DEFAULT ON=1 in the LIF file) will be enabled. If " * " is used as a layer name, all layers will be enabled.
If a layer name starts with `-', the layer is disabled. This may be used to disable some layers enabled by the " default " or " * " layer string values. For example, LAYERS=default,-cities will display all default layers except the cities layer, while LAYERS=*,-cities will show all layers defined in the SDF file except the cities layer.
If a layer name starts with "++" override sign and the overrides are not suppressed by the ALLOW OVERIDE=0, the layer will be displayed regardless on the MIN ZOOM, MAX ZOOM and MAX TILES parameters of the layer. In this case any layer's attribute conditions defined by the ATTR COND directive of the layer's LIF file will also be ignored, and only the attribute conditions defined for the layer in the layer string will be followed.
Note: The `-' and "++" prefixes are not supported for aliases to avoid ambiguities.
If individual layers are listed, the layers will be displayed in the order of their appearance in the layer string. For layers enabled by the default or "*" values of the layer string, their display order is defined by the order in which the layers are listed in the SDF file.
A layer in the LAYERS list may have a list of attribute conditions appended to it, with each condition containing an attribute index starting with `@' character, comparison operation and condition value. For example, if the second attribute (index=1) of the cities layer contains city's population, LAYERS=cities @1>=100000 && @1<500000 may be used to display only cities with population greater than or equal to 100K, but less than 500K. Refer to Attribute Condition Syntax on page 58 for a complete description of the attribute condition syntax.
If the layer has `-' prefix, the condition is reversed and the features matching the attribute condition will not be listed. For example, LAYERS=default,-cities@1<100000 might be used to eliminate cities with population under 100K from the map display that includes the cities layer.
The layer attribute conditions defined in the layer string are logically ANDed with attribute conditions defined in the layer's LIF file using the ATTR COND directive. Only the features that match both sets of conditions will be displayed.
The attribute conditions are processed at run time, and therefore are slower than switching the whole layer on or off. They should be used to filter layer features only when the filter conditions are not known at the design time. If the subsets of a layer which will need to be turned on and off are known at the application design time, it is more efficient to split the layer into a few layers with desired ranges of the attribute value and then switch on and off these new layers. For example, if an application needs to have toggles to control the display of small, medium and large towns and cities, it would be more efficient to split the cities layer into the desired categories based on the value of the population attribute using the Map Server's split utility. However, using attribute conditions is more flexible and convenient when the number of categories is large, or when the thresholds may change frequently.
Defines the longitude and latitude of the center of the map image. This token overrides the center lon/lat specified in the SRS definition. It is used with the EXTENT token and provides an alternative way to specify center of the map as a separate token independent of the SRS definition, for both the rectangular and orthographic projections.
Defines the extent of the map image and provides a more convenient alternative to the BBOX parameter. If the rectangular projection is being used, the two values are the longitudinal and latitudinal extents of the image, respectively. If the orthographic projection is being used, the values are the extent of the image in meters. If AUTO2 SRS projection is used, the extent units are multiplied by the scale factor to convert them to different units.
Defines whether or not to maintain the correct lon/lat aspect ratio. If set to 1, the image will be stretched according to the WIDTH and HEIGHT tokens. If set to 0, the image will maintain its lon/lat aspect ratio. For example, in the orthographic projection, if the entire earth is being viewed, if STRETCH is set to 0, the earth will always appear as a perfect sphere, instead of an oblong one.
Defines whether or not to render errors into the map image. If set to 0, no errors will be rendered. If set to 1, errors will be rendered into the map image in the top left corner. Default value is 1.
Defines whether or not to use anti-aliasing for scaling raster layers. This setting is overwritten by the corresponding setting in the LIF file. The default value is 1.
Defines query layers for GetLocationInfo and GetFeatureInfo requests. For coordinate conversion queries, default may be used. For elevation queries, it is set to the name of the layer that contains elevation data.
Defines the type of the information to be returned for GetLocationInfo and GetFeatureInfo requests. May have the following values:
lat_lon - returns lat/lon coordinates of the requested point
An attribute condition list contains one or more attribute conditions combined using "&&" (local AND) or "||" (logical OR) operations.
Each attribute condition contains an attribute index, comparison operation and condition value. The following comparison operations are supported:
> - greater than (numerical attributes only)
>= - greater than or equal (numerical attributes only)
< -less than (numerical attributes only)
<= -less than or equal (numerical attributes only)
The condition value is interpreted as a numerical value for numerical attributes, or as a string value for string attributes. For string attributes, the string value may contain `?' (one character match) and `*' (multiple characters match) wildcards, in which case it is treated as a regular expression. Spaces are allowed between each element of the attribute condition, and string values containing spaces must be quoted.
Note: When an attribute condition is specified as a value of the command-line attribute in the Unix/Linux environment, it must be quoted, or its special characters must be escaped with `\' to avoid expansion by the shell.
For example, if the second attribute (index=1) of the cities layer contains the city's population, the following attribute condition
@1>=100000 && @1<500000may be used to display only cities with population greater than or equal to 100K, but less than 500K.
If the first attribute of the cities layer contains the name of each city, the following attribute condition
@0 == "New-*"What follows are examples of query strings for generating map images in CGI environment, and corresponding command-line equivalents for testing the query string without a web server setup. These examples use the sample dataset supplied with the Map Server.
Windows Note for all examples : On Windows, the script is called GlmScript.pl , and if using IIS instead of apache, the cgi-bin directory is called Scripts .
The following query will display the map of the United States with state outlines in the orthographic projection using the map server's CGI or FastCGI mode, with grid and states layers:
http://www.myserver.com/cgi-bin/GlmScript?or from the command line (a proper path to the GlmMap executable and sample.sdf file may be required):
GlmMap -generate -dataset sample.sdf -output earth.jpg -oGISreqThe following query will display the view of the whole world in the orthographic projection with political boundaries:
http://www.myserver.com/cgi-bin/GlmScript?The following query will display the world in the rectangular projection with political boundaries:
http://www.myserver.com/cgi-bin/GlmScript?Note: The query request is for use with CGI/FastCGI version of the map server. Refer to the GLG Map Server documentation for the Map Server Library API.
To convert screen coordinates of a point to lat/lon, the GetFeatureInfo request type is used with INFO_TYPE=lat_lon . The I and J parameters of the request supply the X and Y image coordinates of the point of interest, and an optional INFO_FORMAT parameter may be set to either "text/xml" or "text/plain" to specify a desired output format. The map image parameters (i.e. width and height, projection, extent, etc.) need to be supplied as well in order to convert the point's X/Y coordinates to a lat/lon location. The map server will produce an output containing the lat/lon coordinates of the point.
For example, the following coordinate conversion request:
http://www.myserver.com/cgi-bin/GlmScript?will produce the following output:
Content-Type: text/xml <GlmLatLonData> <QueryException>None</QueryException> <Lat>38.000000</Lat> <Lon>-97.000000</Lon> </GlmLatLonData>The following command will produce the same output from the command line:
GlmMap -generate -dataset sample.sdf -oGISreq "VERSION=1.3.0&REQUEST=GetFeatureInfo&To obtain elevation of a point defined by the lat/lon coordinates, the GetLocationInfo request is used with INFO_TYPE=elevation . The LON_LAT parameter provides the lat/lon coordinates of the point. An optional INFO_FORMAT parameter may be set to either "text/xml" or "text/plain" to specify a desired output format.
The following elevation request for a point at a sea level defined by its lat/lon coordinates:
http://www.myserver.com/cgi-bin/GlmScript?will produce the following output:
Content-Type: text/xml <GlmElevationData> <QueryException>None</QueryException> <Elevation>0.000000</Elevation> </GlmElevationData>Note: This example uses elevation layer which is not defined in the sample dataset.
The following command will produce the same output from the command line:
GlmMap -generate -dataset sample.sdf -oGISreqTo obtain elevation of a point defined by a pair of X/Y image coordinates, the GetFeatureInfo request is used instead of GetLocationInfo . The point is defined by its X/Y image coordinates ( I and J requests parameters). The map image parameters (i.e. with and height, projection, extent, etc.) need to be supplied as well in order to convert the point's X/Y coordinates to the lat/lon location:
http://www.myserver.com/cgi-bin/GlmScript?Note: This example uses elevation layer which is not defined in the sample dataset.
The GLG Map Server provides the following utilities:
GVF ASCII/BINARY conversion utility
Image and vector data tiling utility
Hierarchical tile parser and setup files generator
What follows are the command line options required to operate each of these utilities. The same executable is used, and the first option defines the mode.
The -convert option is used to convert GVF files between ASCII and BINARY formats. The ASCII format is cross-platform, but it is slower since the numerical data has to be converted from the string to internal native representation. The BINARY format is faster, but will not allow sharing data between machines with different architectures.
The following command line options are available for the GVF conversion utility.
If used as the first command line argument, will invoke the GVF ASCII/BINARY conversion utility. What follows is a description of subsequent command line options.
Specifies the top-level directory with GVF files to be converted. All subdirectories of this directory will be traversed, making it easy to convert directory-based hierarchical datasets containing large number of files, as well as all GVF files in the map data directory.
Specifies GVF filenames to be converted, may use the "*" and "?" wild cards. If the pattern does not use wildcards, the directory and all its subdirectories are traversed and all files with a specified file name are converted. If the pattern contains the wild cards, all files matching the pattern in the directory and all its subdirectories are converted.
The files are converted in-place and the converted file is saved back into the original file, replacing it. It is recommended to backup the directory before running the conversion utility.
The -merge option is used to merge several vector data files into one GVF file that contains vector features from all merged files.
The following command line options are available for the merge utility.
If used as the first command line argument, will invoke the GVF ASCII/BINARY conversion utility. What follows is a description of subsequent command line options.
Specified the output file for the merged data. The output data are written in the Map Server's GVF format.
Defines the path of an executable file which contains an optional filter to convert vector data from a custom format to the Map Server's GVF format. Examples of filters and a guide to writing them can be found in GVF Filters and Data Converters on page 113.
The -tile option is used for splitting a large high resolution image or vector data file into a number of smaller rectangular tiles for more efficient operation. When the layer is rendered, only the tiles visible in the current map request will be loaded, instead of loading the whole multi-megabyte image or vector file.
In the image mode, -elevation option may be used to tile elevation data. In the vector mode, one of the -pos-range , -neg-range or -no-range options must be specified to define the mode for handling the wrap-around of longitude values. It is used for handling lines that cross the wold boundaries, such as the line extending from lon=359 degrees to lon=361 degrees.
The following command line options are available for the tiling utility.
Specifies the location of the image or vector data file to tile. The image must be either in the JPEG or TIF file formats. The vector data must be in the GVF or shapefile format, unless the -filter option is used to convert the data.
Defines the template to use for outputted tiles. The template must contain two "%" signs to be replaced by numbers representing the horizontal and vertical index of the tile. For example, the first tile, given the template newimage_%_%.jpg will become newimage_0_0.jpg . In the image tiling mode, the format of the generated tiles will be determined by the template's extension or, if it's missing, the extension of the filename parameter. In the vector data tiling mode, the output data files will be written in the GVF format.
The following tiling options are used only with -vector :
Defines the path of an executable file which contains an optional filter to convert vector data from a custom format to the Map Server's GVF format. Examples of filters and a guide to writing them can be found in GVF Filters and Data Converters on page 113.
Specifies the most common -180 to 180 coordinate range for handling the wrap-around of longitude values.
Specifies a 0 to 360 coordinate range for handling the wrap-around of longitude values. This range is used by some datasets, for example, the shorelines data.
Specifies a custom coordinate range for handling the wrap-around of longitude values. The extent of the latitude range are provided by the -min-wlon and -max-wlon options.
These options define the minimum and maximum longitude that appear in a data file for the custom coordinate range. These two options should be used with care as they define the central meridian and where coordinates should be wrapped.
Note : One of the -neg-range , -pos-range , -custom-range , or -no-range options must be specified for tiling vector datasets.
Directs the tiling utility to use the actual extent of the data in the GVF file for calculating extents of the generated tiles.
If the tiles are used in the square tiling mode, the MIN_LON , MAX_LON , MIN_LAT , MAX_LAT parameters of the layer's LIF file must be set to match the GVF extent used to generate the tiles. The -gvf-info command line option may be used to obtain the bounding box of the vector data contained in a GVF file.
If the tiles are used in the tree tiling mode, the Hierarchical Tile Parsing utility automatically handles tile extents.
Directs the tiling utility to use the extent of the whole world for calculating extents of the generated tiles. This option may be used for generating square tiles for a dataset that covers most of the world. The MIN_LON , MAX_LON , MIN_LAT , MAX_LAT parameters of the layer's LIF file must be set to match the whole world extent used to generate the tiles.
Region extent options, define the rectangular region to be used for calculating extents of the generated tiles. These options may be used for square-tiled datasets that cover only a small local area of the map. Tiling such datasets with the -world-extent option would result in the whole dataset being placed in either one tile or in just a few tiles. Defining a custom region using these extent options will generate tiles with boundaries that are better suited to such local-area datasets. The MIN_LON , MAX_LON , MIN_LAT , MAX_LAT parameters of layer's LIF file must be set to match the extent options used to generate the tiles.
Note : One of the -gvf-extent , -world-extent , or -min/max-lat/lon options must be specified for tiling vector datasets.
The following invocation of the image tiling utility will split an image into 100 (10x10) tiles:
GlmMap -tile -image -filename my_image.tifThe -split option is used for splitting vector data file into several files based on the value of some attribute for more efficient operation, extracting data for some region of interest, or splitting large polygon features for faster rendering.
A vector data file may be split in a variety of ways by using different splitting options:
-bbox option extracts and saves vector features that intersect the lat/lon region specified with the bounding box. If the -num-x-tiles and -num-y-tiles options are used, the file is also split into the requested number of rectangular tiles, as described in Tiling Utility for Image and Vector Data on page 66.
-attr option extracts and saves vector features that have the value of the specified attribute matching specified attribute condition. For example, it may be used to split a data file containing all roads into several files each containing the roads of a certain type: primary roads, secondary roads, local roads, etc., based on the value of their CFCC code attribute. Each of the split data file may be set up as a separate layer, making it easier to switch each road type display on or off, and loading data only for the type of roads that needs to be displayed.
-num-points
option splits all polygons into smaller segments, up to the specified maximum number of points. Consider an example when a vector data file contains a shoreline of the whole continent as one polygon, with tens of thousands of points. Even if the map is zoomed on a small region, the whole shoreline has to be traversed to figure out what segments of it have to be rendered. Splitting the shoreline into smaller segments with, for example, five hundred points in each segment, will significantly increase the layer's rendering speed.
After the shoreline has been split into smaller segments with
-num-points
, it also becomes possible to split the data file into tiles using the tiling utility, which wouldn't work when the shoreline was defined as one large object (see below).
Note: Splitting into smaller segments should not be used for filled polygons, as it will distort the filled area. For more efficient rendering of large filled polygons, consider using smaller areas, for example, use state boundaries instead of the US boundaries to fill the background.
Only one of -bbox, -attr or -num-points splitting options can be used at once. To split based on several conditions or to split into several attribute ranges, the splitting utility should be invoked several times, once for each condition.
When tiling is performed, the utility does not split vector features that intersect several tiles. Instead, it replicates these features in each of the tiles. Therefore, tiling a dataset that contains a shoreline of America in the form of one polygon with thousands and thousands of points into 10x10 tiles would not do any good, as the shoreline would be replicated in each of the tiles. Since the shorelines are usually rendered as unfilled edge polygons, the right way of doing the tiling would be using the
-num-points
option first to split the shoreline into smaller segments, and only then split the data file into tiles. The number of points in the segments should be chosen depending on the size of one tile, so that each tile contains at least a few segments.
For -bbox and -num-points , one of the -pos_range , -neg_range , -custom-range or -no-range options must be specified to define the mode for handling the wrap-around of longitude values. It is used for handling lines that cross the world boundaries, such as the line extending from lon=359 degrees to lon=361 degrees.
The following command line options are available for the vector data splitting utility.
If used as the first command line argument, will invoke the vector data tiling and splitting utility. What follows is a description of subsequent command line options.
Specifies the location of the vector data file to tile. The data must be either in the Map Server's GVF or shapefile format, unless a filter is used.
Specified the output file for the processed data. The output data are written in the Map Server's GVF format.
If the vector data is also being split into multiple tiles using the -num-x-tiles and -num-y-tiles options, the -output option must specify a tiling template. The template must contain two "%" signs to be replaced by numbers representing the horizontal and vertical index of the tile. For example, given the template newvector_%_%.gvf , the first tile will become newvector_0_0.gvf .
Defines the path of an executable file which contains a filter to convert vector data from a custom format to the Map Server's GVF format. Examples of filters and a guide to writing them can be found in GVF Filters and Data Converters on page 113.
Defines an attribute condition or list of attribute conditions used to split the vector data. Only the vector features that match the attribute condition will be written. If -attr is used multiple times to specify several sets of attribute conditions, a vector feature will be written if it matches any of the specified conditions. The -invert-attr option may be used to invert attribute conditions.
For example, the following command-line option will select all vector features that have the value of the second attribute (index=1) within the specified range:
-attr "@1>=100000 && @1<500000"Refer to Attribute Condition Syntax on page 58 for a complete description of the attribute condition syntax.
Note: On Unix/Linux systems, the value of the -attr option must be quoted to avoid expansion by the shell. Alternatively, all special characters in the attribute condition, including the quotes that are part of the string value must be escaped with `\'.
Inverts attribute conditions. Outputs only vector features that do not match any of the conditions specified with the -attr option.
Specifies that only vector features fitting into a certain rectangular region should be outputted.
To be used with the -bbox option, defines the minimum and maximum longitude and latitude of a rectangular region: all vector features intersecting this region will be outputted.
Defines an optional number of horizontal and vertical tiles to tile the output into for the -bbox option (default is 1). If values different from 1 are used, the -output option must specify a tiling template.
Defines the maximum number of points an outputted polygon may have. This is useful for data that contains polygons with large numbers of points. A common value is 10. For example, if there exists a 36 point polygon in the file, the utility will split the polygon into 4 polygons with at most 10 points each. Note : This option cannot be used with filled polygons.
Specifies the most common -180 to 180 coordinate range for handling the wrap-around of longitude values.
Specifies a 0 to 360 coordinate range for handling the wrap-around of longitude values. This range is used by some datasets, for example, the shorelines data.
Specifies a custom coordinate range for handling the wrap-around of longitude values. The extent of the latitude range are provided by the -min-wlon and -max-wlon options.
The options define the minimum and maximum longitude that appear in a data file for the custom coordinate range. These two options should be used with care as they define the central meridian and where coordinates should be wrapped.
Note : One of the -neg-range , -pos-range , -custom-range , or -no-range options must be specified for the -bbox and -num-points split modes.
The following invocations of the vector splitting utility will split a dataset file. First, the data will be split into polygons of no more than 10 points:
GlmMap -split -neg-range -filename data_orig.gvf -num-points 10Then, only the data in the boundaries of the U.S. will be extracted:
GlmMap -split -neg-range -filename data_10.gvfFinally, the data will be tiled into 100 tiles (10x10):
GlmMap -tile -vector -neg-range -filename data_US.gvfThe last two operations could be combined and performed in one step:
GlmMap -split -neg-range -filename data_10.gvfThe -slim option is used for slimming high-resolution datasets to generate lower-resolution overview layers.
The following command-line options are supported for the slimming utility:
Specifies the location of the vector data file to tile. The data must be either in the Map Server's GVF or shapefile format, unless a filter is used.
Specified the filename to output the processed data to. The output data files are written in the Map Server's GVF format.
The -shp2gvf option is used for converting shapefiles to the Map Server's GVF format. While the shapefiles may be used without conversion, it is more efficient to preprocess and convert them to GVF format at the setup time. The conversion parameters also allow to eliminate the shapefile attributes that are not used for rendering the data.
The -r option may be used to convert all shapefiles in a directory structure. By default, the output will be written into a file whose name is formed by adding the ".gvf " extension to the name of the shapefile.
The -show-attrs options may be used to display shapefile's attributes. The -verbose option may be used to display the content of the shapefile being converted.
The following command-line options are supported for the shapefile conversion utility:
Specified an optional output file for the processed data when a single shapefile is being processed. If not specified, the output will be written into a file whose name is formed by adding the ".gvf" extension to the name of the corresponding shapefile.
Defines a shapefile name pattern for the recursive option. When a directory is traversed, all shapefiles whose name matches the pattern will be converted. Wild cards are supported and the default value is " * ".
Recursive mode. If a directory is specified as an input file, all its subdirectories will be traversed as well, and all shapefiles matching the pattern will be converted.
Causes all shapefile attributes to be written into the GVF file in the order they are defined in the shapefile. This is the default when no attributes are defined with the -attr option.
Writing all attributes is excessive: only a small number of attributes defined in a shapefile is used at rendering time. Use -attr option to define the attributes to be written into the GVF file.
Specifies an index of the shapefile attribute to be included into the output. More than one attribute option may be specified. The attributes will be converted in the order they are defined: the attribute specified by the first -attr option will be written into the GVF file as an attribute with index=0, the second - as attribute index=1, and so on. Shapefile attributes of the types FTInteger and FTDouble are written into the GVF file as double attributes, and shapefile attributes of FTString type are written as string attributes.
If the -attr option is used, only the specified shapefile attributes will be written into the GVF file, and the rest of the attributes will be discarded. If no attributes are specified, all attributes will be written.
Specifies an optional index of the shapefile attribute to be used for the label string of point features. The index must point to an attribute of FTString type.
If -marker-label-attr is defined, point features are written into the GVF file as markers of the GVF_M_LABEL type with the label string. If -marker-label-attr is not defined, point features from the shapefile are written as marker objects of the GVF_M_MARKER type, and the LABEL FORMAT LIF option may be used to display one of the marker attributes as its label.
The following command will convert the shorelines.shp shape file and write the GVF output into the shorelines.gvf file, discarding all shapefile attributes:
GlmMap -shp2gvf -no-attrs -filename shorelines.shpThe same, but preserving all shapefile attributes in the GVF file:
GlmMap -shp2gvf -all-attrs -filename shorelines.shpThe following command will preserve just two shapefile attributes with indices 2 and 4, saving them as the GVF attributes with index 0 and 1:
GlmMap -shp2gvf -attr 2 -attr 4 -filename shorelines.shpThe following command will display all attributes of a shapefile without converting the data:
GlmMap -shp2gvf -show-attrs -filename shorelines.shpThe following command will convert all shapefiles in the my_shapefile_data directory, writing the converted data into the corresponding files with the ".gvf" extension:
GlmMap -shp2gvf -r -all-attrs -filename my_shapefile_data -pattern *.shpThe -lif option is used for automatic generation of setup files for directory-based vector or raster datasets containing multiple data files in hierarchically organized subdirectories. Each data file will be handled as a tile.
Vector tiles may be non-rectangular and grouped in geographical or administrative regions. The subdirectories contain tiles for one region, for example a state. Each of the state subdirectories, in turn, may contain another level of subdirectories containing data files for counties, and so on, with no limit on the depth of the hierarchy. Such organization of data is called hierarchical tree tiling, and it is used in datasets such as the US Census Tiger/Line data, Digital Chart of the World (DCW/VMAP) dataset, and many others.
Image tiles are always rectangular, but may cover non-rectangular area with some tiles missing. The image tiles may be grouped in geographical or administrative non-rectangular regions as well.
The utility traverses all subdirectories of the dataset, extracting the extent information for each data file. For each traversed directory, the utility writes the directory's Sub-Layer File (SLF), that includes the list of all data files and subdirectories in the directory, as well as the combined extent information for all directory entries. The extent information in the SLF file enables the Map Server to efficiently determine if any given subdirectory of the dataset is needed for rendering the current map request, and to do so without traversing each of the data files and subdirectories it contains.
The top-level SLF file generated by the utility for the top-level directory of the dataset is included in the layer's LIF file using TILES SUBLIF parameter. The LIF file will contain user defined attributes, while the included SLF file is generated by the utility and contains data description. This way, if the SLF file is regenerated, user defined layer data, such as LINE WIDTH , EDGE COLOR and other visual attributes, will not be lost.
The utility needs to be run for the initial setup of a hierarchical tree-tiled datasets, or when data files are added or changed.
What follows is a description of command line options for both vector and image mode.
Specifies the vector mode for processing vector data tiles. Tile extent information will be extracted from the GVF data files.
Specifies the image mode for processing image tiles. Tile extent information is extracted from the SLF files which are associated with the image files and were produced by the image import and conversion utility.
Specifies the single layer mode. In this mode, all tiles specified by the pattern parameter are combined into a single layer. tiles. This is the default for the image mode.
Specifies the multi-layer mode for processing vector tiles. In this mode, the tiles specified by the pattern parameter are combined into multiple layers based on their names. For example, all roads.gvf files located in any of the tile subdirectories will be aggregated into the road layer with the roads.gvf.slf name used for its SLF file, all lakes.gvf files will be aggregated into a lakes layer with lakes.gvf.slf SLF file, and so on. This mode is available only for the vector data and is used for processing all layers of the DCW and TIGER datasets at once.
Defines the top-level directory of the dataset to start parsing from, either as an absolute path or relative to the current directory.
Defines a filename pattern that describes what files to look for in the specified path. Wild cards are supported.
In the multi-layer mode for vector data, the pattern should match the names of the vector data files. The dataset may contain data files for all layers combined in the same directories, and all of them may be processed at once by using "*.gvf" as a pattern. For example, a US dataset may contain a number of state subdirectories, each containing data for roads, land and water features. Each state directory may contain subdirectories containing data for its counties, and so on. The data files for the road features will be named the same way in all state and county subdirectories, and the same is true for the land and water data files.
By using `*.gvf" as a pattern, all datasets will be processed at once, generating SLF files for roads, land and water features in each of the dataset's subdirectories. The top-level directory of the dataset will contain the top-level SLF files generated for the road, land and water layers.
These top-level SLF files will contain cumulative information for each layer's data and should be included in the corresponding layer LIF files using the TILES SUBLIF directive.
The parsing utility traverses the directory structure looking for data files that match the pattern. When a matching data file is found, a Sub-Layer File (SLF) is generated for it. It will contain the extent of the vector data in that file and the name of the file. The name of the SLF file is formed by adding the .slf extension at the end of the file name.
For each directory containing data files matching the pattern, the utility writes a directory SLF file that contains cumulative extent of all data files in the directory and all its subdirectories. Since the utility may be invoked to process directory structure that may contain data for more then one layer, one subdirectory SLF file is written for each layer. The name of each directory SLF file is the same as the name of the corresponding SLF written for the data file. If a directory contains both the data files and subdirectories with data files, the data file SLF is using .sub.slf extension to avoid name conflicts. This process is repeated recursively for all directories in the hierarchy to an unlimited depth.
In the single layer mode for vector data, the tile parsing utility has to be run once for each vector layer, with the pattern set to match the names of the layer's .gvf files and the -out-lif-name providing the name of the generated directory SLF files for that layer. For each directory that contains matching data files, the utility generates a directory SLF file containing cumulative extent of all data files in the directory and all its subdirectories.
The parsing utility traverses the directory structure looking for the GVF files that match the pattern. When a matching data file is found, a Sub-Layer File (SLF) is generated for it. It will contain the extent of the vector data in that file and the name of the file. The name of the SLF file is formed by adding the .slf extension at the end of the file name.
For each directory containing GVF files matching the pattern, the utility writes a directory SLF file that contains cumulative extent of all GVF files in the directory and all its subdirectories. The -out-lif-name parameter defines the name of the generated directory SLF files. This process is repeated recursively for all directories in the hierarchy to an unlimited depth.
In the single layer mode for image, the image import and conversion utility has to be run first to produce image SLF files containing georeferencing information for each image file. Names of these files are formed by adding the ".slf" extension to the corresponding image filename.
After that, the tile parsing utility has to be run once for each image layer, with the pattern set to match the names of the image SLF files for the layer and the -out-lif-name providing the name of the generated directory SLF files for that layer. For each directory that contains matching data files, the utility generates a directory SLF file containing cumulative extent of all data files in the directory and all its subdirectories.
The directory SLF files that are generated for the top level directory are included in the corresponding layer LIF files using the TILES SUBLIF directive.
The parsing utility traverses the directory structure looking for the image SLF files that match the pattern. These files were generated by the image import and conversion utility and contain the names and extent of a corresponding image file.
For each directory containing SLF files matching the pattern, the utility writes a directory SLF file that contains cumulative extent of all image files in the directory and all its subdirectories. The -out-lif-name parameter defines the name of the generated directory SLF files. This process is repeated recursively for all directories in the hierarchy to an unlimited depth.
Specifies the name for the generated directory SLF files for the single-layer mode and is ignored in the multi-layer mode. In the single layer mode, all tiles are combined in one layer and the filename is used for the generated directory SLF files in each of the subdirectories of the dataset. The directory SLF file generated in the top-level directory is included in the layer's LIF file using the TILES SUBLIF directive. Unique filenames must be used for generating SLF files for different layers.
The following command will generate SLF files for all layers of the hierarchically tiled vector dataset in the my_vector_data directory:
GlmMap -lif -vector -multi-layer -path my_vector_data -pattern *.gvfThe top-level SLF files generated in the my_vector_data directory are then included into the corresponding layers' LIF files using the TILES SUBLIF directive.
The following command will generate directory SLF files for one layer of the hierarchically tiled image dataset in the my_image_data directory:
GlmMap -lif -image -path my_image_data -pattern \*.GN\?.tif.slfIt will generate directory SLF files by combining image information from all files ending with ".GN?.tif.slf", which were generated by the image import utility, and writing out combined GN.slf files for the layer. The ` ? ' wildcard in the pattern was used to match a single character, to select files ending with ".GN1.tif.slf", ".GN2.tif.slf", and so on. The top-level GN.slf file in the my_image_data directory is then included into the layer's LIF file using the TILES SUBLIF directive.
The GIS image import utility is used for importing raster and elevation data in various image interchange formats and converting them to the more common TIFF or JPEG formats. This eliminates dependencies on various image format libraries at run time and greatly reduces the complexity and size of the map server executable. The utility is based on the GDAL1 library and is provided for the Linux platform by default.
The utility may be used with several processing mode options to perform various raster data processing:
-write-image option is used to convert images to TIFF or JPEG.
-elevation option is used to convert elevation data to a single-channel TIF file.
-shadow option is used to generate a shadow relief image in JPEG format from the input elevation data and may be used in conjunction with the -elevation option or stand-alone.
-slf option scans the input files and generates SLF setup files with extent information for them. It may be used in conjunction with the -write-image , -elevation and -shadow options or stand-alone. The hierarchical data parsing utility may then be used to combine these SLF files into a directory SLF file for a layer, which is included into the layer's LIF file.
For hierarchical directory-based datasets, the utility may be invoked in the recursive mode, traversing all subdirectories of the dataset and processing all files that match a specified pattern.
What follows is a description of command line options.
Verbose mode. When set to value greater than 0, produces verbose output according to the specified verbosity level.
Used with other options to perform a "dry run", printing out information, but not writing out any output files.
Converts input images to the image format defined by the -out-format option. Each converted image is written to a file whose name is formed by adding the suffix defined by the -out-ext option to the name of the corresponding input image file. Using this option requires the gdal_translate utility to be present on the system and in the search path.
Handles input files as elevation data and writes the output as elevation data in the single-channel TIFF format. The name of the output file is formed by adding the ".tif" suffix to the name of the corresponding input file.
Handles input files as elevation data and generates shadow relief images in JPEG format for each of them. The name of each generated shadow relief image file is formed by adding the ".jpg" suffix to the name of the corresponding input file.
Generates SLF setup files containing image extent for each of the input raster files. The name of each generated SLF file is formed by adding the suffix defined by the -out-ext option and then the ".slf" suffix to the name of the corresponding input image file.
Specifies a GDAL-supported raster format for the converted image generated using the -write-image option. Use GTiff to generate TIFF files, or JPEG for JPEG files. Refer to the documentation of the gdal_translate utility for a list of available GDAL output raster formats.
Specifies a suffix added to the name of the original input file to produce the name of the output file. This option is mandatory.
Specifies an optional suffix added to the name of the output file prior to adding the suffix specified by the -out-ext option.
Specifies an optional filename pattern for recursive mode. Only the input files matching the pattern will be processed. The pattern may contain the `*' and `?' wild cards, which must be escaped with `\' in Unix environment. The default pattern is "*" and all files in the directories are processed.
Recursive mode. If a directory is specified as an input file, all its subdirectories will be traversed as well, and all files matching the pattern will be converted.
Disables compression for the files generated with the -write-image option. By default, LZW compression is used for the converted image files.
In case of an error, skip the error file and continue. By default, the utility stops on the first encountered error. This option may be used for processing large image datasets which may contain a few files with errors.
The following command converts all raster files in the current directory with the ".nitf" extension to TIFF and generates SLF setup files for them:
gis_image_import -write-image -slf -out-ext ".tif"The following command processes the directory-based hierarchical dataset in the NITF_dir directory, converting all ".nitf" files to TIFF and generating SLF setup files:
gis_image_import -r -k -verbosity 1 -write-image -slf -out-ext ".tif" -out-format GTiff -pattern \*.nitf NITF_dirThe following command converts DTED elevation tiles of a directory-based hierarchical dataset in the DTED_dir directory to a single-channel TIFF elevation tiles, generating SLF setup files for them:
gis_image_import -r -elevation -slf -out-ext ".tif"The following command regenerates SLF files for the elevation tiles generated in the previous example without generating the TIFF files:
gis_image_import -r -slf -out-ext ".tif" -pattern \*.dted DTED_dirNote the use of the ".tif" extension, which should match the extension used for the generated elevation tiles.
The following command generates shadow relief images for the DTED elevation dataset used above and generates SLF setup files for the shadow relief tiles:
gis_image_import -r -shadow -slf -out-ext ".jpeg"1. Copyright (c) 2000, Frank Warmerdam.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.