sarpro/
lib.rs

1#![doc = r#"
2SARPRO — a high-performance Sentinel-1 GRD processing toolkit.
3
4This crate provides a typed, ergonomic API for turning Sentinel-1 SAFE (GRD) products
5into high-quality GeoTIFFs or JPEGs, with optional resizing, padding, autoscaling, and
6polarization operations. It powers both the SARPRO CLI and GUI, and can be embedded in
7your own Rust applications.
8
9Stability
10---------
11The public library API is experimental in initial releases. It is built on top of a
12working MVP used by the CLI/GUI and is robust, but may evolve as the crate stabilizes.
13Breaking changes can occur.
14
15Requirements
16------------
17- GDAL development headers and runtime available on your system.
18- Rust 2024 edition toolchain.
19
20Add dependency
21--------------
22```toml
23[dependencies]
24sarpro = { version = "0.1", features = ["full"] }
25```
26
27Quick start: process a SAFE to a file
28-------------------------------------
29```rust,no_run
30use std::path::Path;
31use sarpro::{
32    process_safe_to_path,
33    ProcessingParams,
34    AutoscaleStrategy, BitDepthArg, OutputFormat, Polarization, InputFormat,
35};
36
37fn main() -> sarpro::Result<()> {
38    let params = ProcessingParams {
39        format: OutputFormat::TIFF,
40        input_format: InputFormat::Safe,
41        bit_depth: BitDepthArg::U16,
42        polarization: Polarization::Multiband,
43        autoscale: AutoscaleStrategy::Tamed,
44        target_crs: Some("EPSG:32630".to_string()),
45        resample_alg: Some("lanczos".to_string()),
46        size: Some(2048),
47        pad: true,
48    };
49
50    process_safe_to_path(
51        Path::new("/data/S1A_example.SAFE"),
52        Path::new("/out/product.tiff"),
53        &params,
54    )
55}
56```
57
58Process in-memory to `ProcessedImage`
59-------------------------------------
60```rust,no_run
61use std::path::Path;
62use sarpro::{
63    process_safe_to_buffer,
64    AutoscaleStrategy, BitDepth, OutputFormat, Polarization,
65};
66
67fn main() -> sarpro::Result<()> {
68    let img = process_safe_to_buffer(
69        Path::new("/data/S1A_example.SAFE"),
70        Polarization::Multiband,
71        AutoscaleStrategy::Tamed,
72        BitDepth::U8,
73        Some(1024),
74        true,
75        OutputFormat::JPEG,
76    )?;
77
78    // Use `img` buffers in your pipeline (TIFF grayscale/multiband or synthetic RGB JPEG)
79    // and/or consult its metadata.
80    Ok(())
81}
82```
83
84Typed save helpers (when you already have arrays)
85-------------------------------------------------
86```rust
87use std::path::Path;
88use ndarray::Array2;
89use num_complex::Complex;
90use sarpro::{
91    save_image, save_multiband_image,
92    AutoscaleStrategy, BitDepth, OutputFormat, ProcessingOperation,
93};
94
95fn save_single(processed: &Array2<Complex<f64>>) -> sarpro::Result<()> {
96    save_image(
97        processed,
98        Path::new("/out/single.tiff"),
99        OutputFormat::TIFF,
100        BitDepth::U16,
101        Some(2048),
102        None,                  // Optional SAFE metadata if available
103        true,
104        AutoscaleStrategy::Tamed,
105        ProcessingOperation::SingleBand,
106    )
107}
108
109fn save_dual(vv: &Array2<Complex<f64>>, vh: &Array2<Complex<f64>>) -> sarpro::Result<()> {
110    save_multiband_image(
111        vv,
112        vh,
113        Path::new("/out/multiband.tiff"),
114        OutputFormat::TIFF,
115        BitDepth::U8,
116        Some(1024),
117        None,
118        true,
119        AutoscaleStrategy::Tamed,
120        ProcessingOperation::MultibandVvVh,
121    )
122}
123```
124
125Batch helpers
126-------------
127```rust,no_run
128use std::path::Path;
129use sarpro::{
130    process_directory_to_path,
131    ProcessingParams, AutoscaleStrategy, BitDepthArg, OutputFormat, Polarization, InputFormat,
132};
133
134fn main() -> sarpro::Result<()> {
135    let params = ProcessingParams {
136        format: OutputFormat::JPEG,
137        input_format: InputFormat::Safe,
138        bit_depth: BitDepthArg::U8,
139        polarization: Polarization::Multiband,
140        autoscale: AutoscaleStrategy::Tamed,
141        target_crs: Some("EPSG:32630".to_string()),
142        resample_alg: Some("lanczos".to_string()),
143        size: Some(1024),
144        pad: true,
145    };
146
147    let report = process_directory_to_path(
148        Path::new("/data/safe_root"),
149        Path::new("/out"),
150        &params,
151        true, // continue_on_error
152    )?;
153
154    println!("processed={} skipped={} errors={}", report.processed, report.skipped, report.errors);
155    Ok(())
156}
157```
158
159Error handling
160--------------
161All public functions return `sarpro::Result<T>`; match on `sarpro::Error` to handle specific
162cases, e.g. GDAL or SAFE reader errors.
163
164```rust,no_run
165use std::path::Path;
166use sarpro::{process_safe_to_path, Error, ProcessingParams, AutoscaleStrategy, BitDepthArg, OutputFormat, Polarization, InputFormat};
167
168fn main() {
169    let params = ProcessingParams {
170        format: OutputFormat::TIFF,
171        input_format: InputFormat::Safe,
172        bit_depth: BitDepthArg::U8,
173        polarization: Polarization::Vv,
174        autoscale: AutoscaleStrategy::Tamed,
175        target_crs: Some("EPSG:32630".to_string()),
176        resample_alg: Some("lanczos".to_string()),
177        size: None,
178        pad: false,
179    };
180
181    match process_safe_to_path(Path::new("/bad/path.SAFE"), Path::new("/out.tiff"), &params) {
182        Ok(()) => {}
183        Err(Error::Gdal(e)) => eprintln!("GDAL error: {e}"),
184        Err(Error::Safe(e)) => eprintln!("SAFE error: {e}"),
185        Err(other) => eprintln!("Other error: {other}"),
186    }
187}
188```
189
190Feature flags
191-------------
192- `gui`: builds the GUI crate module.
193- `full`: enables a complete feature set for typical end-to-end workflows.
194
195Useful modules
196--------------
197- [`api`] — high-level, ergonomic entry points.
198- [`types`] — enums and core types (e.g. `AutoscaleStrategy`, `Polarization`, `ProcessingOperation`).
199- [`io`] — SAFE and GDAL readers/writers.
200- [`error`] — crate-level `Error` and `Result`.
201"#]
202
203// Core modules (public)
204pub mod api;
205pub mod core;
206pub mod error;
207pub mod io;
208pub mod types;
209
210// GUI module (only available with gui feature)
211#[cfg(feature = "gui")]
212pub mod gui;
213
214// Curated public API surface
215// Types
216pub use core::params::ProcessingParams;
217pub use error::{Error, Result};
218pub use types::{
219    AutoscaleStrategy, BitDepth, BitDepthArg, InputFormat, OutputFormat, Polarization,
220    PolarizationOperation, ProcessingOperation,
221};
222
223// Readers
224pub use io::gdal::{GdalError, GdalMetadata, GdalSarReader};
225pub use io::sentinel1::{ProductType, SafeError, SafeMetadata, SafeReader};
226
227// Selected writer helpers (keep low-level metadata helpers public)
228pub use io::writers::metadata::{
229    create_jpeg_metadata_sidecar, embed_tiff_metadata, extract_metadata_fields,
230};
231
232// High-level API re-exports
233pub use api::{
234    BatchReport, ProcessedImage, iterate_safe_products, load_operation, load_polarization,
235    process_directory_to_path, process_safe_to_buffer, process_safe_to_path,
236    process_safe_with_options, save_image, save_multiband_image,
237};
sarpro/lib.rs

sarpro/
lib.rs
