Map service ComputeScale method

Calculates the scale of the specified map (data frame) at the given map extent for an image with the given size.

ComputeScale (MapDescription MapDescription, ImageDisplay MapImageDisplay)

Parameter	Description
MapDescription	Used to define the map extent in map units.
ImageDisplay	Used to define the map image extent in pixels.

Return Value

A double value representing the reference (or ratio) scale. The scale value returned represents the reference scale for a map image that would be generated if the MapDescription and ImageDisplay were used with the ExportMapImage method. The map extent defined for the inputMapDescription is often not the extent used to calculate the reference scale. The aspect ratio of the map is adjusted by the map service to account for theImageDisplay properties.

Remarks

Concepts for defining a reference scale for a map are cross-application, namely they apply to all mapping applications. When working with an ArcGIS Server map service, the output map is generated as an image, thus reference scale concepts must be to applied to the contents of the map image. When displaying map images in an application, rendering the map image at the proper scale depends on three variables:

1. The map extent
2. The resolution of the image
3. The resolution and display area (monitor)
4. The size of the display area (monitor)

The image resolution and display area resolution are measured in pixels while a size of the display area and the map extent is expressed using a measurable unit like inches, meters, or decimal degrees. In general reference scale equals:

(map units / pixel) * (pixels / inch of display area) * (screen units / map unit)

The number of map units per image pixel (map units / pixel) is commonly referred to a the Map Scale Factor and can be easily calculated. For example:

(maximum x value for map extent - minimum x value for map extent) / width of map image in pixels

It is often more difficult to determine how many pixels are rendered per inch of display area (pixels / inch of display area) since the display area size and resolution must be known - usually referred to as PPI (pixels per inch) or DPI (dots per inch). In most cases, client-side logic can determine the resolution but not the size of a display area. As a result a client application can either assume a standard size or prompt to end user to provide it. In general, the client-side DPI should match the server-side DPI. For ArcGIS Server map services, the server-side DPI is defined as a property of the ImageDisplay object. The DPI property does not change the resolution of the map image, it is merely used to provide the map service with information to calculate reference scale and change the visibility of scale dependent layers.

The number of screen units in one map unit (screen units / map unit) is a constant value depending on which units are being used. In most applications, the screen is measured using inches while the map unit is in meters or feet. For example, there are 39.3701 inches in 1 meter. Converting between linear units, such as meters to/from feet provides a constant result. Converting between linear and angular units (e.g. decimal degrees) will provide different results depending on the latitude at which the measurement takes place. ArcGIS Server map services assume the linear distance of a decimal degree as measured on the equator, thus one decimal degree equals approximately 69.09 miles. With this in mind, the reference scale for a data frame that defines decimal degrees as the map unit may be inaccurate.

Examples

C#

MapService_MapServer mapservice = new MapService_MapServer();

mapservice.Url = "http://localhost:6080/arcgis/services/MapService/MapServer";

 

MapServerInfo mapinfo = mapservice.GetServerInfo(mapservice.GetDefaultMapName());

>MapDescription mapdesc = mapinfo.DefaultMapDescription;

 

ImageDisplay imgdisp = new ImageDisplay();

imgdisp.ImageHeight = 500; //pixels

imgdisp.ImageWidth = 500; //pixels

imgdisp.ImageDPI = 96;

 

double scale = mapservice.ComputeScale(mapdesc, imgdisp);

VB.NET

Dim mapservice As MapService_MapServer = New MapService_MapServer()

mapservice.Url = "http://localhost:6080/arcgis/services/MapService/MapServer"

 

Dim mapinfo As MapServerInfo = mapservice.GetServerInfo(mapservice.GetDefaultMapName())

Dim mapdesc As MapDescription = mapinfo.DefaultMapDescription

 

Dim imgdisp As ImageDisplay = New ImageDisplay()

imgdisp.ImageHeight = 500 'pixels

imgdisp.ImageWidth = 500 'pixels

imgdisp.ImageDPI = 96

 

Dim scale As Double = mapservice.ComputeScale(mapdesc, imgdisp)

Java

String serviceURL = "http://localhost:6080/arcgis/services/MapService/MapServer";

MapServerBindingStub mapService = new MapServerBindingStub(serviceURL);

 

String mapName = mapService.getDefaultMapName();

MapServerInfo mapInfo = mapService.getServerInfo(mapName);

MapDescription mapDesc = mapInfo.getDefaultMapDescription();

 

ImageDisplay imgDisp = new ImageDisplay();

imgDisp.setImageHeight(500); //Height of the image in pixels

imgDisp.setImageWidth(500); //Width of the image in pixels

imgDisp.setImageDPI(96);

 

double scale = mapService.computeScale(mapDesc, imgDisp);

System.out.println("Scale: " + scale);