Map Your Records - Help

This interface creates a .kmz file (i.e. a Google Earth layer) when supplied with a file of records containing, as a minimum, a list of UK Ordnance Survey grid references. A second file specifies a set of styles to be used for drawing the data.

The Title:

  • This is the name by which the dataset will be labelled in Google Earth. It is also used for the name of the .kmz file that will be generated, e.g. "My Records 2009.kmz". Example .kmz File

The Records file: Example Records File

Style +Species Date Gridref Place Observer Comment
RedSquare Robin 01/04/2003 TL123456 Old Warden K.Balmer Nesting
RedSquareFilled Blackbird 02/03/2004 TL1040 Chicksands Wood NE K.Balmer Foraging
YellowMarker Blackbird 17/10/2009 TL0650 Bedford K.Balmer Scoffing apples in garden

Basic stuff:
  • The records file is a plain text file (i.e. ASCII , txt) not Word, or Excel, etc. Columns of data must be separated by tabs, not by commas, or anything else. Data must not be surrounded by quotes, e.g. the data should be Fred, not "Fred". This format can easily be created by the Save As... option from any decent spreadsheet, which may be the preferred way to maintain/prepare your data. e.g.
    • Excel users should select "Text (Tab delimited)(*.txt)". The file ending should be .txt for Excel.
    • OpenOffice users should select "Text CSV", tick "Edit filter setting", then select {Tab} for the Field delimiter, and nothing at all for the Text delimiter (i.e. delete any offered character). The file ending should be .csv for OpenOffice.
    You can view the file in WordPad or NotePad to check that all is well, but you will probably find it too tedious to prepare using these editors.
  • The first row of the file must contain column headings, one of which must be called Gridref. This is the only required column, all others are optional.
  • Each subsequent row is treated as a record to be mapped. (Don't include carriage-returns in your data or they will be misinterpreted as new records).
  • Each record must contain a grid reference in the Gridref column. (Only UK Ordnance Survey grid references are supported). Grid references may contain spaces, slashes or dashes for human readability, e.g TL123456, TL123 456, TL123/456 and TL123-456 are all acceptable.
  • Records are drawn starting with the 2nd line of the file and ending with the last. If you find a record is drawn beneath another record and you'd rather it was above, then move it further down the file. e.g. you may prefer to put 100m records later in the file than 1km records, so that they are drawn above. (This isn't enforced because you may prefer instead to plot newer records above older ones, or something similar - you have control).
  • Objects are named (labelled) using the contents of the left-most column that is not headed Style.
  • When you click on an object in Google Earth the contents of all the data fields for its record are displayed in a pop-up table, in the same order as the columns are presented in the data file. It is a current limitation that only the top overlapping polygon (square) can be clicked. If you need to click all records at a particular grid reference use the Markers (Icons) instead - Google Earth has an in-built solution for coincident markers.
Fancy stuff:
  • If you wish the records in the Google Earth layer to be grouped into folders then its column heading should begin with a +, e.g. +Species. (You may need to precede the plus with a "'" when using a spreadsheet to stop it thinking you are providing a formula). Only one column heading may begin with a "+". A new folder is started when there is a change in the data in this column as records are processed from top to bottom. Thus if the column contains the data: Robin, Robin, Blackbird, Robin, Robin then three folders are created called Robin, Blackbird, Robin with each Robin folder containing two records. (You thus have control over what gets grouped - sort your data with this in mind).
  • If you wish to control how a record is drawn then put a name for the drawing style in a column headed Style and define the style for that name in the style file (see below). The drawing style is specified for each individual record - you have full control of the appearance of each record. (You cannot group data using the Style column, so don't call this column +Style).
  • If no style is provided for a record (i.e. the Style column is empty, or there is no Style column) then the record is drawn using a style called Default (currently a yellow square). You can define your own style called Default to replace the default style.

The Styles file: Example Styles File

The Example Styles File provides a very useful set of styles to use, and you may not need to define your own. If you do, or are just curious how they are defined, they are explained below:

Style Shape Outline? LineWidth LineColour Fill? FillColour Icon IconScale LabelScale hotspotX hotspotY
RedSquare Square 1 2 ff0000ff 0 600000ff
RedSquareFilled Square 1 2 ff0000ff 1 600000ff
YellowMarker Icon http://maps.google.com/mapfiles
/kml/paddle/ylw-circle.png
1.0 0.5 0.5 0.0
  • The styles file is constructed in the same way as the records file, i.e. as tab-separated, non-quoted, plain text.
  • The first row of the file must contain the column headings exactly as shown above, and in the example file. (The order of the columns doesn't matter though).
  • Each subsequent row is a definition of a drawing style. The data within these columns are described below:
    Style
    A name for the drawing style. This should be unique within the styles file. The names used in the Style column of the records file must correspond with names in this column of the styles file.
    Shape
    Must be either Square or Icon. If Square, then the record is drawn as a polygon. If Icon, then the specified icon is used to mark the location of the record.
    Outline?
    Applicable to Shape=Square only. Must be 0 or 1. 1=the four lines making the outline of the square are drawn. 0=the outline is not drawn (Fill? is expected to be 1 in this case, otherwise nothing will be seen!)
    LineWidth
    Applicable to Shape=Square only. The width of the outline lines in pixels. Small integers (<5) work best.
    LineColour
    Applicable to Shape=Square only. The colour and translucency of the outline lines. Four concatenated 2-digit hexadecimal numbers representing opacity, blue, green and red in that order. e.g. 80ffc023 opacity=80, blue=ff, green=c0 and red=23. For Google's own description click HERE
    Fill?
    Applicable to Shape=Square only. Must be 0 or 1. 1=the area within the outline is filled with colour. 0=the square isn't filled. Note that Google Earth slows down if it has many filled squares to draw, so you may wish to use filled styles sparingly if this is a problem
    FillColour
    Applicable to Shape=Square only. The colour and translucency of the filling. As for LineColour, four concatenated 2-digit hexadecimal numbers representing opacity, blue, green and red in that order. e.g. 80ffc023 opacity=80, blue=ff, green=c0 and red=23. For Google's own description click HERE
    Icon
    Applicable to Shape=Icon only. Contains the address of an icon to be used to mark the location of the record. Must contain the http:// part of the web address, e.g. http://maps.google.com/mapfiles/kml/paddle/red-circle.png is one of Google's pre-defined icons. (To discover the range of icons pre-defined by Google, within Google Earth add a placemark then select its style from the range of icons offered. Its web address is provided at the top of the Icon dialog box). The icon is placed at the centre of the Gridref's square.
    IconScale
    Applicable to Shape=Icon only. An amount to scale the icon. The default is 1.0 if not specified. 1.5 will display it 50% larger than its normal size. A value of 0 will make the icon invisible (which probably isn't of much use!). If the icon is scaling around the "wrong" point of the icon you may not have the hotspot set to the right place. (See hotspotX and hotspotY below).
    LabelScale
    Applicable to Shape=Icon only. An amount to scale the size of the text (label) displayed alongside the icon. The default is 1.0 if not specified. 0.5 will display it at half its normal size. If you want to make labels invisible then set this to 0.
    hotspotX
    Applicable to Shape=Icon only. The place on the icon to be treated as the anchor point (i.e. where it is "placed") as a fraction of its width. (The minimum value is 0.0 which is the left edge, the maximum value is 1.0 which is the right edge). For the "paddle"-like symbols the anchor point should be specified as 0.5 to be mid-width. For "round" symbols this should also be set to 0.5 so that it is placed at the centre of the icon.
    hotspotY
    Applicable to Shape=Icon only. The place on the icon to be treated as the anchor point (i.e. where it is "placed") as a fraction of its height. (The minimum value is 0.0 which is the bottom edge, the maximum value is 1.0 which is the top edge). For the "paddle"-like symbols the anchor point should be specified as 0.0 to be at the base. For "round" symbols this should be set to 0.5 so that it is placed at the centre of the icon.

Having Trouble?:

If you don't get the results you expect it could be a bug in the code, but it is more likely to be something wrong with your data or style definitions.

Study the example record file and style file and see if your's differ in some critical way, and also study the help above. View your files in WordPad to see exactly what they look like.

If you still can't figure out what's wrong, then email your record and style files to me and I'll see if I can help.

Keith Balmer, BNHS webmaster (email)