@fxpineau/moc-wasm

moc-wasm

WebAssembly Library to read/write/create/manipulate HEALPix Multi-Order Coverage maps (MOCs) in a web page.

About

This wasm library is made from the Rust MOC library. It implements the v2.0 of the MOC standard, including (S-)MOCs, T-MOCs and ST-MOCs.

If you are developing a web page using:

• JavaScript: you can use this library (see next section for the list of available JS functions);
• Rust --> wasm: the code can be an example of how to directly use the Rust MOC library.

Technically, this project relies on wasm-bindgen: a big thank you to the developers.

For tools able to display MOCs, see:

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

Use it

Try it

• From version 0.7.0: from this demo page.
• Older versions (pre v0.7.0): from this demo page.

Put it in your own Web page

Download the last moc-wasm-vxx.tar.gz from thegithub release page. Put it in the same directory of you web page and decompress it:

tar xvzf moc-wasm-vxx.tar.gz

And add this in your HTML body:

<script type="module">
    import init, * as moc from './pkg/moc.js';
    async function run() {
        const wasm = await init().catch(console.error);
	window.moc = moc;
    }
    run();
</script>

This the example page.

Used by

Example of web page(s) using MOCwasm:

• Gravitational-Wave Sky Localizations

Use it in you project with NPM

See the npm moc-wasm package. (Not tested, we need feedbacks!).

Available JavaScript methods (from v0.7.0)

Following the provided index.html example, use the moc prefix to, call the following objects/methods (e.g. moc.debugOn() or moc.MOC):

# In case of failure, enable Rust stack trace
debugOn();

# Available objects
MOC
TMOC
FMOC
STMOC

# You can then explore the various methods each object has,
# a large part are common, creation methods from parameters are specific

# - fires the select file dialog (see JS file for more details) to load a local MOCs
let mymoc = (T|F|ST)MOC.fromLocalFile()
# - load the MOC from a FITS file content, provided in the UInt8Array
let mymoc = (T|F|ST)MOC.fromFits(data: UInt8Array)
# - load the MOC stored in a FITS file of given URL
let mymoc = (T|F|ST)MOC.fromFitsUrl(url) // A string of supported mime types can be passed in an additional last parameter
# - load from a ASCII String or an ASCII file
let mymoc = (T|F|ST)MOC.fromAscii(data: String)
let mymoc = (T|F|ST)MOC.fromAsciiUrl(url)

# - load from a JSON String or a JSON file
let mymoc = (T|F|ST)MOC.fromJson(data: String)
let mymoc = (T|F|ST)MOC.fromJsonUrl(url)


# - fires the select dialogto load a multi-order map FITS file and create a MOC from the given parameters
let mymoc = MOC.fromLocalMultiOrderMap(from_threshold: f64, to_threshold: f64, asc: bool, not_strict: bool, split: bool, revese_recursive_descent: bool)
# - load a multi-order map FITS file and create a MOC from the given parameters
let mymoc = MOC.fromFitsMulitOrderMap(data: UInt8Array, from_threshold: f64, to_threshold: f64, asc: bool, not_strict: bool, split: bool, revese_recursive_descent: bool)
# - load a multi-order map FITS file of given URL and create a MOC from the given parameters
let mymoc = MOC.fromMultiOrderMapFitsUrl(url, from_threshold: f64, to_threshold: f64, asc: bool, not_strict: bool, split: bool, revese_recursive_descent: bool) // A string of supported mime types can be passed in an additional last parameter

# Save a MOC
# - get the FITS binary representation of the MOC
mymoc.toFits() -> Uint8Array
# - get the ASCII representation of the MOC
toAscii(name, fold: null|int) -> String
# - get the JSON representation of the MOC
mymoc.toJson(fold: null|int) -> String
# - fires the download dialog to save the MOC in an ASCII/JSON or FITS file.
mymoc.toFitsFile()
mymoc.toAsciiFile(fold: null|int)
mymoc.toJsonFile(fold: null|int)

# Create MOC
# - create a S-MOC from a geometric shape
let mymoc = MOC.fromCone(depth, lon_deg, lat_deg, radius_deg)
let mymoc = MOC.fromRing(depth, lon_deg, lat_deg, internal_radius_deg, external_radius_deg)
let mymoc = MOC.fromEllipse(depth, lon_deg, lat_deg, a_deg, b_deg, pa_deg)
let mymoc = MOC.fromZone(depth, lon_deg_min, lat_deg_min, lon_deg_max, lat_deg_max)
let mymoc = MOC.fromBox(depth, lon_deg, lat_deg, a_deg, b_deg, pa_deg)
let mymoc = MOC.fromPolygon(depth, vertices_deg: Float64Array, complement: boolean)
# - create a S-MOC from a list of coordinates
let mymoc = MOC.fromCoo(depth, coos_deg: Float64Array)
# - create a T-MOC from a list of Julian Days
let mymoc = MOC.fromDecimalJDs(depth, jd: Float64Array)
# - create a T-MOC from a list of Juliand Days range
let mymoc = MOC.fromDecimalJDRanges(depth, jd_ranges: Float64Array)
# - reate a new S-MOC from the given lists of UNIQ and Values (i.e. from a Multi-Order Map)
let mymoc = MOC.fromValuedCells(depth,  density: bool, from_threshold: f64, to_threshold: f64, asc: bool,  not_strict: bool, split: bool, revese_recursive_descent: bool, uniqs: Float64Array, values: Float64Array)

# Single MOC operations
# S/T-MOC
let mynewmoc = mymoc.not() // or mymoc.complement()
let mynewmoc = mymoc.degrade(depth)
# - S-MOC only
let mynewmoc = mymoc.extend()
let mynewmoc = mymoc.contract()
let mynewmoc = mymoc.externalBorder()
let mynewmoc = mymoc.internalBorder()
# -- split considering the 4 direct neighbours (NE, NW, SE, SW) as being part of the same region
let n = mymoc.splitCount()
let mysubmocs = mymoc.split()
# -- split considering the 4 direct neighbours (NE, NW, SE, SW) plus the 4 indirect neighbours (S, N, E, W) as being part of the same region
let n = mymoc.splitIndirectCount()
let mysubmocs = mymoc.splitIndirect()

# Two MOCs operations
let union = mymoc1.or(mymoc2) // or  mymoc1.union(mymoc2)
let inter = mymoc1.and(mymoc2) // or  mymoc1.intersection(mymoc2)
let symdi = mymoc1.xor(mymoc2) // or  mymoc1.symmetric_difference(mymoc2)
let diffe = mymoc1.minus(mymoc2) // or  mymoc1.difference(mymoc2)

# Operation on ST-MOC
let mysmoc = mystmoc.timeFold(mytmoc)
let mytmoc = mystmoc.spaceFold(mysmoc)

# Filter operations (return arrays containing 0 (out of the MOC) or 1 (in the MOC))
let boolarray = mysmoc.filterCoos(coos_deg: Float64Array)
let boolarray = mytmoc.filterJDs( jds: Float64Array)

Example 1: 2MASS and SDSS DR12 MOCs

In the index.html web page put behind a server (see next section), simply copy/paste those line the web browser console:

  // Load 2MASS and SDSS DR12 MOCs from CDS
  let moc2mass = await moc.MOC.fromFitsUrl('http://alasky.u-strasbg.fr/footprints/tables/vizier/II_246_out/MOC');
  console.log("2MASS MOC depth: " + moc2mass.getDepth());
  console.log("2MASS MOC coverage: " + moc2mass.coveragePercentage() + "%");
  let mocsdss = await moc.MOC.fromFitsUrl('http://alasky.u-strasbg.fr/footprints/tables/vizier/V_147_sdss12/MOC');
  console.log("SDSS DR12 MOC depth: " + mocsdss.getDepth());
  console.log("SDSS DR12 MOC coverage: " + mocsdss.coveragePercentage() + "%");

  // Init a timer
  console.time('timer');
  // Performs MOC intersection
  let tmass_inter_sdss12 = moc2mass.and(mocsdss);
  // Log time
  console.timeLog('timer', 'Intersection');
  // Performs MOC union
  let tmass_union_sdss12 = moc2mass.or(mocsdss);
  // Log time
  console.timeLog('timer', 'Union');
  // Degrade to order 2 the result of the intersection
  let tmass_union_sdss12_d2 = tmass_union_sdss12.degrade(2);
  // Remove timer
  console.timeEnd('timer');

  console.log("(2MASS AND SDSS DR12) MOC depth: " + tmass_inter_sdss12.getDepth());
  console.log("(2MASS AND SDSS DR12) MOC coverage: " + tmass_inter_sdss12.coveragePercentage() + "%");
  console.log("(2MASS OR SDSS DR12) MOC depth: " + tmass_union_sdss12.getDepth());
  console.log("(2MASS OR SDSS DR12) MOC coverage: " + tmass_union_sdss12.coveragePercentage() + "%");
  console.log("(2MASS OR SDSS DR12) MOC coverage at depth 2: " + tmass_union_sdss12_d2.coveragePercentage() + "%");

  // Print the ASCII and JSON serializations of '2mass_inter_sdss12_d2'
  console.log(tmass_inter_sdss12.toAscii());
  console.log(tmass_inter_sdss12.toJson());

  // Save the result of the intersection in a FITS file
  tmass_inter_sdss12.toFitsFile();

Example 2: Build a MOC from a Multi-Order Map and split it into disjoint MOCs

  // Load a multi-order map and create a MOC on-the-fly
  let lalmap = await moc.MOC.fromMultiOrderMapFitsUrl('http://cdsxmatch.u-strasbg.fr/lab/moc/LALInference.multiorder.fits', 0.0, 0.9, false, false, false, false);

  console.log("LALMAP MOC depth: " + lalmap.getDepth());
  console.log("LALMAP MOC coverage: " + lalmap.coveragePercentage() + "%");

  // Init a timer
  console.time('timer');

  // Count the number of disjoint MOCs in the MOC
  let n = lalmap.splitCount();
  console.log("n sub_mocs: " + n);
  console.timeLog('timer', 'Spit count');

  // Do split the MOC in 10 sub-MOCs
  let mocs = lalmap.split();
  console.timeLog('timer', 'Spit');
  // Remove timer
  console.timeEnd('timer');

  // List MOCs loaded in the page
  console.log(mocs);

  // Get info on sub-MOCs
  for (let i = 0; i < mocs.length; i++) {
    console.log("Coverage percentage sub " + i  + ": " + mocs[i].coveragePercentage());
  }

Install/run locally

Checkout the git project.

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

rustup update

Install the wasm32-unknown-unknown toolchain (done automatically with wasm-pack?):

rustup target add wasm32-unknown-unknown

Install wasm-pack following those instructions or using (automatic download of sources and local compilation):

cargo install wasm-pack

Run tests:

wasm-pack test --node

Build the project, see wasm-bindgen doc

wasm-pack build --out-name moc --target web --no-typescript 
wasm-pack build --out-name moc --target web --no-typescript --release

Run a local server

• either using the static server from https://crates.io/crates/https

http

• or use python

python2 -m SimpleHTTPServer
python3 -m http.server

And load the web page http://0.0.0.0:8000/ in our favorite (firefox?) web browser.

Publish on NPM (self reminder)

See here

wasm-pack build --out-name moc --release --scope fxpineau
wasm-pack login
wasm-pack publish

ToDo list

• [ ] Add to_png or to_image for S-MOCs
• [ ] Implement difference (xor) for ST-MOCs
• [ ] Implement complement (not) for ST-MOCs (complement on Space only or also on Time with allsky S-MOCs?)
• [ ] Implement degradeSpace (?), degradeTime (?), degradeSpaceAndTime (?) for ST-MOCs
• [ ] Build a ST-MOCs from an array of (jd, lon, lat)
• [ ] Add possibility to filter an array of (jd, lon, lat) with a ST-MOCs
• [ ] Add overlap/contains(MOC, MOC) methods? (use cases?)
• [ ] (Internal change for performances) add native operations on RangeMOC2 instead of transforming in TimeSpaceMoc
• [ ] Implement an egui interface

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 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.