@acalcutt/maplibre-gl-native-test 5.3.0-pre.1 → 5.4.1-pre.2

package/README.md

@@ -1,81 +1,246 @@
-[![MapLibre Logo](https://maplibre.org/img/maplibre-logo-big.svg)](https://maplibre.org/)
+# @maplibre/maplibre-gl-native
 
-# MapLibre Native
+[![Version](https://img.shields.io/npm/v/@maplibre/maplibre-gl-native?style=flat)](https://www.npmjs.com/package/@maplibre/maplibre-gl-native)
+[![node-ci](https://github.com/maplibre/maplibre-native/actions/workflows/node-ci.yml/badge.svg)](https://github.com/maplibre/maplibre-native/actions/workflows/node-ci.yml)
 
-MapLibre 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.
+## Installing
 
-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).
+Binaries are available and downloaded during install for the following platforms:
 
-<p align="center">
-  <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%">
-</p>
+- Operating systems:
+  - Ubuntu 22.04 (amd64/arm64)
+  - macOS 12 (amd64/arm64)
+  - Windows (amd64)
+- Node.js 16, 18, 20
 
-## Getting Started
+Run:
 
-To get started with MapLibre Native, go to your platform below.
+```
+npm install @maplibre/maplibre-gl-native
+```
 
-## Documentation
+Further platforms might work [with additional libraries installed](https://github.com/maplibre/maplibre-native/tree/main/platform/linux#prerequisites).
 
-The documentation of MapLibre 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 Native Markdown Book](https://maplibre.org/maplibre-native/docs/book/). See below for platform-specific documentation.
+## Testing
 
-## Platforms
+```
+npm test
+```
 
-- [⭐️ Android](platform/android/README.md) 
-- [⭐️ iOS](platform/ios/platform/ios/README.md)
-- [GLFW](platform/glfw)
-- [Linux](platform/linux/README.md)
-- [Node.js](platform/node/README.md)
-- [Qt](platform/qt/README.md)
-- [Windows](platform/windows/README.md)
-- [macOS](platform/ios/platform/macos/README.md)
+## Rendering a map tile
 
-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).
+The minimal example requires only the instantiation of the `mbgl.Map` object, loading a style and calling the `map.render` method:
 
-## Renderer Modularization & Metal
+```js
+var mbgl = require('@maplibre/maplibre-gl-native');
+var sharp = require('sharp');
 
-![image-metal](https://user-images.githubusercontent.com/53421382/214308933-66cd4efb-b5a5-4de3-b4b4-7ed59045a1c3.png)
+var map = new mbgl.Map();
 
-MapLibre 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.
+map.load(require('./test/fixtures/style.json'));
 
-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!
+map.render(function(err, buffer) {
+    if (err) throw err;
 
-- Check out the [news](https://maplibre.org/news/) on MapLibre's website.
-- See the [Design Proposals](https://github.com/maplibre/maplibre-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).
+    map.release();
 
-## Contributing
-
-To contribute to MapLibre Native, see [`CONTRIBUTING.md`](CONTRIBUTING.md) and (if applicable) the specific instructions for the platform you want to contribute to.
-
-### Getting Involved
-
-Join the `#maplibre-native` Slack channel at OSMUS. Get an invite at https://slack.openstreetmap.us/ 
-
-### Bounties 💰
-
-Thanks to our sponsors, we are able to award bounties to developers making contributions toward certain [bounty directions](https://github.com/maplibre/maplibre/issues?q=is%3Aissue+is%3Aopen+label%3A%22bounty+direction%22). To get started doing bounties, refer to the [step-by-step bounties guide](https://maplibre.org/roadmap/step-by-step-bounties-guide/).
-
-## Sponsors
+    var image = sharp(buffer, {
+        raw: {
+            width: 512,
+            height: 512,
+            channels: 4
+        }
+    });
 
-We thank everyone who supported us financially in the past and special thanks to the people and organizations who support us with recurring donations!
+    // Convert raw image buffer to PNG
+    image.toFile('image.png', function(err) {
+        if (err) throw err;
+    });
+});
+```
 
-Read more about the MapLibre Sponsorship Program at [https://maplibre.org/sponsors/](https://maplibre.org/sponsors/).
+But you can customize the map providing an options object to `mbgl.Map` constructor and to `map.render` method:
 
-Platinum:
+```js
+var fs = require('fs');
+var path = require('path');
+var mbgl = require('@maplibre/maplibre-gl-native');
+var sharp = require('sharp');
 
-<a href="https://aws.com"><img src="https://maplibre.org/img/aws-logo.svg" alt="Logo AWS" width="25%"/></a>
+var options = {
+  request: function(req, callback) {
+    fs.readFile(path.join(__dirname, 'test', req.url), function(err, data) {
+      callback(err, { data: data });
+    });
+  },
+  ratio: 1
+};
+
+var map = new mbgl.Map(options);
+
+map.load(require('./test/fixtures/style.json'));
+
+map.render({zoom: 0}, function(err, buffer) {
+    if (err) throw err;
+
+    map.release();
+
+    var image = sharp(buffer, {
+        raw: {
+            width: 512,
+            height: 512,
+            channels: 4
+        }
+    });
+
+    // Convert raw image buffer to PNG
+    image.toFile('image.png', function(err) {
+        if (err) throw err;
+    });
+});
+```
+
+The first argument passed to `map.render` is an options object, all keys are optional:
+
+```js
+{
+    zoom: {zoom}, // number, defaults to 0
+    width: {width}, // number (px), defaults to 512
+    height: {height}, // number (px), defaults to 512
+    center: [{longitude}, {latitude}], // array of numbers (coordinates), defaults to [0,0]
+    bearing: {bearing}, // number (in degrees, counter-clockwise from north), defaults to 0
+    pitch: {pitch}, // number (in degrees, arcing towards the horizon), defaults to 0
+    classes: {classes} // array of strings
+}
+```
+
+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.
+
+## Implementing a file source
+
+When creating a `Map`, you can optionally pass an options object (with an optional `request` method and optional `ratio` number) as the first parameter. 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:
+
+```js
+var map = new mbgl.Map({
+    request: function(req) {
+        // TODO
+    },
+    ratio: 2.0
+});
+```
+
+If you omit the `request` method, the `map` object will use the default internal request handlers, which is ok for most cases. However, if you have specific needs, you can implement your own `request` handler. When a `request` method is provided, all `map` resources will be requested by calling the `request` method with two parameters, called `req` and `callback` respectively in this example. The `req` parameter has two properties:
+
+```json
+{
+    "url": "http://example.com",
+    "kind": 1
+}
+```
+
+The `kind` is an enum and defined in [`mbgl.Resource`](https://github.com/maplibre/maplibre-native/blob/main/include/mbgl/storage/resource.hpp):
+
+```json
+{
+    "Unknown": 0,
+    "Style": 1,
+    "Source": 2,
+    "Tile": 3,
+    "Glyphs": 4,
+    "SpriteImage": 5,
+    "SpriteJSON": 6
+}
+```
+
+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.
+
+The `callback` parameter is a function that must be called with two parameters: an error message (if there are no errors, then you must pass `null`), and a response object:
+
+```js
+{
+    data: {data}, // required, must be a byte array, usually a Buffer object
+    modified: {modified}, // Date, optional
+    expires: {expires}, // Date, optional
+    etag: {etag} // string, optional
+}
+```
+
+If there is no data to be sent to the `callback` (empty data, or `no-content` respose), then it must be called without parameters. 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.
+
+A sample implementation that reads files from disk would look like the following:
+
+```js
+var map = new mbgl.Map({
+    request: function(req, callback) {
+        fs.readFile(path.join('base/path', req.url), function(err, data) {
+            callback(err, { data: data });
+        });
+    }
+});
+```
+
+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:
+
+```js
+{
+    modified: new Date(),
+    expires: new Date(),
+    etag: "string",
+    data: new Buffer()
+}
+```
+
+A sample implementation that uses [`request`](https://github.com/request/request) to fetch data from a remote source:
+
+```js
+var mbgl = require('@maplibre/maplibre-gl-native');
+var request = require('request');
+
+var map = new mbgl.Map({
+    request: function(req, callback) {
+        request({
+            url: req.url,
+            encoding: null,
+            gzip: true
+        }, function (err, res, body) {
+            if (err) {
+                callback(err);
+            } else if (res.statusCode == 200) {
+                var response = {};
+
+                if (res.headers.modified) { response.modified = new Date(res.headers.modified); }
+                if (res.headers.expires) { response.expires = new Date(res.headers.expires); }
+                if (res.headers.etag) { response.etag = res.headers.etag; }
+
+                response.data = body;
+
+                callback(null, response);
+            } else if (res.statusCode == 204) {
+                callback();
+            } else {
+                callback(new Error(JSON.parse(body).message));
+            }
+        });
+    }
+});
+```
+
+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.
+
+## Listening for log events
+
+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-native/blob/node-v2.1.0/include/mbgl/platform/event.hpp#L43-L60), [`severity`](https://github.com/maplibre/maplibre-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.
+
+```js
+var mbgl = require('@maplibre/maplibre-gl-native');
+mbgl.on('message', function(msg) {
+    t.ok(msg, 'emits error');
+    t.equal(msg.class, 'Style');
+    t.equal(msg.severity, 'ERROR');
+    t.ok(msg.text.match(/Failed to load/), 'error text matches');
+});
+```
 
-Silver:
-
-<a href="https://meta.com"><img src="https://maplibre.org/img/meta-logo.svg" alt="Logo Meta" width="25%"/></a>
-
-<a href="https://www.mierune.co.jp/?lang=en"><img src="https://maplibre.org/img/mierune-logo.svg" alt="Logo MIERUNE" width="25%"/></a>
-
-<a href="https://komoot.com/"><img src="https://maplibre.org/img/komoot-logo.svg" alt="Logo komoot" width="25%"/></a>
-
-Backers and Supporters:
-
-[![](https://opencollective.com/maplibre/backers.svg?avatarHeight=50&width=600)](https://opencollective.com/maplibre)
-
-## License
+## Contributing
 
-**MapLibre Native** is licensed under the [BSD 2-Clause License](./LICENSE.md).
+See [DEVELOPING.md](DEVELOPING.md) for instructions on building this module for development.

package/{platform/node/index.js → index.js}

@@ -2,7 +2,7 @@
 
 // Shim to wrap req.respond while preserving callback-passing API
 
-var mbgl = require('../../lib/node-v' + process.versions.modules + '/mbgl');
+var mbgl = require('./lib/node-v' + process.versions.modules + '/mbgl');
 var constructor = mbgl.Map.prototype.constructor;
 
 var Map = function(options) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@acalcutt/maplibre-gl-native-test",
-  "version": "5.3.0-pre.1",
-  "description": "Renders map tiles with Maplibre GL",
+  "version": "5.4.1-pre.2",
+  "description": "Renders map tiles with MapLibre Native",
   "keywords": [
     "maplibre",
     "gl"
@@ -11,47 +11,50 @@
   },
   "files": [
     "lib",
-    "platform/node/index.d.ts"
+    "index.d.ts"
   ],
-  "main": "platform/node/index.js",
-  "types": "platform/node/index.d.ts",
+  "main": "index.js",
+  "types": "index.d.ts",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/wifidb/maplibre-native.git"
+    "url": "git+https://github.com/WifiDB/maplibre-native.git"
   },
   "license": "BSD-2-Clause",
   "dependencies": {
-    "@acalcutt/node-pre-gyp": "^1.0.14",
-    "@acalcutt/node-pre-gyp-github": "1.4.8",
-    "minimatch": "^7.2.0",
-    "npm-run-all": "^4.0.2"
+    "@acalcutt/node-pre-gyp": "^1.0.15",
+    "@acalcutt/node-pre-gyp-github": "1.4.9",
+    "minimatch": "^9.0.4",
+    "npm-run-all": "^4.1.5"
   },
   "devDependencies": {
+    "@aws-sdk/client-device-farm": "^3.556.0",
+    "@aws-sdk/client-s3": "^3.556.0",
     "@mapbox/flow-remove-types": "^2.0.0",
     "@mapbox/mvt-fixtures": "3.10.0",
-    "@octokit/plugin-retry": "^4.1.2",
-    "@octokit/rest": "^19.0.7",
+    "@octokit/plugin-retry": "^7.1.0",
+    "@octokit/rest": "^20.1.0",
+    "@types/node": "^20.12.7",
     "argparse": "^2.0.1",
-    "aws-sdk": "^2.1318.0",
-    "csscolorparser": "~1.0.2",
+    "csscolorparser": "~1.0.3",
     "d3-queue": "3.0.7",
-    "diff": "5.1.0",
-    "ejs": "^3.1.8",
+    "diff": "5.2.0",
+    "ejs": "^3.1.9",
     "esm": "~3.2.25",
-    "express": "^4.18.2",
+    "express": "^4.19.2",
     "json-stringify-pretty-compact": "^4.0.0",
-    "jsonwebtoken": "^9.0.0",
-    "lodash": "^4.16.4",
+    "jsonwebtoken": "^9.0.2",
+    "lodash": "^4.17.21",
     "lodash.template": "4.5.0",
     "mapbox-gl-styles": "2.0.2",
     "pixelmatch": "^5.3.0",
-    "pngjs": "^6.0.0",
-    "pretty-bytes": "^6.1.0",
+    "pngjs": "^7.0.0",
+    "pretty-bytes": "^6.1.1",
     "request": "^2.88.0",
-    "semver": "^7.3.8",
+    "semver": "^7.6.0",
     "shuffle-seed": "1.1.6",
     "st": "3.0.0",
-    "tape": "^5.6.3",
+    "tape": "^5.7.5",
+    "typescript": "^5.4.5",
     "xcode": "^3.0.1"
   },
   "engines": {
@@ -59,17 +62,17 @@
   },
   "scripts": {
     "install": "node-pre-gyp install --fallback-to-build=false",
-    "test": "tape platform/node/test/js/**/*.test.js",
-    "test-memory": "node --expose-gc platform/node/test/memory.test.js",
-    "test-expressions": "node -r esm platform/node/test/expression.test.js",
-    "test-render": "node -r esm platform/node/test/render.test.js",
-    "test-query": "node -r esm platform/node/test/query.test.js"
+    "test": "tape test/js/**/*.test.js",
+    "test-memory": "node --expose-gc test/memory.test.js",
+    "test-expressions": "node -r esm test/expression.test.js",
+    "test-render": "node -r esm test/render.test.js",
+    "test-query": "node -r esm test/query.test.js"
   },
   "gypfile": true,
   "binary": {
     "module_name": "mbgl",
     "module_path": "./lib/{node_abi}",
-    "host": "https://github.com/wifidb/maplibre-native/releases/download/",
+    "host": "https://github.com/WifiDB/maplibre-native/releases/download/",
     "remote_path": "node-v{version}",
     "package_name": "{node_abi}-{platform}-{arch}-{configuration}.tar.gz"
   }