Working with VRI files
- Calum Murray
How to read the contents of a VRI file
By default, the files downloaded from FieldNet are in a .vri file, which is not human readable. These files are zipped, but running a simple command to unzip them will not work. The first byte of the file is not correct for a standard unzipping utility such as the unzip command on a unix system. The file header for a zip file is supposed to be PK\x03\x04, and the file header for the .vri file is RK\x03\x04. To fix this and allow your system to unzip the file, you have to change the first byte. To do this in your terminal (tested on macOS):
echo -ne P | dd conv=notrunc bs=1 count=1 of={your_file_name}.vriHow to create a new VRI file
There are three steps to creating a new VRI file:
Create a
plan.geojsonfile which describes the VRI planZip the plan.geojson file into a .vri file
Switch the file header to match the .vri format
These three steps are discussed in more detail below.
Creating a plan.geojson file
Every plan.geojson file must have exactly this naming convention. In addition it must adhere to the standards laid out in RFC 7946: The GeoJSON Format . Specifically, the type of GeoJSON document that plan.goejson is is a FeatureCollection. The tables below describe the parts of the GeoJSON format that are relevant to the plan.geojson file, as well as what additional fields are used in the pla.geojson file.
Table 1: plan.geojson high level structure
Field | Type | Required | Notes |
|---|---|---|---|
“type” | String | yes | Must be exactly “FeatureCollection” |
“features” | Array of | yes | See table 2 for details |
“crs” | Coordinate reference system object | yes | Must be exactly: {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:OGC:1.3:CRS84"
}
} |
“bbox” | Array of numbers | yes | These points are represent a “bounding box” around which contains all of the coordinates in the “features” array. The order is: [ |
“properties” | A “global” | yes | See table 3 for details |
Table 2: features JSON object structure
Field | Type | Required | Notes |
|---|---|---|---|
“type” | String | yes | Must be exactly “Feature” |
“geometry” | GeoJSON geometry object | yes | As far as I can tell, FieldNet only uses |
“properties” | A “local” | yes | See table 5 for details |
Table 3: Global properties JSON object structure
This properties object is being called the “global” properties object because it appears in the top level of the plan.geojson document. Note: this is different than the properties object described in table 5.
Field | Type | Required | Notes |
|---|---|---|---|
“plan_type” | Enum | yes | Must be one of “FullVRI”, “VRI_Percent_Based”, or “VRIIgnoreFlowRates”. Generally, we will want to be using the “FullVRI” option. |
“max_depth” | Number | yes | If “plan_type” is “FullVRI”, this number represents the maximum depth in millimeters used in this plan. Otherwise, this number represents the maximum depth as a percent of the maximum depth the machine can go to. For example, if “plan_type” were “VRIIgnoreFlowRates”, and “max_depth” was 55, that would represent a maximum depth that is 55% of the machine’s maximum. |
Table 4: Polygon GeoJSON object structure
Field | Type | Required | Notes |
|---|---|---|---|
“type” | String | yes | Must be exactly “Polygon”. While other geometries are supported by the GeoJSON spec, it seems like the FieldNet system only generates “Polygon” geometries. |
“coordinates” | Array of arrays of arrays of numbers | yes | Each array of numbers contains exactly two numbers: the first represents the longitude of the point, and the second represents the latitude of the point. These points must be sorted counterclockwise. Additionally, the last point must be identical to the first point. The doubly nested array is a GeoJSON feature, but FieldNet seems to only every have a single array of arrays of numbers within their coordinates array. |
Table 5: local properties JSON object structure
Field | Type | Required | Notes |
|---|---|---|---|
“name” | String | yes | This is the name of the polygon in the UI |
“type” | Enum | yes | One of “application”, “avoid”, or “ignore”. |
“colour” | Hex string | yes | A string containing the hex code of the colour of the feature. |
“application_depth” | Number | yes | The depth in millimeters of the irrigation. This is always provided, even when the plan is provided in percents. When the “type” is “avoid” or “ignore” this is always 0. |
“application_percent” | Number | yes | The depth in percent of the maximum depth that the machine can irrigate. This is always provided, however when the plan is a “FullVRI” plan, it has a value of 0. |
Example plan.geojson document
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"name": "Field 1",
"colour": "#00A4E6",
"type": "application",
"application_depth": 15.24,
"application_percent": 0
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-112.43697881698608,
50.170837555341194
],
[
-112.4371075630188,
50.16683798492274
],
[
-112.43678569793701,
50.16569715262685
],
[
-112.43236541748047,
50.165532210764646
],
[
-112.42837429046631,
50.166425639042664
],
[
-112.42796659469604,
50.16839112246747
],
[
-112.43039131164551,
50.169957953446776
],
[
-112.43697881698608,
50.170837555341194
]
]
]
}
}
],
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:OGC:1.3:CRS84"
}
},
"properties": {
"plan_type": "FullVRI",
"max_depth": 15.24
},
"bbox": [
-112.42796659469604,
50.165532210764646,
-112.4371075630188,
50.170837555341194
]
}Zipping the plan.geojson file
To zip the plan.geojson file, you need to use whatever zip utility you prefer, so long as it uses the deflate method to reduce the file size. Additionally, you will need to change the file extension from .zip to .vri
Setting the appropriate file header
To set the appropriate file header for FieldNet to be able to process it, you need to set the first byte to be 0x52. In order to do this on a Unix based terminal, run: