WKML

WKML is a library for creating KML documents. These documents are intended to be used for "expressing geographic annotation and visualization" for maps and Earth browsers such as Google Earth or Marble. WKML wraps all the necessary XML calls, such that you should never need to touch any WXML calls when outputting KML from a Fortran application.

WKML is intended to produce XML documents that conform to version 2.2 of the Open Geospatial Consortium's schema. However, the library offers no guarantee that documents produced will be valid as only a small subset of the constraints are enforced. The API is designed to minimize the possibilty of producing invalid KML in common use cases, and well-formdness is maintained by the underlying WXML library.

The available functions and their intended use are listed below. One useful reference to the use of KML is Google's KML documentation.

Use of WKML

wkml subroutines can be accessed from within a module or subroutine by inserting

 use FoX_wkml

at the start. This will import all of the subroutines described below, plus the derived type xmlf_t needed to manipulate a KML file.

No other entities will be imported; public/private Fortran namespaces are very carefully controlled within the library.

Conventions used below.

All functions take as their first argument an XML file object, whose keyword is always xf. This file object is initialized by a kmlBeginFile function.

It is highly recommended that subroutines be called with keywords specified rather than relying on the implicit ordering of arguments. This is robust against changes in the library calling convention; and also stepsides a significant cause of errors when using subroutines with large numbers of arguments.

Functions for manipulating the KML file:

This takes care of all calls to open a KML output file.

This takes care of all calls to close an open KML output file, once you have finished with it. It is compulsory to call this - if your program finished without calling this, then your KML file will be invalid.

This starts a new folder. Folders are used in KML to organize other objects into groups, the visability of these groups can be changed in one operation within Google Earth. Folders can be nested.

This closes the current folder.

This starts a new document element at this point in the output. Note that no checks are currently performed to ensure that this is permitted, for example only one document is permitted to be a child of the kml root element. Most users should not need to use this subroutine.

This closes the current document element. Do not close the outermose document element created with kmlBeginFile, this must be closed with kmlFinishFile. Most users should not need to use this subroutine.

Functions for producing geometrical objects:

A single function, kmlCreatePoints accepts various combinations of arguments, and will generate a series of individual points to be visualized in Google Earth. In fact, the KML produced will consist of a Folder, containing Placemarks, one for each point. The list of points may be provided in any of the three ways specified above.

A single function, kmlCreateLine accepts various combinations of arguments, and will generate a series of individual points to be visualized as a (closed or open) path in Google Earth. In fact, the KML produced will consist of a LineString, or LinearRing, containing a list of coordinates. The list of points may be provided in any of the three ways specified above.

Creates a filled region with the outer boundary described by the list of points. May be followed by one or more calls to kmlAddInnerBoundary and these must be followed by a call to kmlAddInnerBoundary.

Ends the specification of a region with or without inner boundaries.

Introduces an internal area that is to be excluded from the enclosing region.

2D fields

WKML also contains two subroutines to allow scalar fields to be plotted over a geographical region. Data is presented to WKML as a collection of values and coordinates and this data can be displayed as a set of coloured cells, or as isocontours.

Data input

For all 2-D field subroutines both position and value of the data must be specified. The data values must always be specified as a rank-2 array, values(:,:). The grid can be specified in three ways depending on grid type.

In all cases, single or double precision data may be used so long as all data is consistent in precision within one call.

Control over the third dimension

The third dimension of the data can be visualized in two (not mutually-exclusive) ways; firstly by assigning colours according to the value of the tird dimension, and secondly by using the altitude of the points as a (suitable scaled) proxy for the third dimension. The following optional arguments control this aspect of the visualization (both for cells and for contours)

Where no colormap is provided, one will be autogenerated with the appropriate number of levels as calculated from the provided contourvalues. Where no contourvalues are provided, they are calculated based on the size of the colormap provided. Where neither colormap nor contour_values are provided, a default of 5 levels with an autogenerated colormap will be used.

Subroutines

This subroutine generates a set of filled pixels over a region of the earth.

This subroutine creates a set of contour lines.

Colours

KML natively handles all colours as 32-bit values, expressed as 8-digit hexadecimal numbers in ABGR (alpha-blue-green-red) channel order. However, this is not very friendly. WKML provides a nicer interface to this, and all WKML functions which accept colour arguments will accept them in three ways:

A function and a subroutine are provided to maniputate the color_t derived type:

This function takes a single argument of type integer or string and returns a color_t derived type. If the argument is a string the colour is taken from the set of X11 colours, if it is an integer, i, the ith colour is selected from the X11 list.

This functon takes a single argument of type string(len=8) representing an 8-digit AVGR hexadecimal number and returns a color_t derived type representing that colour.

Several features of wkml make use of "colour maps", arrays of the color_t derived type, which are used to relate numerical values to colours when showing fields of data. These are created and used thus:

program colours
  use FoX_wkml
  type(color_t) :: colourmap(10)

  ! Use X11 colours from 101 to 110:
  colourmap(1:10) = kmlGetCustomColor(101:110)
  ! Except for number 5 which should be red:
  colourmap(5) = kmlGetCustomColor("indian red")
  ! And for number 6 which should be black
  call kmlSetCustomColor(colourmp(6), "00000000")

end program colours

Styles

Controling styling in KML can be quite complex. Most of the subroutines in WKML allow some control of the generated style but they do not ptovide access to the full KML vocabulary which allows more complex styling. In order to access the more complex styles in KML it is necessary to create KML style maps - objects that are defined, named with a styleURL. The styleURL is then used to reference to the style defined by the map.

Styles can be created using the following three subroutines. In each case one argument is necessary: id, which must be a string (starting with an alphabetic letter, and containing no spaces or punctuation marks) which is used later on to reference the style. All other arguments are optional.

Creates a style that can be used for points.

Creates a style that can be used for lines.

Creates a style that can be used for a polygon.