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
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 and TIFF 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 Tiling on page 32 for details.1
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.
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 Digital Chart of the World (DCW) and US Census Tiger Data, are available in the converted ASCII GVF format from Generic Logic.
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.
It is important to note that all common rendering properties, 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. However, each object in a 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. 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 integral numbers. These numbers are defined in the data file. For example, the area of a city is defined as attribute 1 and the population as attribute 2. This means that some objects may have attributes that do not exist for others. For example, some cities might not have information about their area. So, in some objects, the area is attribute 1, and the population is attribute 2, while other objects lacking the area information will just have population as attribute 2.
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. See the Attribute Map section on page 46 for details.
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.
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, to define the line width of polygons:
LINE WIDTH=1is used in the configuration file. Most configuration variables are one of three types. A configuration variable can be of D, G, or S type. 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, but if the user wants to assign a string with white space, quotes must be used. Hence:
FILENAME=file.gvf FILENAME= file.gvf FILENAME="file.gvf" 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.
Configuration variables also sometimes require multiple parameters, such as the Text Anchor option, which requires the user to list all options they prefer as a list of S variables. 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.
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 definitions. 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 may also contain attribute conditions. 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. The alias value must be quoted if it contains spaces, commas and any other special characters. To avoid ambiguities, the "++" and "-" prefixes are 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 alias name should be different from the names of layers, fonts and reserved GLG resources.
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.
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 library2.
Defines the dataset's default font. It is used for all text labels that do not specify the font explicitly.
Defines the dataset's error font used for rendering error messages. If omitted, the dataset's default font is used.
Specified whether or not to use the relative zoom feature of the Map Server. This variable can take either a 0 or 1 double value. If 1, all zoom coefficients are calculated using the extent of the layer for which they are being calculated. If 0, zoom coefficients are calculated using the entire extent of the world. In most cases, it is preferable to turn the Relative Zoom off, because the user often does not know and does not need to know the extent of the layer. Zoom coefficients can be used to turn layers on and off depending on how zoomed in the image is. See Layers and Tiles on page 31 for details.
Specified the encoding used for the text strings. The default encoding is LATIN .
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.
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.
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.
In this example, The Map Server will look for earth.lif in /usr/local/glm/map_server/layers/earth.lif as well as clouds.lif , but cities.lif will be found in /home/user . It will look for romans.data in /usr/local/glm/map_server/ fonts/romans.data.
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, 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 or is less than a predefined number, 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 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. If relative zoom is enabled on the dataset, the Zoom Factor is the reciprocal of the proportion of the layer that is visible. If relative zoom is not enabled, the Zoom Factor 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.
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:
TYPE=IMAGE TYPE=VECTOR TYPE=GRID TYPE=OUTLINEThe first two layer types correspond to the type of their data: raster or vector. The last two type 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, and 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.
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.
Defines whether or not a layer will be turned on by default, i.e. 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.
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:
TRANS TYPE=OPAQUE TRANS TYPE="ALPHA WHITE OPAQUE" TRANS TYPE="ALPHA BLACK OPAQUE" TRANS TYPE="TRANSPARENT COLOR OPAQUE" TRANS TYPE=XOR TRANS TYPE="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.
Defines a maximum distance in RGB color space (in the range from 0 to 1) used to determine a color's transparency. While the TIFF format is 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. Elevation layers use elevation data in the form of single-channel TIFF files, where every pixel represents elevation data for the corresponding location. DEM and DTED to TIFF converter is provided, refer to the Image and Elevation Data Import utility on page 81 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 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 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.jpgthen the FILENAME should be set to: image_%_%.jpg and the correct values will automatically be filled in:
FILENAME= image_%_%.jpgAn 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=SHPGVF 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 63.
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 113.
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:
IMAGE FORMAT=JPEG IMAGE FORMAT=TIFJPEG images provide more efficient compression and may be used to minimize the size of a dataset. TIF 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.
Enables or disables image antialiasing for individual image layers. Image antialiasing is enabled by default.
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.
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 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.
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.
Define how many tiles exist in the horizontal and vertical directions, respectively. These number is used to replace the `%' characters specified in the filename. If the `%' are missing, the numbers will be appended to the filename.
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 default value of the parameter is 1, which eliminates polygons with extents smaller than one pixel. It may be set to a bigger integer value to speed up map rendering. 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.
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.
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.
Used 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.
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. The default value is 1. (errors are reported). If REDIRECT FILE is used, the volatile errors must not happen.
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.
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 66 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.
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 .
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. 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.
Defines whether or not to render labels next to the grid lines of the grid layer. A value of 0 will not render grid labels, value of 1 (default) will render labels on one side of the map, and the value of 2 will render them on both sides.
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.
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.
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.
Defines how the font will be rendered and how font units will be defined. This variable has three supported values:
TEXT TYPE=FLAT TEXT TYPE=MAPPED FLAT TEXT TYPE=TRANSFORMEDIf 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.
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 HRIGHT HCENTERSimilarly, the vertical anchoring type can be one of:
VTOP VBOTTOM VCENTER TEXT ANCHOR=HLEFT VCENTERwill render the text centered on the right side of the marker.
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 of 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>"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.
Specifies a list of optional rendering attributes for text labels. Supported options are:
BG_EDGE BG_FILL OUTLINEThe 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 specifies the color of the outline.
Defines the color of the outline drawn around text labels. 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.
Defines the top, bottom, left and right margin in pixels between the text and its text box. It is measured from the edge of text box. Since many letters are either smaller or larger than the font box, the actual distance from a given character to the text box may vary with the font and character in question. Text box drawing is enabled by setting LABEL STYLE to include BG_EDGE and/or BG_FILL .
Defines the line width in pixels of the text box drawn around text labels. Text box drawing is enabled by setting LABEL STYLE to include BG_EDGE and/or BG_FILL .
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 and the POLY LABEL FORMAT parameter is defined for polygon labels, the polygon labels will always be displayed.
Defines the label layout type and may have the following values:
NONE LAYER GLOBALSpecifying 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.
Defines label priority for all labels in the layer. 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.
Defines an additional margin in pixels between text labels. Using a bigger value will result in more space between individual text labels when the label layout negotiation is enabled.
Specifies a JPEG of 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 ATTR_MAP attribute on page 46 for more information on attribute threshold tables.
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:
NONE CIRCLE_EDGE CIRCLE_FILL BOX_EDGE BOX_FILL CROSS DOT CUSTOM ICONThe 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.
Defines the size in pixels at which the marker should be rendered. It is ignored if custom icons are used, in which case the size of the image in the icon file is used.
Defines the distance in pixels that the text and/or text box should be rendered from the marker. This option functions identically regardless of the text angle or the icon size. It is measured from the center of the marker.
Defines the fill color of polygons that are rendered if there are any areas to fill. 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. 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 edge color of markers in a vector layer. 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.
Defines the fill color of markers in a vector layer, if there are any marker data objects in the data file. 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. 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 edge color of the text box in a vector layer, if the text box is enabled. 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 fill color of the text box in a vector layer, if the text box is enabled. 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 fill type of polygons to be rendered, analogous to the FillType option in the GLG Toolkit. Supported values are:
FILL TYPE=EDGE FILL TYPE=FILL FILL TYPE="FILL AND EDGE"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.
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.
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 LABEL FORMAT=<format> on page 42 for information on the format string syntax.
Defines where and how the polygon label is rendered. It can have one of the following types:
LABEL TYPE="LINE LABEL" LABEL TYPE="MID LINE LABEL" LABEL TYPE="AREA LABEL" LABEL TYPE="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.
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.
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.
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 (attribute index) associated with any given data object. This attribute will be used as an input of the threshold table.
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 Map Server API on page 85 for details and a full list of resources.
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_SWhat 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 RELand 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.
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.
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.
A custom attribute definition creates a custom attribute which also becomes the layer's resource.
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.
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.
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.
1. The Map Server provides some publicly available image and vector data sets. The earth image is provided by NASA. The following describes the image license for the earth image:
The imagery is free for use. The only restrictions are:
(1) NASA requires that they be given a credit, as owners of the imagery
(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.
(3) VE requests that you provide a credit for the Earth Observatory team (http://earthobservatory.nasa.gov/) for generating the imagery.
Of course, only (1) is required, (2) and (3) are entirely optional and