milsymbol-rs

A Rust wrapper for the milsymbol JavaScript library, enabling the generation of military symbols (MIL-STD-2525 and APP-6) as SVG strings or static images directly from Rust.

This crate uses deno_core to evaluate the optimized JavaScript library within the V8 engine and returns representations suitable for UI frameworks, GIS applications, or for web use.

Compatibility

Features

• Full Milsymbol Support: Generate any symbol supported by the original library.
• Static Image Rendering: (Default enabled) Render symbols directly to image::DynamicImage using resvg.
• Builder Pattern: Ergonomic and typed configuration of symbol options.
• In-Memory Caching: (Default enabled) Automatically caches rendered symbols to avoid re-executing JavaScript or rendering SVGs for identical inputs.
• Automated JS Build: The crate automatically handles the compilation of the milsymbol JavaScript dependency during the Rust build process. npm is required.
• Strongly Typed Errors: Comprehensive error handling using thiserror and eyre.

Basic Usage

use milsymbol_rs::{MilsymbolBuilder, MilsymbolOptions};

fn main() {
    let mut ms = MilsymbolBuilder::new().build().unwrap();
    
    // Generate a simple friendly infantry unit icon as SVG
    let options = MilsymbolOptions::new().size(45.0);
    let symbol = ms.as_svg("10031000001211000000", Some(&options)).unwrap();
    println!("{}", symbol.svg);

    // Generate as a static image (requires 'image' feature, enabled by default)
    #[cfg(feature = "image")]
    {
        let img = ms.as_image("10031000001211000000", Some(&options)).unwrap();
        // img is an image::DynamicImage
        img.save("symbol.png").unwrap();
    }
}

Feature Flags

• cache (default): Enables thread-safe in-memory caching of rendered SVGs and images.
• image (default): Enables static image rendering via resvg and image crates.

Cache Management

When the cache feature is enabled, you can manage the in-memory cache on the Milsymbol instance:

• ms.clear_cache(): Removes all entries from the cache for this engine instance.
• ms.remove_from_cache(sidc, options): Removes a specific symbol from the cache.

Development

The crate includes an automated build.rs script. To build the project, ensure you have npm installed, as it is used to bundle the JavaScript library submodule:

cargo build

Examples

Run the provided examples to see the library in action:

cargo run --example simple
cargo run --example complex

License

This project is licensed under the MIT License - see the LICENSE file for details.