geonative_image/lib.rs
1//! # geonative-image
2//!
3//! Pure-Rust reader for raster images with world-file sidecars — JPG and
4//! PNG with `.jgw` / `.pgw` / `.wld` next to them.
5//!
6//! ## What v0.1 covers
7//!
8//! - **JPEG** decode via `jpeg-decoder` (L8 grayscale + RGB24)
9//! - **PNG** decode via `png` (8-bit Grayscale / Grayscale+Alpha / RGB / RGBA)
10//! - **World files** (`.jgw` / `.pgw` / `.tfw` / `.wld`) — 6-line ASCII
11//! parsed into a [`geonative_core::raster::GeoTransform`]
12//! - **Caller-supplied CRS** — world files don't carry CRS, so the caller
13//! passes one via [`ImageRaster::open_with_crs`] (or accepts
14//! [`geonative_core::Crs::Unknown`] via the basic [`ImageRaster::open`])
15//! - Implements [`geonative_core::raster::RasterLayer`] — interchangeable
16//! with `geonative-geotiff::GeoTiff` in `geonative-convert`'s
17//! `RasterSource` dispatch
18//!
19//! ## Memory note
20//!
21//! These formats don't tile internally — `open` decodes the whole image
22//! into memory. For large inputs (multi-GB satellite imagery), the
23//! recommended workflow is to convert to COG once:
24//!
25//! ```bash
26//! geonative convert big.jpg big.cog
27//! ```
28//!
29//! Then serve from the COG via `geonative-geotiff`'s mmap-backed reader —
30//! that path is Pi-friendly regardless of source size.
31//!
32//! ## Usage
33//!
34//! ```no_run
35//! use geonative_core::Crs;
36//! use geonative_core::raster::RasterLayer;
37//! use geonative_image::ImageRaster;
38//!
39//! // upload.png is sitting next to upload.pgw on disk
40//! let img = ImageRaster::open_with_crs("upload.png", Crs::Epsg(4326))?;
41//! let p = img.profile();
42//! println!("{}×{} px, {} bands", p.width, p.height, p.bands.len());
43//! let tile = img.read_tile(0, 0, 0)?;
44//! # Ok::<(), Box<dyn std::error::Error>>(())
45//! ```
46
47#![forbid(unsafe_code)]
48#![warn(missing_debug_implementations)]
49
50pub mod dataset;
51pub mod error;
52pub mod worldfile;
53
54pub use dataset::{ImageKind, ImageRaster};
55pub use error::{ImageError, Result};
56
57pub const VERSION: &str = env!("CARGO_PKG_VERSION");