Updates to draw and annotate in ArcGIS Survey123 (September 2021)

09-22-2021 04:09 AM
Esri Regular Contributor
6 16 8,148

The September 2021 release of ArcGIS Survey123 (version 3.13) includes several significant improvements to the user experience for draw and annotate questions in the Survey123 field app. These changes incorporate numerous requests and feedback from our Survey123 community and seek to enhance the drawing experience to make it more useful and more efficient in the field. The key highlights in version 3.13 are as follows:

  • Completely redesigned drawing tools palette, including new drawing tools and options.
  • Ability to zoom and pan the canvas.
  • Annotate images at their original resolution. Previously, images would be resized to match the viewable canvas area.
  • Any EXIF information in the source photo is copied to the annotated image.
  • When annotating a map snapshot, the map pin is now hidden from the image.

In this blog post we'll do a quick recap on image annotation in Survey123, delve into the new user experience and explain what’s new, and touch on the enhancements still to come.


Before we check out the latest enhancements, here’s an overview of image annotation in ArcGIS Survey123.

Draw and annotate are staple features of Survey123. By applying the annotate appearance to an image question, an author can allow users to mark up 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.


Draw and annotate questions are useful in a range of applications. For example, an asset inspection field crew might take photos of equipment and mark-up any faults with the drawing tools. A law enforcement officer might take a snapshot of a map and then sketch a diagram of where an incident took place.

To add draw and annotate questions to your survey:

  • Apply either the draw or annotate appearance to an image question.
  • You can also apply the multiline appearance (for example, draw multiline) to allow users to submit multiple images to the same question.
  • Set the default image size for your survey in the Options tab in Survey123 Connect.
  • Set the image size on a per-question basis using the max-pixels parameter in the parameters column.
  • Use the method parameter in the body::esri:style column to restrict the capture method to a new photo from the camera (method=camera), an existing image file (method=browse), or a snapshot of a map (method=map).
  • Optionally, provide a default image. This can be useful for providing a "template" for an image question. For example, a diagram of a piece of equipment that the user can annotate, or grid lines on a plain background for a draw question, perhaps with your company logo in the corner!


For more information on controlling image size for image questions, see Images. For more information on the draw and annotate appearances, see Appearance. There's also an Images and Annotation sample XLSForm in Suvey123 Connect to help you get started.

User experience

The September 2021 release brings with it several improvements to the user interface (or canvas interface, as we like to call it). The canvas interface is documented here. The canvas can be in one of two modes: explore or draw. Here’s a quick tour:

  1. Canvas—Images and graphic elements are added to the canvas.
  2. Explore and draw modes—Switch between the two modes.
  3. Toolbar—Buttons for various options will appear here. Buttons vary depending on the mode the canvas is in and the active drawing tool.
  4. Save image—Save the image and return to the survey form.
  5. Reset—Reset the canvas by taking a new photo with the camera, selecting a new image from file, taking a snapshot of a map, or reverting to a blank canvas. Note: All graphic elements and images currently in the canvas will be removed.
  6. Return to survey without saving.


Explore mode

In explore mode you can zoom and pan the canvas; zoom to the actual size (100%) of the canvas; adjust the zoom to fit the canvas on screen; or fill the screen with the canvas. Manipulate the view either by selecting the buttons or directly on the canvas itself using touch or mouse (on desktop).

Select the explore mode button (1) to enable explore mode. Select again to reveal the explore options menu (2). Several of these options are also available as buttons on the toolbar (3).



Draw mode

In draw mode, select the drawing tool preview in the bottom left of the canvas or the draw mode button to open the drawing tools palette. The drawing tools palette has been enhanced to include more drawing tools (including marker symbols and vertex-by-vertex lines) and greater control over color, line style, transparency, fill, and text style.

  1. Drawing tool settings preview—Shows a preview of the style settings for the currently selected drawing tool.
  2. Draw mode—Select to enable draw mode. Note that the icon for this button reflects the currently selected drawing tool.
  3. Undo—Undo the last graphic element. Buttons on the toolbar will change depending on the active drawing tool.



Drawing tools palette

Select either the drawing tool settings preview or the draw mode button to reveal the drawing tools palette. The drawing tools palette in Survey123 version 3.13 offers many improvements, including:

  • New drawing tools, including arrows, polylines, marker symbols, and text labels.
  • Add halo to text labels.
  • Choose single line or multiline text.
  • Control the opacity of lines and fills.
  • Settings for each tool are saved for each image question.

An overview of the drawing tools palette:

  1. Select from eight drawing tools.
  2. Expand or collapse the settings panel.
  3. Select the fill button (paint bucket) to switch off background fill (in the case of the label tool, the background can be disabled from the text options menu).
  4. Select the text button to reveal text options: single line, multiline, halo, and background color for labels. You can also turn off the label for a drawing tool.
  5. Select the color preview swatch to reveal the color palette.
  6. Adjust the text size, halo width, and line width using the sliders.


The drawing tools palette can be expanded or collapsed (2) and the state of the palette is remembered per question. When the palette is collapsed, switching to another drawing tool requires only a single selection, so once you’ve set up your drawing tools palette you can collapse it to make selecting tools faster:




There are eight default colors to choose from, plus a ninth swatch for setting a custom color; however, any color swatch can be customized by pressing and holding it.

  1. Active color, indicated by check mark. If the custom color swatch is active, no check mark is shown.
  2. The slider lets you change the opacity in increments of 10% from 10 to 100%.
  3. Press and hold on any of the other eight colors to set a new color.
  4. Bottom right color swatch can be used to set an additional custom color.

Note (3) and (4) launch the default color picker dialog for your device’s OS.

The image below shows the default color palette on the left, and a customized palette on the right:




Each drawing tool has text enabled by default. The position of the text varies depending on the drawing tool. For example, for straight lines the text is positioned above the midpoint of the line and rotated to the same angle as the line itself (perfect for adding dimensions!). For shapes, text is positioned in the horizontal and vertical center of the polygon, and for markers the label is placed underneath the symbol itself. To disable text for a drawing tool, select the No label option from the text menu.

You can also add a text label on its own using the label tool (1). This allows you to create “sticky note” labels (see an example, below) with background fill and outline that can be positioned wherever you like on your image.



Image size

Before we get into the details about image size, let’s define the term "viewable canvas area". The viewable canvas area is the region in the app between the title bar and the toolbar, where the canvas or image is presented and you can add graphic elements (lines, text, symbols, and so on). The size and resolution of the viewable canvas area is dependent on the device’s screen dimensions, and the size of the application window when running the field app on desktop.


Prior to the September 2021 release, the image size for draw and annotate questions was limited to the dimensions of the viewable canvas area. Photos taken with the camera or added from file would be resized to fit the viewable canvas area. When adding an image to the canvas, users were often seeing their annotated images reduced to a much smaller size than their original image, which is not ideal if you need to do detailed annotation work. With the latest release, you can configure your survey so that the original size of your source images is preserved.

In general, the size of the canvas for draw and annotate questions (and hence the dimensions of the image attachments that are submitted) can be specified in the following ways:

  • Set the image size in pixels (on the longest edge) for all image questions in your survey on the Options tab in Survey123 Connect. The unrestricted setting will preserve the original size of photos you take with the camera or existing image files. For example, if your device’s camera captures an image at 3000x2000 pixels, the annotated image will also be this size.
  • Set the max-pixels parameter for an individual image question. If max-pixels is specified, this will take precedence over the image size set on the Options tab in Connect. The max-pixels parameter is set in the parameters column of your XLSForm. For example, max-pixels=1200 will set the image size to 1200 pixels on the longest edge, preserving the aspect ratio of the original image.
    o If the max-pixels parameter is set for a draw question the blank canvas will be square (1:1) at the size specified (for example, max-pixels=500 will result in a blank canvas that is 500x500 pixels).
  • Set a default image for an image question. The image file must be in the survey’s media folder and its file name and extension specified either in the default column in your XLSForm, or by using an expression in the calculation column. If a default image is provided, the image size set on the Options tab in Connect and the max-pixels parameter (if specified) will be disregarded, with the size of the final annotated image determined by the dimensions of the default image.

The following special cases also apply:

  • Blank canvas—If max-pixels in not specified and there is no default image, the canvas for a draw question will be set to the dimensions of the viewable canvas area.
  • Map snapshot—A map snapshot is always captured at the size of the viewable canvas area.

Other improvements

You can add a default image to draw or annotate, and its original size will be honored in the annotated image. This is useful for standardizing the image size submitted for a question, regardless of the device. You can also personalize this default; for example, for draw questions where users will draw a sketch, you could add gridlines on a white background, with your company logo in the lower corner. The Transmission Tower Inspection Community sample survey in Survey123 Connect is a good example of how default images can be used effectively for asset inspections.

Customer feedback told us that when it comes to annotating a new image captured with the camera or selecting an existing image from file, it would be useful to retain any EXIF information from the original image file and apply it to the new annotated image. From version 3.13, any EXIF data in the source image is now copied to the annotated image.

Customer feedback also told us that it’s not useful to show the pin on the map when taking a map snapshot, as this can interfere with the annotations. The map pin is now hidden from the canvas (but is still visible in the map window when specifying the map extent).

Future enhancements

The Survey123 team is working on expanding the draw and annotate tools to include more features for editing and customization.

Select and edit graphics

Users will be able to select any graphic element on the canvas and manipulate or delete it. This includes being able to modify the drawing order of elements on the canvas (bring to front, send to back, and so on) as well as rotate and modify individual graphic elements.

Custom palettes

The Survey123 field app ships with the default drawing tools palette containing eight tools that users can configure in the app. We’ve received requests from organizations that wish to standardize the drawing tools so that annotated images are consistent across surveys and across their organization.

The Survey123 team is working on a method to allow survey authors to design custom drawing tools palettes and set these on a per-question basis. For example, a utilities company might have specific symbols and line styles that relate to electrical or gas works. Custom palettes can help make image annotation in the field more efficient and consistent.

Join the ArcGIS Survey123 Early Adopter Community for more details and to get started testing with the latest beta versions.


We hope you enjoy the latest improvements to the user experience for drawing and image annotation in ArcGIS Survey123. Please share your feedback in the comments below, we’d love to hear from you!