Import tree data from GIS (via shapefile/geojson)

This tutorial walks through the steps taken to create an orchard in Truffle Grower by migrating a shapefile of tree data generated by a GIS application.  This procedure will work for any GIS application that supports exporting data layers as a shapefile (or GeoJSON file).

During the procedure, shapefile data is first converted to GeoJSON format, and then imported into Truffle Grower.  The procedure is:

• 1. Export the tree data from a GIS layer to a shapefile
  2. Convert the shapefile to a GeoJSON format file
  3. Open the GeoJSON file using Truffle Grower

Geographical Information Systems (GIS)

Geographical Information Systems (GIS) are a category of software application widely used to create, store and manipulate map based data.  One application to which GIS software can be applied is the design of orchard layouts.

Truffle Grower provides a mechanism for importing data from a GIS.   Tree location and configuration data can be exported from the GIS database and then imported into an existing or new orchard block in the Truffle Grower application.

While there are many types of GIS application available, most software packages allow their data to be exported in a format known as a ‘shapefile’.  Generating a shapefile is the first step in migrating data to Truffle Grower.

Note:  if a GIS supports exporting tree data in GeoJSON format, the steps discussing shapefiles can be skipped.  The GeoJSON file can be imported directly into Truffle Grower.

Shapefiles

Shapefiles are an industry standard data format for GIS software used to describe spatial data.  A shapefile stores location, shape and attributes of geographic features.   Geographic features are represented by points, lines or polygons.  Attributes can be associated with the features, providing additional data, such as name or species.

The term shapefile is misleading, since the shapefile data is made up of a number of files sharing a base filename and stored in a common directory.  When storing or sharing a data set, the component files making up the shapefile are often combined into a single ZIP archive.

Creating the shapefile

GIS applications supporting shapefile data will each have their own method for exporting a data layer into the shapefile.  Please refer to your GIS software’s documentation for help with creating the shapefile.

⚠  Important: make sure that the shapefile bundle includes a file with extension “.prj”.  This PRJ file describes the coordinate system and projection used by the shapefile.  It will be needed to convert the tree coordinates to latitude and longitude.

tree data in a shapefile

When importing shapefile data for an orchard into Truffle Grower, the following assumptions are made about the data:

• • trees are stored in the shapefile as points with a location coordinate
  • points may have attributes that can be used when importing the tree.  These attributes could hold string values for properties Truffle Grower can use when creating tree definitions:
    • a unique tree name
    • the row for the tree
    • the date planted in “yyyy-mm-dd” format

Note:  if the shapefile does not include attributes for all of these properties, the following rules will be applied:

• • if no unique name can be specified, then Truffle Grower will auto-generate names for the trees
  • if no row is specified, then a new tree will be assigned to the first row in the orchard block and an existing tree’s row will not be modified
  • if no attribute specifies  date planted, then the current date will be used for this field when creating the trees

After importing the GIS file, additional changes can be merged with the trees by using Truffle Grower’s import/export to csv file function.

GeoJSON

Truffle Grower cannot directly read shapefile data files.  To import shapefile  data into Truffle Grower, the data must first be converted into a GeoJSON formatted file.  GeoJSON is another standard file format for handling geographic data, but it is a simpler format to work with than shapefiles:

• • GeoJSON data is all contained within a single file
  • the data is simple text, so it is human readable and can be viewed/edited with any text editor
  • location data within the GeoJSON file can be stored as a latitude & longitude

Convert shapefile to GeoJSOn

There are a number of freely available online tools that will assist in converting a shapefile to GeoJSON format.  The website which we have used in this example is:

https://ogre.adc4gis.com/

⚠  Important:  for use in Truffle Grower, coordinates in the GeoJSON file must be represented as degrees latitude and longitude.   To ensure this, you may need to specify a Spatial Reference System (SRS) to use when converting the shapefile to GeoJSON.  Use the standard target SRS of “EPSG:4326” or “WGS84” to ensure the output data coordinate units are degrees latitude and longitude.  Because our shapefile included a “.prj” file, we did not need to specify a source SRS:

Preview the geoJSOn file

Before importing the file into Truffle Grower, preview the file to identify properties that may match with Truffle Grower fields, and check that latitude and longitude values look reasonable.  If the coordinates look strange, you may need to recreate the GeoJSON data using a different SRS.

This example GeoJSON data shows a typical tree definition after conversion from a shapefile (your data will have a different ‘properties’ collection):

{ "type": "Feature", "properties": { "Id": 4, "Block": 1, "Row": 1, "treeID": "A-1-4" }, "geometry": { "type": "Point", "coordinates": [ -33.89499026661673, 151.23519878268965 ] } }

As well as the coordinates, in this file we have properties labeled Id, Block, Row and treeID for each tree.  When we open the file in Truffle Grower, we will use these properties to generate tree names and assign trees to rows.

Given the available properties above, we will use:

tree name = “treeID“    (for this data, the tree’s name is “A-1-4”)

tree row = “Row”   (for this data, the tree’s row is “1”)

In our example, there are no attributes for other tree data.  To populate the planting date or other tree properties, we will need to create a csv file with the missing data and merge it once the trees have been created.

In addition,  while the GeoJSON in this example includes a property “Block“,  the import operation will place all the trees in a single Truffle Grower ‘block’.  In this example, trees in different blocks with the same row number will be imported into the same Truffle Grower row.  As with the missing property values, we will resolve this after the import by creating and merging a csv file with the corrected row names.

Open GeoJSON file in Truffle Grower

The simplest way to open a GeoJSON file in Truffle Grower is by email.  Send the file to a mail account that can be opened on your iOS device, then view the email on your device and download the attachment.

Press on the attachment icon, until the “open with…” list of applications is shown, then select the Truffle Grower icon.

⚠  Important:  in order to recognise the file as GeoJSON, make sure that the filename has the extension “.json”.

Match property fields

Before importing the data, Truffle Grower will prompt for help identifying the properties in the GeoJSON file that match fields used by Truffle Grower.

A list of fields that can be mapped to attributes is shown and users can select corresponding properties from the GeoJSON file for each field.

In the example, we have matched the “Tree name” and “Row” fields with their matching property names “treeID” and “Row”.  Since our GeoJSON file does not include a property for the planting date, this field is left blank.

Note: it is not possible to combine more than one attribute from the GeoJSON file to build the Truffle Grower field.  In our example, while we might like the Row field in Truffle Grower to have a format like “Block–Row“, during the import we can only select the Row attribute in the imported file.  We will lose the block information for each tree.  We can correct this later by using the import/export to CSV file function to make bulk edits to our data.

Select a target orchard

Before we can import the data, we need to identify which orchard block in Truffle Grower to target.  We can either create a new block with the data, or merge the GeoJSON data with an existing orchard.

We have selected “<create new>“, so that a new orchard block will be created from the imported tree data.

Import the file

Press ‘Import’ to import the data into Truffle Grower.  The application will work through the file, creating new trees for each point.  The attributes will be used to generate values for the tree properties name, row and date planted.

Once complete, an entry for the new orchard will be shown in the summary view with a name matching the imported filename.  This name can be edited by pressing the ‘edit’ command and selecting the new orchard block.

Select the orchard name to view the new orchard.

More Complicated tree or row names and missing data

After importing the tree data into a Truffle Grower orchard, we can see that trees have been created at each point specified by the original shapefile.  Depending on the attributes that were available in the shapefile, we may need to make further changes to the new orchard before the task is complete.

Continuing with our example, after importing the GeoJSON file we want to make these further changes:

• • Row names should include the original block code.  For example, a tree ‘A-12-1’ should be placed in row ‘A-12’, and a tree ‘C-12-2’ in row ‘C-12′.  Because we ignored block number during the import operation, these trees are currently both in the same row named ’12’
  • Trees have been created with default values for:
    • Date planted (default value is the current date)
    • Tree species (default value is Quercus robur)
    • Truffle species (default value is Tuber melanosporum)

These additional changes can be made by performing a bulk-edit on the trees using Truffle Grower’s ability to import/export data to csv.

The tutorial “Bulk-edit tree data via import/export to csv” will show how to do this by continuing the example.