Visible scale range | ArcGIS Maps SDK for JavaScript

Percent of households with no vehicle available. Expand the layer list widget in the app to view the legend. As you zoom in, the same data will load with higher resolution geometries to provide more detail.

What is visible scale range?

A visible scale range defines the minimum and the maximum scales at which a dataset can be viewed.

Scale is a unitless way of describing how any distance on the map translates to a real-world distance. For example, a map at a 1:24,000 scale communicates that 1 unit on the screen represents 24,000 of the same unit in the real world. So one inch on the screen represents 24,000 inches in the real world.

Large scales display areas that are zoomed in, such as neighborhoods. Large scales allow you to view small areas so objects in the map (e.g. buildings) appear larger in the view.

Small scales display areas that are zoomed out, such as countries and continents. Small scales allow you to view more data. However, objects (e.g. buildings) appear smaller than they would in large scale maps.

Small scale	Large scale
1:72,876,217	1:8,000

The concept of large scale vs. small scale can be confusing because the ArcGIS Maps SDK for JavaScript defines scale as a whole number using the denominator rather than the actual ratio it represents. For example, a view at a scale of 1:24,000 is defined as view.scale = 24000, not view.scale = 1/24000. Even though 24,000 is less than 4,000,000, a scale value of 24,000 is considered larger than a scale value of 4,000,000 because the fraction 1/24000 is larger than 1/4000000.

Why is visible scale range useful?

Some large datasets can’t be reasonably visualized at certain scales. For example, it doesn’t make sense to display census tracts at scales where you see the whole globe because tracts typically represent neighborhoods and small communities. Many polygons at that scale would be smaller than a pixel, making them useless to the end user.

Setting visible scale range on your layers also helps reduce the initial data download to the browser. Don’t display too much data if you don’t have to!

How visible scale range works

Visible scale range is defined on the layer with a minScale and a maxScale. minScale is the larger of the two numbers and defines the farthest the user can zoom out to view the layer. maxScale is the smaller of the two numbers and defines the farthest the user can zoom in to view the layer. Oftentimes the maxScale can remain undefined or 0. Setting the minScale will make the most difference in reducing download size.

Examples

One variable, multiple layers

The following example demonstrates how to visualize the same data variable at multiple resolutions by setting visible scale ranges on layers representing U.S. states, counties, and census tracts. This requires that the data is properly aggregated within each layer.

Open the CodePen and reset the minScale and maxScale on each layer to 0 to observe how this affects the visualization.

ArcGIS JS API


24 collapsed lines
1
<html>
2
  <head>
3
    <meta charset="utf-8" />
4
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
5
    <title>Visible scale range</title>
6

7
    <link rel="stylesheet" href="https://js.arcgis.com/5.0/esri/themes/light/main.css" />
8
    <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
9
    <script type="module" src="https://js.arcgis.com/5.0/"></script>
10

11
    <script type="module">
12
      const [MapView, Map, SpatialReference, FeatureLayer, LayerList, Expand] =
13
        await $arcgis.import([
14
          "@arcgis/core/views/MapView.js",
15
          "@arcgis/core/Map.js",
16
          "@arcgis/core/geometry/SpatialReference.js",
17
          "@arcgis/core/layers/FeatureLayer.js",
18
          "@arcgis/core/widgets/LayerList.js",
19
          "@arcgis/core/widgets/Expand.js",
20
        ]);
21

22
      const effect = "drop-shadow(4px, 4px, 2px, rgb(100,100,100))";
23

24

25
      const url =
26
        "https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/services/ACS_Vehicle_Availability_Boundaries/FeatureServer";
27

28
      const statesLayer = new FeatureLayer({
29
        url,
30
        layerId: 0,
31
        minScale: 0,
32
        maxScale: 30000001,
33
        effect,
34
      });
35
      const countiesLayer = new FeatureLayer({
36
        url,
37
        layerId: 1,
38
        minScale: 30000000,
39
        maxScale: 2000001,
40
        effect,
41
      });
42
      const tractsLayer = new FeatureLayer({
43
        url,
44
        layerId: 2,
45
        // This prevents the app from loading all census tracts at small scales
46
        minScale: 2000000,
47
        maxScale: 0,
48
        effect,
49
      });
65 collapsed lines
50

51

52
      const viewSpatialReference = new SpatialReference({
53
        wkid: 5070,
54
      });
55
      let centerPoint = {
56
        x: 0,
57
        y: 0,
58
        spatialReference: viewSpatialReference,
59
      };
60

61
      const view = new MapView({
62
        container: "viewDiv",
63
        map: new Map({
64
          layers: [tractsLayer, countiesLayer, statesLayer],
65
        }),
66
        spatialReference: viewSpatialReference,
67
        viewpoint: {
68
          rotation: 0,
69
          scale: 34809209,
70
          targetGeometry: {
71
            type: "point",
72
            spatialReference: {
73
              wkid: 5070,
74
            },
75
            x: -77487.07615764029,
76
            y: 1780211.54390861,
77
          },
78
        },
79
      });
80

81
      const layerlist = new LayerList({
82
        view,
83
        listItemCreatedFunction: (event) => {
84
          const item = event.item;
85
          item.panel = {
86
            content: "legend",
87
          };
88
        },
89
      });
90

91
      view.ui.add(
92
        new Expand({
93
          view,
94
          content: layerlist,
95
        }),
96
        "top-right",
97
      );
98
    </script>
99

100
    <style>
101
      html,
102
      body,
103
      #viewDiv {
104
        background-color: rgba(50, 50, 50, 1);
105
        height: 100%;
106
        margin: 0;
107
      }
108
    </style>
109
  </head>
110

111
  <body>
112
    <div id="viewDiv"></div>
113
  </body>
114
</html>

Scale-aware visualizations

Overview

LayerList widget with actions

Sample Code

API support

The following table describes the geometry and view types that are suited well for each visualization technique.

	2D	Lines	Polygons	Client-side	Server-side
Clustering
Binning
Heatmap
Opacity
Bloom
Aggregation
Thinning	¹	¹	¹	²	³
Visible scale range

Full SupportPartial SupportNo Support

Feature reduction selection not supported
Only by feature reduction selection
Only by scale-driven filter

High density dataThinning 3D visualizationIntroduction