spatialarray

SpatialArray provides labeled n-dimensional arrays and helpers aimed at geospatial and scientific workflows built on ndarray.

Quick publish notes:

• Ensure Cargo.toml has valid metadata (description, authors, readme, license-file).
• Add a LICENSE file matching the license field.
• Run cargo package to verify the package contents before publishing: cargo package --allow-dirty

See the crate documentation at https://docs.rs/spatialarray (after first publish).

This library provides a structure for connecting human-readable dimension names (like "band", "time", "y", "x") to the underlying numerical data store powered by ndarray.

Features

• Labeled Dimensions: Associate human-readable names with array dimensions
• Coordinate Labels: Attach coordinate labels to dimensions for easy data selection
• Type-Safe: Leverages Rust's type system for safe array operations
• Performance: Built on top of ndarray with optional parallel processing support via rayon

Installation

Add this to your Cargo.toml:

[dependencies]
spatialarray = "0.1"

Quick Start

use ndarray::ArrayD;
use spatialarray::SpatialArray;
use std::collections::HashMap;

// Create a simple 2D spatial array
let data = ArrayD::from_shape_vec(vec![3, 4], vec![
    1, 2, 3, 4,
    5, 6, 7, 8,
    9, 10, 11, 12
]).unwrap();
let dims = vec!["y".to_string(), "x".to_string()];
let array = SpatialArray::new(data, dims);

println!("Dimensions: {:?}", array.dims());
println!("Shape: {:?}", array.shape());

Geospatial Example

use ndarray::ArrayD;
use spatialarray::SpatialArray;
use std::collections::HashMap;

// Create a 4D geospatial array: time × band × y × x
let data = ArrayD::from_shape_vec(vec![2, 3, 100, 100], vec![0.0; 60000]).unwrap();
let dims = vec![
    "time".to_string(),
    "band".to_string(),
    "y".to_string(),
    "x".to_string(),
];

let mut coords = HashMap::new();
coords.insert("time".to_string(), vec![
    "2024-01-01".to_string(), 
    "2024-01-02".to_string()
]);
coords.insert("band".to_string(), vec![
    "red".to_string(), 
    "green".to_string(), 
    "blue".to_string()
]);

let array = SpatialArray::with_coords(data, dims, coords);

// Query dimension indices
if let Some(idx) = array.dim_index("band") {
    println!("Band dimension is at index: {}", idx);
}

// Select by coordinate label
if let Some(idx) = array.select_by_label("band", "green") {
    println!("Green band is at index: {}", idx);
}

API Overview

Creating Arrays

• SpatialArray::new(data, dims) - Create array with dimension names
• SpatialArray::with_coords(data, dims, coords) - Create array with dimension names and coordinates

Querying Array Information

• dims() - Get dimension names
• shape() - Get array shape
• ndim() - Get number of dimensions
• data() - Get reference to underlying ndarray
• info() - Get formatted string with array information

Working with Coordinates

• coords(dim) - Get coordinates for a dimension
• all_coords() - Get all coordinates
• set_coords(dim, coords) - Set coordinates for a dimension
• dim_index(dim) - Get the index of a dimension by name
• select_by_label(dim, label) - Find the index of a coordinate label

Examples

Run the included example:

cargo run --example basic_usage

Future Development

This library is designed to be extended with additional geospatial functionality:

• Integration with geo-types for spatial operations
• STAC (SpatioTemporal Asset Catalog) support
• GDAL bindings for reading/writing geospatial formats
• Advanced indexing and selection operations
• Lazy evaluation and chunked processing

License

[Add your license here]

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.