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; * MOCWasm; * Aladin Lite V3; see the Cargo.tom file.

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 F-MOCs (F for Frequency) and SF-MOCs.

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: bash rustup update

Run tests (with or without seeing stdout): bash cargo test cargo test -- --nocapture Run benches: bash cargo bench Build documentation bash cargo doc --open

Build the library for fast test or final build ```bash

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) rust // 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
  • [X] or
  • [ ] and, complement, fold, ...
• [X] 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?

WARNING about the STC-S to MOC function

STC-S parsing is ensured by the STC crate.

Current discrepancies between the STC standard and this implementation:

• The DIFFERENCE operation has been implemented as being a symmetric difference
  • why? probably because:
    1. I am biased towards Boolean algebra, it as XOR (exclusive OR or symmetric difference) but no Difference
    2. I read parts of the STC standard after the STC-S implementation
    3. XOR is already implemented in cdshleapix, but DIFFERENCE is not.
  • has stated in the STC standard: R1 – R2 = R1 AND (NOT R2)); but also: R1 - R2 = R1 AND (R1 XOR R2), and XOR = (R1 OR R2) AND (NOT (R1 AND R2)) is more complex that DIFFERENCE (so is worth having implented?).
• For Polygon: we do not use the STC convention
  • we support self-intersecting polygons
  • we generally return the smallest area polygon (use NOT to get its complement!)
  • one convention could be to use an additional (last) provided points as a control point
    • note that for convex polygons, the control point could be the vertices gravity center
    • in a GUI, a user could define the inner part of the polygon by a final click
  • why?
    1. efficient algorithms dealing with polygons supports self-intersecting polygons
    2. to support arbitrary defined polygons by a user clicking in a viewer such as Aladin or Aladin Lite
    3. cdshleapix is based on self-intersecting polygons
• For Box: a position angle can be added as a last parameter, right after bsize.

So far, we reject STC-S having: * a frame different from ICRS * a flavor different from Spher2 * units different from degrees

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.

Warning

The code is formatted using 2 tab spaces instead of the regular 4:

bash cargo fmt -- --config tab_spaces=2

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.