MLT tileset loading exception, maplibre-gl 5.15.0

[jsorel]

Environement : maplibre-gl 5.15.0

Hello,

I create a tileset of MLT tiles using maplibre java code.
No exception or warning where raised when creating the dataset.

But when trying to display it I have the following errors :

When using MVT format it displays correctly without errors.

I have try with Examind-SDK in MVT or MLT format at it displays correctly too.

So I believe there is an issue in maplibre-gl.
Or if it's not the case, at least the exception should be more revelant.

To reproduce the issue :

Here is a minimalist tileset with the problem :

dataset_mlt.zip

to run is open a terminal, and run in the folder npx http-server -o .
then open page http://127.0.0.1:8080/maplibre.html

Thanks

[HarelM]

I think your tilejson is incorrect, it should state "encoding: mlt" and not "format: mlt".
But that was a very shallow check.
You can see how this works in the demotiles and how the tile json is defined there.

[jsorel]

The error message is a bit better now.

So it seems maplibre.gl has some important limitations in it's MLT support.

About the encoding property, where is that defined ?

I made a full binding of the tileset.json following all the mapbox/maplibre specification from version 1.0.0 to 3.0.0, everything I could find and the encoding property is never mentioned.

• https://github.com/mapbox/tilejson-spec/tree/master/3.0.0
• https://docs.mapbox.com/help/glossary/tilejson/
• https://maplibre.org/maplibre-tile-spec/specification/#21-metadata
• https://maplibre.org/maplibre-tile-spec/assets/spec/mlt_tileset_metadata.json

/**
 * MapBox/Maplibre tileset definition.
 *
 * @author Johann Sorel (Geomatys)
 * @see https://github.com/mapbox/tilejson-spec/tree/master/3.0.0
 * @see https://docs.mapbox.com/help/glossary/tilejson/
 * @see https://maplibre.org/maplibre-tile-spec/specification/#21-metadata
 * @see https://maplibre.org/maplibre-tile-spec/assets/spec/mlt_tileset_metadata.json
 */
public class Tileset extends DataTransferObject{

    public static final String TILEJSON_V100 = "1.0.0";
    public static final String TILEJSON_V200 = "2.0.0";
    public static final String TILEJSON_V201 = "2.0.1";
    public static final String TILEJSON_V210 = "2.1.0";
    public static final String TILEJSON_V220 = "2.2.0";
    public static final String TILEJSON_V300 = "3.0.0";

    public static final String SCHEME_XYZ = "xyz";
    public static final String SCHEME_TMS = "tms";

    /////////////////////////////////////////////
    //properties defined in mapbox tilejson 1.0.0
    /////////////////////////////////////////////

    /**
     * REQUIRED. String.
     * <br>
     * A semver.org style version number as a string.
     * Describes the version of the TileJSON spec that is implemented by this JSON object.
     */
    @JsonProperty("tilejson")
    public String tilejson = TILEJSON_V300;

    /**
     * OPTIONAL. String. Default: null.
     * <br>
     * A name describing the set of tiles. The name can contain any legal character.
     * Implementations SHOULD NOT interpret the name as HTML.
     */
    @JsonProperty("name")
    public String name;

    /**
     * OPTIONAL. String. Default: null.
     * <br>
     * A text description of the set of tiles. The description can contain any valid unicode character as described
     * by the JSON specification RFC 8259.
     */
    @JsonProperty("description")
    public String description;

    /**
     * OPTIONAL. String. Default: "1.0.0".
     * <br>
     * A semver.org style version number of the tiles. When changes across tiles are introduced the minor version MUST change.
     * This may lead to cut off labels.
     * Therefore, implementors can decide to clean their cache when the minor version changes.
     * Changes to the patch level MUST only have changes to tiles that are contained within one tile.
     * When tiles change significantly, such as updating a vector tile layer name, the major version MUST be increased.
     * Implementations MUST NOT use tiles with different major versions.
     */
    @JsonProperty("version")
    public String version;

    /**
     * OPTIONAL. String. Default: null.
     * <br>
     * Contains an attribution to be displayed when the map is shown to a user.
     * Implementations MAY decide to treat this as HTML or literal text.
     * For security reasons, make absolutely sure that this content can't be abused as a vector for XSS or beacon tracking.
     */
    @JsonProperty("attribution")
    public String attribution;

    /**
     * OPTIONAL. Default: null.
     * <br>
     * Contains a javascript function to be used to format data from grids for interaction.
     * See https://github.com/mapbox/mbtiles-spec/blob/master/1.1/interaction.md for the interactivity specification.
     *
     * @deprecated removed in 2.0.0
     */
    @Deprecated
    @JsonProperty("formatter")
    public String formatter;

    /**
     * OPTIONAL. String. Default: null.
     * <br>
     * Contains a legend to be displayed with the map.
     * Implementations MAY decide to treat this as HTML or literal text. For security reasons,
     * make absolutely sure that this field can't be abused as a vector for XSS or beacon tracking.
     */
    @JsonProperty("legend")
    public String legend;

    /**
     * OPTIONAL. String. Default: "xyz".
     * <br>
     * Either "xyz" or "tms". Influences the y direction of the tile coordinates.
     * The global-mercator (aka Spherical Mercator) profile is assumed.
     */
    @JsonProperty("scheme")
    public String scheme = SCHEME_XYZ;

    /**
     * REQUIRED. Array.
     * <br>
     * An array of tile endpoints. {z}, {x} and {y}, if present, are replaced with the corresponding integers.
     * If multiple endpoints are specified, clients may use any combination of endpoints.
     * All endpoint urls MUST be absolute. All endpoints MUST return the same content for the same URL.
     * The array MUST contain at least one endpoint. The tile extension is NOT limited to any particular format.
     * Some of the more popular are: mvt, vector.pbf, png, webp, and jpg.
     */
    @JsonProperty("tiles")
    public String[] tiles = new String[0];

    /**
     * OPTIONAL. Array. Default: [].
     * <br>
     * An array of interactivity endpoints. {z}, {x} and {y}, if present, are replaced with the corresponding integers.
     * If multiple endpoints are specified, clients may use any combination of endpoints.
     * All endpoints MUST return the same content for the same URL.
     * If the array doesn't contain any entries, UTF-Grid interactivity is not supported for this set of tiles.
     * See https://github.com/mapbox/utfgrid-spec/tree/master/1.2 for the interactivity specification.
     * <br>
     * Note: UTF-Grid interactivity predates GL-based map rendering and interaction.
     * Map interactivity is now generally defined outside the TileJSON specification and is dependent on the
     * tile rendering library's features.
     */
    @JsonProperty("grids")
    public String[] grids;

    /**
     * OPTIONAL. Integer. Default: 0.
     * <br>
     * An integer specifying the minimum zoom level. MUST be in range: 0 <= minzoom <= maxzoom <= 30.
     */
    @JsonProperty("minzoom")
    public Integer minzoom;

    /**
     * OPTIONAL. Integer. Default: 30.
     * <br>
     * An integer specifying the maximum zoom level.
     * MUST be in range: 0 <= minzoom <= maxzoom <= 30.
     * A client or server MAY request tiles outside the zoom range, but the availability of these tiles is
     * dependent on how the tile server or renderer handles the request (such as overzooming tiles).
     */
    @JsonProperty("maxzoom")
    public Integer maxzoom;

    /**
     * OPTIONAL. Array. Default: [ -180, -85.05112877980659, 180, 85.0511287798066 ] (xyz-compliant tile bounds)
     * <br>
     * The maximum extent of available map tiles.
     * Bounds MUST define an area covered by all zoom levels.
     * The bounds are represented in WGS 84 latitude and longitude values, in the order left, bottom, right, top.
     * Values may be integers or floating point numbers.
     * The minimum/maximum values for longitude and latitude are -180/180 and -90/90 respectively.
     * Bounds MUST NOT "wrap" around the ante-meridian.
     * If bounds are not present, the default value MAY assume the set of tiles is globally distributed.
     * <br>
     * Bounds where longitude values are the same, and latitude values are the same, are considered valid.
     * This case typically represents a single point geometry in the entire tileset.
     */
    @JsonProperty("bounds")
    @JsonInclude(Include.NON_EMPTY)
    public double[] bounds = new double[0];

    /**
     * OPTIONAL. Array. Default: null.
     * <br>
     * The first value is the longitude, the second is latitude (both in WGS:84 values), the third value is the zoom level as an integer.
     * Longitude and latitude MUST be within the specified bounds.
     * The zoom level MUST be between minzoom and maxzoom.
     * Implementations MAY use this center value to set the default location.
     * If the value is null, implementations MAY use their own algorithm for determining a default location.
     */
    @JsonProperty("center")
    public double[] center;

    /////////////////////////////////////////////
    //properties defined in mapbox tilejson 2.0.0
    /////////////////////////////////////////////

    /**
     * OPTIONAL. String. Default: null.
     * <br>
     * Contains a mustache template to be used to format data from grids for interaction.
     * See https://github.com/mapbox/utfgrid-spec/tree/master/1.2 for the interactivity specification.
     */
    @JsonProperty("template")
    public String template;

    /////////////////////////////////////////////
    //properties defined in mapbox tilejson 2.0.1
    /////////////////////////////////////////////

    /**
     * OPTIONAL. Default: 4
     * <br>
     * The pixel resolution of grids, if available, in px/grid square
     *
     * @deprecated added in 2.0.1, removed in 2.2.0
     */
    @Deprecated
    @JsonProperty("resolution")
    public Integer resolution;

    /////////////////////////////////////////////
    //properties defined in mapbox tilejson 2.1.0
    /////////////////////////////////////////////

    /**
     * OPTIONAL. Array. Default: [].
     * <br>
     * An array of data files in GeoJSON format. {z}, {x} and {y}, if present, are replaced with the corresponding integers.
     * If multiple endpoints are specified, clients may use any combination of endpoints.
     * All endpoints MUST return the same content for the same URL.
     * If the array doesn't contain any entries, then no data is present in the map.
     * This field is for overlaying GeoJSON data on tiled raster maps and is generally no longer used for GL-based maps.
     */
    @JsonProperty("data")
    public String[] data;

    /////////////////////////////////////////////
    //properties defined in mapbox tilejson 3.0.0
    /////////////////////////////////////////////

    /**
     * REQUIRED. Array.
     *
     * An array of objects. Each object describes one layer of vector tile data.
     * A vector_layer object MUST contain the id and fields keys, and MAY contain the description, minzoom, or maxzoom keys.
     * An implementation MAY include arbitrary keys in the object outside those defined in this specification.
     * <br>
     * Note: When describing a set of raster tiles or other tile format that does not have a "layers"
     * concept (i.e. "format": "jpeg"), the vector_layers key is not required.
     */
    @JsonProperty("vector_layers")
    public VectorLayer[] vector_layers = new VectorLayer[0];

    /**
     * OPTIONAL. Integer. Default: null.
     * <br>
     * An integer specifying the zoom level from which to generate overzoomed tiles.
     * Implementations MAY generate overzoomed tiles from parent tiles if the requested zoom level does not exist.
     * In most cases, overzoomed tiles are generated from the maximum zoom level of the set of tiles.
     * If fillzoom is specified, the overzoomed tile MAY be generated from the fillzoom level.
     * <br>
     * For example, in a set of tiles with maxzoom 10 and no fillzoom specified,
     * a request for a z11 tile will use the z10 parent tiles to generate the new, overzoomed z11 tile.
     * If the same TileJSON object had fillzoom specified at z7, a request for a z11 tile would use the z7 tile instead of z10.
     * <br>
     * While TileJSON may specify rules for overzooming tiles, it is ultimately up to the tile serving client
     * or renderer to implement overzooming.
     */
    @JsonProperty("fillzoom")
    public Integer fillzoom;

    ////////////////////////////////////////////////////
    //properties found in maplibre files, not documented
    ////////////////////////////////////////////////////

    /**
     * The tiles format.
     *
     * examples : pdf, jpg, png
     * example for cesium terrain : heightmap-1.0, quantized-mesh-1.0
     */
    @JsonProperty("format")
    public String format;

    /**
     * Not sure what this is ... related to the projection.
     *
     * examples : mercator
     */
    @JsonProperty("profile")
    public String profile;

    /**
     * Tool name which generated those tiles.
     */
    @JsonProperty("generator")
    public String generator;

    /**
     * Coordinate reference system identifier.
     *
     * example : EPSG:3857
     */
    @JsonProperty("crs")
    public String crs;

    /**
     * Coordinate reference system in WKT.
     * Seems to be WKT-1.
     */
    @JsonProperty("crs_wkt")
    public String crs_wkt;

    /**
     * Similar to the bounds property but is defined in the CRS units.
     */
    @JsonProperty("extent")
    @JsonInclude(Include.NON_EMPTY)
    public double[] extent;

[jsorel]

related : maplibre/maplibre-tile-spec#756

[HarelM]

This is not defined in tilejson spec unfortunately, but it is defined in the style spec, and tilejson is somewhat of a superset of that in theory...

[HarelM]

FastPfor is still missing implementation indeed, I would recommend encoding the tiles without it for now.

[jsorel]

This is not defined in tilejson spec unfortunately, but it is defined in the style spec, and tilejson is somewhat of a superset of that in theory...

Do you have a link ?

FastPfor is still missing implementation indeed, I would recommend encoding the tiles without it for now.

I disabled it, so I have no more errors, but still don't see anything.

maplibre.zip

[HarelM]

I don't have the bandwidth to debug this further, sorry...

[HarelM]

Encoding is described here:
https://maplibre.org/maplibre-style-spec/sources/#encoding