2 Structure of Data and File Layout
On the surface, any given map image generated by the GLG Map Server appears to be a collection of lines, areas, images and text. Each of these elements and its attributes must be defined somewhere. Due to the sheer number of objects that many map images require, it is not practical to describe each object separately, especially when many objects share common attributes and require similar operations to be performed on them.
The GLG Map Server provides a way to consistently and efficiently describe data being processed, so as to minimize the redundancy of setup. The following sections will explain the different types of data, how data is described, how it is organized into datasets, layers, tiles and objects, and where the data and descriptions are stored.
The following chapter will describe the three main types of files.
- Server Dataset File (SDF), the master file that lists all fonts and layers
- Layer Information File (LIF), layer files that describe data
- GVF Data Files, which contain the actual data that is used by the Map Server
2.1 Types of Data
The GLG Map Server can process two different kinds of data: raster image data and vector data. Raster image data can be used to view such features as land and ocean cover on a map as well as transparent weather maps or even custom detailed images of local terrain. Vector data can be used to view such features as roads, county areas or shorelines, as well as text labels and map grids.
All data are organized into layers. For image data, each layer control the use of one raster image (the image may actually be a collection of image tiles). For vector data, the layer may contain a collection of similar vector features, such as roads or state boundaries, defined in a single GVF file.
Each layer's properties are defined in its Layer Information File (LIF). For vector layers the LIF file also defines common rendering attributes for all objects in the layer.
Each layer may be enabled or disabled, allowing the user to control what features are shown on the generated map.
Raster image data can itself come in two different file formats. Currently, the GLG Map Server supports both the JPEG, TIFF and PNG file formats. Baseline JPEG files are supported (except those with color-table information), as well as scan-line TIFF, but not TIFF tiles. Instead, the Map Server has its own tiling mechanism. See the Tiling section on page 37 for details.
The raster data may be used as non-transparent background images, or as semi-transparent weather or elevation data to be combined with other image or vector layers.
The NASA Earth Image1 supplied as part of the sample dataset provides an example of using image tiles and fallback layers for different zoom factors. A shaded relief layer of the sample dataset demonstrates the use of shaded relief images2 to visualize terrain elevation.
World Satellite Images with 250m and 15m per pixel resolution are available from Generic Logic as preprocessed datasets ready to be used with the Map Server. They are tiled for optimum performance and include a complete set of setup and configuration files. US Aerial Images for individual US states with 0.5 per pixel resolution can also be provided.
Since vector data can come in many different specialized formats, the Map Server reads its own GVF vector data file format. Files in this format often have the .gvf extension. In order to interface with the myriad other file formats available, the Map Server provides a programmable filter interface by which a file can be loaded through a filter that reads the original data and converts it to the Map Server's format. The converted data can also be converted just once and saved into a GVF file for efficiency. The Map Server provides convenience functions for writing GVF format to assist application developers in writing filters and data converters.
Some commonly used GIS data, such as Open Street Map (OSM), Digital Chart of the World (DCW) and US Census Tiger data, are available in the converted GVF format from Generic Logic. The converted data are preprocessed into hierarchical tiled layout for optimum performance with the Map Server and include a complete set of setup files.
The Map Server's vector file format supports two different types of objects: polygons, and markers with text. All polygons are represented as a group of points. Each point is defined as a horizontal and a vertical coordinate. Each marker is represented as one point which defines the location of the marker and a text string, if any, to be rendered at that location. The text may be rendered using either the vector or TrueType font.
All common properties used to render vector object, such as Line Width or Fill Color, are not defined in the data files for each individual object. They are instead provided in the descriptions of the layer (LIF file) for efficiency. These properties are referred to as layer attributes.
In the programming interface, a resource mechanism similar to that of the GLG Toolkit is used. Resources and layer attributes refer to the same property, but differ in their method of access. Layer attributes are initially defined in the layer's configuration file (LIF file), and then can be accessed via resources.
Each object in a GVF data file can contain what are known as attributes, which is data other than points or strings associated with the object. Each object can have an arbitrary number of attributes, which are numbered, and can be used in the description of the data to customize how each object is displayed.
For example, if a data file contains marker objects that represent cities and towns, the object is also likely to contain information about its population. In this case, an object's first attribute might be the city's name, while the second attribute might be its population. The population attribute may be used to vary the size of the marker used to represent the city, as well as the size of the font used to display its name. It may also be used to show only large cities at the low zoom levels, and display smaller cities and towns as the map is zoomed in.
Attributes associated with data objects in the data file function are almost identical to attribute objects in the GLG Toolkit. Just as in the GLG Toolkit, property is often used as a synonym.
There are three types of attributes that the Map Server supports. A Double attribute (otherwise known as a D attribute) can be used to express a floating point value. The Geometrical type (3 floating point values, otherwise known as a G attribute) can be used to express a 3 dimensional set of coordinates or a color in the RGB color space. A String (S) attribute can be used for names, as well as any other attributes that cannot be encoded as D or G attributes. Sometimes, it may seem more appropriate to use an integer for an attribute, such as the population of a city or the number of precincts in a state, but D attributes are used throughout for consistency with the GLG Toolkit and various API function calls.
Attributes are not named in the traditional sense. Instead, their names are 0-based integral numbers. These numbers are defined in the data file. For example, the city name may be defined as attribute 0, the city area defined as attribute 1 and the population defined as attribute 2. Some objects may have attributes that are not present in other objects. For example, some cities might not have information about their area. So, some objects will have the area (attribute 1) and the population (attribute 2), while other objects lacking the area information will just have population (attribute 2). To handle objects that do not have a complete set of attributes present, the integral number representing the name of the attribute is encoded as part of the attribute record.
Attribute conditions may be used to display only the objects that match the attribute conditions. For example, attribute conditions can be used to display only cities with population greater than 500K. Attribute conditions may be defined in the layer's LIF file or in the Layers string. Defining attribute conditions in the Layers string allows the application to dynamically control which objects will be displayed in the layer. Refer to the ATTR COND layer attribute on page 40 and the Layers string on page 69 for more information.
The 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, and only the objects that match both sets of conditions will be displayed.
Attributes can also be used to change appearance of objects depending on their attributes. For example, the size of a city marker can be changed to reflect a city's population, so that bigger markers will be used for larger cities. The ATTRIBUTE MAP feature described on page 57 is an example of using object attributes to change the object's appearance.
The map server supports both TrueType and vector fonts that can be used for rendering text labels in the generated map image. A font directory of the sample map data provided with the GLG installation (map_data/fonts) contains the following fonts:
True Type fonts:
Additional fonts can be added by placing font files into the font directory. Google Fonts catalog provides a variety of free TrueType fonts that may be browsed and downloaded from the following link:
The open source fonts in the Google Fonts catalog are published under licenses that allow you to use them in both commercial and non-commercial applications.
The font aliases feature described on page 34 allows using multiple fonts with different charsets to render layers with labels that contain characters in different languages, such as English, Korean, Arabic, etc.
2.2 Datasets, Layers, Tiles and Data
At the most fundamental level, there exists data, either in the form of a raster image or vector data such as polygons, markers and text. In order for the Map Server to read and interpret this data, it needs to know where it resides and how to render it. This is done with Layer Information Files (LIF), which usually have the .lif extension for recognition. A LIF describes a data file or a group of data files, and defines common properties such as Line Width and Fill Color. The layer is somewhat analogous to a Group Object in the GLG Toolkit.
When requesting a map image from the Map Server, the user is in essence requesting which layers he/she wants to appear in the image. Therefore, the Map Server must know which layers can possibly be requested by the user. In order to provide this information, a Server Dataset File is used. It often has the .sdf extension. The Server Dataset File contains information about all layers, where to find their LIF files, as well as the location of the font files for vector and TrueType fonts.
2.3 Configuration File Format
All configuration files, such as the SDF and LIF files, have a similar configuration entry format. Comments can appear as lines starting with a hash (#) symbol. All lines not starting with a hash symbol will be assumed to be configuration entries. All entries appear as at least one word, usually the name of the configuration variable, written in capital letters followed by an equal sign and then its value.
For example, the following line may be used in the configuration file to define the line width of polygons:LINE WIDTH=1
Three data types of configuration variables are supported: D (double), G (XYZ or RGB values), or S (string). All D variables must be entered as a single floating point number. All G variables must be entered as three floating point numbers, either with white space in between each number or separated by commas. S variables can be entered either with or without quotes, except for the case described below where quotes are required.
Commas or white spaces are also used as separators between individual strings when a list containing several strings is used. For example, the TEXT ANCHOR option requires two anchor type values, one for horizontal and another for vertical anchoring, separated by either a white space or a comma:TEXT ANCHOR= HLEFT VCENTER
If the user wants to assign a string containing either a white space or a comma to an S variable, quotes must be used. Hence:FILENAME=file.gvf FILENAME= file.gvf FILENAME="file.gvf"
are all valid. However,FILENAME=" file.gvf"
is not valid if the data file is indeed called file.gvf, because use of quotes will pick up the white space within them. The following shows an example of setting a configuration variable value where the quotes are required due to spaces in the variable value:FILL TYPE= "FILL AND EDGE"
An empty string may be defined by two quote characters: "".
The backslash has a special meaning and is used as an escape character. The following C-style escape characters are supported in strings:
- \n - a new line character
- \" - a literal quote character
- \\ - a literal backslash character
The backslash may also be used to escape comma and white space separators. The following shows an alternative way of defining FILL AND EDGE fill type:FILL TYPE= FILL\ AND\ EDGE
While it is a valid entry, using double quotation marks around the string with spaces and/or commas may still be a more readable approach.
All undefined variables assume reasonable default values. For example, the LINE WIDTH variable takes the default value of 1, i.e. one pixel thick lines will be rendered for polygons in that layer.
If variables are redefined, the last definition is the one which will be used, unless some intermediate variables depend on a previous definition.
A Server Dataset File (SDF) enumerates all possible layers that the user can request as well as defines names for them, defines all fonts the Map Server has access to, and also specifies root directories where fonts and layers can be found.
What follows is a list of all possible configuration variables in an SDF file.
GLM ROOT DIR=<dir>
Defines where to look for all files; may also be relative to current directory. All files needed for the Map Server are relative to the GLM ROOT DIR unless an absolute path is used. If this variable is not specified in the SDF, it will default to the directory in which the SDF itself resides. The location of the SDF is specified as a command line option upon invocation of the Map Server executable, so the GLM ROOT DIR may be inherent to that invocation.
Defines where the Map Server should look for layers. This entry is either an absolute filename or relative to the GLM ROOT DIR. If any relative path for a layer is later specified, it will be assumed to be relative to the LAYER DIR.
Defines where the Map Server should look for vector and TrueType font files. This entry is either an absolute filename or relative to the GLM ROOT DIR. If any relative path for a font is later specified, it will be assumed to be relative to the FONT DIR.
Defines where to find a layer. Must specify the name by which this layer is later referred to in a query and where to find a LIF file for that layer. The path is relative the LAYER DIR unless an absolute path is used. This variable definition may be used multiple times in succession to define multiple layers.
Defines an alias which maps a single alias name to a list of layer names specified by the alias value. Aliases may be used to hide details of the dataset layers organization, providing a convenient way to reference collections of layers. When an alias name is encountered in the layer string, it is replaced with its value, and the process is repeated recursively to handle any aliases which may be a part of the substituted alias value. The alias value must be quoted if it contains spaces, commas and any other special characters. The alias name should be different from the names of layers, fonts and reserved GLG resources.
The alias value may also contain attribute conditions described in the Attribute Condition Syntax section on page 71. For example, if the city layer has population as the second attribute (index=1), the following alias:ALIAS=big_cities "earth,cities@1>500000"
may be used in the layer string to display cities with population greater than 500000 with the earth image in the background.
To avoid ambiguities, the "++" override prefix is not allowed in front of the alias name when it is used in the layer string, but may be used as prefixes of layer names in the alias value. The "-" prefix may be used in front of the alias name in the layer string to disable the alias. However, it does not disable the individual layers in the alias if these layers are explicitly listed in the layer string. The "-" may also be used as a prefix of a layer name in the alias value to selectively disable the layer.
ZOOM FACTOR TYPE= <EXTENT or "EXTENT AND WIDTH">
Defines how the zoom factor is calculated. If it is set to EXTENT (default), the zoom factor is calculated based on the map's GIS extent and will not change when the size of the map image changes. If it is set to EXTENT AND WIDTH, the zoom factor will also increase or decrease proportionally to the new map size, with the exact ratio being controlled by the BASE WIDTH attribute described below. This may be used to display more detailed layers for larger maps. Refer to the The Zoom Factor section on page 37 for details.
BASE WIDTH= <value>
Defines the base size of the map (600 by default) for the
ZOOM FACTOR TYPE=EXTENT AND WIDTH. When the size of the generated map image changes, the zoom factor is changed by the a ratio of the map pixel width to the value of the base width attribute. For example, if the map width increases to twice the value of the BASE WIDTH attribute, the zoom factor will increase by the factor of 2.
Since the zoom factor calculation depends on the value of BASE WIDTH, the value of the BASE WIDTH attribute may be used to adjust at what point the map layers are activated and deactivated. For example, if BASE WIDTH is increased by the factor of two, it will decrease the calculated Zoom Factor by the same factor, and all layers whose visibility is controlled by the MIN ZOOM attribute will be activated when the map is zoomed in twice more compared to the previous BASE WIDTH value.
VECTOR FONT=<font_name> <font_file>
Defines where to find a vector font. Must specify the name by which this font is later referred to and where to find the data for the vector font. The path is relative the FONT DIR unless an absolute path is used. The Map Server supports Hershey vector fonts. This variable definition may be used multiple times in succession to define multiple fonts.
IMAGE FONT=<font_name> <font_file>
Defines where to find a TrueType font. Must specify the name by which this font is later referred to and where to find the data for the font. The path is relative the FONT DIR, unless an absolute path is used. This variable definition may be used multiple times in succession to define multiple fonts. The unicode characters are supported with the TrueType fonts.
Any TrueType font installed on the system can be used with the Map Server by copying it into the Map Server's font directory (or creating a symbolic link on UNIX systems). If only TrueType fonts and no vector fonts are used, the FONT DIR may be set to point to the system's font directory.
The TrueType font support is provided via the freetype library3.
FONT ALIAS=<font_alias_name> "<font_name>,<font_name>,..."
Font alias defines a comma-separated list of fonts that can be used to render layers with labels that contain characters in different languages, such as English, Korean, Arabic, etc. Such layers can use the font alias name instead of a font name as a value of the FONT variable in the layer's LIF file. When a label containing characters in multiple charsets is rendered, for each of the label's characters, the renderer searches all fonts defined in the font alias and uses the first font that supports the character's charset. This makes it possible not only to use labels that use different charsets, but also mix characters from different charsets in the same label.
Note: Vector fonts can't be used with font aliases.
Defines the dataset's default font. It is used for all text labels that do not specify the font explicitly. The default value is roboto.
Defines the dataset's error font used for rendering error messages. If omitted, the dataset's default font is used.
ENCODING=<UTF8 or LATIN>
Specifies the encoding used for the text strings. The default encoding is UTF8.
ALLOW OVERRIDE=<0, 1 or 2>
Defines the default setting for the use of the "++" override in the layer string. If set to 0, disallows the use of the override for all layers. Setting it to 1 (default) allows overrides for untiled layers, and suppresses overrides for tiled layers to avoid unintended consumption of significant memory and CPU resources. The setting of 2 allows overrides for all layers of the dataset.
MAX IMAGE TILES
Defines the maximum number of all image tiles that may be kept in the tile cache. While the MAX CACHE SIZE parameter of the layer controls the per-layer cache size, MAX IMAGE TILES may be used to control the total maximum size of the image tile cache for all layers, which is useful for datasets with a large number of layers.
The default value of -1 allows the unlimited total size of the image tile cache. If the parameter is set to a positive value, the image tile cache will be flushed if necessary after rendering each layer to prevent uncontrolled growth of the cache.
MAX VECTOR TILES
Defines the maximum number of all vector tiles that may be kept in the tile cache. While the MAX CACHE SIZE parameter of the layer controls the per-layer cache size, MAX VECTOR TILES may be used to control the total maximum size of the vector tile cache for all layers, which is useful for datasets with a large number of layers.
The default value of -1 allows the unlimited total size of the vector tile cache. If the parameter is set to a positive value, the vector tile cache will be flushed if necessary after rendering each layer to prevent uncontrolled growth of the cache.
GLYPH CACHE TYPE=<type>
Specifies the type of the glyph cache to use and may be set to NONE or GLOBAL (default). The cache is used to increase performance of TrueType font rendering.
Defines the maximum number of internal iterations used to render filled polygons (default 10000), 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.
A Simple Example of an SDF fileGLM ROOT DIR=/usr/local/glm/map_server/ LAYER DIR=layers FONT DIR=fonts LAYER=earth earth.lif LAYER=cities /home/user/cities.lif VECTOR FONT=roman romans.data IMAGE FONT=roboto_m Roboto-Medium.ttf DEFAULT FONT=roboto_m
In this example, The Map Server will look for earth.lif in /usr/local/glm/map_server/layers/earth.lif, but cities.lif will be found in /home/user/cities.lif. It will look for romans.data and Roboto-Medium.ttf font files in the /usr/local/glm/map_server/fonts directory.
Layers and Tiles
Layers are the best way an end user of a mapping application can interact with the Map Server. When a user requests a map image, he/she will be specifying which layers they want to be displayed. These layers are then superimposed in the final map image in the order they are specified in the query string. Each layer is described in a Layer Information File (LIF). This file contains information on what format the data is in, where to locate the data, and common attributes to assign to the data such as colors and line width.
There are a number of ways to control whether a layer is rendered into a map image or not. Primarily, it will be the end user that specifies which layers he/she wishes to be rendered into the final map image. However, there are a number of mechanisms that turn the layer on or off automatically, without user interaction.
When setting up the Map Server, any layer can be defined to be on by default. By specifying the default layer, all layers that have the default flag will be turned on. "default" is a reserved layer name which is associated with all layer with the flag turned on. For example, a query string that requests default,clouds,cities will render all default layers as well as the clouds and cities layer. A layer may also be "subtracted" from the default set of layers by using the "-" prefix. For example, the default,-cities query string will render all default layers but the cities.
Also, for those layers that utilize tiles, a maximum number of tiles may be defined. If the number of tiles required to render the map image exceeds a predefined number, the layer is not rendered, or a fallback layer is rendered instead. For example, if looking at the entire earth, a lower resolution earth image will be used, because the maximum number of tiles for the detailed earth image will be exceeded.
Finally, if the zoom factor exceeds a predefined number defined by the MAX ZOOM attribute or is less than a predefined number defined by MIN ZOOM, the layer will not be rendered. For example, a roads layer is only necessary when zoomed in sufficiently to distinguish unique roads.
The Zoom Factor
The Zoom Factor is a ratio that measures how "zoomed in" a map image is. A simple way to see what the Zoom Factor is for a specific map request is to increase the verbosity, which will cause the Zoom Factor to be printed to the error interface, stderr, as well as written in the image. By default, the Zoom Factor is the same for all map layers and is the reciprocal of the proportion of the entire world that is visible. For example, if the entire world is visible, the Zoom Factor will be 1. If one half of the world is visible, the Zoom Factor will be 2. If the proportion of the horizontal extent of the layer or world is different from the proportion of the vertical extent visible, the greater of the two Zoom Factors is used.
For layers with relative zoom enabled, the Zoom Factor is calculated for that specific layer as the reciprocal of the portion of the layer that is visible. Refer to the RELATIVE ZOOM layer attribute on page 38 for more information.
The dataset's ZOOM FACTOR TYPE attribute may be used to change the Zoom Factor depending on the map image size. When the ZOOM FACTOR TYPE is set to EXTENT (default), the Zoom Factor is calculated based on the map's GIS extent and will not change when the size of the map image changes. If it is set to EXTENT AND WIDTH, the Zoom Factor will also increase or decrease proportionally to the new map size. The BASE WIDTH attribute of the dataset defines the base map size used in zoom factor calculations. For example, if the width of the map increases to twice the value of the BASE WIDTH attribute, the Zoom Factor will increase by the factor of 2. Refer to the description of the ZOOM FACTOR TYPE and BASE WIDTH attributes on page 34 for details.
In many cases, it is not feasible or necessary to load all data into the Map Server. For example, if looking at only one country, it is not necessary to load the entire image of the earth. Also, the entire earth image takes 400 megabytes of space, so using it would utilize a lot of memory and make the Map Server unnecessarily slow. Instead, the Map Server provides a tiling mechanism to alleviate this problem. Only the tiles needed to render a given map image are loaded, which cuts down on memory usage and enhances performance. Tiling capabilities exist for both raster image and vector data. There exist two types of tiling: Rectangular and Hierarchical.
Rectangular tiling is used for image layers and vector data split into rectangular tiles. However, vector data is often split and provided with non rectangular tiles. This happens if the data is grouped by political boundaries, for example. In this case, the Map Server's Hierarchical Tiling can read a directory structure with all the tiles in various locations and use only the ones necessary. For example, the directory hierarchy may contain directories with countries, which contain directories with provinces or states, which may contain directories with counties and/or towns.
LIF files for hierarchical tiling provide the extent of the layer, including all sublayers. This allows the Map Server to quickly read the LIF files to determine which tiles are needed to generate the requested image. The Map Server provides a utility to automatically generate hierarchical LIF files.
What follows is a list of all possible configuration variables in a LIF.
Defines a layer's type and corresponds to the type of data used to render the layer. Can be either:
- IMAGE (default)
The first two layer types correspond to the type of their data: raster or vector. These are the main GIS layers that render either raster or vector data of the map image.
The last three types are special vector layers that have no data file associated with them and are defined completely within its respective LIF. The grid layer draws grid and grid labels, the outline layer draws a filled or unfilled outline. For example, an oval globe outline is drawn in the ORTHOGRAPHIC projection, and a rectangular outline of the whole world is drawn in the RECTANGULAR projection. The background layer is used to render a gradient around the globe in the ORTHOGRAPHIC projection.
Any variables which do not apply to a given layer type will be ignored. For example, the format of the image data clearly does not apply to a vector layer, so it will be ignored if defined for a vector layer.
DEFAULT ON=<0 or 1>
Defines whether or not a layer will be turned on by default, i.e. when a default layer name is included in the map request. The default value is 0, meaning it will not be included. Setting the value to 1 will include the layer into the "default" layer.
RELATIVE ZOOM=<0 or 1>
Specifies whether or not the relative zoom feature of the Map Server is used for this layer. This variable can take a value of either 0 (default) or 1. If set to 1, the layer's zoom factor is calculated using the extent of the layer. If set to 0, the zoom factor is calculated using the entire extent of the world.
MIN ZOOM and MAX ZOOM attributes can be used to turn layers on or off depending on the map zoom level. See the Layers and Tiles section on page 36 for details.
In most cases, it is preferable to disable RELATIVE ZOOM, because the user often does not know and does not need to know the extent of the layer. However, if a layer provides detailed imagery for a small area, relative zoom may be used to activate the layer when the map is zoomed on the area: the layer's zoom factor will be 1 when the map extent equals to the layer extent.
Defines what blending function is to be used when rendering the layer. This variable is very similar to the use of blending functions in OpenGL. The following values are supported:
- OPAQUE (default)
- ALPHA WHITE OPAQUE
- ALPHA BLACK OPAQUE
- TRANSPARENT COLOR OPAQUE
- BUMP MAP
The most common type is OPAQUE. This name is slightly misleading because it does not mean that the layer is necessarily fully opaque. What it does mean is that if its transparency is turned off (ALPHA=1), it will be fully opaque. The other two blending functions render layers similarly to how OpenGL renders light-maps. When set to ALPHA WHITE OPAQUE, the brighter the color, the more opaque it is. This option is commonly used when rendering transparent cloud layers, as a black pixel in the cloud image specifies no cloud cover, while a white pixels specifies full cloud cover. When set to ALPHA BLACK OPAQUE, the darker the color, the more opaque it is. This is identical to the default blending function for the second OpenGL texture unit (used for light maps). A white pixel will be transparent, while a black pixel will be opaque.
The TRANSPARENT COLOR OPAQUE type is similar to OPAQUE, but with the color defined by the TRANS COLOR LIF parameter rendered as transparent. If the type is set to XOR, the color will be XOR'ed with the pixel in the image. This causes lines to stand out, and is very useful for grid layers, where it is desirable to have grid lines that always contrast with the background.
The BUMP MAP option is used for rendering shaded relief images.
Defines which color to render as transparent for the TRANSPARENT COLOR OPAQUE rendering mode. The value must be three double values ranging from 0 to 1, where 0., 0., 0. is black and 1., 1., 1. is white.
TRANS COLOR PRECISION=<value>
Defines a maximum distance in RGB color space (in the range from 0 to 1) used to determine a color's transparency (default 0). While the TIFF and PNG formats are preferred for images that use TRANSPARENT COLOR OPAQUE rendering mode, TRANS COLOR PRECISION may be used with JPEG images to overcome the artifacts of JPEG's lossy compression, which slightly changes pixel colors. All colors within this distance from the transparent colors will be rendered as transparent. A typical parameter value is in the range from 0 to 0.5. If the value of 0 is used (default), only pixels with the exact transparent color value will be transparent.
If set to a value other than NONE, defines the layer as an elevation layer. The following values are supported:
- NONE (default)
Elevation layers use elevation data in the form of single-channel TIFF files, where every pixel represents elevation data for the corresponding location. TIFF files with the int16, uint16 and float32 data formats are supported. DEM and DTED to TIFF converter is provided, refer to the Image and Elevation Data Import Utility section on page 95 of Tools and Utilities for more information.
If the mode is set to DATA, the layer will not be displayed, but will be used for elevation queries, to return elevation values for points on the map.
If the mode is set to COLOR, the layer will be displayed as a color-coded image. This mode is also convenient for visual testing of elevation data before using them in the DATA mode. The
PIXEL MAP parameter may be used to provide a custom color threshold table that will be used to convert elevation values to different colors.
If both color display and elevation queries are required, two separate layers may be set up using the same data file.
Defines the transparency of the layer, ranging from 0 to 1. An alpha value of 0 will make the layer invisible, while an alpha value of 1 (default) will make the layer fully opaque according to the blending function. If the user wishes to make a solid transparent layer, the TRANS TYPE should be set to OPAQUE and the alpha value changed. If any of the other blending functions are used, the transparency of any given pixel will depend on its color. For example, if the user wishes to see transparent county overlays over a state map, the values for the TRANS TYPE and ALPHA mentioned above should be used.
Note: Although setting the ALPHA to 0 is identical to turning the layer off in the map request, this should be avoided, as it will be slower, since every object will still be traversed.
Defines an attribute condition. Only the object whose attribute values match the attribute condition will be displayed. For example, if the second attribute (index=1) of the cities layer contains city's population, the following attribute condition may be used to display only cities with population greater than or equal to 100K, but less than 500K:
ATTR COND= @1 >= 100000 && @1 < 500000
While spaces in the value of the above attribute condition are optional, each part of the attribute condition value is a separate string, which means that the value cannot be surrounded with quotation marks. However, if a string with spaces is used in string attribute conditions, it may be quoted:
ATTR COND= @0 == "Las Vegas" || @0 == "New *"
Refer to the Attribute Condition Syntax section on page 71 for more information.
The attribute conditions defined in the ATTR COND directive are logically ANDed with attribute conditions defined in the Layers string, and only the objects that match both sets of conditions will be displayed.
Defines where to look for the data file(s). This path is relative to the path of the LIF itself, unless an absolute path is defined. If there are multiple data files, such as tiles, the filename is specified with `%' characters which will be replaced by numbers when the file is loaded. For example, if tiles reside in files called:image_0_0.jpg image_0_1.jpg image_0_2.jpg image_1_0.jpg image_1_1.jpg ... image_2_2.jpg
then the FILENAME should be set to image_%_%.jpg and the correct values will automatically be filled in:FILENAME= image_%_%.jpg
An optional parameter that defines the format of the vector data used by the vector layer. The following values are supported:VECTOR FORMAT=GVF VECTOR FORMAT=SHP
GVF is the native format of the Map Server. The SHP format is used for shape files. If
VECTOR FORMAT is omitted, the map server tries to determine the data format based on the vector file extension.
For maximum performance, shape files should be converted to the native GVF format. However, the SHP format may be used for quick testing of the shape files, when maximum performance is not important. To convert shape files to GVF format, use the shape file conversion utility described in Tools and Utilities on page 77.
Defines the path of an executable file which contains a filter to convert vector data from a custom format to the Map Server's format. The advantage of using a filter is to avoid creation of temporary files, as the output of the filter is read directly into the Map Server. However, this approach is slower than running the filter beforehand and using an already converted file instead. The path defined is relative to the LIF itself unless an absolute path is defined. A guide to writing filters can be found in GVF Filters and Data Converters on page 141.
An optional parameter that defines the format of the input image data used by the raster layer, or the format of the custom icon image for vector layers. The following values are supported:JPEG PNG TIF
JPEG images provide more efficient compression and may be used to minimize the size of a dataset. TIF and PNG images provide lossless compression and are preferred in cases when preserving exact pixel values is important. For example, when TRANSPARENT COLOR OPAQUE blending function is used, JPEG's lossy compression would alter the exact pixel values used to determine the pixel's transparency, resulting in visible compression artifacts. If IMAGE FORMAT is omitted, the map server tries to determine the format of the image based on the file extension.
IMAGE ANTIALISING=<0 or 1>
Enables or disables image antialiasing for individual image layers. Image antialiasing is enabled by default.
FALLBACK LAYER=<layer name>
Defines the name of a fallback layer. If the layer exceeds the maximum memory allowance specified by MAX TILES, the fallback layer will be activated instead. For example, this parameter may be used to specify a lower resolution image of the earth, so that if the entire earth is being viewed, a lower resolution image is displayed, while higher resolution images will be used when viewing detailed maps. Without a fallback layer, all tiles of the detailed image would be loaded when the entire earth is displayed, consuming excessive CPU and memory resources.
The same effect might be achieved using the MAX ZOOM and MIN ZOOM parameters of several layers, so that the layers are switched depending on the zoom factor. The FALLBACK LAYER provides an alternative way to switch layers based on the maximum number of used tiles, which may be more convenient. It also provides a way to chain several layers, by specifying a FALLBACK LAYER parameter for the fallback layer as well.
For example, a high-resolution tiled layer may switch to a medium-resolution tiled layer when the number of used tiles exceeds 10. The medium-resolution layer may switch to a layer with a single image file when it's number of used tiles exceed 10 as well. All this may be accomplished by specifying medium-resolution layer as a fallback layer for the high-resolution one, and specifying a single image layer as a fallback layer for the medium-resolution layer. MIN ZOOM and MAX ZOOM limits of the layer may be used to further control the layer's visibility at different zoom levels.
FALLBACK=<file> (deprecated: use FALLBACK LAYER)
Defines where to find fallback data. If the file specified with the FILENAME variables exceeds the maximum memory allowance specified by MAX TILES, this file will be used instead. The file is relative to the path of the LIF itself, unless an absolute path is defined.
This parameter is now obsolete and supported only for backward compatibility. The FALLBACK LAYER parameter listed above provides the same functionality in a cleaner way and with more features.
Defines the maximum number of tiles a layer can require before the fallback is activated. This variable should be set according to the amount of memory the user wishes to use for the Map Server. In addition, it should be set so that when a map consists of the area which requires MAX TILES tiles, the FALLBACK data should have sufficient detail when the area is viewed. The default value of -1 allows unlimited number of tiles.
MAX CACHE SIZE=<number>
Defines the maximum size of the layer's tile cache. This variable should be set according to the amount of memory the user wishes to use for the Map Server. It should be set to a value greater or equal to the MAX TILES variable to avoid tile swapping. The default value of -1 disables cache size limit.
NUM TILES X=<number>
NUM TILES Y=<number>
Define how many tiles exist in the horizontal and vertical directions, respectively. These numbers are used to calculate tile indices used to replace the `%' characters specified in the filename. If the `%' are missing, the indices will be appended to the filename.
MIN PIXEL SIZE=<number>
Specifies the minimal pixel size for map decluttering. All polygons whose pixel extent at the current zoom level is smaller than this parameter will not be drawn. The parameter may be set to a fractional value. The default value of the parameter is 0.1, which eliminates small polygons only when their extent becomes much smaller than one pixel. It may be set to a higher integer value, such as 2 or 3, to speed up rendering of a map that contains a lot of small polygons, such as an OSM water layer. Setting it to 0 disables decluttering and draws all small polygons.
An attribute map may be attached to this resource to control the minimum pixel size for each individual vector feature of a vector layer depending on a value of the feature's attribute.
Note: MIN PIXEL SIZE=1 may result in visible gaps for layers that contain lines represented by a large number of small segments, such as political boundaries. If the segment's size is less than or equal to 1, the segment will be eliminated. Set the parameter value to 0 to avoid it. The parameter works best for layers that contain bodies of water, with a large number of small lakes.
CLIP=<0 or 1>
Enables or disables clipping of the layer's marker and polygon features (enabled by default). The clipping is performed based on the lat/lon coordinates of the marker and polygon features, while their labels may extend outside their point boundaries. The clipping speeds up rendering, but may be disabled to show partially visible marker and polygon labels which otherwise might be completely clipped out.
VOLATILE=<0 or 1>
Defines whether or not a layer is volatile. The data files for the volatile layers will be checked on every new map generation request, to find out if they changed and need to be re-read. The volatile setting may be used to update changing layers, such as current weather or radar maps. The default value is 0 (non-volatile).
Defines the lock file for volatile layers. If the variable is defined and the file does not exist, the Map Server waits for this file to be written before attempting to read layer's data files. This is used to synchronize the Map Server's data reads with volatile layer's data updates. The process that updates the volatile layer's data must remove the lock file, update the data and write the lock file back. The parameter is used with REDIRECT FILE, see below.
Defines the maximum time in seconds the Map Server waits for the lock file before proceeding to read data. The default value is 0.05 seconds.
Specifies the name of the file that contains REDIRECT PREFIX for volatile datasets. See REDIRECT PREFIX below.
REDIRECT PREFIX=<directory or prefix>
Used only in the redirect file to define a redirect prefix for volatile datasets. The prefix is appended in front of the dataset's FILENAME or TILES_SUBLIF before it is used to retrieve the data, and allows updating volatile datasets without compromising their data integrity while the data are being rewritten. The map server uses the old version of the data, while the new version is being written into a separate file or directory. When the new data are ready, the update process rewrites the content of the redirect file to provide a new data location. To avoid errors while the redirect file is being rewritten, the lock file is removed before rewriting the redirect file and is written back when finished, forcing the map server to wait. Since the redirect file is small, the lock wait time is very small as well and does not affect performance of the map server.
If the value redirect prefix ends with "/", it defines the name of a directory where the dataset is located. This is usually used for tiled datasets with a number of tiles. If the value of the redirect prefix does not contain "/", it specifies a file name prefix, which may be used for untiled files with just one data file.
Note: The redirect prefix is ignored if the path it is supposed to be appended to is defined using an absolute path name.
VOLATILE ERRORS=<0 or 1>
Defines whether or not correctable errors are reported for volatile errors. For example, if a volatile layer data file is in the process of being overwritten with new data, the map server will use the last valid data for this layer, and the error will not be reported if the variable is set to 0 (default). The default value is 1. (errors are reported). If REDIRECT FILE is used, the volatile errors must not happen.
ALLOW MISSING TILES=<0 or 1>
If set to 1, allows missing tiles in the square tiling mode. This is always required for vector layers with square tiles, as the vector tiling utility does not output tiles for regions that do not contain any vector features. The default value is 0.
TILES OVERLAP=<0 or 1>
May be set to 1 to indicate that tiles can overlap (default 0). This is used for satellite and areal imagery datasets that use UTM coordinates. Converting this tiles to the lat/lon coordinates results in non-rectangular tiles. The tiles use padding on the sides to make tile images rectangular. The unused area used for padding uses black color to indicate this area is not used and should be transparent. Satellite imagery datasets also use black color for masking out areas in the middle of an ocean, which have no data to minimize the size of an already huge dataset.
When tiles are used to compose a map image, the unused transparent padding areas of neighboring tiles may overlap, which requires additional processing when searching for a tile that should be used to render a particular pixel in the map image. Setting TILES OVERLAP to 1 activates this additional processing.
The TRANS TYPE, TRANS COLOR and TRANS COLOR PRECISION variables are used to make transparent the unused areas rendered using the black color, as shown in the following example:TRANS TYPE= "T RANSPARENT COLOR OPAQUE" TRANS COLOR= 0 0 0 TRANS COLOR PRECISION= 0.025
The TRANS COLOR PRECISION is used to avoid JPEG compressing artifacts for images that were imported from JPEG.
The BACKGROUND COLOR and BACKGROUND LAYER variable may be used to provide a background for transparent areas, such as areas in the middle of an ocean.
Specifies a background color to use for rendering pixels for which no data is provided by the current layer, such as transparent areas in the middle of the ocean or the areas outside of the current layer data coverage. The default value (-1,-1,-1) disables background color.
BACKGROUND LAYER=<layer name>
Specifies a name of a layer to use for rendering pixels outside of the data coverage of the current layer. In the absence of a background color, the background layer is also used for rendering transparent pixels of the current layer, such as transparent areas in the middle of the ocean.
Define the width and height of the image in pixels for image layers. For the tiled datasets with square tiles, these parameters are required to provide the extent of the whole image, which is used for tile math. If the width and height are not specified correctly, the image will not be tiled correctly and tiles might appear in wrong places on the map.
These parameters are optional for layers with a single untiled image file, as the width and height of the image are auto-detected. If the width and height parameters are supplied, they are compared with the ones detected in the image file, issuing a mismatch warning if necessary.
These parameters are not used and are ignored for hierarchical directory-based image layers with tree tiling. The layer width and height information is obtained from the TILES SUBLIF file, which is automatically generated by the tiling setup utility.
Defines the extent of the longitude and latitude in the layer and is mandatory for all image and vector layers that use square tiling. It is also necessary for untiled image layers where the raster image data itself includes no specification of what extent the image occupies.
For untiled vector layers these parameters are not required, but are still useful for optimal performance: if they are specified, the layer may be efficiently clipped without reading its data file. The bounding box utility described in Bounding Box Extraction Utility on page 80 may be used to obtain the extent information for vector data files.
For the layers that use tree tiling, these parameters are not required, as they are provided by the SLF setup files of such layers.
Defines the minimum and maximum zoom factor at which the layer should be rendered. If the zoom factor is below or above these values, the layer will be omitted from rendering. These variables are useful for switching layers with various levels of detail depending on the zoom factor.
An attribute map may be attached to these attributes to control the minimum and maximum zoom limits for displaying each individual vector feature of a vector layer depending on a value of the feature's attribute. The original values of the MIN ZOOM and MAX ZOOM before applying the attribute map still control the zoom limits for the whole layer.
The default value is -1 which disables minimum and maximum zoom thresholds.
Defines an optional clip type used to limit the layer output to the clip area. The following value are supported:
- NONE (default)
No clipping is performed.
- BOX (vector layers only)
The GIS features defined in the layer will be drawn if they are completely inside the clip box or partially intersect it. If a feature intersects the clip box and is drawn, it may extent outside of the box. This clip type has minimal performance penalty, but may yield unexpected results for polygon features.
- POLYGON PIXELS (vector layers only)
Performs exact clipping of polygon features to the clip box. Polygon feature labels may still extend outside the box.
- ALL PIXELS
Performs exact clipping of all layer output to the defined clip box. All features defined in the layer as well as their labels will be clipped to the clip area.
For image layers and map selection requests, the BOX and POLYGON PIXELS clip types work the same way as ALL PIXELS.
CLIP MIN LON=<number>
CLIP MIN LAT=<number>
CLIP MAX LON=<number>
CLIP MAX LAT=<number>
Defines an optional longitude and latitude extent of the layer area to be drawn. While the MIN/MAX LAT/LON parameters define the extend of the data available for the layer, the CLIP parameters may be used to limit the drawn part of the layer to the defined clip box.
For image layers, the output is indeed clipped to the provided DRAW box. For the vector layers, all vector features that are either completely inside the box or partially intersect it will be drawn. As a result, the rendered vector features may extend outside the DRAW box.
GRID LAT INTERVAL=<number>
GRID LON INTERVAL=<number>
Defines the interval between neighboring horizontal (of equal latitude) and vertical (of equal longitude) lines. These variables are only useful if the layer type is set to GRID and ADAPTIVE=0. The default value is 10 for the latitude and 20 for longitude interval.
GRID MIN LON=<number>
GRID MIN LAT=<number>
GRID MAX LON=<number>
GRID MAX LAT=<number>
Defines the extent of grid lines in a grid layer. By default, these variables is set to encompass the entire globe. These variables are useful only if the layer type is set to GRID and ADAPTIVE=0.
Defines an adaptive grid if set to non-zero value (default 0). The Map Server will attempt to divide the extent of the map image into roughly the number of grid lines specified by the variable's value, while placing the grid lines on round numbers such as 10, 25, 50, etc. or 0.1, 0.2, 0.5, etc. if the image spans a small area.
GRID LABELS=<0, 1, 2, 3 or 4>
Defines whether or not to render labels next to the grid lines of the grid layer. A value of 0 (default) will not render grid labels, value of 1 will render labels on one side of the map, and the value of 2 will render them on both sides, except for the special cases of the ORHOGRAPHIC projection (when one of the poles is visible, or the whole unzoomed globe is displayed), which will render labels at the center.
The values of 3 and 4 are used for a special case when a map in the ORTHOGRAPHIC projection is clipped to generate zoomed views of the globe with a visible horizon line. The value of 3 will display grid labels on three sides of the map (left, right and bottom), and the value of 4 will display labels on all four sides.
DECIMAL GRID LABELS=<0 or 1>
Defines the format for displaying the fractional part of the grid labels: if set to 1 (default), decimals are used; if set to 0, minutes and seconds are used.
GRID LABEL FORMAT=<format>
Specifies a custom format for grid labels. For the decimal grid labels, the format must contain a double C format specifier, otherwise it must contain up to four long integer C format specifiers for the degrees, minutes, seconds and deciseconds. For example, the following string may be used to display non-decimal grid labels with degrees, minus and seconds, with no deciseconds:"%.3ld deg %.2ld'%.2ld"
If grid labels use a True Type font, a Unicode degree character may be embedded in the format string.
GRID LABEL FORMAT LON=<format>
Specifies a custom format for the longitudinal grid labels if they must have a different format than the latitudinal grid labels.
GRID LABEL CHAR=<0, 1 or 2>
Controls the use of the directional character (N, S, E or W) added to the label to indicate direction and may have the following values:
- APPEND (default)
If set to NONE, no directional character will be added and a sign will be used instead. The APPEND or PREPEND values may be used to add the directional character at the beginning or at the end of the label string.
ROTATE LON LABELS=<0 or 1>
If set to 1 (default), the longitudinal grid labels will be rotated to be drawn along the vertical grid lines. If set to 0, the labels will be drawn horizontally.
LON LABEL ANGLE=<value>
Defines an optional rotation angle for the longitudinal grid labels, 90 degrees by default.
Defines the font to be used for text rendered from this layer. The name is a vector or TrueType font name specified in the SDF file. If omitted, a default font is used.
Font aliases described on page 34 may be used to define a list of fonts with different charsets for rendering labels containing characters in multiple languages. To use a font alias, use the font alias name instead of a font name.
For vector fonts, defines a multiplier for font units. A multiplier of 1 will render characters of the given font in their original size. A multiplier of 0.5 will render characters one half the size defined by the font.
For the image (TrueType) fonts, defines the font size in pixels.
The default value (12) is optimized for the TrueType fonts.
Defines how the font will be rendered and how font units will be defined. This variable has three supported values:
- MAPPED FLAT (default)
If set to FLAT, the location of the text is defined in terms of pixels from the top left corner. This also means that font units will also be pixels. Font units are used in vector text to specify the size of a given character. For example, the definition of a character might specify that its height is 10 (font units). If FLAT is used, the character will be rendered 10 pixels high.
If set to MAPPED FLAT, the font units will still be pixels, but the location of the text is in lat/lon coordinates.
Finally, if set to TRANSFORMED, both the location and font units are lat/lon coordinates. This means that if the map has curvature, the text will curve around the globe. This also means that the text will appear different sizes depending on the zoom factor.
Defines the angle by which the rendered text should be rotated. It is defined in degrees counterclockwise from the right horizontal axis, i.e. an angle of 0 will render the text as it is seen on paper.
TEXT ANCHOR=<type> <type>
Defines how the text should be anchored. The value for this variable is the horizontal anchoring option followed by the vertical anchoring option, very similar to the text anchoring attribute in the GLG Toolkit. The anchoring options define where the marker should be relative to the text and where the text should be relative to its coordinates. The horizontal anchoring type can be one of:
- HLEFT (default)
Similarly, the vertical anchoring type can be one of:
- VTOP (default)
The horizontal and vertical anchoring types have to be supplied as individual strings separated by either a white space or a comma. Hence:TEXT ANCHOR= HLEFT VCENTER TEXT ANCHOR= HLEFT,VCENTER TEXT ANCHOR= "HLEFT" "VCENTER"
are all valid and will render the text centered on the right side of the marker. However,TEXT ANCHOR= "HLEFT VCENTER"
is not valid, as it provides just one combined string.
Defines what text string is to be rendered alongside the marker. The parameter defines which marker attributes to display in a label, as well as the format string to use for formatting attribute values. The attributes are defined by their attribute numbers, which are specified inside the triangular brackets. The attribute number may be followed by a C printf-style format string. If the format string inside the brackets is omitted, a default format will be used for that attribute. Special character sequences, such as "\n" are also allowed, as well as escaped character sequences. For example, if the first (index 0) attribute is the name of a city and the second (index 1) attribute is the population of a city, then:LABEL FORMAT="<0>\npopulation: <1%.0lf>"
will render:SomeCity population: 12345
for a city named "SomeCity" with a population of 12345. If some markers do not have attributes used in the label format, the missing attributes will be displayed as "***". The first attribute listed in the label format is considered to be the main attribute. If the main attribute is missing, the label will not be displayed at all. If label format is not defined, marker labels will not be rendered.
Defines an alternative label format to be used if the marker attribute used in LABEL FORMAT is missing for some objects.
Specifies a list of optional rendering attributes for text labels. Supported options are:BG_EDGE BG_FILL OUTLINE
The first two options are used for rendering a box around the text. BG_EDGE specifies that the box's edge should be drawn and BG_FILL specifies that the box's area should be drawn. The OUTLINE option draws an outline around the text label to improve label visibility when it is displayed on a background of a similar color. The LABEL OUTLINE COLOR parameter described below specifies the color of the outline.
More than one option may be listed in one string using a comma or space separator and surrounding the whole string with quotes, for example:LABEL STYLE= "OUTLINE,BG_EDGE"
LABEL OUTLINE COLOR=<r g b>
Defines the color of the outline drawn around text labels (default 0.7, 0.7, 0.7). The value must be a triplet of double values ranging from 0 to 1, where 0., 0., 0. is black and 1., 1., 1. is white.
WRAP LABEL LENGTH=<number>
Defines the maximum length of a label line in pixels. If this length is exceeded, the label text will be wrapped by splitting it into several lines. Setting it to 0 (default) disable wrapping. The parameter defines an approximate line length: since text lines are split at spaces, individual text lines may extend outside the box width defined by the parameter.
TEXT BOX OFFSET HORIZ=<number>
Defines the horizontal pixel margin between the label and the text box edge (default 3). Text box is enabled by setting LABEL STYLE to include BG_EDGE and/or BG_FILL.
TEXT BOX OFFSET VERT=<number>
Defines the vertical pixel margin between the label and the text box edge (default 1). Since many letters have a different height, the actual distance from a given character to the text box may vary with the font and character in question.
TBOX LINE WIDTH=<number>
Defines the line width in pixels of the text box drawn around text labels (default 1). Text box drawing is enabled by setting LABEL STYLE to include BG_EDGE and/or BG_FILL.
LABEL MIN ZOOM=<value>
LABEL MAX ZOOM=<value>
Defines the zoom factor range for which marker labels (such as city names) and polygon labels (such as street names) are displayed. The labels will not be displayed for zoom factors outside this range. This causes the Map Server to display labels only when a certain zoom level has been reached, and disable them again when the map is zoomed in too far, decluttering the map image. If these parameters are omitted of set to a default value of -1, labels will always be displayed (if enabled by label format attributes).
Defines the label layout type and may have the following values:
- NONE (default)
Specifying the layout type enables label layout negotiation for text labels. The label layout makes sure that text labels do not obscure each other and that labels with lower priority do not obscure labels with higher priority. When set to LAYER, the layout will be performed only for labels within the layer, which is faster, but may result in label conflicts between labels in different layers. The GLOBAL value is used to perform the label layout negotiation across all layers.
Text layout negotiation is not supported for the TRANSFORMED text.
Defines label priority for all labels in the layer (default 9). The labels with priority value of 0 have the highest priority. A threshold table may be attached to LABEL PRIORITY to vary priority of labels within one layer based on other object attributes, such as a road type or city population. While the priority values may be set to any number greater or equal to 0, using priority values with minimal gaps between them results in better performance.
LABEL REPEAT DISTANCE=<number>
Defines a minimum distance in pixels between labels with the same label string (default 0) when the label layout negotiation is enabled. It may be used to enhance rendering labels of named streets and roads that are split in multiple segments.
Defines an additional margin in pixels between text labels (default 1). Using a bigger value will result in more space between individual text labels when the label layout negotiation is enabled.
LAYOUT MARKERS=<0 or 1>
Specifies the way the layout negotiation handles markers. If set to 1 (default), the markers will be handled together with their labels, and will not be drawn if its label is not drawn. If set to 0, the markers will always be drawn, while their labels will be drawn only if not obscured by other labels with a higher priority.
MARKER ICON FILE=<file>
Specifies a JPEG, PNG or TIFF image file containing a custom icon for rendering markers. An attribute threshold may be attached to this attribute to use different icon types depending on a value of some other attribute. For example, different icons may be used for cities and towns depending on the value of their population attribute. Refer to the ATTR_MAP attribute on page 57 for more information on attribute threshold tables.
MARKER ICON TYPE=<type, type, ...>
Defines what type of marker to render at the location defined by the text object's control point. The value of this variable is a list of all desired marker types. All marker types in the GLG Toolkit are supported. The available marker types are:
- BOX_EDGE (default)
- CUSTOM ICON
The circle options draw a circular marker. The box options draw a square marker. The CROSS option draws a cross, and the DOT option draws a small dot in the center of the marker. The CUSTOM ICON option draws the custom icon specified by MARKER ICON FILE. If the marker type is omitted or set to NONE, no marker will be rendered.
More than one option may be listed in one string using a comma or space separator and surrounding the whole string with quotes, for example:MARKER ICON TYPE= "CIRCLE_FILL,CIRCLE_EDGE,DOT"
MARKER ICON SIZE=<number>
Defines the size in pixels at which the marker should be rendered (default 5). It is ignored if custom icons are used, in which case the size of the image in the icon file is used.
TEXT OFFSET HORIZ=<number>
For marker labels, defines the horizontal pixel distance between the marker and the label
(default 1). For polygon labels, defines the horizontal label offset from the label's calculated position, factoring in a rotation angle for line labels.
TEXT OFFSET VERT=<number>
For marker labels, defines the vertical pixel distance between the marker and the label (default 0). For polygon line labels, defines distance between the label and the line, factoring in a rotation angle for line labels. For other types of polygon labels, defines the vertical label offset from the label's calculated position.
Defines the fill color of polygons that are rendered if there are any areas to fill, as well as the fill color of the outline and background layers (default 0.7, 0.7, 0.7). The value must be three double values ranging from 0 to 1, where 0., 0., 0. is black and 1., 1., 1. is white. Image and grid layers are not affected by this variable.
Defines the edge color of polygons, grid lines and outline (default 0, 0, 0). The value must be three double values ranging from 0 to 1, where 0., 0., 0. is black and 1., 1., 1. is white.
MARKER EDGE COLOR=<r,g,b>
Defines the edge color of markers in a vector layer (default 0, 0, 0). This option only applies if the marker type includes CIRCLE_EDGE, BOX_EDGE, CROSS and DOT. The value must be three double values ranging from 0 to 1, where 0., 0., 0. is black and 1., 1., 1. is white.
MARKER FILL COLOR=<r,g,b>
Defines the fill color of markers in a vector layer (default 0.7, 0.7, 0.7). This option only applies if the marker type includes FILLED_CIRCLE or FILLED_BOX options. Otherwise, the variable has no effect. The value must be three double values ranging from 0 to 1, where 0., 0., 0. is black and 1., 1., 1. is white.
Defines the color of the text labels in a vector layer (default 0, 0, 0). The value must be three double values ranging from 0 to 1, where 0., 0., 0. is black and 1., 1., 1. is white.
BOX EDGE COLOR=<r,g,b>
Defines the edge color of the text box in a vector layer, if the text box is enabled (default 0, 0, 0). The value must be three double values ranging from 0 to 1, where 0., 0., 0. is black and 1., 1., 1. is white. The text box is enabled by setting LABEL STYLE to include BG_EDGE and/or BG_FILL.
BOX FILL COLOR=<r,g,b>
Defines the fill color of the text box in a vector layer, if the text box is enabled (default 0,.7 0.7, 0.7). The value must be three double values ranging from 0 to 1, where 0., 0., 0. is black and 1., 1., 1. is white. The text box is enabled by setting LABEL STYLE to include BG_EDGE and/or BG_FILL.
Defines the gradient color of the background layer (default 0, 0, 0). The value must be three double values ranging from 0 to 1, where 0., 0., 0. is black and 1., 1., 1. is white.
Defines the type of the gradient to be rendered for the background layer in the orthographic projection. Valid values are NONE (default) and AROUND_GLOBE. The AROUND GLOBE gradient type renders a gradient that starts at the edge of the globe and gradually changes color from the GRADIENT COLOR to FILL COLOR as the distance from the center of the globe increases.
Defines the length of the gradient of the background layer (default 1). For the AROUND_GLOBE gradient type, the length is defined in relative units, with 0.3 corresponding to the 30 percent of the globe radius. The gradient starts the edge of the globe and extends outwards.
Defines the fill type of polygons to be rendered, analogous to the FillType option in the GLG Toolkit. Supported values are:
- EDGE (default)
- FILL AND EDGE
NONE disables rendering of the polygon's fill and edge, while still rendering a polygon's label (if defined).
Defines the line width in pixels of polygons, grid lines and outline, analogous to the line width option in the GLG Toolkit. The default value is 1 pixel.
DRAW CENTER MARKER=<0 or 1>
If set to 1, a marker with or without a label will be drawn at the polygon center (default 0). This can be used to draw small (but important) polygons that otherwise would be invisible at low zoom levels due to their small size. The polygon's FILL TYPE may be set to NONE to disable rendering of the polygon when the center marker is used.
The marker and label attributes control rendering of the center marker and its label.
POS RANGE=<0 or 1>
While most vector data for the earth has longitude values ranging from 180 W to 180 E , some data, such as the common shoreline data is presented in the 0 E to 360 E range. This means that it is centered around 180 E as opposed to 0 E. A value of 1 specifies that the vector data is in such a format. The default value is 0.
POLY LABEL FORMAT=<format>
Defines which attributes of a polygon object in a vector data file to display in the polygon label. This parameter is commonly used to draw labels on streets and areas. The placement of the labels is determined by the Map Server. If this parameter is not specified, polygon labels will not be displayed. Refer to the the LABEL FORMAT=<format> section on page 50 for information on the format string syntax.
POLY LABEL FORMAT2=<format>
Defines an alternative label format to be used if the polygon attribute used in
POLY LABEL FORMAT is missing for some objects.
POLY LABEL TYPE=<type>
Defines where and how the polygon label is rendered. It can have one of the following types:
- LINE LABEL (default)
- MID LINE LABEL
- AREA LABEL
- BBOX LABEL
If the type is LINE LABEL, then labels are rendered at the beginning of polygons at an optimal angle. If the type is MID LINE LABEL, then labels are rendered in the middle of polygons at an optimal angle. If the type is AREA LABEL, then labels are rendered according to the
LABEL CENTER attribute. If the type is BBOX LABEL, then labels are rendered in the center of the bounding box of the polygon.
If the type is either AREA LABEL or BBOX LABEL, then all attributes that define the anchoring and angle of the text apply.
POLY LABEL CENTER=<number>
Defines which attributed of a polygon object in a vector data file to use as the center of the label on the polygon. The number must be the name (attribute index) of the data attribute to use.This attribute is used when the LABEL TYPE attribute is set to AREA LABEL. The attribute must be of G type. The default value of -1 indicates an unset value.
LABEL SELECTION MODE=<mode>
Specifies the label selection mode for the GIS selection and can use one of the following modes:
- UNSET (default)
NONE suppresses label selection for the layer. YES enables GIS label selection with maximum precision, INTILE forces the in-tile label selection described in the GlmGetSelection section on page 129 and UNSET allows the label selection mode to be controlled by either the SELECT_LABELS parameter of the map request or the select_labels parameter of the GlmGetSelection method.
ALLOW OVERRIDE=<0 or 1>
If set to 0, disallows the use of the "++" override in the layer string for this layer. By default, the overrides are allowed for untiled layers and suppressed for tiled layers, to avoid unintended consumption of significant memory and CPU resources. The default setting for all layers of the dataset may be specified by the ALLOW OVERRIDE parameter of the dataset's SDF file.
ATTR MAP=<number resource threshold_table REL/ABS>
The Map Server provides a mechanism for mapping attributes of vector data to layer resources. For example, it is possible to vary the color and size of the city marker depending on the city's population. The ATTR MAP parameter defines the threshold table and the way it is applied.
- the name of an attribute (0-based attribute index) associated with any given data object. This attribute will be used as an input of the threshold table. Numbers bigger than the maximum attribute index may be used to reference custom attributes described below.
- Negative numbers may be used to define special attributes provided by the map server:
- -3 Random attribute that generates a random number ranging from zero to the maximum (last) value in the threshold table
- -4 Zoom factor
- defines the name of the layer's resource to vary. This resource will be used as the output of the threshold table. All resources names are concatenations of words, each of which start with a capital letter. This is the same resource naming convention used in the GLG Toolkit. For example, the ALPHA attribute becomes the resource named Alpha and the
MARKER FILL COLOR attribute becomes the MarkerFillColor resource. While most of the attributes previously described can be used as the value of the resource parameter, some cannot. See 1, 2
- the path of a threshold table file, which often has a .tt extension. The format of a threshold table file is as follows:
- INPUT DATA TYPE=<type> OUTPUT DATA TYPE=<type>
- The input data type defines the type of the resource that is used as an input to the threshold table, and the output data type defines the type of resource that is being set. Supported options are:GLM_D GLM_G GLM_S
- What follows is list of values, one line at a time in the following format:<input value> <output value> <input value> <output value> <input value> <output value> ...
- Usually attributes of D type are used as input, but they may control an output resource of any type. The input values of the D type must be defined in the table in ascending order. All input values that are greater than or equal to the last output value will be mapped to the last output value. All input values between the second to last and last input value will be mapped to the second to last output value, and so on. The first input value is ignored: all input values less than the second input value will be mapped to the first output value. See example below.
- If input values of G type are used, they may be listed in any order. If the exact match is found, the corresponding output value is returned. If no match is found, the last output value in the list is returned (the last input value is ignored).
- If input values of G type are used, they may be listed in any order as well. The input values in the list may contain wild cards: `*' matches any number of any characters and `?' matches one character. If a match is found, the corresponding output value is returned. If no match is found, the last output value in the list is returned (the last input value is ignored).
- either REL or ABS. If set to ABS, the resource value will be set to that defined in the threshold table. If set to REL, the value will be relative, i.e. multiplied by the value of resource. Naturally, REL cannot be used for S resources. For G resources, each component is multiplied by the respective component in the threshold table's resource value.
For example, if the second (index 1) attribute of markers in a data file is the population of a city:ATTR MAP=1 EdgeColor popul_to_color.tt REL
and the threshold file (popul_to_color.tt in the sample dataset):INPUT DATA TYPE= GLM_D OUTPUT DATA TYPE= GLM_G 0 0.4 0.4 0.4 10000 0. 1. 1. 50000 1. 1. 0. 100000 0. 1. 0. 500000 1. 0. 0.
will make all large cities (>500k) red, all small cities (100k - 500k) green, all large towns (50k - 100k) yellow, all medium towns (10k - 50k) purple and the rest of the small towns grey.
CUSTOM ATTR=<number resource data_type>
Defines a custom attribute that can be used in an attribute map. This is useful for defining custom descriptions of data to be used in the label format.
- defines the number of the custom attribute. This number must be greater than the largest attribute index in the file.
- the name of a custom resource to create.
- the type of that resource.
A custom attribute definition creates a custom attribute which also becomes the layer's resource.
For example,CUSTOM ATTR=5 CityDescriptor GLM_S ATTR MAP=1 CityDescriptor popul_to_city.tt ABS LABEL FORMAT="<5>"
in the LIF file as well as the following lines in a threshold table (popul_to_city.tt):DATA TYPE= GLM_S 0 "small town" 10000 "town" 50000 "big town" 100000 "small city" 500000 "big city"
will make the marker label either "small town", "town", "big town", "small city" or "big city" depending on the population, which is the second attribute of a marker object.
The following example adds MinPopulation custom attribute that is used to display smaller cities at higher zoom levels:# Controls what cities are displayed at the current zoom level based on the MinPopulation custom # attribute that depends on the zoom factor. ATTR COND= @8 > @14 # A custom attribute that controls a minimum city population to be displayed depending on the zoom. CUSTOM ATTR=14 MinPopulation GLM_D # Maps zoom factor (attribute index=-4) to the value of the MinPopulation custom attribute using a # threshold table. ATTR MAP= -4 MinPopulation zoom_to_min_popul.tt ABS
PIXEL MAP=<number resource threshold_table REL/ABS>
Defines a custom color threshold table for mapping elevation values to different colors. The number and resource parameters are ignored (use zeros), and the rest is the same as for the ATTR MAP parameter above. The threshold table must have the INPUT_DATA_TYPE=GLM_D and OUTPUT_DATA_TYPE=GLM_G, mapping elevation value (D type) to the RGB color values (G type). A sample color threshold table called elev_to_color.tt is provided with the sample dataset.
Includes all variable definitions in the specified file into the current LIF. This variable is useful to either split information into multiple files or when hierarchical tiling LIFs are generated and then included into a more general layer description.
TILES SUBLIF=<top-level sublif file> [<bbox>]
SUBLIF DIR=<directory> [<bbox>]
SUBLIF FILE=<sublif file> [<bbox>]
If hierarchical tiling is used, defines a sub-LIF file (SLF) with tiling information. The sub-LIF files are automatically generated by hierarchical tiling setup utility and contains information about the tile hierarchy for directory-based tiled datasets. The utility traverses the directory that contains a hierarchical dataset and all its subdirectories, generating a hierarchy of linked SLF files that describe the data in a way that allows to quickly find tiles for the requested area on the map. The top-level SLF file generated by the utility is specified as the TILES SUBLIF parameter of the LIF. The TILES SUBLIF file is relative to the directory of the LIF itself, unless an absolute path is specified.
All SLF files include the MIN LAT, MAX LAT, MIN LON and MAX LON entries that define a bounding box covered by the SLF file and all subordinate SLF files it may recursively include. An SLF file may also contain a list of SUBLIF DIR entries that specify subdirectories that contain more tiles. Each listed subdirectory will contain an SLF file with the same name as the top level SLF file specified with TILES SUBLIF, and that SLF file may recursively include more SUBLIF DIR entries, to any level of depth.
An SLF file may also contain a list of SUBLIF FILE entries, which are leaf nodes of the hierarchy tree describing data for one tile. These bottom-level SLF files reference their tile data using the FILENAME parameter and must not include any other SUBLIF DIR or SUBLIF FILE entries.
For image tiles, the bottom-level SLF file may contain USED WIDTH and USED HEIGHT entries, which are automatically generated by the Map Server's tiling utility in cases when the image's width or height could not be evenly divided into the requested number of rows or columns of tiles, and the last tile in the row or column is just partially filled with data. In this case, the entries provide the actual width and height of the last tile, different from the width and/or height of the regular tiles defined in the LIF.
Any of these SUBLIF configuration variables may include an optional BBOX directive in the following format:BBOX= lon1 lat1 lon2 lat2
While the BBOX directive is optional, it is included by default by the tiling setup utility to increase performance of large hierarchical datasets.
1The Earth Image is provided by NASA. The following describes the image license for the earth image:
1The imagery is free for use. The only restrictions are:
1(1) NASA requires that they be given a credit, as owners of the imagery
1(2) Visible Earth requests that you provide a credit (with URL if possible) for them
(http://visibleearth.nasa.gov/), since you found the imagery with us.
1(3) VE requests that you provide a credit for the Earth Observatory team (http://earthobservatory.nasa.gov/) for generating the imagery.
1Of course, only (1) is required, (2) and (3) are entirely optional and have no effect on your permission to use the imagery.
2The shaded relief image is derived from the Global Land One-kilometer Base Elevation (GLOBE) Digital Elevation Model, Version 1.0., by:
2GLOBE Task Team and others (Hastings, David A., Paula K. Dunbar, Gerald M. Elphingstone, Mark Bootz, Hiroshi Murakami, Hiroshi Maruyama, Hiroshi Masaharu, Peter Holland, John Payne, Nevin A. Bryant, Thomas L. Logan, J.-P. Muller, Gunter Schreier, and John S. MacDonald), eds., 1999.
2The Global Land One-kilometer Base Elevation (GLOBE) Digital Elevation Model, Version 1.0.
National Oceanic and Atmospheric Administration, National Geophysical Data Center, 325 Broadway, Boulder, Colorado 80303, U.S.A.
Digital data base on the World Wide Web (URL: http://www.ngdc.noaa.gov/mgg/topo/globe.html)
3Copyright 2006, 2007, 2008, 2009, 2010 by David Turner, Robert Wilhelm, and Werner Lemberg.
Generic Logic, Inc.