Scale and zoom¶

Scale syntax¶

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

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

where:

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]

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:

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:

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]

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:

Zoom examples¶

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.