The GLM Vector Format (GVF) is an open format for describing vector and text data, and is used by the GLG Map Server. The ASCII version of the GVF format is portable across architectures of varying endianness as well as 32-bit and 64-bit architectures, while the binary version provides faster loading time.
If data used in the GLG Map Server is not in the GLM Vector Format, it must be converted. It can either be converted on the fly or converted and saved to a GVF file, which can then be used by the Map Server directly. When the data are converted on the fly, the program that performs the conversion is used as a filter by the Map Server. Converting just once and saving converted data into a file is more efficient, but filters may be used as an interface to external databases and data sources.
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. However, there exist many other custom vector data formats requiring conversion, and the Map Server provides convenience functions for writing a data file in GVF format. The convenience filter functions are provided in a form of the Gvf.c file (in the map_server/src directory) containing the source code of these functions. In order to use it, it must be included in any project that uses the functions. The map_server/src directory contains source code examples of a few commonly used converters.
The first two parameters of GVF functions are common to all of them. The first parameter of all GVF API functions is a file descriptor of an already open file to use for writing GVF data. When the functions are used to write a filter used with the Map Server to convert data files on the fly, stdout must be used as the file parameter to write GVF data to the standard output. Furthermore, no other data may be written to the standard output by the filter. Most of the examples in this chapter use stdout as the first parameter for simplicity.
The second parameter to all GVF functions defines the GVF file format: GVF_ASCII or GVF_BINARY. The ASCII data are cross-platform, but binary data provide much faster load time. It is recommended to write all data in the ASCII mode, and then convert them to the binary mode using the Map Server's GVF converter utility on each of the target platforms.
Before any data can be written, the GvfWriteHeader function must be called to write the appropriate header to the output file. If this header is not written, the Map Server will not recognize the file as a GVF file and will not read it correctly:
GvfWriteHeader( stdout, GVF_ASCII );After the header is written, objects can be written to the file. There are two types of objects, polygons and markers (text is a marker too). Before the data for each polygon or marker is written, it's header must be written. After the object's header is written, all attributes associated with that object must be written, if any exist. Finally, the actual point data can be written to the file.
The polygon header is written via a call to the function GvfWritePolygon . The function must be passed whether the polygon has rings or not, how many points are in the polygon, and how many attributes it contains. The rings parameter is used for composite polygons. These are polygons in which adjacent points are not necessarily connected. For example, a lake with islands might be a composite polygon. If the polygon is composite, each section of the polygon is defined as a polygon itself. All but the last section will have the rings parameter set to 1, but the last section will be set to 0. Any non-composite polygon should have the rings parameter set to 0. For example:
GvfWritePolygon( stdout, GVF_ASCII, 0, 100, 3 );will define a polygon that is non-composite, has 100 points and has 3 attributes. The attributes are written into the data file separately using the GlmWriteAttribute function, and the points are written last using the GvfWritePoint function.
Note: Attributes, as referred to here, are custom attributes associated with polygons. Color, linewidth and other graphical properties are defined in the layer.
The marker headers is written via a call to the function GvfWriteMarker . The function must passed the marker type, the scale, the angle, the anchor, the string and the number of attributes in the object. The type can have the following values:
GVF_M_MARKER
The simplest type, with all marker attributes specified in the LIF file. The marker's string label may be defined in the data file as a marker's attribute and rendered using the
LABEL FORMAT
LIF option.
GVF_M_LABEL
All attributes except the string (scale, angle and anchor) are specified in the LIF file, and the string specified with the marker object in the data file, as part of the marker.
GVF_M_TEXT
All attributes (scale, angle, anchor and string) are specified with the object in the data file.
Regardless of type, all markers can have a graphical marker and a label. The various marker types specify where different properties of the marker are defined. The position is always defined in the data file. In almost all cases, GVF_M_MARKER is desired.
GvfWriteMarker( stdout, GVF_ASCII, GVF_M_MARKER, 0., 0., 0, NULL, 2 );defines a simple marker with two attributes (which may be population and city name). The attributes are written into the data file separately using the GlmWriteAttribute function and the marker's point must be written last using the GlmWritePoint function.
After an object is defined, its attributes, if any exist, must be written. Each attribute is written via a call to the GvfWriteAttribute function. It is passed the number of the attribute, the type, the double value, if a D type, a string, if an S type, and three doubles if a G type attribute. Valid values for the type are:
GLM_G
geometrical or color, 3 doubles
defines the second attribute to be of type D, and have a value of 50000. The second parameter supplies a numerical attribute name. The third parameter is used for passing a string value for string attributes, and the last three parameters are used to pass values of geometrical or color attributes.
After the header and attributes are written, points data can be written to the output file. Data points are a pair of values, usually longitude and latitude. Polygons have an arbitrary number of data points, defined by the num_points parameter of the GlmWritePolygon function. Markers must have exactly one data point defined. Each data point is written into the file with a call to the GvfWritePoint function. It is passed the two point values and a printf style format used in the ASCII mode. For use with the Map Server, the format should contain two space-separated floating point format specifications, for example:
"%lf %lf "Since six digit precision is usually enough for most of the GIS application, the format may parameter may specify precision for more compact data:
"%.6lf %.6lf "The format parameter is ignored in the binary mode.
GvfWritePoint( stdout, GVF_ASCII, 10., 30., "%.6lf %.6lf " );The following example defines a polygon with 1 attribute and 5 points
GvfWritePolygon( stdout, GVF_ASCII, 0, 5, 1 ); GvfWriteAttribute( stdout, GVF_ASCII, 1, GLM_D, 50000, NULL,The following example writes a simple marker with one attribute
GvfWriteMarker( stdout, GVF_ASCII, GVF_M_MARKER, 0., 0., 0, NULL, 1 ); GvfWriteAttribute( stdout, GVF_ASCII, 1, GLM_D, 50000, NULL,Defines the number of attributes.
This function writes a marker definition to the specified file descriptor with the given properties and the given number of attributes. If the type is GVF_M_MARKER , then none of the properties needs to be defined. If the type is GVF_M_LABEL , only the string needs to be defined. If the type is GVF_M_TEXT , the scale, angle, anchoring and string need to be defined.
Specifies a printf style format for the point to be written in.
This function writes a data point to the specified file descriptor with the given location and uses the given format. For use with the Map Server, the format should contain two space-separated floating point format specifications, for example:
"%lf %lf "Since six digit precision is usually enough for most of the GIS application, the format may parameter may specify precision for more compact data:
"%.6lf %.6lf "The number of points must match the num_points parameter passed to GvfWritePolygon .
The GLM Vector Format, as described in this RFC uses, throughout, the extension and abbreviation "GVF". Although GVF files must not necessarily have this extension, it is used for the purpose of this RFC.
Wherever constants are mentioned with the GLM or GVF prefix, their enumerated values should be substituted. What follows is the enumeration of constants to be used throughout the RFC.
GVF_MAGIC 0x69c GVF_OBJ_HEADER 0x7 GVF_ASCII 0x0 GVF_BINARY 0x1 GVF_POLYGON 0x0 GVF_MARKER 0x1 GVF_M_MARKER 0x0 GVF_M_LABEL 0x1 GVF_M_TEXT 0x2 GLM_S 0x1 GLM_D 0x2 GLM_G 0x3 GLM_HCENTER 0x0 GLM_HRIGHT 0x1 GLM_HLEFT 0x2 GLM_VCENTER 0x0 GLM_VTOP 0x10 GLM_VBOTTOM 0x20This format specification only describes the plain-text ASCII version of the GLM Vector format. The binary version uses the native data representation for each platform and is produced by writing data into the file in the same sequence, but using the native raw data format. The first line of the GVF file contains a GVF file header and is always written in ASCII format. It is recommended that all saved data are first saved in the platform-independent ASCII format and then converted to the binary format using the Map Sever's GVF data converter.
In the ASCII version of the GVF format, all integral values are written in hexadecimal form, but without the preceding 0x. All floating point values, such as those present in data points, will be written in their standard decimal form as written by the standard C library function printf . All strings are written by first specifying the length of the string as an integral value and then the characters of the string as ASCII characters, including the terminating null character. In an ASCII version of the GVF format, all entries must be separated by at least one whitespace character.
The first three entries in a GVF file must be the magic number, GVF_MAGIC , the version number, and the format, GVF_ASCII or GVF_BINARY .
After the header is defined, objects may be defined one after another in the following format.
The object header, GVF_OBJ_HEADER , must be written.
The type of object must be written
The object must be defined with the required properties, including:
The number of attributes associated with that object.
If the number of attributes is non-zero, the correct number of attributes must be defined after the object itself is defined.
After the object header is written, the type of object may be one of:
GVF_POLYGON GVF_MARKERIf the object type is GVF_POLYGON , a polygon definition must follow. If the object type is GVF_MARKER , a marker definition must follow.
Polygons are defined to have 3 integral properties following the header. These properties are:
Specifies whether or not the polygon has sub-sections, i.e. whether or not the polygon is composite. If set to 0, the polygon is assumed to be non-composite. If set to 1, the polygon is assumed to be composite and that subsequent polygon definitions define other sections of the polygon. The last section in the definition of a composite polygon must have a Ring parameter of 0.
Markers are defined to have up to 6 properties following the header. These properties are:
Specifies the type of marker to be written, must be one of:
GVF_M_MARKER
The simplest type, with all marker attributes specified in the LIF file. The marker's string label may be defined in the data file as a marker's attribute and rendered using the
LABEL FORMAT
LIF option.
GVF_M_LABEL
All attributes except the string (scale, angle and anchor) are specified in the LIF file, and the string specified with the marker object in the data file, as part of the marker.
GVF_M_TEXT
All attributes (scale, angle, anchor and string) are specified with the object in the data file.
Defines the angle of the marker's text as a floating point value. Must be in degrees, counter-clockwise from the right horizontal axis.
Defines the anchoring of the marker's text as an integral value. Must be a bitwise OR of the horizontal and vertical anchoring types. The horizontal anchoring must be one of:
GLM_HCENTER GLM_HRIGHT GLM_HLEFTand the vertical anchoring must be one of:
GLM_VCENTER GLM_VTOP GLM_VBOTTOMSpecifies the number of attributes associated with the given marker object. After the marker definition, exactly this number of attributes must be defined. Defining a different number of attributes after the marker is invalid.
All marker types require the Marker Type and Number of Attributes properties, but the rest of the properties depends on the marker type. If the type is GVF_M_MARKER , none of the properties are necessary. If the type is GVF_M_LABEL , only the Text String is required. If the type is GVF_M_TEXT , then the Scale , Angle , Anchoring and Text String are required.
Attributes are defined by first writing their name and type. The name is an integral value and the type must be one of:
GLM_D GLM_S GLM_GAfter the name and type, the value must be written. If the type is GLM_D , the value is a floating point number. If the type is GLM_S , the value must be a string. If the type is GLM_G , the value must be exactly three floating point numbers.