PREV NEXT

Generic Logic, Inc. www.genlogic.com


5 GVF Filters and Data Converters

5.1 GVF API Reference

Overview

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.

GVF Functions

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.

Headers

The provided header file Gvf.h must be included in all filters:

#include "Gvf.h"

Writing a Filter or Data Convertor

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.

Polygons

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.

Markers

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.

For example:

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.

Attributes

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_D
double
GLM_G
geometrical or color, 3 doubles
GLM_S
string

For example:

GvfWriteAttribute( stdout, GVF_ASCII, 1, GLM_D, 50000, NULL, 

0., 0., 0. );

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.

Points

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.

The following example:

GvfWritePoint( stdout, GVF_ASCII, 10., 30., "%.6lf %.6lf " );

defines a point with longitude 10 and latitude 30.

Examples

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, 

0., 0., 0. );
GvfWritePoint( stdout, GVF_ASCII, 10., 30., "%lf %lf " ); 
GvfWritePoint( stdout, GVF_ASCII, 20., 31., "%lf %lf " ); 
GvfWritePoint( stdout, GVF_ASCII, 30., 32., "%lf %lf " ); 
GvfWritePoint( stdout, GVF_ASCII, 40., 33., "%lf %lf " ); 
GvfWritePoint( stdout, GVF_ASCII, 50., 34., "%lf %lf " );

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, 

0., 0., 0. );
GvfWritePoint( stdout, GVF_ASCII, 10., 30., "%lf %lf " );

Function Descriptions

GvfWriteHeader

Writes the header.

void GvfWriteHeader( file, mode ) 
	FILE * file;
	GvfSaveFormat mode;
Parameters
file
Specifies a file descriptor.
mode
Specifies GVF_ASCII or GVF_BINARY file writing mode.

This function writes the Glm Vector Format header to the specified file descriptor. Must be called before any other GVF function calls.

GvfWritePolygon

Writes a polygon.

void GvfWritePolygon( file, mode, ring, num_points, num_attr ) 
	FILE * file; 
	GvfSaveFormat mode;
	long ring; 
	long num_points; 
	long num_attr;
Parameters
file
Specifies a file descriptor.
mode
Specifies GVF_ASCII or GVF_BINARY file writing mode.
ring
Specifies whether or not the polygon has sub-sections.
num_points
Defines the number of data points.
num_attr
Defines the number of attributes.

This function writes a polygon definition to the specified file descriptor with the given number of data points and the given number of attributes.

GvfWriteMarker

Writes a marker.

void GvfWriteMarker( file, mode, type, scale, angle, anchor, string, 
num_attr ) 
	FILE * file; 
	GvfSaveFormat mode;
	GvfMarkerType type; 
	double scale; 
	double angle; 
	long anchor; 
	char * string; 
	long num_attr;
Parameters
file
Specifies a file descriptor.
mode
Specifies GVF_ASCII or GVF_BINARY file writing mode.
type
Specifies the marker type, must be one of:
GVF_M_MARKER 
GVF_M_LABEL 
GVF_M_TEXT 
scale
Defines the scale of the marker's text.
angle
Defines the angle of the marker's text.
anchor
Defines the anchoring of the marker's text.
string
Defines the text-string of the marker's text.
num_attr
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.

GvfWriteAttribute

Writes an attribute.

void GvfWriteAttribute( file, mode, name, data_type, d_val, s_val, 
g_val_x, g_val_y, g_val_z ) 
	FILE * file;
	GvfSaveFormat mode;
	long name; 
	GlmDataType data_type; 
	double d_val; 
	char * s_val; 
	double g_val_x, g_val_y, g_val_z;
Parameters
file
Specifies a file descriptor.
mode
Specifies GVF_ASCII or GVF_BINARY file writing mode.
name
Specifies the attribute number. Attribute numbers are used as attribute names for efficiency.
data_type
Specifies the type of the attribute, must be one of:
GLM_D 
GLM_S 
GLM_G 
d_val
Defines the value of the attribute if the type is GLM_D.
s_val
Defines the value of the attribute if the type is GLM_S.
g_val_x, g_val_y, g_val_z
Define the value of the attribute if the type is GLM_G.

This function writes an attribute definition to the specified file descriptor with the given name, type and value.

GvfWritePoint

Writes a data point.

void GvfWritePoint( file, mode, x, y, format ) 
	FILE * file; 
	GvfSaveFormat mode;
	double x; 
	double y; 
	char * format;
Parameters
file
Specifies a file descriptor.
mode
Specifies GVF_ASCII or GVF_BINARY file writing mode.
x
Defines the x value of the point.
y
Defines the y value of the point.
format
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.

5.2 GVF Format RFC

File Extension

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.

Definitions

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 0x20

ASCII Format

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

Header

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.

Body

Objects

After the object header is written, the type of object may be one of:

GVF_POLYGON
GVF_MARKER

If the object type is GVF_POLYGON, a polygon definition must follow. If the object type is GVF_MARKER, a marker definition must follow.

Polygons

Polygons are defined to have 3 integral properties following the header. These properties are:

Ring

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.

Number of Points

Specifies the number of points in the polygon as a positive integral value. After the polygon definition, exactly this number of points must be defined. Defining a different number of points after the polygon is invalid.

Number of Attributes

Specifies the number of attributes associated with the given polygon. After the polygon definition, exactly this number of attributes must be defined. Defining a different number of attributes after the polygon is invalid.

Markers

Markers are defined to have up to 6 properties following the header. These properties are:

Marker Type

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

Defines the size of the marker's text as a floating point value.

Angle

Defines the angle of the marker's text as a floating point value. Must be in degrees, counter-clockwise from the right horizontal axis.

Anchoring

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_HLEFT

and the vertical anchoring must be one of:

GLM_VCENTER 
GLM_VTOP 
GLM_VBOTTOM
Text String

Defines the text-string of the marker's text

Number of Attributes

Specifies 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

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_G

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

Data Points

Data Points are written as two consecutive floating point numbers, usually the X and Y values of a point.


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