Skip to content

Commit dfa4e31

Browse files
jperellijperelli
committed
Improve readme
1 parent fc981a6 commit dfa4e31

File tree

1 file changed

+60
-55
lines changed

1 file changed

+60
-55
lines changed

‎README.md‎

Lines changed: 60 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,85 +1,90 @@
11
# osm-static-maps
22

3-
This pretends to be inspired in Google(c) static map service. But made using open source technologies.
3+
Open source clone of Google static map service.
44

5-
Here you have a [demo](http://osm-static-maps.herokuapp.com/?geojson=[{"type":"Feature","properties":{"party":"Republican"},"geometry":{"type":"Polygon","coordinates":[[[-104.05,48.99],[-97.22,48.98],[-96.58,45.94],[-104.03,45.94],[-104.05,48.99]]]}},{"type":"Feature","properties":{"party":"Democrat"},"geometry":{"type":"Polygon","coordinates":[[[-109.05,41.00],[-102.06,40.99],[-102.03,36.99],[-109.04,36.99],[-109.05,41.00]]]}}]&height=300&width=300 "Just what I wanted!")
6-
7-
And a [dynamic version](http://osm-static-maps.herokuapp.com/dynamic?geojson=[{"type":"Feature","properties":{"party":"Republican"},"geometry":{"type":"Polygon","coordinates":[[[-104.05,48.99],[-97.22,48.98],[-96.58,45.94],[-104.03,45.94],[-104.05,48.99]]]}},{"type":"Feature","properties":{"party":"Democrat"},"geometry":{"type":"Polygon","coordinates":[[[-109.05,41.00],[-102.06,40.99],[-102.03,36.99],[-109.04,36.99],[-109.05,41.00]]]}}]&height=300&width=300 "Wow it gets even better!!") of the demo, for testing purposes.
5+
Here you have a [demo](http://osm-static-maps.herokuapp.com/?geojson=[{"type":"Feature","properties":{"party":"Republican"},"geometry":{"type":"Polygon","coordinates":[[[-104.05,48.99],[-97.22,48.98],[-96.58,45.94],[-104.03,45.94],[-104.05,48.99]]]}},{"type":"Feature","properties":{"party":"Democrat"},"geometry":{"type":"Polygon","coordinates":[[[-109.05,41.00],[-102.06,40.99],[-102.03,36.99],[-109.04,36.99],[-109.05,41.00]]]}}]&height=300&width=300 "Just what I wanted!"). Also a [dynamic version](http://osm-static-maps.herokuapp.com/dynamic?geojson=[{"type":"Feature","properties":{"party":"Republican"},"geometry":{"type":"Polygon","coordinates":[[[-104.05,48.99],[-97.22,48.98],[-96.58,45.94],[-104.03,45.94],[-104.05,48.99]]]}},{"type":"Feature","properties":{"party":"Democrat"},"geometry":{"type":"Polygon","coordinates":[[[-109.05,41.00],[-102.06,40.99],[-102.03,36.99],[-109.04,36.99],[-109.05,41.00]]]}}]&height=300&width=300 "Wow it gets even better!!") of the demo, for testing purposes.
86

97
(heroku demo might be unstable because of too many requests being made to it, a real server costs money and we are not collecting any for this project yet)
108

11-
As a first approach, the service can render a geoJSON in a map, returning a PNG and you can determine also an optional height and width in pixels.
12-
13-
Parameters that can be used (can be passed to the app server as GET query params, or POST json body (remember to set the header `Content-Type: application/json`))
14-
15-
| Parameter | Description | Default Value |
16-
| ---- | ---- | ---- |
17-
| geojson | geojson object to be rendered in the map | `undefined` |
18-
| height | height in pixels of the returned img | `600` |
19-
| width | height in pixels of the returned img | `800` |
20-
| center | center of the map lon,lat floats string | (center of the geojson) or `'-57.9524339,-34.921779'` |
21-
| zoom | zoomlevel of the leaflet map | if `vectorserverUrl` available, use `12` else `20` |
22-
| maxZoom | max zoomlevel of the leaflet map | `17` |
23-
| attribution | attribution legend | `'osm-static-maps / © OpenStreetMap contributors'` |
24-
| tileserverUrl | url of a tileserver | `'http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png'` |
25-
| vectorserverUrl | url of a vector tile server (MVT style.json) | `undefined` |
26-
| vectorserverToken | token of the vector tile server (MVT) | `'no-token'` |
27-
| renderToHtml | returns html of the webpage containing the map (instead of a binary image) | `false` |
28-
| type | format of the image returned (`'jpeg'`/`'png'`) | `'png'` |
29-
| quality | quality of the image returned (`0`-`100`, only for `jpg`) | `100` |
30-
| imagemin | enable lossless compression with [optipng](https://github.com/imagemin/imagemin-optipng) / [jpegtran](https://github.com/imagemin/imagemin-jpegtran) | `false` |
31-
| oxipng | enable losslsess compression with [oxipng](https://github.com/shssoichiro/oxipng) | `false` |
32-
| arrows | render arrows to show the direction of linestrings | `false` |
33-
| scale | enable render a scale ruler (boolean or [a json options object](https://leafletjs.com/reference-1.6.0.html#control-scale-option)) | `false` |
34-
| markerIconOptions | set marker icon options ([a json options object](https://leafletjs.com/reference-1.6.0.html#icon-option)) *see note | `undefined` (leaflet's default marker) |
35-
36-
* Note on markerIconOptions: it's also accepted a markerIconOptions attribute in the geojson feature, for example `{"type":"Point","coordinates":[-105.01621,39.57422],"markerIconOptions":{"iconUrl":"https://leafletjs.com/examples/custom-icons/leaf-red.png"}}`
37-
389
## How to use
3910

40-
1. This library is published in npm you can use it as an npm module
11+
### 1. CLI
4112

42-
```bash
43-
npm install osm-static-maps
44-
```
13+
```bash
14+
sudo npm i -g osm-static-maps
15+
osmsm --help
16+
osmsm -g '{"type":"Point","coordinates":[-105.01621,39.57422]}' > map.png
17+
```
4518

46-
```javascript
47-
// index.js old school
48-
osmsm = require('osm-static-maps');
49-
osmsm({geojson: geojson})
50-
.then(function(imageBinaryBuffer) { ... })
51-
.catch(function(error) { ... })
19+
### 2. nodejs library
5220

53-
// index.js modern style (also supports typescript)
54-
import osmsm from 'osm-static-maps'
55-
const imageBinaryBuffer = await osmsm({geojson})
56-
```
21+
```bash
22+
npm install osm-static-maps
23+
```
5724

58-
2. alternatively you can download the code, run the sample server and use it standalone (see How to run)
25+
```javascript
26+
// index.js old school
27+
osmsm = require('osm-static-maps');
28+
osmsm({geojson: geojson})
29+
.then(function(imageBinaryBuffer) { ... })
30+
.catch(function(error) { ... })
5931

60-
3. lastly you can use the heroku-hosted alternative directly [here](http://osm-static-maps.herokuapp.com/ "Awesome!")
32+
// index.js modern style (also supports typescript)
33+
import osmsm from 'osm-static-maps'
34+
const imageBinaryBuffer = await osmsm({geojson})
35+
```
6136

62-
## How to run
37+
### 3. Standalone sample server
6338

64-
nodejs is a prerequisite, please install it before this from here https://nodejs.org/
6539
```
6640
git clone git@github.com:jperelli/osm-static-maps.git
6741
cd osm-static-maps
6842
npm install
6943
npm start
7044
```
7145

72-
To develop with autoreload you can run directly if you have the required node version installed on the system
73-
74-
```
75-
npm install && npm run dev
76-
```
77-
7846
Or you can use docker-compose
7947
```
8048
docker-compose up
8149
```
8250

51+
### 4. Cloud service
52+
53+
You can use the heroku-hosted alternative directly [here](http://osm-static-maps.herokuapp.com/ "Awesome!")
54+
55+
heroku server might be unstable because of too many requests being made to it, a real server costs money and we are not collecting any for this project yet.
56+
57+
## API Reference
58+
59+
All parameters have a short and long version. The short version can be used only with the shell CLI. The long version can be used with the library and can be passed to the app server as GET query params, or POST json body (remember to set the header `Content-Type: application/json`)
60+
61+
| | Parameter | Description | Default Value |
62+
| - | ---- | ---- | ---- |
63+
| g | geojson | geojson object to be rendered in the map | `undefined` |
64+
| H | height | height in pixels of the returned img | `600` |
65+
| W | width | height in pixels of the returned img | `800` |
66+
| c | center | center of the map lon,lat floats string | (center of the geojson) or `'-57.9524339,-34.921779'` |
67+
| z | zoom | zoomlevel of the leaflet map | if `vectorserverUrl` available, use `12` else `20` |
68+
| Z | maxZoom | max zoomlevel of the leaflet map | `17` |
69+
| A | attribution | attribution legend | `'osm-static-maps / © OpenStreetMap contributors'` |
70+
| t | tileserverUrl | url of a tileserver | `'http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png'` |
71+
| m | vectorserverUrl | url of a vector tile server (MVT style.json) | `undefined` |
72+
| M | vectorserverToken | token of the vector tile server (MVT) | `'no-token'` |
73+
| D | renderToHtml | returns html of the webpage containing the map (instead of a binary image) | `false` |
74+
| F | type | format of the image returned (`'jpeg'`/`'png'`) | `'png'` |
75+
| q | quality | quality of the image returned (`0`-`100`, only for `jpg`) | `100` |
76+
| x | imagemin | enable lossless compression with [optipng](https://github.com/imagemin/imagemin-optipng) / [jpegtran](https://github.com/imagemin/imagemin-jpegtran) | `false` |
77+
| X | oxipng | enable losslsess compression with [oxipng](https://github.com/shssoichiro/oxipng) | `false` |
78+
| a | arrows | render arrows to show the direction of linestrings | `false` |
79+
| s | scale | enable render a scale ruler (boolean or [a json options object](https://leafletjs.com/reference-1.6.0.html#control-scale-option)) | `false` |
80+
| k | markerIconOptions | set marker icon options ([a json options object](https://leafletjs.com/reference-1.6.0.html#icon-option)) *see note | `undefined` (leaflet's default marker) |
81+
82+
* Note on markerIconOptions: it's also accepted a markerIconOptions attribute in the geojson feature, for example `{"type":"Point","coordinates":[-105.01621,39.57422],"markerIconOptions":{"iconUrl":"https://leafletjs.com/examples/custom-icons/leaf-red.png"}}`
83+
84+
## LICENSE
85+
86+
- GPLv2
87+
8388
## Credits
8489

8590
Specially to the contributors of

0 commit comments

Comments
 (0)