PREV NEXT

Generic Logic, Inc. www.genlogic.com


4 Map Server API

4.1 Overview

The GLG Map Server Application Programming Interface (API), provided as a set of C functions, provides a cross-platform way to incorporate the Map Server into an application. The API provides all functionality available in the Map Server executable as well as some advanced functionality to optimize the Map Server's performance. The API allows a developer to create multiple Map Objects and multiple Datasets, as well as cache vector and image data for enhanced performance.

The GLG Map Server is intended as a mapping service and therefore provides no way of displaying generated map images. However, the GLG GIS Object can be used to integrate the generated map images into a graphical GLG application.

If the GLG GIS Object is used, it will handle all invocations of the Map Server API transparently, so that the user does not need to know the Map Server API, and this chapter may be skipped.

The Map Server API provides functions to read data, create and manipulate Map Objects and write the generated images to a file, and is used in applications that do not use the GLG GIS Object.

In order to run an application utilizing the Map Server API on various platforms, the code simply needs to be recompiled. Although the Map Server API itself is completely cross-platform, it is up to the developer to make the rest of the application platform-independent.

Resources

The Map Server API utilizes the same resource mechanism that is used in the GLG Toolkit. Maps and Datasets are both objects whose resources can be Get and Set. Similarly, there are three types of resources: D, S and G which represent double, string and geometrical data. Both Maps and Datasets are GlmObjects. The basic resource access mechanism has the same format as in the GLG Toolkit. For example, to set the Height of a map object, a D resource:

GlmSetDResource( map_object, "Height", 600. ); // set the height
GlmGetDResource( map_object, "Height", &height ); // get

Geometrical resources are passed three values or pointers:

GlmSetGResource( map_object, "FillColor", 1., 0., 0. ); 
// set the color 
GlmGetGResource( map_object, "FillColor", &r, &g, &b ); // get

String resources are passed a string or a pointer to a string:

GlmSetSResource( map_object, "Dataset", "earth.sdf" ); 
// set the string 
GlmSetSResource( map_object, "Dataset", &dataset ); // get

4.2 Basic Structure of a Mapping Application

The basic structure of any mapping application requires:

Any mapping application must first include the file GlmApi.h via the #include directive. The initialization of the Map Server is accomplished via a call to the GlmInit() function. The function has one parameter, a string, which defines the path to a Server Dataset File (SDF). All layer and font information will be loaded from this file.

A Map Object is created via the GlmCreateMap() function. Its resources are set via the GlmSetResource functions. What follows is a detailed description of available resources. These are the same resources that are specified in the -oGISreq command line option.

The type of the resource (D,G or S) is specified after the resource name. When a default value is not listed, it is 0 for D resources, (0,0,0) for G resources and NULL for S resources.

DatasetName D

Specifies the name of the dataset to use. The default is "DefaultDataset", which is always created by GlmInit function. If the application uses multiple datasets, the DatasetName resource is used to set the name of the dataset to be used for generating the map. If the DatasetName resource was changed, the GlmSetupMap function must be called before selecting layers.

Projection D

Specifies which projection is to be used to render the map image. Valid values are GLM_ORTHOGRAPHIC (default) and GLM_RECTANGULAR.

CenterLon D

Defines the longitude at the center of the map image. A value of 0 is at the Greenwich meridian. Negative values are west of the meridian and positive values are east of the meridian.

CenterLat D

Defines the latitude at the center of the map image. A value of 0 is at the equator. Negative values are below the equator and positive values are above the equator.

VExtent D

Defines the vertical extent of the map image. If using the rectangular projection, the extent is in latitudinal coordinates. If using the orthographic projection, the extent is in meters.

HExtent D

Defines the horizontal extent of the map image. If using the rectangular projection, the extent is in longitudinal coordinates. If using the orthographic projection, the extent is in meters.

AngleD

For the rectangular projection, defines the map rotation angle, in degrees counter-clockwise.

Width D

Defines the width of the generated map image in pixels.

Height D

Defines the height of the generated map image in pixels.

Stretch D

Defines whether or not to maintain the correct lon/lat aspect ratio. If set to 1, the image will be stretched according to the Width and Height resources. If set to 0 (default), the image will maintain its lon/lat aspect ratio. For example, in the orthographic projection, if the entire earth is being viewed, if Stretch is set to 0, the earth will always appear as a perfect sphere, instead of an oblong one.

Background G

Defines the background color to be rendered in the map image. The three values are in the range 0 to 1 and define the red, green and blue components of the color, respectively.

ImageAntiAliasing D

Enables or disables antialiasing while scaling images of raster layers. Will be turned on if set to 1 (default 0).

ImageErrors D

Defined whether or not to render errors into the image. If set to 1, errors will be rendered. If set to 0 (default), they will not.

Verbosity D

Defines the verbosity value (default 0). If verbosity level is set to positive integer value, from 1 to 6, diagnostic information will be generated. If verbosity level is set to a negative integer value, from -1 to -6, the performance and timing output will be produced. If verbosity level is set to the values 1001 or 1002, tile extent information is displayed in the generated images for the GetMap requests. The verbosity output is printed to the standard error, the higher the number, the more output is generated. Errors and info are also displayed in the generated image (if IERRORS is set to 1) and logged into the glm_error.log file. By default, the verbosity is set to 0.

Finally, the layers to be rendered into the map image need to be set. The most commonly used function is the GlmSetLayers function. It takes a comma separated list of layers as its parameter. It also takes default and "*" as valid layer names. If default is used as a layer name, all layers with the DEFAULT ON flag specified will be rendered, and if "*" is used as a layer name, all layers in the SDF file will be rendered. For example:

GlmSetLayers( map_object, "default,clouds,shores" );

will turn on all default layers as well as the clouds and shores layer. Two other common functions are: GlmEnableLayer, which enables one layer, and GlmDisableLayer, which disables one layer in the map object. If the map object is used repeatedly, the GlmResetLayers function may be called to clear the previous selection prior to selecting new layers.

Once the Map Object is created and the resources set, the actual map generation needs to occur. This is accomplished with a call to GlmGetProjection(). Its one parameter is the map object with all its parameters specified. It is important to note that after the image is generated, the map object does not need to be discarded. It may be used to generate other images after altering some or all of the map object's resources.

After a call to GlmGetProjection, the GlmWriteImage function can be used to write the resulting map image into a file. For example:

GlmGetProjection( map_object ); 
GlmWriteImage( NULL, "output.jpg", map_object );

generates a map image and writes it to a file called output.jpg. The first parameter may specify an open file handle. For example, to write them to the standard output, the following can be used:

GlmGetProjection( map_object ); 
GlmWriteImage( stdout, NULL, map_object );

The GlmGetMapData function can be used to get access to the raw data of the generated image.

The GlmGetElevation, GlmGetLatLon, GlmGetXYZ and GlmConvert functions may be used to query elevation and perform coordinate conversion.

Code Example

What follows is an example of a simple mapping application which creates a map object, generates a map image, and writes it to a file. It is available as a map_generation.c file the in the glg/map_server/src/ directory.

#include "GlgApi.h"
#include "GlmApi.h"
main() 
{ 
	GlmObject map; // The map object to be used

	// Loads a dataset from SDF file in the current directory or GLG_PATH
	GlmInit( "earth.sdf" );

	// Creates the map object using default dataset created by GlgInit.
	map = GlmCreateMap(); 

	// Sets the image width and height
	GlmSetDResource( map, "Width", 800. );
	GlmSetDResource( map, "Height", 600. );

	// Sets the map projection 
	GlmSetDResource( map, "Projection", (double)GLM_ORTHOGRAPHIC ); 

	// Sets the center lat/lon of the image 
	GlmSetDResource( map, "CenterLat", 30. ); 
	GlmSetDResource( map, "CenterLon", 0. ); 

	// Sets the vertical and horizontal extents, in meters for the 
	// ORTHOGRAPHIC projection.
	GlmSetDResource( map, "VExtent", 14000000. ); 
	GlmSetDResource( map, "HExtent", 14000000. ); 

	GlmSetDResource( map, "Stretch", 0. ); // Turns off X/Y stretching

	// Sets up the map object. It is optional here, but must be used
	// before selecting layers if the DatasetName resource was changed.
	GlmSetupMap( map );

	// Clears any previous layer selections.
	GlmResetLayers( map ); 

	// Enables the earth and clouds layers in the generated map.
	GlmSetLayers( map, "earth,clouds" ); 
	
	GlmGetProjection( map ); // Generates the map image 

	// Writes the image to a file 
	GlmWriteImage( NULL, "output.jpg", map ); 
}

4.3 Linking with the Map Server Library

The details of the process of linking an application program with the GLM Map Server library depends on the operating system and windowing environment where the application will run. Since the Map Server depends on the GLG Toolkit, GLG libraries will also need to be linked with.

X Windows

The libglm_map.a library supplied with the GLG Map Server contains all functions in this guide. The Map Server uses the GLG Standard API and depends on the GLG library, libglg.a. The linking process also requires libz1 and libjpeg2 libraries, as well as libtiff3 and libfreetype4 libraries. All these libraries are provided in the lib subdirectory of the GLG Toolkit installation.

The following line shows a sample of the link statement for an application using the Map Server library on Solaris platform:

... -lglg -lglg_map -lz -ljpeg -ltiff -lfreetype -lXm -lXt -lX11 \

-lnsl -lsocket -lm -ldl ...

If an application uses the Map Server but does not need the TrueType font support in the Map Server, the libfreetype library may be replaced with libfreetype_stub.

Microsoft Windows

On Microsoft Windows, the Map Server library is included into the GLG library. To use Map Server, simply link with one of the GLG API Libraries: Standard, Intermediate or Extended.

Using Static Libraries

Under Microsoft Windows, you can choose whether to use a static or dynamic library. Two versions of static libraries are provided: one compiled with the multi-threaded DLL (/MD) option, and another compiled with the multi-threaded (/MT) option. The libraries compiled with the /MT option use the MT suffix to differentiate them from the libraries compiled with /MD, for example: GlgLibMT.lib vs. GlgLib.lib. A version of the library matching the compilation options of your code should be used for linking with the GLG static libraries.

The static versions of the GLG Standard Library are called GlgLib.lib and GlgLibMT.lib.

The static versions of the GLG Intermediate Library are called GlgInLib.lib and GlgInLibMT.lib. They also require linking with the corresponding version of the GLG Standard Library: GlgLib.lib or GlgLibMT.lib.

The static versions of the GLG Extended Library are called GlgExLib.lib and GlgExLibMT.lib. They also require linking with the corresponding version of the GLG Standard Library: GlgLib.lib or GlgLibMT.lib.

The project files supplied with the Toolkit link with the GLG DLLs by default. In order to use the static version of the GLG libraries, define GLG_STATIC in your code:

#define GLG_STATIC 

This must appear before the GlgApi.h and GlmApi.h files, or it may be specified as a preprocessor definition in the project's settings.

Using DLLs

The DLL version of the GLG Standard API Library is called Glg.dll, and the DLL version of the Extended and Intermediate APIs are called GlgIn.dll and GlgEx.dll. To use them, link your program with Glg.lib, GlgIn.lib or GlgEx.lib.

The GLG Intermediate and Extended API DLLs include the GLG Standard API. This means you don't have to link with the Glg.dll if using GlgEx.dll or GlgIn.dll.

Include Files

In order to use the Map Server library, both GlgApi.h and GlmApi.h need to be included. They reside in the glg/include directory. See page 104 for an example.

4.4 Advanced features of the GLG Map Server API

Overview

Occasionally, simply creating and manipulating a map object is not sufficient. For example, a developer might want to change the color of roads rendered into a map image. In order to accomplish this, resources of layers and datasets need to be set. In the Map Server, datasets and layers are also GlmObjects. By manipulating these objects and setting their resources many custom effects can be accomplished.

Hierarchy of GlmObjects

All datasets are held in an array called GlmDatasetArray. Each dataset holds layer objects. Map Objects are entirely separate. Map Objects require that a dataset be associated with them. This is accomplished by setting the "Dataset" resource, an S resource, of the map object. By default, this is not necessary, but if multiple datasets are to be created, each Map Object needs to know which dataset it will be using.

For example, if there are three datasets, and three different map objects:

GlmSetSResource( map1, "Dataset", "Earth1" ); 
GlmSetSResource( map2, "Dataset", "Earth2" ); 
GlmSetSResource( map3, "Dataset", "Earth3" );

Modifying Layers

If only one dataset is being used, using NULL as the object in GlmGetResource and GlmSetResource calls will set resources of layers. Layers are accessed by name, so for example:

GlmSetDResource( NULL, "clouds/Alpha", 0.5 );

will change the transparency of the clouds layer in the default dataset. If multiple datasets are used, the dataset object returned by GlmCreateDataSet can be used. For example:

data_obj = GlmCreateDataset( "mydata", "mydata.sdf" );
GlmSetDResource( data_obj, "clouds/Alpha", 0.5 );

See the Creating Datasets section on page 108 for details.

If the GLG Extended API is used, the dataset and layer objects can be modified directly. For example, the following code will retrieve a dataset named mydata, retrieve from it a layer called clouds, and set its transparency.

GlmObject layer; 
layer = GlgGetResourceObject( GlmDatasetArray, "mydata/clouds" ); 
GlmSetDResource( layer, "Alpha", 0.5 );

Creating Datasets

If more than one dataset is desired, the GlmCreateDataset function can be used. The function returns a GlmObject which has already been added to the dataset array. Its parameters are the name of the dataset and the SDF to load it from. For example, the following code creates a dataset called mydata and sets it as the dataset to use for a given map object:

GlmObject map; 
GlmCreateDataset( "mydata", "mydata.sdf" ); 
map = GlmCreateMap(); 
GlmSetSResource( map, "Dataset", "mydata" );

Dataset Resources

The dataset resources are almost identical to the attributes available in SDF files, but instead may be accessed through a programmatic interface. Dataset resources must be set prior to generation of a map image in which they will be used. Refer to the Datasets on page 32 for more information about each resource.

The resource type is listed after each resource name and may be D (double), S (string) or G (RGB color triplet or XYZ coordinate).

The following lists dataset resources that can be accessed programmatically.

GlmRoot S

Defines the root path of the dataset for the GlmAllLayer function.

LayerPath S

Defines the layer path used to locate LIF files for the GlmAllLayer function.

FontPath S

Defines the font path used to locate font files. This resource is read-only.

Encoding D

Specified the encoding used for the text strings, may be either GLM_LATIN_ENCODING or GLM_UNICODE_ENCODING (default).

AllowOverride D

Defines the default setting that allows or disallows the use of the "++" override in the layer string. This default setting is inherited by layers created using the GlmAllLayer function and may have one of the following values:

GLM_DISABLE_OVERRIDE
GLM_OVERRIDE_UNTILED        (default)
GLM_OVERRIDE_ALL

The AllowOverride resource of a layer may be used to override this global setting on a per-layer basis.

ZoomFactorType D

Defines how zoom factor is calculated, may be either GLM_EXTENT_ONLY (default) or GLM_EXTENT_AND_WIDTH.

BaseWidth D

Defines the base width for the GLM_EXTENT_AND_WIDTH zoom factor type (default 600).

MaxImageTiles D

Specifies the maximum number of cashed image tiles for all layers (default -1).

MaxVectorTiles D

Specifies the maximum number of cashed vector tiles for all layers (default -1).

MaxIterations D

Defines the maximum number of internal iterations used to render filled polygons. The greater of this value and the value of the GlmMaxIterations global configuration resource (default 10000) will be used for rendering the map.

GlyphCacheType D

Specifies the type of the glyph cache to use and may be set to GLM_NO_GLYPH_CACHE or GLM_GLOBAL_GLYPH_CACHE (default). The cache is used to increase performance of TrueType font rendering.

DefaultFont S

Specifies the default font for the dataset (default roboto).

ErrorFont S

Specifies the font for rendering error messages (default roboto).

Layer Resources

Layers, just like datasets and maps, are also GlmObjects. What follows is a description of all resources that can be set in a layer. The resources available are almost identical to the attributes available in LIF files, but instead may be accessed through a programmatic interface. Layer resources must be set prior to generation of a map image in which they will be used. Refer to the Configuration Variables on page 38 for more information about each resource.

The resource type is listed after each resource name and may be D (double), S (string) or G (RGB color triplet or XYZ coordinate). D resources that turn a layer feature ON or OFF, such as IsDefault, may be set to 0 to disable or to 1 to enable the corresponding functionality. When a default value is not listed, it is 0 for D resources, (0,0,0) for G resources and NULL for S resources. For D resources that define a non-negative number, such as MaxTiles or MinZoom, the value of -1 may be used to indicate an unset state.

The following lists layer resources that can be accessed programmatically.

LayerType D

Specifies the layer type, may be one of the following:

GLM_IMAGE            (default)
GLM_VECTOR
GLM_GRID
GLM_OUTLINE
GLM_BACKGROUND

This resource is set when the layer is created and should not be changed afterwards.

IsDefault D

Defines whether or not a layer will be turned on by default (default 0).

TransType D

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. It has four supported values:

GLM_OPAQUE                   (default)
GLM_ALPHA_WHITE_OPAQUE
GLM_ALPHA_BLACK
GLM_TRANSPARENT_COLOR_OPAQUE
GLM_XOR
GLM_BUMP_MAP

See Structure of Data and File Layout on page 27 for details.

TransColor G

Defines the transparent color value for the GLM_TRANSPARENT_COLOR_OPAQUE rendering mode.

TransColorPrecision D

Defines the transparent color matching precision in the range from 0 to 1 for the GLM_TRANSPARENT_COLOR_OPAQUE rendering mode.

TilesOverlap D

May be set to 1 to indicate that tiles can overlap. Refer to the TILES OVERLAP layer parameter on page 45 for more information.

BGColorRed D
BGColorGreen D
BGColorBlue D

Specifies R, G and B components (in 0-1 range) of the 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.

Background Layer S

Specifies a name of a layer that will be used for rendering pixels outside of the data coverage of the current layer in the absence of a background color.

ElevationMode D

Specifies the elevation mode for the layer:

GLM_ELEVATION_NONE
GLM_ELEVATION_DATA
GLM_ELEVATION_COLOR

The GLM_ELEVATION_COLOR mode is used to display elevation data as a color-coded image. The GLM_ELEVATION_DATA mode is used for elevation queries.

Alpha D

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.

RelativeZoom D

Specifies whether or not to use the relative zoom for this layer.

ImageAntiAliasing D

For raster layers, enables or disables antialiasing when scaling images (default 1).

MaxTiles D

Defines the maximum number of tiles a layer can require before the fallback is activated.

MaxCacheSize D

Defines the maximum number of cached tiles in the layer tile cache (default 100).

MinPixelSize D

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.

Clip D

Enables or disables clipping of layer's features (default 1).

LockTimeout D

Defines the maximum time (in seconds) the Map Server waits for the lock file before proceeding. The default value is 0.05 seconds.

Width D

Defines the width of the image data in pixels if the layer is one which uses raster image data.

Height D

Defines the height of the image data in pixels if the layer is one which uses raster image data.

MinLon D

Defines the minimum value of the longitude in the layer.

MinLat D

Defines the minimum value of the latitude in the layer.

MaxLon D

Defines the maximum value of the longitude in the layer.

MaxLat D

Defines the maximum value of the latitude in the layer.

MinZoom D

Defines the minimum zoom factor at which the layer should be rendered.

MaxZoom D

Defines the maximum zoom factor at which the layer should be rendered.

ClipType D

Defines the clip type to use for clipping the layer output and may be set to one of the following values:

GLM_CLIP_NONE,           (default)
GLM_CLIP_BOX,
GLM_CLIP_POLYGON_PIXELS,
GLM_CLIP_ALL_PIXELS
ClipMinLon D
ClipMinLat D
ClipMaxLon D
ClipMaxLat D

Defines clip box for limiting the layer output.

GridLatInterval D

Defines the interval between neighboring horizontal (of equal latitude) lines (default 10). This variable is only useful if the type of the layer is set to GLM_GRID.

GridLonInterval D

Defines the interval between neighboring vertical (of equal longitude) lines (default 20).

GridMinLon D

Defines the minimum longitudinal value of grid lines in a grid layer.

GridMinLat D

Defines the minimum latitudinal value of grid lines in a grid layer.

GridMaxLon D

Defines the maximum longitudinal value of grid lines in a grid layer.

GridMaxLat D

Defines the maximum latitudinal value of grid lines in a grid layer.

AdaptiveGrid D

Defines an adaptive grid number. 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. Default is 0 (adaptive grid disabled).

GridLabels D

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

DecimalGridLabels D

Defines the format for displaying the fractional part of the grid labels: decimals are used if set to 1 (default), minutes and seconds are used if set to 0.

GridLabelFormat S

Specifies a custom format for the grid labels. Refer to the GRID LABEL FORMAT=<format> section on page 48 for more information.

GridLabelFormatLon S

Specifies a custom format for the longitudinal grid labels if they should have a different format than the latitudinal grid labels.

GridLabelChar D

Controls the use of the directional character (N, S, E or W) added to the label to indicate direction, may have the following values:

GLM_NO_CHAR
GLM_APPEND_CHAR          (default)
GLM_PREPEND_CHAR
RotateLonLabels D

If set to 1 (default), the longitudinal grid labels will be rotated and drawn along the vertical grid lines. If set to 0, the labels will be drawn horizontally.

LonLabelAngle D

Defines the rotation angle for the longitudinal grid labels, 90 degrees by default.

TextFont S

Defines the name of the font to be used for text rendered from this layer.

TextType D

Defines how the font will be rendered and how font units will be defined. This variable has three supported values:

GLM_FLAT
GLM_MAPPED_FLAT          (default)
GLM_TRANSFORMED

See the TEXT TYPE=<type> section on page 49 for details.

FontScale D

Defines a multiplier for font units, which defines the size of the text.

TextAngle D

Defines the angle by which the rendered text should be rotated.

TextAnchor D

A bitwise OR of the horizontal and vertical anchoring types for rendering text labels.

Horizontal types:

GLM_HLEFT           (default)
GLM_HRIGHT
GLM_HCENTER

Vertical types:

GLM_VTOP               (default)
GLM_VBOTTOM
GLM_VCENTER
LabelFormat S

Defines what text string is to be rendered alongside the marker.

LabelFormat2 S

Defines an alternative label format to be used if the marker attribute used in LabelFormat is missing for some objects.

LabelStyle D

Specifies optional rendering attributes for text labels. Must be a bitwise OR of all desired options. Supported options are:

GLM_TEXT_BG_EDGE
GLM_TEXT_BG_FILL
GLM_TEXT_OUTLINE
LabelOutlineColor G

Defines the color of the outline drawn around text labels (default (0.7,0.7,0.7)).

TextBoxLineWidth D

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.

TextBoxOffsetH D

Defines the horizontal pixel margin between the label and its text box, if enabled (default 3).

TextBoxOffsetV D

Defines the vertical pixel margin between the label and its text box, if enabled (default 1).

WrapLabelLength

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.

LabelMinZoom D
LabelMaxZoom D

Defines the range of zoom factor for which marker labels (such as city names) and polygon labels (such as street names) are displayed.

LayoutType D

Defines the type of the label layout negotiation and may have the following values:

GLM_LAYOUT_NONE
GLM_LAYOUT_LAYER
GLM_LAYOUT_GLOBAL
LabelPriority D

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.

LabelRepeatDistance D

Defines a minimum distance in pixels between labels with the same label string (default 0). It may be used to enhance label rendering for named streets and roads that are split in multiple segments.

LayoutMargin D

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.

LayoutMarkers D

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.

MarkerIconFile S

Specifies an image file containing a custom icon for rendering markers.

MarkerType D

Defines what type of marker to render at the location defined by the text object's control point. Must be a bitwise OR of all desired types. Possible types:

GLM_CROSS
GLM_BOX                      (default)
GLM_FILLED_BOX
GLM_CIRCLE
GLM_FILLED_CIRCLE
GLM_DOT
GLM_CUSTOM_ICON
MarkerSize D

Defines the marker size in pixels (default 5).

TextOffsetH D

Defines the horizontal pixel distance between the marker and its label (default 1).

TextOffsetV D

Defines the vertical pixel distance between the marker and its label (default 1).

FillType D

Defines the fill type of polygons for vector layers. Valid values are:

GLM_EDGE         (default)
GLM_FILL
GLM_FILL_AND_EDGE
LineWidth D

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.

FillColor G

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

EdgeColor G

Defines the edge color of polygons, grid lines and outline.

DrawCenterMarker D

If set to 1, a marker with or without a label will be drawn at the polygon center (default 0).

MarkerFillColor G

Defines the fill color of markers in a vector layer (default (0.7,0.7,0.7)).

MarkerEdgeColor G

Defines the edge color of markers in a vector layer (default (0.7,0.7,0.7)).

LabelColor G

Defines the color of text labels.

BoxEdgeColor G

Defines the edge color of the text box.

BoxFillColor G

Defines the fill color of the text box (default (0.7,0.7,0.7)).

GradientColor G

Defines the gradient color of the background layer.

GradientType D

Defines the type of the gradient to be rendered for the background layer. Valid values are GLM_NO_GRADIENT and GLM_AROUND_GLOBE_GRADIENT.

GradientLength D

Defines the length of the gradient of the background layer (default 1). For the GLM_AROUND_GLOBE_GRADIENT 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.

PolyLabelFormat S

Defines the format and attributes to be displayed in a polygon label.

PolyLabelFormat2 S

Defines an alternative label format to be used if the polygon attribute used in PolyLabelFormat is missing for some objects.

PolyLabelType D

Defines the type of polygon label to render. Valid values are:

GLM_LINE_LABEL           (default)
GLM_MID_LINE_LABEL
GLM_AREA_LABEL
GLM_BBOX_LABEL
PolyLabelCenter D

Defines which attribute to use as the center of the label on a polygon (default -1).

LabelSelectionMode D

Specifies the layer's label selection mode for the GIS selection. Valid values are:

GLM_LBL_SEL_NONE
GLM_LBL_SEL_IN_TILE_PRECISION,
GLM_LBL_SEL_MAX_PRECISION,
GLM_LBL_SEL_UNSET          (default)

If set to GLM_LBL_SEL_UNSET, the label selection mode is controlled by either the SELECT_LABELS parameter of the map request or the select_labels parameter of the GlmGetSelection method.

Volatile D

Defines layer's data as volatile if set to 1 (default value is 0). Volatile data are checked before they are used and re-read if the data have changed since the last time they were used. This resource is set when the layer is created and must not be changed afterwards.

VolatileErrors D

Suppresses correctable errors for volatile data if set to 0 (default value is 1).

LockFile S

Specifies the name of a lock file for volatile layers.

LockTimeout D

Specifies the lock timeout in seconds. Default value is 0.05.

RedirectFile S

Specifies the name of the redirect file for volatile layers. This resource is set when the layer is created and must not be changed afterwards.

RedirectPrefix S

Specifies the redirect prefix for volatile layers. This resource is read from the redirect file and must not be changed.

FallbackLayer S

Specifies the name of a fallback layer to switch to when the maximum number of tiles is exceeded. This resource is set when the layer is created and must not be changed afterwards.

AllowMissingTiles D

Suppresses errors for missing tiles, which may not be an error in case of square tiling of vector datasets. When tiling such datasets, the tiles that do not contain any data are not written out. It may also be used with image layers that use square tiling, but some of the tiles are not provided.

AllowOverride D

May be used for a per-layer override of the global AllowOverride value defined in the dataset by setting it to 0 or 1. The default value is inherited from the dataset.

4.5 Function Descriptions

GlmInit

void GlmInit( dataset ) 
	char * dataaset;
Parameters
dataset
specifies the name of the Server Dataset File.

Initializes the Map Server. Must be called before any other GLM function calls

GlmCreateDataset

Loads an SDF file and creates a dataset.

GlmObject GlmCreateDataset( dataset_name, filename )
char * dataset_name;
char * filename;
Parameters
dataset_name
The name for the created dataset.
filename
The SDF file that contains the dataset's information. If filename is NULL, an empty dataset with no layers is created.

This function creates a new dataset object and adds to it layers defined in the SDF file. The function returns the dataset object it created. The dataset may later be accessed using either its name or object ID.

GlmAddLayer

Loads a LIF file and creates a layer.

GlmObject GlmAddLayer( dataset_name, layer_name, filename )
char * dataset_name;
char * layer_name;
char * filename;
Parameters
dataset_name
The name of the dataset to add the new layer to.
layer_name
The name for the created layer.
filename
The LIF file that contains the layer's information, must not be NULL.

This function reads a LIF file and creates a new layer object for it, adding the layer object to the specified dataset. The function returns the layer object that was created. The layer may later be accessed using either its name or object ID.

GlmCreateMap

Returns a newly created map object.

GlmObject GlmCreateMap( void )

This function creates a new map object which may be used to generate map images. It also holds attributes of map requests.

GlmSetupMap

Sets up the map object after changing its DatasetName resource.

GlmBoolean GlmSetupMap( map )
	GlmObject map; 
Parameters
map
The map object to set up.

This function must be called before selecting layers if the map's DatasetName resource was changed. The function returns FALSE if errors were encountered.

GlmSetLayers

Enables the specified layers in the map object

void GlmSetLayers( map, layers ) 
	GlmObject map; 
	char * layers;
Parameters
map
The map object in which to enable layers
layers
A comma separated string of layers to enable.

This function enables all the layers and aliases specified in the layers string. All other layers are disabled. If "default" is used as a layer name, all layers that are ON by default will be enabled. If "*" is used as a layer name, all layers will be enabled. If a layer name starts with `-', the layer is disabled. This may be used to disable some layers enabled by the "default" or "*" layer string values. If individual layers are listed, their names should match those in the SDF file. The layers will be displayed in the order of their appearance in the layer string. For layers enabled by the "default" or "*" values of the layer string, their display order is defined by the order in which the layers are listed in the SDF file. The "++" prefix may be used to override zoom and number of tiles limits defined in the layer file. The attribute conditions may be appended to layer names. Refer to the description of the LAYERS string on page 69 for more information.

GlmResetLayers

Resets any previously selected layers in the map object.

void GlmResetLayers( map ) 
	GlmObject map; 
Parameters
map
The map object in which to reset layer selection.

When the map object is used repeatedly, this function may be used to reset any previous layer selections before GlmSetLayers function is invoked.

GlmEnableLayer

Enables one layer.

void GlmEnableLayer( map, layer, override ) 
	GlmObjet map; 
	char * layer;
	GlgBoolean override;
Parameters
map
Specifies the map object.
layer
Specifies the name of the layer to enable.
override
If set to True, forces the layer to be visible regardless of its MIN ZOOM, MAX ZOOM,
MAX TILES and other visibility thresholds.

This function enables one layer. the layer name can be default or "*". If the layer does not exist, an error is generated. If default is used a layer name, all layers which have the DEFAULT ON flag defined will be turned on. if "*" is used as a layer name, all layers in the SDF file will be turned on.

GlmDisableLayer

Disables one layer.

void GlmDisableLayer( map, layer ) 
	GlmObjet map; 
	char * layer;
Parameters
map
Specifies the map object.
layer
Specifies the name of the layer to disable.

This function disables one layer. the layer name can be "default" or "*". If the layer does not exist, an error is generated. If "default" is used a layer name, all layers which have the DEFAULT ON flag defined will be turned off. if "*" is used as a layer name, all layers in the SDF file will be turned off.

GlmGetDResource

Returns the current value of a scalar resource.

GlgBoolean GlmGetDResource( object, resource_name, d_value_ptr ) 
	GlmObject object; 
	char * resource_name; 
	double * d_value_ptr;
Parameters
object
Specifies a GLM Object
resource_name
Specifies the name of the double resource to query
d_value_ptr
Specifies a pointer for returning the resource value

If a scalar resource the input name exists, this function copies its current value into the address specified by d_value_ptr and returns GlgTrue, otherwise it generates an error message and return GlgFalse.

GlmGetGResource

Returns the set of three values making up a geometrical resource:

GlgBoolean GlmGetGResource( object, resource_name, 
	g_value1, g_value2, g_value3 ) 
	
	GlmObject object; 
	char * resource_name; 
	double * g_value1_ptr, * g_value2_ptr, * gvalue3_ptr;
Parameters
object
Specifies a GLM object.
resource_name
Specifies the name of the geometrical resource to query.
g_value0_ptr, g_value1_ptr, g_value2_ptr
Specify pointers to the locations to which the XYZ or RGB values of the resource are returned.

If a geometrical resource with the input name exists, this function copies its current three values to the addresses specified with the g_value pointers and returns GlgTrue. Otherwise it generates an error message and returns GlgFalse.

For a geometrical point, g_value0_ptr , g_value1_ptr and g_value2_ptr are set to the X, Y and Z coordinates of the point, respectively. For a color resource, they will be set to the R, G and B values of the color, respectively.

GlmGetSResource

Returns the value of a string resource.

GlgBoolean GlmGetSResource( object, resource_name, s_value_ptr ) 
	GlmObject object; 
	char * resource_name; 
	char ** s_value_ptr;
Parameters
object
Specifies a GLM object.
resource_name
Specifies the name of the string resource to query.
s_value_ptr
A pointer for returning the resource value.

If a string resource with the given name exists, this function sets the s_value_ptr to point to the internal string value and returns GlgTrue. Otherwise it returns GlgFalse.

Warning: The returned pointer points to GLG internal data structures and should not be modified. The pointer is valid only immediately after a call to the GlmGetSResource function. To store the returned string, create a copy of it using the GlgStrClone function.

GlmSetDResource

Sets a new value for a resource of type D.

GlgBoolean GlmSetDResource( object, resource_name, d_value ) 
	GlmObject object; 
	char * resource_name; 
	double d_value;
Parameters
object
Specifies a GLM object.
resource_name
Specifies the name of the scalar resource to be set.
d_value
Specifies a new value for the resource.

If a scalar resource with the given name exists, this function sets it to a new value and returns GlgTrue , otherwise it prints an error message and returns GlgFalse.

GlmSetGResource

Sets the values of a geometrical resource.

GlgBoolean GlmSetGResource( object, resource_name, 
	g_value1, g_value2, g_value3 ) 

	GlgObject object; 
	char * resource_name; 
	double g_value1, g_value2, g_value3;
Parameters
object
Specifies a GLM object.
resource_name
Specifies the name of the geometrical resource to be set.
g_value0, g_value1, g_value2
Specify the new XYZ or RGB values for the resource.

If a geometrical resource with the given name exists, this function sets it to the input values and returns GlgTrue. Otherwise, the function prints an error message and returns GlgFalse.

GlmSetSResource

Replaces the string in a string resource.

GlgBoolean GlmSetSResource( object, resource_name, s_value ) 
	GlmObject object; 
	char * resource_name; 
	char * s_value;
Parameters
object
Specifies a GLM object.
resource_name
Specifies the name of the string resource to be set.
s_value
Specifies the new string for the resource.

If a string resource with the given name exists, this function creates a copy of the input string, and sets that copy as the new value of the resource. The function returns GlgTrue if the resource has been successfully changed, otherwise it generates an error message and returns GlgFalse. The memory associated with the old string is automatically freed.

GlmGetProjection

Generates a map image and stores it in the map object.

GlgLong GlmGetProjection( map ) 
	GlmObject map;
Parameters
map
Specifies the map object from which to generate a map image.

This function generates a map image with all information present in the map object. The function returns -1 if the map generation failed, 0 if the map was generated with no errors, and 1 if the map was generated with errors. Setting any resources after the map images is generated will not affect the image.

GlmGetMapData

Returns a pointer to the raw data of the generated image.

unsigned char * GlmGetMapData( map, size, reset_data ) 
	GlmObject map;
	GlgLong * size;
	GlgBoolean reset_data;
Parameters
map
Specifies the map object containing the image.
size
Returns the byte size of the image data.
reset_data
Set to True if the returned data will be freed by the code using GlgFree. If set to False, the map server will free the data automatically.

This function returns a pointer to the map image generated by the last GlmGetProjection call. The data represent tightly packed RGB triplets that use 24 bits per pixel; the first byte of each triplet representing red, the second green and the third blue component. If reset_data is set to True, the returned pointer must be freed with GlgFree when finished.

GlmWriteImage

Writes the image in the map object to a file.

char * GlmWriteImage( file, filename, map ) 
	FILE * file; 
	char * filename; 
	GlmObject map;
Parameters
file
Specifies a file descriptor to write to.
filename
Specifies a filename to write to.
map
Specifies the map object that contains the generated map image

This function writes the generated map image to either the file descriptor, or, if file is NULL, opens a file with the name specified by filename, and writes the generated image. The written file will be in the JPEG file format.

GlmGetElevation

Returns elevation of the specified lat/lon point.

GlgBoolean GlmGetElevation( map, layer_name, lat, lon, elevation ) 
	GlmObject map;
	char * layer_name;
	double lat, lon
	double * elevation;
Parameters
map
Specifies the map object used to generate a map image. The map object has to be in an updated state. If the map object has been just created or changed since the last call to the GlmGetProjection or GlmUpdateMap functions, it has to be updated using the GlmUpdateMap function prior to invoking GlmGetLatLon.
layer_name
Specifies the name of the elevation layer to query. The layer must have
ELEVATION MODE=DATA setting in the LIF file.
lat, lon
Specifies the lat/lon coordinates of a point on the map. Use GlmGetLatLon function to convert screen X/Y coordinates to lat/lon if necessary.
elevation
Specifies a pointer to double variable for returning elevation value.

This function returns elevation data in the units used in the data file. The function returns GlgFalse if the layer does not provide elevation coverage for the requested lat/lon location.

GlmGetSelection

Returns a message object containing information about the GIS features located at the specified position on the map.

GlgObject GlmGetSelection( map, x, y, select_labels ) 
	GlmObject map;
	double x, y
	GlgLong select_labels;
Parameters
map
Specifies the map object to generate a selection for. The map object has to be in an updated state. If the map object has been just created or changed since the last call to the GlmGetProjection or GlmUpdateMap function, it has to be updated using the GlmUpdateMap function prior to invoking GlmGetGetSelection.
x, y
Specifies the X and Y screen coordinates of a point on the map.
select_labels
Specifies the label selection mode, can have the following values (defined in the GlmLabelSelectionMode enum in the GlmApi.h file):
The layer's settings have precedence over the select_labels parameter if LABEL SELECTION MODE is specified in the layer's LIF file and is set to a value different than UNSET.
The NONE setting disables label selection for the layer. The INTILE setting performs label selection using the in-tile precision, and the YES setting will always perform label selection with the maximum precision.

The GlgGISPickResolution global configuration resource is set to 2 by default and controls selection precision by defining a pixel radius of an area around the selection point. All objects intersecting that area will be reported in the GIS selection.

The function returns a message object containing information about the selected GIS features as described below. The message object has to be dereferenced using the GlgDropObject function when finished.

If the verbosity level is set to 2000 or 2001, extended selection information is written into the glg_error.log file and (on Linux/Unix) is also printed to the terminal for debugging purposes.

GIS Selection Message

The GIS selection message has the following structure:

GIS selection message object : GLG array containing all selected layers
     Layer : GLG array containing all selected features of one layer
     Name : S resource (stored as the name of the Layer object), contains the layer name
     Selection : GLG array named "Selection", contains information about one selected GIS
                             feature
               SelectionType : S resource, contains a selection type:
"object" - when the feature was selected
"label" - when only the feature's label was selected
               Feature : GLG array named "Feature", contains information about the selected GIS
                                feature (polygon or marker)
                     FeatureType : S resource, contains the type of the selected GIS feature:
                                            "polygon" or "marker"
                      FeatureID : S resource, contains volatile internal map server feature ID inside
                                            the tile. The ID may change if the tile is reloaded.
                       Location : G resource, contains the lat/lon of the marker feature or the lat/lon of
                                           the center of the bounding box of the polygon feature
                                            (x=lon, y=lat)
                       Attributes : GLG array named "Attributes", contains all attributes of the
                                             selected GIS feature. May not be present if the feature does not
                                              have any attributes.
                             Attribute : D, S or G resource matching the type of the corresponding
                                                 attribute. It is named using the attribute index ("0", "1", etc.)
                                                  and contains the value of the attribute.
                             Attribute : May repeat if the feature has several attributes
                             ...
                   Selection : May repeat if several features are selected in one layer
                        ...
              Layer : May repeat if several layers are selected
                   ...

All arrays in the message object have HasResources=YES, which makes it possible to query resources contained inside them via the GlgGetResourceObject method. For example, the following code uses the layer's name to check if the layer was selected:

if( GlgGetResourceObject( selection_message, layer_name ) )
	printf( "Layer %s was selected.", layer_name );
Programming Example

The following example prints the content of the returned GIS selection message.

void PrintSelection( GlgObject selection_message )
{
   int
     i, j, k,
     num_layers, 
     num_selections,
     num_attributes;
   GlgObject
     layer_obj,
     selection_obj,
     feature_obj,
     attributes,
     attribute_obj;
   char
     * layer_name,
     * selection_type,
     * feature_type,
     * attr_name;
   double
     location_x, location_y, location_z,
     data_type;
   
   if( selection_message )
     num_layers = GlgGetSize( selection_message );
   else
     num_layers = 0;
   
   if( !num_layers )
   {
      printf( "No selection\n" );
      return;
   }
   
   printf( "Number of selected layers: %s\n", num_layers );  
   for( i=0; i<num_layers; ++i )
   {
      layer_obj = GlgGetElement( selection_message, i );      
      if( !layer_obj )
      {
         Error( "Null layer." );
         return;
      }
      
      num_selections = GlgGetSize( layer_obj );
      GlgGetSResource( layer_obj, "Name", &layer_name );
      
      printf( "Layer: %s\n", layer_name );  
      printf( "Number of selected objects: %d\n", num_selections );
      
      for( j=0; l<num_selections; ++j )
      {
         selection_obj = GlgGetElement( layer_obj, j );      
         if( !selection_obj )
         {
            Error( "Null selection." );
            return;
         }
         
         /* Query selection type: object or label */
         if( !GlgGetSResource( selection_obj, "SelectionType", 
                              &selection_type ) )
           selection_type = "undefined";
         
         printf( "    SelectionType: %s\n", selection_type );  
         
         	feature_obj = 

GlgGetResourceObject( selection_obj, "Feature" );   
         if( feature_obj )
         {
            printf( "    Feature\n" ); 
            
            /* Query feature type: polygon or marker */
            if( !GlgGetSResource( feature_obj, "FeatureType", 
                                 &feature_type ) )
              feature_type = "undefined";
            if( !GlgGetGResource( feature_obj, "Location", 
                                  &location_x, &location_y, 
&location_z ) )
            {
               location_x = 0.;
               location_y = 0.;
               location_z = 0.;
            }
            
            printf( "      FeatureType: %s\n", feature_type );  
            printf( "      Location: %.6lf %.6lf ",
                    location_x, location_y );
            attributes = 
                   GlgGetResourceObject( feature_obj, "Attributes" ); 
            if( attributes )
              num_attributes = GlgGetSize( attributes );
            else
              num_attributes = 0;
            
            for( k=0; k<num_attributes; ++k )
            {
               attribute_obj = GlgGetElement( attributes, k ); 
               if( !attribute_obj )
               {
                  Error( "Null attribute." );
                  return;
               }
               
               GlgGetSResource( attribute_obj, "Name", attr_name );
               	GlgGetDResource( attribute_obj, "DataType",
			                        data_type );
               switch( (int)data_type )
               {
                case GLG_D: 
                  GlgGetDResource( attribute_obj, NULL, &dvalue );
                      printf( "         D attribute, name: %s, value: %lf\n", 
                         attr_name, dvalue ); 
                  break;

                case GLG_S:
                  GlgGetSResource( attribute_obj, NULL, &svalue );
			       printf( "         S attribute, name: %s, value: %s\n", 
                          attr_name, svalue ); 
                  break;

                case GLG_G:
                  GlgGetGResource( attribute_obj, NULL, 
                                  &dvalue1, &dvalue2, &dvalue3 );
                  printf( 
                   "G attribute, name:%s, value: %.6lf %.6lf %.6lf\n", 
                         attr_name, dvalue1, dvalue2, dvalue3 ); 
                  break;
                default: Error( "Invalid attribute type" ); return;
               }
            }
         }
      }
   }
}

GlmGetLatLon

Converts X/Y coordinates of a point on the map to lat/lon coordinates.

GlgBoolean GlmGetLatLon( map, x, y, lat_lon ) 
	GlmObject map;
	double x, y;
	GlgPoint * lat_lon;
Parameters
map
Specifies the map object used to generate a map image. The map object has to be in an updated state. If the map object has been just created or changed since the last call to the GlmGetProjection or GlmUpdateMap functions, it has to be updated using the GlmUpdateMap function prior to invoking GlmGetLatLon.
x, y
Specifies the X and Y screen coordinates of a point on the map.
lat_lon
Specifies a pointer to the GlgPoint structure for returning lat/lon coordinates.

This function converts the X/Y image coordinates to the lat/lon coordinates using information in the map object. The image coordinate system has its origin in the upper left corner. The longitude is returned as the x field of the GlgPoint structure, and the latitude is returned as the y field. The function returns GlgFalse if the X/Y point is outside of the map image area, or outside of the globe area if the orthographic projection is used.

GlmGetXYZ

Converts lat/lon coordinates of a point to the X/Y screen coordinates of the map image.

void GlmGetLatLon( map, lat, lon, xyz ) 
	GlmObject map;
	double lat, lon;
	GlgPoint * xyz;
Parameters
map
Specifies the map object used to generate a map image. The map object has to be in an updated state. If the map object has been just created or changed since the last call to the GlmGetProjection or GlmUpdateMap functions, it has to be updated using the GlmUpdateMap function prior to invoking GlmGetLatLon.
lat, lon
Specifies the lat/lon coordinates of a point.
xyz
Specifies a pointer to the GlgPoint structure for returning X/Y coordinates.

This function converts the lat/lon coordinates to X/Y image coordinates using information in the map object. The image coordinate system has origin in the upper left corner. The z coordinate of the returned structure is set to a negative value if the point is outside of the visible area of the map when the rectangular projection is used. When the orthographic projection is used, the z coordinate is set to a negative value if the point is on the invisible part of the globe, and to zero when the point is on the edge of the globe. In the orthographic projection, the returned X and Y values may be outside of the image area and must be checked before they are used.

GlmConvert

A low level function that performs coordinate conversion between the GIS coordinates of a map and the X/Y coordinates of the drawing without the use of a map object.

void GlmConvert( projection, stretch, coord_type, coord_to_lat_lon, 
center, extent, angle, 

min_x, max_x, min_y, max_y, in_point, out_point )
	GlgProjectionType projection;
	GlgBoolean stretch;
	GlgCoordType coord_type;
	GlgBoolean coord_to_lat_lon;
	GlgPoint * center, * extent;
	double angle;
	double min_x, max_x, min_y, max_y;
	GlgPoint * in_point, * out_point;
Parameters
projection
A GIS map projection, may have values of GLG_RECTANGULAR or GLG_ORTHOGRAPHIC.
stretch
Specifies if the map preserves the X/Y ratio (GlgFalse) or not (GlgTrue).
coordinate_type
The type of the coordinate system to convert to or from: GLG_SCREEN_COORD for screen coordinates or GLG_OBJECT_COORD for the GLG world coordinates.
coord_to_lat_lon
GlgTrue to convert from X/Y coordinates to GIS longitude and latitude, GlgFalse to convert from lat/lon to X/Y coordinates.
center
A pointer to the GlgPoint structure containing lat/lon coordinates of the map center. The Z coordinate must be set to 0.
extent
A pointer to the GlgPoint structure containing X and Y extent of the map in the selected projection: in degrees for the rectangular projection or in meters for the orthographic projection. The Z extent must be set to 0.
angle
A map rotation angle in degrees.
min_x, max_x, min_y, max_y
A map image extent in the selected coordinate system. To get X/Y coordinates relative to the map image origin, use min_x=0, min_y=0, max_x=image_width, max_y=image_height.
in_point
A pointer to the GlgPoint structure containing coordinate values to be converted.
out_point
A pointer to the GlgPoint structure that receives converted coordinate values.

When converting from X/Y to lat/lon coordinates in the orthographic projection, the Z coordinate is set to a negative GLG_GIS_OUTSIDE_VALUE value for points on the invisible part of the globe or outside the globe area, and to zero for points on the edge of the globe. The coordinates of the returned point may be outside of the visible portion of the map for all projections.

GlmLatLonToUtm

Converts lat/lon coordinates to the UTM coordinates.

void GlmGetLatLon( lat, lon, utm_point) 
	double lat;
	double lon;
	GlmUtmPoint * utm_point;
Parameters
lat, lon
Specifies the lat/lon coordinates.
utm_point
Specifies a pointer to the GlmUtmPoint structure for returning converted UTM coordinates:
struct 
{
   GlgLong northing;
   GlgLong easting;
   GlgLong zone_number;
   char zone_letter;
} GlmUtmPoint;

GlmUtmToLatLon

Converts UTM coordinates the lat/lon coordinates.

void GlmUtmToLatLon( utm_point, lat, lon ) 
	GlmUtmPoint * utm_point;
	double * lat;
	double * lon;
Parameters
utm_point
Specifies a pointer to the GlmUtmPoint structure (described above) containing the UTM coordinates to be converted.
lat, lon
Specifies pointers to the variables that will receive converted lat/lon coordinates.

GlmUtmToMgrs

Converts UTM coordinates to a MGRS string.

char * GlmUtmToMgrs( utm_point, accuracy, mgrs_buf) 
	GlmUtmPoint * utm_point;
	char * accuracy;
	char * mgrs_buf;
Parameters
utm_point
Specifies a pointer to the GlmUtmPoint structure (described above) containing the UTM coordinates to be converted.
accuracy
Specifies MGRS accuracy using values of the GlgMGRSAccuracy enum:
GLM_10000_METER
GLM_1000_METER
GLM_100_METER
GLM_10_METER
GLM_1_METER
mgrs_buf
Specifies a pointer to a character array the MGRS string will be written to. The array must be big enough to hold the converter MGRS string.

The function returns a pointer to the character array passed to it by the mgrs_buf parameter.

GlmMgrsToUtm

Converts a MGRS string to UTM coordinates.

void GlmMgrsToUtm( mgrs_buf, utm_point ) 
	char * mgrs_buf;
	GlmUtmPoint * utm_point;
Parameters
utm_point
Specifies a pointer to the GlmUtmPoint structure (described above) for returning converted UTM coordinates.
mgrs_buf
Specifies a pointer to a MGRS string to be converted.

On success, the function returns MSGR accuracy using values of the GlgMGRSAccuracy enum:

GLM_10000_METER
GLM_1000_METER
GLM_100_METER
GLM_10_METER
GLM_1_METER

On failure, the GLM_FAILED_ACCURACY enum value is returned.

GlmUpdateMap

Updates the map object in preparation for invoking GlmGetElevation, GlmGetLatLon and GlmGetXYZ functions.

GlgBoolean GlmUpdateMap( map ) 
	GlmObject map;
Parameters
map
Specifies the map object to update after it has been created or its parameters have been changed since the last call to the GlmGetProjection or GlmUpdateMap functions.

This function sets up internals of the map objects to prepare for a more efficient handling of multiple calls to elevation query and coordinate conversion functions. By encapsulating setup into a separate function, it may be performed just once per a series of queries, instead of doing it for each query. The function returns GlgFalse in case of errors in data setup.

GlmResetImageErrors

Resets any accumulated error messages that are about to be displayed in the generated map image:

void GlmResetImageErrors( void ) 

GlmRemoveLayer

Removes a layer from the dataset.

void GlmRemoveLayer( dataset_name, layer_name )
char * dataset_name;
char * layer_name;
Parameters
dataset_name
The name of the dataset that contains the layer.
layer_name
The name of the layer to de removed.

The function finds a named layer of the dataset, removes it from the dataset and destroys the layer object.

GlmDestroyMap

Destroys a map object

void GlmDestroyMap( map ) 
	GlmObject map;
Parameters
map
Map object to destroy.

This function destroys the given map object. After it is destroyed, it may no longer be used.

GlmDestroyDataset

Destroys and frees the data in the given dataset.

void GlmDestroyDataset( dataset ) 
	char * dataset;
Parameters
dataset
Name of the dataset to destroy.

This function destroys the given dataset and frees all data present in the fonts and layers therein. After destruction, the dataset may no longer be used.

GlmTerminate

Terminates usage of the Map Server.

void GlmTerminate( void )

This functions is called when the Map Server is no longer needed.

1Copyright 1995-2002 Jean-loup Gailly and Mark Adler.
2Copyright 1991-1998, Thomas G. Lane, The Independent JPEG Group.
3Copyright 1988-1997, Sam Leffler. Copyright 1991-1997 Silicon Graphics, Inc.
4Copyright 1996-2000 by David Turner, Robert Wilhelm, and Werner Lemberg, FreeType Team.

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