Field operations are what you get when Leaf takes converted machine files and spatially allocates them to field boundaries. A field operation represents a real-world task — planting, harvesting, spraying, or tillage — performed on a specific field.
This page explains how files become operations and what data is available on each operation.
How files become operations
Field operations are created only when fieldOperationCreation is enabled.
A single field activity often spans many machine files. A corn harvest on one field might be represented by dozens or even hundreds of files from the provider. Leaf’s auto-merge process handles this automatically:
- Leaf groups machine files by operation type (
planted, harvested, applied, tillage) and time proximity.
- The grouped files are spatially intersected with field boundaries.
- Files that overlap the same field and represent the same activity are merged into a single field operation.
This works for both provider-connected files and manually uploaded files.
Field boundaries are required. Without boundaries, Leaf converts machine files and produces file-level summaries but cannot create field operations. See Uploading Boundaries or Managing Fields for creating and managing boundaries. Merge timing
The merge process runs continuously. Operations are created or updated each time new files arrive or field boundary changes are made. Merging is computationally expensive and can take time for large datasets.
Operation structure
A field operation (GET /operations/{id}) contains:
| Field | Description |
|---|
id | Unique operation ID |
leafUserId | Owner Leaf user |
apiOwnerUsername | API owner |
type | planted, harvested, applied, or tillage |
startTime / endTime | Time range of the operation |
updatedTime | Last time the operation was modified |
files | List of machine file IDs that were merged into this operation |
fields | List of field objects with id and coverage (percentage of the field boundary covered by the operation) |
providers | List of source providers |
Operation data outputs
For each processed operation, Leaf produces:
Standard GeoJSON (/operations/{id}/standardGeojson) — The merged point-level data in Leaf’s standard schema. This is the full dataset.
Filtered GeoJSON (/operations/{id}/filteredGeojson) — Filtered output is controlled by operationsFilteredGeojson, but the endpoint behavior is not just a simple enabled-or-404 switch. When a dedicated filtered output exists, this endpoint returns it. If not, Leaf can still return the cleaned standard GeoJSON instead. Low-speed points (< 0.5 m/s) are removed, and for harvest operations statistical outliers can also be removed.
Images V2 (/operations/{id}/imagesV2) — Generated from the filtered GeoJSON when data filtering is enabled. Uses a fixed color ramp with 7 quantile-based classes. Returns extent and legend metadata alongside each image. If the filtered GeoJSON fails, images fall back to the standard GeoJSON.
GeoTIFF Images (/operations/{id}/geotiffImages) — Georeferenced TIFF versions of the property maps. Requires both operationsFilteredGeojson and operationsImageAsGeoTiff to be enabled.
Summary (/operations/{id}/summary) — Aggregate statistics and a geometry.
Units (/operations/{id}/units) — Map of property names to their unit strings.
Operation summary
The summary is a GeoJSON Feature containing aggregate properties and a MultiPolygon geometry representing the operation’s spatial coverage.
Properties available by operation type
All operation types include: operationType, startTime, endTime, totalArea, totalDistance, elevation, machinery, originalOperationType, originalOperationData.
Harvest adds: crop, harvestMoisture, wetMass, totalWetMass, wetMassPerArea, wetVolume, totalWetVolume, wetVolumePerArea, dryMass, totalDryMass, dryMassPerArea, dryVolume, totalDryVolume, dryVolumePerArea, varieties.
wetVolume, wetVolumePerArea, dryVolume, and dryVolumePerArea are not available when the crop is sugarcane.
crop, seedRate, totalPlanted, varieties, singulation, downForce, skips, doubles.
Application adds: appliedRate, totalApplied, products, tankMix, crop.
Tillage adds: tillType, tillageDepthActual, tillageDepthTarget.
Stat properties
Most numeric properties in the summary include avg, min, max, and unit. Total properties include value and unit.
Machinery
The machinery array contains objects with name, type (machine or implement), serialNumber (when available), and brand.
Varieties and products
Harvest and planting summaries include a varieties array with per-variety breakdowns of area, totals, and rates. Application summaries include a products array with per-product name, type (Component or Carrier), rate, total applied, and area.
Machine file summary vs. operation summary
Machine file summary — Statistics from a single file’s point data, processed and cleaned by Leaf. Useful for understanding individual file contents.
Operation summary — Statistics from all files merged to a field boundary. Represents the complete picture of what happened on that field. This is what most applications should use.
Configurations that affect operations
| Configuration | Effect |
|---|
operationsFilteredGeojson | Enable filtered GeoJSON and V2 images |
operationsRemoveOutliers | Enable/disable outlier removal on harvest data |
operationsOutliersLimit | Standard deviation threshold for outlier removal (default: 3) |
operationsImageAsGeoTiff | Enable GeoTIFF image generation |
fieldOperationCreation | Enable/disable automatic creation of field operations from merged machine files |
operationsMergeRange | Time window for grouping files into the same operation |
operationsMergeOverlap | Minimum spatial overlap required to merge a file into a field |
What to do next
