n3gb-rs 0.2.2

use crate::cell::HexCell;
use crate::coord::{
    ConversionMethod, Coordinate, convert_multipolygon_to_bng, convert_polygon_to_bng,
    convert_to_bng,
};
use crate::error::N3gbError;
use crate::index::{GRID_EXTENTS, generate_hex_identifier, point_to_row_col, row_col_to_center};
use crate::io::arrow::HexCellsToArrow;
use crate::io::parquet::HexCellsToGeoParquet;
use arrow_array::RecordBatch;
use geo::{BoundingRect, Intersects};
use geo_types::{MultiPolygon, Point, Polygon, Rect};
use geoarrow_array::array::{PointArray, PolygonArray};
use rayon::prelude::*;
use std::collections::HashMap;
use std::path::Path;

/// A collection of hexagonal cells covering a geographic extent.
///
/// `HexGrid` generates and manages multiple [`HexCell`]s for a given bounding box
/// and zoom level.
///
/// Use it when you need to work with multiple cells at once,
/// such as tiling an area prior to performing spatial queries.
///
/// # Example
///
/// ```
/// use n3gb_rs::HexGrid;
/// use geo_types::point;
///
/// # fn main() -> Result<(), n3gb_rs::N3gbError> {
/// // Create a grid covering an area
/// let grid = HexGrid::builder()
///     .zoom_level(10)
///     .bng_extent(&(457000.0, 339500.0), &(458000.0, 340500.0))
///     .build()?;
///
/// println!("Grid contains {} cells", grid.len());
///
/// // Find which cell contains a point
/// let pt = point! { x: 457500.0, y: 340000.0 };
/// if let Some(cell) = grid.get_cell_at(&pt) {
///     println!("Point is in cell: {}", cell.id);
/// }
/// # Ok(())
/// # }
/// ```
#[derive(Debug, Clone)]
pub struct HexGrid {
    cells: Vec<HexCell>,
    index: HashMap<(i64, i64), usize>,
    zoom_level: u8,
}

impl HexGrid {
    /// Build a `HexGrid` from a vec of cells, constructing the spatial index.
    fn new(cells: Vec<HexCell>, zoom_level: u8) -> Self {
        let index = cells
            .iter()
            .enumerate()
            .map(|(i, cell)| ((cell.row, cell.col), i))
            .collect();
        Self {
            cells,
            index,
            zoom_level,
        }
    }

    /// Creates a new [`HexGridBuilder`] for grid construction.
    ///
    /// # Returns
    ///
    /// A fresh [`HexGridBuilder`] with no parameters set.
    pub fn builder() -> HexGridBuilder {
        HexGridBuilder::new()
    }

    /// Build a grid from a bounding box extent.
    fn from_extent(
        min_x: f64,
        min_y: f64,
        max_x: f64,
        max_y: f64,
        zoom_level: u8,
    ) -> Result<Self, N3gbError> {
        let cells = generate_cells_for_extent(min_x, min_y, max_x, max_y, zoom_level)?;
        Ok(Self::new(cells, zoom_level))
    }

    /// Creates a HexGrid from a `geo_types::Rect` in BNG coordinates.
    ///
    /// # Arguments
    ///
    /// * `rect` - The bounding rectangle, in BNG (EPSG:27700) coordinates.
    /// * `zoom_level` - The zoom level for the generated cells.
    ///
    /// # Returns
    ///
    /// A `HexGrid` covering the rectangle's extent.
    ///
    /// # Errors
    ///
    /// Returns [`N3gbError::InvalidZoomLevel`] if `zoom_level` exceeds the
    /// maximum supported zoom level.
    pub fn from_rect(rect: &Rect<f64>, zoom_level: u8) -> Result<Self, N3gbError> {
        Self::from_extent(
            rect.min().x,
            rect.min().y,
            rect.max().x,
            rect.max().y,
            zoom_level,
        )
    }

    /// Create a HexGrid from British National Grid coordinates
    ///
    /// # Example
    /// ```
    /// use n3gb_rs::HexGrid;
    /// use geo_types::Point;
    ///
    /// # fn main() -> Result<(), n3gb_rs::N3gbError> {
    /// // From tuples
    /// let grid = HexGrid::from_bng_extent(&(457000.0, 339500.0), &(458000.0, 340500.0), 10)?;
    /// // From Points
    /// let grid = HexGrid::from_bng_extent(
    ///     &Point::new(457000.0, 339500.0),
    ///     &Point::new(458000.0, 340500.0),
    ///     10
    /// )?;
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Arguments
    ///
    /// * `min` - The minimum (lower-left) corner, in BNG (EPSG:27700) coordinates.
    /// * `max` - The maximum (upper-right) corner, in BNG (EPSG:27700) coordinates.
    /// * `zoom_level` - The zoom level for the generated cells.
    ///
    /// # Returns
    ///
    /// A `HexGrid` covering the given extent.
    ///
    /// # Errors
    ///
    /// Returns [`N3gbError::InvalidZoomLevel`] if `zoom_level` exceeds the
    /// maximum supported zoom level.
    pub fn from_bng_extent(
        min: &impl Coordinate,
        max: &impl Coordinate,
        zoom_level: u8,
    ) -> Result<Self, N3gbError> {
        Self::from_extent(min.x(), min.y(), max.x(), max.y(), zoom_level)
    }

    /// Create a HexGrid from WGS84 (lon/lat) coordinates
    ///
    /// # Example
    /// ```
    /// use n3gb_rs::HexGrid;
    /// use geo_types::Point;
    ///
    /// # fn main() -> Result<(), n3gb_rs::N3gbError> {
    /// // From tuples (lon, lat)
    /// let grid = HexGrid::from_wgs84_extent(&(-2.3, 53.4), &(-2.2, 53.5), 10, n3gb_rs::ConversionMethod::Proj)?;
    /// // From Points
    /// let grid = HexGrid::from_wgs84_extent(
    ///     &Point::new(-2.3, 53.4),
    ///     &Point::new(-2.2, 53.5),
    ///     10,
    ///     n3gb_rs::ConversionMethod::Proj,
    /// )?;
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Arguments
    ///
    /// * `min` - The minimum (lower-left) corner, in WGS84 (lon/lat) coordinates.
    /// * `max` - The maximum (upper-right) corner, in WGS84 (lon/lat) coordinates.
    /// * `zoom_level` - The zoom level for the generated cells.
    /// * `method` - The conversion backend used to project from WGS84 to BNG.
    ///
    /// # Returns
    ///
    /// A `HexGrid` covering the given extent.
    ///
    /// # Errors
    ///
    /// Returns [`N3gbError::ProjectionError`] if projecting the corners from
    /// WGS84 to BNG fails, or [`N3gbError::InvalidZoomLevel`] if `zoom_level`
    /// exceeds the maximum supported zoom level.
    pub fn from_wgs84_extent(
        min: &impl Coordinate,
        max: &impl Coordinate,
        zoom_level: u8,
        method: ConversionMethod,
    ) -> Result<Self, N3gbError> {
        let min_bng = convert_to_bng(min, method)?;
        let max_bng = convert_to_bng(max, method)?;
        Self::from_extent(
            min_bng.x(),
            min_bng.y(),
            max_bng.x(),
            max_bng.y(),
            zoom_level,
        )
    }

    /// Creates a HexGrid from a polygon in BNG coordinates.
    ///
    /// Generates hex cells for the polygon's bounding box, then filters
    /// to only include cells whose hexagon intersects the polygon.
    ///
    /// # Example
    /// ```
    /// use n3gb_rs::HexGrid;
    /// use geo_types::{Polygon, LineString, coord};
    ///
    /// # fn main() -> Result<(), n3gb_rs::N3gbError> {
    /// let polygon = Polygon::new(
    ///     LineString::from(vec![
    ///         coord! { x: 457000.0, y: 339500.0 },
    ///         coord! { x: 458000.0, y: 339500.0 },
    ///         coord! { x: 458000.0, y: 340500.0 },
    ///         coord! { x: 457000.0, y: 340500.0 },
    ///         coord! { x: 457000.0, y: 339500.0 },
    ///     ]),
    ///     vec![],
    /// );
    /// let grid = HexGrid::from_bng_polygon(&polygon, 10)?;
    /// assert!(!grid.is_empty());
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Arguments
    ///
    /// * `polygon` - The polygon, in BNG (EPSG:27700) coordinates.
    /// * `zoom_level` - The zoom level for the generated cells.
    ///
    /// # Returns
    ///
    /// A `HexGrid` containing only the cells whose hexagon intersects the
    /// polygon. Empty if the polygon has no bounding rectangle.
    ///
    /// # Errors
    ///
    /// Returns [`N3gbError::InvalidZoomLevel`] if `zoom_level` exceeds the
    /// maximum supported zoom level.
    pub fn from_bng_polygon(polygon: &Polygon<f64>, zoom_level: u8) -> Result<Self, N3gbError> {
        let bbox = match polygon.bounding_rect() {
            Some(rect) => rect,
            None => return Ok(Self::new(Vec::new(), zoom_level)),
        };

        Ok(Self::from_rect(&bbox, zoom_level)?
            .retain(|cell| polygon.intersects(&cell.to_polygon())))
    }

    /// Creates a HexGrid from a polygon in WGS84 (lon/lat) coordinates.
    ///
    /// Projects the polygon to BNG, then generates hex cells for the
    /// polygon's bounding box and filters to cells that intersect.
    ///
    /// # Example
    /// ```
    /// use n3gb_rs::HexGrid;
    /// use geo_types::{Polygon, LineString, coord};
    ///
    /// # fn main() -> Result<(), n3gb_rs::N3gbError> {
    /// let polygon = Polygon::new(
    ///     LineString::from(vec![
    ///         coord! { x: -2.3, y: 53.4 },
    ///         coord! { x: -2.2, y: 53.4 },
    ///         coord! { x: -2.2, y: 53.5 },
    ///         coord! { x: -2.3, y: 53.5 },
    ///         coord! { x: -2.3, y: 53.4 },
    ///     ]),
    ///     vec![],
    /// );
    /// let grid = HexGrid::from_wgs84_polygon(&polygon, 10, n3gb_rs::ConversionMethod::Proj)?;
    /// assert!(!grid.is_empty());
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Arguments
    ///
    /// * `polygon` - The polygon, in WGS84 (lon/lat) coordinates.
    /// * `zoom_level` - The zoom level for the generated cells.
    /// * `method` - The conversion backend used to project from WGS84 to BNG.
    ///
    /// # Returns
    ///
    /// A `HexGrid` containing only the cells whose hexagon intersects the
    /// projected polygon.
    ///
    /// # Errors
    ///
    /// Returns [`N3gbError::ProjectionError`] if projecting the polygon from
    /// WGS84 to BNG fails, or [`N3gbError::InvalidZoomLevel`] if `zoom_level`
    /// exceeds the maximum supported zoom level.
    pub fn from_wgs84_polygon(
        polygon: &Polygon<f64>,
        zoom_level: u8,
        method: ConversionMethod,
    ) -> Result<Self, N3gbError> {
        let bng_polygon = convert_polygon_to_bng(polygon, method)?;
        Self::from_bng_polygon(&bng_polygon, zoom_level)
    }

    /// Creates a HexGrid from a multipolygon in BNG coordinates.
    ///
    /// Generates hex cells for each polygon in the multipolygon and
    /// combines them, deduplicating overlapping cells.
    ///
    /// # Example
    /// ```
    /// use n3gb_rs::HexGrid;
    /// use geo_types::{MultiPolygon, Polygon, LineString, coord};
    ///
    /// # fn main() -> Result<(), n3gb_rs::N3gbError> {
    /// let poly1 = Polygon::new(
    ///     LineString::from(vec![
    ///         coord! { x: 457000.0, y: 339500.0 },
    ///         coord! { x: 457500.0, y: 339500.0 },
    ///         coord! { x: 457500.0, y: 340000.0 },
    ///         coord! { x: 457000.0, y: 340000.0 },
    ///         coord! { x: 457000.0, y: 339500.0 },
    ///     ]),
    ///     vec![],
    /// );
    /// let poly2 = Polygon::new(
    ///     LineString::from(vec![
    ///         coord! { x: 457500.0, y: 340000.0 },
    ///         coord! { x: 458000.0, y: 340000.0 },
    ///         coord! { x: 458000.0, y: 340500.0 },
    ///         coord! { x: 457500.0, y: 340500.0 },
    ///         coord! { x: 457500.0, y: 340000.0 },
    ///     ]),
    ///     vec![],
    /// );
    /// let mp = MultiPolygon::new(vec![poly1, poly2]);
    /// let grid = HexGrid::from_bng_multipolygon(&mp, 10)?;
    /// assert!(!grid.is_empty());
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Arguments
    ///
    /// * `multipolygon` - The multipolygon, in BNG (EPSG:27700) coordinates.
    /// * `zoom_level` - The zoom level for the generated cells.
    ///
    /// # Returns
    ///
    /// A `HexGrid` containing only the cells whose hexagon intersects any
    /// polygon, with duplicates removed. Empty if the multipolygon has no
    /// bounding rectangle.
    ///
    /// # Errors
    ///
    /// Returns [`N3gbError::InvalidZoomLevel`] if `zoom_level` exceeds the
    /// maximum supported zoom level.
    pub fn from_bng_multipolygon(
        multipolygon: &MultiPolygon<f64>,
        zoom_level: u8,
    ) -> Result<Self, N3gbError> {
        let bbox = match multipolygon.bounding_rect() {
            Some(rect) => rect,
            None => return Ok(Self::new(Vec::new(), zoom_level)),
        };

        Ok(Self::from_rect(&bbox, zoom_level)?
            .retain(|cell| multipolygon.intersects(&cell.to_polygon())))
    }

    /// Creates a HexGrid from a multipolygon in WGS84 (lon/lat) coordinates.
    ///
    /// Projects the multipolygon to BNG, then generates hex cells for each
    /// polygon and combines them, deduplicating overlapping cells.
    ///
    /// # Example
    /// ```
    /// use n3gb_rs::HexGrid;
    /// use geo_types::{MultiPolygon, Polygon, LineString, coord};
    ///
    /// # fn main() -> Result<(), n3gb_rs::N3gbError> {
    /// let poly1 = Polygon::new(
    ///     LineString::from(vec![
    ///         coord! { x: -2.3, y: 53.4 },
    ///         coord! { x: -2.25, y: 53.4 },
    ///         coord! { x: -2.25, y: 53.45 },
    ///         coord! { x: -2.3, y: 53.45 },
    ///         coord! { x: -2.3, y: 53.4 },
    ///     ]),
    ///     vec![],
    /// );
    /// let poly2 = Polygon::new(
    ///     LineString::from(vec![
    ///         coord! { x: -2.25, y: 53.45 },
    ///         coord! { x: -2.2, y: 53.45 },
    ///         coord! { x: -2.2, y: 53.5 },
    ///         coord! { x: -2.25, y: 53.5 },
    ///         coord! { x: -2.25, y: 53.45 },
    ///     ]),
    ///     vec![],
    /// );
    /// let mp = MultiPolygon::new(vec![poly1, poly2]);
    /// let grid = HexGrid::from_wgs84_multipolygon(&mp, 10, n3gb_rs::ConversionMethod::Proj)?;
    /// assert!(!grid.is_empty());
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Arguments
    ///
    /// * `multipolygon` - The multipolygon, in WGS84 (lon/lat) coordinates.
    /// * `zoom_level` - The zoom level for the generated cells.
    /// * `method` - The conversion backend used to project from WGS84 to BNG.
    ///
    /// # Returns
    ///
    /// A `HexGrid` containing only the cells whose hexagon intersects any
    /// projected polygon, with duplicates removed.
    ///
    /// # Errors
    ///
    /// Returns [`N3gbError::ProjectionError`] if projecting the multipolygon
    /// from WGS84 to BNG fails, or [`N3gbError::InvalidZoomLevel`] if
    /// `zoom_level` exceeds the maximum supported zoom level.
    pub fn from_wgs84_multipolygon(
        multipolygon: &MultiPolygon<f64>,
        zoom_level: u8,
        method: ConversionMethod,
    ) -> Result<Self, N3gbError> {
        let bng_multipolygon = convert_multipolygon_to_bng(multipolygon, method)?;
        Self::from_bng_multipolygon(&bng_multipolygon, zoom_level)
    }

    /// Keeps only cells matching the predicate, rebuilding the spatial index.
    fn retain<F>(self, predicate: F) -> Self
    where
        F: Fn(&HexCell) -> bool + Sync,
    {
        let cells: Vec<HexCell> = self
            .cells
            .into_par_iter()
            .filter(|cell| predicate(cell))
            .collect();
        Self::new(cells, self.zoom_level)
    }

    /// Returns the zoom level of this grid.
    ///
    /// # Returns
    ///
    /// The zoom level shared by all cells in this grid.
    pub fn zoom_level(&self) -> u8 {
        self.zoom_level
    }

    /// Returns the number of cells in this grid.
    ///
    /// # Returns
    ///
    /// The count of cells in this grid.
    pub fn len(&self) -> usize {
        self.cells.len()
    }

    /// Returns `true` if the grid contains no cells.
    ///
    /// # Returns
    ///
    /// `true` if the grid contains no cells, `false` otherwise.
    pub fn is_empty(&self) -> bool {
        self.cells.is_empty()
    }

    /// Returns a slice of all cells in this grid.
    ///
    /// # Returns
    ///
    /// A slice borrowing all cells in this grid.
    pub fn cells(&self) -> &[HexCell] {
        &self.cells
    }

    /// Returns an iterator over the cells in this grid.
    ///
    /// # Returns
    ///
    /// An iterator yielding a reference to each cell in this grid.
    pub fn iter(&self) -> impl Iterator<Item = &HexCell> {
        self.cells.iter()
    }

    /// Looks up which hex cell a point falls in.
    ///
    /// Converts the point to a grid `(row, col)` address, then uses the
    /// spatial index to find the cell at that address in O(1) time.
    ///
    /// Returns `Some(&HexCell)` if found, or `None` if the point falls
    /// outside this grid's extent.
    ///
    /// # Arguments
    ///
    /// * `point` - The point to locate, in BNG (EPSG:27700) coordinates.
    ///
    /// # Returns
    ///
    /// `Some(&HexCell)` containing the point, or `None` if no cell in this
    /// grid contains it.
    pub fn get_cell_at(&self, point: &Point<f64>) -> Option<&HexCell> {
        let (row, col) = point_to_row_col(point, self.zoom_level).ok()?;
        self.index.get(&(row, col)).map(|&i| &self.cells[i])
    }

    /// Converts all cells to hexagonal polygons.
    ///
    /// # Returns
    ///
    /// A vector containing the hexagonal polygon for each cell in this grid.
    pub fn to_polygons(&self) -> Vec<Polygon<f64>> {
        self.cells
            .par_iter()
            .map(|cell| cell.to_polygon())
            .collect()
    }

    /// Returns cells matching the given predicate.
    ///
    /// # Arguments
    ///
    /// * `predicate` - A closure called with each cell; cells for which it
    ///   returns `true` are included.
    ///
    /// # Returns
    ///
    /// A vector of references to the cells that satisfy the predicate.
    pub fn filter<F>(&self, predicate: F) -> Vec<&HexCell>
    where
        F: Fn(&HexCell) -> bool,
    {
        self.cells.iter().filter(|cell| predicate(cell)).collect()
    }

    /// Converts all cell centers to an Arrow PointArray.
    ///
    /// # Returns
    ///
    /// A [`PointArray`] containing the center point of each cell in this grid.
    pub fn to_arrow_points(&self) -> PointArray {
        self.cells.to_arrow_points()
    }

    /// Converts all cells to an Arrow PolygonArray.
    ///
    /// # Returns
    ///
    /// A [`PolygonArray`] containing the hexagonal polygon for each cell in
    /// this grid.
    pub fn to_arrow_polygons(&self) -> PolygonArray {
        self.cells.to_arrow_polygons()
    }

    /// Converts all cells to an Arrow RecordBatch with all attributes.
    ///
    /// # Returns
    ///
    /// A [`RecordBatch`] containing every cell's attributes.
    ///
    /// # Errors
    ///
    /// Returns [`N3gbError::IoError`] if the record batch cannot be
    /// constructed.
    pub fn to_record_batch(&self) -> Result<RecordBatch, N3gbError> {
        self.cells.to_record_batch()
    }

    /// Writes all cells to a GeoParquet file.
    ///
    /// # Arguments
    ///
    /// * `path` - The filesystem path to write the GeoParquet file to.
    ///
    /// # Returns
    ///
    /// `()` on success, once all cells have been written to the file.
    ///
    /// # Errors
    ///
    /// Returns [`N3gbError::IoError`] if the file cannot be written.
    pub fn to_geoparquet(&self, path: impl AsRef<Path>) -> Result<(), N3gbError> {
        self.cells.to_geoparquet(path)
    }
}

impl<'a> IntoIterator for &'a HexGrid {
    type Item = &'a HexCell;
    type IntoIter = std::slice::Iter<'a, HexCell>;

    fn into_iter(self) -> Self::IntoIter {
        self.cells.iter()
    }
}

impl IntoIterator for HexGrid {
    type Item = HexCell;
    type IntoIter = std::vec::IntoIter<HexCell>;

    fn into_iter(self) -> Self::IntoIter {
        self.cells.into_iter()
    }
}

/// Builder for constructing a [`HexGrid`].
///
/// Remeber that the builder struct is there to collect and normalise inputs (converting to BNG if needed)
/// then .build() passes the final object into the HexGrid constructors
/// this does the actual work — generating cells, filtering, building the HashMap index, etc.
///
/// It returns a result - either an error or the actual hex grid
///
/// # Example
///
/// ```
/// use n3gb_rs::HexGrid;
///
/// # fn main() -> Result<(), n3gb_rs::N3gbError> {
/// let grid = HexGrid::builder()
///     .zoom_level(10)
///     .bng_extent(&(457000.0, 339500.0), &(458000.0, 340500.0))
///     .build()?;
/// # Ok(())
/// # }
/// ```
#[derive(Debug, Default, Clone)]
pub struct HexGridBuilder {
    zoom_level: Option<u8>,
    min_x: Option<f64>,
    min_y: Option<f64>,
    max_x: Option<f64>,
    max_y: Option<f64>,
    polygon: Option<Polygon<f64>>,
    multipolygon: Option<MultiPolygon<f64>>,
    conversion_method: ConversionMethod,
}

impl HexGridBuilder {
    /// Creates a new builder with no parameters set.
    ///
    /// # Returns
    ///
    /// A fresh `HexGridBuilder` with no parameters set.
    pub fn new() -> Self {
        Self::default()
    }

    /// Sets the zoom level (0-15).
    ///
    /// # Arguments
    ///
    /// * `zoom_level` - The zoom level for the generated cells.
    ///
    /// # Returns
    ///
    /// The updated builder, for chaining.
    pub fn zoom_level(mut self, zoom_level: u8) -> Self {
        self.zoom_level = Some(zoom_level);
        self
    }

    /// Sets the WGS84→BNG conversion backend.
    ///
    /// Must be called before any `wgs84_*` input method.
    /// Defaults to [`ConversionMethod::Proj`].
    ///
    /// # Arguments
    ///
    /// * `method` - The conversion backend used to project from WGS84 to BNG.
    ///
    /// # Returns
    ///
    /// The updated builder, for chaining.
    pub fn conversion_method(mut self, method: ConversionMethod) -> Self {
        self.conversion_method = method;
        self
    }

    /// Sets the extent from a `geo_types::Rect` in BNG coordinates.
    ///
    /// # Arguments
    ///
    /// * `rect` - The bounding rectangle, in BNG (EPSG:27700) coordinates.
    ///
    /// # Returns
    ///
    /// The updated builder, for chaining.
    pub fn rect(mut self, rect: &Rect<f64>) -> Self {
        self.min_x = Some(rect.min().x);
        self.min_y = Some(rect.min().y);
        self.max_x = Some(rect.max().x);
        self.max_y = Some(rect.max().y);
        self
    }

    /// Set extent from British National Grid coordinates
    ///
    /// # Example
    /// ```
    /// use n3gb_rs::HexGrid;
    ///
    /// # fn main() -> Result<(), n3gb_rs::N3gbError> {
    /// let grid = HexGrid::builder()
    ///     .zoom_level(10)
    ///     .bng_extent(&(457000.0, 339500.0), &(458000.0, 340500.0))
    ///     .build()?;
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Arguments
    ///
    /// * `min` - The minimum (lower-left) corner, in BNG (EPSG:27700) coordinates.
    /// * `max` - The maximum (upper-right) corner, in BNG (EPSG:27700) coordinates.
    ///
    /// # Returns
    ///
    /// The updated builder, for chaining.
    pub fn bng_extent(mut self, min: &impl Coordinate, max: &impl Coordinate) -> Self {
        self.min_x = Some(min.x());
        self.min_y = Some(min.y());
        self.max_x = Some(max.x());
        self.max_y = Some(max.y());
        self
    }

    /// Set extent from WGS84 (lon/lat) coordinates
    ///
    /// # Example
    /// ```
    /// use n3gb_rs::HexGrid;
    ///
    /// # fn main() -> Result<(), n3gb_rs::N3gbError> {
    /// let grid = HexGrid::builder()
    ///     .zoom_level(10)
    ///     .wgs84_extent(&(-2.3, 53.4), &(-2.2, 53.5))?
    ///     .build()?;
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Arguments
    ///
    /// * `min` - The minimum (lower-left) corner, in WGS84 (lon/lat) coordinates.
    /// * `max` - The maximum (upper-right) corner, in WGS84 (lon/lat) coordinates.
    ///
    /// # Returns
    ///
    /// The updated builder, for chaining.
    ///
    /// # Errors
    ///
    /// Returns [`N3gbError::ProjectionError`] if projecting the corners from
    /// WGS84 to BNG fails.
    pub fn wgs84_extent(
        mut self,
        min: &impl Coordinate,
        max: &impl Coordinate,
    ) -> Result<Self, N3gbError> {
        let min_bng = convert_to_bng(min, self.conversion_method)?;
        let max_bng = convert_to_bng(max, self.conversion_method)?;
        self.min_x = Some(min_bng.x());
        self.min_y = Some(min_bng.y());
        self.max_x = Some(max_bng.x());
        self.max_y = Some(max_bng.y());
        Ok(self)
    }

    /// Sets the geometry from a polygon in BNG coordinates.
    ///
    /// When a polygon is set, the grid will only include cells that
    /// intersect the polygon, not the full bounding box.
    ///
    /// # Example
    /// ```
    /// use n3gb_rs::HexGrid;
    /// use geo_types::{Polygon, LineString, coord};
    ///
    /// # fn main() -> Result<(), n3gb_rs::N3gbError> {
    /// let polygon = Polygon::new(
    ///     LineString::from(vec![
    ///         coord! { x: 457000.0, y: 339500.0 },
    ///         coord! { x: 458000.0, y: 339500.0 },
    ///         coord! { x: 458000.0, y: 340500.0 },
    ///         coord! { x: 457000.0, y: 340500.0 },
    ///         coord! { x: 457000.0, y: 339500.0 },
    ///     ]),
    ///     vec![],
    /// );
    /// let grid = HexGrid::builder()
    ///     .zoom_level(10)
    ///     .bng_polygon(polygon)
    ///     .build()?;
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Arguments
    ///
    /// * `polygon` - The polygon, in BNG (EPSG:27700) coordinates.
    ///
    /// # Returns
    ///
    /// The updated builder, for chaining.
    pub fn bng_polygon(mut self, polygon: Polygon<f64>) -> Self {
        self.polygon = Some(polygon);
        self
    }

    /// Sets the geometry from a polygon in WGS84 (lon/lat) coordinates.
    ///
    /// Projects the polygon to BNG, then filters cells to those
    /// that intersect the polygon.
    ///
    /// # Example
    /// ```
    /// use n3gb_rs::HexGrid;
    /// use geo_types::{Polygon, LineString, coord};
    ///
    /// # fn main() -> Result<(), n3gb_rs::N3gbError> {
    /// let polygon = Polygon::new(
    ///     LineString::from(vec![
    ///         coord! { x: -2.3, y: 53.4 },
    ///         coord! { x: -2.2, y: 53.4 },
    ///         coord! { x: -2.2, y: 53.5 },
    ///         coord! { x: -2.3, y: 53.5 },
    ///         coord! { x: -2.3, y: 53.4 },
    ///     ]),
    ///     vec![],
    /// );
    /// let grid = HexGrid::builder()
    ///     .zoom_level(10)
    ///     .wgs84_polygon(polygon)?
    ///     .build()?;
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Arguments
    ///
    /// * `polygon` - The polygon, in WGS84 (lon/lat) coordinates.
    ///
    /// # Returns
    ///
    /// The updated builder, for chaining.
    ///
    /// # Errors
    ///
    /// Returns [`N3gbError::ProjectionError`] if projecting the polygon from
    /// WGS84 to BNG fails.
    pub fn wgs84_polygon(mut self, polygon: Polygon<f64>) -> Result<Self, N3gbError> {
        let bng_polygon = convert_polygon_to_bng(&polygon, self.conversion_method)?;
        self.polygon = Some(bng_polygon);
        Ok(self)
    }

    /// Sets the geometry from a multipolygon in BNG coordinates.
    ///
    /// When a multipolygon is set, the grid will only include cells that
    /// intersect any of the polygons, with duplicates removed.
    ///
    /// # Example
    /// ```
    /// use n3gb_rs::HexGrid;
    /// use geo_types::{MultiPolygon, Polygon, LineString, coord};
    ///
    /// # fn main() -> Result<(), n3gb_rs::N3gbError> {
    /// let poly1 = Polygon::new(
    ///     LineString::from(vec![
    ///         coord! { x: 457000.0, y: 339500.0 },
    ///         coord! { x: 457500.0, y: 339500.0 },
    ///         coord! { x: 457500.0, y: 340000.0 },
    ///         coord! { x: 457000.0, y: 340000.0 },
    ///         coord! { x: 457000.0, y: 339500.0 },
    ///     ]),
    ///     vec![],
    /// );
    /// let poly2 = Polygon::new(
    ///     LineString::from(vec![
    ///         coord! { x: 457500.0, y: 340000.0 },
    ///         coord! { x: 458000.0, y: 340000.0 },
    ///         coord! { x: 458000.0, y: 340500.0 },
    ///         coord! { x: 457500.0, y: 340500.0 },
    ///         coord! { x: 457500.0, y: 340000.0 },
    ///     ]),
    ///     vec![],
    /// );
    /// let mp = MultiPolygon::new(vec![poly1, poly2]);
    /// let grid = HexGrid::builder()
    ///     .zoom_level(10)
    ///     .bng_multipolygon(mp)
    ///     .build()?;
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Arguments
    ///
    /// * `multipolygon` - The multipolygon, in BNG (EPSG:27700) coordinates.
    ///
    /// # Returns
    ///
    /// The updated builder, for chaining.
    pub fn bng_multipolygon(mut self, multipolygon: MultiPolygon<f64>) -> Self {
        self.multipolygon = Some(multipolygon);
        self
    }

    /// Sets the geometry from a multipolygon in WGS84 (lon/lat) coordinates.
    ///
    /// Projects the multipolygon to BNG, then filters cells to those
    /// that intersect any of the polygons.
    ///
    /// # Example
    /// ```
    /// use n3gb_rs::HexGrid;
    /// use geo_types::{MultiPolygon, Polygon, LineString, coord};
    ///
    /// # fn main() -> Result<(), n3gb_rs::N3gbError> {
    /// let poly1 = Polygon::new(
    ///     LineString::from(vec![
    ///         coord! { x: -2.3, y: 53.4 },
    ///         coord! { x: -2.25, y: 53.4 },
    ///         coord! { x: -2.25, y: 53.45 },
    ///         coord! { x: -2.3, y: 53.45 },
    ///         coord! { x: -2.3, y: 53.4 },
    ///     ]),
    ///     vec![],
    /// );
    /// let poly2 = Polygon::new(
    ///     LineString::from(vec![
    ///         coord! { x: -2.25, y: 53.45 },
    ///         coord! { x: -2.2, y: 53.45 },
    ///         coord! { x: -2.2, y: 53.5 },
    ///         coord! { x: -2.25, y: 53.5 },
    ///         coord! { x: -2.25, y: 53.45 },
    ///     ]),
    ///     vec![],
    /// );
    /// let mp = MultiPolygon::new(vec![poly1, poly2]);
    /// let grid = HexGrid::builder()
    ///     .zoom_level(10)
    ///     .wgs84_multipolygon(mp)?
    ///     .build()?;
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Arguments
    ///
    /// * `multipolygon` - The multipolygon, in WGS84 (lon/lat) coordinates.
    ///
    /// # Returns
    ///
    /// The updated builder, for chaining.
    ///
    /// # Errors
    ///
    /// Returns [`N3gbError::ProjectionError`] if projecting the multipolygon
    /// from WGS84 to BNG fails.
    pub fn wgs84_multipolygon(
        mut self,
        multipolygon: MultiPolygon<f64>,
    ) -> Result<Self, N3gbError> {
        let bng_multipolygon = convert_multipolygon_to_bng(&multipolygon, self.conversion_method)?;
        self.multipolygon = Some(bng_multipolygon);
        Ok(self)
    }

    /// Builds the [`HexGrid`].
    ///
    /// # Returns
    ///
    /// The constructed [`HexGrid`], built from the multipolygon, polygon, or
    /// extent that was set on the builder.
    ///
    /// # Errors
    ///
    /// Returns [`N3gbError::InvalidZoomLevel`] if `zoom_level` exceeds the
    /// maximum supported zoom level, and propagates any error from the
    /// selected construction source.
    ///
    /// # Panics
    ///
    /// Panics if `zoom_level` has not been set, or if neither extent, polygon,
    /// nor multipolygon has been set.
    pub fn build(self) -> Result<HexGrid, N3gbError> {
        let zoom_level = self.zoom_level.expect("zoom_level must be set");

        match (self.multipolygon, self.polygon) {
            (Some(mp), _) => HexGrid::from_bng_multipolygon(&mp, zoom_level),
            (_, Some(p)) => HexGrid::from_bng_polygon(&p, zoom_level),
            (None, None) => {
                let min_x = self
                    .min_x
                    .expect("extent, polygon, or multipolygon must be set");
                let min_y = self
                    .min_y
                    .expect("extent, polygon, or multipolygon must be set");
                let max_x = self
                    .max_x
                    .expect("extent, polygon, or multipolygon must be set");
                let max_y = self
                    .max_y
                    .expect("extent, polygon, or multipolygon must be set");
                HexGrid::from_extent(min_x, min_y, max_x, max_y, zoom_level)
            }
        }
    }
}

/// Generates all hex cells that cover a bounding box.
///
/// This is the single entry point for all grid construction. Every public
/// constructor (`from_bng_extent`, `from_rect`, `from_bng_polygon`, etc.)
/// ultimately calls this function.
///
/// ## How it works
///
/// 1. Converts the four corners of the bounding box to grid `(row, col)` addresses.
/// 2. Takes the min/max of those to get the full row and column range.
/// 3. Iterates every `(row, col)` pair in that range (in parallel via Rayon).
/// 4. For each pair, computes the hex center point and generates a `HexCell`.
/// 5. Filters out any cells whose center falls outside the BNG grid extents.
///
/// ## Errors
///
/// Returns `Err(InvalidZoomLevel)` if `zoom_level` exceeds `MAX_ZOOM_LEVEL`.
fn generate_cells_for_extent(
    min_x: f64,
    min_y: f64,
    max_x: f64,
    max_y: f64,
    zoom_level: u8,
) -> Result<Vec<HexCell>, N3gbError> {
    let (ll_row, ll_col) = point_to_row_col(&(min_x, min_y), zoom_level)?;
    let (lr_row, lr_col) = point_to_row_col(&(max_x, min_y), zoom_level)?;
    let (ur_row, ur_col) = point_to_row_col(&(max_x, max_y), zoom_level)?;
    let (ul_row, ul_col) = point_to_row_col(&(min_x, max_y), zoom_level)?;

    let min_row = ll_row.min(lr_row).min(ur_row).min(ul_row);
    let max_row = ll_row.max(lr_row).max(ur_row).max(ul_row);
    let min_col = ll_col.min(lr_col).min(ur_col).min(ul_col);
    let max_col = ll_col.max(lr_col).max(ur_col).max(ul_col);

    let row_cols: Vec<(i64, i64)> = (min_row..=max_row)
        .flat_map(|row| (min_col..=max_col).map(move |col| (row, col)))
        .collect();

    let cells: Vec<HexCell> = row_cols
        .into_par_iter()
        .filter_map(|(row, col)| {
            let center = row_col_to_center(row, col, zoom_level).ok()?;

            if center.x() < GRID_EXTENTS[0] || center.y() < GRID_EXTENTS[1] {
                return None;
            }

            let id = generate_hex_identifier(center.x(), center.y(), zoom_level);
            Some(HexCell::new(id, center, zoom_level, row, col))
        })
        .collect();

    Ok(cells)
}

#[cfg(test)]
mod tests {
    use super::*;
    use geo_types::{coord, point};

    #[test]
    fn test_hex_grid_from_bng_extent() -> Result<(), N3gbError> {
        let grid = HexGrid::from_bng_extent(&(457000.0, 339500.0), &(458000.0, 340500.0), 10)?;
        assert!(!grid.is_empty());
        assert_eq!(grid.zoom_level(), 10);

        for cell in grid.iter() {
            assert_eq!(cell.zoom_level, 10);
        }
        Ok(())
    }

    #[test]
    fn test_hex_grid_from_rect() -> Result<(), N3gbError> {
        let rect = Rect::new(
            coord! { x: 457000.0, y: 339500.0 },
            coord! { x: 458000.0, y: 340500.0 },
        );
        let grid = HexGrid::from_rect(&rect, 10)?;
        assert!(!grid.is_empty());
        Ok(())
    }

    #[test]
    fn test_hex_grid_builder() -> Result<(), N3gbError> {
        let grid = HexGrid::builder()
            .zoom_level(10)
            .bng_extent(&(457000.0, 339500.0), &(458000.0, 340500.0))
            .build()?;

        assert!(!grid.is_empty());
        assert_eq!(grid.zoom_level(), 10);
        Ok(())
    }

    #[test]
    fn test_hex_grid_builder_with_rect() -> Result<(), N3gbError> {
        let rect = Rect::new(
            coord! { x: 457000.0, y: 339500.0 },
            coord! { x: 458000.0, y: 340500.0 },
        );
        let grid = HexGrid::builder().zoom_level(10).rect(&rect).build()?;

        assert!(!grid.is_empty());
        Ok(())
    }

    #[test]
    fn test_get_cell_at() -> Result<(), N3gbError> {
        let grid = HexGrid::from_bng_extent(&(457000.0, 339500.0), &(458000.0, 340500.0), 10)?;
        let pt = point! { x: 457500.0, y: 340000.0 };

        let cell = grid.get_cell_at(&pt);
        assert!(cell.is_some());
        Ok(())
    }

    #[test]
    fn test_filter_cells() -> Result<(), N3gbError> {
        let grid = HexGrid::from_bng_extent(&(457000.0, 339500.0), &(458000.0, 340500.0), 10)?;

        let filtered = grid.filter(|cell| cell.easting() > 457500.0);
        assert!(!filtered.is_empty());
        Ok(())
    }

    #[test]
    fn test_to_polygons() -> Result<(), N3gbError> {
        let grid = HexGrid::from_bng_extent(&(457000.0, 339500.0), &(458000.0, 340500.0), 10)?;
        let polygons = grid.to_polygons();

        assert_eq!(polygons.len(), grid.len());
        Ok(())
    }

    #[test]
    fn test_invalid_zoom_level() {
        let result = HexGrid::from_bng_extent(&(457000.0, 339500.0), &(458000.0, 340500.0), 20);
        assert!(matches!(result, Err(N3gbError::InvalidZoomLevel(20))));
    }
}