From GridInfo

Contents 1 WKML 1.1 Use of WKML 1.2 Conventions used below 1.3 Functions for manipulating the KML file 1.3.1 kmlBeginFile 1.3.2 kmlFinishFile 1.3.3 kmlAddNamespace (optional) 1.4 Kml Color handling functions: (liable to change, API is not final) 1.4.1 kmlloadcolor (optional) 1.4.2 kmllistcolor(optional) 1.4.3 kmlcustomcolorindex 1.5 Kml Open/Close functions 1.5.1 kmlOpenDocument 1.5.2 kmlOpenFolder 1.5.3 kmlCloseFoder 1.5.4 kmlCloseDocument 1.6 Kml Adding functions (private functions) 1.7 Kml Create functions 1.7.1 kmlCreatePointStyle 1.7.2 kmlCreatePoints 1.7.3 kmlCreateLineStyle 1.7.4 kmlCreateLine 1.7.5 kmlCreateContours 1.7.6 kmlCreateCells 1.7.7 kmlCreateCells2 1.7.8 kmlCreateCells3

WKML

WKML is a library for outputting KML (Keyhole Markup Language) data. It wraps all the necessary XML calls, such that you should never need to touch any WXML calls when outputting KML.

The KML output is conformant to version 2.1 of the KML schema. For more detail about KML 2.1 http://earth.google.com/kml/kml_tags_21.html

WKML subroutines can be accessed from within a module or subroutine by inserting. WKML is designed in three layers. The lowest layer is simply providing subroutines to make writing kml elements easier. kmladdsomething, kmlOpensomething, and kmlClosesomething are first level WKML functions, which are private functions. Several second level subroutines named kmlCreatesomething have been built to generate points, lines, and cells. The third layer, not described in this document this moment, is optional layer providing some functions for loading netCDF file and converting to KML.

Use of WKML

use FoX_wkml

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

Functions are named in the following way:

All functions begin kml

To Open and Close a section of the KML file, a pair of functions will exist:

kmlOpensomething kmlClosesomething

To output a given quantity/property/concept etc. a function will exist kmlAddsomething, or kmlCreatesomething.

Conventions used below

argument names are in bold
optional argument names are in (parenthesized bold)
string: string of arbitrary (unless otherwise specified) length
integer: default integer
real(sp): single precision real number
real(dp): double precision real number
logical: default logical
real: either of real(sp) or real(dp)
array: argument needed to be passed in as one dimension array
matrix: argument needed to be passed in as two dimension array

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 step sides a significant cause of errors when using subroutines with large numbers of arguments.

Functions for manipulating the KML file

kmlBeginFile

filename: string scalar: Filename to be opened.
unit: integer scalar: what unit number should the file be opened on? If you don't care, you may specify '-1' as the unit number, in which case WKML will make a guess.
(replace): logical scalar: should the file be replaced if it already exists? default: yes

kmlFinishFile

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.

kmlAddNamespace (optional)

prefix: string scalar, prefix to be used
nsURI: string scalar, namespace URI to be used. This adds a namespace to a KML file.
NB: This functions has been included in kmlBeginFile already and using http://earth.google.com/kml/2.1 as name space. Mostly this subroutine is not required.

Kml Color handling functions: (liable to change, API is not final)

There are functions for manipulating the colours of elements, but the API is unstable and under development, so it is not documented here. The following functions are temporarily in use and work fine at this moment.

kmlloadcolor (optional)

This function is used when one like to use colors defined in bgr.txt file. There is a bgr.txt file comes with wkml and defined in the following format. The default one has 637 colors.

Colorindex Blue Green Red ColorHex Colorname
1 250 250 250 EEFAFAFF snow
2 255 248 248 EEFFF8F8 ghost white

Colors will be loaded in public variable ci, which is a variable of derived type colorindex. This function will be improved next version, so one do not have to deal with read bgr.txt color table in.

kmllistcolor(optional)

kmllistcolor can be called to list all colors that have been loaded.

kmlcustomcolorindex

One can customize the colorindex by simply using kmlcustomcolorindex and all colors index will be recorded in module variable cindex, which is a one dimension array.

index: integer. Color index is going to be used in the main program
color: character. Colorhex, it has to be 8 character ordered by transparency, blue, green and red, for example, an red color with no transparency will be FF0000FF.
numcolors: integer. Number of colors are going to be defined in color index

Example for using kml color handling functions.

     ! load color tables bgr.txt, if want to use provided colors
     call kmlloadcolor
     ! custom color index and assign which colors are going to be used, in this case, ten colors are used.
     call kmlcustomcolorindex(1,ci(5)%colorhex,10)
     call kmlcustomcolorindex(2,ci(8)%colorhex,10)
     call kmlcustomcolorindex(3,ci(14)%colorhex,10)
     call kmlcustomcolorindex(4,ci(30)%colorhex,10)
     call kmlcustomcolorindex(5,ci(40)%colorhex,10)
     call kmlcustomcolorindex(6,ci(45)%colorhex,10)
     call kmlcustomcolorindex(7,ci(60)%colorhex,10)
     call kmlcustomcolorindex(8,ci(80)%colorhex,10)
     call kmlcustomcolorindex(9,ci(88)%colorhex,10)
     call kmlcustomcolorindex(10,ci(99)%colorhex,10)

The colors selected from bgr.txt will be recorded in public variable cindex as a one dimension array. One can use cindex for customizing kml styles later. The ci(*) shown above is just simply a 8 character color hex. For instance, ci(5) is EEF5F5F5.

Kml Open/Close functions

If the name of a KML element starts with a lowercase letter, it means there are no inner elements. On the other hand, if an element starts with an uppercase letter, it means there are more inner elements. For example, <LinearRing> consists <extrude>,<altitudeMode>,<coordinates> and <tessellate>. kmlOpen/Close functions are designed for those elements which have more inner elements. Those functions are not generating real data. They simply open and close elements. All kmlOpen/Close sections with only one argument “xf” and “id” as optional, the exceptions are kmlOpenDocumnet and kmlOpenFolder. Those are providing one more argument, which is the “name” for defining the name of the kml document and kml folder elements.

kmlOpenDocument

name: character. The name of kml Document will be shown in GE
(id): character.

kmlOpenFolder

(name): character. The name of kml Folder will be shown in GE. The name of Folder is optional.
(id): character.

kmlCloseFoder

Simply call kmlCloseFolder to close the Folder.

kmlCloseDocument

Simply call kmlCloseDocument to close the Document.

Example for using kmlOpensomething functions.

Call kmlOpenDocument(xf, Documentname)
Call kmlOpenFolder(xf,foldername1)
	Call kmlOpenPlacemark(xf)
		xxxxxxxxxxx
		xxxxxxxxxxx
	Call kmlClosePlacemark(xf)
	Call kmlCloseFolder(xf)
	Call kmlCloseFolder(xf)
    	Call kmlOpenFolder(xf,fodername2)
	Call kmlOpenPlacemark(xf)
		xxxxxxxxxxxx
		xxxxxxxxxxxx
	Call kmlClosePlacemark(xf)
	Call kmlCloseFolder(xf)
 Call kmlOpenDocument(xf)

Kml Adding functions (private functions)

kmlAddsomething functions are designed for those elements without inner elements. Any KML element starts with lowercase can be added using those functions. Those are the lowest level of WKML library. The kmlAddsomething functions can be called with argument which provides the value might required. By default, all those argument are characters. At this moment, those functions are only for internal usage.

Kml Create functions

kmlCreatesomething functions are second level subroutines. Currently, kmlCreatesomething functions provide subroutines for creating points, cells, lines, and contour lines.

kmlCreatePointStyle

KML required a style section to defined the style information such as color, size, icon style..etc. then the placemarks can then refers to defined style. kmlCreatePointStyle can define the point style includes the size, color, iconstyle ..etc.

(normalurl): character. An HTTP address or a local file specification used to load an icon representing normal. Default is http://cete.niees.group.cam.ac.uk/googlemaptest/icons
(normalscale): real(sp). Scale representing the size of point in normal situation. Default is 0.2.
(highlighturl): character. An HTTP address or a local file specification used to load an icon representing highlight. Default is http://cete.niees.group.cam.ac.uk/googlemaptest/icons
(highlightscale): real(sp). Scale representing the size of point in highlight situation. Default is 0.5.
(normalcolor): character. Style id for color name at normal stage.
(highlightcolor): character. Style id for color name at highlight stage.
(color): character. The color is going to use for representing a point. At this moment, the values are: blue, green, purple, yellow, orange, red. Default is red.

kmlCreatePoints

This function is passing zed value in single value, array, or matrix. Longitude and latitude could be either single value or an array. Placemarks will be created. Id the Zed value representing height, zed or zed2d arguments can be used.

longitude: real, (array). Longitude of the points
latitude: real, (array). Latitude of the points
(nx):integer. Number of longitude. it is required when using assumed size array.
(ny):integer. Number of latitude. . it is required when using assumed size array.
(zed): real, (array). If the zed value is representing height.
(zed2d):real,(matrix), zed value representing height.
(name): character. Name of the placemark. Default is empty
(color): character. Color used for this point, the color has to be the one defined in PointStyle. At this moment, the color value has orange, blue, green, yellow, red, and purple.
(scale): character. The scale or the size of the point. Default is 0.2.
(description_ch): character. description of the point, which could be the zed value or other information.
(description_dp): real(dp). Description of the point, which could be the zed value or other information
(description_sp): real(sp). Description of the point, which could be the zed value or other information
(description2d_ch): character, (matrix). Description of the point, which could be the zed value or other information. If passing zed2d in, it has to use description2d_ch.
(description2d_dp): real(dp), (matrix). Description of the point, which could be the zed value or other information. If passing zed2d in, it has to use description2d_dp.
(description2d_sp): real(sp), (matrix). Description of the point, which could be the zed value or other information. If passing zed2d in, has to used description2d_sp.

If using description2d_ch, and likes to use the zed value in description. An character array of description has to be passed in. it can be created in main program using WXML function str

Do i=1, number of longitude
  Do j=1, number of latitude
  Description2d_ch(i,j)=str(zed value(i,j))
  End do
End do

Example for using kmlCreatePoints

call kmlBeginFile(myfile, kmlfilename, -1)
call kmlOpenDocument(myfile,”point-test”) 
    call kmlCreatePointStyle(myfile,color="orange")
    call kmlOpenFolder(myfile,name="reloc")
    call kmlCreatePoints(myfile,longitude,latitude,color="orange",scale=maganitude(i)*0.4)
    call kmlCloseFolder(myfile)
call kmlCloseDocument(myfile)
call kmlFinishFile(myfile)

kmlCreateLineStyle

This subroutine generates styles for Lines

id: character, the name of this style.
(color): hex. Which color is going to use, this has to be hex number AABBGGRR, it can use cindex instead. Default is red EE0000FF
(width): character. The width of line is going to use. Default is 1.5

kmlCreateLine

This function creates single line with passing an array of coordinates.

x: real, array. longitudes
y: real, array. latitude
(z): real, array. zed value
(styleurl): character. Reference to the style id defined by kmlCreateLineStyle
(tessellate): character. Default is 1
(altmode): character. Default is relativeToGround.
(name): character. name of the palcemark
(linewidth):character. Width of the line, default is 1.5
(description_ch): character. Description of the line

Example for using kmlCreateLine

call kmlBeginFile(myfile, filename, -1)
      call kmlOpenDocument(myfile,"kmlCreateLine-path")
      call kmlCreateLineStyle(myfile,"cc",color="EE00FFFF",width="1.1")
      		call kmlCreateLine(myfile,longitude,latitude,z=zed,altmode="absolute",&
description_ch="path",styleurl="cc")
      	      call kmlCloseDocument(myfile)
call kmlFinishFile(myfile)

kmlCreateContours

This subroutine is going to plot contour lines from a regular distributed grid data.

x: real(sp). one dimension array of longitude.
y: real(sp). one dimension array of latitude.
z :real (sp). A matrix recorded the data which are going to be calculated
contour_values: real(sp). One dimension array containing the contour values which are going to be plotted.
(ncv): integer. Number of contour values. contour_values can not be used if using ncv. This is trying to automatically find which contour values are going to be plot.
(lines): logical. Contour represented as lines.
(regions): logical. Contour represented as surface contour with filling color.
(ignore_gt): real(sp). Cut value. Contouring is function will ignore those values.

Example for using kmlCreateContours

cv = (/ 0.009, 0.01, 0.013, 0.015, 0.018, 0.02, 0.023, 0.025, 0.027, 0.028 /)
     filename='sigconttest.kml'
      call loadcolor
      call customcolorindex(1,ci(5)%colorhex,10)
      call customcolorindex(2,ci(8)%colorhex,10)
      xxxxxxxxxx
      call kmlBeginFile(myfile, filename, -1)
      call kmlOpenDocument(myfile,"contours")
       call kmlCreateContours(myfile, filename, x, y, z, contour_values=cv)
      call kmlCloseDocument(myfile)
      call kmlFinishFile(myfile)

kmlCreateCells

This subroutine is used for creating cells (gridded). This function reads three matrix in and represent in red, green, and blue. The final result is 24 bit color images liked data.

east: real(dp). The coordinate of east boundary. It is usually the biggest longitude value.
west: real(dp). The coordinate of west boundary. It is usually the smallest longitude value.
south: real(dp). The coordinate of south boundary. It is usually the smallest latitude value.
north: real(dp). The coordinate of north boundary. It is usually the biggest latitude value.
m: number of cells on x axis.
n: number of cells on y axis.
Rblue: real(dp). The raw data is going to be passed in and represented as blue
Rgreen: real(dp). The raw data is going to be passed in and represented as green.
Rred: real(dp). The raw data is going to be passed in and represented as red
(numbit): integer. The color resolution for each band. Default is 8 bit and 256 colors.

kmlCreateCells2

This subroutine is used to create cells of a square region for a single matrix with flexible color assigned. Color index (cindex) has to be defined before.

east: real(dp). The coordinate of east boundary. It is usually the biggest longitude value.
west: real(dp). The coordinate of west boundary. It is usually the smallest longitude value.
south: real(dp). The coordinate of south boundary. It is usually the smallest latitude value.
north: real(dp). The coordinate of north boundary. It is usually the biggest latitude value.
m: number of cells on x axis.
n: number of cells on y axis.
value: real(dp). The data is going to be represented in different colors. The colors are defined before using kml color functions. Color index is a one dimension array named cindex.
numcolors: integer. Numer of colors. It is usually the size of cindex.

kmlCreateCells3

This subroutine reads longitude, latitude , representing data, stylecolor all in one dimension array. This function is usually used for handling netcdf type data

longitude: real(sp). one dimension array of longitude
latitude: real(sp). one dimension array of latitude
values: real(sp). two dimension array of the data is going to be represented.
valuescale: integer. Resolution of the dataset is going to be represented, same as numcolors used before.
(mask): real(sp). The ignore value of the dataset

Example for using kmlCreateCells3 
      call kmlloadcolor
      call kmlcustomcolorindex(1,ci(5)%colorhex,10)
      call kmlcustomcolorindex(2,ci(8)%colorhex,10)
      xxxxxxxxxxxxx
      xxxxxxxxxxxxx
      tos=tos*0.05
      filename='tostest.kml'
      call kmlBeginFile(xf, filename, -1)
      call kmlOpenDocument(xf,"test kmlCreateCells3")     
      do i=1,10 
      call kmlAddPolygonStyle(xf,cindex(i),id=cindex(i))
      end do 
      call kmlCreateCells3(xf,longitude,latitude,tos,10,mask=5.E+18)
      call kmlCloseDocument(xf)
      call kmlFinishFile(xf)