Skip to main content

parquet_geospatial/
types.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: See the NOTICE file distributed with this work for additional information regarding copyright ownership
3// SPDX-FileContributor: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements
4
5use arrow_schema::{ArrowError, DataType, extension::ExtensionType};
6use serde::{Deserialize, Serialize};
7
8/// Hints at the likely Parquet geospatial logical type represented by a [`Metadata`].
9///
10/// Based on the `algorithm` field:
11/// - [`Hint::Geometry`]: WKB format with linear/planar edge interpolation
12/// - [`Hint::Geography`]: WKB format with explicit non-linear/non-planar edge interpolation
13///
14/// See the [Parquet Geospatial specification](https://github.com/apache/parquet-format/blob/master/Geospatial.md)
15/// for more details.
16#[derive(Copy, Clone, Debug, Serialize, Deserialize)]
17pub enum Hint {
18    /// Geospatial features in WKB format with linear/planar edge interpolation
19    Geometry,
20    /// Geospatial features in WKB format with explicit non-linear/non-planar edge interpolation
21    Geography,
22}
23
24/// The edge interpolation algorithms used with `GEOMETRY` logical types.
25#[derive(Default, Debug, Copy, Clone, PartialEq, Eq, Serialize, Deserialize)]
26#[serde(rename_all = "lowercase")]
27pub enum Edges {
28    /// Edges are interpolated as geodesics on a sphere.
29    #[default]
30    Spherical,
31    /// <https://en.wikipedia.org/wiki/Vincenty%27s_formulae>
32    Vincenty,
33    /// Thomas, Paul D. Spheroidal geodesics, reference systems, & local geometry. US Naval Oceanographic Office, 1970
34    Thomas,
35    /// Thomas, Paul D. Mathematical models for navigation systems. US Naval Oceanographic Office, 1965.
36    Andoyer,
37    /// Karney, Charles FF. "Algorithms for geodesics." Journal of Geodesy 87 (2013): 43-55
38    Karney,
39}
40
41/// The metadata associated with a [`WkbType`].
42#[derive(Clone, Debug, Default, Serialize, Deserialize)]
43pub struct Metadata {
44    /// The Coordinate Reference System (CRS) of the [`WkbType`], if present.
45    ///
46    /// This may be a raw string value (e.g., "EPSG:3857") or a JSON object (e.g., PROJJSON).
47    #[serde(skip_serializing_if = "Option::is_none")]
48    pub crs: Option<serde_json::Value>,
49    /// The edge interpolation algorithm of the [`WkbType`], if present.
50    #[serde(rename = "edges", skip_serializing_if = "Option::is_none")]
51    pub algorithm: Option<Edges>,
52}
53
54impl Metadata {
55    /// Constructs a new [`Metadata`] with the given CRS and algorithm.
56    ///
57    /// If a CRS is provided, and can be parsed as JSON, it will be stored as a JSON object instead
58    /// of its string representation.
59    pub fn new(crs: Option<&str>, algorithm: Option<Edges>) -> Self {
60        let crs = crs.map(|c| match serde_json::from_str(c) {
61            Ok(crs) => crs,
62            Err(_) => serde_json::Value::String(c.to_string()),
63        });
64
65        Self { crs, algorithm }
66    }
67
68    /// Returns a [`Hint`] to the likely underlying Logical Type that this [`Metadata`] represents.
69    pub fn type_hint(&self) -> Hint {
70        match &self.algorithm {
71            Some(_) => Hint::Geography,
72            None => Hint::Geometry,
73        }
74    }
75
76    /// Detect if the CRS is a common representation of lon/lat on the standard WGS84 ellipsoid.
77    ///
78    /// Returns `true` for OGC:CRS84, EPSG:4326, and PROJJSON representations thereof.
79    pub fn crs_is_lon_lat(&self) -> bool {
80        use serde_json::Value;
81
82        let Some(crs) = &self.crs else {
83            return false;
84        };
85
86        match crs {
87            Value::String(s) if s == "EPSG:4326" || s == "OGC:CRS84" => true,
88            Value::Object(_) => match (&crs["id"]["authority"], &crs["id"]["code"]) {
89                (Value::String(auth), Value::String(code)) if auth == "OGC" && code == "CRS84" => {
90                    true
91                }
92                (Value::String(auth), Value::String(code)) if auth == "EPSG" && code == "4326" => {
93                    true
94                }
95                (Value::String(auth), Value::Number(code))
96                    if auth == "EPSG" && code.as_i64() == Some(4326) =>
97                {
98                    true
99                }
100                _ => false,
101            },
102            _ => false,
103        }
104    }
105}
106
107/// Well-Known Binary (WKB) [`ExtensionType`] for geospatial data.
108///
109/// Represents the canonical Arrow Extension Type for storing
110/// [GeoArrow](https://github.com/geoarrow/geoarrow) data.
111#[derive(Debug, Default)]
112pub struct WkbType(Metadata);
113
114impl WkbType {
115    /// Constructs a new [`WkbType`] with the given [`Metadata`].
116    ///
117    /// If `None` is provided, default (empty) metadata is used.
118    pub fn new(metadata: Option<Metadata>) -> Self {
119        Self(metadata.unwrap_or_default())
120    }
121}
122
123type ArrowResult<T> = Result<T, ArrowError>;
124impl ExtensionType for WkbType {
125    const NAME: &'static str = "geoarrow.wkb";
126
127    type Metadata = Metadata;
128
129    fn metadata(&self) -> &Self::Metadata {
130        &self.0
131    }
132
133    fn serialize_metadata(&self) -> Option<String> {
134        serde_json::to_string(&self.0).ok()
135    }
136
137    fn deserialize_metadata(metadata: Option<&str>) -> ArrowResult<Self::Metadata> {
138        let Some(metadata) = metadata else {
139            return Ok(Self::Metadata::default());
140        };
141
142        serde_json::from_str(metadata).map_err(|e| ArrowError::JsonError(e.to_string()))
143    }
144
145    fn supports_data_type(&self, data_type: &arrow_schema::DataType) -> ArrowResult<()> {
146        match data_type {
147            DataType::Binary | DataType::LargeBinary | DataType::BinaryView => Ok(()),
148            dt => Err(ArrowError::InvalidArgumentError(format!(
149                "Geometry data type mismatch, expected one of Binary, LargeBinary, BinaryView. Found {dt}"
150            ))),
151        }
152    }
153
154    fn try_new(data_type: &arrow_schema::DataType, metadata: Self::Metadata) -> ArrowResult<Self> {
155        let wkb = Self(metadata);
156        wkb.supports_data_type(data_type)?;
157        Ok(wkb)
158    }
159}
160
161#[cfg(test)]
162mod tests {
163    use super::*;
164    use arrow_schema::Field;
165
166    /// Test metadata serialization and deserialization with empty/default metadata
167    #[test]
168    fn test_metadata_empty_roundtrip() -> ArrowResult<()> {
169        let metadata = Metadata::default();
170        let wkb = WkbType::new(Some(metadata));
171
172        let serialized = wkb.serialize_metadata().unwrap();
173        assert_eq!(serialized, "{}");
174
175        let deserialized = WkbType::deserialize_metadata(Some(&serialized))?;
176        assert!(deserialized.crs.is_none());
177        assert!(deserialized.algorithm.is_none());
178
179        Ok(())
180    }
181
182    /// Test metadata serialization with CRS as a simple string
183    #[test]
184    fn test_metadata_crs_string_roundtrip() -> ArrowResult<()> {
185        let metadata = Metadata::new(Some("srid:1234"), None);
186        let wkb = WkbType::new(Some(metadata));
187
188        let serialized = wkb.serialize_metadata().unwrap();
189        assert_eq!(serialized, r#"{"crs":"srid:1234"}"#);
190
191        let deserialized = WkbType::deserialize_metadata(Some(&serialized))?;
192        assert_eq!(
193            deserialized.crs.unwrap(),
194            serde_json::Value::String(String::from("srid:1234"))
195        );
196        assert!(deserialized.algorithm.is_none());
197
198        Ok(())
199    }
200
201    /// Test metadata serialization with CRS as a JSON object
202    #[test]
203    fn test_metadata_crs_json_object_roundtrip() -> ArrowResult<()> {
204        let crs_json = r#"{"type":"custom_json","properties":{"name":"EPSG:4326"}}"#;
205        let metadata = Metadata::new(Some(crs_json), None);
206        let wkb = WkbType::new(Some(metadata));
207
208        let serialized = wkb.serialize_metadata().unwrap();
209        // Validate by parsing the JSON and checking structure (field order is not guaranteed)
210        let parsed: serde_json::Value = serde_json::from_str(&serialized).unwrap();
211        assert_eq!(parsed["crs"]["type"], "custom_json");
212        assert_eq!(parsed["crs"]["properties"]["name"], "EPSG:4326");
213
214        let deserialized = WkbType::deserialize_metadata(Some(&serialized))?;
215
216        // Verify it's a JSON object with expected structure
217        let crs = deserialized.crs.unwrap();
218        assert!(crs.is_object());
219        assert_eq!(crs["type"], "custom_json");
220        assert_eq!(crs["properties"]["name"], "EPSG:4326");
221
222        Ok(())
223    }
224
225    /// Test metadata serialization with algorithm field
226    #[test]
227    fn test_metadata_algorithm_roundtrip() -> ArrowResult<()> {
228        let metadata = Metadata::new(None, Some(Edges::Spherical));
229        let wkb = WkbType::new(Some(metadata));
230
231        let serialized = wkb.serialize_metadata().unwrap();
232        assert_eq!(serialized, r#"{"edges":"spherical"}"#);
233
234        let deserialized = WkbType::deserialize_metadata(Some(&serialized))?;
235        assert!(deserialized.crs.is_none());
236        assert_eq!(deserialized.algorithm, Some(Edges::Spherical));
237
238        Ok(())
239    }
240
241    /// Test metadata serialization with both CRS and algorithm
242    #[test]
243    fn test_metadata_full_roundtrip() -> ArrowResult<()> {
244        let metadata = Metadata::new(Some("srid:1234"), Some(Edges::Spherical));
245        let wkb = WkbType::new(Some(metadata));
246
247        let serialized = wkb.serialize_metadata().unwrap();
248        assert_eq!(serialized, r#"{"crs":"srid:1234","edges":"spherical"}"#);
249
250        let deserialized = WkbType::deserialize_metadata(Some(&serialized))?;
251        assert_eq!(
252            deserialized.crs.unwrap(),
253            serde_json::Value::String("srid:1234".to_string())
254        );
255        assert_eq!(deserialized.algorithm, Some(Edges::Spherical));
256
257        Ok(())
258    }
259
260    /// Test deserialization of None metadata
261    #[test]
262    fn test_metadata_deserialize_none() -> ArrowResult<()> {
263        let deserialized = WkbType::deserialize_metadata(None)?;
264        assert!(deserialized.crs.is_none());
265        assert!(deserialized.algorithm.is_none());
266        Ok(())
267    }
268
269    /// Test deserialization of invalid JSON
270    #[test]
271    fn test_metadata_deserialize_invalid_json() {
272        let result = WkbType::deserialize_metadata(Some("not valid json {"));
273        assert!(matches!(result, Err(ArrowError::JsonError(_))));
274    }
275
276    /// Test metadata that results in a Geometry type hint
277    #[test]
278    fn test_type_hint_geometry() {
279        let metadata = Metadata::new(None, None);
280        assert!(matches!(metadata.type_hint(), Hint::Geometry));
281    }
282
283    /// Test metadata that results in a Geography type hint
284    #[test]
285    fn test_type_hint_edges_is_geography() {
286        let algorithms = vec![
287            Edges::Spherical,
288            Edges::Vincenty,
289            Edges::Thomas,
290            Edges::Andoyer,
291            Edges::Karney,
292        ];
293        for algo in algorithms {
294            let metadata = Metadata::new(None, Some(algo));
295            assert!(matches!(metadata.type_hint(), Hint::Geography));
296        }
297    }
298
299    /// Test extension type integration using a Field
300    #[test]
301    fn test_extension_type_with_field() -> ArrowResult<()> {
302        let metadata = Metadata::new(Some("srid:1234"), None);
303        let wkb_type = WkbType::new(Some(metadata));
304
305        let mut field = Field::new("geometry", DataType::Binary, false);
306        field.try_with_extension_type(wkb_type)?;
307
308        // Verify we can extract the extension type back
309        let extracted = field.try_extension_type::<WkbType>()?;
310        assert_eq!(
311            extracted.metadata().crs.as_ref().unwrap(),
312            &serde_json::Value::String(String::from("srid:1234"))
313        );
314
315        Ok(())
316    }
317
318    /// Test extension type DataType support
319    #[test]
320    fn test_extension_type_support() -> ArrowResult<()> {
321        let wkb = WkbType::default();
322        // supported types
323        wkb.supports_data_type(&DataType::Binary)?;
324        wkb.supports_data_type(&DataType::LargeBinary)?;
325        wkb.supports_data_type(&DataType::BinaryView)?;
326
327        // reject unsupported types with an error
328        let result = wkb.supports_data_type(&DataType::Utf8);
329        assert!(matches!(result, Err(ArrowError::InvalidArgumentError(_))));
330
331        Ok(())
332    }
333
334    /// Test crs_is_lon_lat() detection for common lon/lat representations
335    #[test]
336    fn test_crs_is_lon_lat() -> ArrowResult<()> {
337        // EPSG:4326 as string should be detected
338        let metadata = Metadata::new(Some("EPSG:4326"), None);
339        assert!(metadata.crs_is_lon_lat());
340
341        // OGC:CRS84 as string should be detected
342        let metadata = Metadata::new(Some("OGC:CRS84"), None);
343        assert!(metadata.crs_is_lon_lat());
344
345        // A JSON object that reasonably looks like PROJJSON for EPSG:4326 should be detected
346        // detect "4326" as a string
347        let crs_json = r#"{"id":{"authority":"EPSG","code":"4326"}}"#;
348        let metadata = Metadata::new(Some(crs_json), None);
349        assert!(metadata.crs_is_lon_lat());
350
351        // detect 4326 as a number
352        let crs_json = r#"{"id":{"authority":"EPSG","code":4326}}"#;
353        let metadata = Metadata::new(Some(crs_json), None);
354        assert!(metadata.crs_is_lon_lat());
355
356        // A JSON object that reasonably looks like PROJJSON for OGC:CRS84 should be detected
357        let crs_json = r#"{"id":{"authority":"OGC","code":"CRS84"}}"#;
358        let metadata = Metadata::new(Some(crs_json), None);
359        assert!(metadata.crs_is_lon_lat());
360
361        // Other CRS values should NOT be detected as lon/lat
362        let metadata = Metadata::new(Some("srid:1234"), None);
363        assert!(!metadata.crs_is_lon_lat());
364
365        let metadata = Metadata::new(Some("EPSG:3857"), None);
366        assert!(!metadata.crs_is_lon_lat());
367
368        // None CRS should NOT be detected as lon/lat
369        let metadata = Metadata::new(None, None);
370        assert!(!metadata.crs_is_lon_lat());
371
372        Ok(())
373    }
374}