SKYTOMCAT / cds-moc-rust

MOC library in Rust; used in MOCPy, a CLI, a WASM lib, ...

moc

Read, write, create and manipulate HEALPix Multi-Order Coverage maps (MOCs), i.e. discretized geomatrical surfaces on the unit sphere.

MOC Lib Rust, the Rust MOC library used in MOCPy, MOCli, MOCSet, and MOCWasm.

MOC Lib Rust rely on the CDS HEALPix Rust library.

About

This Rust library implements the v2.0 of the MOC standard, including (S-)MOCs, T-MOCs and ST-MOCs.
It also implements a still experimental F-MOC (F for Frequency).

MOC Lib Rust is used in:

• MOCPy, a Python wrapper to manipulate MOCs;
• a standalone command line tool MOCli for linux, MacOS and Windows;
• a standalone command line tool MOCSet for linux, MacOS and Windows;
• a WASM library MOCWasm to be used in web browsers.

For tools able to display MOCs, see:

• the Aladin Desktop sky atlas in Java (also supports MOC operations);
• Aladin Lite, "a lightweight version of the Aladin Sky Atlas running in the browser";
• MOCPy scripts, a python wrapper using the very same Rust MOC library.

Release

The github releases section number is the MOCCli, MOCSet and MOCWasm release number.

Install/test

Install rust (and check that ~/.cargo/bin/ is in your path), or update the Rust compiler with:

rustup update

Run tests (with or without seeing stdout):

cargo test
cargo test -- --nocapture

Run benches:

cargo bench

Build documentation

cargo doc --open

Build the library for fast test or final build

# Fast build (large not optimized file) 
cargo build
# Optimized file
cargo build --release

Particularities

• The core of this library is very generic
• We implemented lazy, streamed operations:
  • an operation between 2 MOCs takes in input 2 iterators and returns an iterator (streaming)
  • you can combine operations by combining iterators at no cost; the process start when starting to iterate on the outermost iterator (lazyness)

// Signature of the Union operation between 2 2D-MOCs
pub fn or<T, Q, U, R, I1, J1, K1, I2, J2, K2>(
  left_it: K1,
  right_it: K2
) -> OrRange2Iter<T, Q, I1, I2>
  where
    T: Idx,       // Type of the 1st quantity (e.g. u32 or u64)
    Q: MocQty<T>, // First quantity type, e.g Time
    U: Idx,       // Type of the 2nd quantity (e.g. u32 or u64)
    R: MocQty<U>, // Second quantity type, e.g Space (we use Hpx for HEALPix)
    I1: RangeMOCIterator<T, Qty=Q>,
    J1: RangeMOCIterator<U, Qty=R>,
    K1: RangeMOC2ElemIt<T, Q, U, R, It1=I1, It2=J1>,
    I2: RangeMOCIterator<T, Qty=Q>,
    J2: RangeMOCIterator<U, Qty=R>,
    K2: RangeMOC2ElemIt<T, Q, U, R, It1=I2, It2=J2>

Possible Enhancements / Ideas

• Add operations on RangeMOC2
  • or
  • and, complement, fold, ...
• Implement a function dividing a disjoint MOCs into a list of joint MOCs (tip: use the order and the flag of a BMOC, the flag telling is the cell has already been visited).
• Implement the compact notation (bits coding quad-tree traversal) for S-MOCs (binary + ASCII Base 64)
• Implement compact S-MOC: single z-order curve sorted array of indices with a 2 bits flag telling whether the index is a single index, a range lower bound or a range upper bound
• Make a PostgresQL wrapper using e.g. pgx?

License

Like most projects in Rust, this project is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Acknowledgements

This work has been partly supported by the ESCAPE project.
ESCAPE - The European Science Cluster of Astronomy & Particle Physics ESFRI Research Infrastructures - has received funding from the European Union’s Horizon 2020 research and innovation programme under Grant Agreement no. 824064.