Prepare for rangefinder data collection

Rangefinders can be used to capture location, offset, and height information about a target object. Rangefinders are typically used in the following situations:

• When mapping the location of an object which is inaccessible, either because it is difficult to get to or it is not safe to get to the object. For example, a tree on an island, or a manhole in the middle of a busy road.
• When mapping the location of an object where it is not possible to get a GPS signal, or a GPS position of sufficient accuracy. For example, under a large tree or in a narrow street or ‘urban canyon’.

Prepare a survey to record measurements

First, you must decide which measurements will be recorded.

At a minimum, you must create a text question with an appearance of rangefinder to store the values that are returned from the rangefinder. This question can be a text question if you are recording multiple rangefinder measurements (the entire JSON object will be stored), or an integer or decimal question if you are only recording one measurement (a single numeric value is stored).

Measurement types are specified in the bind::esri:parameters column using measurement= followed by a comma separated list of parameters, for example, measurement=height,azimuth,horizontalDistance,slopeDistance,inclination.

A multiple height measurement routine can also be carried out on a vertical structure using the multipleHeight parameter, followed by the comma separated list of height labels. Enclose the list of parameters in quotation marks if any of the height labels contain spaces, for example, measurement="multipleHeight,Height 1,Height 2,Height 3". Multiple height measurement routines cannot be combined with other measurement values; they can only be used in isolation.

Additional text questions in the survey can store individual measurements. Use the pulldata function to pull out properties from the JSON object that is returned by the rangefinder. For example, the following will return only the heading value (azimuth): pulldata("@json",${tree},"azimuth").

The following is an example of a JSON object returned by a rangefinder. Any of these properties can be retrieved and stored in a question using a pulldata expression similar to the one above:

{
    "referenceCoordinates": {
       "latitude":-37.8479578,
       "longitude":144.9792849
    },
    "targetCoordinates": {
       "latitude":-37.847956857525,
       "longitude":144.979303248161
    },
    "height":0.6,
    "heightUnits":"m"
    "horizontalDistance":2.1,
    "horizontalDistanceUnits":"m",
    "slopeDistance":2.1,
    "slopeDistanceUnits":"m",
    "azimuth":50.1,
    "azimuthUnits":deg",
    "inclination":-4.4,
    "inclinationUnits":"deg",
    "heightArray":[0.6,0.9,1.1,1.4,2]
}

When a survey that contains questions with the rangefinder appearance is launched, the user will see a rangefinder icon next to the question. To capture a measurement they will tap on the icon, fire the rangefinder, and return to the survey to complete the remaining questions.

Prepare a survey for use in a workflow

An alternative configuration can be made to a survey to allow it to be selected from the Rangefinder tile in the Survey123 gallery.

The rangefinder tile is suited to repetitive capture projects where rangefinder measurements form the bulk of the data input for the survey. Multiple surveys can be configured to accept rangefinder measurements and can be selected at the time of capture.

To configure a survey to appear in the survey list of the rangefinder tile, add one of the following values to the bind::esri:workflow column:

• rangefinderMode=height
• rangefinderMode=offset
• rangefinderMode=height,offset
• rangefinderHeight

This parameter will tell the app which rangefinder measurement workflow you are running and store the returned JSON object in the associated text question. These questions can be hidden in the survey (using the hidden appearance) and individual measurement values can be stored in additional questions.

The multiple height measurement workflow can also be configured by including the text question with rangefinderMode=height, along with additional decimal questions to store each height value. Give each decimal question the value of rangefinderHeight in the bind::esri:workflow column of the XLSForm.

Additional questions in the survey can store other individual measurement values. Use the pulldata function to pull out properties from the JSON object that is returned by the rangefinder as described in Prepare a survey to record measurements.