Survey123 Tricks of the Trade: A built-in compass for your forms
There are some specific field data collection workflows where you may want to capture the direction of things. Geologists, for example, measure the horizontal orientation, or strike, of geological faults. During an inspection or hazard assessment, you may need to report in what direction a utility pole, or tree, is leaning.
While you can always add a numeric question to your Survey123 form and ask field users to measure direction with an external compass, in this article I will describe how you can measure the direction of things using a built-in compass right within your Survey123 smart form.
This feature is not documented, other than through our Early Adopter Community website, so I thought I would bring some extra visibility to it. Familiarity with XLSForm and Survey123 Connect is assumed.
The Survey123 compass control uses the magnetometer in your mobile device to measure the orientation of your device. All you need to do is to align your device with the direction you want to measure. Once you are happy, you tap on the compass control to lock the measurement.
The compass control also includes an indicator on the side. If your device magnetometer is not calibrated correctly, the pointer will move into the red zone.
To add the compass control into a smart form, add a decimal question and set its appearance to bearing. Please note that the bearing appearance is not documented, nor is it included with the Survey123 templates. You will need to type the word bearing into the appearance column manually.
The compass control returns the azimuth measured against magnetic north. If you want the azimuth measured against true north, you need to correct the measurement using the magnetic declination at your location.
If you plan to use your survey in a reduced geographic area, you can get the magnetic declination for your area from the NOAA website and use a calculation in your form to make the adjustment.
For example, for the city of Redlands, in California, the magnetic declination is 11.45 degrees. In my XLSForm, I add a new question to apply the correction. Note that I also set the bind::esri:fieldtype column to null in the question with the bearing appearance, because I do not want to store the value without the adjustment.
If you want to get fancy, you could dynamically calculate the magnetic declination based on your location using a custom JS function. Here is one showing how this could be done. Note that the function makes a call to the NOAA Magnetic Declination online calculator service. This function will not work if you are offline.
function getMD(location){
var coordsArray = location.split(" ");
var lat = coordsArray[0];
var lon = coordsArray[1];
var url = "https://www.ngdc.noaa.gov/geomag-web/calculators/calculateDeclination?lat1=" + lat + "&lon1=" + lon + "&resultFormat=json";
var xmlhttp = new XMLHttpRequest();
xmlhttp.open("GET",url,false);
xmlhttp.send();
if (xmlhttp.status!==200){
return (xmlhttp.status);
} else {
var responseJSON=JSON.parse(xmlhttp.responseText)
if (responseJSON.error){
return (JSON.stringify(responseJSON.error));
} else {
return JSON.stringify(responseJSON.result[0].declination);
}
}
}
Here is the corresponding XLSForm:
Similarly, you could adjust the direction values using workflow automation with Integromat or Microsoft Power Automate. If you take that approach you could work offline and still have the true north azimuth values calculated dynamically. Ah! Of course, you can also use ArcGIS Pro or a Python script!
Again, I think that for most cases you may be fine calculating the magnetic declination for your area and hard-coding the value in the form logic, but other options exist for you to make corrections dynamically if you need to.
One last thing to keep in mind: the bearing appearance is only supported in the Survey123 field app.