Skip to main content

oxigeo_ml/
lib.rs

1//! OxiGeo ML - Machine Learning for Geospatial Data
2//!
3//! This crate provides machine learning capabilities for the OxiGeo ecosystem,
4//! enabling geospatial ML workflows with ONNX Runtime integration.
5//!
6//! # Features
7//!
8//! - **ONNX Runtime Integration**: Pure Rust interface to ONNX Runtime for model inference
9//! - **Image Segmentation**: Semantic, instance, and panoptic segmentation
10//! - **Image Classification**: Scene classification, land cover classification, multi-label
11//! - **Object Detection**: Bounding box detection with NMS and georeferencing
12//! - **Preprocessing**: Normalization, tiling, padding, and augmentation
13//! - **Postprocessing**: Tile merging, thresholding, polygon conversion, GeoJSON export
14//!
15//! # Optional Features
16//!
17//! - `gpu` / `cuda` / `rocm` - GPU acceleration backends
18//! - `vulkan` / `metal` / `opencl` / `webgpu` - Additional compute backends
19//! - `quantization` / `pruning` / `distillation` - Model optimization
20//! - `cloud-removal` - Cloud and shadow removal (Pure Rust)
21//! - `model-download` - Download models over HTTP
22//!
23//! # Example: Image Segmentation
24//!
25//! ```ignore
26//! use oxigeo_ml::*;
27//! use oxigeo_ml::models::OnnxModel;
28//! use oxigeo_ml::inference::{InferenceEngine, InferenceConfig};
29//! use oxigeo_ml::segmentation::probability_to_mask;
30//!
31//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
32//! // Load ONNX model
33//! let model = OnnxModel::from_file("segmentation.onnx")?;
34//!
35//! // Create inference engine
36//! let config = InferenceConfig::default();
37//! let engine = InferenceEngine::new(model, config);
38//!
39//! // Load input raster (not shown)
40//! # use oxigeo_core::buffer::RasterBuffer;
41//! # use oxigeo_core::types::RasterDataType;
42//! # let input = RasterBuffer::zeros(256, 256, RasterDataType::Float32);
43//!
44//! // Run inference
45//! let predictions = engine.predict(&input)?;
46//!
47//! // Convert to segmentation mask
48//! let mask = probability_to_mask(&predictions, 2, 0.5)?;
49//! # Ok(())
50//! # }
51//! ```
52//!
53//! # Example: Object Detection
54//!
55//! ```ignore
56//! use oxigeo_ml::*;
57//! use oxigeo_ml::detection::{non_maximum_suppression, NmsConfig};
58//! use oxigeo_ml::postprocessing::export_detections_geojson;
59//!
60//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
61//! // Assume we have detections from a model
62//! # let detections = vec![];
63//!
64//! // Apply NMS to filter overlapping detections
65//! let config = NmsConfig::default();
66//! let filtered = non_maximum_suppression(&detections, &config)?;
67//!
68//! // Export to GeoJSON
69//! # let geo_detections = vec![];
70//! # export_detections_geojson(&geo_detections, "detections.geojson")?;
71//! # Ok(())
72//! # }
73//! ```
74//!
75//! # Example: Batch Processing with Progress Tracking
76//!
77//! ```ignore
78//! use oxigeo_ml::*;
79//! use oxigeo_ml::batch::{BatchConfig, BatchProcessor};
80//! use oxigeo_ml::models::OnnxModel;
81//! # use oxigeo_core::buffer::RasterBuffer;
82//! # use oxigeo_core::types::RasterDataType;
83//!
84//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
85//! // Load model
86//! let model = OnnxModel::from_file("model.onnx")?;
87//!
88//! // Auto-tune batch size based on available memory
89//! let sample_size = 3 * 256 * 256 * 4; // 3 channels, 256x256, float32
90//! let batch_size = BatchConfig::auto_tune_batch_size(sample_size, 0.5);
91//!
92//! // Create batch processor
93//! let config = BatchConfig::builder()
94//!     .max_batch_size(batch_size)
95//!     .parallel_batches(4)
96//!     .build();
97//!
98//! let processor = BatchProcessor::new(model, config);
99//!
100//! // Process large batch with progress bar
101//! # let inputs: Vec<RasterBuffer> = vec![];
102//! let results = processor.infer_batch_with_progress(inputs, true)?;
103//! # Ok(())
104//! # }
105//! ```
106//!
107//! # Example: Model Optimization Pipeline
108//!
109//! ```ignore
110//! use oxigeo_ml::*;
111//! use oxigeo_ml::optimization::{OptimizationPipeline, OptimizationProfile};
112//!
113//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
114//! // Create optimization pipeline for edge deployment
115//! let pipeline = OptimizationPipeline::from_profile(OptimizationProfile::Size);
116//!
117//! // Optimize model (applies quantization + pruning)
118//! let stats = pipeline.optimize("model.onnx", "model_optimized.onnx")?;
119//!
120//! println!("Size reduction: {:.1}%", stats.size_reduction_percent());
121//! println!("Speedup: {:.2}x", stats.speedup);
122//! println!("Accuracy delta: {:.2}%", stats.accuracy_delta);
123//! # Ok(())
124//! # }
125//! ```
126//!
127//! # Example: Model Zoo - Download Pretrained Models
128//!
129//! ```ignore
130//! use oxigeo_ml::*;
131//! use oxigeo_ml::zoo::ModelZoo;
132//! use oxigeo_ml::models::OnnxModel;
133//!
134//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
135//! // Create model zoo
136//! let mut zoo = ModelZoo::new()?;
137//!
138//! // List available models
139//! let models = zoo.list_models();
140//! for model in models {
141//!     println!("{}: {} - {:.1}% accuracy",
142//!         model.name, model.description,
143//!         model.accuracy.unwrap_or(0.0));
144//! }
145//!
146//! // Download a model (with progress bar and checksum verification)
147//! let model_path = zoo.get_model("unet_buildings")?;
148//!
149//! // Load and use the model
150//! let model = OnnxModel::from_file(model_path)?;
151//! # Ok(())
152//! # }
153//! ```
154//!
155//! # Example: Transfer Learning
156//!
157//! ```no_run
158//! use oxigeo_ml::*;
159//! # #[cfg(feature = "temporal")]
160//! # fn example() -> Result<(), Box<dyn std::error::Error>> {
161//! // This example requires oxigeo-ml-foundation
162//! // Load pretrained feature extractor
163//! use oxigeo_ml_foundation::transfer::FeatureExtractor;
164//!
165//! // Extract features from pretrained model
166//! let extractor = FeatureExtractor::from_pretrained("resnet50")?;
167//!
168//! // Use features for custom classification task
169//! // (Training loop implementation would go here)
170//! # Ok(())
171//! # }
172//! ```
173//!
174//! # Example: GPU Backend Detection
175//!
176//! Detection and device selection are real; actual GPU execution additionally
177//! requires the ONNX backend compiled with the `gpu` feature (otherwise
178//! inference runs on CPU).
179//!
180//! ```no_run
181//! use oxigeo_ml::gpu::{GpuBackend, GpuConfig};
182//! use oxigeo_ml::inference::{InferenceEngine, InferenceConfig};
183//! use oxigeo_ml::models::OnnxModel;
184//!
185//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
186//! // Detect available GPU backends
187//! let backends = GpuBackend::detect_all();
188//! for backend in &backends {
189//!     println!("Available: {:?}", backend);
190//! }
191//!
192//! // Configure GPU acceleration
193//! let gpu_config = GpuConfig::builder()
194//!     .preferred_backend(GpuBackend::Cuda)
195//!     .device_id(0)
196//!     .build();
197//!
198//! // Create inference engine with GPU support
199//! let model = OnnxModel::from_file("model.onnx")?;
200//! let mut inference_config = InferenceConfig::default();
201//! inference_config.gpu_config = Some(gpu_config);
202//!
203//! let engine = InferenceEngine::new(model, inference_config);
204//! # Ok(())
205//! # }
206//! ```
207//!
208//! # Example: Model Monitoring
209//!
210//! ```ignore
211//! use oxigeo_ml::*;
212//! use oxigeo_ml::monitoring::{ModelMonitor, MonitoringConfig};
213//! use oxigeo_ml::models::OnnxModel;
214//! # use oxigeo_core::buffer::RasterBuffer;
215//!
216//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
217//! let model = OnnxModel::from_file("model.onnx")?;
218//!
219//! // Create monitor with custom config
220//! let config = MonitoringConfig::builder()
221//!     .track_latency(true)
222//!     .track_memory(true)
223//!     .alert_threshold_ms(100.0)
224//!     .build();
225//!
226//! let mut monitor = ModelMonitor::new(model, config);
227//!
228//! // Run inference with monitoring
229//! # let input = RasterBuffer::zeros(256, 256, oxigeo_core::types::RasterDataType::Float32);
230//! let result = monitor.predict(&input)?;
231//!
232//! // Check metrics
233//! let metrics = monitor.metrics();
234//! println!("Avg latency: {:.2}ms", metrics.avg_latency_ms());
235//! println!("Memory usage: {:.1}MB", metrics.peak_memory_mb);
236//! # Ok(())
237//! # }
238//! ```
239//!
240//! # SciRS2 Integration Status
241//!
242//! This crate is being migrated to use the Pure Rust SciRS2 ecosystem following
243//! COOLJAPAN policy. Current status:
244//!
245//! - **Random Number Generation**: Completed - using `scirs2-core::random` for RNG
246//! - **Statistical Distributions**: Completed - using `NormalDistribution` for Gaussian noise
247//! - **Data Augmentation**: Completed - integrated SciRS2-Core RNG
248//! - **Linear Algebra**: Partial - `ndarray` still used in some modules, migration ongoing
249//! - **Neural Network Training**: In Progress - `oxigeo-ml-foundation` implements custom
250//!   Pure Rust backend with SciRS2 integration
251//!
252//! ## Usage Example with SciRS2
253//!
254//! ```no_run
255//! use oxigeo_ml::augmentation::{add_gaussian_noise, random_crop};
256//! # use oxigeo_core::buffer::RasterBuffer;
257//! # use oxigeo_core::types::RasterDataType;
258//!
259//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
260//! // Create a raster buffer
261//! let input = RasterBuffer::zeros(512, 512, RasterDataType::Float32);
262//!
263//! // Add Gaussian noise using SciRS2-Core
264//! let noisy = add_gaussian_noise(&input, 0.01)?;
265//!
266//! // Random crop using SciRS2-Core RNG
267//! let cropped = random_crop(&input, 256, 256)?;
268//! # Ok(())
269//! # }
270//! ```
271//!
272//! For more information about SciRS2 integration, see the SCIRS2 POLICY in the
273//! workspace documentation.
274
275#![warn(missing_docs)]
276#![warn(clippy::all)]
277// Pedantic disabled to reduce noise - default clippy::all is sufficient
278// #![warn(clippy::pedantic)]
279#![deny(clippy::unwrap_used)]
280#![allow(clippy::module_name_repetitions)]
281#![allow(clippy::missing_errors_doc)]
282#![allow(clippy::missing_panics_doc)]
283// Allow unused imports in feature-gated modules
284#![allow(unused_imports)]
285// Allow dead code for ML model structures
286#![allow(dead_code)]
287// Allow collapsible match for ML result handling
288#![allow(clippy::collapsible_match)]
289#![allow(clippy::collapsible_if)]
290// Allow expect() for model loading invariants
291#![allow(clippy::expect_used)]
292// Allow for loop with idx for tensor operations
293#![allow(clippy::needless_range_loop)]
294// Allow manual div_ceil for batch calculations
295#![allow(clippy::manual_div_ceil)]
296// Allow field assignment outside initializer for ML configs
297#![allow(clippy::field_reassign_with_default)]
298// Allow unexpected cfg for temporarily disabled features
299#![allow(unexpected_cfgs)]
300
301pub mod augmentation;
302pub mod batch;
303pub mod batch_predict;
304pub mod classification;
305#[cfg(feature = "cloud-removal")]
306pub mod cloud;
307pub mod detection;
308pub mod error;
309pub mod gpu;
310pub mod hot_reload;
311pub mod inference;
312pub mod inference_cache;
313pub mod model_versioning;
314pub mod models;
315pub mod monitoring;
316pub mod optimization;
317pub mod postprocessing;
318pub mod preprocessing;
319pub mod segmentation;
320pub mod serving;
321pub mod superres;
322#[cfg(feature = "temporal")]
323pub mod temporal;
324pub mod tiling;
325pub mod zoo;
326
327// Re-export commonly used items
328pub use augmentation::AugmentationConfig;
329pub use batch::{BatchConfig, BatchProcessor};
330pub use error::{MlError, Result};
331pub use gpu::{GpuBackend, GpuConfig, GpuDevice};
332pub use models::{Model, OnnxModel};
333pub use monitoring::{ModelMonitor, MonitoringConfig, PerformanceMetrics};
334pub use optimization::{OptimizationPipeline, OptimizationProfile};
335pub use serving::{DeploymentStrategy, ModelServer, ServerConfig};
336pub use superres::{SuperResConfig, SuperResolution, UpscaleFactor};
337#[cfg(feature = "temporal")]
338pub use temporal::{ForecastConfig, ForecastResult, TemporalForecaster};
339pub use zoo::ModelZoo;
340
341/// Crate version
342pub const VERSION: &str = env!("CARGO_PKG_VERSION");
343
344/// Crate name
345pub const NAME: &str = env!("CARGO_PKG_NAME");
346
347#[cfg(test)]
348mod tests {
349    use super::*;
350
351    #[test]
352    fn test_version() {
353        assert!(!VERSION.is_empty());
354        assert_eq!(NAME, "oxigeo-ml");
355    }
356}