1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
# node-mapbox-gl-native
[](https://npmjs.org/package/mapbox-gl-native)
## Installing
Requires a modern C++ runtime that supports C++14.
By default, installs binaries. On these platforms no additional dependencies are needed.
- 64 bit OS X or 64 bit Linux
- Node.js v0.10.x, Node.js v0.12.x, io.js v2.x
Just run:
```
npm install mapbox-gl-native
```
Other platforms will fall back to a source compile with `make node`. To compile this module, make sure all submodules are initialized with `git submodule update --init` and install the [external dependencies required to build from source](https://github.com/mapbox/mapbox-gl-native/blob/master/INSTALL.md#depends).
## Rendering a map tile
```js
var map = new mbgl.Map({ request: function() {} });
map.load(require('./test/fixtures/style.json'));
map.render({}, function(err, image) {
if (err) throw err;
fs.writeFileSync('image.png', image);
});
```
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: [{latitude}, {longitude}], // array of numbers (coordinates), defaults to [0,0]
bearing: {bearing}, // number (in degrees, counter-clockwise from north), defaults to 0
classes: {classes} // array of strings
}
```
When you are finished using a map object, you can call `map.release()` to dispose the internal map resources manually. This is not necessary, but can be helpful to optimize resource usage (memory, file sockets) on a more granualar level than v8's garbage collector.
## Testing
```
npm test
```
## Implementing a file source
When creating a `Map`, you must pass an options object (with a required `ratio`, required `request` and optional `cancel` method) as the first parameter.
```js
var map = new mbgl.Map({
request: function(req) {
// TODO
},
cancel: function(req) {
// TODO
},
ratio: 1.0
});
```
The `request()` method starts a new request to a file, while `cancel()` tells the FileSource to cancel the request (if possible). 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:
```json
{
"url": "http://example.com",
"kind": 1
}
```
The `kind` is an enum and defined in [`mbgl.Resource`](https://github.com/mapbox/mapbox-gl-native/blob/node/include/mbgl/storage/resource.hpp):
```json
{
"Unknown": 0,
"Style": 1,
"Source": 2,
"Tile": 3,
"Glyphs": 4,
"SpriteImage": 5,
"SpriteJSON": 6
}
```
It 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.
A sample implementation that reads files from disk would look like the following:
```js
var map = new mbgl.Map({
request: function(req) {
fs.readFile(path.join('base/path', req.url), function(err, data) {
req.respond(err, { data: data });
});
},
ratio: 1.0
});
```
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 `req.respond()`, which takes either an error object or `null` and an object with several settings:
```js
{
modified: new Date(),
expires: new Date(),
etag: "string",
data: new Buffer()
};
```
A sample implementation that uses [`request`](https://github.com/request/request) to query data from HTTP:
```js
var mbgl = require('mapbox-gl-native');
var request = require('request');
var map = new mbgl.Map({
request: function(req) {
request({
url: req.url,
encoding: null,
gzip: true
}, function (err, res, body) {
if (err) {
req.respond(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;
req.respond(null, response);
} else {
req.respond(new Error(JSON.parse(body).message));
}
});
},
ratio: 1.0
});
```
Mapbox GL uses two types of protocols: `asset://` for files that should be loaded from some local static system, and `http://` (and `https://`), which should be loaded from the internet. However, stylesheets are free to use other protocols too, if your implementation of `request` supports these; e.g. you could use `s3://` to indicate that files are supposed to be loaded from S3.
## Mapbox API Access tokens
To use styles that rely on Mapbox vector tiles, you must pass an [API access token](https://www.mapbox.com/developers/api/#access-tokens) in your `request` implementation with requests to `mapbox://` protocols.
```js
var mbgl = require('mapbox-gl-native');
var request = require('request');
var url = require('url');
var map = new mbgl.Map({
request: function(req) {
var opts = {
url: req.url,
encoding: null,
gzip: true
};
if (url.parse(req.url).protocol === 'mapbox:') {
opts.qs = { access_token: process.env.MAPBOX_ACCESS_TOKEN};
}
request(opts, function (err, res, body) {
if (err) {
req.respond(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;
req.respond(null, response);
} else {
req.respond(new Error(JSON.parse(body).message));
}
});
},
ratio: 1.0
});
// includes a datasource with a reference to something like `mapbox://mapbox.mapbox-streets-v6`
var style = mapboxStyle;
map.load(style);
map.render({}, function(err, image) {
if (err) throw err;
fs.writeFileSync('image.png', image);
});
```
|
