# [osgEarth](https://github.com/gwaldron/osgearth) 🌍 ported to [WebAssembly](https://webassembly.org/) to run it on the web platform

[osgearthwasm](https://github.com/boardend/osgearthwasm) is a TypeScript/JavaScript library to run [osgEarth](https://github.com/gwaldron/osgearth) ported to [WebAssembly](https://webassembly.org/) inside modern browsers to render beautiful 2D or 3D maps

[![osgearthwasm on npm](https://img.shields.io/npm/v/osgearthwasm)](https://www.npmjs.com/package/osgearthwasm)

> **DISCLAIMER**: This project is in **early alpha state**! It's dangerous to go alone! Take this 🗡️

## Usage

### Browser

```html
<div id="shell"></div>
<script type="module">    
  import { osgearthwasm } from "https://unpkg.com/osgearthwasm";
  osgearthwasm("#shell")
    .then(({ api }) => {
      // 📐 add some WKT geometries to the globe (see https://docs.osgearth.org/en/latest/earthfile.html)
      api.addEarthFile(`
        <map>
          <OGRFeatures name="geometry">
            <geometry>POLYGON((-120 30, -120 50, -70 50, -70 30))</geometry>
          </OGRFeatures>
          <FeatureModel features="geometry">
              <styles><style type="text/css">
                default {
                  fill: #ffff006f;
                  altitude-clamping: terrain-drape;
                }
              </style></styles>
            </FeatureModel>
        </map>
      `);
      // 🌍 fly to a random location every 15 seconds
      setInterval(() => {
        api.setViewpoint(
          {
            longitude: (Math.random() * (75 - -75) + -75).toFixed(6) * 1, // random between -75° and 75°)
            latitude: (Math.random() * (180 - -180) + -180).toFixed(6) * 1, // random between -180° and 180°)
            altitude: 100000, heading: 0, pitch: -90, range: 500000
          },
          5 // animation time,
        );
      }, (15 * 1000));
      // ⌛ simulate one day in one minute (with an update every simulated 30 minutes)
      let clock = new Date();
      setInterval(() => {
        clock = new Date(clock.getTime() + (30 * 60 * 1000)); 
        api.setDate(clock);
      }, (60 * 1000) / ((24 * 60) / 2));
    });
</script>
<style lang="css">
  body, html, #shell {
    position: absolute;
    top: 0; right: 0; bottom: 0; left: 0;
    margin: 0; padding: 0;
    overflow: hidden;
    background-color: black;
  }
</style>
```

> _NOTE_: The [COOP and COEP headers](#coop-and-coep-headers) have to be set from the web server.

### ES Module with Bundler (Webpack, Vite, etc.)

#### Installation

```bash
npm install osgearthwasm --save
```

#### Import

```javascript
import { osgearthwasm } from "osgearthwasm";

const { api } = await osgearthwasm("#shell");

api.flyToPoint(8.5061792, 47.4085885);
```

> _NOTE_: See [bundling.md](docs/bundling.md) for more information about how to include the necessary assets with your bundler. Also the [COOP and COEP headers](#coop-and-coep-headers) have to be set from the web server.

## COOP and COEP headers

[cross-origin isolation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy#certain_features_depend_on_cross-origin_isolation) is required to use [SharedArrayBuffers](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer/SharedArrayBuffer). To opt-in, the following headers have to be set by the web server:

```
Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-origin
```

To start a development server with those flags one could use:

```
npx osgearthwasm serve
```

For more information, have a look at [headers.md](docs/headers.md).

## Libraries

| Library  | Version | License | Source                               |
| -------- | ------- | ------- | ------------------------------------ |
| osgEarth | 3.2     | LGPL    | https://github.com/gwaldron/osgearth |
| `//TODO` |         |         |                                      |

## Acknowledgements

- [osgEarth](https://github.com/gwaldron/osgearth)

## License

[GPLv3](./LICENCE) License
