kaushiksrini commented on code in PR #8225: URL: https://github.com/apache/arrow-rs/pull/8225#discussion_r2302304044
########## parquet/src/geospatial/statistics.rs: ########## @@ -0,0 +1,320 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +//! Geospatial statistics for Parquet files. +//! +//! This module provides functionality for working with geospatial statistics in Parquet files. +//! It includes support for bounding boxes and geospatial statistics in column chunk metadata. + +use crate::format as parquet; +use crate::format::GeospatialStatistics as TGeospatialStatistics; +use crate::errors::{ParquetError, Result}; + +// ---------------------------------------------------------------------- +// Bounding Box + +/// A geospatial instance has at least two coordinate dimensions: X and Y for 2D coordinates of each point. +/// X represents longitude/easting and Y represents latitude/northing. A geospatial instance can optionally +/// have Z and/or M values associated with each point. +/// +/// The Z values introduce the third dimension coordinate, typically used to indicate height or elevation. +/// +/// M values allow tracking a value in a fourth dimension. These can represent: +/// - Linear reference values (e.g., highway milepost) +/// - Timestamps +/// - Other values defined by the CRS +/// +/// The bounding box is defined as min/max value pairs of coordinates from each axis. X and Y values are +/// always present, while Z and M are omitted for 2D geospatial instances. +/// +/// When calculating a bounding box: +/// - Null or NaN values in a coordinate dimension are skipped +/// - If a dimension has only null/NaN values, that dimension is omitted +/// - If either X or Y dimension is missing, no bounding box is produced +/// - Example: POINT (1 NaN) contributes to X but not to Y, Z, or M dimensions +/// +/// Special cases: +/// - For X values only, xmin may exceed xmax. In this case, a point matches if x >= xmin OR x <= xmax +/// - This wraparound occurs when the bounding box crosses the antimeridian line +/// - In geographic terms: xmin=westernmost, xmax=easternmost, ymin=southernmost, ymax=northernmost +/// +/// For GEOGRAPHY types: +/// - X values must be within [-180, 180] (longitude) +/// - Y values must be within [-90, 90] (latitude) +/// +/// Derived from the parquet format spec: https://github.com/apache/parquet-format/blob/ae39061f28d7c508a97af58a3c0a567352c8ea41/Geospatial.md#bounding-box +/// +/// # Examples +/// +/// ``` +/// use parquet::geospatial::statistics::BoundingBox; +/// +/// // 2D bounding box +/// let bbox_2d = BoundingBox::new(0.0, 0.0, 100.0, 100.0); +/// +/// // 3D bounding box with elevation +/// let bbox_3d = BoundingBox::new(0.0, 0.0, 100.0, 100.0).with_zrange(0.0, 1000.0); +/// ``` +#[derive(Clone, Debug, PartialEq)] +pub struct BoundingBox { + /// Minimum X coordinate (longitude or easting) + xmin: f64, + /// Minimum Y coordinate (latitude or northing) + ymin: f64, + /// Maximum X coordinate (longitude or easting) + xmax: f64, + /// Maximum Y coordinate (latitude or northing) + ymax: f64, + /// Minimum Z coordinate (elevation/height), if present + zmin: Option<f64>, + /// Maximum Z coordinate (elevation/height), if present + zmax: Option<f64>, + /// Minimum M coordinate (measured value), if present + mmin: Option<f64>, + /// Maximum M coordinate (measured value), if present + mmax: Option<f64>, +} + +impl BoundingBox { + /// Creates a new bounding box with the specified coordinates. + /// + /// # Arguments + /// + /// * `xmin` - Minimum X coordinate + /// * `ymin` - Minimum Y coordinate + /// * `xmax` - Maximum X coordinate + /// * `ymax` - Maximum Y coordinate + /// + /// # Returns + /// + /// A new `BoundingBox` instance with the specified coordinates. + pub fn new(xmin: f64, ymin: f64, xmax: f64, ymax: f64) -> Self { + Self { xmin, ymin, xmax, ymax, zmin: None, zmax: None, mmin: None, mmax: None } + } + + /// Creates a new bounding box with the specified Z-coordinate range. + /// + /// # Arguments + /// + /// * `zmin` - Minimum Z coordinate + /// * `zmax` - Maximum Z coordinate + pub fn with_zrange(self, zmin: f64, zmax: f64) -> Self { + Self { zmin: Some(zmin), zmax: Some(zmax), ..self } + } + + /// Creates a new bounding box with the specified M-coordinate range. + /// + /// # Arguments + /// + /// * `mmin` - Minimum M coordinate + /// * `mmax` - Maximum M coordinate + pub fn with_mrange(self, mmin: f64, mmax: f64) -> Self { + Self { mmin: Some(mmin), mmax: Some(mmax), ..self } + } +} + +// ---------------------------------------------------------------------- +// Geospatial Statistics + +/// Represents geospatial statistics for a Parquet column or dataset. +/// +/// This struct contains metadata about the spatial characteristics of geospatial data, +/// including bounding box information and the types of geospatial geometries present. +/// It's used to optimize spatial queries and provide spatial context for data analysis. +/// +/// # Examples +/// +/// ``` +/// use parquet::geospatial::statistics::{GeospatialStatistics, BoundingBox}; +/// +/// // Empty statistics +/// let empty_stats = GeospatialStatistics::new_empty(); +/// +/// // Statistics with bounding box +/// let bbox = BoundingBox::new(0.0, 0.0, 100.0, 100.0, None, None, None, None); +/// let stats = GeospatialStatistics::new(Some(bbox), Some(vec![1, 2, 3])); +/// ``` +#[derive(Clone, Debug, PartialEq, Default)] +pub struct GeospatialStatistics { + /// Optional bounding box encompassing all geospatial data + bbox: Option<BoundingBox>, + /// Optional list of geospatial geometry type identifiers + /// as specified in https://github.com/apache/parquet-format/blob/ae39061f28d7c508a97af58a3c0a567352c8ea41/Geospatial.md#geospatial-types + geospatial_types: Option<Vec<i32>>, Review Comment: kept it as `i32` since to keep it in sync with the [thrift definition](https://github.com/apache/parquet-format/blob/ae39061f28d7c508a97af58a3c0a567352c8ea41/src/main/thrift/parquet.thrift#L260) and [c++ implementation](https://github.com/paleolimbot/arrow/blob/e1b7061cb1df3d5fc861fe80557cd7824980346a/cpp/src/parquet/geospatial/statistics.h#L58), but u16 makes more sense given the possible values -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: github-unsubscr...@arrow.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
