martin_tile_utils/
lib.rs

1#![doc = include_str!("../README.md")]
2
3// This code was partially adapted from https://github.com/maplibre/mbtileserver-rs
4// project originally written by Kaveh Karimi and licensed under MIT/Apache-2.0
5
6use std::f64::consts::PI;
7use std::fmt::{Display, Formatter, Result};
8
9/// circumference of the earth in meters
10pub const EARTH_CIRCUMFERENCE: f64 = 40_075_016.685_578_5;
11/// radius of the earth in meters
12pub const EARTH_RADIUS: f64 = EARTH_CIRCUMFERENCE / 2.0 / PI;
13
14pub const MAX_ZOOM: u8 = 30;
15
16mod decoders;
17pub use decoders::*;
18
19#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
20pub struct TileCoord {
21    pub z: u8,
22    pub x: u32,
23    pub y: u32,
24}
25
26pub type TileData = Vec<u8>;
27pub type Tile = (TileCoord, Option<TileData>);
28
29impl Display for TileCoord {
30    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
31        if f.alternate() {
32            write!(f, "{}/{}/{}", self.z, self.x, self.y)
33        } else {
34            write!(f, "{},{},{}", self.z, self.x, self.y)
35        }
36    }
37}
38
39impl TileCoord {
40    /// Checks provided coordinates for validity
41    /// before constructing [`TileCoord`] instance.
42    ///
43    /// Check [`Self::new_unchecked`] if you are sure that your inputs are possible.
44    #[must_use]
45    pub fn new_checked(z: u8, x: u32, y: u32) -> Option<TileCoord> {
46        Self::is_possible_on_zoom_level(z, x, y).then_some(Self { z, x, y })
47    }
48
49    /// Constructs [`TileCoord`] instance from arguments without checking that the tiles can exist.
50    ///
51    /// Check [`Self::new_checked`] if you are unsure if your inputs are possible.
52    #[must_use]
53    pub fn new_unchecked(z: u8, x: u32, y: u32) -> TileCoord {
54        Self { z, x, y }
55    }
56
57    /// Checks that zoom `z` is plausibily small and `x`/`y` is possible on said zoom level
58    #[must_use]
59    pub fn is_possible_on_zoom_level(z: u8, x: u32, y: u32) -> bool {
60        if z > MAX_ZOOM {
61            return false;
62        }
63
64        let side_len = 1_u32 << z;
65        x < side_len && y < side_len
66    }
67}
68
69#[derive(Clone, Copy, Debug, PartialEq, Eq)]
70pub enum Format {
71    Gif,
72    Jpeg,
73    Json,
74    Mvt,
75    Png,
76    Webp,
77}
78
79impl Format {
80    #[must_use]
81    pub fn parse(value: &str) -> Option<Self> {
82        Some(match value.to_ascii_lowercase().as_str() {
83            "gif" => Self::Gif,
84            "jpg" | "jpeg" => Self::Jpeg,
85            "json" => Self::Json,
86            "pbf" | "mvt" => Self::Mvt,
87            "png" => Self::Png,
88            "webp" => Self::Webp,
89            _ => None?,
90        })
91    }
92
93    /// Get the `format` value as it should be stored in the `MBTiles` metadata table
94    #[must_use]
95    pub fn metadata_format_value(self) -> &'static str {
96        match self {
97            Self::Gif => "gif",
98            Self::Jpeg => "jpeg",
99            Self::Json => "json",
100            // QGIS uses `pbf` instead of `mvt` for some reason
101            Self::Mvt => "pbf",
102            Self::Png => "png",
103            Self::Webp => "webp",
104        }
105    }
106
107    #[must_use]
108    pub fn content_type(&self) -> &str {
109        match *self {
110            Self::Gif => "image/gif",
111            Self::Jpeg => "image/jpeg",
112            Self::Json => "application/json",
113            Self::Mvt => "application/x-protobuf",
114            Self::Png => "image/png",
115            Self::Webp => "image/webp",
116        }
117    }
118
119    #[must_use]
120    pub fn is_detectable(self) -> bool {
121        match self {
122            Self::Png | Self::Jpeg | Self::Gif | Self::Webp => true,
123            // TODO: Json can be detected, but currently we only detect it
124            //       when it's not compressed, so to avoid a warning, keeping it as false for now.
125            //       Once we can detect it inside a compressed data, change it to true.
126            Self::Mvt | Self::Json => false,
127        }
128    }
129}
130
131impl Display for Format {
132    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
133        f.write_str(match *self {
134            Self::Gif => "gif",
135            Self::Jpeg => "jpeg",
136            Self::Json => "json",
137            Self::Mvt => "mvt",
138            Self::Png => "png",
139            Self::Webp => "webp",
140        })
141    }
142}
143
144#[derive(Clone, Copy, Debug, Hash, PartialEq, Eq)]
145pub enum Encoding {
146    /// Data is not compressed, but it can be
147    Uncompressed = 0b0000_0000,
148    /// Some formats like JPEG and PNG are already compressed
149    Internal = 0b0000_0001,
150    Gzip = 0b0000_0010,
151    Zlib = 0b0000_0100,
152    Brotli = 0b0000_1000,
153    Zstd = 0b0001_0000,
154}
155
156impl Encoding {
157    #[must_use]
158    pub fn parse(value: &str) -> Option<Self> {
159        Some(match value.to_ascii_lowercase().as_str() {
160            "none" => Self::Uncompressed,
161            "gzip" => Self::Gzip,
162            "zlib" => Self::Zlib,
163            "brotli" => Self::Brotli,
164            "zstd" => Self::Zstd,
165            _ => None?,
166        })
167    }
168
169    #[must_use]
170    pub fn content_encoding(&self) -> Option<&str> {
171        match *self {
172            Self::Uncompressed | Self::Internal => None,
173            Self::Gzip => Some("gzip"),
174            Self::Zlib => Some("deflate"),
175            Self::Brotli => Some("br"),
176            Self::Zstd => Some("zstd"),
177        }
178    }
179
180    #[must_use]
181    pub fn is_encoded(self) -> bool {
182        match self {
183            Self::Uncompressed | Self::Internal => false,
184            Self::Gzip | Self::Zlib | Self::Brotli | Self::Zstd => true,
185        }
186    }
187}
188
189#[derive(Clone, Copy, Debug, PartialEq, Eq)]
190pub struct TileInfo {
191    pub format: Format,
192    pub encoding: Encoding,
193}
194
195impl TileInfo {
196    #[must_use]
197    pub fn new(format: Format, encoding: Encoding) -> Self {
198        Self { format, encoding }
199    }
200
201    /// Try to figure out the format and encoding of the raw tile data
202    #[must_use]
203    #[allow(clippy::enum_glob_use)]
204    pub fn detect(value: &[u8]) -> Option<Self> {
205        use Encoding::*;
206        use Format::*;
207
208        // TODO: Make detection slower but more accurate:
209        //  - uncompress gzip/zlib/... and run detection again. If detection fails, assume MVT
210        //  - detect json inside a compressed data
211        //  - json should be fully parsed
212        //  - possibly keep the current `detect()` available as a fast path for those who may need it
213        Some(match value {
214            // Compressed prefixes assume MVT content
215            v if v.starts_with(b"\x1f\x8b") => Self::new(Mvt, Gzip),
216            v if v.starts_with(b"\x78\x9c") => Self::new(Mvt, Zlib),
217            v if v.starts_with(b"\x89\x50\x4E\x47\x0D\x0A\x1A\x0A") => Self::new(Png, Internal),
218            v if v.starts_with(b"\x47\x49\x46\x38\x39\x61") => Self::new(Gif, Internal),
219            v if v.starts_with(b"\xFF\xD8\xFF") => Self::new(Jpeg, Internal),
220            v if v.starts_with(b"RIFF") && v.len() > 8 && v[8..].starts_with(b"WEBP") => {
221                Self::new(Webp, Internal)
222            }
223            v if v.starts_with(b"{") => Self::new(Json, Uncompressed),
224            _ => None?,
225        })
226    }
227
228    #[must_use]
229    pub fn encoding(self, encoding: Encoding) -> Self {
230        Self { encoding, ..self }
231    }
232}
233
234impl From<Format> for TileInfo {
235    fn from(format: Format) -> Self {
236        Self::new(
237            format,
238            match format {
239                Format::Png | Format::Jpeg | Format::Webp | Format::Gif => Encoding::Internal,
240                Format::Mvt | Format::Json => Encoding::Uncompressed,
241            },
242        )
243    }
244}
245
246impl Display for TileInfo {
247    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
248        write!(f, "{}", self.format.content_type())?;
249        if let Some(encoding) = self.encoding.content_encoding() {
250            write!(f, "; encoding={encoding}")?;
251        } else if self.encoding != Encoding::Uncompressed {
252            f.write_str("; uncompressed")?;
253        }
254        Ok(())
255    }
256}
257
258/// Convert longitude and latitude to a tile (x,y) coordinates for a given zoom
259#[must_use]
260#[allow(clippy::cast_possible_truncation)]
261#[allow(clippy::cast_sign_loss)]
262pub fn tile_index(lng: f64, lat: f64, zoom: u8) -> (u32, u32) {
263    let tile_size = EARTH_CIRCUMFERENCE / f64::from(1_u32 << zoom);
264    let (x, y) = wgs84_to_webmercator(lng, lat);
265    let col = (((x - (EARTH_CIRCUMFERENCE * -0.5)).abs() / tile_size) as u32).min((1 << zoom) - 1);
266    let row = ((((EARTH_CIRCUMFERENCE * 0.5) - y).abs() / tile_size) as u32).min((1 << zoom) - 1);
267    (col, row)
268}
269
270/// Convert min/max XYZ tile coordinates to a bounding box values.
271///
272/// The result is `[min_lng, min_lat, max_lng, max_lat]`
273///
274/// # Panics
275/// Panics if `zoom` is greater than [`MAX_ZOOM`].
276#[must_use]
277pub fn xyz_to_bbox(zoom: u8, min_x: u32, min_y: u32, max_x: u32, max_y: u32) -> [f64; 4] {
278    assert!(zoom <= MAX_ZOOM, "zoom {zoom} must be <= {MAX_ZOOM}");
279
280    let tile_length = EARTH_CIRCUMFERENCE / f64::from(1_u32 << zoom);
281
282    let left_down_bbox = tile_bbox(min_x, max_y, tile_length);
283    let right_top_bbox = tile_bbox(max_x, min_y, tile_length);
284
285    let (min_lng, min_lat) = webmercator_to_wgs84(left_down_bbox[0], left_down_bbox[1]);
286    let (max_lng, max_lat) = webmercator_to_wgs84(right_top_bbox[2], right_top_bbox[3]);
287    [min_lng, min_lat, max_lng, max_lat]
288}
289
290#[allow(clippy::cast_lossless)]
291fn tile_bbox(x: u32, y: u32, tile_length: f64) -> [f64; 4] {
292    let min_x = EARTH_CIRCUMFERENCE * -0.5 + x as f64 * tile_length;
293    let max_y = EARTH_CIRCUMFERENCE * 0.5 - y as f64 * tile_length;
294
295    [min_x, max_y - tile_length, min_x + tile_length, max_y]
296}
297
298/// Convert bounding box to a tile box `(min_x, min_y, max_x, max_y)` for a given zoom
299#[must_use]
300pub fn bbox_to_xyz(left: f64, bottom: f64, right: f64, top: f64, zoom: u8) -> (u32, u32, u32, u32) {
301    let (min_col, min_row) = tile_index(left, top, zoom);
302    let (max_col, max_row) = tile_index(right, bottom, zoom);
303    (min_col, min_row, max_col, max_row)
304}
305
306/// Compute precision of a zoom level, i.e. how many decimal digits of the longitude and latitude are relevant
307#[must_use]
308#[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
309pub fn get_zoom_precision(zoom: u8) -> usize {
310    assert!(zoom < MAX_ZOOM, "zoom {zoom} must be <= {MAX_ZOOM}");
311    let lng_delta = webmercator_to_wgs84(EARTH_CIRCUMFERENCE / f64::from(1_u32 << zoom), 0.0).0;
312    let log = lng_delta.log10() - 0.5;
313    if log > 0.0 { 0 } else { -log.ceil() as usize }
314}
315
316/// transform [`WebMercator`](https://epsg.io/3857) to [WGS84](https://epsg.io/4326)
317// from https://github.com/Esri/arcgis-osm-editor/blob/e4b9905c264aa22f8eeb657efd52b12cdebea69a/src/OSMWeb10_1/Utils/WebMercator.cs
318#[must_use]
319pub fn webmercator_to_wgs84(x: f64, y: f64) -> (f64, f64) {
320    let lng = (x / EARTH_RADIUS).to_degrees();
321    let lat = f64::atan(f64::sinh(y / EARTH_RADIUS)).to_degrees();
322    (lng, lat)
323}
324
325/// transform [WGS84](https://epsg.io/4326) to [`WebMercator`](https://epsg.io/3857)
326// from https://github.com/Esri/arcgis-osm-editor/blob/e4b9905c264aa22f8eeb657efd52b12cdebea69a/src/OSMWeb10_1/Utils/WebMercator.cs
327#[must_use]
328pub fn wgs84_to_webmercator(lon: f64, lat: f64) -> (f64, f64) {
329    let x = lon * PI / 180.0 * EARTH_RADIUS;
330
331    let y_sin = lat.to_radians().sin();
332    let y = EARTH_RADIUS / 2.0 * ((1.0 + y_sin) / (1.0 - y_sin)).ln();
333
334    (x, y)
335}
336
337#[cfg(test)]
338mod tests {
339    #![allow(clippy::unreadable_literal)]
340
341    use std::fs::read;
342
343    use Encoding::{Internal, Uncompressed};
344    use Format::{Jpeg, Json, Png, Webp};
345    use approx::assert_relative_eq;
346    use rstest::rstest;
347
348    use super::*;
349
350    fn detect(path: &str) -> Option<TileInfo> {
351        TileInfo::detect(&read(path).unwrap())
352    }
353
354    #[allow(clippy::unnecessary_wraps)]
355    fn info(format: Format, encoding: Encoding) -> Option<TileInfo> {
356        Some(TileInfo::new(format, encoding))
357    }
358
359    #[test]
360    fn test_data_format_png() {
361        assert_eq!(detect("./fixtures/world.png"), info(Png, Internal));
362    }
363
364    #[test]
365    fn test_data_format_jpg() {
366        assert_eq!(detect("./fixtures/world.jpg"), info(Jpeg, Internal));
367    }
368
369    #[test]
370    fn test_data_format_webp() {
371        assert_eq!(detect("./fixtures/dc.webp"), info(Webp, Internal));
372        assert_eq!(TileInfo::detect(br"RIFF"), None);
373    }
374
375    #[test]
376    fn test_data_format_json() {
377        assert_eq!(
378            TileInfo::detect(br#"{"foo":"bar"}"#),
379            info(Json, Uncompressed)
380        );
381    }
382
383    #[rstest]
384    #[case(-180.0, 85.0511, 0, (0,0))]
385    #[case(-180.0, 85.0511, 1, (0,0))]
386    #[case(-180.0, 85.0511, 2, (0,0))]
387    #[case(0.0, 0.0, 0, (0,0))]
388    #[case(0.0, 0.0, 1, (1,1))]
389    #[case(0.0, 0.0, 2, (2,2))]
390    #[case(0.0, 1.0, 0, (0,0))]
391    #[case(0.0, 1.0, 1, (1,0))]
392    #[case(0.0, 1.0, 2, (2,1))]
393    fn test_tile_colrow(
394        #[case] lng: f64,
395        #[case] lat: f64,
396        #[case] zoom: u8,
397        #[case] expected: (u32, u32),
398    ) {
399        assert_eq!(
400            expected,
401            tile_index(lng, lat, zoom),
402            "{lng},{lat}@z{zoom} should be {expected:?}"
403        );
404    }
405
406    #[rstest]
407    // you could easily get test cases from maptiler: https://www.maptiler.com/google-maps-coordinates-tile-bounds-projection/#4/-118.82/71.02
408    #[case(0, 0, 0, 0, 0, [-180.0,-85.0511287798066,180.0,85.0511287798066])]
409    #[case(1, 0, 0, 0, 0, [-180.0,0.0,0.0,85.0511287798066])]
410    #[case(5, 1, 1, 2, 2, [-168.75,81.09321385260837,-146.25,83.97925949886205])]
411    #[case(5, 1, 3, 2, 5, [-168.75,74.01954331150226,-146.25,81.09321385260837])]
412    fn test_xyz_to_bbox(
413        #[case] zoom: u8,
414        #[case] min_x: u32,
415        #[case] min_y: u32,
416        #[case] max_x: u32,
417        #[case] max_y: u32,
418        #[case] expected: [f64; 4],
419    ) {
420        let bbox = xyz_to_bbox(zoom, min_x, min_y, max_x, max_y);
421        assert_relative_eq!(bbox[0], expected[0], epsilon = f64::EPSILON * 2.0);
422        assert_relative_eq!(bbox[1], expected[1], epsilon = f64::EPSILON * 2.0);
423        assert_relative_eq!(bbox[2], expected[2], epsilon = f64::EPSILON * 2.0);
424        assert_relative_eq!(bbox[3], expected[3], epsilon = f64::EPSILON * 2.0);
425    }
426
427    #[rstest]
428    #[case(0, (0, 0, 0, 0))]
429    #[case(1, (0, 1, 0, 1))]
430    #[case(2, (0, 3, 0, 3))]
431    #[case(3, (0, 7, 0, 7))]
432    #[case(4, (0, 14, 1, 15))]
433    #[case(5, (0, 29, 2, 31))]
434    #[case(6, (0, 58, 5, 63))]
435    #[case(7, (0, 116, 11, 126))]
436    #[case(8, (0, 233, 23, 253))]
437    #[case(9, (0, 466, 47, 507))]
438    #[case(10, (1, 933, 94, 1014))]
439    #[case(11, (3, 1866, 188, 2029))]
440    #[case(12, (6, 3732, 377, 4059))]
441    #[case(13, (12, 7465, 755, 8119))]
442    #[case(14, (25, 14931, 1510, 16239))]
443    #[case(15, (51, 29863, 3020, 32479))]
444    #[case(16, (102, 59727, 6041, 64958))]
445    #[case(17, (204, 119455, 12083, 129917))]
446    #[case(18, (409, 238911, 24166, 259834))]
447    #[case(19, (819, 477823, 48332, 519669))]
448    #[case(20, (1638, 955647, 96665, 1039339))]
449    #[case(21, (3276, 1911295, 193331, 2078678))]
450    #[case(22, (6553, 3822590, 386662, 4157356))]
451    #[case(23, (13107, 7645181, 773324, 8314713))]
452    #[case(24, (26214, 15290363, 1546649, 16629427))]
453    #[case(25, (52428, 30580726, 3093299, 33258855))]
454    #[case(26, (104857, 61161453, 6186598, 66517711))]
455    #[case(27, (209715, 122322907, 12373196, 133035423))]
456    #[case(28, (419430, 244645814, 24746393, 266070846))]
457    #[case(29, (838860, 489291628, 49492787, 532141692))]
458    #[case(30, (1677721, 978583256, 98985574, 1064283385))]
459    fn test_box_to_xyz(#[case] zoom: u8, #[case] expected_xyz: (u32, u32, u32, u32)) {
460        let actual_xyz = bbox_to_xyz(
461            -179.43749999999955,
462            -84.76987877980656,
463            -146.8124999999996,
464            -81.37446385260833,
465            zoom,
466        );
467        assert_eq!(
468            actual_xyz, expected_xyz,
469            "zoom {zoom} does not have te right xyz"
470        );
471    }
472
473    #[rstest]
474    // test data via https://epsg.io/transform#s_srs=4326&t_srs=3857
475    #[case((0.0,0.0), (0.0,0.0))]
476    #[case((30.0,0.0), (3339584.723798207,0.0))]
477    #[case((-30.0,0.0), (-3339584.723798207,0.0))]
478    #[case((0.0,30.0), (0.0,3503549.8435043753))]
479    #[case((0.0,-30.0), (0.0,-3503549.8435043753))]
480    #[case((38.897957,-77.036560), (4330100.766138651, -13872207.775755845))] // white house
481    #[case((-180.0,-85.0), (-20037508.342789244, -19971868.880408566))]
482    #[case((180.0,85.0), (20037508.342789244, 19971868.880408566))]
483    #[case((0.026949458523585632,0.08084834874097367), (3000.0, 9000.0))]
484    fn test_coordinate_syste_conversion(
485        #[case] wgs84: (f64, f64),
486        #[case] webmercator: (f64, f64),
487    ) {
488        // epsg produces the expected values with f32 precision, grrr..
489        let epsilon = f64::from(f32::EPSILON);
490
491        let actual_wgs84 = webmercator_to_wgs84(webmercator.0, webmercator.1);
492        assert_relative_eq!(actual_wgs84.0, wgs84.0, epsilon = epsilon);
493        assert_relative_eq!(actual_wgs84.1, wgs84.1, epsilon = epsilon);
494
495        let actual_webmercator = wgs84_to_webmercator(wgs84.0, wgs84.1);
496        assert_relative_eq!(actual_webmercator.0, webmercator.0, epsilon = epsilon);
497        assert_relative_eq!(actual_webmercator.1, webmercator.1, epsilon = epsilon);
498    }
499
500    #[rstest]
501    #[case(0..11, 0)]
502    #[case(11..14, 1)]
503    #[case(14..17, 2)]
504    #[case(17..21, 3)]
505    #[case(21..24, 4)]
506    #[case(24..27, 5)]
507    #[case(27..30, 6)]
508    fn test_get_zoom_precision(
509        #[case] zoom: std::ops::Range<u8>,
510        #[case] expected_precision: usize,
511    ) {
512        for z in zoom {
513            let actual_precision = get_zoom_precision(z);
514            assert_eq!(
515                actual_precision, expected_precision,
516                "Zoom level {z} should have precision {expected_precision}, but was {actual_precision}"
517            );
518        }
519    }
520
521    #[test]
522    fn test_tile_coord_zoom_range() {
523        for z in 0..=MAX_ZOOM {
524            assert!(TileCoord::is_possible_on_zoom_level(z, 0, 0));
525            assert_eq!(
526                TileCoord::new_checked(z, 0, 0),
527                Some(TileCoord { z, x: 0, y: 0 })
528            );
529        }
530        assert!(!TileCoord::is_possible_on_zoom_level(MAX_ZOOM + 1, 0, 0));
531        assert_eq!(TileCoord::new_checked(MAX_ZOOM + 1, 0, 0), None);
532    }
533
534    #[test]
535    fn test_tile_coord_new_checked_xy_for_zoom() {
536        assert!(TileCoord::is_possible_on_zoom_level(5, 0, 0));
537        assert_eq!(
538            TileCoord::new_checked(5, 0, 0),
539            Some(TileCoord { z: 5, x: 0, y: 0 })
540        );
541        assert!(TileCoord::is_possible_on_zoom_level(5, 31, 31));
542        assert_eq!(
543            TileCoord::new_checked(5, 31, 31),
544            Some(TileCoord { z: 5, x: 31, y: 31 })
545        );
546        assert!(!TileCoord::is_possible_on_zoom_level(5, 31, 32));
547        assert_eq!(TileCoord::new_checked(5, 31, 32), None);
548        assert!(!TileCoord::is_possible_on_zoom_level(5, 32, 31));
549        assert_eq!(TileCoord::new_checked(5, 32, 31), None);
550    }
551
552    #[test]
553    /// Any (u8, u32, u32) values can be put inside [`TileCoord`], of course, but some
554    /// functions may panic at runtime (e.g. [`mbtiles::invert_y_value`]) if they are impossible,
555    /// so let's not do that.
556    fn test_tile_coord_new_unchecked() {
557        assert_eq!(
558            TileCoord::new_unchecked(u8::MAX, u32::MAX, u32::MAX),
559            TileCoord {
560                z: u8::MAX,
561                x: u32::MAX,
562                y: u32::MAX
563            }
564        );
565    }
566}
martin_tile_utils/lib.rs

martin_tile_utils/
lib.rs
