Skip to content

Scale and zoom

It is common for different rules to be applied at different zoom levels on a web map.

For example, on a roads layer, you would not want to display every single road when viewing the whole world. Or perhaps you may wish to styles the same features differently depending on the zoom level. For example: a cities layer styled using points at low zoom levels (when "zoomed out") and with polygon borders at higher zoom levels ("zoomed in").

Todo

ADD FIGURE

YSLD allows rules to be applied depending on the scale or zoom level. You can specify by scale, or you can define zoom levels in terms of scales and specify by zoom level.

Warning

Be aware that scales for a layer (where a style is applied) may interact differently when the layer is contained in a map, if the map has a different coordinate reference system from the layer.

Scale syntax

The syntax for using a scale conditional parameter in a rule is:

rules:
- ...
  scale: [<min>,<max>]
  ...

where:

Attribute Required? Description Default value
min Yes The minimum scale (inclusive) for which the rule will be applied. Value is a number, either decimal or integer. N/A
max Yes The maximum scale (exclusive) for which the rule will be applied. Value is a number, either decimal or integer. N/A

Note

It is not possible to use an expression for any of these values.

Use the literal strings min and max to denote where there are no lower or upper scale boundaries. For example, to denote that the scale is anything less than some <max> value:

scale: [min,<max>]

To denote that the scale is anything greater than or equal to some <min> value:

scale: [<min>,max]

Note

In the above examples, min and max are always literals, entered exactly like that, while <min> and <max> would be replaced by actual scalar values.

If the scale parameter is omitted entirely, then the rule will apply at all scales.

Scale examples

Three rules, all applicable at different scales:

rule:
- name: large_scale
  scale: [min,100000]
  symbolizers:
  - line:
      stroke-width: 3
      stroke-color: '#0165CD'
- name: medium_scale
  scale: [100000,200000]
  symbolizers:
  - line:
      stroke-width: 2
      stroke-color: '#0165CD'
- name: small_scale
  scale: [200000,max]
  symbolizers:
  - line:
      stroke-width: 1
      stroke-color: '#0165CD'

This example will display lines with:

  • A stroke width of 3 at scales less than 100,000 (large_scale)
  • A stroke width of 2 at scales between 100,000 and 200,000 (medium_scale)
  • A stroke width of 1 at scales greater than 200,000 (small_scale)

Given the rules above, the following arbitrary sample scales would map to the rules as follows:

Scale Rule
50000 large_scale
100000 medium_scale
150000 medium_scale
200000 small_scale
300000 small_scale

Note the edge cases, since the min value is inclusive and the max value is exclusive.

Scientific notation for scales

To make comprehension easier and to lessen the chance of errors, scale values can be expressed in scientific notation.

So a scale of 500000000, which is equal to 5 × 10\^8 (a 5 with eight zeros), can be replaced by 5e8.

Relationship between scale and zoom

When working with web maps, often it is more convenient to talk about zoom levels instead of scales. The relationship between zoom and scale is context dependent.

For example, for EPSG:4326 with world boundaries, zoom level 0 (completely zoomed out) corresponds to a scale of approximately 279,541,000 with each subsequent zoom level having half the scale value. For EPSG:3857 (Web Mercator) with world boundaries, zoom level 0 corresponds to a scale of approximately 559,082,000, again with each subsequent zoom level having half the scale value.

But since zoom levels are discrete (0, 1, 2, etc.) and scale levels are continuous, it's actually a range of scale levels that corresponds to a given zoom level.

For example, if you have a situation where a zoom level 0 corresponds to a scale of 1,000,000 (and each subsequent zoom level is half that scale, as is common), you can set the scale values of your rules to be:

  • scale: [750000,1500000] (includes 1,000,000)
  • scale: [340000,750000] (includes 500,000)
  • scale: [160000,340000] (includes 250,000)
  • scale: [80000,160000] (includes 125,000)
  • etc.

Also be aware of the inverse relationship between scale and zoom; as the zoom level increases, the scale decreases.

Zoom syntax

In certain limited cases, it can be more useful to specify scales by way of zoom levels for predefined gridsets. These can be any predefined gridsets in GeoServer.

Inside a rule, the syntax for using zoom levels is:

rules:
- ...
  zoom: [<min>, <max>]
  ...

where:

Attribute Required? Description Default value
min Yes The minimum zoom level for which the rule will be applied. Value is an integer. N/A
max Yes The maximum zoom level for which the rule will be applied. Value is an integer. N/A

Note

It is not possible to use an expression for any of these values.

As with scales, use the literal strings min and max to denote where there are no lower or upper scale boundaries. For example, to denote that the zoom level is anything less than some <max> value:

zoom: [min,<max>]

To denote that the zoom level is anything greater than or equal to some <min> value:

zoom: [<min>,max]

Note

In the above examples, min and max are always literals, entered exactly like that, while <min> and <max> would be replaced by actual scalar values.

The scale and zoom parameters should not be used together in a rule (but if used, scale takes priority over zoom).

Specifying a grid

While every web map can have zoom levels, the specific relationship between a zoom level and its scale is dependent on the gridset (spatial reference system, extent, etc.) used.

So when specifying zoom levels in YSLD, you should also specify the grid.

The grid parameter should remain at the top of the YSLD content, above any Feature Styles or Rules. The syntax is:

grid:
  name: <string>

where:

Property Required? Description Default value
name No WGS84, WebMercator, or a name of a predefined gridset in GeoServer. WebMercator

Note

As many web maps use "web mercator" (also known as EPSG:3857 or EPSG:900913), this is assumed to be the default if no grid is specified.

Warning

As multiple gridsets can contain the same SRS, we recommend naming custom gridsets by something other than the EPSG code.

Zoom examples

Default gridset

Given the default of web mercator (also known as EPSG:3857 or EPSG:900913), which requires no grid designation, this defines zoom levels as the following scale levels (rounded to the nearest whole number below):

Scale Zoom level
559082264 0
279541132 1
139770566 2
69885283 3
34942641 4
17471321 5
8735660 6
4367830 7
2183915 8
<previous_scale> / 2 <previous_zoom> + 1

Named gridsets

For the existing gridset of WGS84 (often known as EPSG:4326):

grid:
  name: WGS84

This defines zoom levels as the following scale levels (rounded to the nearest whole number below):

Scale Zoom level
559082264 0
279541132 1
139770566 2
69885283 3
34942641 4
17471321 5
8735660 6
4367830 7
2183915 8
<previous_scale> / 2 <previous_zoom> + 1

Given a custom named gridset called NYLongIslandFtUS, defined by a CRS of EPSG:2263 and using its full extent:

grid:
  name: NYLongIslandFtUS

This defines zoom levels as the following (rounded to the nearest whole number below):

Scale Zoom level
4381894 0
2190947 1
1095473 2
547736 3
273868 4
136934 5
68467 6
34234 7
17117 8
<previous_scale> / 2 <previous_zoom> + 1

Note

These scale values can be verified in GeoServer on the Gridsets page under the definition for the gridset:

Gridset defined in GeoServer

Specifically, note the Scale values under Tile Matrix Set.