1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
//! # EORST - Earth Observation and Remote Sensing Toolkit
//!
//! A Rust library for processing geospatial raster data.
//!
//! ## Quick Start
//!
//! - **[Installation Guide](crate::standalone_docs::install)** - Set up with Nix (recommended)
//! - **[RasterDataset](crate::RasterDataset)** - Main data structure for working with rasters
//! - **[RasterDatasetBuilder](crate::RasterDatasetBuilder)** - Build datasets from various sources
//!
//! ## Getting Started
//!
//! ### Add EORST to your project
//!
//! ```toml
//! [dependencies]
//! eorst = "1.0"
//! ```
//!
//! ### Basic Usage
//!
//! ```rust,ignore
//! use std::path::PathBuf;
//! use chrono::NaiveDate;
//! use anyhow::Result;
//! use ndarray::Array4;
//!
//! use rss_core::{DEA, query::ImageQueryBuilder, qvf::Collection, utils::{Cmp, Intersects}};
//! use eorst::{types::BlockSize, RasterDatasetBuilder, RasterDataBlock};
//!
//! // ── 1. Query DEA Sentinel-2 ARD via STAC ──
//! let source = DEA.clone();
//! let query = ImageQueryBuilder::new(
//! source,
//! Collection::Sentinel2,
//! Intersects::Scene(vec!["56jns"]),
//! )
//! .canonical_bands(["red", "nir"])
//! .start_date(NaiveDate::parse_from_str("2021-01-01", "%Y-%m-%d")?)
//! .end_date(NaiveDate::parse_from_str("2021-06-01", "%Y-%m-%d")?)
//! .cloudcover((Cmp::Less, 5))
//! .build();
//!
//! let output_dir = PathBuf::from("/tmp/DEA_S2");
//! let _ = query.get(&output_dir, None, None)?; // download scenes
//!
//! // ── 2. Build a RasterDataset from the downloaded scenes ──
//! let scene_files: Vec<_> = std::fs::read_dir(&output_dir)?
//! .filter_map(|e| e.ok())
//! .filter(|e| e.path().extension().map_or(false, |ext| ext == "tif"))
//! .map(|e| e.path())
//! .collect();
//!
//! let rds = RasterDatasetBuilder::<u16>::from_sources(&scene_files)
//! .block_size(BlockSize { cols: 2048, rows: 2048 })
//! .build();
//!
//! // ── 3. Apply a parallel worker across all blocks ──
//! fn ndvi_worker(block: &RasterDataBlock<u16>) -> Result<Array4<i16>> {
//! let red = block.select_layers(&["red"])?;
//! let nir = block.select_layers(&["nir"])?;
//! let red_f: ndarray::Array4<f32> = red.data.mapv(|v| v as f32);
//! let nir_f: ndarray::Array4<f32> = nir.data.mapv(|v| v as f32);
//! let ndvi = ((&nir_f - &red_f) / (&nir_f + &red_f + 1e-10)) * 10000.0;
//! Ok(ndvi.mapv(|v| v as i16))
//! }
//!
//! rds.apply::<i16>(ndvi_worker, 8, &PathBuf::from("ndvi_output.tif"))?;
//! ```
//!
//! ## Core Types
//!
//! | Type | Description |
//! |------|-------------|
//! | [`RasterDataset<T>`](crate::RasterDataset) | Main data structure for raster data with parallel I/O, reprojection, sampling |
//! | [`RasterDatasetBuilder`](crate::RasterDatasetBuilder) | Builder for creating datasets from files, STAC queries, or scratch |
//! | [`RasterType`](crate::RasterType) | Trait for types that can be used as raster data (i16, f32, etc.) |
//! | [`ItemCollection`](crate::ItemCollection) | STAC item collection for cloud-native data access |
//!
//! ## Features
//!
//! - **Parallel I/O** - Read/write rasters efficiently using block-based processing
//! - **On-the-fly Reprojection** - Transform rasters between coordinate systems automatically
//! - **Point Sampling** - Extract raster values at point locations with spatial indexing
//! - **Time Series** - Handle multi-temporal data with dimension management
//! - **Band Math** - Perform per-pixel operations across bands
//! - **Block Processing** - Process rasters larger than memory using chunked operations
//!
//! ## Optional Features
//!
//! Enable additional capabilities in `cargo.toml`:
//!
//! ```toml
//! eorst = { version = "1.0", features = ["use_polars"] } # Polars DataFrame support
//! eorst = { version = "1.0", features = ["use_opencv"] } # OpenCV integration
//! eorst = { version = "1.0", features = ["use_lgbm"] } # LightGBM ML integration
//! eorst = { version = "1.0", features = ["use_rss"] } # RSS-specific utilities
//! ```
//!
//! ## CLI Tools
//!
//! EORST provides command-line tools (installed via Nix, see [Installation](crate::standalone_docs::install)):
//!
//! ```bash
//! # Extract raster values at point locations
//! eorst extract raster.tif points.gpkg id output.csv -b 1,2,3
//!
//! # Rasterize vectors to rasters
//! eo-rasterize vectors.gpkg output.tif -res 30
//! ```
//!
//! ## Examples
//!
//! The crate includes numerous examples demonstrating key functionality:
//!
//! | Example | Description |
//! |---------|-------------|
//! | [`example_3_process_image`](https://docs.rs/eorst/latest/eorst/example.3_process_image.html) | Basic image processing workflow |
//! | [`example_4_compute_ndvi`](https://docs.rs/eorst/latest/eorst/example.4_compute_ndvi.html) | Calculate NDVI vegetation index |
//! | [`example_5_compute_ndvi_over_time`](https://docs.rs/eorst/latest/eorst/example.5_compute_ndvi_over_time.html) | Time-series NDVI from STAC/DEA |
//! | [`example_rasterize`](https://docs.rs/eorst/latest/eorst/example.rasterize.html) | Burn vector geometries into rasters |
//! | [`example_11_zonal_stats`](https://docs.rs/eorst/latest/eorst/example.11_zonal_stats.html) | Zonal statistics with Polars |
//!
//! Run examples with:
//! ```bash
//! cargo run --example 3_process_image
//! cargo run --example 4_compute_ndvi
//! ```
//!
//! Build docs with examples (requires nightly):
//! ```bash
//! cargo +nightly doc -Zunstable-options -Zrustdoc-scrape-examples
//! ```
//!
//! ## Crate Status
//!
//! - Actively developing - breaking changes may occur between versions
//! - Main focus: support [JRSRP](https://www.jrsrp.org.au/) projects
//! - Developed for [Spatial Biocondition project](https://www.qld.gov.au/__data/assets/pdf_file/0015/230019/spatial-biocondition-vegetation-condition-map-for-queensland.pdf)
//!
//! ## License
//!
//! LGPL-3.0-or-later