Custom palettes for image annotation in Survey123

Jim-Moore · ‎02-23-2022

In ArcGIS Survey123 an image question with the annotate appearance allows users to mark up an image. The image can be a photo captured with the device's camera, an existing image file, or a snapshot of a map. Similarly, an image question with the draw appearance provides a blank canvas for users to sketch on.

In September and December 2021, we introduced several significant improvements to the user experience for draw and annotate questions, including better drawing tools and the ability to edit annotations. For a detailed look at these improvements, see the Updates to draw and annotate in ArcGIS Survey123 (September 2021) blog post.

Survey123 ships with a default drawing tools palette that contains eight tools, including arrows, generic marker symbols, and text labels. The default palette allows users to modify the properties of the drawing tools to their liking while in the field. But what if, as a survey author, you want to make sure users draw their annotations with a specific set of tools, so that all annotations are consistent?

In this blog post, we’ll explore how to create your own custom annotation tools palettes and add them to questions in a survey.

Standardize image annotations for your organization

Your organization might have a need to customize (or should we say, standardize) drawing tools to help make annotated images consistent and to help make image annotation in the field more efficient. For example, to ensure a particular feature is always drawn using the same line style, or that labels are always the same size and color.

A few examples are shown below. A utility company might have specific symbols and line styles that relate to electrical or gas works. Similarly, an engineering organization might want certain colours and arrows to be used when marking up defects in equipment. An environmental assessment survey might require a special symbol to represent a particular type of ground cover.

The February 2022 release of Survey123 allows you to create custom drawing tools palettes for the Survey123 field app, where you can configure your own line styles, add your own marker symbols, and so on. What’s more, custom palettes are applied to individual questions in your survey, meaning you can include multiple palettes in the same survey, each with a specific application.

For example, in a road assessment survey, you might have an image question asking the user to indicate the where potholes are on a snapshot of a map. This question could have a custom palette that includes only two tools: specific symbols for small and large potholes. Another question in the survey might ask the user to take a photo of a guard railing that is damaged and use an orange arrow to indicate where the damage is. And so on.

Note: Custom palettes for image annotation are not supported in the Survey123 web app.

The process for creating a custom palette and adding it to your survey is as follows:

Configure the Python environment in ArcGIS Survey123 Connect, so that you can run the conversion utility (step 4).
Prepare a custom palette using the XLSPalette specification.
Add the XLSPalette file and any associated files to the survey's media folder.
Convert the XLSPalette to a .palette file by running the conversion utility on the Media tab in Survey123 Connect.
In the XLSForm for the survey, set an image question with draw or annotate appearance to use the custom palette instead of the default palette by specifying the palette parameter in the body::esri:style column.

The following sections will guide you through these steps.

Configure tools in Survey123 Connect

To use custom palettes in Survey123 you must first configure Python in Survey123 Connect. The reason this step comes first is because without Python, it is not possible to convert your XLSPalette file (step 4) and add it to your survey (step 5). Before you get carried away with designing drawing tools in XLSPalette, you’ll need to overcome this first hurdle! To get started:

Install Python 3.7 or later.
1. You can download Python from the Windows Store or the Python website.
2. It is recommended to add Python as a PATH environment variable.
3. If you have ArcGIS Pro installed, you can use its Python environment, which is installed with ArcGIS Pro by default.
Install the openpyxl package.
1. If you are using ArcGIS Pro as your Python environment openpyxl will be installed automatically. For more information, see Work with Python packages.

Once your Python environment is installed, in Survey13 Connect, go to Settings and select the Tools tab. If Python was added as a PATH environment variable, Survey123 Connect should automatically detect your Python install. If it doesn’t, click the folder button next to the empty path and navigate to the folder where your Python environment is located. The default ArcGIS Pro Python installation is in:

C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3

Survey123 Connect will automatically detect what Python packages are installed and let you know if you have the arcgis, openpyxl, and pyxform packages installed. This workflow requires openpyxl only. If you see a check mark next to openpyxl you can move on to the next step. If you don't see openpyxl checked, check the installed packages you have in the environment specified. Note that the openpyxl version number will vary depending on your Python environment, but any recent version should suffice.

If you happen to have the pyxform package installed, you will also see the option to specify a Java Runtime Environment on the Tools tab, in addition to Terminal settings. Neither are not required for this workflow, or any other workflow in Connect at this stage – but watch this space. In the future, we hope to support additional tools that make use of Python, JRE, and Terminal.

Prepare custom palette

A custom palette is configured in XLSPalette, a .xlsx file that contains the worksheets that will be converted into a .palette file. The XLSPalette specification is designed specifically for creating annotation tools in Survey123. It provides a syntax that can be entered into a familiar spreadsheet, in much the same way as XLSForm is used to create a survey form.

Download the Survey123 XLSPalette template to get started.

Toolsets and drawing tools

Each worksheet in the XLSPalette is a toolset: a group of tools in the palette. The rows in each toolset worksheet define the annotation tools that make up the toolset.

Toolset worksheets can be added or removed as required. To add a new toolset worksheet, make a copy of an existing toolset worksheet to ensure the conditional formatting and data validation is preserved. Toolset worksheets that do not contain any rows besides the header row will be ignored when the XLSPalette is converted to a .palette file.

There’s no limit to the number of tools you can add to a toolset, but a practical limit can be determined by your screen size. Half a dozen tools in a toolset works well.

The full XLSPalette specification is described on the Reference worksheet in the XLSPalette template and in the Survey123 documentation.

Data validation on the toolset worksheets will help guide you through what is required in each column. Cells that require a value are highlighted red. The cells to complete will vary depending on the type.

The following example shows the XLSPalette configuration for three annotation tools on a toolset worksheet named Services&icon=wrench. The &icon= parameter in the worksheet name is used to specify the toolset icon that will appear in the Survey123 field app. Read more about toolset icons here.

The drawing tool type (line, area, marker, or text) is specified in the type column. A label for the tool is provided in the label column; this label will appear in the Survey123 field app, under a preview of the tool’s style.

In the tool column, the tool style is defined. For example, a line can be a straight line, or a polyline with multiple vertices. These styles are also part of the default palette. For more information on these, refer to the documentation on the default palette.

The symbol column is where you set out the properties of the tool in name=value pairs, separated by ampersands. In the textSymbol column you can specify text properties such as color, size, and alignment.

The syntax above includes the following:

For Gas Line (Proposed), the color, width, and style properties are used to create a blue line that is five pixels wide, with a dash pattern of 4 on, 1 off. That is, solid line for a relative length of 4, followed by a space of length 1.
For Work Area, the tool column is set to polygon, which allows users to draw a polygon vertex-by-vertex. The polygon has a transparent red fill and dotted outline. See more on tool colors, below.
For Gas Meter, the marker is a .svg file that is stored in the survey’s media folder. The &size= property sets the marker size in pixels. The black text label is anchored to the bottom of the marker and has a cyan halo.
For Notes, the syntax in the textSymbol column creates a “sticky note” text box with yellow background and black outline, with text that is aligned to the left.

Here’s how the tools appear in the Survey123 field app:

Tool colors

Colors can be specified by HTML color name, #rrggbb, or #aarrggbb. Use #aarrggbb to specify opacity. The “aa” represents the hexadecimal value for the alpha channel, which describes the degree of transparency. This value can be equated to an opacity percentage by determining the percentage of 255, then finding the hexadecimal value of that number.

For example, an opacity of 50% (that is, 50% transparent) would be 255 × 0.5 = 127.5. The hexadecimal value for 128 is 80, so standard blue with 50% transparency would be given as #800000ff. You can use the built-in Windows Calculator app in Programmer mode to get the hex value for a decimal number.

Once you have configured the toolsets and drawing tools, copy the XLSPalette file (XLSX) and any image files the palette uses (for example, SVG marker symbols and toolset icons) to the media folder for your survey. The XLSPalette can now be converted into a .palette file that Survey123 can use.

Convert palette

In Survey123 Connect, go to the Media tab for your survey. The Media tab lists the contents of your survey's media folder. A palette button is shown alongside all .xlsx files in the media folder. Click the palette button to convert your XLSPalette. When the conversion is complete, a .palette file is added to the media folder. This file contains JSON that describes your toolsets and drawing tools in a notation that Survey123 can read. For the curious, you can open a .palette file in a text editor and check it out.

The name of the .xlsx file will be the name of the .palette file, and this is the name that must be used in the palette=<palette_name> parameter in your XLSForm. To ensure your palette name can be used as a parameter, ensure your .palette file name does not contain any spaces.

Update palette

To update your custom palette, make the changes in the .xlsx file, save your changes, and click the button to run the conversion utility on the Media tab. This will update the existing .palette file in the media folder. The changes will be available in Survey123 Connect as soon as the form preview is updated. This process is quick and helps when designing a palette, as there can be some trial and error involved in getting the symbol settings just right. Once you’re happy with your custom palette, publish your survey to see the changes in the Survey123 field app.

Add custom palette to your survey

You can add as many custom palettes to your survey as you like, but only one palette can be used in each image question. To add a custom palette to your survey:

Ensure the .palette file is in your survey's media folder.
For an image question with draw or annotate appearance, add palette=<palette_name> in the body::esri:style column, where <palette_name> is the name of the .palette file without the extension. This parameter is case sensitive.
1. For annotate questions, specify the image capture method in the same column, using the method parameter. The palette and method parameters must be separated by a space. For example, palette=SiteLayout method=map,camera,browse. For more on the method parameter, see the documentation on appearances.
Publish your survey.

Your custom palette will be used for the image question, replacing the default palette.

A number of improvements introduced in the last six months means there’s now a lot you can do with annotation in the Survey123 field app. We hope you enjoy the freedom to tailor the drawing and annotation experience for your organization’s needs. Leave a comment below and let us know how these features might help your workflows!