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.