geostyler / geostyler

Generic Styler for geodata

Code: github Package: npm

Documentation: main / latest / 11.1.1

Examples: Demo application

Developer Guide: Developer Guide

🚀 GeoStyler Code Sprint 2024

We are happy to announce the third GeoStyler Code Sprint from 17.-21.06.2024 in Paris. Be part of it! More infos on https://geostyler.org/.

📆 Monthly meetings

On the first tuesday of every month, there is a video meeting on the GeoStyler Discord at 2pm CET. The meeting is for all contributors, users or other people interested in GeoStyler.

What is this all about?

The GeoStyler is a generic styler for geodata*.

GeoStyler provides a set of UI Components for map styling. Just like a modular building block system all components can be stacked together to create a nice UI for your web applications. To simplify the setup, we also provide some high-level components (based on our building blocks) that already do the work for you. These include among many others Symbolizer Editors, RuleTables and a fully-fledged StyleEditor including filters and scaleDenominators.

Furthermore, GeoStyler allows for the translation between multiple styling formats, i.e. SLD, OpenLayers, QGIS, Mapbox. Since we are following the concept of micro packages, these translators (we call them parsers) can be used as standalone libraries, without the need to include the UI components as a dependency. Just take a look at StyleParser Implementations.

* geodata as a single dataset (layer) not a complete map appearance.

If you are missing any UI components, formats or even have a custom style format, feel free to open a PR. We are happy for any kind of contributions.

To see the GeoStyler in action have a look at the demo application. It demonstrates the GeoStyler UI components as a standalone application.

Every parser works as a standalone library, too. So you can easily translate between style formats.

For example a small SLD to OpenLayers-Style parser (untested code 😄):

import SLDParser from "geostyler-sld-parser";
import OpenLayersParser from "geostyle-openlayers-parser";
const sldParser = new SLDParser();
const olParser = new OpenLayersParser();

const sldToOL = async (sld) => {
  const { output: geostylerStyle } = await sldParser.readStyle(someSld);
  const { output: olStyle } = await olParser.writeStyle(geostylerStyle);
  return olStyle;
};

export default sldToOl;

Installation

Run

npm i geostyler

from within your project directory to add GeoStyler as a dependency. Please be aware of the peerDependencies that come along with GeoStyler.

Components can be used as follows:

import {wanted-geostyler-compoment} from 'geostyler';

//... your component code
render() {
  return (
    <wanted-geostyler-component
      foo=""
      bar={}
    />
  );
}

GeoStyler - Behind the Scenes

Internally we are using our own style definition called GeoStyler Style (see TypeScript Declaration Files), which takes the best from SLD and Mapbox. We are not trying to establish just another standard, but we need an exchange format that is flexible and highly compatible with current styling standards. Understanding GeoStyler Style is only necessary for developers of the project, not for users! Our style parsers all read and write from and to GeoStyler Style to keep the complexity low. As a positive side effect this lets you translate from any supported style to any other supported style.

Imagine your previous project was based on QGIS and now you want to setup your own web application. With GeoStyler you can still use your QGIS styles and either save all future formats in qml as well, or you simply translate all your old styles to another format e.g. OpenLayers styles or SLD. It's simple as that!

To populate the UI with information from imported data we provide a set of data parsers (defined in GeoStyler Data). Currently, we support GeoJSON, Shapefile and WFS.

With these two formats there come two interfaces. You can implement these interfaces to create a parser. Compare the list of existing parsers below.

Related projects

TypeScript Declaration Files

• GeoStyler Data (github / npm)
• GeoStyler Style (github / npm)

DataParser Implementations

• GeoJSON (github / npm)
• Shapefile (github / npm)
• Web Feature Service (WFS) (github / npm)

StyleParser Implementations

• SLD (github / npm)
• OpenLayers Style (github / npm)
• Mapbox Style (github / npm)
• MapServer Mapfiles (github / npm)
• QGIS Style [*.qml] (github / npm)

More

• CQL Filter (github / npm)
• Legend (github / npm)
• CLI (Command Line Interface) (github / npm)

Developer Guide

For our guidelines for contributions, please take a look at CONTRIBUTING.md. Head there if you need general advice for first contributing steps (code or documentation).

More detailed information to ensure a great development experience when working on geostyler is summarized in DEVELOPING.md. You'll find hints with regard to developing UI components or guidance when you want to enhance (or create) parsers for style formats or data formats there.

Additionally, please read through our code of conduct.

We look forward to seeing you contribute soon!

License

GeoStyler is released under the BSD 2-Clause license. Please see the file LICENSE in the root of this repository.

Thanks to all contributors ❤

Funding & financial sponsorship

Maintenance and further development of this code can be funded through the GeoStyler Open Collective. All contributions and expenses can transparently be reviewed by anyone; you see what we use the donated money for. Thank you for any financial support you give the GeoStyler project 💞

geostyler's Issues

KickOff

Target:
JavaScript frontend for reading, editing and writing various styles (sld, ol-stylefunctions, mbstyles, ...).

Basis:

• react
• react-geo
• antd

Structure:

• Internal style representation (mbstyles?)
• Layer/DescribeLayers as input (ol-layer, shp, WFS-DescribeLayer, …?)
• Plugable export interfaces
  • Use existing converters like ol-mapbox-style
• Composable components
• Utilities
  (- Containers for complex and simple styling)
• TypeScript ?

Features:
Simple:

• Point, Line, Polygon
  • StrokeColor, FillColor, StrokeWidth
• Point
  • Radius, Icon, Standard-Symbols (circle, square, …)

Complex:

• Mutliple Rules
  • Boolean combinators (and/or)
• Scale Denominators

Add StyleParser interface to geostyler-style declaration

We need to add a StyleParser interface to the geostyler-style declaration at https://github.com/terrestris/geostyler-style.

Compare https://github.com/terrestris/geostyler-data/blob/master/index.d.ts#L117

Enable canvas for unit tests

Since we plan to introduce OpenLayers, which uses canvas to render its map, the unit test environment should be enabled to work with canvas elements.

A promising package could be jest-canvas-mock or the more basic canvas package.

Implement a Rule GUI

Setup the UserInterface for a Rule.

The final UI for the filter could look like this (somehow):

It consists of three key components:

• a ScaleDenominator
• a Filter
• a Symbolizer

Add name property to StyleParser interface

The StyleParser interface should get a name property aswell. So we can determine what parser we are using in the GeoStyler itself.

Use typedef library for GeoJSON

@KaiVolland and me suggest to use an existing library for the type definition for GeoJSON objects.

Preferred library is https://www.npmjs.com/package/@types/geojson
This lib seems very clean and is widely spread.

This has impact to #7 and should be integrated in #10.

Create geostyler-shapefile-parser

Create the geostyler-shapefile-parser repository under terrestris.

It should contain the concrete implementation of the GeoStyler_DataParser interface targeting Shapefile based geodata.

Integrate OpenLayers with TypeScript

For several components, such as the style preview UI (see #81) and the preview map inside the StyleEditor (see #82) we need the integration of OpenLayers. Since we are using TypeScript we need some kind of TypeScript-binding for OpenLayers. Yet there is no official support for this but here can be found some ideas and infos.

Create geostyler-wfs-parser

Create the geostyler-wfs-parser repository under terrestris.

It should contain the concrete implementation of the GeoStyler_DataParser interface targeting WFS based geodata.

Use GeoStyler OL parser in SymbolizerPreview

At the moment a temporary "proof-of-concept parser" to transform the internal styles to OpenLayers styles is used inside the SymbolizerPreview UI. Once we have an "official" geostyler-ol-parser we should replace the temporary parser with the official one.

Therefore the transformation is encapsulated in the function symbolizer2OlStyle and can be replaced inside this function without any further API-breaks.

UI for combined ComparisonFilter objects

Since the GUI for a ComparisonFilter is nearly done (see #64) one of the next steps would be a GUI that allows the combination of several ComparisonFilter objects. Either with connected AND or OR.

Fix interface inheritance in geostyler-style

Currently this is a correct implementation but it shouldn't be valid:
We have to find a way to restrict mixed properties.

interface Symbolizer {
    visibility?: boolean
}

interface PointSymbolizer extends Symbolizer {
    radius: number
}

interface LineSymbolizer extends Symbolizer {
    lineWidth: number
}

const myRide: PointSymbolizer | LineSymbolizer = {
    visibility: true,
    // Just one of both should be allowed. Not mixed.
    radius: 5,
    lineWidth: 10
}

Remove Models, Types, Interfaces covered by geostyler-style

As we created our own declaration repository for the geostyler-style we need to remove all duplicated/unneeded Models, Types and Interfaces.

Mapping of the rules name property in the SLD-Parser

We need to discuss how we want to map the SLD-Rule-Properties name and title to the name property of the GeoStyler Style Rule.

Correct "main"-Path in SLD-Parser

The "main"-Path declaration in the package.json is not correct at the moment. Either it has to be changed in

"main": "build/dist/src/SldStyleParser.js",

or the build-folder structure has to be changed according to the current setting.

Otherwise the integration of the SLD-Parser as dependency does not work.

Version 10 of node.js has been released

Version 10 of Node.js (code name Dubnium) has been released! 🎊

To see what happens to your code in Node.js 10, Greenkeeper has created a branch with the following changes:

• Added the new Node.js version to your .travis.yml

If you’re interested in upgrading this repo to Node.js 10, you can open a PR with these changes. Please note that this issue is just intended as a friendly reminder and the PR as a possible starting point for getting your code running on Node.js 10.

More information on this issue

Greenkeeper has checked the engines key in any package.json file, the .nvmrc file, and the .travis.yml file, if present.

• engines was only updated if it defined a single version, not a range.
• .nvmrc was updated to Node.js 10
• .travis.yml was only changed if there was a root-level node_js that didn’t already include Node.js 10, such as node or lts/*. In this case, the new version was appended to the list. We didn’t touch job or matrix configurations because these tend to be quite specific and complex, and it’s difficult to infer what the intentions were.

For many simpler .travis.yml configurations, this PR should suffice as-is, but depending on what you’re doing it may require additional work or may not be applicable at all. We’re also aware that you may have good reasons to not update to Node.js 10, which is why this was sent as an issue and not a pull request. Feel free to delete it without comment, I’m a humble robot and won’t feel rejected 🤖

---

FAQ and help

There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.

---

Your Greenkeeper Bot 🌴

ComparisonFilter GUI: Filter operators according to attribute type

The operator combobox inside the ComparisonFilter GUI should be filtered according to the type of the selected attribute. This is necessary since not all operators make sense for every type (string, number, boolean).

Design GeoStyler_Data model and interface

We need to design the GeoStyler_Data (naming is not fixed) model.

It should be able to represent and describe the attributes of a vectordata dataset.

It could somewhat look like:

{
  "attributes": [{
    "name": "firstname",
    "type": "String",
    …
  }, {
    "name": "age",
    "type": "Number",
  }, …],
  "data": [{
    "name": "Peter",
    "age": 12
  }, {
    "name": "Ilse",
    "age": 13
  }, …]
}

Make read and write methods of Data- and StyleParsers async

The read and write methods of Data- and StyleParsers should be asynchornous / return Promises.

This allows us to do asynchronous stuff in the concrete implementations of our parsers. An explicit example would be the (not yet existing) WFS-Dataparser which needs to do a request before it is able to read the data.

Extract GeoStyler Style models as declaration file

To re-use the GeoStyler Style models in different parts of the GeoStyler ecosystem we need to extract them as TypeScript Declaration File.
Once this is done the declaration file can live in an own repository and thus be included in different GeoStyler components (StyleParser, Core, etc.).

Child issue of #8

Create geostyler-sld-parser

Create the geostyler-sld-parser repository under terrestris.

It should contain the concrete implementation of the GeoStyler_StyleParser interface targerting SLD files.

Adds support for GeoStyler Style IconSymbolizers

We need to add support for GeoStyler Style IconSymbolizers.

Add write/read methods for sub-entities to StyleParser Interface

In some cases writing/reading sub-entities of the style might be useful.

So we should introduce the following functions to the StyleParser Interface:

• readRule & writeRule
• readFilter & writeFilter
• readSymbolizer & writeSymbolizer
• readScaleDenominator & writeScaleDenominator

Implement a Symbolizer preview UI

We need to add a a Symbolizer preview UI showing the currently active style for the geometries.

It has to be cleared if this should be done with OpenLayers (which needs a TypeScript binding for OL) or by native TypeScript (with canvas drawing or similar).

The UI should look like this (POINT / LINE / POLYGON):

Enable less or similar for advanced styling

We should integrate a CSS Preprocessor such as less to get advanced styling possibilities.

See: https://github.com/facebook/create-react-app/blob/master/packages/react-scripts/template/README.md#adding-a-css-preprocessor-sass-less-etc

Setup styleguidist

Setup styleguidist to provide the environment for examples and docs.

Design GeoStyler_Style model and interface

We need to design the GeoStyler_Styler (naming is not fixed) model.

It should be able to represent the style of a vectordata dataset.
This includes:

Style:
  Rules:
    Filter (Attributive [spatial?]):
    ScaleDenominator:
    Symbolizer:
      Point|Line|Polygon

Broken import in FilterUtil.spec.ts

In the file src/util/FilterUtil/FilterUtil.spec.ts seems to be a broken import definition for FilterUtil:

import { Filter } from '../../Interface/Filter/Filter';

Changing the import to

import Filter from '../../Interface/Filter/Filter';

seems to solve this.

Name property on GeoStyler-Style Style

I think we should add a name property to the GeoStyler-Style Style like we have it at the Rule.

Implement DataProvider

The GeoStyler needs a DataProvider component, which is supposed to do the following:

• Retrieve and manage a list of available DataParser instances (for different formats)
• Implement a method retrieving external geodata (e.g. GeoJSON), transform it into the internal data structure (by a suitable parser) and return internal data object

@KaiVolland and me agreed on the following structure (pseudo code):

new DataProvider({ 
  parser: [
    {
      format: 'GeoJSON',
      impl: new GeoJsonDataParser({ ... })
    }  
  ] 
});

Implement a geometry style editor

In order to let the user create or edit the geometry style definition we need a StyleEditor component (naming not fixed). This component should offer tools to edit the style (fill-color, outline-color, etc.), to edit label placement and to show a preview map.

The UI could be inspired by:

Refactor getStyleTypeFromSldString to getStyleTypeFromSldObject to use xml2js

geostyler-sld-parser

Adds support for PropertyIsBetween Operator

We need to add support for the PropertyIsBetween Operator.

Publish code over at npm

The code should be published over at npm, also of the utility libraries. I suggest geostyler, right now that name is not taken, take @terrestris/geostyler otherwise.

Publishing should be made a simple npm task, e.g. using np, publish-please, release-it or sth. more elaborated like semantic-release. The latter requires some change in how we name our commits.

Anyhow, this should all live at npm.

Create geostyler-openlayers-parser

Create the geostyler-openlayers-parser repository under terrestris.

It should contain the concrete implementation of the GeoStyler_StyleParser interface targeting OpenLayers styles.

Support for i18n titles

Geoserver supports i18n legends by using a special syntax: http://docs.geoserver.org/stable/en/user/styling/sld/language.html

It would be great to support this in order to create i18n aware styles.

Create the geostyler-ol-vector-parser

Create the geostyler-ol-vector-parser repository under terrestris.

It should contain the concrete implementation of the GeoStyler_DataParser interface targeting geodata of an ol.layer.Vector.

Style UI

We need to create a Style UI.

Extract GeoStyler Data models as declaration file

To re-use the GeoStyler Data models in different parts of the GeoStyler ecosystem we need to extract them as TypeScript Declaration File.
Once this is done the declaration file can live in an own repository and thus be included in different GeoStyler components (DataParser, Core, etc.).

Child issue of #7

Add TypeScript declaration for SLD object created by xml2js

We should add a declaration for the JS objects generated by xml2js when reading an SLD.

Improve tests for SLD Parser

Currently the SLD Parser contains many dummy tests.
These should be filled/replaced with real tests.

[SLD-Parser] Support multiple Symbolizers per Rule

Currently the SLD parser only supports one symbolizer per rule. As it is a key feature of SLD to stack symbolizer we should support this too.

Rework DataProvider to use returned Promise

Due to the interface definition change of the readData function we have to adapt the DataProvider to use the returned Promise object to access the data (instead of accessing it directly).

Related to #40.

Implement writeStyle for the SLD Parser

We need to implement the writeStyle method of the SLD Parser.

ComparisonFilter GUI: Add Validator

The ComparisonFilter GUI (or its child components) needs a validator, so the user gets a visual feedback if not all properties (attribute | operator | value) are set.

Setup CI for related repositories

We need to setup CI for these subprojects:

• https://github.com/terrestris/geostyler-style
• https://github.com/terrestris/geostyler-data
• https://github.com/terrestris/geostyler-geojson-parser

Comparison Filter GUI

Setup the UserInterface for ComparisonFilters.

The final UI for the filter should look something like this:

It consists of three key components:

1. An "AttributeCombo" which reads the available attributes from the DataParser
2. An "OpertatorCombo" to select one of the Opertors allowed by the Style-ComparisonFilter.
3. A "ValueField" which is related to the datatype of the selected attribute.

---

❗ Please keep in mind that we will have NegationFilter and CombinationFilter later on. So the filters might be nested.

Component naming and visualization is not fixed. Just choose the best matching UI-Component from Ant Design components.

Make 'npm start' work

Right now npm start leads to

Failed to compile.

/home/jansen/eclipse-ws/geostyler/src/Model/Rule/Rule.spec.ts
(4,10): Module '"/home/jansen/eclipse-ws/geostyler/src/Interface/Filter/Filter"' has no exported member 'Filter'.

This should do sth. different

Add name property to DataParser interface

The DataParser interface should get a name property aswell. So we can determine what parser we are using in the GeoStyler itself.

Include new "name" property of stlye-rule to SLD parser

We need to include the "name" property of Rule to the SLD parser.

It is a required property so this needs to be fixed when upgrading to geostyler-style v0.2.1.