@maplibre/maplibre-gl-native 5.1.1 → 5.2.0-pre.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +43 -264
- package/package.json +11 -10
- package/platform/node/README.md +201 -0
- package/platform/node/index.d.ts +129 -0
package/README.md
CHANGED
|
@@ -1,300 +1,79 @@
|
|
|
1
|
-
|
|
1
|
+
[](https://maplibre.org/)
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
# MapLibre GL Native
|
|
4
4
|
|
|
5
|
-
MapLibre GL Native is a
|
|
5
|
+
MapLibre GL Native is a free and open-source library for publishing maps in your apps and desktop applications on various platforms. Fast displaying of maps is possible thanks to GPU-accelerated vector tile rendering.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
This project originated as a fork of Mapbox GL Native, before their switch to a non-OSS license in December 2020. For more information, see: [`FORK.md`](./FORK.md).
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
* The iOS binaries distribution was upgraded from fat packages to Swift package containing XCFramework.
|
|
13
|
-
* The Android binaries are distributed to GitHub maven package repository.
|
|
9
|
+
<p align="center">
|
|
10
|
+
<img src="https://user-images.githubusercontent.com/649392/211550776-8779041a-7c12-4bed-a7bd-c2ec80af2b29.png" alt="Android device with MapLibre" width="24%"> <img src="https://user-images.githubusercontent.com/649392/211550762-0f42ebc9-05ab-4d89-bd59-c306453ea9af.png" alt="iOS device with MapLibre" width="25%">
|
|
11
|
+
</p>
|
|
14
12
|
|
|
15
|
-
|
|
13
|
+
## Getting Started
|
|
16
14
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
## Build Status
|
|
20
|
-
|
|
21
|
-
| SDK | Build | Build status |
|
|
22
|
-
|---------------------------------------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
23
|
-
| [Maps SDK for iOS](platform/ios/) | CI | [](https://github.com/maplibre/maplibre-gl-native/workflows/ios-ci) |
|
|
24
|
-
| [Maps SDK for iOS](platform/ios/) | Release | [](https://github.com/maplibre/maplibre-gl-native/workflows/ios-release) |
|
|
25
|
-
| [Maps SDK for Android](platform/android/) | CI | [](https://github.com/maplibre/maplibre-gl-native/workflows/android-ci) |
|
|
26
|
-
| [Maps SDK for Android](platform/android/) | Release | [](https://github.com/maplibre/maplibre-gl-native/workflows/android-release) |
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
## Sponsors
|
|
30
|
-
|
|
31
|
-
We thank everyone who supported us financially in the past and special thanks to the people and organizations who support us with recurring donations!
|
|
32
|
-
|
|
33
|
-
Read more about the MapLibre Sponsorship Program at [https://maplibre.org/sponsors/](https://maplibre.org/sponsors/).
|
|
34
|
-
|
|
35
|
-
Platinum:
|
|
36
|
-
|
|
37
|
-
<img src="https://maplibre.org/img/aws-logo.svg" alt="Logo AWS" width="25%"/>
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
Silver:
|
|
41
|
-
|
|
42
|
-
<img src="https://maplibre.org/img/meta-logo.svg" alt="Logo Meta" width="50%"/>
|
|
43
|
-
|
|
44
|
-
Stone:
|
|
45
|
-
|
|
46
|
-
[MIERUNE Inc.](https://www.mierune.co.jp/?lang=en)
|
|
47
|
-
|
|
48
|
-
Backers and Supporters:
|
|
49
|
-
|
|
50
|
-
<a href="https://opencollective.com/maplibre/backer/0/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/0/avatar.svg?requireActive=false"></a>
|
|
51
|
-
<a href="https://opencollective.com/maplibre/backer/1/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/1/avatar.svg?requireActive=false"></a>
|
|
52
|
-
<a href="https://opencollective.com/maplibre/backer/2/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/2/avatar.svg?requireActive=false"></a>
|
|
53
|
-
<a href="https://opencollective.com/maplibre/backer/3/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/3/avatar.svg?requireActive=false"></a>
|
|
54
|
-
<a href="https://opencollective.com/maplibre/backer/4/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/4/avatar.svg?requireActive=false"></a>
|
|
55
|
-
<a href="https://opencollective.com/maplibre/backer/5/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/5/avatar.svg?requireActive=false"></a>
|
|
56
|
-
<a href="https://opencollective.com/maplibre/backer/6/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/6/avatar.svg?requireActive=false"></a>
|
|
57
|
-
<a href="https://opencollective.com/maplibre/backer/7/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/7/avatar.svg?requireActive=false"></a>
|
|
58
|
-
<a href="https://opencollective.com/maplibre/backer/8/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/8/avatar.svg?requireActive=false"></a>
|
|
59
|
-
<a href="https://opencollective.com/maplibre/backer/9/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/9/avatar.svg?requireActive=false"></a>
|
|
60
|
-
<a href="https://opencollective.com/maplibre/backer/10/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/10/avatar.svg?requireActive=false"></a>
|
|
61
|
-
<a href="https://opencollective.com/maplibre/backer/11/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/11/avatar.svg?requireActive=false"></a>
|
|
62
|
-
<a href="https://opencollective.com/maplibre/backer/12/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/12/avatar.svg?requireActive=false"></a>
|
|
63
|
-
<a href="https://opencollective.com/maplibre/backer/13/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/13/avatar.svg?requireActive=false"></a>
|
|
64
|
-
<a href="https://opencollective.com/maplibre/backer/14/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/14/avatar.svg?requireActive=false"></a>
|
|
65
|
-
<a href="https://opencollective.com/maplibre/backer/15/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/15/avatar.svg?requireActive=false"></a>
|
|
66
|
-
<a href="https://opencollective.com/maplibre/backer/16/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/16/avatar.svg?requireActive=false"></a>
|
|
67
|
-
<a href="https://opencollective.com/maplibre/backer/17/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/17/avatar.svg?requireActive=false"></a>
|
|
68
|
-
<a href="https://opencollective.com/maplibre/backer/18/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/18/avatar.svg?requireActive=false"></a>
|
|
69
|
-
<a href="https://opencollective.com/maplibre/backer/19/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/19/avatar.svg?requireActive=false"></a>
|
|
70
|
-
<a href="https://opencollective.com/maplibre/backer/20/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/20/avatar.svg?requireActive=false"></a>
|
|
71
|
-
<a href="https://opencollective.com/maplibre/backer/21/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/21/avatar.svg?requireActive=false"></a>
|
|
72
|
-
<a href="https://opencollective.com/maplibre/backer/22/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/22/avatar.svg?requireActive=false"></a>
|
|
73
|
-
<a href="https://opencollective.com/maplibre/backer/23/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/23/avatar.svg?requireActive=false"></a>
|
|
74
|
-
<a href="https://opencollective.com/maplibre/backer/24/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/24/avatar.svg?requireActive=false"></a>
|
|
75
|
-
<a href="https://opencollective.com/maplibre/backer/25/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/25/avatar.svg?requireActive=false"></a>
|
|
76
|
-
<a href="https://opencollective.com/maplibre/backer/26/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/26/avatar.svg?requireActive=false"></a>
|
|
77
|
-
<a href="https://opencollective.com/maplibre/backer/27/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/27/avatar.svg?requireActive=false"></a>
|
|
78
|
-
<a href="https://opencollective.com/maplibre/backer/28/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/28/avatar.svg?requireActive=false"></a>
|
|
79
|
-
<a href="https://opencollective.com/maplibre/backer/29/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/29/avatar.svg?requireActive=false"></a>
|
|
80
|
-
<a href="https://opencollective.com/maplibre/backer/30/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/30/avatar.svg?requireActive=false"></a>
|
|
15
|
+
To get started with MapLibre GL Native, go to your platform below.
|
|
81
16
|
|
|
82
17
|
## Documentation
|
|
83
18
|
|
|
84
|
-
The
|
|
85
|
-
|
|
86
|
-
The iOS API documentation is available at https://maplibre.org/maplibre-gl-native/ios/api/
|
|
87
|
-
|
|
88
|
-
Architecture: https://maplibre.org/maplibre-gl-native/docs/book/
|
|
89
|
-
|
|
90
|
-
## Installation
|
|
91
|
-
|
|
92
|
-
### Android
|
|
93
|
-
|
|
94
|
-
1. Add bintray maven repositories to your build.gradle at project level so that you can access MapLibre packages for Android:
|
|
95
|
-
|
|
96
|
-
```gradle
|
|
97
|
-
allprojects {
|
|
98
|
-
repositories {
|
|
99
|
-
...
|
|
100
|
-
mavenCentral()
|
|
101
|
-
}
|
|
102
|
-
}
|
|
103
|
-
```
|
|
104
|
-
|
|
105
|
-
> Note: [Bintray was turn off May 1st, 2021](https://jfrog.com/blog/into-the-sunset-bintray-jcenter-gocenter-and-chartcenter/) so we migrated all packages to maven central.
|
|
106
|
-
|
|
107
|
-
2. Add the library as a dependency into your module build.gradle
|
|
108
|
-
|
|
109
|
-
```gradle
|
|
110
|
-
dependencies {
|
|
111
|
-
...
|
|
112
|
-
implementation 'org.maplibre.gl:android-sdk:<version>'
|
|
113
|
-
...
|
|
114
|
-
}
|
|
115
|
-
```
|
|
116
|
-
|
|
117
|
-
3. Sync gradle and rebuild your app
|
|
118
|
-
|
|
119
|
-
*Note: MapLibre by default ships with the proprietary Google Play Location Services. If you want to avoid pulling proprietary dependencies into your project, you can exclude Google Play Location Services as follows:*
|
|
120
|
-
```gradle
|
|
121
|
-
implementation ('org.maplibre.gl:android-sdk:<version>') {
|
|
122
|
-
exclude group: 'com.google.android.gms'
|
|
123
|
-
}
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
### iOS
|
|
127
|
-
|
|
128
|
-
1. To add a package dependency to your Xcode project, select File > Swift Packages > Add Package Dependency and enter its repository URL. You can also navigate to your target’s General pane, and in the “Frameworks, Libraries, and Embedded Content” section, click the + button, select Add Other, and choose Add Package Dependency.
|
|
129
|
-
|
|
130
|
-
2. Either add MapLibre GitHub distribution URL (https://github.com/maplibre/maplibre-gl-native-distribution) or search for `maplibre-gl-native` package.
|
|
131
|
-
|
|
132
|
-
3. Choose "next". Xcode should clone the distribution repository and download the binaries.
|
|
133
|
-
|
|
134
|
-
## Alternative installation
|
|
19
|
+
The documentation of MapLibre GL Native is a work in progress. To get an architectural overview and to learn about the current state of the project and its path forward read the [MapLibre GL Native Markdown Book](https://maplibre.org/maplibre-gl-native/docs/book/). See below for platform-specific documentation.
|
|
135
20
|
|
|
136
|
-
|
|
21
|
+
## Platforms
|
|
137
22
|
|
|
138
|
-
|
|
23
|
+
- [⭐️ Android](platform/android/README.md)
|
|
24
|
+
- [⭐️ iOS](platform/ios/platform/ios/README.md)
|
|
25
|
+
- [GLFW](platform/glfw)
|
|
26
|
+
- [Linux](platform/linux/README.md)
|
|
27
|
+
- [Node.js](platform/node/README.md)
|
|
28
|
+
- [Qt](platform/qt/README.md)
|
|
29
|
+
- [Windows](platform/windows/README.md)
|
|
30
|
+
- [macOS](platform/ios/platform/macos/README.md)
|
|
139
31
|
|
|
140
|
-
|
|
32
|
+
Platforms with a ⭐️ are **MapLibre Core Projects** and have a substantial amount of financial resources allocated to them. Learn about the different [project tiers](https://github.com/maplibre/maplibre/blob/main/PROJECT_TIERS.md#project-tiers).
|
|
141
33
|
|
|
142
|
-
|
|
143
|
-
git clone --recurse-submodules https://github.com/maplibre/maplibre-gl-native.git
|
|
144
|
-
```
|
|
34
|
+
## Renderer Modularization & Metal
|
|
145
35
|
|
|
146
|
-
|
|
36
|
+
|
|
147
37
|
|
|
148
|
-
MapLibre
|
|
38
|
+
MapLibre GL Native is being actively developed. Our big goal for 2023 is to modularize the OpenGL renderer and implement a Metal graphics backend (https://developer.apple.com/metal/). This will improve the performance and yield lower power consumption on iOS devices. At the same time, the Metal preparations will help us in the implementation of a Vulkan graphics backend.
|
|
149
39
|
|
|
150
|
-
|
|
40
|
+
Your help in preparing the codebase for the latest graphics backends is more than welcome. Feel free to reach out if you are interested in joining the effort!
|
|
151
41
|
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
git tag
|
|
42
|
+
- Check out the [news](https://maplibre.org/news/) on MapLibre's website.
|
|
43
|
+
- See the [Design Proposals](https://github.com/louwers/maplibre-gl-native/tree/main/design-proposals) that have been accepted and are being worked on, the most recent ones being the [Rendering Modularization Design Proposal](design-proposals/2022-10-27-rendering-modularization.md) and the [Metal Port Design Proposal](design-proposals/2022-11-29-metal-port.md).
|
|
155
44
|
|
|
156
|
-
|
|
157
|
-
# TAG=android-v9.4.2
|
|
158
|
-
# TAG=android-v9.5.2
|
|
159
|
-
TAG=ios-v5.12.0
|
|
160
|
-
# TAG=ios-v5.12.0-pre.1
|
|
45
|
+
## Contributing
|
|
161
46
|
|
|
162
|
-
|
|
163
|
-
git checkout tags/$TAG -b $TAG
|
|
47
|
+
To contribute to MapLibre GL Native, see [`CONTRIBUTING.md`](CONTRIBUTING.md) and (if applicable) the specific instructions for the platform you want to contribute to.
|
|
164
48
|
|
|
165
|
-
|
|
166
|
-
# clean, if you need to troubleshoot build dependencies by using `make clean`
|
|
167
|
-
```
|
|
49
|
+
### Getting Involved
|
|
168
50
|
|
|
169
|
-
|
|
51
|
+
Join the `#maplibre-native` Slack channel at OSMUS. Get an invite at https://slack.openstreetmap.us/
|
|
170
52
|
|
|
171
|
-
[Bazel](https://bazel.build) is also supported as a build option for getting a packaged release of the xcframework compiled for either static or dynamic linking.
|
|
172
53
|
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
`brew install baselisk`
|
|
176
|
-
|
|
177
|
-
From there you can use the script in platform/ios/platform/ios/scripts/package-bazel.sh
|
|
178
|
-
|
|
179
|
-
#### There are 4 options:
|
|
180
|
-
|
|
181
|
-
`cd platform/ios/platform/ios/scripts`
|
|
182
|
-
|
|
183
|
-
Static xcframework compiled for release (this is default if no parameters are provided):
|
|
184
|
-
`./bazel-package.sh --static --release`
|
|
185
|
-
|
|
186
|
-
Static xcframework compiled for debug:
|
|
187
|
-
`./bazel-package.sh --static --debug`
|
|
188
|
-
|
|
189
|
-
Dynamic xcframework compiled for release:
|
|
190
|
-
`./bazel-package.sh --dynamic --release`
|
|
191
|
-
|
|
192
|
-
Dynamic xcframework compiled for debug:
|
|
193
|
-
`./bazel-package.sh --dynamic --debug`
|
|
194
|
-
|
|
195
|
-
All compiled frameworks will end up in the `bazel-bin/platform/ios/` path from the root of the repo.
|
|
196
|
-
|
|
197
|
-
Also you can use the link option to ensure that the framework is able to link.
|
|
198
|
-
|
|
199
|
-
`./bazel-package.sh --link`
|
|
200
|
-
|
|
201
|
-
#### Bazel build files are placed in a few places throughout the project:
|
|
202
|
-
|
|
203
|
-
`BUILD.bazel`
|
|
204
|
-
- Covering the base cpp in the root `src` directory.
|
|
205
|
-
|
|
206
|
-
`vendor/BUILD.bazel`
|
|
207
|
-
- Covering the submodule dependencies of Maplibre.
|
|
208
|
-
|
|
209
|
-
`platform/default/BUILD.bazel`
|
|
210
|
-
- Covering the cpp dependencies in default.
|
|
211
|
-
|
|
212
|
-
`platform/darwin/BUILD.bazel`
|
|
213
|
-
- Covering the cpp source in platform/default.
|
|
214
|
-
|
|
215
|
-
`platform/ios/platform/ios/vendor/`
|
|
216
|
-
- Covering the iOS specific dependencies.
|
|
217
|
-
|
|
218
|
-
`platform/ios/BUILD.bazel`
|
|
219
|
-
- Covering the source in `platform/ios/platform/ios/src` and `platform/ios/platform/darwin/src` as well as defining all the other BUILD.bazel files and defining the xcframework targets.
|
|
220
|
-
|
|
221
|
-
#### There are also some other areas that make bazel work:
|
|
222
|
-
|
|
223
|
-
`WORKSPACE`
|
|
224
|
-
- Defines the "repo" and the different modules that are loaded in order to compile for Apple.
|
|
225
|
-
|
|
226
|
-
`.bazelversion`
|
|
227
|
-
- Defines the version of bazel used, important for specific support for Apple targets.
|
|
228
|
-
|
|
229
|
-
`bazel/flags.bzl`
|
|
230
|
-
- Defines some compilation flags that are used between the different build files.
|
|
231
|
-
|
|
232
|
-
### Android
|
|
233
|
-
|
|
234
|
-
---
|
|
235
|
-
|
|
236
|
-
<details open><summary>macOS Build Environment: Android Studio + NDK</summary>
|
|
237
|
-
<ul>
|
|
238
|
-
<li>Environment: Android Studio + NDK<ul>
|
|
239
|
-
<li><code style="font-family: Menlo, Consolas, "DejaVu Sans Mono", monospace;">JAVA_HOME=/Applications/Android Studio.app/Contents/jre/Contents/Home</code></li>
|
|
240
|
-
<li><code style="font-family: Menlo, Consolas, "DejaVu Sans Mono", monospace;">ANDROID_SDK_ROOT=~/Library/Android/sdk</code></li>
|
|
241
|
-
<li><code style="font-family: Menlo, Consolas, "DejaVu Sans Mono", monospace;">~/Library/Android/sdk/tools/bin/sdkmanager --install ndk;major.minor.build</code></li>
|
|
242
|
-
</ul>
|
|
243
|
-
</details>
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
```bash
|
|
247
|
-
cd platform/android
|
|
248
|
-
BUILDTYPE=Debug make apackage
|
|
249
|
-
#BUILDTYPE=Release make apackage
|
|
250
|
-
```
|
|
251
|
-
|
|
252
|
-
Binaries are produced in `platform/android/MapboxGLAndroidSDK/build/outputs/aar/MapboxGLAndroidSDK-<BUILDTYPE>.aar`
|
|
253
|
-
Please refer to [Mapbox Maps SDK for Android](platform/android/) for detailed instructions.
|
|
254
|
-
|
|
255
|
-
### iOS
|
|
256
|
-
|
|
257
|
-
You can run automated test on a Simulator or Device by changing to the Scheme `iosapp` and choosing `Product` > `Test` (or use `⌘-U`). Use `⌘-9` to navigate to `Reports` to see results and browse through screenshots. This method of testing should work well with CI tools such as GitHub Actions, Xcode Server Bots, & AWS Device Farm.
|
|
258
|
-
|
|
259
|
-
```bash
|
|
260
|
-
cd platform/ios
|
|
54
|
+
## Sponsors
|
|
261
55
|
|
|
262
|
-
|
|
263
|
-
make iproj
|
|
56
|
+
We thank everyone who supported us financially in the past and special thanks to the people and organizations who support us with recurring donations!
|
|
264
57
|
|
|
265
|
-
|
|
266
|
-
make iproj CI=1
|
|
58
|
+
Read more about the MapLibre Sponsorship Program at [https://maplibre.org/sponsors/](https://maplibre.org/sponsors/).
|
|
267
59
|
|
|
268
|
-
|
|
269
|
-
make xcframework BUILDTYPE=Release
|
|
60
|
+
Platinum:
|
|
270
61
|
|
|
271
|
-
|
|
272
|
-
make ios-test
|
|
62
|
+
<img src="https://maplibre.org/img/aws-logo.svg" alt="Logo AWS" width="25%"/>
|
|
273
63
|
|
|
274
|
-
# UITests
|
|
275
|
-
# You can review uitest results: $(IOS_OUTPUT_PATH)/Logs/Test
|
|
276
|
-
make ios-uitest
|
|
277
|
-
```
|
|
278
64
|
|
|
279
|
-
|
|
280
|
-
Please refer to [Mapbox Maps SDK for iOS](platform/ios/platform/ios/) for detailed instructions.
|
|
65
|
+
Silver:
|
|
281
66
|
|
|
67
|
+
<img src="https://maplibre.org/img/meta-logo.svg" alt="Logo Meta" width="50%"/>
|
|
282
68
|
|
|
283
|
-
|
|
69
|
+
Stone:
|
|
284
70
|
|
|
285
|
-
|
|
286
|
-
cd platform/ios
|
|
287
|
-
# open macOS project in Xcode
|
|
288
|
-
make xproj
|
|
71
|
+
[MIERUNE Inc.](https://www.mierune.co.jp/?lang=en)
|
|
289
72
|
|
|
290
|
-
|
|
291
|
-
make xpackage
|
|
292
|
-
make macos-test
|
|
293
|
-
```
|
|
73
|
+
Backers and Supporters:
|
|
294
74
|
|
|
295
|
-
|
|
296
|
-
Please refer to [Mapbox Maps SDK for macos](platform/ios/platform/macos/) for detailed instructions.
|
|
75
|
+
[](https://opencollective.com/maplibre)
|
|
297
76
|
|
|
298
|
-
|
|
77
|
+
## License
|
|
299
78
|
|
|
300
|
-
|
|
79
|
+
**MapLibre GL Native** is licensed under the [BSD 2-Clause License](./LICENSE.md).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@maplibre/maplibre-gl-native",
|
|
3
|
-
"version": "5.
|
|
3
|
+
"version": "5.2.0-pre.0",
|
|
4
4
|
"description": "Renders map tiles with Maplibre GL",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"maplibre",
|
|
@@ -10,27 +10,28 @@
|
|
|
10
10
|
"lib": "lib"
|
|
11
11
|
},
|
|
12
12
|
"files": [
|
|
13
|
-
"lib"
|
|
13
|
+
"lib",
|
|
14
|
+
"platform/node/index.d.ts"
|
|
14
15
|
],
|
|
15
16
|
"main": "platform/node/index.js",
|
|
17
|
+
"types": "platform/node/index.d.ts",
|
|
16
18
|
"repository": {
|
|
17
19
|
"type": "git",
|
|
18
20
|
"url": "git+https://github.com/maplibre/maplibre-gl-native.git"
|
|
19
21
|
},
|
|
20
22
|
"license": "BSD-2-Clause",
|
|
21
23
|
"dependencies": {
|
|
22
|
-
"@mapbox/cmake-node-module": "^1.2.0",
|
|
23
24
|
"@acalcutt/node-pre-gyp": "^1.0.11",
|
|
24
25
|
"@acalcutt/node-pre-gyp-github": "1.4.8",
|
|
25
|
-
"minimatch": "^
|
|
26
|
+
"minimatch": "^7.0.0",
|
|
26
27
|
"npm-run-all": "^4.0.2"
|
|
27
28
|
},
|
|
28
29
|
"devDependencies": {
|
|
29
30
|
"@mapbox/flow-remove-types": "^2.0.0",
|
|
30
31
|
"@mapbox/mvt-fixtures": "3.10.0",
|
|
31
|
-
"@octokit/plugin-retry": "^
|
|
32
|
-
"@octokit/rest": "^19.0.
|
|
33
|
-
"aws-sdk": "^2.
|
|
32
|
+
"@octokit/plugin-retry": "^4.1.2",
|
|
33
|
+
"@octokit/rest": "^19.0.7",
|
|
34
|
+
"aws-sdk": "^2.1318.0",
|
|
34
35
|
"csscolorparser": "~1.0.2",
|
|
35
36
|
"d3-queue": "3.0.7",
|
|
36
37
|
"diff": "5.1.0",
|
|
@@ -38,18 +39,18 @@
|
|
|
38
39
|
"esm": "~3.2.25",
|
|
39
40
|
"express": "^4.18.2",
|
|
40
41
|
"json-stringify-pretty-compact": "^4.0.0",
|
|
41
|
-
"jsonwebtoken": "^
|
|
42
|
+
"jsonwebtoken": "^9.0.0",
|
|
42
43
|
"lodash": "^4.16.4",
|
|
43
44
|
"lodash.template": "4.5.0",
|
|
44
45
|
"mapbox-gl-styles": "2.0.2",
|
|
45
46
|
"pixelmatch": "^5.3.0",
|
|
46
47
|
"pngjs": "^6.0.0",
|
|
47
|
-
"pretty-bytes": "^6.
|
|
48
|
+
"pretty-bytes": "^6.1.0",
|
|
48
49
|
"request": "^2.88.0",
|
|
49
50
|
"semver": "^7.3.8",
|
|
50
51
|
"shuffle-seed": "1.1.6",
|
|
51
52
|
"st": "3.0.0",
|
|
52
|
-
"tape": "^5.6.
|
|
53
|
+
"tape": "^5.6.3",
|
|
53
54
|
"xcode": "^3.0.1"
|
|
54
55
|
},
|
|
55
56
|
"engines": {
|
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
# @maplibre/maplibre-gl-native
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@maplibre/maplibre-gl-native)
|
|
4
|
+
[](https://github.com/maplibre/maplibre-gl-native/actions/workflows/node-ci.yml)
|
|
5
|
+
|
|
6
|
+
## Installing
|
|
7
|
+
|
|
8
|
+
Binaries are available and downloaded during install for the following platforms:
|
|
9
|
+
|
|
10
|
+
- Operating systems:
|
|
11
|
+
- Ubuntu 20.04 (amd64/arm64)
|
|
12
|
+
- macOS 12 (amd64/arm64)
|
|
13
|
+
- Node.js 14, 16, 18
|
|
14
|
+
|
|
15
|
+
Run:
|
|
16
|
+
|
|
17
|
+
```
|
|
18
|
+
npm install @maplibre/maplibre-gl-native
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Further platforms might work [with additional libraries installed](https://github.com/maplibre/maplibre-gl-native/tree/main/platform/linux#prerequisites).
|
|
22
|
+
|
|
23
|
+
## Testing
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
npm test
|
|
27
|
+
npm run test-suite
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Rendering a map tile
|
|
31
|
+
|
|
32
|
+
```js
|
|
33
|
+
var fs = require('fs');
|
|
34
|
+
var path = require('path');
|
|
35
|
+
var mbgl = require('@maplibre/maplibre-gl-native');
|
|
36
|
+
var sharp = require('sharp');
|
|
37
|
+
|
|
38
|
+
var options = {
|
|
39
|
+
request: function(req, callback) {
|
|
40
|
+
fs.readFile(path.join(__dirname, 'test', req.url), function(err, data) {
|
|
41
|
+
callback(err, { data: data });
|
|
42
|
+
});
|
|
43
|
+
},
|
|
44
|
+
ratio: 1
|
|
45
|
+
};
|
|
46
|
+
|
|
47
|
+
var map = new mbgl.Map(options);
|
|
48
|
+
|
|
49
|
+
map.load(require('./test/fixtures/style.json'));
|
|
50
|
+
|
|
51
|
+
map.render({zoom: 0}, function(err, buffer) {
|
|
52
|
+
if (err) throw err;
|
|
53
|
+
|
|
54
|
+
map.release();
|
|
55
|
+
|
|
56
|
+
var image = sharp(buffer, {
|
|
57
|
+
raw: {
|
|
58
|
+
width: 512,
|
|
59
|
+
height: 512,
|
|
60
|
+
channels: 4
|
|
61
|
+
}
|
|
62
|
+
});
|
|
63
|
+
|
|
64
|
+
// Convert raw image buffer to PNG
|
|
65
|
+
image.toFile('image.png', function(err) {
|
|
66
|
+
if (err) throw err;
|
|
67
|
+
});
|
|
68
|
+
});
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
The first argument passed to `map.render` is an options object, all keys are optional:
|
|
72
|
+
|
|
73
|
+
```js
|
|
74
|
+
{
|
|
75
|
+
zoom: {zoom}, // number, defaults to 0
|
|
76
|
+
width: {width}, // number (px), defaults to 512
|
|
77
|
+
height: {height}, // number (px), defaults to 512
|
|
78
|
+
center: [{longitude}, {latitude}], // array of numbers (coordinates), defaults to [0,0]
|
|
79
|
+
bearing: {bearing}, // number (in degrees, counter-clockwise from north), defaults to 0
|
|
80
|
+
pitch: {pitch}, // number (in degrees, arcing towards the horizon), defaults to 0
|
|
81
|
+
classes: {classes} // array of strings
|
|
82
|
+
}
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
When you are finished using a map object, you can call `map.release()` to permanently dispose the internal map resources. This is not necessary, but can be helpful to optimize resource usage (memory, file sockets) on a more granular level than V8's garbage collector. Calling `map.release()` will prevent a map object from being used for any further render calls, but can be safely called as soon as the `map.render()` callback returns, as the returned pixel buffer will always be retained for the scope of the callback.
|
|
86
|
+
|
|
87
|
+
## Implementing a file source
|
|
88
|
+
|
|
89
|
+
When creating a `Map`, you must pass an options object (with a required `request` method and optional 'ratio' number) as the first parameter.
|
|
90
|
+
|
|
91
|
+
```js
|
|
92
|
+
var map = new mbgl.Map({
|
|
93
|
+
request: function(req) {
|
|
94
|
+
// TODO
|
|
95
|
+
},
|
|
96
|
+
ratio: 2.0
|
|
97
|
+
});
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
The `request()` method handles a request for a resource. The `ratio` sets the scale at which the map will render tiles, such as `2.0` for rendering images for high pixel density displays. The `req` parameter has two properties:
|
|
101
|
+
|
|
102
|
+
```json
|
|
103
|
+
{
|
|
104
|
+
"url": "http://example.com",
|
|
105
|
+
"kind": 1
|
|
106
|
+
}
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
The `kind` is an enum and defined in [`mbgl.Resource`](https://github.com/maplibre/maplibre-gl-native/blob/main/include/mbgl/storage/resource.hpp):
|
|
110
|
+
|
|
111
|
+
```json
|
|
112
|
+
{
|
|
113
|
+
"Unknown": 0,
|
|
114
|
+
"Style": 1,
|
|
115
|
+
"Source": 2,
|
|
116
|
+
"Tile": 3,
|
|
117
|
+
"Glyphs": 4,
|
|
118
|
+
"SpriteImage": 5,
|
|
119
|
+
"SpriteJSON": 6
|
|
120
|
+
}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
The `kind` enum has no significance for anything but serves as a hint to your implemention as to what sort of resource to expect. E.g., your implementation could choose caching strategies based on the expected file type.
|
|
124
|
+
|
|
125
|
+
The `request` implementation should pass uncompressed data to `callback`. If you are downloading assets from a source that applies gzip transport encoding, the implementation must decompress the results before passing them on.
|
|
126
|
+
|
|
127
|
+
A sample implementation that reads files from disk would look like the following:
|
|
128
|
+
|
|
129
|
+
```js
|
|
130
|
+
var map = new mbgl.Map({
|
|
131
|
+
request: function(req, callback) {
|
|
132
|
+
fs.readFile(path.join('base/path', req.url), function(err, data) {
|
|
133
|
+
callback(err, { data: data });
|
|
134
|
+
});
|
|
135
|
+
}
|
|
136
|
+
});
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
This is a very barebones implementation and you'll probably want a better implementation. E.g. it passes the url verbatim to the file system, but you'd want add some logic that normalizes `http` URLs. You'll notice that once your implementation has obtained the requested file, you have to deliver it to the requestee by calling `callback()`, which takes either an error object or `null` and an object with several keys:
|
|
140
|
+
|
|
141
|
+
```js
|
|
142
|
+
{
|
|
143
|
+
modified: new Date(),
|
|
144
|
+
expires: new Date(),
|
|
145
|
+
etag: "string",
|
|
146
|
+
data: new Buffer()
|
|
147
|
+
}
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
A sample implementation that uses [`request`](https://github.com/request/request) to fetch data from a remote source:
|
|
151
|
+
|
|
152
|
+
```js
|
|
153
|
+
var mbgl = require('@maplibre/maplibre-gl-native');
|
|
154
|
+
var request = require('request');
|
|
155
|
+
|
|
156
|
+
var map = new mbgl.Map({
|
|
157
|
+
request: function(req, callback) {
|
|
158
|
+
request({
|
|
159
|
+
url: req.url,
|
|
160
|
+
encoding: null,
|
|
161
|
+
gzip: true
|
|
162
|
+
}, function (err, res, body) {
|
|
163
|
+
if (err) {
|
|
164
|
+
callback(err);
|
|
165
|
+
} else if (res.statusCode == 200) {
|
|
166
|
+
var response = {};
|
|
167
|
+
|
|
168
|
+
if (res.headers.modified) { response.modified = new Date(res.headers.modified); }
|
|
169
|
+
if (res.headers.expires) { response.expires = new Date(res.headers.expires); }
|
|
170
|
+
if (res.headers.etag) { response.etag = res.headers.etag; }
|
|
171
|
+
|
|
172
|
+
response.data = body;
|
|
173
|
+
|
|
174
|
+
callback(null, response);
|
|
175
|
+
} else {
|
|
176
|
+
callback(new Error(JSON.parse(body).message));
|
|
177
|
+
}
|
|
178
|
+
});
|
|
179
|
+
}
|
|
180
|
+
});
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
Stylesheets are free to use any protocols, but your implementation of `request` must support these; e.g. you could use `s3://` to indicate that files are supposed to be loaded from S3.
|
|
184
|
+
|
|
185
|
+
## Listening for log events
|
|
186
|
+
|
|
187
|
+
The module imported with `require('maplibre-gl-native')` inherits from [`EventEmitter`](https://nodejs.org/api/events.html), and the `NodeLogObserver` will push log events to this. Log messages can have [`class`](https://github.com/maplibre/maplibre-gl-native/blob/node-v2.1.0/include/mbgl/platform/event.hpp#L43-L60), [`severity`](https://github.com/maplibre/maplibre-gl-native/blob/node-v2.1.0/include/mbgl/platform/event.hpp#L17-L23), `code` ([HTTP status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html)), and `text` parameters.
|
|
188
|
+
|
|
189
|
+
```js
|
|
190
|
+
var mbgl = require('@maplibre/maplibre-gl-native');
|
|
191
|
+
mbgl.on('message', function(msg) {
|
|
192
|
+
t.ok(msg, 'emits error');
|
|
193
|
+
t.equal(msg.class, 'Style');
|
|
194
|
+
t.equal(msg.severity, 'ERROR');
|
|
195
|
+
t.ok(msg.text.match(/Failed to load/), 'error text matches');
|
|
196
|
+
});
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
## Contributing
|
|
200
|
+
|
|
201
|
+
See [DEVELOPING.md](DEVELOPING.md) for instructions on building this module for development.
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
declare module '@maplibre/maplibre-gl-native' {
|
|
2
|
+
const enum ResourceKind {
|
|
3
|
+
Unknown = 0,
|
|
4
|
+
Style = 1,
|
|
5
|
+
Source = 2,
|
|
6
|
+
Tile = 3,
|
|
7
|
+
Glyphs = 4,
|
|
8
|
+
SpriteImage = 5,
|
|
9
|
+
SpriteJSON = 6,
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* Response expected by a request call during render
|
|
14
|
+
*/
|
|
15
|
+
type RequestResponse = {
|
|
16
|
+
data: Uint8Array;
|
|
17
|
+
modified?: Date;
|
|
18
|
+
expires?: Date;
|
|
19
|
+
etag?: string;
|
|
20
|
+
};
|
|
21
|
+
|
|
22
|
+
const enum MapMode {
|
|
23
|
+
/**
|
|
24
|
+
* Render all tiles in map view
|
|
25
|
+
*/
|
|
26
|
+
Static = 'static',
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Render and request only a single tile
|
|
30
|
+
*/
|
|
31
|
+
Tile = 'tile',
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
type MapOptions = {
|
|
35
|
+
/**
|
|
36
|
+
* Will be used during a `Map.render` call to request all necessary map resources (tiles, fonts...)
|
|
37
|
+
*/
|
|
38
|
+
request: (
|
|
39
|
+
request: { url: string; kind: ResourceKind },
|
|
40
|
+
callback: (error?: Error, response?: RequestResponse) => void,
|
|
41
|
+
) => void;
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* Pixel ratio at which to render images
|
|
45
|
+
*
|
|
46
|
+
* @default 1
|
|
47
|
+
*/
|
|
48
|
+
ratio?: number;
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* Mode in which map view will be rendered
|
|
52
|
+
*
|
|
53
|
+
* @default MapMode.Static
|
|
54
|
+
*/
|
|
55
|
+
mode?: MapMode;
|
|
56
|
+
};
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* Defines the map view to render and the resulting image
|
|
60
|
+
*/
|
|
61
|
+
type RenderOptions = {
|
|
62
|
+
/**
|
|
63
|
+
* @default 0
|
|
64
|
+
*/
|
|
65
|
+
zoom?: number;
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* Width of image in pixel
|
|
69
|
+
*
|
|
70
|
+
* @default 512
|
|
71
|
+
*/
|
|
72
|
+
width?: number;
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* Height of image in pixel
|
|
76
|
+
*
|
|
77
|
+
* @default 512
|
|
78
|
+
*/
|
|
79
|
+
height?: number;
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* Coordinates [longitude, latitude]
|
|
83
|
+
*
|
|
84
|
+
* @default [0, 0]
|
|
85
|
+
*/
|
|
86
|
+
center?: [number, number];
|
|
87
|
+
|
|
88
|
+
/**
|
|
89
|
+
* Bearing of map view in degrees, counter-clockwise from north
|
|
90
|
+
*
|
|
91
|
+
* @default 0
|
|
92
|
+
*/
|
|
93
|
+
bearing?: number;
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* Pitch of map view in degrees, arcing towards the horizon
|
|
97
|
+
*
|
|
98
|
+
* @default 0
|
|
99
|
+
*/
|
|
100
|
+
pitch?: number;
|
|
101
|
+
|
|
102
|
+
/**
|
|
103
|
+
* @default []
|
|
104
|
+
*/
|
|
105
|
+
classes?: string[];
|
|
106
|
+
};
|
|
107
|
+
|
|
108
|
+
/**
|
|
109
|
+
* A `Map` instance is used to render images from map views
|
|
110
|
+
*/
|
|
111
|
+
class Map {
|
|
112
|
+
constructor(mapOptions: MapOptions);
|
|
113
|
+
|
|
114
|
+
load: (style: any) => void;
|
|
115
|
+
|
|
116
|
+
/**
|
|
117
|
+
* Render a specific map view to an image with previously loaded map styles
|
|
118
|
+
*/
|
|
119
|
+
render: (
|
|
120
|
+
renderOptions: RenderOptions,
|
|
121
|
+
callback: (...args: [error: Error, buffer: undefined] | [error: undefined, buffer: Uint8Array]) => void,
|
|
122
|
+
) => void;
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* Call to permanently dispose the internal map resources, instance can't be used for further render calls
|
|
126
|
+
*/
|
|
127
|
+
release: () => void;
|
|
128
|
+
}
|
|
129
|
+
}
|