Output symbology and coordinate systems in web tools

When constructing web tools, the output rendering and coordinate system of the data can be important details. Your tool successfully ran, created output, and your job as the author of the tool is complete. Or is it? To construct a good tool for use on the web, time spent understanding and ensuring your tool is well defined with good symbology and a proper coordinate system can be the difference between a good experience and a great experience for the consumer of your tools.

Output symbology

Web tools that provide geographic output can have results drawn in one of the following two ways:

  • The client is sent the result features and draws them.
  • The client is sent a map image from a map service that has drawn the image on the server.

The client consuming a web tool cannot ask for the result as a map image unless the service has been set up this way. The publisher or administrator of the service must have enabled this setting prior to the consumption of the web tool.

Client draws the output

By default, a web tool returns the output features from a successful tool execution to the client. It is up to that client to draw or render those features on a map. In Javascript API, the code must get the result, set a renderer, and finally draw the result as defined by the web app creator. With desktop applications, they will get and draw the features from the web tool. The client can change the symbology as they interact with it.

Server returns a map image

When creating a web tool, you can opt to view the output as a map image (when the service is set to execute asynchronously). The output features from the service will be drawn as a map image and that image will be returned to the client. In this situation, the features are not usually returned (the service publisher may have set that no features can be returned). Creating the result on the server and returning the map image is useful for a variety of cases, such as the following:

  • When it is impractical to send large data (big rasters) or a large number of features back to a client.
  • When the output features cannot be drawn in the client. For example, a raster (.tif) cannot be drawn in a web app.
  • When the client cannot draw or render to a high cartographic quality. The map image maintains the same symbology settings of your output result at the time it was published.

Coordinate systems

Every dataset a web tool processes must have a coordinate system. Generally, all the data your tool processes will be in the same coordinate system, and you won't give any further thought to particular coordinate systems in your web tools. However, there are situations when you need to be aware and modify the data.

Web apps almost exclusively use the Web Mercator coordinate system (WKID: 102100). When constructing a web tool that will output features to be drawn on a web app, you may or may not want to generate your data in Web Mercator. If the objective is to simply display the results in a map, using Web Mercator may be best as it reduces unnecessary transformations. If the objective is to prioritize accurate area or length measurements, a local coordinate system that lends itself well to your area of study may be preferred. Geoprocessing tools process and output data based on the coordinate system of the input unless the output coordinate system of the particular tool has been defined. Keep these points in mind as you decide whether to reproject the data or keep it as is before constructing your web tool.

The geoprocessing service of the web tool has the option to accept an output coordinate system value. At the time the tool is executed on the server, the client application can tell the service to return the output in a specific coordinate system. As mentioned previously, processing is done based on the coordinate system of the input, thus, the output will be in that same coordinate system. This setting allows the processing to continue in the given coordinate system, but the server will project the data as needed and return the final output in the coordinate system of your choice. See the ArcGIS REST API help for more information on setting the outSR.