versatiles_container/lib.rs
1//! `VersaTiles` Container: read, convert, and write tile containers.
2//!
3//! This crate exposes a small set of building blocks to work with map tile containers:
4//! - a registry that maps file extensions to readers/writers,
5//! - reader traits and adapters to stream tiles,
6//! - writer traits to serialize tiles,
7//! - utilities like caching and streaming combinators.
8//!
9//! It is designed for **runtime composition**: readers are object‑safe and can be wrapped
10//! by adapters (e.g. bbox filters, axis flips, compression overrides) and then written
11//! out with the appropriate writer inferred from the output path.
12//!
13//! # Quick start
14//! ```rust
15//! use versatiles_container::*;
16//! use versatiles_core::*;
17//! use std::sync::Arc;
18//!
19//! #[tokio::main]
20//! async fn main() -> anyhow::Result<()> {
21//! // Open a source container via the registry
22//! let runtime = TilesRuntime::default();
23//! let reader = runtime.reader_from_str("../testdata/berlin.mbtiles").await?;
24//!
25//! // Optionally adapt the reader: limit to a tile pyramid, keep compression as-is
26//! let params = TilesConverterParameters {
27//! tile_pyramid: Some(TilePyramid::new_full_up_to(8)),
28//! ..Default::default()
29//! };
30//! let reader = Arc::new(Box::new(TilesConvertReader::new_from_reader(reader, params).await?) as Box<dyn TileSource>);
31//!
32//! // Write to a target path; format is inferred from the extension
33//! let output = std::env::temp_dir().join("example.versatiles");
34//! runtime.write_to_path(reader, &output).await?;
35//! Ok(())
36//! }
37//! ```
38//!
39//! # Features
40//! - `cli`: enables human‑readable probing of containers and tiles.
41//! - `test`: helpers for integration tests in downstream crates.
42//!
43//! ## See also
44//! - [`ContainerRegistry`]: register custom reader/writer implementations at runtime
45//! - [`TileSource`], [`TilesWriter`]: object‑safe traits for IO
46//! - [`TilesConvertReader`], [`convert_tiles_container`]: convenience conversion helpers
47
48pub mod cache;
49/// Re‑exports in‑memory caches and helpers used by readers/writers.
50pub use cache::*;
51
52mod container;
53/// Re‑exports the container registry and common open/write helpers.
54pub use container::*;
55
56pub mod progress;
57pub use progress::*;
58
59/// Re‑exports progress tracking and event bus types.
60pub mod runtime;
61pub use runtime::*;
62
63mod traversal;
64pub use traversal::*;
65
66mod types;
67/// Re‑exports reader/writer traits, converters, and auxiliary types.
68pub use types::*;
69
70#[cfg(any(test, feature = "test"))]
71pub mod testing;