Wasm bindings for Rust Geodesy.

About

Geodesy is a pure Rust library for doing coordinate transformations and conversion. Geodesy-Wasm is, as the name suggests, wasm bindings for Rust Geodesy. It is intended as an alternative to Proj4.js for performing coordinate transformations in the browser. Today there is no alternative to Proj4.js and while for many projects this isn't an issue - it becomes challenging if you require more advanced transformations that only PROJ offers - notably via the pipeline operator. Rust Geodesy is built with pipelines as first class citizens and support to PROJ via the parse_proj helper function.

Note: Please see the warnings in the Geodesy create regarding stability and architectural goals. In short Geodesy isn't a replacement for PROJ and only contains a fraction of the projects. However you if only need a sub-set of what PROJ has to offer this project may be of interest.

Contributions very much welcome!

🚴 Usage

📦 Install

npm install geodesy-wasm

📝 Examples

See the examples folder for more examples. They can be run with bun run examples -n <example name (excluding extension)>.

The examples are written to be run with Node or Bun, however with the exception of loading a gridshift they will translate directly to the browser.

bun run examples -n 00-basic

You can also run them directly with ts-node:

ts-node examples/js/00-basic.ts

Using ESM Modules in ObservableHQ

See this notebook for an example of using Geodesy-Wasm in ObservableHQ.

📚 Documentation

Development

For convenience all scripts can be run with bun <script>. Make sure all the javascript related dependencies are installed with bun install. Rust dependencies are managed by cargo and don't require and explicit install step.

🛠️ Build the bindings

bun build

# Or for a specific target run. Only `node` and `bundler` targets are supported
TARGET=node ENV=debug bun build

🔧 Developing the JS wrapper

The wrapper is intended to abstract some of the complexities of using a wasm library - like dealing with pointers and managing WASM memory. It's also written to provide a more familiar API for JS developers - see examples.

Note: This project uses Bun for building and testing of the Typescript wrapper.

To develop the wrapper you must first build the wasm bindings:

bun build:wrapper-dev

This will ensure that you get all the linting goodness from typescript while making changes to the wrapper.

🔬 Testing

Wasm bindings

Written in rust so we use cargo

cargo test

JS wrapper

First we need to build the bindings:

bun build:wrapper-dev

Then we can run the tests:

bun test:wrapper-dev

License

Geodesy-Wasm: Copyright (c) 2023 by Sean Rennie.

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 the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.