PREV NEXT

Generic Logic, Inc. www.genlogic.com


3 Using the Map Server and Utilities

3.1 Map Server Executable

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 153 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, GetSelection for getting information about objects inside the map at the mouse location, 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.

Error handling

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.

Synopsis

GlmMap [options]

Description

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.

Command Line Options

While most of the command line options differ depending on the desired function, the following options transcend all uses:

-help

Prints all available command-line options in the terminal window.

-version

Prints the map server version.

-arg-file <file>

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.

-verbosity <number>

Defines how verbose the Map Server should be. The verbosity level values are handled differently depending on the mode the map server executable was started in: to generate a map or perform a map query in the map server mode, or to perform data massaging in the utility mode. The following lists the use of the verbosity values in both modes.

In the Map Server mode:
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 as tile outlines in the generated images for the GetMap requests. The 1003 verbosity level displays vector tiles coverage as filled areas without displaying the tiles' content. 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.
In the Utility mode:
Setting verbosity level to an integer value from 1 to 6 prints information about the data being processed according to the specified verbosity level. The verbosity level of 0 disables all diagnostic output. By default, the verbosity is set to 0.
-progress <number>

In the Utility mode, prints progress information for every N processed files, where N is the option value. The default value is 100. Use 0 to suppress progress reporting.

Map Generation and Queries

Synopsis

GlmMap [-arg-file] -generate [-verbosity N] [options]

Description

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.

Options

The following command line options can be defined after -generate to specify map query parameters:

-dataset <file>

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.

-cgi

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&

option2=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 the Map Query String section on page 66. See the Examples of OpenGIS map query strings section on page 72 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.

-fcgi

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.

-oGISreq <string>

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 the Map Query String section on page 66 for the query string format information. See the Examples of OpenGIS map query strings section on page 72 for examples.

-output <file>

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.

-max-iterations <N>

Defines the maximum number of internal iterations used to render filled polygons, which prevents rendering delays if the map is zoomed in too much. This parameter may need to be increased if large filled polygons (such as OSM country or state areas) are rendered with very high zoom levels. This value may be overridden by the MAX ITERATIONS parameter in the dataset's SDF file.

Map Query String

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.

VERSION=<version>

Defines the version of the OpenGIS protocol to use. The following versions are supported:

REQUEST=<request type>

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:

SRS=<value>

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:

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).

WIDTH=<number>

Defines, in pixels, the width of the image to be generated.

HEIGHT=<number>

Defines, in pixels, the height of the image to be generated.

BBOX=<min,min,max,max>

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.

ANGLE=<number>

Defines the counter-clock-wise map rotation angle in degrees for rectangular projections, ignored for orthographic projections.

BGCOLOR=<color>

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.

STYLES=<value>

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.

FORMAT=<image format>

Defines the file format of the output image for the GetMap, as well as the output format for the GetSelection request. Must be set to either image/jpeg or image/jpg for GetMap, and to text/plain or text/xml for GetSelection.

LAYERS=<list>

Defines the layers to turn on in the generated image for the GetMap request, as well as vector layers to be queried for the GetSelection 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 dataset attribute, 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. By default, the overrides are allowed only for untiled layers.

Note: The `++' prefix is not supported for the default layer and aliases to avoid ambiguities.
The "-" prefix can be used with both the default layer and aliases. However, it does not disable an individual layer in the default layer or an alias if this layer is explicitly listed in the LAYERS string.

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 the Attribute Condition Syntax section on page 71 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.

CENTER=<lon,lat>

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.

EXTENT=<x,y>

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.

STRETCH=<0 or 1>

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.

IERRORS=<0 or 1>

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.

IMAGE_ANTIALIASING=<0 or 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.

QUERY_LAYERS=<layer name>

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.

INFO_TYPE=<info type>

Defines the type of the information to be returned for GetLocationInfo and GetFeatureInfo requests. May have the following values:

INFO_FORMAT=<info format>

Defines the output format for the GetFeatureInfo, GetLocationInfo and GetCapabilities requests, as well as the error format for the GetMap request. May be set to text/xml or text/plain. Default value is text/xml for the CGI use and text/xml when invoked from the command line.

I=<number>

Defines X coordinate of the image point for the GetFeatureInfo and GetSelection requests.

J=<number>

Defines Y coordinate of the image point for the GetFeatureInfo and GetSelection requests.

LON_LAT=<lon,lat>

Defines lat/lon coordinates of the point for the GetLocationInfo request.

SELECT_LABELS=<value>

Specifies a global label selection mode for the GetSelection request:

The global label selection mode may be overridden by a layer's LABEL SELECTION MODE setting in the layer's LIF file.

PICK_RESOLUTION=<number>

Specifies pick resolution in pixels for the GetSelection request (default 2). All objects within this distance from the selection point will be reported in the GIS selection.

Attribute Condition Syntax

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. A special attribute index value of -4 may be used to reference the current zoom factor.

The following comparison operations are supported:

== - equal
!= - not equal
> - 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 either quoted or the spaces in the values have to be escaped with the backslash to treat them literally. The backslash cannot be used with wildcards, which are always handled as special wildcard characters. An empty string can be defined by using two quotes: "".

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.

Examples of Attribute Conditions

For example, if the second attribute (index=1) of the cities layer contains the city's population, the following attribute condition

@1>=100000 && @1<500000 

may 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-*" 

will display only the cities whose names start with "New-".

Examples of OpenGIS map query strings

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?

VERSION=1.3.0&REQUEST=GetMap&

SRS=AUTO2:42003,1.,-97.,38.&

WIDTH=700&HEIGHT=700&

BBOX=-2500000,-2500000,2500000,2500000&

BGCOLOR=0x0&

STYLES=default&

FORMAT=image/jpeg&

LAYERS=earth,grid,states&

STRETCH=0

The same on Windows with IIS:

http://www.myserver.com/Scripts/GlmScript.pl?

VERSION=1.3.0&REQUEST=GetMap&

SRS=AUTO2:42003,1.,-97.,38.&

WIDTH=700&HEIGHT=700&

BBOX=-2500000,-2500000,2500000,2500000&

BGCOLOR=0x0&

STYLES=default&

FORMAT=image/jpeg&

LAYERS=earth,grid,states&

STRETCH=0

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 -oGISreq

"VERSION=1.3.0&REQUEST=GetMap&

SRS=AUTO2:42003,1.,-97,38&

WIDTH=700&HEIGHT=700&

BBOX=-2500000,-2500000,2500000,2500000&

BGCOLOR=0x0&

STYLES=default&

FORMAT=image/jpeg&

LAYERS=earth,grid,states&

STRETCH=0"

The following query will display the view of the whole world in the orthographic projection with political boundaries:

http://www.myserver.com/cgi-bin/GlmScript?

VERSION=1.3.0&REQUEST=GetMap&

SRS=AUTO2:42003,1,10.,40.&

WIDTH=700&HEIGHT=600&

BBOX=-6500000.,-6500000.,6500000.,6500000.&

BGCOLOR=0x0&

STYLES=default&

FORMAT=image/jpeg&

LAYERS=earth,political&

STRETCH=0

or on the command line:

GlmMap -generate -dataset sample.sdf -output earth.jpg -oGISreq

"VERSION=1.3.0&REQUEST=GetMap&

SRS=AUTO2:42003,1,10.,40.&

WIDTH=700&HEIGHT=600&

BBOX=-6500000.,-6500000.,6500000.,6500000.&

BGCOLOR=0x0&

STYLES=default&

FORMAT=image/jpeg&

LAYERS=earth,political&

STRETCH=0"

The following query will display the world in the rectangular projection with political boundaries:

http://www.myserver.com/cgi-bin/GlmScript?

VERSION=1.1.0&REQUEST=GetMap&

SRS=EPSG:4326&

WIDTH=800&

HEIGHT=600&

BBOX=-180,-90,180,90&

BGCOLOR=0x0&

STYLES=default&

FORMAT=image/jpeg&

LAYERS=earth,political&

STRETCH=1

or on the command line:

GlmMap -generate -dataset sample.sdf -output earth.jpg -oGISreq

"VERSION=1.1.0&REQUEST=GetMap&

SRS=EPSG:4326&

WIDTH=800&

HEIGHT=600&

BBOX=-180,-90,180,90&

BGCOLOR=0x0&

STYLES=default&

FORMAT=image/jpeg&

LAYERS=earth,political&

STRETCH=1"

Examples of coordinate conversion and elevation queries

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.

Coordinate Conversion Query

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?

VERSION=1.3.0&REQUEST=GetFeatureInfo&

SRS=AUTO:42003,9001,-97.,38.&

WIDTH=400&HEIGHT=400&

BBOX=-2500000,-2500000,2500000,2500000&

STRETCH=0&

QUERY_LAYERS=default&

INFO_TYPE=lat_lon&

INFO_FORMAT=text/xml&

I=200&J=200

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&

SRS=AUTO:42003,9001,-97.,38.&

WIDTH=400&HEIGHT=400&

BBOX=-2500000,-2500000,2500000,2500000&

STRETCH=0&

QUERY_LAYERS=default&

INFO_TYPE=lat_lon&

INFO_FORMAT=text/xml&

I=200&J=200"
Elevation Query for a Lat/Lon location

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?

VERSION=1.3.0&REQUEST=GetLocationInfo&

QUERY_LAYERS=elevation&

INFO_TYPE=elevation&

INFO_FORMAT=text/xml&

LON_LAT=10.,-30.

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 -oGISreq 

"VERSION=1.3.0&

REQUEST=GetLocationInfo&

QUERY_LAYERS=elevation&

INFO_TYPE=elevation&

INFO_FORMAT=text/xml&

LON_LAT=10.,-30."
Elevation Query for an X/Y image point

To 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 request 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?

VERSION=1.3.0&

REQUEST=GetFeatureInfo&

SRS=AUTO:42003,9001,-97.,38.&

WIDTH=400&HEIGHT=400&

BBOX=-2500000,-2500000,2500000,2500000&

STRETCH=0&

QUERY_LAYERS=default&

INFO_TYPE=elevation&

INFO_FORMAT=text/xml&

I=200&J=200

or from the command line:

GlmMap -generate -dataset sample.sdf -oGISreq "VERSION=1.3.0&

REQUEST=GetFeatureInfo&

SRS=AUTO:42003,9001,-97.,38.&

WIDTH=400&HEIGHT=400&

BBOX=-2500000,-2500000,2500000,2500000&

STRETCH=0&

QUERY_LAYERS=default&

INFO_TYPE=elevation&

INFO_FORMAT=text/xml&

I=200&J=200"

Note: This example uses elevation layer which is not defined in the sample dataset.

GIS Selection Query Example

To query a list of objects selected by the mouse click in the map generated by the GetMap request, the GetSelection request must provide all parameters that were used to generate the map, such as projection, center, extent, etc. The LAYERS parameter must be provided as well, but its value is different for this request and defines a vector layer (or list of layers) to be queried. Additionally, the GetSelection request must provide the I and J parameters to specify selection point location in pixels relatively to the map image origin, as well as the SELECT_LABELS parameter that controls label selection. The FORMAT parameter defines the output format and may be set to text/plain or text/xml.

For example, the following selection request:

http://www.myserver.com/cgi-bin/GlmScript?

VERSION=1.3.0&REQUEST=GetSelection&

SRS=EPSG:4326&STRETCH=1&

WIDTH=800&HEIGHT=600&BBOX=-180,-90,180,90&

LAYERS=us_cities&I=241&J=384&

SELECT_LABELS=INTILE&FORMAT=text/plain

or a command from the command line:

GlmMap -generate -dataset sample.sdf -oGISreq "VERSION=1.3.0&

REQUEST=GetSelection&

SRS=EPSG:4326&STRETCH=1&

WIDTH=800&HEIGHT=600&BBOX=-180,-90,180,90&

LAYERS=us_cities&I=241&J=384&

SELECT_LABELS=INTILE&FORMAT=text/plain"

may produce the following text output:

GlmMap: Info: Selection in layer: us_cities
GlmMap: Info:   Selection type: object
GlmMap: Info:   Feature type: marker
GlmMap: Info:   Feature id: 7dc97c70
GlmMap: Info:   Feature lon: -86.158056
GlmMap: Info:   Feature lat: 39.768333
GlmMap: Info:   Num attrs: 3
GlmMap: Info:     Attribute: 0
GlmMap: Info:       Attribute value: INDIANAPOLIS
GlmMap: Info:     Attribute: 1
GlmMap: Info:       Attribute value: 700807
GlmMap: Info:     Attribute: 2
GlmMap: Info:       Attribute value: IN

The output includes attributes of the selected city defined in the GVF file: a city name, its population and the state code.

The FORMAT parameter may be changed to text/xml to generate XML output.

3.2 Tools and Utilities

The GLG Map Server provides the following utilities:

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.

Converting GVF ASCII and BINARY Files

Synopsis

GlmMap [-arg-file] -convert [-verbosity N] [-progress N] [options]

Description

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.

Options

The following command line options are available for the GVF conversion utility.

-convert

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.

-a

Saves the converted GVF file in the ASCII format.

-b

Saves the converted GVF file in the BINARY format.

-path <directory>

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.

-pattern <file_name_pattern>

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.

Examples

The following command converts all GVF files in the directory and all its subdirectories to BINARY GVF format:

GlmMap -convert -b -path /usr/local/map_data -pattern \*.gvf

The `*' wildcard is escaped to pass it unchanged and prevent the shell from expanding it. It is not needed on Windows.

Merging Vector Data Files

Synopsis

GlmMap [-arg-file] -merge [-verbosity N] [-progress N] [options] files

Description

The -merge option is used to merge several vector data files into one GVF file that contains vector features from all merged files.

Options

The following command line options are available for the merge utility.

-merge

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.

-output <file>

Specified the output file for the merged data. The output data are written in the Map Server's GVF format.

-filter <file>

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 141.

-a

Saves the merged GVF file in the ASCII format.

-b

Saves the merged GVF file in the BINARY format.

Examples

The following merges all GVF files in the current directory and writes the result into the merged.gvf file:

GlmMap -merge -output merged.gvf *.gvf

Bounding Box Extraction Utility

Synopsis

GlmMap [-arg-file] -gvf-info [-verbosity N] [-progress N] files

Description

The -gvf-info option is used to display the bounding box of all vector features in each of the specified GVF files. The bounding box information may be used for specifying the MIN LAT, MAX LAT, MIN LON and MAX LON LIF parameters for layers that use square tiles.

Examples

The following displays bounding boxes of all GVF files in the current directory:

GlmMap -gvf-info *.gvf

Tiling Utility for Image and Vector Data

Synopsis

GlmMap [-arg-file] -tile [-verbosity N] [-progress N] [options]

Description

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.

Options

The following command line options are available for the tiling utility.

-tile

If used as the first command line argument, will invoke the image tiling utility.

-image

Specifies the image tiling mode.

-vector

Specifies the vector data tiling mode.

-filename <file>

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.

-template <string>

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.

-num-x-tiles <number>

Defines the number of horizontal tiles to tile into.

-num-y-tiles <number>

Defines the number of vertical tiles to tile into.

Image Tiling Options

The following tiling option is used only with -image:

-elevation

Specifies the elevation mode for tiling single-channel TIFF files containing int16, uint16 or float32 elevation data.

Vector Data Tiling Options

The following tiling options are used only with -vector:

-filter <file>

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. If a filter string contains the "%" character, it will be replaced with the file specified by the -filename option, otherwise the file will be appended at the end of the filter string. Examples of filters and a guide to writing them can be found in GVF Filters and Data Converters on page 141.

-neg-range

Specifies the most common -180 to 180 coordinate range for handling the wrap-around of longitude values.

-pos-range

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.

-no-range

Suppresses handling of the wrap-around of longitude values.

-custom-range

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.

-min-wlon <number>
-max-wlon <number>

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.

-gvf-extent

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.

-world-extent

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.

-min-lat <number>
-max-lat <number>
-min-lon <number>
-max-lon <number>

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.

-a

Saves the converted GVF file in the ASCII format (default).

-b

Saves the converted GVF file in the BINARY format.

Examples

The following invocation of the image tiling utility will split an image into 100 (10x10) tiles:

GlmMap -tile -image -filename my_image.tif 

-num-x-tiles 10 -num-y-tiles 10 

-template my_image_tiles_%_%.jpg

The same for vector data:

GlmMap -tile -vector -neg-range -world-extent -filename my_vector.gvf 

-num-x-tiles 10 -num-y-tiles 10 

-template my_vector_tiles_%_%.gvf 

Splitting Vector Data

Synopsis

GlmMap [-arg-file] -split [-verbosity N] [-progress N] [options]

Description

The -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:

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.

Options

The following command line options are available for the vector data splitting utility.

-split

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.

-filename <file>

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.

-output <file>

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.

-filter <filter>

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. If a filter string contains the "%" character, it will be replaced with the file specified by the -filename option, otherwise the file will be appended at the end of the filter string. Examples of filters and a guide to writing them can be found in GVF Filters and Data Converters on page 141.

-attr <conditions>

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 the Attribute Condition Syntax section on page 71 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 `\'.

-invert-attr <index>

Inverts attribute conditions. Outputs only vector features that do not match any of the conditions specified with the -attr option.

-bbox

Specifies that only vector features fitting into a certain rectangular region should be outputted.

-min-lat <number>
-max-lat <number>
-min-lon <number>
-max-lon <number>

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.

-num-x-tiles <number>
-num-y-tiles <number>

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.

-num-points <number>

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.

-neg-range

Specifies the most common -180 to 180 coordinate range for handling the wrap-around of longitude values.

-pos-range

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.

-no-range

Suppresses handling of the wrap-around of longitude values.

-custom-range

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.

-min-wlon <number>
-max-wlon <number>

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.

Examples:

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 10 

-output data_10.gvf

Then, only the data in the boundaries of the U.S. will be extracted:

GlmMap -split -neg-range -filename data_10.gvf 

-bbox -min-lat 25 -max-lat 50 -min-lon -120 -max-lon -70 

-output data_US.gvf

Finally, the data will be tiled into 100 tiles (10x10):

GlmMap -tile -vector -neg-range -filename data_US.gvf 

-num-x-tiles 10 -num-y-tiles 10 -output data_tiled_%_%.gvf

The last two operations could be combined and performed in one step:

GlmMap -split -neg-range -filename data_10.gvf 

-bbox -min-lat 25 -max-lat 50 -min-lon -120 -max-lon -70 

-num-x-tiles 10 -num-y-tiles 10 -output data_tiled_%_%.gvf

Slimming Utility for Vector Data

Synopsis

GlmMap [-arg-file] -slim [-verbosity N] [-progress N] [options]

Description

The -slim option is used for slimming high-resolution datasets to generate lower-resolution overview layers.

Options

The following command-line options are supported for the slimming utility:

-slim

If used as the first command line argument, will invoke the vector data slimming utility.

-filename <file>

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.

-output <file>

Specified the filename to output the processed data to. The output data files are written in the Map Server's GVF format.

-resolution <dir>

Defines the slimming resolution in lat/lon degrees. All polygon features with extents smaller than the resolution value will be eliminated, and all polygon points with distances between them less than the resolution value will be merged.

-a

Saves the converted GVF file in the ASCII format (default).

-b

Saves the converted GVF file in the BINARY format.

Examples

The following command will slim the GVF file to the resolution of 0.1 degree:

GlmMap -slim -resolution -filename shorelines.gvf

-output shorelines_0.1.gvf

Shapefile Conversion Utility

Synopsis

GlmMap [-arg-file] -shp2gvf [-verbosity N] [-progress N] [options] 

[list of shapefiles or directories to convert]

Description

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 -verbosity option may be used to display the content of the shapefile being converted.

The -gvf-info command line option may be used to obtain the bounding box of the generated GVF file to use it in a LIF file. See the Bounding Box Extraction Utility section on page page 80 for details.

Options

The following command-line options are supported for the shapefile conversion utility:

-shp2gvf

If used as the first command line argument, will invoke the shapefile conversion utility.

-output <file>

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.

-pattern <pattern>

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 "*".

-r

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.

-a

Saves the converted GVF file in the ASCII format (default).

-b

Saves the converted GVF file in the BINARY format.

-show-attrs

Prints out the content of the shapefile's attribute table without converting the data.

-dump

When used with -show-attrs, dumps attribute values.

-no-header

Suppresses the output of an attribute table header for the -dump option.

-m

Specifies a multi-line mode for the -dump option.

-raw

When used with -dump, dumps raw attribute values with no formatting.

-all-attrs

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.

-no-attrs

Causes no shapefile attributes to be written into the GVF file.

-attr <index>

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.

-marker-label-attr <index>

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.

-close-polygons

Coverts polylines to polygons by adding a closing segment.

Examples

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 -output shorelines_0.1.gvf shorelines.shp

The same, but preserving all shapefile attributes in the GVF file:

GlmMap -shp2gvf -all-attrs -output shorelines_0.1.gvf shorelines.shp

The 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 -output shorelines_0.1.gvf 
shorelines.shp

The following command will display all attributes of a shapefile without converting the data:

GlmMap -shp2gvf -show-attrs shorelines.shp

The 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 -pattern *.shp my_shapefile_data

Hierarchical Tile Parsing (Advanced)

Synopsis

GlmMap [-arg-file] -slf [-verbosity N] [-progress N] [options]

Description

The -slf 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.

Options

What follows is a description of command line options for both vector and image mode.

-slf

If used as the first command line argument, will invoke the hierarchical tile parsing utility.

-vector

Specifies the vector mode for processing vector data tiles. Tile extent information will be extracted from the GVF data files.

-image

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.

-single-layer

Specifies the single layer mode. In this mode, all tiles specified by the pattern parameter are combined into a single layer. This is the default for the image mode.

-multi-layer

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.

-path <dir>

Defines the top-level directory of the dataset to start parsing from, either as an absolute path or relative to the current directory.

-suppress-bbox

Suppresses generation of the inlined BBOX for included SLFs. By default, the extent of the bounding box is added to each included SLF line using the BBOX descriptor to increase performance of large hierarchical data sets.

-pattern <pattern>

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. For each layer, the provided pattern parameter has to match the names of the .gvf files for that layer, and the -out-slf-name parameter should provide the name of the generated directory SLF files for the 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-slf-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-slf-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-slf-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.

-out-slf-name <filename>

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.

Examples

The following command will generate SLF files for all layers of the hierarchically tiled vector dataset in the my_vector_data directory:

GlmMap -slf -vector -multi-layer -path my_vector_data -pattern *.gvf

The 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 -slf -image -path my_image_data -pattern \*.GN\?.tif.slf 

-out-slf-name GN.slf

It 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.

Image and Elevation Data Import (Advanced)

Synopsis

gis_image_import [options] <list of input image files or directories>

Description

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:

The output file name is derived by adding an extension specified with the -out-ext option to the original file name.

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.

Options

What follows is a description of command line options.

-verbosity <level>

Verbose mode. When set to value greater than 0, produces verbose output according to the specified verbosity level in the range from 1 to 10. By default, the verbosity is set to 1 to print only the basic information.

-progress <number>

Prints progress information for every N processed files, where N is the option value. The default value is 100. Use 0 to suppress progress reporting.

-info-only

Used with other options to perform a "dry run", printing out information, but not writing out any output files.

-write-image

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.

-elevation

Handles input files as elevation data and writes the output as elevation data in the single-channel TIFF format. The output data format (int16, uint16 or float32) is chosen as a closest match to the format of the input data. The name of the output file is formed by adding the ".tif" suffix to the name of the corresponding input file.

-shadow

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.

For large data files, verbosity values greater than 8 may be used to indicate the progress of the shadow relief image generation.

-data-shift

Specifies an optional data shift value used to fit sample data into a single byte used for generating shadow relief image. The default shift value is 6, which discards 6 lower bits of the elevation data in the int16 and uint16 formats to accommodate heights up to 16383 (2^14- 1). For data files with low elevation, discarding the lower bits will result in the zero elevation values. For such data files, a lower data shift may be used. For example, for data files where with maximum elevation values do not exceed 255 (2^8 -1 ), a data shift value of 0 may be used, effectively scaling the range to have 255 as the range high. The resulting shadow relief image will have exaggerated shadow compared with images that used the default data shift value.

The -verbosity option with a value greater than 3 may be used to output information about the range of values in the input data file, which may be used to select a proper data shift value.

-data-offset

Specifies an optional data offset value to be added to each sample's data when generating shadow relief image from data in the int32 format. The shadow relief image generation process discards negative elevation data, since negative values are often used to represent areas with missing data. If negative data have to be included into the generated shadow relief image, a positive offset may be specified to shift all data upwards to make a desired range of data positive. The default offset value is 0.

The -verbosity option with a value greater than 3 may be used to output information about the range of values in the input data file, which may be helpful for selecting a proper data offset value.

-slf

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.

-out-format <format>

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.

-out-ext <extension>

Specifies a suffix added to the name of the original input file to produce the name of the output file. This option is mandatory.

-postfix <extension>

Specifies an optional suffix added to the name of the output file prior to adding the suffix specified by the -out-ext option.

-pattern <pattern>

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.

-r

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.

-u

Disables compression for the files generated with the -write-image option. By default, LZW compression is used for the converted image files.

-k

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.

-f

In case of an error, still try to process the file if possible. This option may be used to force the utility to save the converted file in spite of some errors, in order to inspect the content of the file for the clues on the causes of the error.

-dont-emboss

Modifies the -shadow option behavior to write the output JPEG file as is, without embossing it. This option may be used to debug problems with the input elevation data files.

Examples

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" 

-out-format GTiff *.nitf

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_dir

The 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" 

-pattern \*.dted DTED_dir

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_dir

Note 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" 

-pattern \*.dted DTED_dir

1Copyright (c) 2000, Frank Warmerdam.
1Permission 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.
1THE 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.

Generic Logic, Inc.
www.genlogic.com
PREV NEXT