Specification and current implementation

Specification

User input/configuration

The software must mandate that the user provides a path to a single file, be this by configuration file, command line argument or appropriate component(s) in a GUI.

The software must also allow the user to supply a destination for the output files. The output file destination directory doesn’t have to be empty.

The software must also be able to allow the user to choose to have the geometry precision reduced if required (details below).

Supported input file format

The software should be able to parse files in the GeoJSON format. A typical townland dataset that the software should be able to read can be quite large, up to sizes of a few hundred megabytes. Implementations of this software specification should remain performant when working with these large files.

The software should check that the user-provided path to the input file is valid (it exists) and that it can be read. The software should also check that the file contents are valid (valid JSON) before proceeding.

Output files

The software should produce output files in valid GeoJSON format that can be read by the script called “WME Geometries” available for the Waze Map Editor. There should be an output file produced in a user-provided target directory for each of the counties in the Republic of Ireland. The six counties of Northern Ireland may be included, but this is not strictly necessary as a typical input file does not contain townland boundaries for Northern Ireland.

Output files should follow this naming convention:
For “reduced” files (see below for details on reduction):
townlands_reduced_[county].geojson

For non-reduced files:
townlands_[county].geojson

Where [county] is the uncapitalised name of the county.

While not required, every effort should be made to make the files as small as possible. Please minify output where possible.

County GeoJSON file structure

Each county GeoJSON file should have the same structural elements. Each file should contain a single object which will contain an array of other objects which contain the townland geometries.

The root object will look similar to this:

{
  "type": "FeatureCollection",
  "features": [
    ...// Townland objects here.
  ]
}
Townland objects

Each townland is represented in the features array by its own JSON object. GeoJSON specifies that there are two root elements in the object, and these should be included in the output:

  • properties - an object containing metadata about the polygons that the object describes.
  • geometry - an object containing an array of coordinates.

The properties object should contain the following keys:

  • NAME - originally called TD_ENGLISH in the input files
  • TD_GAEILGE - can be left as is as English names are preferred, but this data is still left in the cases where some townlands only have Irish names. A modification to the WME Geometries script will be required to display this particular key.

All other values (as specified in this document) can be discarded in the output files.

Supporting the reduce argument

The user can request “reduced” output files. These files contain the same number of townlands, but with reduced precision in order to reduce file size and thus improve performance in the editor.

Each coordinate in the file should be rounded to four decimal places. This has been found to be the best number of places to round to while maintaining enough precision in order to reconstruct townland boundaries with acceptable accuracy in the editor.

Current implementation

Details for the relevant headings above can be found below regarding the current implementation of the software as found on GitHub at https://github.com/cw1998/townland-clipper/ 

  • The implementation (software) is written in JavaScript.
  • It is designed to run in a node based environment, but certain aspects of the software can be run anywhere where JavaScript runs due to the primitive nature of the specification.
  • The project’s package manager is the Node Package Manager (npm) but the project itself is not published on npm.
  • Currently there is no notion of a “released” version of the software. It is provided as is in the repository and can be used according to the instructions in the README markdown file, or the documentation provided on this website.

Input files

The software reads a GeoJSON file and parses it in its entirety to a normal JavaScript object. This allows for relatively good performance (as opposed to streaming the file) at the expense of memory efficiency.

The software consumed around 8GB of memory when the largest open dataset of townlands was input.

Output files

A minified output file is produced for each of the following counties:

  • Carlow
  • Cavan
  • Clare
  • Cork
  • Donegal
  • Dublin
  • Galway
  • Kerry
  • Kildare
  • Kilkenny
  • Laois
  • Leitrim
  • Limerick
  • Longford
  • Louth
  • Mayo
  • Meath
  • Monaghan
  • Offaly
  • Roscommon
  • Sligo
  • Tipperary
  • Waterford
  • Westmeath
  • Wexford
  • Wicklow