Using the GeoJSON file uploader

The Footprint GeoJSON Uploader tool allows the definition of geographical areas via the GeoJSON file format. Computational Grids, Quality Flagging Regions, and Regions of Interest can all be defined by a file matching the GeoJSON specification (plus a few additional attributes required by Tovi).

Making a GeoJSON file

A GeoJSON file must contain valid JSON, and must have the .geojson file extension. A GeoJSON file produced by ArcGIS (or another online alternative) should suffice, as will a plain text document (provided its contents are valid JSON and it is given the .geojson file extension). A template GeoJSON file can be downloaded from within the Tovi software, allowing you to fill in the missing information for your site (i.e., provide coordinate pairs) for an otherwise valid GeoJSON file.

A GeoJSON file encodes a geographical area as a feature object, which are stored in a feature collection array. At the top-level, a Tovi-valid GeoJSON file should contain a type attribute with a value of FeatureCollection, and a features array of individual objects.

Features

A GeoJSON feature is an object that outlines a geographical area. To be Tovi-valid, a GeoJSON feature should contain:

  • A type property with a value of Feature.
  • A properties object containing Tovi-specific properties (see Properties).
  • A geometry object containing geometric data (see Geometries and Coordinates).

Properties

In order to import geographical areas into Tovi, the software must know what each GeoJSON feature represents. Thus, each GeoJSON feature must have a properties object with a role attribute that has one of following values (note that each word is capitalized): Computational Grid, Quality Flagging Region or Region Of Interest. Additionally, any Regions of Interest generated in this fashion must also have a class attribute in the properties object, with one of the following values (again, note that each word is capitalized): Class One or Class Two.

Geometries

A GeoJSON feature contains a geometry object, which provides data about the geographical area. A feature’s geometry object must have a type attribute with a value of Polygon to be valid in Tovi.

Coordinates

Within the geometry object of a GeoJSON feature is a coordinates array, which contains Longitude/Latitude pairs.

GeoJSON places the Longitude coordinate first!

Additionally, GeoJSON requires that the first Longitude/Latitude coordinate pair be repeated at the end of the array if the geometry is intended to be a closed shape (instead of simply a line).

ALL Tovi geographical areas must be closed shapes so be sure that the ending coordinates are the same as the beginning coordinates.

Finally, the actual structure of a geometry’s coordinates is a bit strange. Coordinates are actually a nested array of Longitude/Latitude pairs (each of which is itself an array).

To illustrate, coordinate pairs are defined as such:

Copy 
"properties": { "role": "Computational Grid" }, "geometry": { "type": "Polygon", "coordinates": [ [ [ "Longitude_1 (Longitude Goes First in GeoJSON Files!)", "Latitude_1" ], [ "Longitude_2", "Latitude_2" ], ... [ "Longitude_1 (Repeated To Close The Shape)", "Latitude_1 (Repeated To Close The Shape)" ] ] ] } }

This double-nested structure is so GeoJSON shapes can define inner and outer coordinate pairs, allowing for complex shapes with empty space inside (i.e., rings or grids). However, Tovi does not support such complex shapes at this time.

Tovi-specific constraints

It is entirely possible to produce a valid GeoJSON file that is not acceptable for use within Tovi.

First, GeoJSON files must contain a properties object that defines a geographical area’s purpose within Tovi (see Properties).

Next, a geographical area must be a closed shape (see Coordinates), must have at least 3 sides (no lines or single points) and must have an area of at least 50 square meters.

Also, Longitude/Latitude pairs must be a reasonable distance from the Site tower (reasonable means the point is still visible when a user zooms all the way out from a site tower on any given Tovi map), and must contain numeric values.

Finally, a Computational Grid must be a rectangle, and no more than one Computational Grid or Quality Flagging Region is allowed within the same file (you may, of course, include as many Regions of Interest as desired).