FarmBot uses computer vision software to detect the average z-axis coordinate of the soil in an image. See how it works.

While the Measure Soil Height feature provides an automated method for mapping the soil surface, you may also manually add soil surface points through the Points panel. It is recommended to add at least several points manually (even if using the automatic method) for comparison.


  1. Move FarmBot to a location where the camera has a clear view of a wide area of soil. Ensure the Y and Z axes have room to move away from home/zero.
  2. Measure the distance from the camera lens to the soil with a tape measure.
  3. Open the Measure Soil Height section of the Photos panel.
  4. Enter the measured distance in millimeters in the Measured distance from camera to soil input.
  5. Press CALIBRATE. FarmBot will:
    • take a photo
    • move the y-axis a small amount
    • take another photo
    • move the z-axis
    • take another photo
    • move the y-axis back
    • take another photo
    • move the z-axis back


Once calibration is complete, soil height can be measured and recorded by pressing MEASURE in the Measure Soil Height section of the Photos panel or by using a Measure Soil Height sequence command and running the sequence.

For full garden soil mapping, follow Scan the Garden for Weeds and use the Measure Soil Height sequence command.

Check results

The measured soil z coordinate will be shown in a toast message and saved to a soil height point in the Points panel. An image will be saved to the Photos panel which will also be shown in the map if the camera has been calibrated.

Before using the detected soil height values, compare the results to your garden bed:

  • Spot check individual values by moving FarmBot above the soil height point and measuring the distance to the soil with a tape measure or slowly moving FarmBot down to the detected soil height.
  • Remove or adjust outliers at the top and bottom of the soil height points list.
  • Open the profile viewer and check the detected soil cross-section.

If the detected values are consistently offset from the actual soil surface, try adjusting the Measured distance from camera to soil input in the Measure Soil Height section of the Photos panel or re-calibrate by pressing the RESET CALIBRATION VALUES button and following the calibration steps.

To choose a different output image, click Advanced in the Measure Soil Height section of the Photos panel and select an IMAGE OUTPUT option.

Use soil height

After checking the detected soil points and removing or adjusting any outliers, open the soil height points list and press the USE AVERAGE Z button to apply the average detected soil height to the soil height value used by Move sequence commands.


  • Ensure the Y and Z axes move smoothly without errors before attempting calibration.
  • Tune the weed detector parameters to detect plants before attempting soil height measurements.
  • Calibrate and measure soil height from a medium to maximum camera to soil distance.
  • Take measurements and update the soil height value over time to account for soil settlement.
  • Prepare the garden bed soil surface by smoothing and flattening as much as reasonably possible.
  • If high precision is required, consider an alternative approach such as manual measurements. Measure Soil Height is a simple camera-based solution and will not be as accurate or available over a large range of conditions as other methods.



Error message: Problem getting image
Troubleshooting steps: Verify camera is working by taking a photo.


Error message: Calibration measured distance input required
Solution: Provide a distance measurement (see the calibration steps).

Error message: Image size must match calibration
Solution: Recalibrate or revert change to image capture size or rotation.


All other error messages
Troubleshooting steps:

  • Verify the soil is clearly visible in photos.
  • Try recalibrating at a different location.
  • Try moving the camera as far away from the soil as possible. If a closer measurement distance is desired, increase the DISPARITY SEARCH DEPTH value in Advanced settings.