mlt-py 0.1.28

Python bindings for MapLibre Tile (MLT) format via PyO3
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

# mlt_py

Python bindings for the MapLibre Tile (MLT) format via [PyO3](https://pyo3.rs/).

## Decoding

```python
import maplibre_tiles

data = open("tile.mlt", "rb").read()

# Structured decode with geo-referencing
layers = maplibre_tiles.decode_mlt(data, z=14, x=8297, y=10749, tms=True)
for layer in layers:
    print(f"Layer: {layer.name}, extent: {layer.extent}")
    for feat in layer.features[:3]:
        print(f"  id={feat.id}, type={feat.geometry_type}")
        print(f"  wkb={len(feat.wkb)} bytes, props={dict(feat.properties)}")

# Raw tile-local coordinates (no z/x/y needed)
layers = maplibre_tiles.decode_mlt(data)

# GeoJSON string output (tile-local coords)
geojson_str = maplibre_tiles.decode_mlt_to_geojson(data)

# Fast layer listing (no full decode)
names = maplibre_tiles.list_layers(data)
```


## Decoded objects


`decode_mlt(...)` returns a list of `MltLayer` objects.
Each `MltLayer` represents one decoded MLT layer and exposes:
- `name: str` - the layer name.
- `extent: int` - the layer extent.
- `features: list[MltFeature]` - the decoded features in that layer.

Each `MltFeature` represents one decoded feature and exposes:
- `id: int | None` - the feature id, if present.
- `geometry_type: str` - the decoded geometry type.
- `wkb: bytes` - the geometry as WKB.
- `properties: dict` - the feature properties.


```python
import maplibre_tiles


layers = maplibre_tiles.decode_mlt(data)
for layer in layers:
    print(layer.name, layer.extent)
    for feature in layer.features[:2]:
        print(feature.id, feature.geometry_type, dict(feature.properties))
```


## Encoding


`encode_geojson(geojson, name, extent=4096, *, tessellate=False, sort="auto", shared_dict=True, fsst=True, fastpfor=True) -> bytes` encodes a single layer to an MLT blob.
- `geojson` is a GeoJSON [`FeatureCollection`](https://datatracker.ietf.org/doc/html/rfc7946#section-3.3).
  Geometry is in **tile-local coordinate space** (no projection), matching `tilezen/mapbox-vector-tile`'s default.
  Coordinates must be integers and 2D.
  They must be JSON integers (`2048`), not floats: a float-typed value such as `2048.0` raises `ValueError`.
- `name` and `extent` set the MLT layer metadata, since a `FeatureCollection` has no slot for them.
  `extent` defaults to `4096`.
- `tessellate` generates triangulation data for polygons and multi-polygons.
- `sort` controls which feature ordering(s) the encoder tries: `all`, `auto`, `morton`, `hilbert`, `id`, or `none`.
- `shared_dict` enables grouping strings into shared dictionaries.
- `fsst` enables FSST string compression.
- `fastpfor` enables FastPFOR integer compression.

`encode_mvt(data, *, tessellate=False, sort="auto", shared_dict=True, fsst=True, fastpfor=True) -> bytes` encodes an entire raw Mapbox Vector Tile (protobuf) to MLT using the same encoding options.


```python
import maplibre_tiles


blob = maplibre_tiles.encode_geojson(
    {
        "type": "FeatureCollection",
        "features": [
            {
                "type": "Feature",
                "id": 1,
                "geometry": {"type": "Point", "coordinates": },
                "properties": {"name": "main", "lanes": 3},
            },
        ],
    },
    name="roads",
    extent=4096,
)


# Multi-layer tiles -> encode each layer and concatenate the bytes
tile = b"".join([
    maplibre_tiles.encode_geojson(roads, name="roads"),
    maplibre_tiles.encode_geojson(water, name="water"),
])
```


```python
import maplibre_tiles


mvt = open("tile.mvt", "rb").read()

blob = maplibre_tiles.encode_mvt(mvt)


# With explicit encoding options
blob = maplibre_tiles.encode_mvt(
    mvt,
    tessellate=False,
    sort="auto",
    shared_dict=True,
    fsst=True,
    fastpfor=True,
)
```

Input is validated strictly.
A non-`FeatureCollection` input, a non-`Feature` member, float-typed or 3D coordinates, null or empty geometry, nested or non-scalar property values, a non-`u64` id, and an empty collection all raise `ValueError`.