Preparing Geospatial Data for Lens

This article will cover Lens’s data requirements, as well as how to resolve error messages you may encounter when uploading data to Lens. 

Overview

This article will cover the basics of preparing your geospatial data for Lens. Most of the information below is relevant for uploading new data to Lens via a file, which would be prepared in a GIS software of your choice. 

To add properties into Lens without any GIS work, you can use the Draw Properties feature to add areas of interest without GIS expertise. Drawing properties might also be useful for scouting out new acquisitions or areas where you don’t yet have geospatial data. 

QGIS is a free and open-source GIS software that we often use here at Upstream. With QGIS or any other GIS software of your choice, you can ensure that your geospatial data is ready for Lens. 

Data Requirements in Lens

File Format Requirements 

For new property additions via file upload, we currently support the following file formats: shapefile (.zip file containing .shp, .shx, .dbf, and .prj files), .kmz, .kml, and .geojson. 

  • Shapefiles are the most common geospatial file format, and they consist of multiple files zipped (or compressed) together. All files are required to convey the projection and geometry information required. When exporting a shapefile from GIS, make sure that all exported files (.shp, .shx, .dbf, and .prj) are zipped together.
  • .kml files are exported from Google Earth, and .kmz files are one or more compressed .kml files. 
  • .geojson is the fourth file format that can be uploaded to Lens. Since it is exported from GIS as a single file–unlike a shapefile–it can be easier to manage.

If uploading a large batch of new properties, we recommend that you add one file including all properties if possible. This will be a single file with multiple features within it, each property being a separate feature that appears as a line item in the attribute table. 

Above: Zipping together the multiple components of a shapefile 

Projection Requirements

All files uploaded to Lens must have a valid projection. EPSG:4326 is most accurate for shapefiles. WGS 84 or any UTM projection will work, too. In a zipped shapefile, the .prj file is what includes the projection information.

In QGIS, you can check the projection by navigating to the ‘Information’ section of the layer properties and looking under the ‘Coordinate Reference System (CRS)’ section. And you can use the “Reproject layer” tool to change the layer’s projection. In ArcGIS, you can check the projection of a layer by navigating to the ‘Source’ tab of the layer properties and looking under the ‘Spatial Reference’ section. You can also use the “Project (Data Management)” tool to change the vector layer’s projection.

Data Type

Files uploaded to Lens must include polygon vector data. Points and lines data will not be accepted for new properties. Points and lines data can be converted to polygonal data in GIS, by using a “lines to polygons” tool. Search “lines to polygons” in the GIS software of your choice to find the relevant tool.

You can check whether your data is polygon vector data by navigating to the layer properties. In QGIS, you’ll look for geometry information under the ‘Information’ tab. In ArcGIS, the geometry type is found under the ‘Source’ tab.

Attributes

The attribute table is where non-geographic information is stored about your features. This includes property names, ownership or project information, internal and external naming preferences, etc. When uploading new properties to Lens (or updating existing properties), you will need to specify the property name field that you’d like to use. The other additional attributes will be visible in Lens by navigating to the Details pane > Additional Attributes. Lens IDs are generally no longer required in Lens, but if you plan on using an integration with Landscape or LOCATE, we will need Lens IDs to be included in your attribute table. See this article for more details on setting up those integrations. 

Above: The attribute table of a shapefile, accessible by right-clicking the layer in the Layers Pane

Size Considerations

The maximum size of a single property in Lens is 500,000 acres. But there are other considerations for multi-feature properties (example: a property consisting of multiple parcels spread out across a large area). These properties are generally best in Lens as a multi-location property, as many satellite images are captured in strips and are unlikely to cover all areas of a spread-out property. By breaking up wide-spanning properties into multi-location properties or separate properties altogether, you will have more imagery availability and faster loading. In GIS, this would require selecting individual polygons of a multi-polygon feature, and splitting these polygons out into separate features. 

Lens Uploader Error Messages & Troubleshooting 

Below are some error messages that you may see while uploading data to Lens. By following the instructions below and above, you should be able to resolve any errors that you encounter. Still stuck? Reach out to us at lens@upstream.tech!

“Duplicate Features”

This error message means that aspects of your polygon overlap with one another, which won’t work in Lens. To remove the duplicate features, simply search “remove duplicates” in the toolbox of your GIS software, and run the tool to create a new, duplicate-free layer. Then you can export that layer following the file format requirements above. When the tool runs, it may identify the number and locations of duplicate features so that you can fix those areas in your master shapefile. 

Above: Using the "Delete Duplicate Geometries" tool in QGIS to remove the duplicate features of a shapefile.

“Invalid Geometry”

This error means that something is off with your geospatial file. Here’s an exhaustive list of what could be wrong, but starting with a “Fix geometries” tool in GIS is an easy way to fix the problematic areas of your file. This tool will then create an output with the valid elements of your file.

Above: The "Fix Geometries" tool in GIS being used to fix a file with invalid geometry.

“Z Dimension”

There are three dimensions of data: X, Y, and Z. The Z, or third dimension usually representing height/elevation, is not accepted by Lens. We just need the two dimensional X and Y data. To remove that Z dimension, re-export the layer from GIS and de-select the “include Z-dimension data” checkmark. To re-export the layer, right-click it in the table of contents, select export, and then export it as the file type of your choice (while following the guidance above). 

Above: Make sure that the "Z-Dimension" is not included in the polygon

"Wrong filetype: 'must provide file as a zipped shapefile (.zip), .kml, .kmz or .geojson'"

Read the file requirements above, and make sure that your provided filetype matches those required by Lens. If you're uploading a shapefile, make sure all components of the shapefile (.shp, .shx, .dbf, and .prj files) are zipped together.

"File size is too large"

5MB is the largest file size that can be uploaded at once. Files larger than 5MB will encounter this message. You can break the file up and upload in smaller chunks.

"No polygonal geometry found (lines and points are not supported)"

If you upload a raster file with no polygonal features, you will encounter this error. Make sure that your data is polygonal, not points and lines. See the Data Type section above for more details on how to prepare polygonal data.

"Too many features provided"

Files uploaded to Lens cannot contain more than 1,000 features (which you can check by opening the attribute table of your file). For this file to be uploaded to Lens, email it to us at lens@upstream.tech or reduce the number of features included in the file.

"Feature area is too large"

The maximum size for a single property in Lens is 500,000 acres. This helps support the best monitoring experience, as commercial images will rarely cover this large of a property. You can divide your property up into multiple features, and upload them to Lens as a multi-location property so that imagery can be processed in smaller chunks.

"Feature area is too small"

If your property is smaller than 0.1 acres, it can't be uploaded into Lens. Even with the highest resolution imagery, properties smaller than 0.1 acres are extremely difficult to remotely monitor. If you would still like this property added to Lens, add a buffer around the property in GIS so that the feature size is over 0.1 acres.

"Feature area is too spread out"

If you upload a feature that spans more than 150,000 km (for example, a multi-polygon feature that includes many areas across a region), you'll see an error and be unable to add this as a property. Properties that are this spread out are unlikely to have good imagery coverage and the monitoring experience is not ideal. Feel free to break into smaller sections, or reach out to us at lens@upstream.tech if you'd like to discuss other ways to configure your Lens properties.

"Feature has too many coordinates"

If you upload a feature that has more than 3,000 coordinates, you will see this error and be unable to upload this geometry to Lens. This is because many of our data and imagery providers don't allow us to request their data for such complex geometries. We suggest running a simplification tool on your property in GIS before uploading to Lens. Reach out to us at lens@upstream.tech if you need help getting your property into Lens.