Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/qazsato/maplibre-gl-compass
A heading-up compass for MapLibre GL JS ðŸ§
https://github.com/qazsato/maplibre-gl-compass
compass maplibre-gl-js
Last synced: 4 days ago
JSON representation
A heading-up compass for MapLibre GL JS ðŸ§
- Host: GitHub
- URL: https://github.com/qazsato/maplibre-gl-compass
- Owner: qazsato
- License: mit
- Created: 2024-11-27T23:24:35.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2024-12-06T13:49:34.000Z (about 1 month ago)
- Last Synced: 2024-12-06T14:31:45.642Z (about 1 month ago)
- Topics: compass, maplibre-gl-js
- Language: TypeScript
- Homepage: https://qazsato.github.io/maplibre-gl-compass/
- Size: 743 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# maplibre-gl-compass
[](https://badge.fury.io/js/maplibre-gl-compass)
[](https://badge.fury.io/js/maplibre-gl-compass)
[](LICENSE)
A **heading-up** compass for MapLibre GL JS ðŸ§
This plugin rotates the map based on the values from the [Device orientation events](https://developer.mozilla.org/en-US/docs/Web/API/Device_orientation_events).
Therefore, it can only be used on devices equipped with an orientation sensor, such as mobile devices.
Demo page is [here](https://qazsato.github.io/maplibre-gl-compass).
## Installation
```sh
npm install maplibre-gl-compass
```
## Usage
### Basic usage
```js
import { Map } from 'maplibre-gl'
import 'maplibre-gl/dist/maplibre-gl.css'
import { CompassControl } from 'maplibre-gl-compass'
import 'maplibre-gl-compass/style.css'
const map = new Map({/* YOUR_MAP_OPTION */})
map.addControl(new CompassControl())
```
### Advanced usage
```js
import { Map } from 'maplibre-gl'
import 'maplibre-gl/dist/maplibre-gl.css'
import { CompassControl } from 'maplibre-gl-compass'
import type { CompassEvent, CompassError } from 'maplibre-gl-compass'
import 'maplibre-gl-compass/style.css'
const map = new Map({/* YOUR_MAP_OPTION */})
const compass = new CompassControl({
debug: true, // Show debug view. Default is false.
visible: true, // Show compass button. Default is true.
timeout: 10000, // The maximum time to wait for a DeviceOrientationEvent. Default is 3000 [ms].
})
compass.on('turnon', () => {
// Set pitch when compass is turned on.
map.setPitch(45)
})
compass.on('turnoff', () => {
// Restore pitch and north up when compass is turned off
map.setPitch(0)
map.setBearing(0)
})
compass.on('compass', (event: CompassEvent) => {
// Your custom logic is here!
})
compass.on('error', (event: CompassError) => {
// Your custom logic is here!
})
map.addControl(compass)
```
## Options
| name | default | description |
| ------- | ------- | ---------------------------------------------------------- |
| debug | false | Show debug view. |
| visible | true | Show compass button. |
| timeout | 3000 | The maximum time[ms] to wait for a DeviceOrientationEvent. |
## Events
| name | description |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| turnon | Fired when the compass is turned on. |
| turnoff | Fired when the compass is turned off. |
| error | Fired when the compass cannot be accessed due to permission denied or a timeout. |
| compass | Fired when the device orientation changes.
A `heading` number represents the difference between the motion of the device around the z axis of the world system and the direction of the north, expressed in degrees with values ranging from 0 to 360. |
## Reference
- https://developer.apple.com/documentation/webkitjs/deviceorientationevent
- https://developer.mozilla.org/en-US/docs/Web/API/Window/deviceorientationabsolute_event
## License
This project is licensed under the terms of the [MIT license](https://github.com/qazsato/maplibre-gl-compass/blob/main/LICENSE).