Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/gagan-bansal/geojson2svg

Converts GeoJSON to SVG string given SVG view port size and maps extent.
https://github.com/gagan-bansal/geojson2svg

geojson javascript map maps svg

Last synced: about 6 hours ago
JSON representation

Converts GeoJSON to SVG string given SVG view port size and maps extent.

Awesome Lists containing this project

README

        

# geojson2svg
Converts GeoJSON to an SVG string, given the SVG viewport size and map extent. geojson2svg can be used on the client side (in the browser) or server side (with Node.js).

Check [world map](https://rawgit.com/gagan-bansal/geojson2svg/master/examples/world.html), [SVG scaled map](https://rawgit.com/gagan-bansal/geojson2svg/master/examples/world-scaled.html) and [color coded map](https://rawgit.com/gagan-bansal/geojson2svg/master/examples/world-pop.html) examples to demonstrate that its very easy to convert GeoJSON into map.

🛠 [Installation](#-installation)
:car: [Usage](#car-usage)
:popcorn: [Basic Example](#popcorn-basic-example)
🔌 [API](#-api)
✈️ [Migration from 1.x to 2.x](#-migration-from-1x-to-2x)
📌 [Important points](#-important-points)
📋 [Changelog](#-changelog)
🪪 [License](#-license)
🔗 [Related useful articles](#-related-useful-articles)

## 🛠 Installation
* Using in node.js
```
npm install geojson2svg
```
* For including in html page, download the build file [./dist/geojson2svg.min.js](https://raw.githubusercontent.com/gagan-bansal/geojson2svg/master/dist/geojson2svg.min.js)
```html

```
This creates a global variable 'GeoJSON2SVG' as a Class.

* geojson2svg is also available on [cdnjs](https://cdnjs.com/libraries/geojson2svg) and can be included like:
```html

```

## :car: Usage
* Using with node.js

With ES6
```javascript
import {GeoJSON2SVG} from 'geojson2svg';
const converter = new GeoJSON2SVG(options);
const svgStrings = converter.convert(geojson, options);
```

With CommonJS
```javascript
const {GeoJSON2SVG} = require('geojson2svg');
const converter = new GeoJSON2SVG(options);
const svgStrings = converter.convert(geojson, options);
```
* Usage in browser:
```
const converter = new GeoJSON2SVG(options);
const svgStrings = converter.convert(geojson,options);
```

## :popcorn: Basic Example
```javascript
const {GeoJSON2SVG} = require('geojson2svg');

const converter = new GeoJSON2SVG({
mapExtent: {left: -180, bottom: -90, right: 180, top: 90},
viewportSize: {width: 200, height: 100},
attributes: ['properties.class' , 'properties.foo'],
r: 2
});
const geojsonData = {
type: 'FeatureCollection',
features: [{
type: 'Feature',
id: 'pt-1',
geometry: {type:'Point',coordinates:[50, 50]},
properties: {foo: 'val-1', class: 'point-tree'}
}, {
type: 'Feature',
geometry: {
type: 'LineString',
coordinates: [[10, 10],[15, 20],[30, 10]]
},
properties: {id: 'ln-1', foo: 'val-2', class: 'line-road', bar: 'val'}
}, {
type: 'Feature',
id: 'pg-1',
geometry: {
type: 'LineString',
coordinates: [[30, 10], [40, 40], [20, 40], [10, 20], [30, 10]]
},
properties: {id: 'not-used', foo: 'val-3', class: 'polygon-pond'}
}]
});

const svgStr = converter.convert(geojsonData);
console.log(svgStr);

// output
// [
// '',
// '',
// ''
// ]
```
**convert** function returns an array of SVG elements' strings.

## ✈️ Migration from 1.x to 2.x

* Default export as a function is removed. Now `geojson2svg` exports class `GeoJSON2SVG`.

With 1.x
```javascript
const geojson2svg = require('geojson2svg');
const converter = geojson2svg(options);
```

Now with 2.x

```javascript
// With ES6
import {GeoJSON2SVG} from 'geojson2svg';
const converter = new GeoJSON2SVG(options);
const svgStrings = converter.convert(geojson, options);

// With CommonJS
const {GeoJSON2SVG} = require('geojson2svg');
const converter = new GeoJSON2SVG(options);
```

* Default value of `mapExtent` in 1.x was Web Mercator projection's full extent. In 2.x if `mapExtent` is not provided the `mapExtentFromGeoJSON` is considered to be true, that means the extent of the input data is considered as `mapExtent`.

* There is only one case (from 1.x to 2.x) for which your existing code would fail, the input GeoJSON data projection system is Web Mercator and you have not specified `mapExtent`. So to work with 2.x just pass the `mapExtent` as [Web Mercator extent](https://gis.stackexchange.com/a/280022/12962)

## 🔌 API

### Initializing the instance

```javascript
const converter = new GeoJSON2SVG(options);
```

Here are all options available for initializing the instance.

* **viewportSize** is object containing width and height in pixels. Default viewportSize value is: `{width: 256, height: 256}`
* **mapExtent:** {"left": coordinate, "bottom": coordinate, "right": coordinate, "top": coordinate}. Coordinates should be in same projection as of GeoJSON data. **NOTE: If `mapExtent` is not defined, the parameter `mapExtentFromGeojson` is considered `true`.**

* **mapExtentFromGeojson:** boolean, if true `mapExtent` is calculated from GeoJSON data that is passed in `.convert` function.

* **fitTo:** 'width' | 'height' Fit output SVG map to width or height. If nothing is provided, the program tries to fit the data within width or height so that full mapExtent is visible in viewport.
* **coordinateConverter:** 'function' to convert input GeoJSON coordinates while converting to SVG. This function should take coordinates of a point `[x,y]` and returns transformed point `[x, y]`.
* **pointAsCircle:** true | false, default is false. For point GeoJSON return circle element for option:
``` { "pointAsCircel": true } ```
output SVG string would be:

```''```
* **r:** radius of point SVG element

* **attributes:** Attributes which are required to attach as SVG attributes from features can be passed here as list of path in feature or json object for static attributes, like shown here

**dynamic** ``` {"attributes": ["properties.foo", "properties.bar"]}```

output: ``` [] ```

or **static** ``` {"attributes": {"class": "mapstyle"}}```

outut: ```''```

or **dynamic** and **static** both

{attributes: [
{
property: 'properties.foo',
type: 'dynamic',
key: 'id'
}, {
property: 'properties.baz',
type: 'dynamic'
}, {
property: 'bar',
value: 'barStatic',
type: 'static'
}]
})

output: ``` [ ''] ```

**Note**: If a feature does not have value at the mentioned path then the attribute key would not be attached to SVG string and no error would be thrown.

* **explode:** true | false, default is false. Should multigeojson be exploded to many SVG elements or not.

* **precision** number, precision of output SVG coordinates. Default is false.
* **output:** 'svg'|'path' default is 'svg'

'svg' - SVG element string is returned like ```''```

'path' - path 'd' value is returned ```'M0,0 20,10 106,40'``` a linestring

* **callback:** function, accept function that will be called on every GeoJSON conversion with output string as one input variable e.g:
```
{ "callback": function(svgString) {
// do something with svgString
}}
```

Callback function could be used to render SVG string.

### Instance method

`.convert(geojson, options)`

The options **'attributes'**, **'r'** and **'callback'** can also be given in **convert** function's option. Example:

```javascript
let svgStrings = convertor.convert(geojson,
{
"attributes": ...,
"r": ...,
"callback": function
}
);
```

## 📌 Important points

* **mapExtent** is critical option. Usually your data would would be in [WGS84](https://en.wikipedia.org/wiki/World_Geodetic_System) (World Geodetic System) and unit as degree decimal for latitudes and longitude. Spatial reference system code for this is "EPSG:4326". To show the geographic data on two dimensional plane (paper or HTML page) the coordinates need to be projected. The usual choice is Web Mercator projection ('EPSG:3857') also known as Spherical Mercator. Web Mercator projection is used by many web mapping sites (OpenStreetMap, Google, Bing, and others). Geographic coordinates can be converted to Web Mercator Projection using [reproject-spherical-mercator](https://github.com/geosquare/reproject-spherical-mercator) or [reproject](https://github.com/perliedman/reproject) or [proj4js](https://github.com/proj4js/proj4js). Check [world map](https://github.com/gagan-bansal/geojson2svg/blob/master/examples/js/world.js) example for detail.

* **Assigning id to SVG path,** there are two ways to achieve this. The first is default, the converter reads it from GeoJSON data attributes `feature.properties.id` or `feature.id`. Another way is explicitly specify the `id` attributes in `.convert` method, pass id along with attributes like `converter.convert(feature, {attributes: {id:'foo-1', class: 'bar'}})`. Preference order is: first as `id` key in attributes then `feature.id` and last `feature.properties.id`.

* **Converting SVG string to HTML DOM element**, the SVG strings returned by `convert` method can be easily converted to HTML SVG elements. Intentionally I have kept the geojson2svg's output as string to make it more modular. Here is simple way to convert SVG strings to SVG elements with [parse-svg](https://github.com/gagan-bansal/parse-svg) or with any other parser. Read more about SVG string conversion to DOM Element [here](https://stackoverflow.com/a/3642265/713573) or [here](https://stackoverflow.com/a/24109000/713573). The usage of 'parse-svg' is as follows:

```shell
npm install parse-svg
```
or include in your html file
```html

```
Simple way to convert svgStrings to SVG elements

```javascript
var parseSVG = require('parse-svg');
var svgElements = svgStrings.map(parseSVG);
```

## 📋 Changelog
Check [here](https://github.com/gagan-bansal/geojson2svg/blob/master/CHANGELOG.md)

## 🪪 License

This project is licensed under the terms of the [MIT license](https://github.com/gagan-bansal/geojson2svg/blob/master/LICENSE).

## 🔗 Related useful articles

* [CSS-TRICKS: SVG Properties and CSS](https://css-tricks.com/svg-properties-and-css/)
* [MDN SVG Tutorial: SVG and CSS](https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/SVG_and_CSS)
* [JENKOV SVG Tutorial: SVG and CSS - Cascading Style Sheets](https://jenkov.com/tutorials/svg/svg-and-css.html#css-attributes)
* Check my blog [maps-on-blackboard](http://maps-on-blackboard.github.io/tag/geojson2svg/) for more detailed examples using `geojson2svg`.