MapLibre GL JS Compatibility
MapLibre GL JS Compatibility
Vector tile support via ShumateVectorRenderer is based on the MapLibre GL JS style
specification.
A style is a JSON document describing the vector data source and the layers
that are drawn to render the map. It includes a JSON-based expression format
that allows style authors to do a wide range of data-based styling.
Not all of the features in the spec are implemented in libshumate, and some features have important differences. These differences are described here.
Rasterization
The most important architectural difference between MapLibre GL JS and libshumate is that, while MapLibre uses WebGL to render vector data directly to the screen, libshumate rasterizes the tiles first. This has broad effects because once a tile is rendered, its pixel contents do not change as you zoom.
Style Root
| bearing | ❌ Not supported |
| center | ❌ Not supported |
| glyphs | ❌ Not supported. Text is drawn using Pango and the system fonts. |
| layers | ✅ Supported |
| light | ❌ Not supported |
| name | ✅ Supported |
| pitch | ❌ Not supported |
| sources | ✅ Supported, but see caveats below |
| sprite | ❌ Not supported. Sprite sheets are set using ShumateVectorRenderer:sprite-sheet.
Only one sprite sheet may be used. |
| terrain | ❌ Not supported |
| transition | ❌ Not supported |
| version | ❌ Not supported |
| zoom | ❌ Not supported |
Sources
Exactly one source must be provided. Only vector sources are supported;
for raster maps, use ShumateRasterRenderer. TileJSON URLs via the
“url” property are not supported.
vector
| attribution | ❌ Not supported. Use ShumateMapSource:license and ShumateMapSource:license-uri instead. |
| bounds | ❌ Not supported |
| maxzoom | ✅ Supported |
| minzoom | ✅ Supported |
| promoteId | ❌ Not supported |
| scheme | ❌ Not supported |
| tiles | ✅ Supported |
| url | ❌ Not supported. The stylesheet will fail to parse if this property is present. |
| volatile | ❌ Not supported |
Layers
| filter | ✅ Supported |
| id | ✅ Supported |
| maxzoom | ✅ Supported |
| minzoom | ✅ Supported |
| source | ❌ Not supported. ShumateVectorRenderer only supports a single data source, so this property is ignored. |
| source-layer | ✅ Supported |
| type | ✅ Supported |
background
| background-color | ✅ Supported |
| background-opacity | ✅ Supported |
| background-pattern | ❌ Not supported |
| visibility | ❌ Not supported |
fill
| fill-antialias | ❌ Not supported |
| fill-color | ✅ Supported |
| fill-opacity | ✅ Supported |
| fill-outline-color | ❌ Not supported |
| fill-pattern | ✅ Supported |
| fill-sort-key | ❌ Not supported |
| fill-translate | ❌ Not supported |
| fill-translate-anchor | ❌ Not supported |
| visibility | ❌ Not supported |
line
| line-blur | ❌ Not supported |
| line-cap | ✅ Supported |
| line-color | ✅ Supported |
| line-dasharray | Supported, but does not support expressions. |
| line-gap-width | ❌ Not supported |
| line-gradient | ❌ Not supported |
| line-join | ✅ Supported |
| line-miter-limit | ❌ Not supported |
| line-offset | ❌ Not supported |
| line-opacity | ✅ Supported |
| line-pattern | ❌ Not supported |
| line-round-limit | ❌ Not supported |
| line-sort-key | ❌ Not supported |
| line-translate | ❌ Not supported |
| line-translate-anchor | ❌ Not supported |
| line-width | ✅ Supported |
| visibility | ❌ Not supported |
symbol
Symbols are rendered using Pango and system fonts, not the glyphs defined in the spec.
| icon-allow-overlap | ✅ Supported |
| icon-anchor | ✅ Supported |
| icon-color | ✅ Supported. Only works for symbolic icons. |
| icon-halo-blur | ❌ Not supported |
| icon-halo-color | ❌ Not supported |
| icon-halo-width | ❌ Not supported |
| icon-ignore-placement | ✅ Supported |
| icon-image | ✅ Supported |
| icon-keep-upright | ❌ Not supported |
| icon-offset | Expressions are not supported. |
| icon-opacity | ✅ Supported |
| icon-optional | ✅ Supported |
| icon-overlap | ✅ Supported |
| icon-padding | ✅ Supported |
| icon-pitch-alignment | ❌ Not supported |
| icon-rotate | ✅ Supported |
| icon-rotation-alignment | ✅ Supported |
| icon-size | ✅ Supported |
| icon-text-fit | ❌ Not supported |
| icon-text-fit-padding | ❌ Not supported |
| icon-translate | ❌ Not supported |
| icon-translate-anchor | ❌ Not supported |
| symbol-avoid-edges | ❌ Not supported |
| symbol-placement | “line-center” is treated like “line”. |
| symbol-sort-key | ✅ Supported |
| symbol-spacing | ✅ Supported |
| symbol-z-order | ❌ Not supported |
| text-allow-overlap | ✅ Supported |
| text-anchor | Not supported when glyphs are positioned along a line geometry. |
| text-color | ✅ Supported |
| text-field | ✅ Supported |
| text-font | Expressions are not supported. Fallback fonts are not handled correctly. |
| text-halo-blur | ❌ Not supported |
| text-halo-color | ❌ Not supported |
| text-halo-width | ❌ Not supported |
| text-ignore-placement | ✅ Supported |
| text-justify | ❌ Not supported |
| text-keep-upright | ✅ Supported |
| text-letter-spacing | ✅ Supported |
| text-line-height | ❌ Not supported |
| text-max-angle | ❌ Not supported |
| text-max-width | ❌ Not supported |
| text-offset | Not supported when glyphs are positioned along a line geometry. Expressions are not supported. |
| text-opacity | ✅ Supported |
| text-optional | ✅ Supported |
| text-overlap | ✅ Supported |
| text-padding | ✅ Supported |
| text-pitch-alignment | ❌ Not supported |
| text-radial-offset | ❌ Not supported |
| text-rotate | ❌ Not supported |
| text-rotation-alignment | ✅ Supported |
| text-size | ✅ Supported |
| text-transform | ✅ Supported |
| text-translate | ❌ Not supported |
| text-translate-anchor | ❌ Not supported |
| text-variable-anchor | ❌ Not supported |
| text-writing-mode | ❌ Not supported |
| visibility | ❌ Not supported |
raster
❌ Not supported. Use ShumateRasterRenderer instead.
circle
❌ Not supported
fill-extrusion
❌ Not supported
heatmap
❌ Not supported
hillshade
❌ Not supported
Expressions
Unlike MapLibre GL JS, libshumate does not check expression types when the style is parsed, only when they are evaluated.
Due to limitations in libshumate’s rendering pipeline, all expressions are evaluated at integer zoom levels only.
Types
| array | ❌ Not supported. The expression engine in libshumate does not perform ahead-of-time type checking. |
| boolean | ❌ Not supported. The expression engine in libshumate does not perform ahead-of-time type checking. |
| collator | Only the case-sensitive property is supported. The locale property is always set to the current locale and may not be changed. |
| format | The text-font style override property is not supported. |
| image | ✅ Supported |
| literal | Only array literals are supported, not objects. |
| number | ❌ Not supported. The expression engine in libshumate does not perform ahead-of-time type checking. |
| number-format | ❌ Not supported |
| object | ❌ Not supported. The expression engine in libshumate does not perform ahead-of-time type checking. |
| string | ❌ Not supported. The expression engine in libshumate does not perform ahead-of-time type checking. |
| to-boolean | ✅ Supported |
| to-color | ✅ Supported |
| to-number | ✅ Supported |
| to-string | ✅ Supported |
| typeof | ✅ Supported. Arrays always return “array”, without information about the array’s elements like in MapLibre GL JS. Additionally, because libshumate’s type system is less static than MapLibre GL JS’s, results may differ in some (likely not common) cases. |
Feature data
| accumulated | ❌ Not supported |
| feature-state | ❌ Not supported |
| geometry-type | ✅ Supported |
| id | ✅ Supported |
| line-progress | ❌ Not supported |
| properties | ❌ Not supported |
Lookup
| at | ✅ Supported |
| get | The object argument is not supported. |
| has | The object argument is not supported. |
| in | Only supports arrays, not substring search. |
| index-of | ✅ Supported |
| length | ✅ Supported |
| slice | ✅ Supported |
Decision
| ! | ✅ Supported |
| != | ✅ Supported |
| < | ✅ Supported |
| <= | ✅ Supported |
| == | ✅ Supported |
| > | ✅ Supported |
| >= | ✅ Supported |
| all | ✅ Supported |
| any | ✅ Supported |
| case | ✅ Supported. The fallback argument is optional in libshumate; if no case matches, then the expression fails to evaluate. |
| coalesce | ✅ Supported. Arguments that fail to evaluate will be skipped rather than causing the entire expression to fail. |
| match | ✅ Supported. The fallback argument is optional in libshumate; if no case matches, then the expression fails to evaluate. |
| within | ❌ Not supported |
Ramps, scales, curves
| interpolate | Only linear and exponential interpolation is supported. |
| interpolate-hcl | ❌ Not supported |
| interpolate-lab | ❌ Not supported |
| step | ✅ Supported |
Variable binding
| let | ✅ Supported |
| var | ✅ Supported |
String
| concat | ✅ Supported |
| downcase | ✅ Supported |
| is-supported-script | ❌ Not supported |
| resolved-locale | ✅ Supported |
| upcase | ✅ Supported |
Color
| rgb | ❌ Not supported |
| rgba | ❌ Not supported |
| to-rgba | ❌ Not supported |
Math
| - (subtraction) | ✅ Supported |
| * (multiplication) | ✅ Supported |
| / (division) | ✅ Supported |
| % (remainder) | ✅ Supported |
| ^ (exponent) | ✅ Supported |
| + (sum) | ✅ Supported |
| abs | ✅ Supported |
| acos | ✅ Supported |
| asin | ✅ Supported |
| atan | ✅ Supported |
| ceil | ✅ Supported |
| cos | ✅ Supported |
| distance | ❌ Not supported |
| e | ✅ Supported |
| floor | ✅ Supported |
| ln | ✅ Supported |
| ln2 | ✅ Supported |
| log10 | ✅ Supported |
| log2 | ✅ Supported |
| max | ✅ Supported |
| min | ✅ Supported |
| pi | ✅ Supported |
| round | ✅ Supported |
| sin | ✅ Supported |
| sqrt | ✅ Supported |
| tan | ✅ Supported |
Zoom
✅ Supported. Zoom expressions are supported anywhere in libshumate, not just as the input to a top-level “step” or “interpolate” expression.
Heatmap
❌ Not supported