versatiles_container 3.7.0

//! Converts tile data between formats, compressions, and coordinate conventions.
//!
//! This module provides:
//! - [`TilesConverterParameters`]: declarative knobs (bbox filter, compression override, `flip_y`, `swap_xy`)
//! - [`TilesConvertReader`]: an adapter that applies those conversions while reading
//! - [`convert_tiles_container`]: a convenience function to convert and write to a target path using a [`ContainerRegistry`]
//!
//! ## Coordinate transforms
//! - `flip_y`: inverts Y within the zoom level (useful to switch between TMS and XYZ-like schemes)
//! - `swap_xy`: swaps X and Y (occasionally useful for sources with unconventional axis ordering)
//!
//! ## Example
//! ```rust
//! use versatiles_container::*;
//! use versatiles_core::*;
//! use std::sync::Arc;
//!
//! #[tokio::main]
//! async fn main() -> anyhow::Result<()> {
//!
//!     // Create runtime with default settings
//!     let runtime = TilesRuntime::default();
//!
//!     // Open the source
//!     let reader = runtime.get_reader_from_str("../testdata/berlin.mbtiles").await?;
//!
//!     // Limit to a bbox pyramid and keep source compression;
//!     // you could also set `tile_compression: Some(TileCompression::Brotli)` to re-encode.
//!     let converter_params = TilesConverterParameters {
//!         bbox_pyramid: Some(TileBBoxPyramid::new_full_up_to(8)),
//!         ..Default::default()
//!     };
//!
//!     // Convert and write
//!     let path_versatiles = std::env::temp_dir().join("temp2.versatiles");
//!     convert_tiles_container(reader, converter_params, &path_versatiles.as_path(), runtime).await?;
//!
//!     println!("Wrote {:?}", path_versatiles);
//!     Ok(())
//! }
//! ```

use crate::{SharedTileSource, SourceType, Tile, TileSource, TileSourceMetadata, TilesRuntime};
use anyhow::Result;
use async_trait::async_trait;
use std::{path::Path, sync::Arc};
use versatiles_core::{GeoBBox, TileBBox, TileBBoxPyramid, TileCompression, TileCoord, TileJSON, TileStream};
use versatiles_derive::context;

/// Parameters that control how tiles are transformed during reading/conversion.
///
/// These options affect coordinate handling, the subset of tiles traversed, and
/// whether tile payloads are re-encoded with a different compression.
///
/// Use with [`TilesConvertReader::new_from_reader`] or the helper
/// [`convert_tiles_container`].
#[derive(Debug)]
pub struct TilesConverterParameters {
	/// Optional spatial/zoom restriction. When set, only tiles inside the given
	/// [`TileBBoxPyramid`] are read/streamed. Existing bounds are intersected with this.
	pub bbox_pyramid: Option<TileBBoxPyramid>,
	/// Optional geographic bounding box filter. When set, existing tilejson bounds are
	/// intersected with this bbox rather than being recalculated from the pyramid.
	pub geo_bbox: Option<GeoBBox>,
	/// Optional compression override. When set, tile payloads are re-encoded to this
	/// [`TileCompression`] (e.g., Gzip → Brotli). If `None`, the source compression is kept.
	pub tile_compression: Option<TileCompression>,
	/// If `true`, flip the Y coordinate within the zoom level (TMS ↔ XYZ-like).
	pub flip_y: bool,
	/// If `true`, swap X and Y coordinates.
	pub swap_xy: bool,
}

impl Default for TilesConverterParameters {
	/// Returns parameters that perform no geometric change and keep source compression.
	fn default() -> Self {
		TilesConverterParameters {
			bbox_pyramid: None,
			geo_bbox: None,
			tile_compression: None,
			flip_y: false,
			swap_xy: false,
		}
	}
}

/// Converts tiles from the given reader and writes them to `path` using the provided runtime.
///
/// The conversion is applied by wrapping `reader` in a [`TilesConvertReader`] configured by `cp`.
///
/// ### Arguments
/// - `reader`: Source container reader.
/// - `cp`: Conversion parameters (bbox filter, compression override, `flip_y`, `swap_xy`).
/// - `path`: Output path; the format is inferred from its extension (or directory).
/// - `runtime`: Runtime configuration providing registry, cache, and event system.
///
/// ### Errors
/// Returns an error if reading tiles fails, if writing to the destination fails,
/// or if no suitable writer is registered for the output path.
///
/// ### Example
/// See the module-level example.
#[context("Converting tiles from reader to file")]
pub async fn convert_tiles_container(
	reader: SharedTileSource,
	cp: TilesConverterParameters,
	path: &Path,
	runtime: TilesRuntime,
) -> Result<()> {
	runtime.events().step("Starting conversion".to_string());

	let converter = TilesConvertReader::new_from_reader(reader, cp)?;
	runtime.write_to_path(converter.into_shared(), path).await?;

	runtime.events().step("Conversion complete".to_string());
	Ok(())
}

/// Reader adapter that applies coordinate transforms, bbox filtering, and optional
/// compression changes on-the-fly.
///
/// This type implements [`TileSource`], so it can be used anywhere a normal
/// reader is expected. Use [`TilesConvertReader::new_from_reader`] to wrap an
/// existing reader.
#[derive(Debug)]
pub struct TilesConvertReader {
	reader: SharedTileSource,
	converter_parameters: TilesConverterParameters,
	reader_metadata: TileSourceMetadata,
	tilejson: TileJSON,
}

impl TilesConvertReader {
	/// Wraps an existing reader so that reads are transformed according to `cp`.
	///
	/// Updates the internal [`TileSourceMetadata`] and [`TileJSON`] to reflect
	/// the chosen bbox, axis transforms, and compression.
	///
	/// ### Errors
	/// Propagates errors from querying/deriving parameters or updating metadata.
	#[context("Creating converter reader from existing reader")]
	pub fn new_from_reader(reader: SharedTileSource, cp: TilesConverterParameters) -> Result<TilesConvertReader> {
		let rp: TileSourceMetadata = reader.metadata().to_owned();
		let mut new_rp: TileSourceMetadata = rp.clone();

		if cp.flip_y {
			new_rp.bbox_pyramid.flip_y();
		}
		if cp.swap_xy {
			new_rp.bbox_pyramid.swap_xy();
		}

		if let Some(bbox_pyramid) = &cp.bbox_pyramid {
			new_rp.bbox_pyramid.intersect(bbox_pyramid);
		}

		if let Some(tile_compression) = cp.tile_compression {
			new_rp.tile_compression = tile_compression;
		}

		let mut tilejson = reader.tilejson().clone();

		if let Some(ref geo_bbox) = cp.geo_bbox {
			// Intersect existing tilejson bounds with the given geo bbox
			if let Some(ref mut bounds) = tilejson.bounds {
				bounds.intersect(geo_bbox);
			} else {
				tilejson.bounds = Some(*geo_bbox);
			}
			tilejson.center = None;
		}
		new_rp.update_tilejson(&mut tilejson);

		Ok(TilesConvertReader {
			reader,
			converter_parameters: cp,
			reader_metadata: new_rp,
			tilejson,
		})
	}
}

#[async_trait]
impl TileSource for TilesConvertReader {
	fn source_type(&self) -> Arc<SourceType> {
		SourceType::new_processor("TilesConvertReader", self.reader.source_type())
	}

	fn metadata(&self) -> &TileSourceMetadata {
		&self.reader_metadata
	}

	fn tilejson(&self) -> &TileJSON {
		&self.tilejson
	}

	async fn get_tile(&self, coord: &TileCoord) -> Result<Option<Tile>> {
		let mut coord = *coord;

		if self.converter_parameters.flip_y {
			coord.flip_y();
		}

		if self.converter_parameters.swap_xy {
			coord.swap_xy();
		}

		let tile = self.reader.get_tile(&coord).await?;

		let Some(mut tile) = tile else { return Ok(None) };

		if let Some(compression) = self.converter_parameters.tile_compression {
			tile.change_compression(compression)?;
		}

		Ok(Some(tile))
	}

	async fn get_tile_stream(&self, mut bbox: TileBBox) -> Result<TileStream<'static, Tile>> {
		if self.converter_parameters.swap_xy {
			bbox.swap_xy();
		}
		if self.converter_parameters.flip_y {
			bbox.flip_y();
		}

		let mut stream = self.reader.get_tile_stream(bbox).await?;

		let flip_y = self.converter_parameters.flip_y;
		let swap_xy = self.converter_parameters.swap_xy;

		if flip_y || swap_xy {
			stream = stream.map_coord(move |mut coord| {
				if flip_y {
					coord.flip_y();
				}
				if swap_xy {
					coord.swap_xy();
				}
				coord
			});
		}

		if let Some(tile_compression) = self.converter_parameters.tile_compression {
			stream = stream
				.map_parallel_try(move |_coord, mut tile| {
					tile.change_compression(tile_compression)?;
					Ok(tile)
				})
				.unwrap_results();
		}

		Ok(stream)
	}
}

/// Integration tests verifying bbox intersection, coordinate transforms, traversal order,
/// and compression override behavior.
#[cfg(test)]
mod tests {
	use super::*;
	use crate::{MockReader, Traversal, VersaTilesReader};
	use assert_fs::NamedTempFile;
	use rstest::rstest;
	use versatiles_core::{
		TileCompression::*,
		TileFormat::{self, *},
	};

	fn new_bbox(b: [u32; 4]) -> TileBBoxPyramid {
		let mut pyramid = TileBBoxPyramid::new_empty();
		pyramid.include_bbox(&TileBBox::from_min_and_max(3, b[0], b[1], b[2], b[3]).unwrap());
		pyramid
	}

	fn get_mock_reader(tf: TileFormat, tc: TileCompression) -> SharedTileSource {
		let bbox_pyramid = TileBBoxPyramid::new_full_up_to(4);
		let reader_metadata = TileSourceMetadata::new(tf, tc, bbox_pyramid, Traversal::ANY);
		MockReader::new_mock(reader_metadata).unwrap().into_shared()
	}

	#[rstest]
	#[case(false, false, [2, 3, 4, 5], "23 33 43 24 34 25 35 44 45")]
	#[case(false, true, [2, 3, 5, 4], "32 33 34 35 42 43 44 45")]
	#[case(true, false, [2, 3, 4, 6], "24 34 44 23 33 22 32 21 31 43 42 41")]
	#[case(true, true, [2, 3, 6, 4], "35 34 33 32 31 45 44 43 42 41")]
	#[tokio::test]
	async fn bbox_and_tile_order(
		#[case] flip_y: bool,
		#[case] swap_xy: bool,
		#[case] bbox_out: [u32; 4],
		#[case] tile_list: &str,
	) -> Result<()> {
		let pyramid_in = new_bbox([0, 1, 4, 5]);
		let pyramid_convert = new_bbox([2, 3, 7, 7]);
		let pyramid_out = new_bbox(bbox_out);

		let reader_metadata = TileSourceMetadata::new(JSON, Uncompressed, pyramid_in, Traversal::ANY);
		let reader = MockReader::new_mock(reader_metadata)?.into_shared();

		let temp_file = NamedTempFile::new("test.versatiles")?;
		let runtime = TilesRuntime::default();

		let cp = TilesConverterParameters {
			bbox_pyramid: Some(pyramid_convert),
			geo_bbox: None,
			flip_y,
			swap_xy,
			tile_compression: None,
		};
		convert_tiles_container(reader, cp, &temp_file, runtime.clone()).await?;

		let reader_out = VersaTilesReader::open_path(&temp_file, runtime).await?;
		let parameters_out = reader_out.metadata();
		let tile_compression_out = parameters_out.tile_compression;
		assert_eq!(parameters_out.bbox_pyramid, pyramid_out);

		let bbox = pyramid_out.get_level_bbox(3);
		let mut tiles: Vec<String> = Vec::new();
		for coord in bbox.iter_coords_zorder() {
			let mut text = reader_out
				.get_tile(&coord)
				.await?
				.unwrap()
				.into_blob(tile_compression_out)?
				.to_string();
			text = text
				.replace("{\"z\":3,\"x\":", "")
				.replace(",\"y\":", "")
				.replace('}', "");
			tiles.push(text);
		}
		let tiles = tiles.join(" ");
		assert_eq!(tiles, tile_list);

		Ok(())
	}

	#[test]
	fn test_tiles_converter_parameters_new() {
		let cp = TilesConverterParameters {
			bbox_pyramid: Some(TileBBoxPyramid::new_full_up_to(1)),
			geo_bbox: None,
			flip_y: true,
			swap_xy: true,
			tile_compression: None,
		};

		assert!(cp.bbox_pyramid.is_some());
		assert!(cp.flip_y);
		assert!(cp.swap_xy);
	}

	#[test]
	fn test_tiles_converter_parameters_default() {
		let cp = TilesConverterParameters::default();

		assert_eq!(cp.bbox_pyramid, None);
		assert!(!cp.flip_y);
		assert!(!cp.swap_xy);
	}

	#[test]
	fn test_tiles_convert_reader_new_from_reader() {
		let reader = get_mock_reader(MVT, Uncompressed);
		let cp = TilesConverterParameters::default();

		let tcr = TilesConvertReader::new_from_reader(reader, cp).unwrap();

		assert_eq!(tcr.reader.source_type().to_string(), "container 'dummy' ('dummy')");
		assert_eq!(tcr.source_type().to_string(), "processor 'TilesConvertReader'");
	}

	#[tokio::test]
	async fn test_get_tile() -> Result<()> {
		let reader = get_mock_reader(MVT, Uncompressed);
		let cp = TilesConverterParameters::default();
		let tcr = TilesConvertReader::new_from_reader(reader, cp)?;

		let coord = TileCoord::new(0, 0, 0)?;
		let data = tcr.get_tile(&coord).await?;
		assert!(data.is_some());

		Ok(())
	}

	#[tokio::test]
	async fn test_flip_y_and_swap_xy() -> Result<()> {
		let reader = get_mock_reader(MVT, Uncompressed);
		let cp = TilesConverterParameters {
			flip_y: true,
			swap_xy: true,
			..Default::default()
		};
		let tcr = TilesConvertReader::new_from_reader(reader, cp)?;

		let mut coord = TileCoord::new(4, 5, 6)?;
		let data = tcr.get_tile(&coord).await?;
		assert!(data.is_some());

		coord.flip_y();
		coord.swap_xy();
		let data_flipped = tcr.get_tile(&coord).await?;
		assert_eq!(data, data_flipped);

		Ok(())
	}

	#[test]
	fn test_geo_bbox_intersects_existing_tilejson_bounds() {
		// Source has bounds covering a wide area
		let source_bounds = GeoBBox::new(10.0, 50.0, 15.0, 55.0).unwrap();
		let bbox_pyramid = TileBBoxPyramid::new_full_up_to(4);
		let reader_metadata = TileSourceMetadata::new(MVT, Uncompressed, bbox_pyramid, Traversal::ANY);
		let mut reader = MockReader::new_mock(reader_metadata).unwrap();
		reader.tilejson_mut().bounds = Some(source_bounds);
		let reader = reader.into_shared();

		// User specifies a bbox that partially overlaps
		let filter_bbox = GeoBBox::new(12.0, 52.0, 20.0, 60.0).unwrap();
		let mut filter_pyramid = TileBBoxPyramid::new_full();
		filter_pyramid.intersect_geo_bbox(&filter_bbox).unwrap();

		let cp = TilesConverterParameters {
			bbox_pyramid: Some(filter_pyramid),
			geo_bbox: Some(filter_bbox),
			..Default::default()
		};
		let tcr = TilesConvertReader::new_from_reader(reader, cp).unwrap();
		let bounds = tcr.tilejson().bounds.unwrap();

		// Bounds should be the intersection: [12.0, 52.0, 15.0, 55.0]
		assert_eq!(bounds.as_tuple(), (12.0, 52.0, 15.0, 55.0));
	}

	#[test]
	fn test_geo_bbox_without_existing_bounds_uses_pyramid() {
		// Source has NO explicit bounds in tilejson
		let bbox_pyramid = TileBBoxPyramid::new_full_up_to(4);
		let reader_metadata = TileSourceMetadata::new(MVT, Uncompressed, bbox_pyramid, Traversal::ANY);
		let reader = MockReader::new_mock(reader_metadata).unwrap().into_shared();

		let filter_bbox = GeoBBox::new(12.0, 52.0, 14.0, 54.0).unwrap();
		let mut filter_pyramid = TileBBoxPyramid::new_full();
		filter_pyramid.intersect_geo_bbox(&filter_bbox).unwrap();

		let cp = TilesConverterParameters {
			bbox_pyramid: Some(filter_pyramid),
			geo_bbox: Some(filter_bbox),
			..Default::default()
		};
		let tcr = TilesConvertReader::new_from_reader(reader, cp).unwrap();

		// Bounds should be set from the pyramid (since no existing bounds to intersect)
		assert!(tcr.tilejson().bounds.is_some());
	}
}