diff options
| author | Jérémy Lal <kapouer@melix.org> | 2016-11-12 10:35:09 +0100 |
|---|---|---|
| committer | Jérémy Lal <kapouer@melix.org> | 2016-11-12 10:35:09 +0100 |
| commit | 0de5417925439f165903b8dfcd41a722b1a5ae50 (patch) | |
| tree | 79c5b46342c9c5ece1ef21958892eb4febfb6ad6 | |
| parent | bb9dcd725654a7f2ba898e3e1d93ddfc256bee2d (diff) | |
New upstream version 0.16.3
227 files changed, 33174 insertions, 964 deletions
diff --git a/.eslintrc.yml b/.eslintrc.yml new file mode 100644 index 0000000..cd269dc --- /dev/null +++ b/.eslintrc.yml @@ -0,0 +1,191 @@ +parserOptions: + ecmaVersion: 5 + sourceType: module +env: + browser: true + node: true + mocha: true +extends: 'eslint:recommended' +rules: + accessor-pairs: 2 + array-bracket-spacing: 0 + array-callback-return: 2 + arrow-body-style: 2 + arrow-parens: 2 + arrow-spacing: 2 + block-scoped-var: 0 + block-spacing: + - 2 + - always + brace-style: 0 + callback-return: 2 + camelcase: 0 + comma-spacing: 0 + comma-style: + - 2 + - last + complexity: 0 + computed-property-spacing: 0 + consistent-return: 0 + consistent-this: 2 + curly: 0 + default-case: 0 + dot-location: + - 2 + - property + dot-notation: 0 + eol-last: 2 + eqeqeq: 0 + func-names: 0 + func-style: 0 + generator-star-spacing: 2 + global-require: 0 + guard-for-in: 0 + handle-callback-err: 2 + id-blacklist: 2 + id-length: 0 + id-match: 2 + indent: 0 + init-declarations: 0 + jsx-quotes: 2 + key-spacing: 0 + keyword-spacing: + - 2 + - after: true + before: true + linebreak-style: + - 2 + - unix + lines-around-comment: 2 + max-depth: 0 + max-len: 0 + max-nested-callbacks: 2 + max-params: 0 + new-parens: 2 + newline-after-var: 0 + newline-per-chained-call: 0 + no-alert: 2 + no-array-constructor: 2 + no-bitwise: 0 + no-caller: 2 + no-confusing-arrow: 2 + no-console: 0 + no-continue: 0 + no-div-regex: 2 + no-else-return: 0 + no-empty-function: 0 + no-eq-null: 2 + no-eval: 2 + no-extend-native: 2 + no-extra-bind: 2 + no-extra-label: 2 + no-extra-parens: 0 + no-floating-decimal: 2 + no-implicit-globals: 0 + no-implied-eval: 2 + no-inline-comments: 0 + no-inner-declarations: + - 2 + - functions + no-invalid-this: 2 + no-iterator: 2 + no-label-var: 2 + no-labels: 2 + no-lone-blocks: 2 + no-lonely-if: 0 + no-loop-func: 0 + no-magic-numbers: 0 + no-mixed-requires: 0 + no-multi-spaces: 0 + no-multi-str: 2 + no-multiple-empty-lines: + - 2 + - max: 3 + no-native-reassign: 2 + no-negated-condition: 0 + no-nested-ternary: 0 + no-new: 2 + no-new-func: 2 + no-new-object: 2 + no-new-require: 2 + no-new-wrappers: 2 + no-octal-escape: 0 + no-param-reassign: 0 + no-path-concat: 2 + no-plusplus: 0 + no-process-env: 2 + no-process-exit: 2 + no-proto: 2 + no-restricted-imports: 2 + no-restricted-modules: 2 + no-restricted-syntax: 2 + no-return-assign: 0 + no-script-url: 2 + no-self-compare: 2 + no-sequences: 0 + no-shadow: 0 + no-shadow-restricted-names: 2 + no-spaced-func: 0 + no-sync: 0 + no-ternary: 0 + no-throw-literal: 2 + no-trailing-spaces: 2 + no-undef-init: 2 + no-undefined: 0 + no-underscore-dangle: 0 + no-unmodified-loop-condition: 0 + no-unneeded-ternary: + - 2 + - defaultAssignment: true + no-unused-expressions: 0 + no-use-before-define: 0 + no-useless-call: 2 + no-useless-concat: 2 + no-useless-constructor: 2 + no-var: 0 + no-void: 2 + no-warning-comments: 0 + no-whitespace-before-property: 2 + no-with: 2 + object-curly-spacing: 0 + object-shorthand: 0 + one-var: 0 + one-var-declaration-per-line: 0 + operator-assignment: 0 + operator-linebreak: 0 + padded-blocks: 0 + prefer-arrow-callback: 0 + prefer-const: 2 + prefer-reflect: 0 + prefer-rest-params: 0 + prefer-spread: 0 + prefer-template: 0 + quote-props: 0 + quotes: 0 + radix: + - 2 + - always + require-jsdoc: 0 + require-yield: 2 + semi: 0 + semi-spacing: + - 2 + - after: true + before: false + sort-imports: 2 + sort-vars: 0 + space-before-blocks: 0 + space-before-function-paren: 0 + space-in-parens: 0 + space-infix-ops: 0 + space-unary-ops: 0 + spaced-comment: 0 + strict: + - 2 + - never + template-curly-spacing: 2 + valid-jsdoc: 0 + vars-on-top: 0 + wrap-regex: 0 + yield-star-spacing: 2 + yoda: 0 @@ -1,5 +1,5 @@ -/node_modules +**/node_modules .DS_Store test/rendering/layers/ test/rendering/cache/ -test/rendering-mss/npm-debug.log
\ No newline at end of file +test/rendering-mss/npm-debug.log diff --git a/.travis.yml b/.travis.yml index 242c6f2..11e2c4b 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,7 +1,13 @@ language: node_js +sudo: true + node_js: - - "0.11" - - "0.10" - - "0.8" - - "0.6" + - "5" + - "4" + - "0.12" + - "0.10.44" + +script: + - npm test + - if [[ ${TRAVIS_NODE_VERSION} == "0.10.44" ]]; then npm run coverage; fi; diff --git a/CHANGELOG.md b/CHANGELOG.md index 1d79991..ab3e8fc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,85 @@ ## Changelog +## 0.16.3 + +* Fixed outdated library reference for carto help screen ([#444](https://github.com/mapbox/carto/pull/443)) +* Fixed a regression related to color math with non-color values being interpreted as HSL instead of RGB ([#446](https://github.com/mapbox/carto/issues/446)) + +## 0.16.2 + +* Fixed a regression related to color math ([#443](https://github.com/mapbox/carto/issues/443)) + +## 0.16.1 + +* Fixed a regression related to the color mix function ([#442](https://github.com/mapbox/carto/issues/442)) + +## 0.16.0 + +* Fixed a bug related to parsing numerical selectors ([#393](https://github.com/mapbox/carto/pull/393)) +* More meaningful error messages on erroneous Stylesheet references in MML ([#438](https://github.com/mapbox/carto/pull/438)) +* Added support for YAML MML files ([#419](https://github.com/mapbox/carto/pull/419)) +* Added support for [HuSL](http://www.husl-colors.org) perceptual colors ([#422](https://github.com/mapbox/carto/pull/422)) +* Added support for targeting Mapnik API versions in `carto` command line tool ([#433](https://github.com/mapbox/carto/pull/433)) +* Added support for `minimum-/maximum-scale-denominator` ([#394](https://github.com/mapbox/carto/issues/394)) +* Updated documentation, fixed its display problems and added doc for `image-filter` ([#432](https://github.com/mapbox/carto/pull/432)) +* Moved from `underscore` to `lodash` dependency ([#431](https://github.com/mapbox/carto/pull/431)) +* Moved from `optimist` to `yargs` dependency ([#435](https://github.com/mapbox/carto/pull/435)) +* Bump `mapnik-reference` dependency to 8.5.3 (support for Mapnik 3.0.10) +* Modernized development dependencies +* Further small fixes and improvements for development. + +## 0.15.3 + +* Support for Mapnik 3.0.6 + +## 0.15.2 + +* Support for Mapnik 3.0.5 + +## 0.15.1 + +* Support for Mapnik 3.0.4 + +## 0.15.0 + +* Support for Mapnik 3.0.3 + +## 0.14.1 + +* Support latest Mapnik 3.x +* Bump `mapnik-reference` dependency to 7.x. + +## 0.14.0 + +* Support for Mapnik 3.x +* Bump `mapnik-reference` dependency to ~6.0.1. + +## 0.13.0 + +* Allows optional args in transforms. +* Bump `mapnik-reference` dependency to 5.1.x. + +## 0.12.0 + +* Drop mml2json and xml2js dependency. + +## 0.11.0 + +* Switch API to be synchronous. All errors should be caught using try/catch now. + +## 0.10.0 + +* Remove automatic inclusion of `maximum-extent` on Map element to allow geometries that are buffered past extent bounds (e.g. dateline). +* Bump `mapnik-reference` dependency to ~5.0.9 (with `shield-halo-rasterizer`) + +## 0.9.6 + +* Fixed support for `text-face-name` values with `&` like `El&Font Bubble` +* Fixed support for filtering on fields containing single quotes. Now `#layer[name="it's"] { ... }` is possible. +* Fixed support for filtering on fields containing `&`. Now `#layer["Hello&Goodbye"="yes"] { ... }` is possible. +* Added support for exponential notation in filters. Now `#layer[value = 1.2e3] { ... }` is possible. +* Bump `mapnik-reference` dependency to ~5.0.8 (with support for Mapnik v2.3.0 and 3.x) + ## 0.9.5 * Various speed optimizations to help address #20 (#231) @@ -178,5 +258,3 @@ Tagged Aug 15, 2012 * Fix bug in which SRS autodetection broke error handling * Update carto - - diff --git a/DEVELOPING.md b/CONTRIBUTING.md index f63106f..afb531a 100644 --- a/DEVELOPING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,8 @@ Installing: - git clone git@github.com:mapbox/carto.git + git clone https://github.com/mapbox/carto.git + cd carto npm install Test: @@ -13,10 +14,22 @@ Running the head binary: ./bin/carto +## Releasing + + - Make sure all tests are passing + - Ensure CHANGELOG.md is up to date + - Test relevant applications to ensure no regressions + - `npm publish` + - Regenerate documentation (see below) + +If there's a high chance of regression, please bump to 1.0.0 so that code using a semver ^ or ~ doesn't auto-upgrade anyone. + +For examples of previous releases see: https://github.com/mapbox/carto/issues/440 + ## Documentation This repository contains auto-generated documentation of the content of Carto -that's published on MapBox.com. +that's published on Mapbox.com. git fetch origin gh-pages:gh-pages diff --git a/Makefile b/Makefile deleted file mode 100644 index 60277de..0000000 --- a/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# -# Run all tests -# - -expresso = ./node_modules/.bin/mocha - -lint: - ./node_modules/.bin/jshint lib/carto/*.js lib/carto/tree/*.js - -ifndef only -test: - @NODE_PATH=./lib:$NODE_PATH $(expresso) -R spec -I lib test/*.test.js -else -test: - @NODE_PATH=./lib:$NODE_PATH $(expresso) -R spec -I lib test/${only}.test.js -endif - -check: test - -.PHONY: test @@ -1,182 +1,119 @@ # CartoCSS -[](http://travis-ci.org/mapbox/carto) - -Is a stylesheet renderer for Mapnik. It's an evolution of the -[Cascadenik](https://github.com/mapnik/Cascadenik) idea and language, -with an emphasis on speed and flexibility. - -## Reference Documentation - -* [mapbox.com/carto](http://mapbox.com/carto/) - -## MML -_incompatibility_ - -* MML files are assumed to be JSON, not XML. The files are near-identical - to the XML files accepted by Cascadenik, just translated into JSON. -* CartoCSS will not embed files or download URLs for you. Stylesheets should - be embedded directly into your MML JSON and any datasources should be - paths (relative or absolute) that would be acceptable in Mapnik XML. - The [millstone project](https://github.com/mapbox/millstone) aims to fill this need. - -CartoCSS MML: - - { - "srs": "+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over", - "Stylesheet": [{"id":"style.mss","data":"Map {\n background-color: #fff;\n}\n\n#world {\n line-color: #ccc;\n line-width: 0.5;\n polygon-fill: #eee;\n}"}], - "Layer": [{ - "id": "world", - "name": "world", - "srs": "+proj=latlong +ellps=WGS84 +datum=WGS84 +no_defs", - "Datasource": { - "file": "world_borders", - "type": "shape" - } - }] - } +[](http://travis-ci.org/mapbox/carto) [](https://ci.appveyor.com/project/Mapbox/carto) [](https://coveralls.io/github/mapbox/carto?branch=master) [](https://www.npmjs.com/package/carto) -Cascadenik MML +Is the language for map design used by [Mapbox Studio Classic](http://mapbox.com/mapbox-studio-classic/). It is similar in syntax to CSS, but builds upon it with specific abilities to filter map data and by providing things like variables. -<pre><Stylesheet>< and is able to generate Mapnik XML. - Layer { - line-width: 1; - line-color: #696; - polygon-fill: #6f9; - } -]]></Stylesheet> -<Layer srs="+proj=latlong +ellps=WGS84 +datum=WGS84 +no_defs"> - <Datasource> - <Parameter name="type">shape</Parameter> - <Parameter name="file">world_borders</Parameter> - </Datasource> -</Layer> -</Map></pre> - -## Attachments and Instances -_new_ +Carto is an evolution of the [Cascadenik](https://github.com/mapnik/Cascadenik) idea and language, +with an emphasis on speed and flexibility. If you are a previous user of Cascadenik, see the [key differences wiki](https://github.com/mapbox/carto/wiki/Differences-With-Cascadenik). -In CSS, a certain object can only have one instance of a property. A `<div>` has a specific border width and color, rules that match better than others (#id instead of .class) override previous definitions. `CartoCSS` acts the same way normally for the sake of familiarity and organization, but Mapnik itself is more powerful. +## Documentation -Layers in Mapnik can have multiple [borders](http://trac.mapnik.org/wiki/LineSymbolizer) and multiple copies of other attributes. This ability is useful in drawing line outlines, like in the case of road borders or 'glow' effects around coasts. `CartoCSS` makes this accessible by allowing attachments to styles: +For users looking to learn how to use Mapbox Studio Classic the best places to start are to 1) Download [Mapbox Studio Classic](https://www.mapbox.com/mapbox-studio-classic/) and review the [Carto reference documentation](https://github.com/mapbox/carto/blob/master/docs/latest.md). - #world { - line-color: #fff; - line-width: 3; - } +Tutorials like the [Mapbox Getting started with CartoCSS guide](https://www.mapbox.com/guides/getting-started-cartocss/) are a great place to start to learn the basics of CartoCSS. - #world::outline { - line-color: #000; - line-width: 6; - } +For more advanced topics see the [Studio style quickstart guide](https://www.mapbox.com/guides/style-quickstart/) and [Studio style manual](https://www.mapbox.com/guides/style-manual). The links below reference the Tilemill application, which preceded Mapbox Studio Classic, but still contain useful and relevant information. -Attachments are optional: if you don't define them, CartoCSS does overriding of styles just like Cascadenik. + - [Details on Filtering data with CartoCSS](https://www.mapbox.com/tilemill/docs/guides/selectors/) + - [How order works in rendering](https://www.mapbox.com/tilemill/docs/guides/symbol-drawing-order/) + - [How to style labels](https://www.mapbox.com/tilemill/docs/guides/styling-labels/) + - [How to style lines](https://www.mapbox.com/tilemill/docs/guides/styling-lines/) + - [How to style polygons](https://www.mapbox.com/tilemill/docs/guides/styling-polygons/) + - See also the [Styling Concepts](#styling-concepts) for explanations of advanced features. -This brings us to another _incompatibility_: `line-inline` and `line-outline` have been removed from the language, because attachments are capable of the same trick. +## Developers -While attachments allow creating implicit "layers" with the same data, using **instances** allows you to create multiple symbolizers in the same style/layer: +For details about how to install Carto from source and use on the command line see the [Installation section](#installation). - #roads { - casing/line-width: 6; - casing/line-color: #333; - line-width: 4; - line-color: #666; - } +## Styling Concepts -This makes Mapnik first draw the line of color #333 with a width of 6, and then immediately afterwards, it draws the same line again with width 4 and color #666. Contrast that to attachments: Mapnik would first draw all casings before proceeding to the actual lines. +### Attachments and Instances -## text-name -_incompatibility_ +In CSS, a certain object can only have one instance of a property. A `<div>` has a specific border width and color, rules that match better than others (#id instead of .class) override previous definitions. `CartoCSS` acts the same way normally for the sake of familiarity and organization, but Mapnik itself is more powerful. -Instead of the name attribute of the [TextSymbolizer](http://trac.mapnik.org/wiki/TextSymbolizer) and [ShieldSymbolizer](http://trac.mapnik.org/wiki/ShieldSymbolizer) being a part of the selector, it is a property of a rule. Thus the evaluation is less complex and one can use expressions in names. +Layers in Mapnik can have multiple [borders](http://trac.mapnik.org/wiki/LineSymbolizer) and multiple copies of other attributes. This ability is useful in drawing line outlines, like in the case of road borders or 'glow' effects around coasts. `CartoCSS` makes this accessible by allowing attachments to styles: -<table> - <tr> - <th>cascadenik</th> - <th>CartoCSS</th> - </tr> - <tr> - <td valign='top'> - <pre> -#world NAME { - text-face-name: "Arial"; -}</pre> - </td> - <td valign='top'> - <pre> +```css #world { - text-name: "NAME"; - text-face-name: "Arial"; -}</pre> - </td> - </tr> -</table> - -## Mapnik -_new_ + line-color: #fff; + line-width: 3; +} + +#world::outline { + line-color: #000; + line-width: 6; +} +``` -CartoCSS is only compatible with Mapnik >= 2.x.x. +Attachments are optional. -## Rasters and Buildings -_new_ +While attachments allow creating implicit "layers" with the same data, using **instances** allows you to create multiple symbolizers in the same style/layer: -Rasters are supported in CartoCSS - it knows how to download `.vrt`, `.tiff`, and soon other raster formats, and the properties of the [RasterSymbolizer](http://trac.mapnik.org/wiki/RasterSymbolizer) are exposed in the language. +```css +#roads { + casing/line-width: 6; + casing/line-color: #333; + line-width: 4; + line-color: #666; +} +``` -The [BuildingSymbolizer](http://trac.mapnik.org/wiki/BuildingSymbolizer) is also supported in `CartoCSS`. The code stores symbolizer types and properties in a JSON file (in `tree/reference.json`), so new Mapnik features can be quickly implemented here. +This makes Mapnik first draw the line of color #333 with a width of 6, and then immediately afterwards, it draws the same line again with width 4 and color #666. Contrast that to attachments: Mapnik would first draw all casings before proceeding to the actual lines. ## Variables & Expressions -_new_ CartoCSS inherits from its basis in [less.js](http://lesscss.org/) some new features in CSS. One can define variables in stylesheets, and use expressions to modify them. - @mybackground: #2B4D2D; - - Map { - background-color: @mybackground - } - - #world { - polygon-fill: @mybackground + #222; - line-color: darken(@mybackground, 10%); - } +```css +@mybackground: #2B4D2D; + +Map { + background-color: @mybackground +} + +#world { + polygon-fill: @mybackground + #222; + line-color: darken(@mybackground, 10%); +} +``` ## Nested Styles -_new_ CartoCSS also inherits nesting of rules from less.js. - /* Applies to all layers with .land class */ - .land { - line-color: #ccc; - line-width: 0.5; - polygon-fill: #eee; - /* Applies to #lakes.land */ - #lakes { - polygon-fill: #000; - } - } +```css +/* Applies to all layers with .land class */ +.land { + line-color: #ccc; + line-width: 0.5; + polygon-fill: #eee; + /* Applies to #lakes.land */ + #lakes { + polygon-fill: #000; + } +} +``` This can be a convenient way to group style changes by zoom level: - [zoom > 1] { - /* Applies to all layers at zoom > 1 */ - polygon-gamma: 0.3; - #world { - polygon-fill: #323; - } - #lakes { - polygon-fill: #144; - } - } +```css +[zoom > 1] { + /* Applies to all layers at zoom > 1 */ + polygon-gamma: 0.3; + #world { + polygon-fill: #323; + } + #lakes { + polygon-fill: #144; + } +} +``` ## FontSets -_new_ - By defining multiple fonts in a `text-face-name` definition, you create [FontSets](http://trac.mapnik.org/wiki/FontSet) in `CartoCSS`. These are useful for supporting multiple character sets and fallback fonts for distributed styles. <table> @@ -237,11 +174,9 @@ String comparisons: #world[name =~ "A.*"] ``` -## Developers - #### Installation -If you're using [TileMill](http://mapbox.com/tilemill/), you're already +If you're using [Mapbox Studio Classic](http://mapbox.com/mapbox-studio/), you're already using CartoCSS and don't need to do a thing. If you're a developer-type and want to use the `carto` binary with @@ -249,12 +184,25 @@ If you're a developer-type and want to use the `carto` binary with npm install -g carto -#### From the binary +Optionally you may also want to install millstone which is required for resolving data in the same way as Mapbox Studio Classic does: + + npm install -g millstone + -Install `millstone` to enable support for localizing external resources (URLs and local files) referenced in your mml file. +Having `millstone` installed specifically enable support for localizing external resources (URLs and local files) referenced in your mml file, and detecting projections (using [node-srs](https://github.com/mapbox/node-srs)) - npm install millstone - carto map_file.json +Now that Carto is installed you should have a `carto` command line tool available that can be run on a Mapbox Studio Classic project: + + carto project.mml > mapnik.xml + +Available parameters: +* -h / --help - Display help message +* -v / --version - Display version information +* -b / --benchmark - Outputs total compile time +* -l / --localize - Use millstone to localize resources when loading an MML (default: off) +* -n / --nosymlink - Use absolute paths instead of symlinking files +* -a / --api VERSION - Specify Mapnik API version (e.g. --api 3.0.10) (default: 2.3.0) +* -ppi RESOLUTION - Pixels per inch used to convert m, mm, cm, in, pt, pc to pixels (default: 90.714) #### From code @@ -265,39 +213,33 @@ The `Renderer` interface is the main API for developers, and it takes an MML fil // - input (the name or identifier of the file being parsed) // - data (a string containing the MML or an object of MML) var carto = require('carto'); - - new carto.Renderer({ + + try { + var output = new carto.Renderer({ filename: input, local_data_dir: path.dirname(input), - }).render(data, function(err, output) { - if (err) { - if (Array.isArray(err)) { - err.forEach(function(e) { - carto.writeError(e, options); - }); - } else { throw err; } - } else { - sys.puts(output); - } - }); + }).render(data); + } catch(err) { + if (Array.isArray(err)) { + err.forEach(function(e) { + carto.writeError(e, options); + }); + } else { throw err; } + } + console.log(output); ### Vim -To install, download or clone this repository, then add the `vim-carto` -directory located at `build/vim-carto` to your `~/.vim` file. +To install, download or clone this repository, then copy the `vim-carto` +directory located at `build/vim-carto` to your `~/.vim` directory. + + cp build/vim-carto/* ~/.vim -R ## Credits CartoCSS is based on [less.js](https://github.com/cloudhead/less.js), a CSS compiler written by Alexis Sellier. -It depends on: - -* [underscore.js](https://github.com/documentcloud/underscore/) - -Only for running tests: - -* [mocha](https://github.com/visionmedia/mocha) -* [sax-js](https://github.com/isaacs/sax-js/) +See also a [list of dependencies](https://david-dm.org/mapbox/carto#info=dependencies&view=list). ## Authors diff --git a/appveyor.yml b/appveyor.yml new file mode 100644 index 0000000..09804c9 --- /dev/null +++ b/appveyor.yml @@ -0,0 +1,25 @@ +# Test against this versions of Node.js +environment: + matrix: + - nodejs_version: 5 + - nodejs_version: 4 + - nodejs_version: 0.12 + - nodejs_version: 0.10 + +# Install scripts. (runs after repo cloning) +install: + # Get the latest stable version of Node.js or io.js + - ps: Install-Product node $env:nodejs_version + # install modules + - npm install + +# Post-install test scripts. +test_script: + # Output useful info for debugging. + - node --version + - npm --version + # run tests + - npm test + +# Don't actually build. +build: off @@ -3,29 +3,32 @@ var path = require('path'), fs = require('fs'), carto = require('../lib/carto'), + semver = require('semver'), url = require('url'), - _ = require('underscore'); + _ = require('lodash'), + yaml = require('js-yaml'); var existsSync = require('fs').existsSync || require('path').existsSync -var optimist = require('optimist') +var yargs = require('yargs') .usage("Usage: $0 <source MML file>") .options('h', {alias:'help', describe:'Display this help message'}) .options('v', {alias:'version', boolean:true, describe:'Display version information'}) .options('b', {alias:'benchmark', boolean:true, describe:'Outputs total compile time'}) .options('l', {alias:'localize', boolean:true, default:false, describe:'Use millstone to localize resources when loading an MML'}) .options('n', {alias:'nosymlink', boolean:true, describe:'Use absolute paths instead of symlinking files'}) + .options('a', {alias:'api', describe:'Specify Mapnik API version', default:'2.3.0'}) .options('ppi', {describe:'Pixels per inch used to convert m, mm, cm, in, pt, pc to pixels', default:90.714}); -var options = optimist.argv; +var options = yargs.argv; if (options.help) { - optimist.showHelp(); + yargs.showHelp(); process.exit(0); } if (options.version) { - console.log("carto " + carto.version.join('.') + " (Carto map stylesheet compiler)"); + console.error("carto " + carto.version.join('.') + " (Carto map stylesheet compiler)"); process.exit(0); } @@ -35,10 +38,17 @@ if (input && input[0] != '/') { } if (!input) { - console.log("carto: no input files ('carto -h or --help' for help)"); + console.error("carto: no input files ('carto -h or --help' for help)"); process.exit(1); } +if (options.api) { + if (!semver.valid(options.api)) { + console.error("carto: invalid Mapnik API version. A valid version is e.g. 3.0.10"); + process.exit(1); + } +} + if (options.benchmark) { var start = +new Date; } @@ -46,12 +56,12 @@ if (options.benchmark) { var ext = path.extname(input); if (!ext) { - console.log("carto: please pass either a .mml file or .mss file"); + console.error("carto: please pass either a .mml file or .mss file"); process.exit(1); } if (!existsSync(input)) { - console.log("carto: file does not exist: '" + input + "'"); + console.error("carto: file does not exist: '" + input + "'"); process.exit(1); } @@ -65,34 +75,33 @@ function compileMML(err, data) { console.error(err); process.exit(1); } + var renderer = new carto.Renderer({ + filename: input, + benchmark: options.benchmark, + ppi: options.ppi + }, + { + mapnik_version: options.api + }); try { - var renderer = new carto.Renderer({ - filename: input, - benchmark: options.benchmark, - ppi: options.ppi - }); - renderer.render(data, function(err, output) { - if (err) { - console.error(err); - throw err; - process.exit(1); - } else { - if (!options.benchmark) { - console.log(output); - } else { - var duration = (+new Date) - start; - console.log('TOTAL: ' + (duration) + 'ms'); - } - } - }); + var output = renderer.render(data); } catch (e) { if (e.stack) { console.error(e.stack); - } else { + } else if (e.message) { + console.error(e.message); + } + else { console.error(e); } process.exit(1); } + if (!options.benchmark) { + console.log(output); + } else { + var duration = (+new Date) - start; + console.log('TOTAL: ' + (duration) + 'ms'); + } }; function compileMSS(err, data) { @@ -100,26 +109,16 @@ function compileMSS(err, data) { console.error(err); process.exit(1); } + var renderer = new carto.Renderer({ + filename: path.basename(input), + benchmark: options.benchmark, + ppi: options.ppi + }, + { + mapnik_version: options.api + }); try { - var renderer = new carto.Renderer({ - filename: path.basename(input), - benchmark: options.benchmark, - ppi: options.ppi - }); - renderer.renderMSS(data, function(err, output) { - if (err) { - console.error(err); - throw err; - process.exit(1); - } else { - if (!options.benchmark) { - console.log(output); - } else { - var duration = (+new Date) - start; - console.log('TOTAL: ' + (duration) + 'ms'); - } - } - }); + var output = renderer.renderMSS(data); } catch (e) { if (e.stack) { console.error(e.stack); @@ -128,6 +127,12 @@ function compileMSS(err, data) { } process.exit(1); } + if (!options.benchmark) { + console.log(output); + } else { + var duration = (+new Date) - start; + console.log('TOTAL: ' + (duration) + 'ms'); + } }; try { @@ -139,7 +144,7 @@ try { if (ext == '.mml') { try { - data = JSON.parse(data); + data = yaml.safeLoad(data); } catch(err) { console.error("carto: " + err.message.replace(/^[A-Z]+, /, '')); process.exit(1); @@ -161,16 +166,19 @@ if (ext == '.mml') { nosymlink: options.nosymlink }, compileMML); } else { - data.Stylesheet = data.Stylesheet.map(function(x) { - if (typeof x !== 'string') { - return { id: x, data: x.data } - } - return { id: x, data: fs.readFileSync(path.join(path.dirname(input), x), 'utf8') } - }); + if (_.has(data, 'Stylesheet') && !_.isNil(data.Stylesheet)) { + data.Stylesheet = _.castArray(data.Stylesheet); + data.Stylesheet = data.Stylesheet.map(function(x) { + if (typeof x !== 'string') { + return { id: x, data: x.data } + } + return { id: x, data: fs.readFileSync(path.join(path.dirname(input), x), 'utf8') } + }); + } compileMML(null,data); } } else if (ext == '.mss') { compileMSS(null,data); } else { - console.log("carto: please pass either a .mml file or .mss file"); + console.error("carto: please pass either a .mml file or .mss file"); } diff --git a/bin/mml2json.js b/bin/mml2json.js deleted file mode 100755 index 24afcdd..0000000 --- a/bin/mml2json.js +++ /dev/null @@ -1,69 +0,0 @@ -#!/usr/bin/env node - -var xml2js = require('xml2js'), - fs = require('fs'); - -if (!process.argv[2]) { - console.log('Please specify a XML file.'); - process.exit(1); -} - -fs.readFile(process.argv[2], 'utf-8', function(err, data) { - if (err) throw err; - - // Replace entities. - var entities = {}; - var match = data.match(/<!ENTITY([^>]|"([^"]|\\")*")+>/g) - if (match != null) { - match.forEach(function(entity) { - var parts = entity.match(/^<!ENTITY\s+(\w+)\s+"(.+)">$/); - entities['&' + parts[1] + ';'] = parts[2]; - }); - } - data = data.replace(/&\w+;/g, function(entity) { - return entities[entity]; - }); - - function addAttributes(obj) { - if (obj['$']) for (var key in obj['$']) obj[key] = obj['$'][key]; - delete obj['$']; - return obj; - } - - function simplifyExternal(obj) { - if (obj.src) return obj.src; - else return obj; - } - - var parser = new xml2js.Parser({ - explicitRoot: false, - explicitArray: false - }); - parser.addListener('end', function(json) { - console.log(JSON.stringify(json, function(key, value) { - if (!key) { - return addAttributes(value); - } - else if (key === 'Stylesheet') { - if (Array.isArray(value)) return value.map(addAttributes).map(simplifyExternal); - else return [ simplifyExternal(addAttributes(value)) ]; - } - else if (key === 'Layer' || key === 'Stylesheet') { - if (Array.isArray(value)) return value.map(addAttributes); - else return [ addAttributes(value) ]; - } - else if (key === 'Datasource') { - value = addAttributes(value); - value.Parameter.forEach(function(parameter) { - value[parameter['$'].name] = parameter['_']; - }); - delete value.Parameter; - return value; - } - else { - return value; - } - }, 4)); - }); - parser.parseString(data); -}); diff --git a/build/carto.tmbundle/Syntaxes/carto.tmLanguage b/build/carto.tmbundle/Syntaxes/carto.tmLanguage index 9165b1e..96de723 100644 --- a/build/carto.tmbundle/Syntaxes/carto.tmLanguage +++ b/build/carto.tmbundle/Syntaxes/carto.tmLanguage @@ -264,7 +264,7 @@ </dict> </dict> <key>match</key> - <string>\b(background-color|background-image|srs|buffer|font-directory|polygon-fill|polygon-gamma|polygon-opacity|polygon-meta-output|polygon-meta-writer|line-color|line-width|line-opacity|line-join|line-cap|line-gamma|line-dasharray|line-meta-output|line-meta-writer|marker-file|marker-opacity|marker-line-color|marker-line-width|marker-line-opacity|marker-placement|marker-type|marker-width|marker-height|marker-fill|marker-allow-overlap|marker-spacing|marker-max-error|marker-transform|marker-meta-output|marker-meta-writer|shield-name|shield-face-name|shield-size|shield-fill|shield-min-distance|shield-halo-fill|shield-halo-radius|shield-spacing|shield-character-spacing|shield-line-spacing|shield-file|shield-width|shield-height|shield-type|shield-text-dx|shield-text-dy|shield-dx|shield-dy|shield-meta-output|shield-meta-writer|line-pattern-file|line-pattern-width|line-pattern-height|line-pattern-type|line-pattern-meta-output|line-pattern-meta-writer|polygon-pattern-file|polygon-pattern-width|polygon-pattern-height|polygon-pattern-type|polygon-pattern-meta-output|polygon-pattern-meta-writer|raster-opacity|raster-comp-op|raster-scaling|point-file|point-width|point-height|point-type|point-allow-overlap|point-placement|point-meta-output|point-meta-writer|text-name|text-face-name|text-size|text-ratio|text-wrap-width|text-spacing|text-character-spacing|text-line-spacing|text-label-position-tolerance|text-max-char-angle-delta|text-fill|text-halo-fill|text-halo-radius|text-dx|text-dy|text-avoid-edges|text-min-distance|text-min-padding|text-allow-overlap|text-placement|text-placement-type|text-placements|text-transform|text-meta-output|text-meta-writer|building-fill|building-fill-opacity|building-height)\s*:</string> + <string>\b(background-color|background-image|srs|buffer|font-directory|polygon-fill|polygon-gamma|polygon-opacity|polygon-meta-output|polygon-meta-writer|line-color|line-width|line-opacity|line-join|line-cap|line-gamma|line-dasharray|line-meta-output|line-meta-writer|marker-file|marker-opacity|marker-line-color|marker-line-width|marker-line-opacity|marker-placement|marker-type|marker-width|marker-height|marker-fill|marker-allow-overlap|marker-spacing|marker-max-error|marker-transform|marker-meta-output|marker-meta-writer|shield-name|shield-face-name|shield-size|shield-fill|shield-min-distance|shield-halo-fill|shield-halo-radius|shield-spacing|shield-character-spacing|shield-line-spacing|shield-file|shield-width|shield-height|shield-type|shield-text-dx|shield-text-dy|shield-dx|shield-dy|shield-meta-output|shield-meta-writer|shield-label-position-tolerance|line-pattern-file|line-pattern-width|line-pattern-height|line-pattern-type|line-pattern-meta-output|line-pattern-meta-writer|polygon-pattern-file|polygon-pattern-width|polygon-pattern-height|polygon-pattern-type|polygon-pattern-meta-output|polygon-pattern-meta-writer|raster-opacity|raster-comp-op|raster-scaling|point-file|point-width|point-height|point-type|point-allow-overlap|point-placement|point-meta-output|point-meta-writer|text-name|text-face-name|text-size|text-ratio|text-wrap-width|text-spacing|text-character-spacing|text-line-spacing|text-label-position-tolerance|text-max-char-angle-delta|text-fill|text-halo-fill|text-halo-radius|text-dx|text-dy|text-avoid-edges|text-min-distance|text-min-padding|text-allow-overlap|text-placement|text-placement-type|text-placements|text-transform|text-meta-output|text-meta-writer|building-fill|building-fill-opacity|building-height)\s*:</string> </dict> <dict> <key>match</key> diff --git a/docs-generator/README.md b/docs-generator/README.md new file mode 100644 index 0000000..3cd22d6 --- /dev/null +++ b/docs-generator/README.md @@ -0,0 +1,15 @@ +# Generating CartoCSS docs + +From the `docs-generator/` directory: + +``` +$ npm install +``` + +Then: + +``` +$ node generate.js +``` + +Will save docs to `docs/`.
\ No newline at end of file diff --git a/docs-generator/generate.js b/docs-generator/generate.js new file mode 100644 index 0000000..399437e --- /dev/null +++ b/docs-generator/generate.js @@ -0,0 +1,22 @@ +var fs = require('fs'), + path = require('path'), + refs = require('mapnik-reference'), + _ = require('lodash'); + +function tmpl(x) { + return _.template(fs.readFileSync(path.join(__dirname, x), 'utf-8')); +} + +var index = tmpl('index._'); +var table = tmpl('symbolizers._'); + + refs.versions.forEach(function (v) { + var ref = refs.load(v); + fs.writeFileSync(path.join(__dirname, '../docs/' + v + '.md'), index({ + symbolizers: ref.symbolizers, + table: table, + version: v, + versions: refs.versions, + _: _ + })); +}); diff --git a/docs-generator/index._ b/docs-generator/index._ new file mode 100644 index 0000000..8f8bd56 --- /dev/null +++ b/docs-generator/index._ @@ -0,0 +1,153 @@ +# Carto documentation + +The following is a list of properties provided in CartoCSS that you can apply to map elements. +<%= table({symbolizers:symbolizers}) %> + +### Values + +Below is a list of values and an explanation of any expression that can be applied to properties in CartCSS. + +### Color + +CartoCSS accepts a variety of syntaxes for colors - HTML-style hex values, rgb, rgba, hsl, hsla, husl, and husla. It also supports the predefined HTML colors names, like `yellow` and `blue`. + +``` css +#line { +line-color: #ff0; +line-color: #ffff00; +line-color: rgb(255, 255, 0); +line-color: rgba(255, 255, 0, 1); +line-color: hsl(100, 50%, 50%); +line-color: hsla(100, 50%, 50%, 1); +line-color: husl(100, 50%, 50%); // same values yield different color than HSL +line-color: husla(100, 50%, 50%, 1); +line-color: yellow; +} +``` + +Especially of note is the support for hsl and husl, which can be [easier to reason about than rgb()](http://mothereffinghsl.com/). Carto also includes several color operation functions [borrowed from less](http://lesscss.org/functions/#color-operations): + +``` css +// lighten and darken colors +lighten(#ace, 10%); +darken(#ace, 10%); + +// saturate and desaturate +saturate(#550000, 10%); +desaturate(#00ff00, 10%); + +// increase or decrease the opacity of a color +fadein(#fafafa, 10%); +fadeout(#fefefe, 14%); + +// spin rotates a color around the color wheel by degrees +spin(#ff00ff, 10); + +// mix generates a color in between two other colors. +mix(#fff, #000, 50%); + +// get color components +hue(#ff00ff); +saturation(#ff00ff); +lightness(#ff00ff); +alpha(hsla(100, 50%, 50%, 0.5)); +``` + +These functions all take arguments which can be color variables, literal colors, or the results of other functions operating on colors. All the above mentioned functions also come in +a `functionp`-variant (e.g. `lightenp`), which force a given color into perceptual color space. + +### Float + +Float is a fancy way of saying 'number'. In CartoCSS, you specify _just a number_ - unlike CSS, there are no units, but everything is specified in pixels. + +``` css +#line { +line-width: 2; +} +``` + +It's also possible to do simple math with number values: + +``` css +#line { +line-width: 4 / 2; // division +line-width: 4 + 2; // addition +line-width: 4 - 2; // subtraction +line-width: 4 * 2; // multiplication +line-width: 4 % 2; // modulus +} +``` + +### URI + +URI is a fancy way of saying URL. When an argument is a URI, you use the same kind of `url('place.png')` notation that you would with HTML. Quotes around the URL aren't required, but are highly recommended. URIs can be paths to places on your computer, or on the internet. + +```css +#markers { +marker-file: url('marker.png'); +} +``` + +### String + +A string is basically just text. In the case of CartoCSS, you're going to put it in quotes. Strings can be anything, though pay attention to the cases of `text-name` and `shield-name` - they actually will refer to features, which you refer to by putting them in brackets, as seen in the example below. + +```css +#labels { +text-name: "[MY_FIELD]"; +} +``` + +### Boolean + +Boolean means yes or no, so it accepts the values `true` or `false`. + +```css +#markers { +marker-allow-overlap:true; +} +``` + +### Expressions + +Expressions are statements that can include fields, numbers, and other types in a really flexible way. You have run into expressions before, in the realm of 'fields', where you'd specify `"[FIELD]"`, but expressions allow you to drop the quotes and also do quick addition, division, multiplication, and concatenation from within Carto syntax. + +```css +#buildings { +building-height: [HEIGHT_FIELD] * 10; +} +``` + +### Numbers +Numbers are comma-separated lists of one or more number in a specific order. They're used in line dash arrays, in which the numbers specify intervals of line, break, and line again. + +```css +#disputedboundary { +line-dasharray: 1, 4, 2; +} +``` + +### Percentages +In Carto, the percentage symbol, `%` universally means `value/100`. It's meant to be used with ratio-related properties, like opacity rules. + +_You should not use percentages as widths, heights, or other properties - unlike CSS, percentages are not relative to cascaded classes or page size, they're, as stated, simply the value divided by one hundred._ + +```css +#world { +// this syntax +polygon-opacity: 50%; + +// is equivalent to +polygon-opacity: 0.5; +} +``` + +### Functions + +Functions are comma-separated lists of one or more functions. For instance, transforms use the `functions` type to allow for transforms within Carto, which are optionally chainable. + +```css +#point { +point-transform: scale(2, 2); +} +``` diff --git a/docs-generator/package.json b/docs-generator/package.json new file mode 100644 index 0000000..3277622 --- /dev/null +++ b/docs-generator/package.json @@ -0,0 +1,20 @@ +{ + "name": "carto-site", + "private": true, + "version": "0.0.0", + "description": "Mapnik Stylesheet Compiler", + "url": "https://github.com/mapbox/carto", + "repositories": [{ + "type": "git", + "url": "http://github.com/mapbox/carto.git" + }], + "author": { + "name": "MapBox", + "url": "http://mapbox.com/", + "email": "info@mapbox.com" + }, + "dependencies": { + "lodash": "~4.5.1", + "mapnik-reference": "~8.5.3" + } +} diff --git a/docs-generator/symbolizers._ b/docs-generator/symbolizers._ new file mode 100644 index 0000000..0cf507b --- /dev/null +++ b/docs-generator/symbolizers._ @@ -0,0 +1,14 @@ +<% _(symbolizers).each(function(symbolizer, name) { %> +<% if (name == '*') { %>## All elements<% } else { %>## <%= name %><% } %> +<% _(symbolizer).filter(function(p) { return p.css; }).each(function(p) { %> +##### <%= p.css.replace(/\s/g, '') %> <% if (_.isArray(p.type)) { %>`keyword`<% } else { %>`<%= p.type %>`<% } %> +<% if (_.isArray(p.type)) { %><% _(p.type).each(function(type) { %>`<%= type %>`<% }); %><% } %> +<% if (p.type === 'functions' && _.isArray(p.functions)) { %><% _(p.functions).each(function(type) { %>`<%= type[0] %>`<% }); %><% } %> + +<% if (typeof p['default-value'] !== '') { %>Default Value: <%= p['default-value'] %><% } %> +<% if (p['default-meaning']) { %>_(<%- p['default-meaning'] %>)_<% } %> +<% if (typeof p['range'] !== 'undefined') { %>Range: <%= '' + p['range'] %><% } %> +<% if (p.doc) { %><%= p.doc%><% } %> +* * * +<% }); %> +<% }); %> diff --git a/docs/2.0.0.md b/docs/2.0.0.md new file mode 100644 index 0000000..e81d79d --- /dev/null +++ b/docs/2.0.0.md @@ -0,0 +1,1277 @@ +# Carto documentation + +The following is a list of properties provided in CartoCSS that you can apply to map elements. + +## map + +##### background-color `color` + + + +Default Value: none +_(transparent)_ + +Map Background color +* * * + +##### background-image `uri` + + + +Default Value: +_(transparent)_ + +An image that is repeated below all features on a map as a background. +* * * + +##### srs `string` + + + +Default Value: +proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs +_(The proj4 literal of EPSG:4326 is assumed to be the Map's spatial reference and all data from layers within this map will be plotted using this coordinate system. If any layers do not declare an srs value then they will be assumed to be in the same srs as the Map and not transformations will be needed to plot them in the Map's coordinate space)_ + +Map spatial reference (proj4 string) +* * * + +##### buffer-size `float` + + + +Default Value: 0 +_(No buffer will be used)_ + +Extra tolerance around the map (in pixels) used to ensure labels crossing tile boundaries are equally rendered in each tile (e.g. cut in each tile). Not intended to be used in combination with "avoid-edges". +* * * + +##### base `string` + + + +Default Value: +_(This base path defaults to an empty string meaning that any relative paths to files referenced in styles or layers will be interpreted relative to the application process.)_ + +Any relative paths used to reference files will be understood as relative to this directory path if the map is loaded from an in memory object rather than from the filesystem. If the map is loaded from the filesystem and this option is not provided it will be set to the directory of the stylesheet. +* * * + +##### font-directory `uri` + + + +Default Value: none +_(No map-specific fonts will be registered)_ + +Path to a directory which holds fonts which should be registered when the Map is loaded (in addition to any fonts that may be automatically registered). +* * * + + +## polygon + +##### polygon-fill `color` + + + +Default Value: rgba(128,128,128,1) +_(gray and fully opaque (alpha = 1), same as rgb(128,128,128))_ + +Fill color to assign to a polygon +* * * + +##### polygon-gamma `float` + + + +Default Value: 1 +_(fully antialiased)_ +Range: 0-1 +Level of antialiasing of polygon edges +* * * + +##### polygon-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The opacity of the polygon +* * * + +##### polygon-smooth `float` + + + +Default Value: 0 +_(no smoothing)_ +Range: 0-1 +Amount of smoothing applied +* * * + + +## line + +##### line-color `color` + + + +Default Value: rgba(0,0,0,1) +_(black and fully opaque (alpha = 1), same as rgb(0,0,0))_ + +The color of a drawn line +* * * + +##### line-width `float` + + + +Default Value: 1 + + +The width of a line in pixels +* * * + +##### line-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The opacity of a line +* * * + +##### line-join `keyword` +`miter``round``bevel` + + +Default Value: miter + + +The behavior of lines when joining +* * * + +##### line-cap `keyword` +`butt``round``square` + + +Default Value: butt + + +The display of line endings +* * * + +##### line-gamma `float` + + + +Default Value: 1 +_(fully antialiased)_ +Range: 0-1 +Level of antialiasing of stroke line +* * * + +##### line-dasharray `numbers` + + + +Default Value: none +_(solid line)_ + +A pair of length values [a,b], where (a) is the dash length and (b) is the gap length respectively. More than two values are supported for more complex patterns. +* * * + +##### line-dash-offset `numbers` + + + +Default Value: none +_(solid line)_ + +valid parameter but not currently used in renderers +* * * + +##### line-rasterizer `keyword` +`full``fast` + + +Default Value: full + + +Exposes an alternate AGG rendering method that sacrifices some accuracy for speed. +* * * + + +## markers + +##### marker-file `uri` + + + +Default Value: +_(An ellipse or circle, if width equals height)_ + +An SVG file that this marker shows at each placement. If no file is given, the marker will show an ellipse. +* * * + +##### marker-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The overall opacity of the marker +* * * + +##### marker-line-color `color` + + + +Default Value: black + + +The color of the stroke around a marker shape. +* * * + +##### marker-line-width `float` + + + +Default Value: 0.5 + + +The width of the stroke around the marker, in pixels. This is positioned on the boundary, so high values can cover the area itself. +* * * + +##### marker-line-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The opacity of a line +* * * + +##### marker-placement `keyword` +`point``line` + + +Default Value: line + + +Attempt to place markers on a point once or on a line repeatedly +* * * + +##### marker-type `keyword` +`arrow``ellipse` + + +Default Value: ellipse + + +The default marker-type. If a SVG file is not given as the marker-file parameter, the renderer provides either an arrow or an ellipse (a circle if height is equal to width) +* * * + +##### marker-width `float` + + + +Default Value: 10 + + +The width of the marker, if using one of the default types. +* * * + +##### marker-height `float` + + + +Default Value: 10 + + +The height of the marker, if using one of the default types. +* * * + +##### marker-fill `color` + + + +Default Value: blue + + +The color of the area of the marker. +* * * + +##### marker-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow makers to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping markers are shown or hidden. +* * * + +##### marker-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache)_ + +value to control whether the placement of the feature will prevent the placement of other features +* * * + +##### marker-spacing `float` + + + +Default Value: 100 + + +Space between repeated labels +* * * + +##### marker-max-error `float` + + + +Default Value: 0.2 + + +The maximum difference between actual marker placement and the marker-spacing parameter. Setting a high value can allow the renderer to try to resolve placement conflicts with other symbolizers. +* * * + +##### marker-transform `string` + + + +Default Value: +_(no transformation)_ + +An SVG transformation definition +* * * + + +## shield + +##### shield-name `string` + + + +Default Value: + + +Value to use for a shield"s text label. Data columns are specified using brackets like [column_name] +* * * + +##### shield-face-name `string` + + + +Default Value: + + +Font name and style to use for the shield text +* * * + +##### shield-unlock-image `boolean` + + + +Default Value: false +_(text alignment relative to the shield image uses the center of the image as the anchor for text positioning.)_ + +This parameter should be set to true if you are trying to position text beside rather than on top of the shield image +* * * + +##### shield-size `float` + + + +Default Value: 10 + + +The size of the shield text in pixels +* * * + +##### shield-fill `color` + + + +Default Value: black + + +The color of the shield text +* * * + +##### shield-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point + + +How this shield should be placed. Point placement attempts to place it on top of points, line places along lines multiple times per feature, vertex places on the vertexes of polygons, and interior attempts to place inside of polygons. +* * * + +##### shield-avoid-edges `boolean` + + + +Default Value: false + + +Tell positioning algorithm to avoid labeling near intersection edges. +* * * + +##### shield-min-distance `float` + + + +Default Value: 0 + + +Minimum distance to the next shield symbol, not necessarily the same shield. +* * * + +##### shield-spacing `float` + + + +Default Value: 0 + + +The spacing between repeated occurrences of the same shield on a line +* * * + +##### shield-min-padding `float` + + + +Default Value: 0 + + +Determines the minimum amount of padding that a shield gets relative to other shields +* * * + +##### shield-wrap-width `float` + + + +Default Value: 0 + + +Length before wrapping long names. +* * * + +##### shield-wrap-character `string` + + + +Default Value: + + +Use this character instead of a space to wrap long names. +* * * + +##### shield-halo-fill `color` + + + +Default Value: #FFFFFF +_(white)_ + +Specifies the color of the halo around the text. +* * * + +##### shield-halo-radius `float` + + + +Default Value: 0 +_(no halo)_ + +Specify the radius of the halo in pixels +* * * + +##### shield-character-spacing `float` + + + +Default Value: 0 + + +Horizontal spacing between characters (in pixels). Currently works for point placement only, not line placement. +* * * + +##### shield-line-spacing `float` + + + +Default Value: 0 + + +Vertical spacing between lines of multiline labels (in pixels) +* * * + +##### shield-file `uri` + + + +Default Value: none + + +Image file to render behind the shield text +* * * + +##### shield-text-dx `float` + + + +Default Value: 0 + + +Displace text within shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right +* * * + +##### shield-text-dy `float` + + + +Default Value: 0 + + +Displace text within shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text down +* * * + +##### shield-dx `float` + + + +Default Value: 0 + + +Displace shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right +* * * + +##### shield-dy `float` + + + +Default Value: 0 + + +Displace shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text down +* * * + +##### shield-opacity `float` + + + +Default Value: 1 + + +(Default 1.0) - opacity of the image used for the shield +* * * + +##### shield-text-opacity `float` + + + +Default Value: 1 + + +(Default 1.0) - opacity of the text placed on top of the shield +* * * + +##### shield-horizontal-alignment `keyword` +`left``middle``right``auto` + + +Default Value: middle + + +The shield's horizontal alignment from its centerpoint +* * * + +##### shield-text-transform `keyword` +`none``uppercase``lowercase``capitalize` + + +Default Value: none + + +Transform the case of the characters +* * * + +##### shield-no-text `boolean` + + + +Default Value: false + + +Whether the shield should make room for a text label. +* * * + +##### shield-justify-alignment `string` + + + +Default Value: middle + + +Define how text in a shield's label is justified +* * * + + +## line-pattern + +##### line-pattern-file `uri` + + + +Default Value: none + + +An image file to be repeated and warped along a line +* * * + + +## polygon-pattern + +##### polygon-pattern-file `uri` + + + +Default Value: none + + +Image to use as a repeated pattern fill within a polygon +* * * + +##### polygon-pattern-alignment `keyword` +`local``global` + + +Default Value: local + + +Specify whether to align pattern fills to the layer or to the map. +* * * + +##### polygon-pattern-gamma `float` + + + +Default Value: 1 +_(fully antialiased)_ +Range: 0-1 +Level of antialiasing of polygon pattern edges +* * * + + +## raster + +##### raster-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The opacity of the raster symbolizer on top of other symbolizers. +* * * + +##### raster-mode `keyword` +`normal``grain_merge``grain_merge2``multiply``multiply2``divide``divide2``screen``hard_light` + + +Default Value: normal + + +The blending technique used to overlay this raster image on the layer below. Normal simply covers the layer. Grain merge adds the two layers together and subtracts 128 from the value, making the resulting area sometimes high-contrast. Screen often gives a lighter, washed-out appearance. Multiply multiplies the pixels, giving a high-contrast result. Divide divides the upper layer by the lower layer, making a lighter version. +* * * + +##### raster-filter-factor `float` + + + +Default Value: -1 +_(Allow the datasource to choose appropriate downscaling.)_ + +This is used by the Raster or Gdal datasources to pre-downscale images using overviews. Higher numbers can sometimes cause much better scaled image output, at the cost of speed. +* * * + +##### raster-scaling `keyword` +`fast``bilinear``bilinear8``bicubic``spline16``gaussian``lanczos` + + +Default Value: fast + + +The scaling algorithm used to making different resolution versions of this raster layer. Bilinear is a good compromise between speed and accuracy, while lanczos gives the highest quality. +* * * + +##### raster-mesh-size `integer` + + + +Default Value: 16 +_(Reprojection mesh will be 1/16 of the resolution of the source image)_ + +A reduced resolution mesh is used for raster reprojection, and the total image size is divided by the mesh-size to determine the quality of that mesh. Values for mesh-size larger than the default will result in faster reprojection but might lead to distortion. +* * * + + +## point + +##### point-file `uri` + + + +Default Value: none + + +Image file to represent a point +* * * + +##### point-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow points to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping points are shown or hidden. +* * * + +##### point-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache)_ + +value to control whether the placement of the feature will prevent the placement of other features +* * * + +##### point-opacity `float` + + + +Default Value: 1 +_(Fully opaque)_ + +A value from 0 to 1 to control the opacity of the point +* * * + +##### point-placement `keyword` +`centroid``interior` + + +Default Value: centroid + + +How this point should be placed. Centroid calculates the geometric center of a polygon, which can be outside of it, while interior always places inside of a polygon. +* * * + +##### point-transform `string` + + + +Default Value: +_(No transformation)_ + +SVG transformation definition +* * * + + +## text + +##### text-name `string` + + + +Default Value: + + +Value to use for a text label. Data columns are specified using brackets like [column_name] +* * * + +##### text-face-name `string` + + + +Default Value: + + +Font name and style to render a label in +* * * + +##### text-size `float` + + + +Default Value: 10 + + +Text size in pixels +* * * + +##### text-ratio `float` + + + +Default Value: 0 + + +Define the amount of text (of the total) present on successive lines when wrapping occurs +* * * + +##### text-wrap-width `float` + + + +Default Value: 0 + + +Length of a chunk of text in characters before wrapping text +* * * + +##### text-wrap-character `string` + + + +Default Value: + + +Use this character instead of a space to wrap long text. +* * * + +##### text-spacing `float` + + + +Default Value: 0 + + +Distance between repeated text labels on a line +* * * + +##### text-character-spacing `float` + + + +Default Value: 0 + + +Horizontal spacing adjustment between characters in pixels +* * * + +##### text-line-spacing `float` + + + +Default Value: 0 + + +Vertical spacing adjustment between lines in pixels +* * * + +##### text-label-position-tolerance `float` + + + +Default Value: 0 + + +Allows the label to be displaced from its ideal position by a number of pixels +* * * + +##### text-max-char-angle-delta `float` + + + +Default Value: none + + +If present, the maximum angle change, in degrees, allowed between adjacent characters in a label. This will stop label placement around sharp corners. +* * * + +##### text-fill `color` + + + +Default Value: #000000 + + +Specifies the color for the text +* * * + +##### text-opacity `float` + + + +Default Value: 1 +_(Fully opaque)_ + +A number from 0 to 1 specifying the opacity for the text +* * * + +##### text-halo-fill `color` + + + +Default Value: #FFFFFF +_(white)_ + +Specifies the color of the halo around the text. +* * * + +##### text-halo-radius `float` + + + +Default Value: 0 +_(no halo)_ + +Specify the radius of the halo in pixels +* * * + +##### text-dx `float` + + + +Default Value: 0 + + +Displace text by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right +* * * + +##### text-dy `float` + + + +Default Value: 0 + + +Displace text by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text down +* * * + +##### text-vertical-alignment `keyword` +`top``middle``bottom` + + +Default Value: middle +_(Default affected by value of dy; "bottom" for dy>0, "top" for dy<0.)_ + +Position of label relative to point position. +* * * + +##### text-avoid-edges `boolean` + + + +Default Value: false + + +Tell positioning algorithm to avoid labeling near intersection edges. +* * * + +##### text-min-distance `float` + + + +Default Value: 0 + + +Minimum permitted distance to the next text symbolizer. +* * * + +##### text-min-padding `float` + + + +Default Value: 0 + + +Determines the minimum amount of padding that a text symbolizer gets relative to other text +* * * + +##### text-min-path-length `float` + + + +Default Value: 0 +_(place labels on all paths)_ + +Place labels only on paths longer than this value. +* * * + +##### text-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow text to overlap with other text - overlapping markers will not be shown.)_ + +Control whether overlapping text is shown or hidden. +* * * + +##### text-orientation `float` + + + +Default Value: 0 + + +Rotate the text. +* * * + +##### text-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point + + +Control the style of placement of a point versus the geometry it is attached to. +* * * + +##### text-placement-type `keyword` +`dummy``simple` + + +Default Value: dummy + + +Re-position and/or re-size text to avoid overlaps. "simple" for basic algorithm (using text-placements string,) "dummy" to turn this feature off. +* * * + +##### text-placements `string` + + + +Default Value: + + +If "placement-type" is set to "simple", use this "POSITIONS,[SIZES]" string. See TextSymbolizer docs for format. +* * * + +##### text-transform `keyword` +`none``uppercase``lowercase``capitalize` + + +Default Value: none + + +Transform the case of the characters +* * * + +##### text-horizontal-alignment `keyword` +`left``middle``right``auto` + + +Default Value: middle + + +The text's horizontal alignment from its centerpoint +* * * + +##### text-align `keyword` +`left``right``center` + + +Default Value: center + + +Set the text alignment. +* * * + + +## building + +##### building-fill `color` + + + +Default Value: #FFFFFF + + +The color of the buildings walls. +* * * + +##### building-fill-opacity `float` + + + +Default Value: 1 + + +The opacity of the building as a whole, including all walls. +* * * + +##### building-height `float` + + + +Default Value: 0 + + +The height of the building in pixels. +* * * + + + + +### Values + +Below is a list of values and an explanation of any expression that can be applied to properties in CartCSS. + +### Color + +CartoCSS accepts a variety of syntaxes for colors - HTML-style hex values, rgb, rgba, hsl, hsla, husl, and husla. It also supports the predefined HTML colors names, like `yellow` and `blue`. + +``` css +#line { +line-color: #ff0; +line-color: #ffff00; +line-color: rgb(255, 255, 0); +line-color: rgba(255, 255, 0, 1); +line-color: hsl(100, 50%, 50%); +line-color: hsla(100, 50%, 50%, 1); +line-color: husl(100, 50%, 50%); // same values yield different color than HSL +line-color: husla(100, 50%, 50%, 1); +line-color: yellow; +} +``` + +Especially of note is the support for hsl and husl, which can be [easier to reason about than rgb()](http://mothereffinghsl.com/). Carto also includes several color operation functions [borrowed from less](http://lesscss.org/functions/#color-operations): + +``` css +// lighten and darken colors +lighten(#ace, 10%); +darken(#ace, 10%); + +// saturate and desaturate +saturate(#550000, 10%); +desaturate(#00ff00, 10%); + +// increase or decrease the opacity of a color +fadein(#fafafa, 10%); +fadeout(#fefefe, 14%); + +// spin rotates a color around the color wheel by degrees +spin(#ff00ff, 10); + +// mix generates a color in between two other colors. +mix(#fff, #000, 50%); + +// get color components +hue(#ff00ff); +saturation(#ff00ff); +lightness(#ff00ff); +alpha(hsla(100, 50%, 50%, 0.5)); +``` + +These functions all take arguments which can be color variables, literal colors, or the results of other functions operating on colors. All the above mentioned functions also come in +a `functionp`-variant (e.g. `lightenp`), which force a given color into perceptual color space. + +### Float + +Float is a fancy way of saying 'number'. In CartoCSS, you specify _just a number_ - unlike CSS, there are no units, but everything is specified in pixels. + +``` css +#line { +line-width: 2; +} +``` + +It's also possible to do simple math with number values: + +``` css +#line { +line-width: 4 / 2; // division +line-width: 4 + 2; // addition +line-width: 4 - 2; // subtraction +line-width: 4 * 2; // multiplication +line-width: 4 % 2; // modulus +} +``` + +### URI + +URI is a fancy way of saying URL. When an argument is a URI, you use the same kind of `url('place.png')` notation that you would with HTML. Quotes around the URL aren't required, but are highly recommended. URIs can be paths to places on your computer, or on the internet. + +```css +#markers { +marker-file: url('marker.png'); +} +``` + +### String + +A string is basically just text. In the case of CartoCSS, you're going to put it in quotes. Strings can be anything, though pay attention to the cases of `text-name` and `shield-name` - they actually will refer to features, which you refer to by putting them in brackets, as seen in the example below. + +```css +#labels { +text-name: "[MY_FIELD]"; +} +``` + +### Boolean + +Boolean means yes or no, so it accepts the values `true` or `false`. + +```css +#markers { +marker-allow-overlap:true; +} +``` + +### Expressions + +Expressions are statements that can include fields, numbers, and other types in a really flexible way. You have run into expressions before, in the realm of 'fields', where you'd specify `"[FIELD]"`, but expressions allow you to drop the quotes and also do quick addition, division, multiplication, and concatenation from within Carto syntax. + +```css +#buildings { +building-height: [HEIGHT_FIELD] * 10; +} +``` + +### Numbers +Numbers are comma-separated lists of one or more number in a specific order. They're used in line dash arrays, in which the numbers specify intervals of line, break, and line again. + +```css +#disputedboundary { +line-dasharray: 1, 4, 2; +} +``` + +### Percentages +In Carto, the percentage symbol, `%` universally means `value/100`. It's meant to be used with ratio-related properties, like opacity rules. + +_You should not use percentages as widths, heights, or other properties - unlike CSS, percentages are not relative to cascaded classes or page size, they're, as stated, simply the value divided by one hundred._ + +```css +#world { +// this syntax +polygon-opacity: 50%; + +// is equivalent to +polygon-opacity: 0.5; +} +``` + +### Functions + +Functions are comma-separated lists of one or more functions. For instance, transforms use the `functions` type to allow for transforms within Carto, which are optionally chainable. + +```css +#point { +point-transform: scale(2, 2); +} +``` diff --git a/docs/2.0.1.md b/docs/2.0.1.md new file mode 100644 index 0000000..e81d79d --- /dev/null +++ b/docs/2.0.1.md @@ -0,0 +1,1277 @@ +# Carto documentation + +The following is a list of properties provided in CartoCSS that you can apply to map elements. + +## map + +##### background-color `color` + + + +Default Value: none +_(transparent)_ + +Map Background color +* * * + +##### background-image `uri` + + + +Default Value: +_(transparent)_ + +An image that is repeated below all features on a map as a background. +* * * + +##### srs `string` + + + +Default Value: +proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs +_(The proj4 literal of EPSG:4326 is assumed to be the Map's spatial reference and all data from layers within this map will be plotted using this coordinate system. If any layers do not declare an srs value then they will be assumed to be in the same srs as the Map and not transformations will be needed to plot them in the Map's coordinate space)_ + +Map spatial reference (proj4 string) +* * * + +##### buffer-size `float` + + + +Default Value: 0 +_(No buffer will be used)_ + +Extra tolerance around the map (in pixels) used to ensure labels crossing tile boundaries are equally rendered in each tile (e.g. cut in each tile). Not intended to be used in combination with "avoid-edges". +* * * + +##### base `string` + + + +Default Value: +_(This base path defaults to an empty string meaning that any relative paths to files referenced in styles or layers will be interpreted relative to the application process.)_ + +Any relative paths used to reference files will be understood as relative to this directory path if the map is loaded from an in memory object rather than from the filesystem. If the map is loaded from the filesystem and this option is not provided it will be set to the directory of the stylesheet. +* * * + +##### font-directory `uri` + + + +Default Value: none +_(No map-specific fonts will be registered)_ + +Path to a directory which holds fonts which should be registered when the Map is loaded (in addition to any fonts that may be automatically registered). +* * * + + +## polygon + +##### polygon-fill `color` + + + +Default Value: rgba(128,128,128,1) +_(gray and fully opaque (alpha = 1), same as rgb(128,128,128))_ + +Fill color to assign to a polygon +* * * + +##### polygon-gamma `float` + + + +Default Value: 1 +_(fully antialiased)_ +Range: 0-1 +Level of antialiasing of polygon edges +* * * + +##### polygon-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The opacity of the polygon +* * * + +##### polygon-smooth `float` + + + +Default Value: 0 +_(no smoothing)_ +Range: 0-1 +Amount of smoothing applied +* * * + + +## line + +##### line-color `color` + + + +Default Value: rgba(0,0,0,1) +_(black and fully opaque (alpha = 1), same as rgb(0,0,0))_ + +The color of a drawn line +* * * + +##### line-width `float` + + + +Default Value: 1 + + +The width of a line in pixels +* * * + +##### line-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The opacity of a line +* * * + +##### line-join `keyword` +`miter``round``bevel` + + +Default Value: miter + + +The behavior of lines when joining +* * * + +##### line-cap `keyword` +`butt``round``square` + + +Default Value: butt + + +The display of line endings +* * * + +##### line-gamma `float` + + + +Default Value: 1 +_(fully antialiased)_ +Range: 0-1 +Level of antialiasing of stroke line +* * * + +##### line-dasharray `numbers` + + + +Default Value: none +_(solid line)_ + +A pair of length values [a,b], where (a) is the dash length and (b) is the gap length respectively. More than two values are supported for more complex patterns. +* * * + +##### line-dash-offset `numbers` + + + +Default Value: none +_(solid line)_ + +valid parameter but not currently used in renderers +* * * + +##### line-rasterizer `keyword` +`full``fast` + + +Default Value: full + + +Exposes an alternate AGG rendering method that sacrifices some accuracy for speed. +* * * + + +## markers + +##### marker-file `uri` + + + +Default Value: +_(An ellipse or circle, if width equals height)_ + +An SVG file that this marker shows at each placement. If no file is given, the marker will show an ellipse. +* * * + +##### marker-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The overall opacity of the marker +* * * + +##### marker-line-color `color` + + + +Default Value: black + + +The color of the stroke around a marker shape. +* * * + +##### marker-line-width `float` + + + +Default Value: 0.5 + + +The width of the stroke around the marker, in pixels. This is positioned on the boundary, so high values can cover the area itself. +* * * + +##### marker-line-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The opacity of a line +* * * + +##### marker-placement `keyword` +`point``line` + + +Default Value: line + + +Attempt to place markers on a point once or on a line repeatedly +* * * + +##### marker-type `keyword` +`arrow``ellipse` + + +Default Value: ellipse + + +The default marker-type. If a SVG file is not given as the marker-file parameter, the renderer provides either an arrow or an ellipse (a circle if height is equal to width) +* * * + +##### marker-width `float` + + + +Default Value: 10 + + +The width of the marker, if using one of the default types. +* * * + +##### marker-height `float` + + + +Default Value: 10 + + +The height of the marker, if using one of the default types. +* * * + +##### marker-fill `color` + + + +Default Value: blue + + +The color of the area of the marker. +* * * + +##### marker-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow makers to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping markers are shown or hidden. +* * * + +##### marker-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache)_ + +value to control whether the placement of the feature will prevent the placement of other features +* * * + +##### marker-spacing `float` + + + +Default Value: 100 + + +Space between repeated labels +* * * + +##### marker-max-error `float` + + + +Default Value: 0.2 + + +The maximum difference between actual marker placement and the marker-spacing parameter. Setting a high value can allow the renderer to try to resolve placement conflicts with other symbolizers. +* * * + +##### marker-transform `string` + + + +Default Value: +_(no transformation)_ + +An SVG transformation definition +* * * + + +## shield + +##### shield-name `string` + + + +Default Value: + + +Value to use for a shield"s text label. Data columns are specified using brackets like [column_name] +* * * + +##### shield-face-name `string` + + + +Default Value: + + +Font name and style to use for the shield text +* * * + +##### shield-unlock-image `boolean` + + + +Default Value: false +_(text alignment relative to the shield image uses the center of the image as the anchor for text positioning.)_ + +This parameter should be set to true if you are trying to position text beside rather than on top of the shield image +* * * + +##### shield-size `float` + + + +Default Value: 10 + + +The size of the shield text in pixels +* * * + +##### shield-fill `color` + + + +Default Value: black + + +The color of the shield text +* * * + +##### shield-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point + + +How this shield should be placed. Point placement attempts to place it on top of points, line places along lines multiple times per feature, vertex places on the vertexes of polygons, and interior attempts to place inside of polygons. +* * * + +##### shield-avoid-edges `boolean` + + + +Default Value: false + + +Tell positioning algorithm to avoid labeling near intersection edges. +* * * + +##### shield-min-distance `float` + + + +Default Value: 0 + + +Minimum distance to the next shield symbol, not necessarily the same shield. +* * * + +##### shield-spacing `float` + + + +Default Value: 0 + + +The spacing between repeated occurrences of the same shield on a line +* * * + +##### shield-min-padding `float` + + + +Default Value: 0 + + +Determines the minimum amount of padding that a shield gets relative to other shields +* * * + +##### shield-wrap-width `float` + + + +Default Value: 0 + + +Length before wrapping long names. +* * * + +##### shield-wrap-character `string` + + + +Default Value: + + +Use this character instead of a space to wrap long names. +* * * + +##### shield-halo-fill `color` + + + +Default Value: #FFFFFF +_(white)_ + +Specifies the color of the halo around the text. +* * * + +##### shield-halo-radius `float` + + + +Default Value: 0 +_(no halo)_ + +Specify the radius of the halo in pixels +* * * + +##### shield-character-spacing `float` + + + +Default Value: 0 + + +Horizontal spacing between characters (in pixels). Currently works for point placement only, not line placement. +* * * + +##### shield-line-spacing `float` + + + +Default Value: 0 + + +Vertical spacing between lines of multiline labels (in pixels) +* * * + +##### shield-file `uri` + + + +Default Value: none + + +Image file to render behind the shield text +* * * + +##### shield-text-dx `float` + + + +Default Value: 0 + + +Displace text within shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right +* * * + +##### shield-text-dy `float` + + + +Default Value: 0 + + +Displace text within shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text down +* * * + +##### shield-dx `float` + + + +Default Value: 0 + + +Displace shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right +* * * + +##### shield-dy `float` + + + +Default Value: 0 + + +Displace shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text down +* * * + +##### shield-opacity `float` + + + +Default Value: 1 + + +(Default 1.0) - opacity of the image used for the shield +* * * + +##### shield-text-opacity `float` + + + +Default Value: 1 + + +(Default 1.0) - opacity of the text placed on top of the shield +* * * + +##### shield-horizontal-alignment `keyword` +`left``middle``right``auto` + + +Default Value: middle + + +The shield's horizontal alignment from its centerpoint +* * * + +##### shield-text-transform `keyword` +`none``uppercase``lowercase``capitalize` + + +Default Value: none + + +Transform the case of the characters +* * * + +##### shield-no-text `boolean` + + + +Default Value: false + + +Whether the shield should make room for a text label. +* * * + +##### shield-justify-alignment `string` + + + +Default Value: middle + + +Define how text in a shield's label is justified +* * * + + +## line-pattern + +##### line-pattern-file `uri` + + + +Default Value: none + + +An image file to be repeated and warped along a line +* * * + + +## polygon-pattern + +##### polygon-pattern-file `uri` + + + +Default Value: none + + +Image to use as a repeated pattern fill within a polygon +* * * + +##### polygon-pattern-alignment `keyword` +`local``global` + + +Default Value: local + + +Specify whether to align pattern fills to the layer or to the map. +* * * + +##### polygon-pattern-gamma `float` + + + +Default Value: 1 +_(fully antialiased)_ +Range: 0-1 +Level of antialiasing of polygon pattern edges +* * * + + +## raster + +##### raster-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The opacity of the raster symbolizer on top of other symbolizers. +* * * + +##### raster-mode `keyword` +`normal``grain_merge``grain_merge2``multiply``multiply2``divide``divide2``screen``hard_light` + + +Default Value: normal + + +The blending technique used to overlay this raster image on the layer below. Normal simply covers the layer. Grain merge adds the two layers together and subtracts 128 from the value, making the resulting area sometimes high-contrast. Screen often gives a lighter, washed-out appearance. Multiply multiplies the pixels, giving a high-contrast result. Divide divides the upper layer by the lower layer, making a lighter version. +* * * + +##### raster-filter-factor `float` + + + +Default Value: -1 +_(Allow the datasource to choose appropriate downscaling.)_ + +This is used by the Raster or Gdal datasources to pre-downscale images using overviews. Higher numbers can sometimes cause much better scaled image output, at the cost of speed. +* * * + +##### raster-scaling `keyword` +`fast``bilinear``bilinear8``bicubic``spline16``gaussian``lanczos` + + +Default Value: fast + + +The scaling algorithm used to making different resolution versions of this raster layer. Bilinear is a good compromise between speed and accuracy, while lanczos gives the highest quality. +* * * + +##### raster-mesh-size `integer` + + + +Default Value: 16 +_(Reprojection mesh will be 1/16 of the resolution of the source image)_ + +A reduced resolution mesh is used for raster reprojection, and the total image size is divided by the mesh-size to determine the quality of that mesh. Values for mesh-size larger than the default will result in faster reprojection but might lead to distortion. +* * * + + +## point + +##### point-file `uri` + + + +Default Value: none + + +Image file to represent a point +* * * + +##### point-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow points to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping points are shown or hidden. +* * * + +##### point-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache)_ + +value to control whether the placement of the feature will prevent the placement of other features +* * * + +##### point-opacity `float` + + + +Default Value: 1 +_(Fully opaque)_ + +A value from 0 to 1 to control the opacity of the point +* * * + +##### point-placement `keyword` +`centroid``interior` + + +Default Value: centroid + + +How this point should be placed. Centroid calculates the geometric center of a polygon, which can be outside of it, while interior always places inside of a polygon. +* * * + +##### point-transform `string` + + + +Default Value: +_(No transformation)_ + +SVG transformation definition +* * * + + +## text + +##### text-name `string` + + + +Default Value: + + +Value to use for a text label. Data columns are specified using brackets like [column_name] +* * * + +##### text-face-name `string` + + + +Default Value: + + +Font name and style to render a label in +* * * + +##### text-size `float` + + + +Default Value: 10 + + +Text size in pixels +* * * + +##### text-ratio `float` + + + +Default Value: 0 + + +Define the amount of text (of the total) present on successive lines when wrapping occurs +* * * + +##### text-wrap-width `float` + + + +Default Value: 0 + + +Length of a chunk of text in characters before wrapping text +* * * + +##### text-wrap-character `string` + + + +Default Value: + + +Use this character instead of a space to wrap long text. +* * * + +##### text-spacing `float` + + + +Default Value: 0 + + +Distance between repeated text labels on a line +* * * + +##### text-character-spacing `float` + + + +Default Value: 0 + + +Horizontal spacing adjustment between characters in pixels +* * * + +##### text-line-spacing `float` + + + +Default Value: 0 + + +Vertical spacing adjustment between lines in pixels +* * * + +##### text-label-position-tolerance `float` + + + +Default Value: 0 + + +Allows the label to be displaced from its ideal position by a number of pixels +* * * + +##### text-max-char-angle-delta `float` + + + +Default Value: none + + +If present, the maximum angle change, in degrees, allowed between adjacent characters in a label. This will stop label placement around sharp corners. +* * * + +##### text-fill `color` + + + +Default Value: #000000 + + +Specifies the color for the text +* * * + +##### text-opacity `float` + + + +Default Value: 1 +_(Fully opaque)_ + +A number from 0 to 1 specifying the opacity for the text +* * * + +##### text-halo-fill `color` + + + +Default Value: #FFFFFF +_(white)_ + +Specifies the color of the halo around the text. +* * * + +##### text-halo-radius `float` + + + +Default Value: 0 +_(no halo)_ + +Specify the radius of the halo in pixels +* * * + +##### text-dx `float` + + + +Default Value: 0 + + +Displace text by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right +* * * + +##### text-dy `float` + + + +Default Value: 0 + + +Displace text by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text down +* * * + +##### text-vertical-alignment `keyword` +`top``middle``bottom` + + +Default Value: middle +_(Default affected by value of dy; "bottom" for dy>0, "top" for dy<0.)_ + +Position of label relative to point position. +* * * + +##### text-avoid-edges `boolean` + + + +Default Value: false + + +Tell positioning algorithm to avoid labeling near intersection edges. +* * * + +##### text-min-distance `float` + + + +Default Value: 0 + + +Minimum permitted distance to the next text symbolizer. +* * * + +##### text-min-padding `float` + + + +Default Value: 0 + + +Determines the minimum amount of padding that a text symbolizer gets relative to other text +* * * + +##### text-min-path-length `float` + + + +Default Value: 0 +_(place labels on all paths)_ + +Place labels only on paths longer than this value. +* * * + +##### text-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow text to overlap with other text - overlapping markers will not be shown.)_ + +Control whether overlapping text is shown or hidden. +* * * + +##### text-orientation `float` + + + +Default Value: 0 + + +Rotate the text. +* * * + +##### text-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point + + +Control the style of placement of a point versus the geometry it is attached to. +* * * + +##### text-placement-type `keyword` +`dummy``simple` + + +Default Value: dummy + + +Re-position and/or re-size text to avoid overlaps. "simple" for basic algorithm (using text-placements string,) "dummy" to turn this feature off. +* * * + +##### text-placements `string` + + + +Default Value: + + +If "placement-type" is set to "simple", use this "POSITIONS,[SIZES]" string. See TextSymbolizer docs for format. +* * * + +##### text-transform `keyword` +`none``uppercase``lowercase``capitalize` + + +Default Value: none + + +Transform the case of the characters +* * * + +##### text-horizontal-alignment `keyword` +`left``middle``right``auto` + + +Default Value: middle + + +The text's horizontal alignment from its centerpoint +* * * + +##### text-align `keyword` +`left``right``center` + + +Default Value: center + + +Set the text alignment. +* * * + + +## building + +##### building-fill `color` + + + +Default Value: #FFFFFF + + +The color of the buildings walls. +* * * + +##### building-fill-opacity `float` + + + +Default Value: 1 + + +The opacity of the building as a whole, including all walls. +* * * + +##### building-height `float` + + + +Default Value: 0 + + +The height of the building in pixels. +* * * + + + + +### Values + +Below is a list of values and an explanation of any expression that can be applied to properties in CartCSS. + +### Color + +CartoCSS accepts a variety of syntaxes for colors - HTML-style hex values, rgb, rgba, hsl, hsla, husl, and husla. It also supports the predefined HTML colors names, like `yellow` and `blue`. + +``` css +#line { +line-color: #ff0; +line-color: #ffff00; +line-color: rgb(255, 255, 0); +line-color: rgba(255, 255, 0, 1); +line-color: hsl(100, 50%, 50%); +line-color: hsla(100, 50%, 50%, 1); +line-color: husl(100, 50%, 50%); // same values yield different color than HSL +line-color: husla(100, 50%, 50%, 1); +line-color: yellow; +} +``` + +Especially of note is the support for hsl and husl, which can be [easier to reason about than rgb()](http://mothereffinghsl.com/). Carto also includes several color operation functions [borrowed from less](http://lesscss.org/functions/#color-operations): + +``` css +// lighten and darken colors +lighten(#ace, 10%); +darken(#ace, 10%); + +// saturate and desaturate +saturate(#550000, 10%); +desaturate(#00ff00, 10%); + +// increase or decrease the opacity of a color +fadein(#fafafa, 10%); +fadeout(#fefefe, 14%); + +// spin rotates a color around the color wheel by degrees +spin(#ff00ff, 10); + +// mix generates a color in between two other colors. +mix(#fff, #000, 50%); + +// get color components +hue(#ff00ff); +saturation(#ff00ff); +lightness(#ff00ff); +alpha(hsla(100, 50%, 50%, 0.5)); +``` + +These functions all take arguments which can be color variables, literal colors, or the results of other functions operating on colors. All the above mentioned functions also come in +a `functionp`-variant (e.g. `lightenp`), which force a given color into perceptual color space. + +### Float + +Float is a fancy way of saying 'number'. In CartoCSS, you specify _just a number_ - unlike CSS, there are no units, but everything is specified in pixels. + +``` css +#line { +line-width: 2; +} +``` + +It's also possible to do simple math with number values: + +``` css +#line { +line-width: 4 / 2; // division +line-width: 4 + 2; // addition +line-width: 4 - 2; // subtraction +line-width: 4 * 2; // multiplication +line-width: 4 % 2; // modulus +} +``` + +### URI + +URI is a fancy way of saying URL. When an argument is a URI, you use the same kind of `url('place.png')` notation that you would with HTML. Quotes around the URL aren't required, but are highly recommended. URIs can be paths to places on your computer, or on the internet. + +```css +#markers { +marker-file: url('marker.png'); +} +``` + +### String + +A string is basically just text. In the case of CartoCSS, you're going to put it in quotes. Strings can be anything, though pay attention to the cases of `text-name` and `shield-name` - they actually will refer to features, which you refer to by putting them in brackets, as seen in the example below. + +```css +#labels { +text-name: "[MY_FIELD]"; +} +``` + +### Boolean + +Boolean means yes or no, so it accepts the values `true` or `false`. + +```css +#markers { +marker-allow-overlap:true; +} +``` + +### Expressions + +Expressions are statements that can include fields, numbers, and other types in a really flexible way. You have run into expressions before, in the realm of 'fields', where you'd specify `"[FIELD]"`, but expressions allow you to drop the quotes and also do quick addition, division, multiplication, and concatenation from within Carto syntax. + +```css +#buildings { +building-height: [HEIGHT_FIELD] * 10; +} +``` + +### Numbers +Numbers are comma-separated lists of one or more number in a specific order. They're used in line dash arrays, in which the numbers specify intervals of line, break, and line again. + +```css +#disputedboundary { +line-dasharray: 1, 4, 2; +} +``` + +### Percentages +In Carto, the percentage symbol, `%` universally means `value/100`. It's meant to be used with ratio-related properties, like opacity rules. + +_You should not use percentages as widths, heights, or other properties - unlike CSS, percentages are not relative to cascaded classes or page size, they're, as stated, simply the value divided by one hundred._ + +```css +#world { +// this syntax +polygon-opacity: 50%; + +// is equivalent to +polygon-opacity: 0.5; +} +``` + +### Functions + +Functions are comma-separated lists of one or more functions. For instance, transforms use the `functions` type to allow for transforms within Carto, which are optionally chainable. + +```css +#point { +point-transform: scale(2, 2); +} +``` diff --git a/docs/2.0.2.md b/docs/2.0.2.md new file mode 100644 index 0000000..e81d79d --- /dev/null +++ b/docs/2.0.2.md @@ -0,0 +1,1277 @@ +# Carto documentation + +The following is a list of properties provided in CartoCSS that you can apply to map elements. + +## map + +##### background-color `color` + + + +Default Value: none +_(transparent)_ + +Map Background color +* * * + +##### background-image `uri` + + + +Default Value: +_(transparent)_ + +An image that is repeated below all features on a map as a background. +* * * + +##### srs `string` + + + +Default Value: +proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs +_(The proj4 literal of EPSG:4326 is assumed to be the Map's spatial reference and all data from layers within this map will be plotted using this coordinate system. If any layers do not declare an srs value then they will be assumed to be in the same srs as the Map and not transformations will be needed to plot them in the Map's coordinate space)_ + +Map spatial reference (proj4 string) +* * * + +##### buffer-size `float` + + + +Default Value: 0 +_(No buffer will be used)_ + +Extra tolerance around the map (in pixels) used to ensure labels crossing tile boundaries are equally rendered in each tile (e.g. cut in each tile). Not intended to be used in combination with "avoid-edges". +* * * + +##### base `string` + + + +Default Value: +_(This base path defaults to an empty string meaning that any relative paths to files referenced in styles or layers will be interpreted relative to the application process.)_ + +Any relative paths used to reference files will be understood as relative to this directory path if the map is loaded from an in memory object rather than from the filesystem. If the map is loaded from the filesystem and this option is not provided it will be set to the directory of the stylesheet. +* * * + +##### font-directory `uri` + + + +Default Value: none +_(No map-specific fonts will be registered)_ + +Path to a directory which holds fonts which should be registered when the Map is loaded (in addition to any fonts that may be automatically registered). +* * * + + +## polygon + +##### polygon-fill `color` + + + +Default Value: rgba(128,128,128,1) +_(gray and fully opaque (alpha = 1), same as rgb(128,128,128))_ + +Fill color to assign to a polygon +* * * + +##### polygon-gamma `float` + + + +Default Value: 1 +_(fully antialiased)_ +Range: 0-1 +Level of antialiasing of polygon edges +* * * + +##### polygon-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The opacity of the polygon +* * * + +##### polygon-smooth `float` + + + +Default Value: 0 +_(no smoothing)_ +Range: 0-1 +Amount of smoothing applied +* * * + + +## line + +##### line-color `color` + + + +Default Value: rgba(0,0,0,1) +_(black and fully opaque (alpha = 1), same as rgb(0,0,0))_ + +The color of a drawn line +* * * + +##### line-width `float` + + + +Default Value: 1 + + +The width of a line in pixels +* * * + +##### line-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The opacity of a line +* * * + +##### line-join `keyword` +`miter``round``bevel` + + +Default Value: miter + + +The behavior of lines when joining +* * * + +##### line-cap `keyword` +`butt``round``square` + + +Default Value: butt + + +The display of line endings +* * * + +##### line-gamma `float` + + + +Default Value: 1 +_(fully antialiased)_ +Range: 0-1 +Level of antialiasing of stroke line +* * * + +##### line-dasharray `numbers` + + + +Default Value: none +_(solid line)_ + +A pair of length values [a,b], where (a) is the dash length and (b) is the gap length respectively. More than two values are supported for more complex patterns. +* * * + +##### line-dash-offset `numbers` + + + +Default Value: none +_(solid line)_ + +valid parameter but not currently used in renderers +* * * + +##### line-rasterizer `keyword` +`full``fast` + + +Default Value: full + + +Exposes an alternate AGG rendering method that sacrifices some accuracy for speed. +* * * + + +## markers + +##### marker-file `uri` + + + +Default Value: +_(An ellipse or circle, if width equals height)_ + +An SVG file that this marker shows at each placement. If no file is given, the marker will show an ellipse. +* * * + +##### marker-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The overall opacity of the marker +* * * + +##### marker-line-color `color` + + + +Default Value: black + + +The color of the stroke around a marker shape. +* * * + +##### marker-line-width `float` + + + +Default Value: 0.5 + + +The width of the stroke around the marker, in pixels. This is positioned on the boundary, so high values can cover the area itself. +* * * + +##### marker-line-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The opacity of a line +* * * + +##### marker-placement `keyword` +`point``line` + + +Default Value: line + + +Attempt to place markers on a point once or on a line repeatedly +* * * + +##### marker-type `keyword` +`arrow``ellipse` + + +Default Value: ellipse + + +The default marker-type. If a SVG file is not given as the marker-file parameter, the renderer provides either an arrow or an ellipse (a circle if height is equal to width) +* * * + +##### marker-width `float` + + + +Default Value: 10 + + +The width of the marker, if using one of the default types. +* * * + +##### marker-height `float` + + + +Default Value: 10 + + +The height of the marker, if using one of the default types. +* * * + +##### marker-fill `color` + + + +Default Value: blue + + +The color of the area of the marker. +* * * + +##### marker-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow makers to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping markers are shown or hidden. +* * * + +##### marker-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache)_ + +value to control whether the placement of the feature will prevent the placement of other features +* * * + +##### marker-spacing `float` + + + +Default Value: 100 + + +Space between repeated labels +* * * + +##### marker-max-error `float` + + + +Default Value: 0.2 + + +The maximum difference between actual marker placement and the marker-spacing parameter. Setting a high value can allow the renderer to try to resolve placement conflicts with other symbolizers. +* * * + +##### marker-transform `string` + + + +Default Value: +_(no transformation)_ + +An SVG transformation definition +* * * + + +## shield + +##### shield-name `string` + + + +Default Value: + + +Value to use for a shield"s text label. Data columns are specified using brackets like [column_name] +* * * + +##### shield-face-name `string` + + + +Default Value: + + +Font name and style to use for the shield text +* * * + +##### shield-unlock-image `boolean` + + + +Default Value: false +_(text alignment relative to the shield image uses the center of the image as the anchor for text positioning.)_ + +This parameter should be set to true if you are trying to position text beside rather than on top of the shield image +* * * + +##### shield-size `float` + + + +Default Value: 10 + + +The size of the shield text in pixels +* * * + +##### shield-fill `color` + + + +Default Value: black + + +The color of the shield text +* * * + +##### shield-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point + + +How this shield should be placed. Point placement attempts to place it on top of points, line places along lines multiple times per feature, vertex places on the vertexes of polygons, and interior attempts to place inside of polygons. +* * * + +##### shield-avoid-edges `boolean` + + + +Default Value: false + + +Tell positioning algorithm to avoid labeling near intersection edges. +* * * + +##### shield-min-distance `float` + + + +Default Value: 0 + + +Minimum distance to the next shield symbol, not necessarily the same shield. +* * * + +##### shield-spacing `float` + + + +Default Value: 0 + + +The spacing between repeated occurrences of the same shield on a line +* * * + +##### shield-min-padding `float` + + + +Default Value: 0 + + +Determines the minimum amount of padding that a shield gets relative to other shields +* * * + +##### shield-wrap-width `float` + + + +Default Value: 0 + + +Length before wrapping long names. +* * * + +##### shield-wrap-character `string` + + + +Default Value: + + +Use this character instead of a space to wrap long names. +* * * + +##### shield-halo-fill `color` + + + +Default Value: #FFFFFF +_(white)_ + +Specifies the color of the halo around the text. +* * * + +##### shield-halo-radius `float` + + + +Default Value: 0 +_(no halo)_ + +Specify the radius of the halo in pixels +* * * + +##### shield-character-spacing `float` + + + +Default Value: 0 + + +Horizontal spacing between characters (in pixels). Currently works for point placement only, not line placement. +* * * + +##### shield-line-spacing `float` + + + +Default Value: 0 + + +Vertical spacing between lines of multiline labels (in pixels) +* * * + +##### shield-file `uri` + + + +Default Value: none + + +Image file to render behind the shield text +* * * + +##### shield-text-dx `float` + + + +Default Value: 0 + + +Displace text within shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right +* * * + +##### shield-text-dy `float` + + + +Default Value: 0 + + +Displace text within shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text down +* * * + +##### shield-dx `float` + + + +Default Value: 0 + + +Displace shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right +* * * + +##### shield-dy `float` + + + +Default Value: 0 + + +Displace shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text down +* * * + +##### shield-opacity `float` + + + +Default Value: 1 + + +(Default 1.0) - opacity of the image used for the shield +* * * + +##### shield-text-opacity `float` + + + +Default Value: 1 + + +(Default 1.0) - opacity of the text placed on top of the shield +* * * + +##### shield-horizontal-alignment `keyword` +`left``middle``right``auto` + + +Default Value: middle + + +The shield's horizontal alignment from its centerpoint +* * * + +##### shield-text-transform `keyword` +`none``uppercase``lowercase``capitalize` + + +Default Value: none + + +Transform the case of the characters +* * * + +##### shield-no-text `boolean` + + + +Default Value: false + + +Whether the shield should make room for a text label. +* * * + +##### shield-justify-alignment `string` + + + +Default Value: middle + + +Define how text in a shield's label is justified +* * * + + +## line-pattern + +##### line-pattern-file `uri` + + + +Default Value: none + + +An image file to be repeated and warped along a line +* * * + + +## polygon-pattern + +##### polygon-pattern-file `uri` + + + +Default Value: none + + +Image to use as a repeated pattern fill within a polygon +* * * + +##### polygon-pattern-alignment `keyword` +`local``global` + + +Default Value: local + + +Specify whether to align pattern fills to the layer or to the map. +* * * + +##### polygon-pattern-gamma `float` + + + +Default Value: 1 +_(fully antialiased)_ +Range: 0-1 +Level of antialiasing of polygon pattern edges +* * * + + +## raster + +##### raster-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The opacity of the raster symbolizer on top of other symbolizers. +* * * + +##### raster-mode `keyword` +`normal``grain_merge``grain_merge2``multiply``multiply2``divide``divide2``screen``hard_light` + + +Default Value: normal + + +The blending technique used to overlay this raster image on the layer below. Normal simply covers the layer. Grain merge adds the two layers together and subtracts 128 from the value, making the resulting area sometimes high-contrast. Screen often gives a lighter, washed-out appearance. Multiply multiplies the pixels, giving a high-contrast result. Divide divides the upper layer by the lower layer, making a lighter version. +* * * + +##### raster-filter-factor `float` + + + +Default Value: -1 +_(Allow the datasource to choose appropriate downscaling.)_ + +This is used by the Raster or Gdal datasources to pre-downscale images using overviews. Higher numbers can sometimes cause much better scaled image output, at the cost of speed. +* * * + +##### raster-scaling `keyword` +`fast``bilinear``bilinear8``bicubic``spline16``gaussian``lanczos` + + +Default Value: fast + + +The scaling algorithm used to making different resolution versions of this raster layer. Bilinear is a good compromise between speed and accuracy, while lanczos gives the highest quality. +* * * + +##### raster-mesh-size `integer` + + + +Default Value: 16 +_(Reprojection mesh will be 1/16 of the resolution of the source image)_ + +A reduced resolution mesh is used for raster reprojection, and the total image size is divided by the mesh-size to determine the quality of that mesh. Values for mesh-size larger than the default will result in faster reprojection but might lead to distortion. +* * * + + +## point + +##### point-file `uri` + + + +Default Value: none + + +Image file to represent a point +* * * + +##### point-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow points to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping points are shown or hidden. +* * * + +##### point-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache)_ + +value to control whether the placement of the feature will prevent the placement of other features +* * * + +##### point-opacity `float` + + + +Default Value: 1 +_(Fully opaque)_ + +A value from 0 to 1 to control the opacity of the point +* * * + +##### point-placement `keyword` +`centroid``interior` + + +Default Value: centroid + + +How this point should be placed. Centroid calculates the geometric center of a polygon, which can be outside of it, while interior always places inside of a polygon. +* * * + +##### point-transform `string` + + + +Default Value: +_(No transformation)_ + +SVG transformation definition +* * * + + +## text + +##### text-name `string` + + + +Default Value: + + +Value to use for a text label. Data columns are specified using brackets like [column_name] +* * * + +##### text-face-name `string` + + + +Default Value: + + +Font name and style to render a label in +* * * + +##### text-size `float` + + + +Default Value: 10 + + +Text size in pixels +* * * + +##### text-ratio `float` + + + +Default Value: 0 + + +Define the amount of text (of the total) present on successive lines when wrapping occurs +* * * + +##### text-wrap-width `float` + + + +Default Value: 0 + + +Length of a chunk of text in characters before wrapping text +* * * + +##### text-wrap-character `string` + + + +Default Value: + + +Use this character instead of a space to wrap long text. +* * * + +##### text-spacing `float` + + + +Default Value: 0 + + +Distance between repeated text labels on a line +* * * + +##### text-character-spacing `float` + + + +Default Value: 0 + + +Horizontal spacing adjustment between characters in pixels +* * * + +##### text-line-spacing `float` + + + +Default Value: 0 + + +Vertical spacing adjustment between lines in pixels +* * * + +##### text-label-position-tolerance `float` + + + +Default Value: 0 + + +Allows the label to be displaced from its ideal position by a number of pixels +* * * + +##### text-max-char-angle-delta `float` + + + +Default Value: none + + +If present, the maximum angle change, in degrees, allowed between adjacent characters in a label. This will stop label placement around sharp corners. +* * * + +##### text-fill `color` + + + +Default Value: #000000 + + +Specifies the color for the text +* * * + +##### text-opacity `float` + + + +Default Value: 1 +_(Fully opaque)_ + +A number from 0 to 1 specifying the opacity for the text +* * * + +##### text-halo-fill `color` + + + +Default Value: #FFFFFF +_(white)_ + +Specifies the color of the halo around the text. +* * * + +##### text-halo-radius `float` + + + +Default Value: 0 +_(no halo)_ + +Specify the radius of the halo in pixels +* * * + +##### text-dx `float` + + + +Default Value: 0 + + +Displace text by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right +* * * + +##### text-dy `float` + + + +Default Value: 0 + + +Displace text by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text down +* * * + +##### text-vertical-alignment `keyword` +`top``middle``bottom` + + +Default Value: middle +_(Default affected by value of dy; "bottom" for dy>0, "top" for dy<0.)_ + +Position of label relative to point position. +* * * + +##### text-avoid-edges `boolean` + + + +Default Value: false + + +Tell positioning algorithm to avoid labeling near intersection edges. +* * * + +##### text-min-distance `float` + + + +Default Value: 0 + + +Minimum permitted distance to the next text symbolizer. +* * * + +##### text-min-padding `float` + + + +Default Value: 0 + + +Determines the minimum amount of padding that a text symbolizer gets relative to other text +* * * + +##### text-min-path-length `float` + + + +Default Value: 0 +_(place labels on all paths)_ + +Place labels only on paths longer than this value. +* * * + +##### text-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow text to overlap with other text - overlapping markers will not be shown.)_ + +Control whether overlapping text is shown or hidden. +* * * + +##### text-orientation `float` + + + +Default Value: 0 + + +Rotate the text. +* * * + +##### text-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point + + +Control the style of placement of a point versus the geometry it is attached to. +* * * + +##### text-placement-type `keyword` +`dummy``simple` + + +Default Value: dummy + + +Re-position and/or re-size text to avoid overlaps. "simple" for basic algorithm (using text-placements string,) "dummy" to turn this feature off. +* * * + +##### text-placements `string` + + + +Default Value: + + +If "placement-type" is set to "simple", use this "POSITIONS,[SIZES]" string. See TextSymbolizer docs for format. +* * * + +##### text-transform `keyword` +`none``uppercase``lowercase``capitalize` + + +Default Value: none + + +Transform the case of the characters +* * * + +##### text-horizontal-alignment `keyword` +`left``middle``right``auto` + + +Default Value: middle + + +The text's horizontal alignment from its centerpoint +* * * + +##### text-align `keyword` +`left``right``center` + + +Default Value: center + + +Set the text alignment. +* * * + + +## building + +##### building-fill `color` + + + +Default Value: #FFFFFF + + +The color of the buildings walls. +* * * + +##### building-fill-opacity `float` + + + +Default Value: 1 + + +The opacity of the building as a whole, including all walls. +* * * + +##### building-height `float` + + + +Default Value: 0 + + +The height of the building in pixels. +* * * + + + + +### Values + +Below is a list of values and an explanation of any expression that can be applied to properties in CartCSS. + +### Color + +CartoCSS accepts a variety of syntaxes for colors - HTML-style hex values, rgb, rgba, hsl, hsla, husl, and husla. It also supports the predefined HTML colors names, like `yellow` and `blue`. + +``` css +#line { +line-color: #ff0; +line-color: #ffff00; +line-color: rgb(255, 255, 0); +line-color: rgba(255, 255, 0, 1); +line-color: hsl(100, 50%, 50%); +line-color: hsla(100, 50%, 50%, 1); +line-color: husl(100, 50%, 50%); // same values yield different color than HSL +line-color: husla(100, 50%, 50%, 1); +line-color: yellow; +} +``` + +Especially of note is the support for hsl and husl, which can be [easier to reason about than rgb()](http://mothereffinghsl.com/). Carto also includes several color operation functions [borrowed from less](http://lesscss.org/functions/#color-operations): + +``` css +// lighten and darken colors +lighten(#ace, 10%); +darken(#ace, 10%); + +// saturate and desaturate +saturate(#550000, 10%); +desaturate(#00ff00, 10%); + +// increase or decrease the opacity of a color +fadein(#fafafa, 10%); +fadeout(#fefefe, 14%); + +// spin rotates a color around the color wheel by degrees +spin(#ff00ff, 10); + +// mix generates a color in between two other colors. +mix(#fff, #000, 50%); + +// get color components +hue(#ff00ff); +saturation(#ff00ff); +lightness(#ff00ff); +alpha(hsla(100, 50%, 50%, 0.5)); +``` + +These functions all take arguments which can be color variables, literal colors, or the results of other functions operating on colors. All the above mentioned functions also come in +a `functionp`-variant (e.g. `lightenp`), which force a given color into perceptual color space. + +### Float + +Float is a fancy way of saying 'number'. In CartoCSS, you specify _just a number_ - unlike CSS, there are no units, but everything is specified in pixels. + +``` css +#line { +line-width: 2; +} +``` + +It's also possible to do simple math with number values: + +``` css +#line { +line-width: 4 / 2; // division +line-width: 4 + 2; // addition +line-width: 4 - 2; // subtraction +line-width: 4 * 2; // multiplication +line-width: 4 % 2; // modulus +} +``` + +### URI + +URI is a fancy way of saying URL. When an argument is a URI, you use the same kind of `url('place.png')` notation that you would with HTML. Quotes around the URL aren't required, but are highly recommended. URIs can be paths to places on your computer, or on the internet. + +```css +#markers { +marker-file: url('marker.png'); +} +``` + +### String + +A string is basically just text. In the case of CartoCSS, you're going to put it in quotes. Strings can be anything, though pay attention to the cases of `text-name` and `shield-name` - they actually will refer to features, which you refer to by putting them in brackets, as seen in the example below. + +```css +#labels { +text-name: "[MY_FIELD]"; +} +``` + +### Boolean + +Boolean means yes or no, so it accepts the values `true` or `false`. + +```css +#markers { +marker-allow-overlap:true; +} +``` + +### Expressions + +Expressions are statements that can include fields, numbers, and other types in a really flexible way. You have run into expressions before, in the realm of 'fields', where you'd specify `"[FIELD]"`, but expressions allow you to drop the quotes and also do quick addition, division, multiplication, and concatenation from within Carto syntax. + +```css +#buildings { +building-height: [HEIGHT_FIELD] * 10; +} +``` + +### Numbers +Numbers are comma-separated lists of one or more number in a specific order. They're used in line dash arrays, in which the numbers specify intervals of line, break, and line again. + +```css +#disputedboundary { +line-dasharray: 1, 4, 2; +} +``` + +### Percentages +In Carto, the percentage symbol, `%` universally means `value/100`. It's meant to be used with ratio-related properties, like opacity rules. + +_You should not use percentages as widths, heights, or other properties - unlike CSS, percentages are not relative to cascaded classes or page size, they're, as stated, simply the value divided by one hundred._ + +```css +#world { +// this syntax +polygon-opacity: 50%; + +// is equivalent to +polygon-opacity: 0.5; +} +``` + +### Functions + +Functions are comma-separated lists of one or more functions. For instance, transforms use the `functions` type to allow for transforms within Carto, which are optionally chainable. + +```css +#point { +point-transform: scale(2, 2); +} +``` diff --git a/docs/2.1.0.md b/docs/2.1.0.md new file mode 100644 index 0000000..3a72323 --- /dev/null +++ b/docs/2.1.0.md @@ -0,0 +1,1640 @@ +# Carto documentation + +The following is a list of properties provided in CartoCSS that you can apply to map elements. + +## All elements + +##### image-filters `functions` + +`agg-stack-blur``emboss``blur``gray``sobel``edge-detect``x-gradient``y-gradient``invert``sharpen` + +Default Value: none +_(no filters)_ + +A list of image filters. +* * * + +##### comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current layer on top of other layers)_ + +Composite operation. This defines how this layer should behave relative to layers atop or below it. +* * * + +##### opacity `float` + + + +Default Value: 1 +_(no separate buffer will be used and no alpha will be applied to the style after rendering)_ + +An alpha value for the style (which means an alpha applied to all features in separate buffer and then composited back to main buffer) +* * * + + +## map + +##### background-color `color` + + + +Default Value: none +_(transparent)_ + +Map Background color +* * * + +##### background-image `uri` + + + +Default Value: +_(transparent)_ + +An image that is repeated below all features on a map as a background. +* * * + +##### srs `string` + + + +Default Value: +proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs +_(The proj4 literal of EPSG:4326 is assumed to be the Map's spatial reference and all data from layers within this map will be plotted using this coordinate system. If any layers do not declare an srs value then they will be assumed to be in the same srs as the Map and not transformations will be needed to plot them in the Map's coordinate space)_ + +Map spatial reference (proj4 string) +* * * + +##### buffer-size `float` + + + +Default Value: 0 +_(No buffer will be used)_ + +Extra tolerance around the map (in pixels) used to ensure labels crossing tile boundaries are equally rendered in each tile (e.g. cut in each tile). Not intended to be used in combination with "avoid-edges". +* * * + +##### base `string` + + + +Default Value: +_(This base path defaults to an empty string meaning that any relative paths to files referenced in styles or layers will be interpreted relative to the application process.)_ + +Any relative paths used to reference files will be understood as relative to this directory path if the map is loaded from an in memory object rather than from the filesystem. If the map is loaded from the filesystem and this option is not provided it will be set to the directory of the stylesheet. +* * * + +##### font-directory `uri` + + + +Default Value: none +_(No map-specific fonts will be registered)_ + +Path to a directory which holds fonts which should be registered when the Map is loaded (in addition to any fonts that may be automatically registered). +* * * + + +## polygon + +##### polygon-fill `color` + + + +Default Value: rgba(128,128,128,1) +_(gray and fully opaque (alpha = 1), same as rgb(128,128,128))_ + +Fill color to assign to a polygon +* * * + +##### polygon-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The opacity of the polygon +* * * + +##### polygon-gamma `float` + + + +Default Value: 1 +_(fully antialiased)_ +Range: 0-1 +Level of antialiasing of polygon edges +* * * + +##### polygon-gamma-method `keyword` +`power``linear``none``threshold``multiply` + + +Default Value: power +_(pow(x,gamma) is used to calculate pixel gamma, which produces slightly smoother line and polygon antialiasing than the 'linear' method, while other methods are usually only used to disable AA)_ + +An Antigrain Geometry specific rendering hint to control the quality of antialiasing. Under the hood in Mapnik this method is used in combination with the 'gamma' value (which defaults to 1). The methods are in the AGG source at https://github.com/mapnik/mapnik/blob/master/deps/agg/include/agg_gamma_functions.h +* * * + +##### polygon-clip `boolean` + + + +Default Value: true +_(geometry will be clipped to map bounds before rendering)_ + +geometries are clipped to map bounds by default for best rendering performance. In some cases users may wish to disable this to avoid rendering artifacts. +* * * + +##### polygon-smooth `float` + + + +Default Value: 0 +_(no smoothing)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### polygon-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(geometry will not be transformed)_ + +Allows transformation functions to be applied to the geometry. +* * * + +##### polygon-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## line + +##### line-color `color` + + + +Default Value: rgba(0,0,0,1) +_(black and fully opaque (alpha = 1), same as rgb(0,0,0))_ + +The color of a drawn line +* * * + +##### line-width `float` + + + +Default Value: 1 + + +The width of a line in pixels +* * * + +##### line-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The opacity of a line +* * * + +##### line-join `keyword` +`miter``round``bevel` + + +Default Value: miter + + +The behavior of lines when joining +* * * + +##### line-cap `keyword` +`butt``round``square` + + +Default Value: butt + + +The display of line endings +* * * + +##### line-gamma `float` + + + +Default Value: 1 +_(fully antialiased)_ +Range: 0-1 +Level of antialiasing of stroke line +* * * + +##### line-gamma-method `keyword` +`power``linear``none``threshold``multiply` + + +Default Value: power +_(pow(x,gamma) is used to calculate pixel gamma, which produces slightly smoother line and polygon antialiasing than the 'linear' method, while other methods are usually only used to disable AA)_ + +An Antigrain Geometry specific rendering hint to control the quality of antialiasing. Under the hood in Mapnik this method is used in combination with the 'gamma' value (which defaults to 1). The methods are in the AGG source at https://github.com/mapnik/mapnik/blob/master/deps/agg/include/agg_gamma_functions.h +* * * + +##### line-dasharray `numbers` + + + +Default Value: none +_(solid line)_ + +A pair of length values [a,b], where (a) is the dash length and (b) is the gap length respectively. More than two values are supported for more complex patterns. +* * * + +##### line-dash-offset `numbers` + + + +Default Value: none +_(solid line)_ + +valid parameter but not currently used in renderers (only exists for experimental svg support in Mapnik which is not yet enabled) +* * * + +##### line-miterlimit `float` + + + +Default Value: 4 +_(Will auto-convert miters to bevel line joins when theta is less than 29 degrees as per the SVG spec: 'miterLength / stroke-width = 1 / sin ( theta / 2 )')_ + +The limit on the ratio of the miter length to the stroke-width. Used to automatically convert miter joins to bevel joins for sharp angles to avoid the miter extending beyond the thickness of the stroking path. Normally will not need to be set, but a larger value can sometimes help avoid jaggy artifacts. +* * * + +##### line-clip `boolean` + + + +Default Value: true +_(geometry will be clipped to map bounds before rendering)_ + +geometries are clipped to map bounds by default for best rendering performance. In some cases users may wish to disable this to avoid rendering artifacts. +* * * + +##### line-smooth `float` + + + +Default Value: 0 +_(no smoothing)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### line-offset `float` + + + +Default Value: 0 +_(no offset)_ + +Offsets a line a number of pixels parallel to its actual path. Postive values move the line left, negative values move it right (relative to the directionality of the line). +* * * + +##### line-rasterizer `keyword` +`full``fast` + + +Default Value: full + + +Exposes an alternate AGG rendering method that sacrifices some accuracy for speed. +* * * + +##### line-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(geometry will not be transformed)_ + +Allows transformation functions to be applied to the geometry. +* * * + +##### line-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## markers + +##### marker-file `uri` + + + +Default Value: +_(An ellipse or circle, if width equals height)_ + +An SVG file that this marker shows at each placement. If no file is given, the marker will show an ellipse. +* * * + +##### marker-opacity `float` + + + +Default Value: 1 +_(The stroke-opacity and fill-opacity will be used)_ + +The overall opacity of the marker, if set, overrides both the opacity of both the fill and stroke +* * * + +##### marker-fill-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The fill opacity of the marker +* * * + +##### marker-line-color `color` + + + +Default Value: black + + +The color of the stroke around a marker shape. +* * * + +##### marker-line-width `float` + + + +Default Value: 0.5 + + +The width of the stroke around a marker shape, in pixels. This is positioned on the boundary, so high values can cover the area itself. +* * * + +##### marker-line-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The opacity of a line +* * * + +##### marker-placement `keyword` +`point``line``interior` + + +Default Value: point +_(Place markers at the center point (centroid) of the geometry)_ + +Attempt to place markers on a point, in the center of a polygon, or if markers-placement:line, then multiple times along a line. 'interior' placement can be used to ensure that points placed on polygons are forced to be inside the polygon interior +* * * + +##### marker-type `keyword` +`arrow``ellipse` + + +Default Value: ellipse + + +The default marker-type. If a SVG file is not given as the marker-file parameter, the renderer provides either an arrow or an ellipse (a circle if height is equal to width) +* * * + +##### marker-width `float` + + + +Default Value: 10 + + +The width of the marker, if using one of the default types. +* * * + +##### marker-height `float` + + + +Default Value: 10 + + +The height of the marker, if using one of the default types. +* * * + +##### marker-fill `color` + + + +Default Value: blue + + +The color of the area of the marker. +* * * + +##### marker-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow makers to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping markers are shown or hidden. +* * * + +##### marker-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache)_ + +value to control whether the placement of the feature will prevent the placement of other features +* * * + +##### marker-spacing `float` + + + +Default Value: 100 + + +Space between repeated labels +* * * + +##### marker-max-error `float` + + + +Default Value: 0.2 + + +The maximum difference between actual marker placement and the marker-spacing parameter. Setting a high value can allow the renderer to try to resolve placement conflicts with other symbolizers. +* * * + +##### marker-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: +_(No transformation)_ + +SVG transformation definition +* * * + +##### marker-clip `boolean` + + + +Default Value: true +_(geometry will be clipped to map bounds before rendering)_ + +geometries are clipped to map bounds by default for best rendering performance. In some cases users may wish to disable this to avoid rendering artifacts. +* * * + +##### marker-smooth `float` + + + +Default Value: 0 +_(no smoothing)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### marker-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(geometry will not be transformed)_ + +Allows transformation functions to be applied to the geometry. +* * * + +##### marker-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## shield + +##### shield-name `string` + + + +Default Value: + + +Value to use for a shield"s text label. Data columns are specified using brackets like [column_name] +* * * + +##### shield-file `uri` + + + +Default Value: none + + +Image file to render behind the shield text +* * * + +##### shield-face-name `string` + + + +Default Value: + + +Font name and style to use for the shield text +* * * + +##### shield-unlock-image `boolean` + + + +Default Value: false +_(text alignment relative to the shield image uses the center of the image as the anchor for text positioning.)_ + +This parameter should be set to true if you are trying to position text beside rather than on top of the shield image +* * * + +##### shield-size `float` + + + +Default Value: 10 + + +The size of the shield text in pixels +* * * + +##### shield-fill `color` + + + +Default Value: black + + +The color of the shield text +* * * + +##### shield-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point + + +How this shield should be placed. Point placement attempts to place it on top of points, line places along lines multiple times per feature, vertex places on the vertexes of polygons, and interior attempts to place inside of polygons. +* * * + +##### shield-avoid-edges `boolean` + + + +Default Value: false + + +Tell positioning algorithm to avoid labeling near intersection edges. +* * * + +##### shield-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow shields to overlap with other map elements already placed.)_ + +Control whether overlapping shields are shown or hidden. +* * * + +##### shield-min-distance `float` + + + +Default Value: 0 + + +Minimum distance to the next shield symbol, not necessarily the same shield. +* * * + +##### shield-spacing `float` + + + +Default Value: 0 + + +The spacing between repeated occurrences of the same shield on a line +* * * + +##### shield-min-padding `float` + + + +Default Value: 0 + + +Determines the minimum amount of padding that a shield gets relative to other shields +* * * + +##### shield-wrap-width `unsigned` + + + +Default Value: 0 + + +Length of a chunk of text in characters before wrapping text +* * * + +##### shield-wrap-before `boolean` + + + +Default Value: false + + +Wrap text before wrap-width is reached. If false, wrapped lines will be a bit longer than wrap-width. +* * * + +##### shield-wrap-character `string` + + + +Default Value: + + +Use this character instead of a space to wrap long names. +* * * + +##### shield-halo-fill `color` + + + +Default Value: #FFFFFF +_(white)_ + +Specifies the color of the halo around the text. +* * * + +##### shield-halo-radius `float` + + + +Default Value: 0 +_(no halo)_ + +Specify the radius of the halo in pixels +* * * + +##### shield-character-spacing `unsigned` + + + +Default Value: 0 + + +Horizontal spacing between characters (in pixels). Currently works for point placement only, not line placement. +* * * + +##### shield-line-spacing `unsigned` + + + +Default Value: 0 + + +Vertical spacing between lines of multiline labels (in pixels) +* * * + +##### shield-text-dx `float` + + + +Default Value: 0 + + +Displace text within shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right +* * * + +##### shield-text-dy `float` + + + +Default Value: 0 + + +Displace text within shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text down +* * * + +##### shield-dx `float` + + + +Default Value: 0 + + +Displace shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right +* * * + +##### shield-dy `float` + + + +Default Value: 0 + + +Displace shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text down +* * * + +##### shield-opacity `float` + + + +Default Value: 1 + + +(Default 1.0) - opacity of the image used for the shield +* * * + +##### shield-text-opacity `float` + + + +Default Value: 1 + + +(Default 1.0) - opacity of the text placed on top of the shield +* * * + +##### shield-horizontal-alignment `keyword` +`left``middle``right``auto` + + +Default Value: auto + + +The shield's horizontal alignment from its centerpoint +* * * + +##### shield-vertical-alignment `keyword` +`top``middle``bottom``auto` + + +Default Value: middle + + +The shield's vertical alignment from its centerpoint +* * * + +##### shield-text-transform `keyword` +`none``uppercase``lowercase``capitalize` + + +Default Value: none + + +Transform the case of the characters +* * * + +##### shield-justify-alignment `keyword` +`left``center``right``auto` + + +Default Value: auto + + +Define how text in a shield's label is justified +* * * + +##### shield-clip `boolean` + + + +Default Value: true +_(geometry will be clipped to map bounds before rendering)_ + +geometries are clipped to map bounds by default for best rendering performance. In some cases users may wish to disable this to avoid rendering artifacts. +* * * + +##### shield-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## line-pattern + +##### line-pattern-file `uri` + + + +Default Value: none + + +An image file to be repeated and warped along a line +* * * + +##### line-pattern-clip `boolean` + + + +Default Value: true +_(geometry will be clipped to map bounds before rendering)_ + +geometries are clipped to map bounds by default for best rendering performance. In some cases users may wish to disable this to avoid rendering artifacts. +* * * + +##### line-pattern-smooth `float` + + + +Default Value: 0 +_(no smoothing)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### line-pattern-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(geometry will not be transformed)_ + +Allows transformation functions to be applied to the geometry. +* * * + +##### line-pattern-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## polygon-pattern + +##### polygon-pattern-file `uri` + + + +Default Value: none + + +Image to use as a repeated pattern fill within a polygon +* * * + +##### polygon-pattern-alignment `keyword` +`local``global` + + +Default Value: local + + +Specify whether to align pattern fills to the layer or to the map. +* * * + +##### polygon-pattern-gamma `float` + + + +Default Value: 1 +_(fully antialiased)_ +Range: 0-1 +Level of antialiasing of polygon pattern edges +* * * + +##### polygon-pattern-opacity `float` + + + +Default Value: 1 +_(The image is rendered without modifications)_ + +(Default 1.0) - Apply an opacity level to the image used for the pattern +* * * + +##### polygon-pattern-clip `boolean` + + + +Default Value: true +_(geometry will be clipped to map bounds before rendering)_ + +geometries are clipped to map bounds by default for best rendering performance. In some cases users may wish to disable this to avoid rendering artifacts. +* * * + +##### polygon-pattern-smooth `float` + + + +Default Value: 0 +_(no smoothing)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### polygon-pattern-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(geometry will not be transformed)_ + +Allows transformation functions to be applied to the geometry. +* * * + +##### polygon-pattern-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## raster + +##### raster-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The opacity of the raster symbolizer on top of other symbolizers. +* * * + +##### raster-filter-factor `float` + + + +Default Value: -1 +_(Allow the datasource to choose appropriate downscaling.)_ + +This is used by the Raster or Gdal datasources to pre-downscale images using overviews. Higher numbers can sometimes cause much better scaled image output, at the cost of speed. +* * * + +##### raster-scaling `keyword` +`near``fast``bilinear``bilinear8``bicubic``spline16``spline36``hanning``hamming``hermite``kaiser``quadric``catrom``gaussian``bessel``mitchell``sinc``lanczos``blackman` + + +Default Value: near + + +The scaling algorithm used to making different resolution versions of this raster layer. Bilinear is a good compromise between speed and accuracy, while lanczos gives the highest quality. +* * * + +##### raster-mesh-size `unsigned` + + + +Default Value: 16 +_(Reprojection mesh will be 1/16 of the resolution of the source image)_ + +A reduced resolution mesh is used for raster reprojection, and the total image size is divided by the mesh-size to determine the quality of that mesh. Values for mesh-size larger than the default will result in faster reprojection but might lead to distortion. +* * * + +##### raster-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## point + +##### point-file `uri` + + + +Default Value: none + + +Image file to represent a point +* * * + +##### point-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow points to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping points are shown or hidden. +* * * + +##### point-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache)_ + +value to control whether the placement of the feature will prevent the placement of other features +* * * + +##### point-opacity `float` + + + +Default Value: 1 +_(Fully opaque)_ + +A value from 0 to 1 to control the opacity of the point +* * * + +##### point-placement `keyword` +`centroid``interior` + + +Default Value: centroid + + +How this point should be placed. Centroid calculates the geometric center of a polygon, which can be outside of it, while interior always places inside of a polygon. +* * * + +##### point-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: +_(No transformation)_ + +SVG transformation definition +* * * + +##### point-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## text + +##### text-name `string` + + + +Default Value: + + +Value to use for a text label. Data columns are specified using brackets like [column_name] +* * * + +##### text-face-name `string` + + + +Default Value: + + +Font name and style to render a label in +* * * + +##### text-size `float` + + + +Default Value: 10 + + +Text size in pixels +* * * + +##### text-ratio `unsigned` + + + +Default Value: 0 + + +Define the amount of text (of the total) present on successive lines when wrapping occurs +* * * + +##### text-wrap-width `unsigned` + + + +Default Value: 0 + + +Length of a chunk of text in characters before wrapping text +* * * + +##### text-wrap-before `boolean` + + + +Default Value: false + + +Wrap text before wrap-width is reached. If false, wrapped lines will be a bit longer than wrap-width. +* * * + +##### text-wrap-character `string` + + + +Default Value: + + +Use this character instead of a space to wrap long text. +* * * + +##### text-spacing `unsigned` + + + +Default Value: 0 + + +Distance between repeated text labels on a line (aka. label-spacing) +* * * + +##### text-character-spacing `float` + + + +Default Value: 0 + + +Horizontal spacing adjustment between characters in pixels +* * * + +##### text-line-spacing `unsigned` + + + +Default Value: 0 + + +Vertical spacing adjustment between lines in pixels +* * * + +##### text-label-position-tolerance `unsigned` + + + +Default Value: 0 + + +Allows the label to be displaced from its ideal position by a number of pixels (only works with placement:line) +* * * + +##### text-max-char-angle-delta `float` + + + +Default Value: 22.5 + + +The maximum angle change, in degrees, allowed between adjacent characters in a label. This value internally is converted to radians to the default is 22.5*math.pi/180.0. The higher the value the fewer labels will be placed around around sharp corners. +* * * + +##### text-fill `color` + + + +Default Value: #000000 + + +Specifies the color for the text +* * * + +##### text-opacity `float` + + + +Default Value: 1 +_(Fully opaque)_ + +A number from 0 to 1 specifying the opacity for the text +* * * + +##### text-halo-fill `color` + + + +Default Value: #FFFFFF +_(white)_ + +Specifies the color of the halo around the text. +* * * + +##### text-halo-radius `float` + + + +Default Value: 0 +_(no halo)_ + +Specify the radius of the halo in pixels +* * * + +##### text-dx `float` + + + +Default Value: 0 + + +Displace text by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right +* * * + +##### text-dy `float` + + + +Default Value: 0 + + +Displace text by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text down +* * * + +##### text-vertical-alignment `keyword` +`top``middle``bottom``auto` + + +Default Value: auto +_(Default affected by value of dy; "bottom" for dy>0, "top" for dy<0.)_ + +Position of label relative to point position. +* * * + +##### text-avoid-edges `boolean` + + + +Default Value: false + + +Tell positioning algorithm to avoid labeling near intersection edges. +* * * + +##### text-min-distance `float` + + + +Default Value: 0 + + +Minimum permitted distance to the next text symbolizer. +* * * + +##### text-min-padding `float` + + + +Default Value: 0 + + +Determines the minimum amount of padding that a text symbolizer gets relative to other text +* * * + +##### text-min-path-length `float` + + + +Default Value: 0 +_(place labels on all paths)_ + +Place labels only on paths longer than this value. +* * * + +##### text-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow text to overlap with other text - overlapping markers will not be shown.)_ + +Control whether overlapping text is shown or hidden. +* * * + +##### text-orientation `float` + + + +Default Value: 0 + + +Rotate the text. +* * * + +##### text-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point + + +Control the style of placement of a point versus the geometry it is attached to. +* * * + +##### text-placement-type `keyword` +`dummy``simple``list` + + +Default Value: dummy + + +Re-position and/or re-size text to avoid overlaps. "simple" for basic algorithm (using text-placements string,) "dummy" to turn this feature off. +* * * + +##### text-placements `string` + + + +Default Value: + + +If "placement-type" is set to "simple", use this "POSITIONS,[SIZES]" string. An example is `text-placements: "E,NE,SE,W,NW,SW";` +* * * + +##### text-transform `keyword` +`none``uppercase``lowercase``capitalize` + + +Default Value: none + + +Transform the case of the characters +* * * + +##### text-horizontal-alignment `keyword` +`left``middle``right``auto` + + +Default Value: auto + + +The text's horizontal alignment from its centerpoint +* * * + +##### text-align `keyword` +`left``right``center``auto` + + +Default Value: auto +_(Auto alignment means that text will be centered by default except when using the `placement-type` parameter - in that case either right or left justification will be used automatically depending on where the text could be fit given the `text-placements` directives)_ + +Define how text is justified +* * * + +##### text-clip `boolean` + + + +Default Value: true +_(geometry will be clipped to map bounds before rendering)_ + +geometries are clipped to map bounds by default for best rendering performance. In some cases users may wish to disable this to avoid rendering artifacts. +* * * + +##### text-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## building + +##### building-fill `color` + + + +Default Value: #FFFFFF + + +The color of the buildings walls. +* * * + +##### building-fill-opacity `float` + + + +Default Value: 1 + + +The opacity of the building as a whole, including all walls. +* * * + +##### building-height `float` + + + +Default Value: 0 + + +The height of the building in pixels. +* * * + + + + +### Values + +Below is a list of values and an explanation of any expression that can be applied to properties in CartCSS. + +### Color + +CartoCSS accepts a variety of syntaxes for colors - HTML-style hex values, rgb, rgba, hsl, hsla, husl, and husla. It also supports the predefined HTML colors names, like `yellow` and `blue`. + +``` css +#line { +line-color: #ff0; +line-color: #ffff00; +line-color: rgb(255, 255, 0); +line-color: rgba(255, 255, 0, 1); +line-color: hsl(100, 50%, 50%); +line-color: hsla(100, 50%, 50%, 1); +line-color: husl(100, 50%, 50%); // same values yield different color than HSL +line-color: husla(100, 50%, 50%, 1); +line-color: yellow; +} +``` + +Especially of note is the support for hsl and husl, which can be [easier to reason about than rgb()](http://mothereffinghsl.com/). Carto also includes several color operation functions [borrowed from less](http://lesscss.org/functions/#color-operations): + +``` css +// lighten and darken colors +lighten(#ace, 10%); +darken(#ace, 10%); + +// saturate and desaturate +saturate(#550000, 10%); +desaturate(#00ff00, 10%); + +// increase or decrease the opacity of a color +fadein(#fafafa, 10%); +fadeout(#fefefe, 14%); + +// spin rotates a color around the color wheel by degrees +spin(#ff00ff, 10); + +// mix generates a color in between two other colors. +mix(#fff, #000, 50%); + +// get color components +hue(#ff00ff); +saturation(#ff00ff); +lightness(#ff00ff); +alpha(hsla(100, 50%, 50%, 0.5)); +``` + +These functions all take arguments which can be color variables, literal colors, or the results of other functions operating on colors. All the above mentioned functions also come in +a `functionp`-variant (e.g. `lightenp`), which force a given color into perceptual color space. + +### Float + +Float is a fancy way of saying 'number'. In CartoCSS, you specify _just a number_ - unlike CSS, there are no units, but everything is specified in pixels. + +``` css +#line { +line-width: 2; +} +``` + +It's also possible to do simple math with number values: + +``` css +#line { +line-width: 4 / 2; // division +line-width: 4 + 2; // addition +line-width: 4 - 2; // subtraction +line-width: 4 * 2; // multiplication +line-width: 4 % 2; // modulus +} +``` + +### URI + +URI is a fancy way of saying URL. When an argument is a URI, you use the same kind of `url('place.png')` notation that you would with HTML. Quotes around the URL aren't required, but are highly recommended. URIs can be paths to places on your computer, or on the internet. + +```css +#markers { +marker-file: url('marker.png'); +} +``` + +### String + +A string is basically just text. In the case of CartoCSS, you're going to put it in quotes. Strings can be anything, though pay attention to the cases of `text-name` and `shield-name` - they actually will refer to features, which you refer to by putting them in brackets, as seen in the example below. + +```css +#labels { +text-name: "[MY_FIELD]"; +} +``` + +### Boolean + +Boolean means yes or no, so it accepts the values `true` or `false`. + +```css +#markers { +marker-allow-overlap:true; +} +``` + +### Expressions + +Expressions are statements that can include fields, numbers, and other types in a really flexible way. You have run into expressions before, in the realm of 'fields', where you'd specify `"[FIELD]"`, but expressions allow you to drop the quotes and also do quick addition, division, multiplication, and concatenation from within Carto syntax. + +```css +#buildings { +building-height: [HEIGHT_FIELD] * 10; +} +``` + +### Numbers +Numbers are comma-separated lists of one or more number in a specific order. They're used in line dash arrays, in which the numbers specify intervals of line, break, and line again. + +```css +#disputedboundary { +line-dasharray: 1, 4, 2; +} +``` + +### Percentages +In Carto, the percentage symbol, `%` universally means `value/100`. It's meant to be used with ratio-related properties, like opacity rules. + +_You should not use percentages as widths, heights, or other properties - unlike CSS, percentages are not relative to cascaded classes or page size, they're, as stated, simply the value divided by one hundred._ + +```css +#world { +// this syntax +polygon-opacity: 50%; + +// is equivalent to +polygon-opacity: 0.5; +} +``` + +### Functions + +Functions are comma-separated lists of one or more functions. For instance, transforms use the `functions` type to allow for transforms within Carto, which are optionally chainable. + +```css +#point { +point-transform: scale(2, 2); +} +``` diff --git a/docs/2.1.1.md b/docs/2.1.1.md new file mode 100644 index 0000000..821e216 --- /dev/null +++ b/docs/2.1.1.md @@ -0,0 +1,1650 @@ +# Carto documentation + +The following is a list of properties provided in CartoCSS that you can apply to map elements. + +## All elements + +##### image-filters `functions` + +`agg-stack-blur``emboss``blur``gray``sobel``edge-detect``x-gradient``y-gradient``invert``sharpen` + +Default Value: none +_(no filters)_ + +A list of image filters. +* * * + +##### comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current layer on top of other layers)_ + +Composite operation. This defines how this layer should behave relative to layers atop or below it. +* * * + +##### opacity `float` + + + +Default Value: 1 +_(no separate buffer will be used and no alpha will be applied to the style after rendering)_ + +An alpha value for the style (which means an alpha applied to all features in separate buffer and then composited back to main buffer) +* * * + + +## map + +##### background-color `color` + + + +Default Value: none +_(transparent)_ + +Map Background color +* * * + +##### background-image `uri` + + + +Default Value: +_(transparent)_ + +An image that is repeated below all features on a map as a background. +* * * + +##### srs `string` + + + +Default Value: +proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs +_(The proj4 literal of EPSG:4326 is assumed to be the Map's spatial reference and all data from layers within this map will be plotted using this coordinate system. If any layers do not declare an srs value then they will be assumed to be in the same srs as the Map and not transformations will be needed to plot them in the Map's coordinate space)_ + +Map spatial reference (proj4 string) +* * * + +##### buffer-size `float` + + + +Default Value: 0 +_(No buffer will be used)_ + +Extra tolerance around the map (in pixels) used to ensure labels crossing tile boundaries are equally rendered in each tile (e.g. cut in each tile). Not intended to be used in combination with "avoid-edges". +* * * + +##### base `string` + + + +Default Value: +_(This base path defaults to an empty string meaning that any relative paths to files referenced in styles or layers will be interpreted relative to the application process.)_ + +Any relative paths used to reference files will be understood as relative to this directory path if the map is loaded from an in memory object rather than from the filesystem. If the map is loaded from the filesystem and this option is not provided it will be set to the directory of the stylesheet. +* * * + +##### font-directory `uri` + + + +Default Value: none +_(No map-specific fonts will be registered)_ + +Path to a directory which holds fonts which should be registered when the Map is loaded (in addition to any fonts that may be automatically registered). +* * * + + +## polygon + +##### polygon-fill `color` + + + +Default Value: rgba(128,128,128,1) +_(gray and fully opaque (alpha = 1), same as rgb(128,128,128))_ + +Fill color to assign to a polygon +* * * + +##### polygon-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The opacity of the polygon +* * * + +##### polygon-gamma `float` + + + +Default Value: 1 +_(fully antialiased)_ +Range: 0-1 +Level of antialiasing of polygon edges +* * * + +##### polygon-gamma-method `keyword` +`power``linear``none``threshold``multiply` + + +Default Value: power +_(pow(x,gamma) is used to calculate pixel gamma, which produces slightly smoother line and polygon antialiasing than the 'linear' method, while other methods are usually only used to disable AA)_ + +An Antigrain Geometry specific rendering hint to control the quality of antialiasing. Under the hood in Mapnik this method is used in combination with the 'gamma' value (which defaults to 1). The methods are in the AGG source at https://github.com/mapnik/mapnik/blob/master/deps/agg/include/agg_gamma_functions.h +* * * + +##### polygon-clip `boolean` + + + +Default Value: true +_(geometry will be clipped to map bounds before rendering)_ + +geometries are clipped to map bounds by default for best rendering performance. In some cases users may wish to disable this to avoid rendering artifacts. +* * * + +##### polygon-smooth `float` + + + +Default Value: 0 +_(no smoothing)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### polygon-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(geometry will not be transformed)_ + +Allows transformation functions to be applied to the geometry. +* * * + +##### polygon-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## line + +##### line-color `color` + + + +Default Value: rgba(0,0,0,1) +_(black and fully opaque (alpha = 1), same as rgb(0,0,0))_ + +The color of a drawn line +* * * + +##### line-width `float` + + + +Default Value: 1 + + +The width of a line in pixels +* * * + +##### line-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The opacity of a line +* * * + +##### line-join `keyword` +`miter``round``bevel` + + +Default Value: miter + + +The behavior of lines when joining +* * * + +##### line-cap `keyword` +`butt``round``square` + + +Default Value: butt + + +The display of line endings +* * * + +##### line-gamma `float` + + + +Default Value: 1 +_(fully antialiased)_ +Range: 0-1 +Level of antialiasing of stroke line +* * * + +##### line-gamma-method `keyword` +`power``linear``none``threshold``multiply` + + +Default Value: power +_(pow(x,gamma) is used to calculate pixel gamma, which produces slightly smoother line and polygon antialiasing than the 'linear' method, while other methods are usually only used to disable AA)_ + +An Antigrain Geometry specific rendering hint to control the quality of antialiasing. Under the hood in Mapnik this method is used in combination with the 'gamma' value (which defaults to 1). The methods are in the AGG source at https://github.com/mapnik/mapnik/blob/master/deps/agg/include/agg_gamma_functions.h +* * * + +##### line-dasharray `numbers` + + + +Default Value: none +_(solid line)_ + +A pair of length values [a,b], where (a) is the dash length and (b) is the gap length respectively. More than two values are supported for more complex patterns. +* * * + +##### line-dash-offset `numbers` + + + +Default Value: none +_(solid line)_ + +valid parameter but not currently used in renderers (only exists for experimental svg support in Mapnik which is not yet enabled) +* * * + +##### line-miterlimit `float` + + + +Default Value: 4 +_(Will auto-convert miters to bevel line joins when theta is less than 29 degrees as per the SVG spec: 'miterLength / stroke-width = 1 / sin ( theta / 2 )')_ + +The limit on the ratio of the miter length to the stroke-width. Used to automatically convert miter joins to bevel joins for sharp angles to avoid the miter extending beyond the thickness of the stroking path. Normally will not need to be set, but a larger value can sometimes help avoid jaggy artifacts. +* * * + +##### line-clip `boolean` + + + +Default Value: true +_(geometry will be clipped to map bounds before rendering)_ + +geometries are clipped to map bounds by default for best rendering performance. In some cases users may wish to disable this to avoid rendering artifacts. +* * * + +##### line-smooth `float` + + + +Default Value: 0 +_(no smoothing)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### line-offset `float` + + + +Default Value: 0 +_(no offset)_ + +Offsets a line a number of pixels parallel to its actual path. Postive values move the line left, negative values move it right (relative to the directionality of the line). +* * * + +##### line-rasterizer `keyword` +`full``fast` + + +Default Value: full + + +Exposes an alternate AGG rendering method that sacrifices some accuracy for speed. +* * * + +##### line-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(geometry will not be transformed)_ + +Allows transformation functions to be applied to the geometry. +* * * + +##### line-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## markers + +##### marker-file `uri` + + + +Default Value: +_(An ellipse or circle, if width equals height)_ + +An SVG file that this marker shows at each placement. If no file is given, the marker will show an ellipse. +* * * + +##### marker-opacity `float` + + + +Default Value: 1 +_(The stroke-opacity and fill-opacity will be used)_ + +The overall opacity of the marker, if set, overrides both the opacity of both the fill and stroke +* * * + +##### marker-fill-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The fill opacity of the marker +* * * + +##### marker-line-color `color` + + + +Default Value: black + + +The color of the stroke around a marker shape. +* * * + +##### marker-line-width `float` + + + +Default Value: 0.5 + + +The width of the stroke around a marker shape, in pixels. This is positioned on the boundary, so high values can cover the area itself. +* * * + +##### marker-line-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The opacity of a line +* * * + +##### marker-placement `keyword` +`point``line``interior` + + +Default Value: point +_(Place markers at the center point (centroid) of the geometry)_ + +Attempt to place markers on a point, in the center of a polygon, or if markers-placement:line, then multiple times along a line. 'interior' placement can be used to ensure that points placed on polygons are forced to be inside the polygon interior +* * * + +##### marker-multi-policy `keyword` +`each``whole``largest` + + +Default Value: each +_(If a feature contains multiple geometries and the placement type is either point or interior then a marker will be rendered for each)_ + +A special setting to allow the user to control rendering behavior for 'multi-geometries' (when a feature contains multiple geometries). This setting does not apply to markers placed along lines. The 'each' policy is default and means all geometries will get a marker. The 'whole' policy means that the aggregate centroid between all geometries will be used. The 'largest' policy means that only the largest (by bounding box areas) feature will get a rendered marker (this is how text labeling behaves by default). +* * * + +##### marker-type `keyword` +`arrow``ellipse` + + +Default Value: ellipse + + +The default marker-type. If a SVG file is not given as the marker-file parameter, the renderer provides either an arrow or an ellipse (a circle if height is equal to width) +* * * + +##### marker-width `expression` + + + +Default Value: 10 + + +The width of the marker, if using one of the default types. +* * * + +##### marker-height `expression` + + + +Default Value: 10 + + +The height of the marker, if using one of the default types. +* * * + +##### marker-fill `color` + + + +Default Value: blue + + +The color of the area of the marker. +* * * + +##### marker-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow makers to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping markers are shown or hidden. +* * * + +##### marker-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache)_ + +value to control whether the placement of the feature will prevent the placement of other features +* * * + +##### marker-spacing `float` + + + +Default Value: 100 + + +Space between repeated labels +* * * + +##### marker-max-error `float` + + + +Default Value: 0.2 + + +The maximum difference between actual marker placement and the marker-spacing parameter. Setting a high value can allow the renderer to try to resolve placement conflicts with other symbolizers. +* * * + +##### marker-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: +_(No transformation)_ + +SVG transformation definition +* * * + +##### marker-clip `boolean` + + + +Default Value: true +_(geometry will be clipped to map bounds before rendering)_ + +geometries are clipped to map bounds by default for best rendering performance. In some cases users may wish to disable this to avoid rendering artifacts. +* * * + +##### marker-smooth `float` + + + +Default Value: 0 +_(no smoothing)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### marker-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(geometry will not be transformed)_ + +Allows transformation functions to be applied to the geometry. +* * * + +##### marker-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## shield + +##### shield-name `expression` + + + +Default Value: + + +Value to use for a shield"s text label. Data columns are specified using brackets like [column_name] +* * * + +##### shield-file `uri` + + + +Default Value: none + + +Image file to render behind the shield text +* * * + +##### shield-face-name `string` + + + +Default Value: + + +Font name and style to use for the shield text +* * * + +##### shield-unlock-image `boolean` + + + +Default Value: false +_(text alignment relative to the shield image uses the center of the image as the anchor for text positioning.)_ + +This parameter should be set to true if you are trying to position text beside rather than on top of the shield image +* * * + +##### shield-size `float` + + + +Default Value: 10 + + +The size of the shield text in pixels +* * * + +##### shield-fill `color` + + + +Default Value: black + + +The color of the shield text +* * * + +##### shield-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point + + +How this shield should be placed. Point placement attempts to place it on top of points, line places along lines multiple times per feature, vertex places on the vertexes of polygons, and interior attempts to place inside of polygons. +* * * + +##### shield-avoid-edges `boolean` + + + +Default Value: false + + +Tell positioning algorithm to avoid labeling near intersection edges. +* * * + +##### shield-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow shields to overlap with other map elements already placed.)_ + +Control whether overlapping shields are shown or hidden. +* * * + +##### shield-min-distance `float` + + + +Default Value: 0 + + +Minimum distance to the next shield symbol, not necessarily the same shield. +* * * + +##### shield-spacing `float` + + + +Default Value: 0 + + +The spacing between repeated occurrences of the same shield on a line +* * * + +##### shield-min-padding `float` + + + +Default Value: 0 + + +Determines the minimum amount of padding that a shield gets relative to other shields +* * * + +##### shield-wrap-width `unsigned` + + + +Default Value: 0 + + +Length of a chunk of text in characters before wrapping text +* * * + +##### shield-wrap-before `boolean` + + + +Default Value: false + + +Wrap text before wrap-width is reached. If false, wrapped lines will be a bit longer than wrap-width. +* * * + +##### shield-wrap-character `string` + + + +Default Value: + + +Use this character instead of a space to wrap long names. +* * * + +##### shield-halo-fill `color` + + + +Default Value: #FFFFFF +_(white)_ + +Specifies the color of the halo around the text. +* * * + +##### shield-halo-radius `float` + + + +Default Value: 0 +_(no halo)_ + +Specify the radius of the halo in pixels +* * * + +##### shield-character-spacing `unsigned` + + + +Default Value: 0 + + +Horizontal spacing between characters (in pixels). Currently works for point placement only, not line placement. +* * * + +##### shield-line-spacing `unsigned` + + + +Default Value: 0 + + +Vertical spacing between lines of multiline labels (in pixels) +* * * + +##### shield-text-dx `float` + + + +Default Value: 0 + + +Displace text within shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right +* * * + +##### shield-text-dy `float` + + + +Default Value: 0 + + +Displace text within shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text down +* * * + +##### shield-dx `float` + + + +Default Value: 0 + + +Displace shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right +* * * + +##### shield-dy `float` + + + +Default Value: 0 + + +Displace shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text down +* * * + +##### shield-opacity `float` + + + +Default Value: 1 + + +(Default 1.0) - opacity of the image used for the shield +* * * + +##### shield-text-opacity `float` + + + +Default Value: 1 + + +(Default 1.0) - opacity of the text placed on top of the shield +* * * + +##### shield-horizontal-alignment `keyword` +`left``middle``right``auto` + + +Default Value: auto + + +The shield's horizontal alignment from its centerpoint +* * * + +##### shield-vertical-alignment `keyword` +`top``middle``bottom``auto` + + +Default Value: middle + + +The shield's vertical alignment from its centerpoint +* * * + +##### shield-text-transform `keyword` +`none``uppercase``lowercase``capitalize` + + +Default Value: none + + +Transform the case of the characters +* * * + +##### shield-justify-alignment `keyword` +`left``center``right``auto` + + +Default Value: auto + + +Define how text in a shield's label is justified +* * * + +##### shield-clip `boolean` + + + +Default Value: true +_(geometry will be clipped to map bounds before rendering)_ + +geometries are clipped to map bounds by default for best rendering performance. In some cases users may wish to disable this to avoid rendering artifacts. +* * * + +##### shield-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## line-pattern + +##### line-pattern-file `uri` + + + +Default Value: none + + +An image file to be repeated and warped along a line +* * * + +##### line-pattern-clip `boolean` + + + +Default Value: true +_(geometry will be clipped to map bounds before rendering)_ + +geometries are clipped to map bounds by default for best rendering performance. In some cases users may wish to disable this to avoid rendering artifacts. +* * * + +##### line-pattern-smooth `float` + + + +Default Value: 0 +_(no smoothing)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### line-pattern-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(geometry will not be transformed)_ + +Allows transformation functions to be applied to the geometry. +* * * + +##### line-pattern-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## polygon-pattern + +##### polygon-pattern-file `uri` + + + +Default Value: none + + +Image to use as a repeated pattern fill within a polygon +* * * + +##### polygon-pattern-alignment `keyword` +`local``global` + + +Default Value: local + + +Specify whether to align pattern fills to the layer or to the map. +* * * + +##### polygon-pattern-gamma `float` + + + +Default Value: 1 +_(fully antialiased)_ +Range: 0-1 +Level of antialiasing of polygon pattern edges +* * * + +##### polygon-pattern-opacity `float` + + + +Default Value: 1 +_(The image is rendered without modifications)_ + +(Default 1.0) - Apply an opacity level to the image used for the pattern +* * * + +##### polygon-pattern-clip `boolean` + + + +Default Value: true +_(geometry will be clipped to map bounds before rendering)_ + +geometries are clipped to map bounds by default for best rendering performance. In some cases users may wish to disable this to avoid rendering artifacts. +* * * + +##### polygon-pattern-smooth `float` + + + +Default Value: 0 +_(no smoothing)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### polygon-pattern-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(geometry will not be transformed)_ + +Allows transformation functions to be applied to the geometry. +* * * + +##### polygon-pattern-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## raster + +##### raster-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The opacity of the raster symbolizer on top of other symbolizers. +* * * + +##### raster-filter-factor `float` + + + +Default Value: -1 +_(Allow the datasource to choose appropriate downscaling.)_ + +This is used by the Raster or Gdal datasources to pre-downscale images using overviews. Higher numbers can sometimes cause much better scaled image output, at the cost of speed. +* * * + +##### raster-scaling `keyword` +`near``fast``bilinear``bilinear8``bicubic``spline16``spline36``hanning``hamming``hermite``kaiser``quadric``catrom``gaussian``bessel``mitchell``sinc``lanczos``blackman` + + +Default Value: near + + +The scaling algorithm used to making different resolution versions of this raster layer. Bilinear is a good compromise between speed and accuracy, while lanczos gives the highest quality. +* * * + +##### raster-mesh-size `unsigned` + + + +Default Value: 16 +_(Reprojection mesh will be 1/16 of the resolution of the source image)_ + +A reduced resolution mesh is used for raster reprojection, and the total image size is divided by the mesh-size to determine the quality of that mesh. Values for mesh-size larger than the default will result in faster reprojection but might lead to distortion. +* * * + +##### raster-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## point + +##### point-file `uri` + + + +Default Value: none + + +Image file to represent a point +* * * + +##### point-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow points to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping points are shown or hidden. +* * * + +##### point-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache)_ + +value to control whether the placement of the feature will prevent the placement of other features +* * * + +##### point-opacity `float` + + + +Default Value: 1 +_(Fully opaque)_ + +A value from 0 to 1 to control the opacity of the point +* * * + +##### point-placement `keyword` +`centroid``interior` + + +Default Value: centroid + + +How this point should be placed. Centroid calculates the geometric center of a polygon, which can be outside of it, while interior always places inside of a polygon. +* * * + +##### point-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: +_(No transformation)_ + +SVG transformation definition +* * * + +##### point-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## text + +##### text-name `expression` + + + +Default Value: + + +Value to use for a text label. Data columns are specified using brackets like [column_name] +* * * + +##### text-face-name `string` + + + +Default Value: + + +Font name and style to render a label in +* * * + +##### text-size `float` + + + +Default Value: 10 + + +Text size in pixels +* * * + +##### text-ratio `unsigned` + + + +Default Value: 0 + + +Define the amount of text (of the total) present on successive lines when wrapping occurs +* * * + +##### text-wrap-width `unsigned` + + + +Default Value: 0 + + +Length of a chunk of text in characters before wrapping text +* * * + +##### text-wrap-before `boolean` + + + +Default Value: false + + +Wrap text before wrap-width is reached. If false, wrapped lines will be a bit longer than wrap-width. +* * * + +##### text-wrap-character `string` + + + +Default Value: + + +Use this character instead of a space to wrap long text. +* * * + +##### text-spacing `unsigned` + + + +Default Value: 0 + + +Distance between repeated text labels on a line (aka. label-spacing) +* * * + +##### text-character-spacing `float` + + + +Default Value: 0 + + +Horizontal spacing adjustment between characters in pixels +* * * + +##### text-line-spacing `unsigned` + + + +Default Value: 0 + + +Vertical spacing adjustment between lines in pixels +* * * + +##### text-label-position-tolerance `unsigned` + + + +Default Value: 0 + + +Allows the label to be displaced from its ideal position by a number of pixels (only works with placement:line) +* * * + +##### text-max-char-angle-delta `float` + + + +Default Value: 22.5 + + +The maximum angle change, in degrees, allowed between adjacent characters in a label. This value internally is converted to radians to the default is 22.5*math.pi/180.0. The higher the value the fewer labels will be placed around around sharp corners. +* * * + +##### text-fill `color` + + + +Default Value: #000000 + + +Specifies the color for the text +* * * + +##### text-opacity `float` + + + +Default Value: 1 +_(Fully opaque)_ + +A number from 0 to 1 specifying the opacity for the text +* * * + +##### text-halo-fill `color` + + + +Default Value: #FFFFFF +_(white)_ + +Specifies the color of the halo around the text. +* * * + +##### text-halo-radius `float` + + + +Default Value: 0 +_(no halo)_ + +Specify the radius of the halo in pixels +* * * + +##### text-dx `float` + + + +Default Value: 0 + + +Displace text by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right +* * * + +##### text-dy `float` + + + +Default Value: 0 + + +Displace text by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text down +* * * + +##### text-vertical-alignment `keyword` +`top``middle``bottom``auto` + + +Default Value: auto +_(Default affected by value of dy; "bottom" for dy>0, "top" for dy<0.)_ + +Position of label relative to point position. +* * * + +##### text-avoid-edges `boolean` + + + +Default Value: false + + +Tell positioning algorithm to avoid labeling near intersection edges. +* * * + +##### text-min-distance `float` + + + +Default Value: 0 + + +Minimum permitted distance to the next text symbolizer. +* * * + +##### text-min-padding `float` + + + +Default Value: 0 + + +Determines the minimum amount of padding that a text symbolizer gets relative to other text +* * * + +##### text-min-path-length `float` + + + +Default Value: 0 +_(place labels on all paths)_ + +Place labels only on paths longer than this value. +* * * + +##### text-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow text to overlap with other text - overlapping markers will not be shown.)_ + +Control whether overlapping text is shown or hidden. +* * * + +##### text-orientation `expression` + + + +Default Value: 0 + + +Rotate the text. +* * * + +##### text-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point + + +Control the style of placement of a point versus the geometry it is attached to. +* * * + +##### text-placement-type `keyword` +`dummy``simple``list` + + +Default Value: dummy + + +Re-position and/or re-size text to avoid overlaps. "simple" for basic algorithm (using text-placements string,) "dummy" to turn this feature off. +* * * + +##### text-placements `string` + + + +Default Value: + + +If "placement-type" is set to "simple", use this "POSITIONS,[SIZES]" string. An example is `text-placements: "E,NE,SE,W,NW,SW";` +* * * + +##### text-transform `keyword` +`none``uppercase``lowercase``capitalize` + + +Default Value: none + + +Transform the case of the characters +* * * + +##### text-horizontal-alignment `keyword` +`left``middle``right``auto` + + +Default Value: auto + + +The text's horizontal alignment from its centerpoint +* * * + +##### text-align `keyword` +`left``right``center``auto` + + +Default Value: auto +_(Auto alignment means that text will be centered by default except when using the `placement-type` parameter - in that case either right or left justification will be used automatically depending on where the text could be fit given the `text-placements` directives)_ + +Define how text is justified +* * * + +##### text-clip `boolean` + + + +Default Value: true +_(geometry will be clipped to map bounds before rendering)_ + +geometries are clipped to map bounds by default for best rendering performance. In some cases users may wish to disable this to avoid rendering artifacts. +* * * + +##### text-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## building + +##### building-fill `color` + + + +Default Value: #FFFFFF + + +The color of the buildings walls. +* * * + +##### building-fill-opacity `float` + + + +Default Value: 1 + + +The opacity of the building as a whole, including all walls. +* * * + +##### building-height `expression` + + + +Default Value: 0 + + +The height of the building in pixels. +* * * + + + + +### Values + +Below is a list of values and an explanation of any expression that can be applied to properties in CartCSS. + +### Color + +CartoCSS accepts a variety of syntaxes for colors - HTML-style hex values, rgb, rgba, hsl, hsla, husl, and husla. It also supports the predefined HTML colors names, like `yellow` and `blue`. + +``` css +#line { +line-color: #ff0; +line-color: #ffff00; +line-color: rgb(255, 255, 0); +line-color: rgba(255, 255, 0, 1); +line-color: hsl(100, 50%, 50%); +line-color: hsla(100, 50%, 50%, 1); +line-color: husl(100, 50%, 50%); // same values yield different color than HSL +line-color: husla(100, 50%, 50%, 1); +line-color: yellow; +} +``` + +Especially of note is the support for hsl and husl, which can be [easier to reason about than rgb()](http://mothereffinghsl.com/). Carto also includes several color operation functions [borrowed from less](http://lesscss.org/functions/#color-operations): + +``` css +// lighten and darken colors +lighten(#ace, 10%); +darken(#ace, 10%); + +// saturate and desaturate +saturate(#550000, 10%); +desaturate(#00ff00, 10%); + +// increase or decrease the opacity of a color +fadein(#fafafa, 10%); +fadeout(#fefefe, 14%); + +// spin rotates a color around the color wheel by degrees +spin(#ff00ff, 10); + +// mix generates a color in between two other colors. +mix(#fff, #000, 50%); + +// get color components +hue(#ff00ff); +saturation(#ff00ff); +lightness(#ff00ff); +alpha(hsla(100, 50%, 50%, 0.5)); +``` + +These functions all take arguments which can be color variables, literal colors, or the results of other functions operating on colors. All the above mentioned functions also come in +a `functionp`-variant (e.g. `lightenp`), which force a given color into perceptual color space. + +### Float + +Float is a fancy way of saying 'number'. In CartoCSS, you specify _just a number_ - unlike CSS, there are no units, but everything is specified in pixels. + +``` css +#line { +line-width: 2; +} +``` + +It's also possible to do simple math with number values: + +``` css +#line { +line-width: 4 / 2; // division +line-width: 4 + 2; // addition +line-width: 4 - 2; // subtraction +line-width: 4 * 2; // multiplication +line-width: 4 % 2; // modulus +} +``` + +### URI + +URI is a fancy way of saying URL. When an argument is a URI, you use the same kind of `url('place.png')` notation that you would with HTML. Quotes around the URL aren't required, but are highly recommended. URIs can be paths to places on your computer, or on the internet. + +```css +#markers { +marker-file: url('marker.png'); +} +``` + +### String + +A string is basically just text. In the case of CartoCSS, you're going to put it in quotes. Strings can be anything, though pay attention to the cases of `text-name` and `shield-name` - they actually will refer to features, which you refer to by putting them in brackets, as seen in the example below. + +```css +#labels { +text-name: "[MY_FIELD]"; +} +``` + +### Boolean + +Boolean means yes or no, so it accepts the values `true` or `false`. + +```css +#markers { +marker-allow-overlap:true; +} +``` + +### Expressions + +Expressions are statements that can include fields, numbers, and other types in a really flexible way. You have run into expressions before, in the realm of 'fields', where you'd specify `"[FIELD]"`, but expressions allow you to drop the quotes and also do quick addition, division, multiplication, and concatenation from within Carto syntax. + +```css +#buildings { +building-height: [HEIGHT_FIELD] * 10; +} +``` + +### Numbers +Numbers are comma-separated lists of one or more number in a specific order. They're used in line dash arrays, in which the numbers specify intervals of line, break, and line again. + +```css +#disputedboundary { +line-dasharray: 1, 4, 2; +} +``` + +### Percentages +In Carto, the percentage symbol, `%` universally means `value/100`. It's meant to be used with ratio-related properties, like opacity rules. + +_You should not use percentages as widths, heights, or other properties - unlike CSS, percentages are not relative to cascaded classes or page size, they're, as stated, simply the value divided by one hundred._ + +```css +#world { +// this syntax +polygon-opacity: 50%; + +// is equivalent to +polygon-opacity: 0.5; +} +``` + +### Functions + +Functions are comma-separated lists of one or more functions. For instance, transforms use the `functions` type to allow for transforms within Carto, which are optionally chainable. + +```css +#point { +point-transform: scale(2, 2); +} +``` diff --git a/docs/2.2.0.md b/docs/2.2.0.md new file mode 100644 index 0000000..6182cf8 --- /dev/null +++ b/docs/2.2.0.md @@ -0,0 +1,1833 @@ +# Carto documentation + +The following is a list of properties provided in CartoCSS that you can apply to map elements. + +## All elements + +##### image-filters `functions` + +`agg-stack-blur``emboss``blur``gray``sobel``edge-detect``x-gradient``y-gradient``invert``sharpen``colorize-alpha` + +Default Value: none +_(no filters)_ + +A list of image filters that will be applied to the active rendering canvas for a given style. The presence of one more more `image-filters` will trigger a new canvas to be created before starting to render a style and then this canvas will be composited back into the main canvas after rendering all features and after all `image-filters` have been applied. See `direct-image-filters` if you want to apply a filter directly to the main canvas. +* * * + +##### direct-image-filters `functions` + +`agg-stack-blur``emboss``blur``gray``sobel``edge-detect``x-gradient``y-gradient``invert``sharpen``colorize-alpha` + +Default Value: none +_(no filters)_ + +A list of image filters to apply to the main canvas (see the `image-filters` doc for how they work on a separate canvas) +* * * + +##### comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current layer on top of other layers)_ + +Composite operation. This defines how this layer should behave relative to layers atop or below it. +* * * + +##### opacity `float` + + + +Default Value: 1 +_(no separate buffer will be used and no alpha will be applied to the style after rendering)_ + +An alpha value for the style (which means an alpha applied to all features in separate buffer and then composited back to main buffer) +* * * + + +## map + +##### background-color `color` + + + +Default Value: none +_(transparent)_ + +Map Background color +* * * + +##### background-image `uri` + + + +Default Value: +_(transparent)_ + +An image that is repeated below all features on a map as a background. +* * * + +##### srs `string` + + + +Default Value: +proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs +_(The proj4 literal of EPSG:4326 is assumed to be the Map's spatial reference and all data from layers within this map will be plotted using this coordinate system. If any layers do not declare an srs value then they will be assumed to be in the same srs as the Map and not transformations will be needed to plot them in the Map's coordinate space)_ + +Map spatial reference (proj4 string) +* * * + +##### buffer-size `float` + + + +Default Value: 0 +_(No buffer will be used)_ + +Extra tolerance around the map (in pixels) used to ensure labels crossing tile boundaries are equally rendered in each tile (e.g. cut in each tile). Not intended to be used in combination with "avoid-edges". +* * * + +##### base `string` + + + +Default Value: +_(This base path defaults to an empty string meaning that any relative paths to files referenced in styles or layers will be interpreted relative to the application process.)_ + +Any relative paths used to reference files will be understood as relative to this directory path if the map is loaded from an in memory object rather than from the filesystem. If the map is loaded from the filesystem and this option is not provided it will be set to the directory of the stylesheet. +* * * + +##### font-directory `uri` + + + +Default Value: none +_(No map-specific fonts will be registered)_ + +Path to a directory which holds fonts which should be registered when the Map is loaded (in addition to any fonts that may be automatically registered). +* * * + + +## polygon + +##### polygon-fill `color` + + + +Default Value: rgba(128,128,128,1) +_(gray and fully opaque (alpha = 1), same as rgb(128,128,128))_ + +Fill color to assign to a polygon +* * * + +##### polygon-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The opacity of the polygon +* * * + +##### polygon-gamma `float` + + + +Default Value: 1 +_(fully antialiased)_ +Range: 0-1 +Level of antialiasing of polygon edges +* * * + +##### polygon-gamma-method `keyword` +`power``linear``none``threshold``multiply` + + +Default Value: power +_(pow(x,gamma) is used to calculate pixel gamma, which produces slightly smoother line and polygon antialiasing than the 'linear' method, while other methods are usually only used to disable AA)_ + +An Antigrain Geometry specific rendering hint to control the quality of antialiasing. Under the hood in Mapnik this method is used in combination with the 'gamma' value (which defaults to 1). The methods are in the AGG source at https://github.com/mapnik/mapnik/blob/master/deps/agg/include/agg_gamma_functions.h +* * * + +##### polygon-clip `boolean` + + + +Default Value: true +_(geometry will be clipped to map bounds before rendering)_ + +geometries are clipped to map bounds by default for best rendering performance. In some cases users may wish to disable this to avoid rendering artifacts. +* * * + +##### polygon-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified)_ + +geometries are simplified by the given tolerance +* * * + +##### polygon-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(geometry will not be simplified using the radial distance algorithm)_ + +geometries are simplified by the given algorithm +* * * + +##### polygon-smooth `float` + + + +Default Value: 0 +_(no smoothing)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### polygon-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(geometry will not be transformed)_ + +Allows transformation functions to be applied to the geometry. +* * * + +##### polygon-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## line + +##### line-color `color` + + + +Default Value: rgba(0,0,0,1) +_(black and fully opaque (alpha = 1), same as rgb(0,0,0))_ + +The color of a drawn line +* * * + +##### line-width `float` + + + +Default Value: 1 + + +The width of a line in pixels +* * * + +##### line-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The opacity of a line +* * * + +##### line-join `keyword` +`miter``round``bevel` + + +Default Value: miter + + +The behavior of lines when joining +* * * + +##### line-cap `keyword` +`butt``round``square` + + +Default Value: butt + + +The display of line endings +* * * + +##### line-gamma `float` + + + +Default Value: 1 +_(fully antialiased)_ +Range: 0-1 +Level of antialiasing of stroke line +* * * + +##### line-gamma-method `keyword` +`power``linear``none``threshold``multiply` + + +Default Value: power +_(pow(x,gamma) is used to calculate pixel gamma, which produces slightly smoother line and polygon antialiasing than the 'linear' method, while other methods are usually only used to disable AA)_ + +An Antigrain Geometry specific rendering hint to control the quality of antialiasing. Under the hood in Mapnik this method is used in combination with the 'gamma' value (which defaults to 1). The methods are in the AGG source at https://github.com/mapnik/mapnik/blob/master/deps/agg/include/agg_gamma_functions.h +* * * + +##### line-dasharray `numbers` + + + +Default Value: none +_(solid line)_ + +A pair of length values [a,b], where (a) is the dash length and (b) is the gap length respectively. More than two values are supported for more complex patterns. +* * * + +##### line-dash-offset `numbers` + + + +Default Value: none +_(solid line)_ + +valid parameter but not currently used in renderers (only exists for experimental svg support in Mapnik which is not yet enabled) +* * * + +##### line-miterlimit `float` + + + +Default Value: 4 +_(Will auto-convert miters to bevel line joins when theta is less than 29 degrees as per the SVG spec: 'miterLength / stroke-width = 1 / sin ( theta / 2 )')_ + +The limit on the ratio of the miter length to the stroke-width. Used to automatically convert miter joins to bevel joins for sharp angles to avoid the miter extending beyond the thickness of the stroking path. Normally will not need to be set, but a larger value can sometimes help avoid jaggy artifacts. +* * * + +##### line-clip `boolean` + + + +Default Value: true +_(geometry will be clipped to map bounds before rendering)_ + +geometries are clipped to map bounds by default for best rendering performance. In some cases users may wish to disable this to avoid rendering artifacts. +* * * + +##### line-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified)_ + +geometries are simplified by the given tolerance +* * * + +##### line-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(geometry will not be simplified using the radial distance algorithm)_ + +geometries are simplified by the given algorithm +* * * + +##### line-smooth `float` + + + +Default Value: 0 +_(no smoothing)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### line-offset `float` + + + +Default Value: 0 +_(no offset)_ + +Offsets a line a number of pixels parallel to its actual path. Positive values move the line left, negative values move it right (relative to the directionality of the line). +* * * + +##### line-rasterizer `keyword` +`full``fast` + + +Default Value: full + + +Exposes an alternate AGG rendering method that sacrifices some accuracy for speed. +* * * + +##### line-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(geometry will not be transformed)_ + +Allows transformation functions to be applied to the geometry. +* * * + +##### line-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## markers + +##### marker-file `uri` + + + +Default Value: +_(An ellipse or circle, if width equals height)_ + +An SVG file that this marker shows at each placement. If no file is given, the marker will show an ellipse. +* * * + +##### marker-opacity `float` + + + +Default Value: 1 +_(The stroke-opacity and fill-opacity will be used)_ + +The overall opacity of the marker, if set, overrides both the opacity of both the fill and stroke +* * * + +##### marker-fill-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The fill opacity of the marker +* * * + +##### marker-line-color `color` + + + +Default Value: black + + +The color of the stroke around a marker shape. +* * * + +##### marker-line-width `float` + + + +Default Value: 0.5 + + +The width of the stroke around a marker shape, in pixels. This is positioned on the boundary, so high values can cover the area itself. +* * * + +##### marker-line-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The opacity of a line +* * * + +##### marker-placement `keyword` +`point``line``interior` + + +Default Value: point +_(Place markers at the center point (centroid) of the geometry)_ + +Attempt to place markers on a point, in the center of a polygon, or if markers-placement:line, then multiple times along a line. 'interior' placement can be used to ensure that points placed on polygons are forced to be inside the polygon interior +* * * + +##### marker-multi-policy `keyword` +`each``whole``largest` + + +Default Value: each +_(If a feature contains multiple geometries and the placement type is either point or interior then a marker will be rendered for each)_ + +A special setting to allow the user to control rendering behavior for 'multi-geometries' (when a feature contains multiple geometries). This setting does not apply to markers placed along lines. The 'each' policy is default and means all geometries will get a marker. The 'whole' policy means that the aggregate centroid between all geometries will be used. The 'largest' policy means that only the largest (by bounding box areas) feature will get a rendered marker (this is how text labeling behaves by default). +* * * + +##### marker-type `keyword` +`arrow``ellipse` + + +Default Value: ellipse + + +The default marker-type. If a SVG file is not given as the marker-file parameter, the renderer provides either an arrow or an ellipse (a circle if height is equal to width) +* * * + +##### marker-width `float` + + + +Default Value: 10 + + +The width of the marker, if using one of the default types. +* * * + +##### marker-height `float` + + + +Default Value: 10 + + +The height of the marker, if using one of the default types. +* * * + +##### marker-fill `color` + + + +Default Value: blue + + +The color of the area of the marker. +* * * + +##### marker-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow makers to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping markers are shown or hidden. +* * * + +##### marker-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache)_ + +value to control whether the placement of the feature will prevent the placement of other features +* * * + +##### marker-spacing `float` + + + +Default Value: 100 + + +Space between repeated markers in pixels. If the spacing is less than the marker size or larger than the line segment length then no marker will be placed +* * * + +##### marker-max-error `float` + + + +Default Value: 0.2 + + +The maximum difference between actual marker placement and the marker-spacing parameter. Setting a high value can allow the renderer to try to resolve placement conflicts with other symbolizers. +* * * + +##### marker-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: +_(No transformation)_ + +SVG transformation definition +* * * + +##### marker-clip `boolean` + + + +Default Value: true +_(geometry will be clipped to map bounds before rendering)_ + +geometries are clipped to map bounds by default for best rendering performance. In some cases users may wish to disable this to avoid rendering artifacts. +* * * + +##### marker-smooth `float` + + + +Default Value: 0 +_(no smoothing)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### marker-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(geometry will not be transformed)_ + +Allows transformation functions to be applied to the geometry. +* * * + +##### marker-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## shield + +##### shield-name `string` + + + +Default Value: + + +Value to use for a shield"s text label. Data columns are specified using brackets like [column_name] +* * * + +##### shield-file `uri` + + + +Default Value: none + + +Image file to render behind the shield text +* * * + +##### shield-face-name `string` + + + +Default Value: + + +Font name and style to use for the shield text +* * * + +##### shield-unlock-image `boolean` + + + +Default Value: false +_(text alignment relative to the shield image uses the center of the image as the anchor for text positioning.)_ + +This parameter should be set to true if you are trying to position text beside rather than on top of the shield image +* * * + +##### shield-size `float` + + + +Default Value: 10 + + +The size of the shield text in pixels +* * * + +##### shield-fill `color` + + + +Default Value: black + + +The color of the shield text +* * * + +##### shield-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point + + +How this shield should be placed. Point placement attempts to place it on top of points, line places along lines multiple times per feature, vertex places on the vertexes of polygons, and interior attempts to place inside of polygons. +* * * + +##### shield-avoid-edges `boolean` + + + +Default Value: false + + +Avoid placing shields that intersect with tile boundaries. +* * * + +##### shield-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow shields to overlap with other map elements already placed.)_ + +Control whether overlapping shields are shown or hidden. +* * * + +##### shield-min-distance `float` + + + +Default Value: 0 + + +Minimum distance to the next shield symbol, not necessarily the same shield. +* * * + +##### shield-spacing `float` + + + +Default Value: 0 + + +The spacing between repeated occurrences of the same shield on a line +* * * + +##### shield-min-padding `float` + + + +Default Value: 0 + + +Minimum distance a shield will be placed from the edge of a metatile. +* * * + +##### shield-wrap-width `unsigned` + + + +Default Value: 0 + + +Length of a chunk of text in characters before wrapping text +* * * + +##### shield-wrap-before `boolean` + + + +Default Value: false + + +Wrap text before wrap-width is reached. If false, wrapped lines will be a bit longer than wrap-width. +* * * + +##### shield-wrap-character `string` + + + +Default Value: + + +Use this character instead of a space to wrap long names. +* * * + +##### shield-halo-fill `color` + + + +Default Value: #FFFFFF +_(white)_ + +Specifies the color of the halo around the text. +* * * + +##### shield-halo-radius `float` + + + +Default Value: 0 +_(no halo)_ + +Specify the radius of the halo in pixels +* * * + +##### shield-character-spacing `unsigned` + + + +Default Value: 0 + + +Horizontal spacing between characters (in pixels). Currently works for point placement only, not line placement. +* * * + +##### shield-line-spacing `unsigned` + + + +Default Value: 0 + + +Vertical spacing between lines of multiline labels (in pixels) +* * * + +##### shield-text-dx `float` + + + +Default Value: 0 + + +Displace text within shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right +* * * + +##### shield-text-dy `float` + + + +Default Value: 0 + + +Displace text within shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text down +* * * + +##### shield-dx `float` + + + +Default Value: 0 + + +Displace shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right +* * * + +##### shield-dy `float` + + + +Default Value: 0 + + +Displace shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text down +* * * + +##### shield-opacity `float` + + + +Default Value: 1 + + +The opacity of the image used for the shield +* * * + +##### shield-text-opacity `float` + + + +Default Value: 1 + + +The opacity of the text placed on top of the shield +* * * + +##### shield-horizontal-alignment `keyword` +`left``middle``right``auto` + + +Default Value: auto + + +The shield's horizontal alignment from its centerpoint +* * * + +##### shield-vertical-alignment `keyword` +`top``middle``bottom``auto` + + +Default Value: middle + + +The shield's vertical alignment from its centerpoint +* * * + +##### shield-placement-type `keyword` +`dummy``simple` + + +Default Value: dummy + + +Re-position and/or re-size shield to avoid overlaps. "simple" for basic algorithm (using shield-placements string,) "dummy" to turn this feature off. +* * * + +##### shield-placements `string` + + + +Default Value: + + +If "placement-type" is set to "simple", use this "POSITIONS,[SIZES]" string. An example is `shield-placements: "E,NE,SE,W,NW,SW";` +* * * + +##### shield-text-transform `keyword` +`none``uppercase``lowercase``capitalize` + + +Default Value: none + + +Transform the case of the characters +* * * + +##### shield-justify-alignment `keyword` +`left``center``right``auto` + + +Default Value: auto + + +Define how text in a shield's label is justified +* * * + +##### shield-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: +_(No transformation)_ + +SVG transformation definition +* * * + +##### shield-clip `boolean` + + + +Default Value: true +_(geometry will be clipped to map bounds before rendering)_ + +geometries are clipped to map bounds by default for best rendering performance. In some cases users may wish to disable this to avoid rendering artifacts. +* * * + +##### shield-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## line-pattern + +##### line-pattern-file `uri` + + + +Default Value: none + + +An image file to be repeated and warped along a line +* * * + +##### line-pattern-clip `boolean` + + + +Default Value: true +_(geometry will be clipped to map bounds before rendering)_ + +geometries are clipped to map bounds by default for best rendering performance. In some cases users may wish to disable this to avoid rendering artifacts. +* * * + +##### line-pattern-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified)_ + +geometries are simplified by the given tolerance +* * * + +##### line-pattern-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(geometry will not be simplified using the radial distance algorithm)_ + +geometries are simplified by the given algorithm +* * * + +##### line-pattern-smooth `float` + + + +Default Value: 0 +_(no smoothing)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### line-pattern-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(geometry will not be transformed)_ + +Allows transformation functions to be applied to the geometry. +* * * + +##### line-pattern-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## polygon-pattern + +##### polygon-pattern-file `uri` + + + +Default Value: none + + +Image to use as a repeated pattern fill within a polygon +* * * + +##### polygon-pattern-alignment `keyword` +`local``global` + + +Default Value: local + + +Specify whether to align pattern fills to the layer or to the map. +* * * + +##### polygon-pattern-gamma `float` + + + +Default Value: 1 +_(fully antialiased)_ +Range: 0-1 +Level of antialiasing of polygon pattern edges +* * * + +##### polygon-pattern-opacity `float` + + + +Default Value: 1 +_(The image is rendered without modifications)_ + +Apply an opacity level to the image used for the pattern +* * * + +##### polygon-pattern-clip `boolean` + + + +Default Value: true +_(geometry will be clipped to map bounds before rendering)_ + +geometries are clipped to map bounds by default for best rendering performance. In some cases users may wish to disable this to avoid rendering artifacts. +* * * + +##### polygon-pattern-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified)_ + +geometries are simplified by the given tolerance +* * * + +##### polygon-pattern-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(geometry will not be simplified using the radial distance algorithm)_ + +geometries are simplified by the given algorithm +* * * + +##### polygon-pattern-smooth `float` + + + +Default Value: 0 +_(no smoothing)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### polygon-pattern-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(geometry will not be transformed)_ + +Allows transformation functions to be applied to the geometry. +* * * + +##### polygon-pattern-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## raster + +##### raster-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The opacity of the raster symbolizer on top of other symbolizers. +* * * + +##### raster-filter-factor `float` + + + +Default Value: -1 +_(Allow the datasource to choose appropriate downscaling.)_ + +This is used by the Raster or Gdal datasources to pre-downscale images using overviews. Higher numbers can sometimes cause much better scaled image output, at the cost of speed. +* * * + +##### raster-scaling `keyword` +`near``fast``bilinear``bilinear8``bicubic``spline16``spline36``hanning``hamming``hermite``kaiser``quadric``catrom``gaussian``bessel``mitchell``sinc``lanczos``blackman` + + +Default Value: near + + +The scaling algorithm used to making different resolution versions of this raster layer. Bilinear is a good compromise between speed and accuracy, while lanczos gives the highest quality. +* * * + +##### raster-mesh-size `unsigned` + + + +Default Value: 16 +_(Reprojection mesh will be 1/16 of the resolution of the source image)_ + +A reduced resolution mesh is used for raster reprojection, and the total image size is divided by the mesh-size to determine the quality of that mesh. Values for mesh-size larger than the default will result in faster reprojection but might lead to distortion. +* * * + +##### raster-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### raster-colorizer-default-mode `keyword` +`discrete``linear``exact` + + +Default Value: linear +_(A linear interpolation is used to generate colors between the two nearest stops.)_ + +This can be either `discrete`, `linear` or `exact`. If it is not specified then the default is `linear`. +* * * + +##### raster-colorizer-default-color `color` + + + +Default Value: transparent +_(Pixels that are not colored by the colorizer stops will be transparent)_ + +This can be any color. Sets the color that is applied to all values outside of the range of the colorizer-stops. If not supplied pixels will be fully transparent +* * * + +##### raster-colorizer-epsilon `float` + + + +Default Value: 1.1920928955078125e-07 +_(Pixels must very closely match the stop filter otherwise they will not be colored.)_ + +This can be any positive floating point value and will be used as a tolerance in floating point comparisions. The higher the value the more likely a stop will match and color data. +* * * + +##### raster-colorizer-stops `tags` + + + +Default Value: +_(No colorization will happen without supplying stops.)_ + +Assigns raster data values to colors. Stops must be listed in ascending order, and contain at a minimum the value and the associated color. You can also include the color-mode as a third argument, like `stop(100,#fff,exact)`. +* * * + + +## point + +##### point-file `uri` + + + +Default Value: none + + +Image file to represent a point +* * * + +##### point-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow points to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping points are shown or hidden. +* * * + +##### point-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache)_ + +value to control whether the placement of the feature will prevent the placement of other features +* * * + +##### point-opacity `float` + + + +Default Value: 1 +_(Fully opaque)_ + +A value from 0 to 1 to control the opacity of the point +* * * + +##### point-placement `keyword` +`centroid``interior` + + +Default Value: centroid + + +How this point should be placed. Centroid calculates the geometric center of a polygon, which can be outside of it, while interior always places inside of a polygon. +* * * + +##### point-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: +_(No transformation)_ + +SVG transformation definition +* * * + +##### point-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## text + +##### text-name `string` + + + +Default Value: + + +Value to use for a text label. Data columns are specified using brackets like [column_name] +* * * + +##### text-face-name `string` + + + +Default Value: + + +Font name and style to render a label in +* * * + +##### text-size `float` + + + +Default Value: 10 + + +Text size in pixels +* * * + +##### text-ratio `unsigned` + + + +Default Value: 0 + + +Define the amount of text (of the total) present on successive lines when wrapping occurs +* * * + +##### text-wrap-width `unsigned` + + + +Default Value: 0 + + +Length of a chunk of text in characters before wrapping text +* * * + +##### text-wrap-before `boolean` + + + +Default Value: false + + +Wrap text before wrap-width is reached. If false, wrapped lines will be a bit longer than wrap-width. +* * * + +##### text-wrap-character `string` + + + +Default Value: + + +Use this character instead of a space to wrap long text. +* * * + +##### text-spacing `unsigned` + + + +Default Value: 0 + + +Distance between repeated text labels on a line (aka. label-spacing) +* * * + +##### text-character-spacing `float` + + + +Default Value: 0 + + +Horizontal spacing adjustment between characters in pixels +* * * + +##### text-line-spacing `unsigned` + + + +Default Value: 0 + + +Vertical spacing adjustment between lines in pixels +* * * + +##### text-label-position-tolerance `unsigned` + + + +Default Value: 0 + + +Allows the label to be displaced from its ideal position by a number of pixels (only works with placement:line) +* * * + +##### text-max-char-angle-delta `float` + + + +Default Value: 22.5 + + +The maximum angle change, in degrees, allowed between adjacent characters in a label. This value internally is converted to radians to the default is 22.5*math.pi/180.0. The higher the value the fewer labels will be placed around around sharp corners. +* * * + +##### text-fill `color` + + + +Default Value: #000000 + + +Specifies the color for the text +* * * + +##### text-opacity `float` + + + +Default Value: 1 +_(Fully opaque)_ + +A number from 0 to 1 specifying the opacity for the text +* * * + +##### text-halo-fill `color` + + + +Default Value: #FFFFFF +_(white)_ + +Specifies the color of the halo around the text. +* * * + +##### text-halo-radius `float` + + + +Default Value: 0 +_(no halo)_ + +Specify the radius of the halo in pixels +* * * + +##### text-halo-rasterizer `keyword` +`full``fast` + + +Default Value: full + + +Exposes an alternate text halo rendering method that sacrifices quality for speed. +* * * + +##### text-dx `float` + + + +Default Value: 0 + + +Displace text by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right +* * * + +##### text-dy `float` + + + +Default Value: 0 + + +Displace text by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text down +* * * + +##### text-vertical-alignment `keyword` +`top``middle``bottom``auto` + + +Default Value: auto +_(Default affected by value of dy; "bottom" for dy>0, "top" for dy<0.)_ + +Position of label relative to point position. +* * * + +##### text-avoid-edges `boolean` + + + +Default Value: false + + +Avoid placing labels that intersect with tile boundaries. +* * * + +##### text-min-distance `float` + + + +Default Value: 0 + + +Minimum permitted distance to the next text symbolizer. +* * * + +##### text-min-padding `float` + + + +Default Value: 0 + + +Minimum distance a text label will be placed from the edge of a metatile. +* * * + +##### text-min-path-length `float` + + + +Default Value: 0 +_(place labels on all paths)_ + +Place labels only on paths longer than this value. +* * * + +##### text-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow text to overlap with other text - overlapping markers will not be shown.)_ + +Control whether overlapping text is shown or hidden. +* * * + +##### text-orientation `float` + + + +Default Value: 0 + + +Rotate the text. +* * * + +##### text-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point + + +Control the style of placement of a point versus the geometry it is attached to. +* * * + +##### text-placement-type `keyword` +`dummy``simple` + + +Default Value: dummy + + +Re-position and/or re-size text to avoid overlaps. "simple" for basic algorithm (using text-placements string,) "dummy" to turn this feature off. +* * * + +##### text-placements `string` + + + +Default Value: + + +If "placement-type" is set to "simple", use this "POSITIONS,[SIZES]" string. An example is `text-placements: "E,NE,SE,W,NW,SW";` +* * * + +##### text-transform `keyword` +`none``uppercase``lowercase``capitalize` + + +Default Value: none + + +Transform the case of the characters +* * * + +##### text-horizontal-alignment `keyword` +`left``middle``right``auto` + + +Default Value: auto + + +The text's horizontal alignment from its centerpoint +* * * + +##### text-align `keyword` +`left``right``center``auto` + + +Default Value: auto +_(Auto alignment means that text will be centered by default except when using the `placement-type` parameter - in that case either right or left justification will be used automatically depending on where the text could be fit given the `text-placements` directives)_ + +Define how text is justified +* * * + +##### text-clip `boolean` + + + +Default Value: true +_(geometry will be clipped to map bounds before rendering)_ + +geometries are clipped to map bounds by default for best rendering performance. In some cases users may wish to disable this to avoid rendering artifacts. +* * * + +##### text-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## building + +##### building-fill `color` + + + +Default Value: #FFFFFF + + +The color of the buildings walls. +* * * + +##### building-fill-opacity `float` + + + +Default Value: 1 + + +The opacity of the building as a whole, including all walls. +* * * + +##### building-height `float` + + + +Default Value: 0 + + +The height of the building in pixels. +* * * + + +## debug + +##### debug-mode `string` + + + +Default Value: collision + + +The mode for debug rendering +* * * + + + + +### Values + +Below is a list of values and an explanation of any expression that can be applied to properties in CartCSS. + +### Color + +CartoCSS accepts a variety of syntaxes for colors - HTML-style hex values, rgb, rgba, hsl, hsla, husl, and husla. It also supports the predefined HTML colors names, like `yellow` and `blue`. + +``` css +#line { +line-color: #ff0; +line-color: #ffff00; +line-color: rgb(255, 255, 0); +line-color: rgba(255, 255, 0, 1); +line-color: hsl(100, 50%, 50%); +line-color: hsla(100, 50%, 50%, 1); +line-color: husl(100, 50%, 50%); // same values yield different color than HSL +line-color: husla(100, 50%, 50%, 1); +line-color: yellow; +} +``` + +Especially of note is the support for hsl and husl, which can be [easier to reason about than rgb()](http://mothereffinghsl.com/). Carto also includes several color operation functions [borrowed from less](http://lesscss.org/functions/#color-operations): + +``` css +// lighten and darken colors +lighten(#ace, 10%); +darken(#ace, 10%); + +// saturate and desaturate +saturate(#550000, 10%); +desaturate(#00ff00, 10%); + +// increase or decrease the opacity of a color +fadein(#fafafa, 10%); +fadeout(#fefefe, 14%); + +// spin rotates a color around the color wheel by degrees +spin(#ff00ff, 10); + +// mix generates a color in between two other colors. +mix(#fff, #000, 50%); + +// get color components +hue(#ff00ff); +saturation(#ff00ff); +lightness(#ff00ff); +alpha(hsla(100, 50%, 50%, 0.5)); +``` + +These functions all take arguments which can be color variables, literal colors, or the results of other functions operating on colors. All the above mentioned functions also come in +a `functionp`-variant (e.g. `lightenp`), which force a given color into perceptual color space. + +### Float + +Float is a fancy way of saying 'number'. In CartoCSS, you specify _just a number_ - unlike CSS, there are no units, but everything is specified in pixels. + +``` css +#line { +line-width: 2; +} +``` + +It's also possible to do simple math with number values: + +``` css +#line { +line-width: 4 / 2; // division +line-width: 4 + 2; // addition +line-width: 4 - 2; // subtraction +line-width: 4 * 2; // multiplication +line-width: 4 % 2; // modulus +} +``` + +### URI + +URI is a fancy way of saying URL. When an argument is a URI, you use the same kind of `url('place.png')` notation that you would with HTML. Quotes around the URL aren't required, but are highly recommended. URIs can be paths to places on your computer, or on the internet. + +```css +#markers { +marker-file: url('marker.png'); +} +``` + +### String + +A string is basically just text. In the case of CartoCSS, you're going to put it in quotes. Strings can be anything, though pay attention to the cases of `text-name` and `shield-name` - they actually will refer to features, which you refer to by putting them in brackets, as seen in the example below. + +```css +#labels { +text-name: "[MY_FIELD]"; +} +``` + +### Boolean + +Boolean means yes or no, so it accepts the values `true` or `false`. + +```css +#markers { +marker-allow-overlap:true; +} +``` + +### Expressions + +Expressions are statements that can include fields, numbers, and other types in a really flexible way. You have run into expressions before, in the realm of 'fields', where you'd specify `"[FIELD]"`, but expressions allow you to drop the quotes and also do quick addition, division, multiplication, and concatenation from within Carto syntax. + +```css +#buildings { +building-height: [HEIGHT_FIELD] * 10; +} +``` + +### Numbers +Numbers are comma-separated lists of one or more number in a specific order. They're used in line dash arrays, in which the numbers specify intervals of line, break, and line again. + +```css +#disputedboundary { +line-dasharray: 1, 4, 2; +} +``` + +### Percentages +In Carto, the percentage symbol, `%` universally means `value/100`. It's meant to be used with ratio-related properties, like opacity rules. + +_You should not use percentages as widths, heights, or other properties - unlike CSS, percentages are not relative to cascaded classes or page size, they're, as stated, simply the value divided by one hundred._ + +```css +#world { +// this syntax +polygon-opacity: 50%; + +// is equivalent to +polygon-opacity: 0.5; +} +``` + +### Functions + +Functions are comma-separated lists of one or more functions. For instance, transforms use the `functions` type to allow for transforms within Carto, which are optionally chainable. + +```css +#point { +point-transform: scale(2, 2); +} +``` diff --git a/docs/2.3.0.md b/docs/2.3.0.md new file mode 100644 index 0000000..a90fe1b --- /dev/null +++ b/docs/2.3.0.md @@ -0,0 +1,1883 @@ +# Carto documentation + +The following is a list of properties provided in CartoCSS that you can apply to map elements. + +## All elements + +##### image-filters `functions` + +`agg-stack-blur``emboss``blur``gray``sobel``edge-detect``x-gradient``y-gradient``invert``sharpen``colorize-alpha``color-to-alpha``scale-hsla` + +Default Value: none +_(no filters)_ + +A list of image filters that will be applied to the active rendering canvas for a given style. The presence of one more more `image-filters` will trigger a new canvas to be created before starting to render a style and then this canvas will be composited back into the main canvas after rendering all features and after all `image-filters` have been applied. See `direct-image-filters` if you want to apply a filter directly to the main canvas. +* * * + +##### image-filters-inflate `boolean` + + + +Default Value: false +_(No special handling will be done and image filters that blur data will only blur up to the edge of a tile boundary)_ + +A property that can be set to true to enable using an inflated image internally for seamless blurring across tiles (requires buffered data). +* * * + +##### direct-image-filters `functions` + +`agg-stack-blur``emboss``blur``gray``sobel``edge-detect``x-gradient``y-gradient``invert``sharpen``colorize-alpha``color-to-alpha``scale-hsla` + +Default Value: none +_(no filters)_ + +A list of image filters to apply to the main canvas (see the `image-filters` doc for how they work on a separate canvas). +* * * + +##### comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current layer on top of other layers)_ + +Composite operation. This defines how this layer should behave relative to layers atop or below it. +* * * + +##### opacity `float` + + + +Default Value: 1 +_(no separate buffer will be used and no alpha will be applied to the style after rendering)_ + +An alpha value for the style (which means an alpha applied to all features in separate buffer and then composited back to main buffer). +* * * + + +## map + +##### background-color `color` + + + +Default Value: none +_(transparent)_ + +Map Background color. +* * * + +##### background-image `uri` + + + +Default Value: +_(transparent)_ + +An image that is repeated below all features on a map as a background. Accepted formats: JPG, PNG. +* * * + +##### background-image-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(The background-image will be blended with the background normally (placed on top of any existing background-color))_ + +Set the compositing operation used to blend the image into the background. +* * * + +##### background-image-opacity `float` + + + +Default Value: 1 +_(The image opacity will not be changed when applied to the map background)_ + +Set the opacity of the image. +* * * + +##### srs `string` + + + +Default Value: +proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs +_(The proj4 literal of EPSG:4326 is assumed to be the Map's spatial reference and all data from layers within this map will be plotted using this coordinate system. If any layers do not declare an srs value then they will be assumed to be in the same srs as the Map and not transformations will be needed to plot them in the Map's coordinate space)_ + +Map spatial reference (proj4 string). +* * * + +##### buffer-size `float` + + + +Default Value: 0 +_(No buffer will be used)_ + +Extra tolerance around the map (in pixels) used to ensure labels crossing tile boundaries are equally rendered in each tile (e.g. cut in each tile). Not intended to be used in combination with "avoid-edges". +* * * + +##### base `string` + + + +Default Value: +_(This base path defaults to an empty string meaning that any relative paths to files referenced in styles or layers will be interpreted relative to the application process.)_ + +Any relative paths used to reference files will be understood as relative to this directory path if the map is loaded from an in memory object rather than from the filesystem. If the map is loaded from the filesystem and this option is not provided it will be set to the directory of the stylesheet. +* * * + +##### font-directory `uri` + + + +Default Value: none +_(No map-specific fonts will be registered)_ + +Path to a directory which holds fonts which should be registered when the Map is loaded (in addition to any fonts that may be automatically registered). +* * * + + +## polygon + +##### polygon-fill `color` + + + +Default Value: rgba(128,128,128,1) +_(gray and fully opaque (alpha = 1), same as rgb(128,128,128))_ + +Fill color to assign to a polygon. +* * * + +##### polygon-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The opacity of the polygon. +* * * + +##### polygon-gamma `float` + + + +Default Value: 1 +_(fully antialiased)_ +Range: 0-1 +Level of antialiasing of polygon edges. +* * * + +##### polygon-gamma-method `keyword` +`power``linear``none``threshold``multiply` + + +Default Value: power +_(pow(x,gamma) is used to calculate pixel gamma, which produces slightly smoother line and polygon antialiasing than the 'linear' method, while other methods are usually only used to disable AA)_ + +An Antigrain Geometry specific rendering hint to control the quality of antialiasing. Under the hood in Mapnik this method is used in combination with the 'gamma' value (which defaults to 1). The methods are in the AGG source at https://github.com/mapnik/mapnik/blob/master/deps/agg/include/agg_gamma_functions. +* * * + +##### polygon-clip `boolean` + + + +Default Value: true +_(geometry will be clipped to map bounds before rendering)_ + +Geometries are clipped to map bounds by default for best rendering performance. In some cases users may wish to disable this to avoid rendering artifacts. +* * * + +##### polygon-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified)_ + +Simplify geometries by the given tolerance. +* * * + +##### polygon-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(geometry will be simplified using the radial distance algorithm)_ + +Simplify gemoetries by the given algorithm. +* * * + +##### polygon-smooth `float` + + + +Default Value: 0 +_(no smoothing)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### polygon-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(geometry will not be transformed)_ + +Allows transformation functions to be applied to the geometry. +* * * + +##### polygon-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## line + +##### line-color `color` + + + +Default Value: rgba(0,0,0,1) +_(black and fully opaque (alpha = 1), same as rgb(0,0,0))_ + +The color of a drawn line. +* * * + +##### line-width `float` + + + +Default Value: 1 + + +The width of a line in pixels. +* * * + +##### line-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The opacity of a line. +* * * + +##### line-join `keyword` +`miter``round``bevel` + + +Default Value: miter + + +The behavior of lines when joining. +* * * + +##### line-cap `keyword` +`butt``round``square` + + +Default Value: butt + + +The display of line endings. +* * * + +##### line-gamma `float` + + + +Default Value: 1 +_(fully antialiased)_ +Range: 0-1 +Level of antialiasing of stroke line. +* * * + +##### line-gamma-method `keyword` +`power``linear``none``threshold``multiply` + + +Default Value: power +_(pow(x,gamma) is used to calculate pixel gamma, which produces slightly smoother line and polygon antialiasing than the 'linear' method, while other methods are usually only used to disable AA)_ + +An Antigrain Geometry specific rendering hint to control the quality of antialiasing. Under the hood in Mapnik this method is used in combination with the 'gamma' value (which defaults to 1). The methods are in the AGG source at https://github.com/mapnik/mapnik/blob/master/deps/agg/include/agg_gamma_functions. +* * * + +##### line-dasharray `numbers` + + + +Default Value: none +_(solid line)_ + +A pair of length values [a,b], where (a) is the dash length and (b) is the gap length respectively. More than two values are supported for more complex patterns. +* * * + +##### line-dash-offset `numbers` + + + +Default Value: none +_(solid line)_ + +Valid parameter but not currently used in renderers (only exists for experimental svg support in Mapnik which is not yet enabled). +* * * + +##### line-miterlimit `float` + + + +Default Value: 4 +_(Will auto-convert miters to bevel line joins when theta is less than 29 degrees as per the SVG spec: 'miterLength / stroke-width = 1 / sin ( theta / 2 )')_ + +The limit on the ratio of the miter length to the stroke-width. Used to automatically convert miter joins to bevel joins for sharp angles to avoid the miter extending beyond the thickness of the stroking path. Normally will not need to be set, but a larger value can sometimes help avoid jaggy artifacts. +* * * + +##### line-clip `boolean` + + + +Default Value: true +_(geometry will be clipped to map bounds before rendering)_ + +Geometries are clipped to map bounds by default for best rendering performance. In some cases users may wish to disable this to avoid rendering artifacts. +* * * + +##### line-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified)_ + +Simplify gemoetries by the given tolerance +* * * + +##### line-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(geometry will be simplified using the radial distance algorithm)_ + +Simplify gemoetries by the given algorithm. +* * * + +##### line-smooth `float` + + + +Default Value: 0 +_(no smoothing)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### line-offset `float` + + + +Default Value: 0 +_(no offset)_ + +Offsets a line a number of pixels parallel to its actual path. Positive values move the line left, negative values move it right (relative to the directionality of the line). +* * * + +##### line-rasterizer `keyword` +`full``fast` + + +Default Value: full + + +Exposes an alternate AGG rendering method that sacrifices some accuracy for speed. +* * * + +##### line-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(geometry will not be transformed)_ + +Allows transformation functions to be applied to the geometry. +* * * + +##### line-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## markers + +##### marker-file `uri` + + + +Default Value: none +_(An ellipse or circle, if width equals height.)_ + +A file that this marker shows at each placement. If no file is given, the marker will show an ellipse. Accepted formats: SVG, JPG, PNG. +* * * + +##### marker-opacity `float` + + + +Default Value: 1 +_(The stroke-opacity and fill-opacity of the marker.)_ + +The overall opacity of the marker, if set, overrides both the opacity of both the fill and stroke +* * * + +##### marker-fill-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The fill opacity of the marker. +* * * + +##### marker-line-color `color` + + + +Default Value: black + + +The color of the stroke around the marker. +* * * + +##### marker-line-width `float` + + + +Default Value: 0.5 + + +The width of the stroke around the marker, in pixels. This is positioned on the boundary, so high values can cover the area itself. +* * * + +##### marker-line-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The opacity of the line. +* * * + +##### marker-placement `keyword` +`point``line``interior` + + +Default Value: point +_(Place markers at the center point (centroid) of the geometry)_ + +Attempt to place markers on a point, in the center of a polygon, or if markers-placement:line, then multiple times along a line. 'interior' placement can be used to ensure that points placed on polygons are forced to be inside the polygon interior. +* * * + +##### marker-multi-policy `keyword` +`each``whole``largest` + + +Default Value: each +_(If a feature contains multiple geometries and the placement type is either point or interior then a marker will be rendered for each)_ + +A special setting to allow the user to control rendering behavior for 'multi-geometries' (when a feature contains multiple geometries). This setting does not apply to markers placed along lines. The 'each' policy is default and means all geometries will get a marker. The 'whole' policy means that the aggregate centroid between all geometries will be used. The 'largest' policy means that only the largest (by bounding box areas) feature will get a rendered marker (this is how text labeling behaves by default). +* * * + +##### marker-type `keyword` +`arrow``ellipse` + + +Default Value: ellipse + + +The default marker-type. If a SVG file is not given as the marker-file parameter, the renderer provides either an arrow or an ellipse (a circle if height is equal to width). +* * * + +##### marker-width `float` + + + +Default Value: 10 + + +The width of the marker, if using one of the default types. +* * * + +##### marker-height `float` + + + +Default Value: 10 + + +The height of the marker, if using one of the default types. +* * * + +##### marker-fill `color` + + + +Default Value: blue + + +The color of the area of the marker. +* * * + +##### marker-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow makers to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping markers are shown or hidden. +* * * + +##### marker-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache)_ + +Value to control whether the placement of the feature will prevent the placement of other features. +* * * + +##### marker-spacing `float` + + + +Default Value: 100 + + +Space between repeated markers in pixels. If the spacing is less than the marker size or larger than the line segment length then no marker will be placed. +* * * + +##### marker-max-error `float` + + + +Default Value: 0.2 + + +The maximum difference between actual marker placement and the marker-spacing parameter. Setting a high value can allow the renderer to try to resolve placement conflicts with other symbolizers. +* * * + +##### marker-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation)_ + +SVG transformation definition. +* * * + +##### marker-clip `boolean` + + + +Default Value: true +_(geometry will be clipped to map bounds before rendering)_ + +geometries are clipped to map bounds by default for best rendering performance. In some cases users may wish to disable this to avoid rendering artifacts. +* * * + +##### marker-smooth `float` + + + +Default Value: 0 +_(no smoothing)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### marker-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(geometry will not be transformed)_ + +Allows transformation functions to be applied to the geometry. +* * * + +##### marker-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## shield + +##### shield-name `string` + + + +Default Value: + + +Value to use for a shield"s text label. Data columns are specified using brackets like [column_name]. +* * * + +##### shield-file `uri` + + + +Default Value: none + + +Image file to render behind the shield text. Accepted formats: SVG, JPG, PNG. +* * * + +##### shield-face-name `string` + + + +Default Value: + + +Font name and style to use for the shield text +* * * + +##### shield-unlock-image `boolean` + + + +Default Value: false +_(text alignment relative to the shield image uses the center of the image as the anchor for text positioning.)_ + +This parameter should be set to true if you are trying to position text beside rather than on top of the shield image +* * * + +##### shield-size `float` + + + +Default Value: 10 + + +The size of the shield text in pixels. +* * * + +##### shield-fill `color` + + + +Default Value: black + + +The color of the shield text. +* * * + +##### shield-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point + + +How this shield should be placed. Point placement attempts to place it on top of points, line places along lines multiple times per feature, vertex places on the vertexes of polygons, and interior attempts to place inside of polygons. +* * * + +##### shield-avoid-edges `boolean` + + + +Default Value: false + + +Avoid placing shields that intersect with tile boundaries. +* * * + +##### shield-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow shields to overlap with other map elements already placed.)_ + +Control whether overlapping shields are shown or hidden. +* * * + +##### shield-min-distance `float` + + + +Default Value: 0 + + +Minimum distance to the next shield symbol, not necessarily the same shield. +* * * + +##### shield-spacing `float` + + + +Default Value: 0 + + +The spacing between repeated occurrences of the same shield on a line. +* * * + +##### shield-min-padding `float` + + + +Default Value: 0 + + +Minimum distance a shield will be placed from the edge of a metatile. This option is similiar to shield-avoid-edges:true except that the extra margin is used to discard cases where the shield+margin are not fully inside the metatile. +* * * + +##### shield-wrap-width `unsigned` + + + +Default Value: 0 + + +Length of a chunk of text in pixels before wrapping text. If set to zero, text doesn't wrap. +* * * + +##### shield-wrap-before `boolean` + + + +Default Value: false + + +Wrap text before wrap-width is reached. If false, wrapped lines will be a bit longer than wrap-width. +* * * + +##### shield-wrap-character `string` + + + +Default Value: " " + + +Use this character instead of a space to wrap long names. +* * * + +##### shield-halo-fill `color` + + + +Default Value: #FFFFFF +_(white)_ + +Specifies the color of the halo around the text. +* * * + +##### shield-halo-radius `float` + + + +Default Value: 0 +_(no halo)_ + +Specify the radius of the halo in pixels. +* * * + +##### shield-halo-rasterizer `keyword` +`full``fast` + + +Default Value: full + + +Exposes an alternate text halo rendering method that sacrifices quality for speed. +* * * + +##### shield-character-spacing `unsigned` + + + +Default Value: 0 + + +Horizontal spacing between characters (in pixels). Currently works for point placement only, not line placement. +* * * + +##### shield-line-spacing `unsigned` + + + +Default Value: 0 + + +Vertical spacing between lines of multiline labels (in pixels). +* * * + +##### shield-text-dx `float` + + + +Default Value: 0 + + +Displace text within shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the shield right. +* * * + +##### shield-text-dy `float` + + + +Default Value: 0 + + +Displace text within shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the shield down. +* * * + +##### shield-dx `float` + + + +Default Value: 0 + + +Displace shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right. +* * * + +##### shield-dy `float` + + + +Default Value: 0 + + +Displace shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text down. +* * * + +##### shield-opacity `float` + + + +Default Value: 1 + + +The opacity of the image used for the shield +* * * + +##### shield-text-opacity `float` + + + +Default Value: 1 + + +The opacity of the text placed on top of the shield +* * * + +##### shield-horizontal-alignment `keyword` +`left``middle``right``auto` + + +Default Value: auto + + +The shield's horizontal alignment from its centerpoint +* * * + +##### shield-vertical-alignment `keyword` +`top``middle``bottom``auto` + + +Default Value: middle + + +The shield's vertical alignment from its centerpoint +* * * + +##### shield-placement-type `keyword` +`dummy``simple``list` + + +Default Value: dummy + + +Re-position and/or re-size shield to avoid overlaps. "simple" for basic algorithm (using shield-placements string,) "dummy" to turn this feature off. +* * * + +##### shield-placements `string` + + + +Default Value: + + +If "placement-type" is set to "simple", use this "POSITIONS,[SIZES]" string. An example is `shield-placements: "E,NE,SE,W,NW,SW";` +* * * + +##### shield-text-transform `keyword` +`none``uppercase``lowercase``capitalize` + + +Default Value: none + + +Transform the case of the characters. +* * * + +##### shield-justify-alignment `keyword` +`left``center``right``auto` + + +Default Value: auto + + +Define how text in a shield's label is justified. +* * * + +##### shield-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation)_ + +SVG transformation definition. +* * * + +##### shield-clip `boolean` + + + +Default Value: true +_(geometry will be clipped to map bounds before rendering)_ + +geometries are clipped to map bounds by default for best rendering performance. In some cases users may wish to disable this to avoid rendering artifacts. +* * * + +##### shield-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## line-pattern + +##### line-pattern-file `uri` + + + +Default Value: none + + +An image file to be repeated and warped along a line. Accepted formats: JPG, PNG. +* * * + +##### line-pattern-clip `boolean` + + + +Default Value: true +_(geometry will be clipped to map bounds before rendering)_ + +geometries are clipped to map bounds by default for best rendering performance. In some cases users may wish to disable this to avoid rendering artifacts. +* * * + +##### line-pattern-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified)_ + +geometries are simplified by the given tolerance +* * * + +##### line-pattern-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(geometry will be simplified using the radial distance algorithm)_ + +geometries are simplified by the given algorithm. +* * * + +##### line-pattern-smooth `float` + + + +Default Value: 0 +_(no smoothing)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### line-pattern-offset `float` + + + +Default Value: 0 +_(no offset)_ + +Offsets a line a number of pixels parallel to its actual path. Positive values move the line left, negative values move it right (relative to the directionality of the line). +* * * + +##### line-pattern-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(geometry will not be transformed)_ + +Allows transformation functions to be applied to the geometry. +* * * + +##### line-pattern-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## polygon-pattern + +##### polygon-pattern-file `uri` + + + +Default Value: none + + +Image to use as a repeated pattern fill within a polygon. Accepted formats: JPG, PNG. +* * * + +##### polygon-pattern-alignment `keyword` +`local``global` + + +Default Value: local + + +Specify whether to align pattern fills to the layer or to the map. +* * * + +##### polygon-pattern-gamma `float` + + + +Default Value: 1 +_(fully antialiased)_ +Range: 0-1 +Level of antialiasing of polygon pattern edges +* * * + +##### polygon-pattern-opacity `float` + + + +Default Value: 1 +_(The image is rendered without modifications)_ + +Apply an opacity level to the image used for the pattern +* * * + +##### polygon-pattern-clip `boolean` + + + +Default Value: true +_(geometry will be clipped to map bounds before rendering)_ + +geometries are clipped to map bounds by default for best rendering performance. In some cases users may wish to disable this to avoid rendering artifacts. +* * * + +##### polygon-pattern-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified)_ + +geometries are simplified by the given tolerance +* * * + +##### polygon-pattern-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(geometry will be simplified using the radial distance algorithm)_ + +geometries are simplified by the given algorithm +* * * + +##### polygon-pattern-smooth `float` + + + +Default Value: 0 +_(no smoothing)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### polygon-pattern-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(geometry will not be transformed)_ + +Allows transformation functions to be applied to the geometry. +* * * + +##### polygon-pattern-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## raster + +##### raster-opacity `float` + + + +Default Value: 1 +_(opaque)_ + +The opacity of the raster symbolizer on top of other symbolizers. +* * * + +##### raster-filter-factor `float` + + + +Default Value: -1 +_(Allow the datasource to choose appropriate downscaling.)_ + +This is used by the Raster or Gdal datasources to pre-downscale images using overviews. Higher numbers can sometimes cause much better scaled image output, at the cost of speed. +* * * + +##### raster-scaling `keyword` +`near``fast``bilinear``bicubic``spline16``spline36``hanning``hamming``hermite``kaiser``quadric``catrom``gaussian``bessel``mitchell``sinc``lanczos``blackman` + + +Default Value: near + + +The scaling algorithm used to making different resolution versions of this raster layer. Bilinear is a good compromise between speed and accuracy, while lanczos gives the highest quality. +* * * + +##### raster-mesh-size `unsigned` + + + +Default Value: 16 +_(Reprojection mesh will be 1/16 of the resolution of the source image)_ + +A reduced resolution mesh is used for raster reprojection, and the total image size is divided by the mesh-size to determine the quality of that mesh. Values for mesh-size larger than the default will result in faster reprojection but might lead to distortion. +* * * + +##### raster-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### raster-colorizer-default-mode `keyword` +`discrete``linear``exact` + + +Default Value: linear +_(A linear interpolation is used to generate colors between the two nearest stops.)_ + +This can be either `discrete`, `linear` or `exact`. If it is not specified then the default is `linear`. +* * * + +##### raster-colorizer-default-color `color` + + + +Default Value: transparent +_(Pixels that are not colored by the colorizer stops will be transparent)_ + +This can be any color. Sets the color that is applied to all values outside of the range of the colorizer-stops. If not supplied pixels will be fully transparent +* * * + +##### raster-colorizer-epsilon `float` + + + +Default Value: 1.1920928955078125e-07 +_(Pixels must very closely match the stop filter otherwise they will not be colored.)_ + +This can be any positive floating point value and will be used as a tolerance in floating point comparisions. The higher the value the more likely a stop will match and color data. +* * * + +##### raster-colorizer-stops `tags` + + + +Default Value: +_(No colorization will happen without supplying stops.)_ + +Assigns raster data values to colors. Stops must be listed in ascending order, and contain at a minimum the value and the associated color. You can also include the color-mode as a third argument, like `stop(100,#fff,exact)`. +* * * + + +## point + +##### point-file `uri` + + + +Default Value: none + + +Image file to represent a point. Accepted formats: SVG, PNG, JPG. +* * * + +##### point-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow points to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping points are shown or hidden. +* * * + +##### point-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache)_ + +Control whether the placement of the feature will prevent the placement of other features. +* * * + +##### point-opacity `float` + + + +Default Value: 1 +_(Fully opaque)_ + +A value from 0 to 1 to control the opacity of the point. +* * * + +##### point-placement `keyword` +`centroid``interior` + + +Default Value: centroid + + +Control how this point should be placed. Centroid calculates the geometric center of a polygon, which can be outside of it, while interior always places inside of a polygon. +* * * + +##### point-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation)_ + +SVG transformation definition. +* * * + +##### point-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## text + +##### text-name `string` + + + +Default Value: + + +Value to use for a text label. Data columns are specified using brackets like [column_name] +* * * + +##### text-face-name `string` + + + +Default Value: + + +Font name and style to render a label in +* * * + +##### text-size `float` + + + +Default Value: 10 + + +Text size in pixels +* * * + +##### text-ratio `unsigned` + + + +Default Value: 0 + + +Define the amount of text (of the total) present on successive lines when wrapping occurs +* * * + +##### text-wrap-width `unsigned` + + + +Default Value: 0 + + +Length of a chunk of text in pixels before wrapping text. If set to zero, text doesn't wrap. +* * * + +##### text-wrap-before `boolean` + + + +Default Value: false + + +Wrap text before wrap-width is reached. If false, wrapped lines will be a bit longer than wrap-width. +* * * + +##### text-wrap-character `string` + + + +Default Value: " " + + +Use this character instead of a space to wrap long text. +* * * + +##### text-spacing `unsigned` + + + +Default Value: 0 + + +Distance between repeated text labels on a line (aka. label-spacing). +* * * + +##### text-character-spacing `float` + + + +Default Value: 0 + + +Horizontal spacing adjustment between characters in pixels. +* * * + +##### text-line-spacing `unsigned` + + + +Default Value: 0 + + +Vertical spacing adjustment between lines in pixels. +* * * + +##### text-label-position-tolerance `float` + + + +Default Value: 0 + + +Allows the label to be displaced from its ideal position by a number of pixels (only works with placement:line). +* * * + +##### text-max-char-angle-delta `float` + + + +Default Value: 22.5 + + +The maximum angle change, in degrees, allowed between adjacent characters in a label. This value internally is converted to radians to the default is 22.5*math.pi/180.0. The higher the value the fewer labels will be placed around around sharp corners. +* * * + +##### text-fill `color` + + + +Default Value: #000000 + + +Specifies the color for the text +* * * + +##### text-opacity `float` + + + +Default Value: 1 +_(Fully opaque)_ + +A number from 0 to 1 specifying the opacity for the text +* * * + +##### text-halo-fill `color` + + + +Default Value: #FFFFFF +_(white)_ + +Specifies the color of the halo around the text. +* * * + +##### text-halo-radius `float` + + + +Default Value: 0 +_(no halo)_ + +Specify the radius of the halo in pixels +* * * + +##### text-halo-rasterizer `keyword` +`full``fast` + + +Default Value: full + + +Exposes an alternate text halo rendering method that sacrifices quality for speed. +* * * + +##### text-dx `float` + + + +Default Value: 0 + + +Displace text by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right. +* * * + +##### text-dy `float` + + + +Default Value: 0 + + +Displace text by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text up. +* * * + +##### text-vertical-alignment `keyword` +`top``middle``bottom``auto` + + +Default Value: auto +_(Default affected by value of dy; "top" for dy>0, "bottom" for dy<0.)_ + +Position of label relative to point position. +* * * + +##### text-avoid-edges `boolean` + + + +Default Value: false + + +Avoid placing labels that intersect with tile boundaries. +* * * + +##### text-min-distance `float` + + + +Default Value: 0 + + +Minimum permitted distance to the next text symbolizer. +* * * + +##### text-min-padding `float` + + + +Default Value: 0 + + +Minimum distance a text label will be placed from the edge of a metatile. This option is similiar to shield-avoid-edges:true except that the extra margin is used to discard cases where the shield+margin are not fully inside the metatile. +* * * + +##### text-min-path-length `float` + + + +Default Value: 0 +_(place labels on all paths)_ + +Place labels only on paths longer than this value. +* * * + +##### text-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow text to overlap with other text - overlapping markers will not be shown.)_ + +Control whether overlapping text is shown or hidden. +* * * + +##### text-orientation `float` + + + +Default Value: 0 + + +Rotate the text. +* * * + +##### text-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point + + +Control the style of placement of a point versus the geometry it is attached to. +* * * + +##### text-placement-type `keyword` +`dummy``simple``list` + + +Default Value: dummy + + +Re-position and/or re-size text to avoid overlaps. "simple" for basic algorithm (using text-placements string,) "dummy" to turn this feature off. +* * * + +##### text-placements `string` + + + +Default Value: + + +If "placement-type" is set to "simple", use this "POSITIONS,[SIZES]" string. An example is `text-placements: "E,NE,SE,W,NW,SW";` +* * * + +##### text-transform `keyword` +`none``uppercase``lowercase``capitalize` + + +Default Value: none + + +Transform the case of the characters. +* * * + +##### text-horizontal-alignment `keyword` +`left``middle``right``auto` + + +Default Value: auto + + +The text's horizontal alignment from its centerpoint. +* * * + +##### text-align `keyword` +`left``right``center``auto` + + +Default Value: auto +_(Auto alignment means that text will be centered by default except when using the `placement-type` parameter - in that case either right or left justification will be used automatically depending on where the text could be fit given the `text-placements` directives.)_ + +Define how text is justified +* * * + +##### text-clip `boolean` + + + +Default Value: true +_(geometry will be clipped to map bounds before rendering)_ + +Geometries are clipped to map bounds by default for best rendering performance. In some cases users may wish to disable this to avoid rendering artifacts. +* * * + +##### text-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(add the current symbolizer on top of other symbolizer)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## building + +##### building-fill `color` + + + +Default Value: #FFFFFF + + +The color of the buildings walls. +* * * + +##### building-fill-opacity `float` + + + +Default Value: 1 + + +The opacity of the building as a whole, including all walls. +* * * + +##### building-height `float` + + + +Default Value: 0 + + +The height of the building in pixels. +* * * + + +## debug + +##### debug-mode `string` + + + +Default Value: collision + + +The mode for debug rendering. +* * * + + + + +### Values + +Below is a list of values and an explanation of any expression that can be applied to properties in CartCSS. + +### Color + +CartoCSS accepts a variety of syntaxes for colors - HTML-style hex values, rgb, rgba, hsl, hsla, husl, and husla. It also supports the predefined HTML colors names, like `yellow` and `blue`. + +``` css +#line { +line-color: #ff0; +line-color: #ffff00; +line-color: rgb(255, 255, 0); +line-color: rgba(255, 255, 0, 1); +line-color: hsl(100, 50%, 50%); +line-color: hsla(100, 50%, 50%, 1); +line-color: husl(100, 50%, 50%); // same values yield different color than HSL +line-color: husla(100, 50%, 50%, 1); +line-color: yellow; +} +``` + +Especially of note is the support for hsl and husl, which can be [easier to reason about than rgb()](http://mothereffinghsl.com/). Carto also includes several color operation functions [borrowed from less](http://lesscss.org/functions/#color-operations): + +``` css +// lighten and darken colors +lighten(#ace, 10%); +darken(#ace, 10%); + +// saturate and desaturate +saturate(#550000, 10%); +desaturate(#00ff00, 10%); + +// increase or decrease the opacity of a color +fadein(#fafafa, 10%); +fadeout(#fefefe, 14%); + +// spin rotates a color around the color wheel by degrees +spin(#ff00ff, 10); + +// mix generates a color in between two other colors. +mix(#fff, #000, 50%); + +// get color components +hue(#ff00ff); +saturation(#ff00ff); +lightness(#ff00ff); +alpha(hsla(100, 50%, 50%, 0.5)); +``` + +These functions all take arguments which can be color variables, literal colors, or the results of other functions operating on colors. All the above mentioned functions also come in +a `functionp`-variant (e.g. `lightenp`), which force a given color into perceptual color space. + +### Float + +Float is a fancy way of saying 'number'. In CartoCSS, you specify _just a number_ - unlike CSS, there are no units, but everything is specified in pixels. + +``` css +#line { +line-width: 2; +} +``` + +It's also possible to do simple math with number values: + +``` css +#line { +line-width: 4 / 2; // division +line-width: 4 + 2; // addition +line-width: 4 - 2; // subtraction +line-width: 4 * 2; // multiplication +line-width: 4 % 2; // modulus +} +``` + +### URI + +URI is a fancy way of saying URL. When an argument is a URI, you use the same kind of `url('place.png')` notation that you would with HTML. Quotes around the URL aren't required, but are highly recommended. URIs can be paths to places on your computer, or on the internet. + +```css +#markers { +marker-file: url('marker.png'); +} +``` + +### String + +A string is basically just text. In the case of CartoCSS, you're going to put it in quotes. Strings can be anything, though pay attention to the cases of `text-name` and `shield-name` - they actually will refer to features, which you refer to by putting them in brackets, as seen in the example below. + +```css +#labels { +text-name: "[MY_FIELD]"; +} +``` + +### Boolean + +Boolean means yes or no, so it accepts the values `true` or `false`. + +```css +#markers { +marker-allow-overlap:true; +} +``` + +### Expressions + +Expressions are statements that can include fields, numbers, and other types in a really flexible way. You have run into expressions before, in the realm of 'fields', where you'd specify `"[FIELD]"`, but expressions allow you to drop the quotes and also do quick addition, division, multiplication, and concatenation from within Carto syntax. + +```css +#buildings { +building-height: [HEIGHT_FIELD] * 10; +} +``` + +### Numbers +Numbers are comma-separated lists of one or more number in a specific order. They're used in line dash arrays, in which the numbers specify intervals of line, break, and line again. + +```css +#disputedboundary { +line-dasharray: 1, 4, 2; +} +``` + +### Percentages +In Carto, the percentage symbol, `%` universally means `value/100`. It's meant to be used with ratio-related properties, like opacity rules. + +_You should not use percentages as widths, heights, or other properties - unlike CSS, percentages are not relative to cascaded classes or page size, they're, as stated, simply the value divided by one hundred._ + +```css +#world { +// this syntax +polygon-opacity: 50%; + +// is equivalent to +polygon-opacity: 0.5; +} +``` + +### Functions + +Functions are comma-separated lists of one or more functions. For instance, transforms use the `functions` type to allow for transforms within Carto, which are optionally chainable. + +```css +#point { +point-transform: scale(2, 2); +} +``` diff --git a/docs/3.0.0.md b/docs/3.0.0.md new file mode 100644 index 0000000..5079f76 --- /dev/null +++ b/docs/3.0.0.md @@ -0,0 +1,2226 @@ +# Carto documentation + +The following is a list of properties provided in CartoCSS that you can apply to map elements. + +## All elements + +##### image-filters `functions` + +`agg-stack-blur``emboss``blur``gray``sobel``edge-detect``x-gradient``y-gradient``invert``sharpen``colorize-alpha``color-to-alpha``scale-hsla` + +Default Value: none +_(no filters.)_ + +A list of image filters that will be applied to the active rendering canvas for a given style. The presence of one more `image-filters` will trigger a new canvas to be created before starting to render a style and then this canvas will be composited back into the main canvas after rendering all features and after all `image-filters` have been applied. See `direct-image-filters` if you want to apply a filter directly to the main canvas. +* * * + +##### image-filters-inflate `boolean` + + + +Default Value: false +_(No special handling will be done and image filters that blur data will only blur up to the edge of a tile boundary.)_ + +A property that can be set to true to enable using an inflated image internally for seamless blurring across tiles (requires buffered data). +* * * + +##### direct-image-filters `functions` + +`agg-stack-blur``emboss``blur``gray``sobel``edge-detect``x-gradient``y-gradient``invert``sharpen``colorize-alpha``color-to-alpha``scale-hsla` + +Default Value: none +_(no filters.)_ + +A list of image filters to apply to the main canvas (see the `image-filters` doc for how they work on a separate canvas). +* * * + +##### comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current layer on top of other layers.)_ + +Composite operation. This defines how this layer should behave relative to layers atop or below it. +* * * + +##### opacity `float` + + + +Default Value: 1 +_(No separate buffer will be used and no alpha will be applied to the style after rendering.)_ + +An alpha value for the style (which means an alpha applied to all features in separate buffer and then composited back to main buffer). +* * * + + +## map + +##### background-color `color` + + + +Default Value: none +_(Will be rendered transparent.)_ + +Map Background color. +* * * + +##### background-image `uri` + + + +Default Value: +_(No background image will be used.)_ + +An image that is repeated below all features on a map as a background. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### background-image-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(The background-image will be blended with the background normally (placed on top of any existing background-color).)_ + +Set the compositing operation used to blend the image into the background. +* * * + +##### background-image-opacity `float` + + + +Default Value: 1 +_(The image opacity will not be changed when applied to the map background.)_ + +Set the opacity of the image. +* * * + +##### srs `string` + + + +Default Value: +proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs +_(The proj4 literal of EPSG:4326 is assumed to be the Map's spatial reference and all data from layers within this map will be plotted using this coordinate system. If any layers do not declare an srs value then they will be assumed to be in the same srs as the Map and not transformations will be needed to plot them in the Map's coordinate space.)_ + +Map spatial reference (proj4 string). +* * * + +##### buffer-size `float` + + + +Default Value: 0 +_(No buffer will be used.)_ + +Extra tolerance around the map (in pixels) used to ensure labels crossing tile boundaries are equally rendered in each tile (e.g. cut in each tile). Not intended to be used in combination with "avoid-edges". +* * * + +##### maximum-extent `string` + + + +Default Value: -20037508.34,-20037508.34,20037508.34,20037508.34 +_(All data will be clipped to global mercator extent (default is applied in Carto.js).)_ + +An extent to be used to limit the bounds used to query all layers during rendering. Should be minx, miny, maxx, maxy in the coordinates of the Map. +* * * + +##### base `string` + + + +Default Value: +_(This base path defaults to an empty string meaning that any relative paths to files referenced in styles or layers will be interpreted relative to the application process.)_ + +Any relative paths used to reference files will be understood as relative to this directory path if the map is loaded from an in memory object rather than from the filesystem. If the map is loaded from the filesystem and this option is not provided it will be set to the directory of the stylesheet. +* * * + +##### font-directory `uri` + + + +Default Value: none +_(No map-specific fonts will be registered.)_ + +Path to a directory which holds fonts which should be registered when the Map is loaded (in addition to any fonts that may be automatically registered). +* * * + + +## polygon + +##### polygon-fill `color` + + + +Default Value: The color gray will be used for fill. +_(Gray and fully opaque (alpha = 1), same as rgb(128,128,128) or rgba(128,128,128,1).)_ + +Fill color to assign to a polygon. +* * * + +##### polygon-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the polygon. +* * * + +##### polygon-gamma `float` + + + +Default Value: 1 +_(Fully antialiased.)_ +Range: 0-1 +Level of antialiasing of polygon edges. +* * * + +##### polygon-gamma-method `keyword` +`power``linear``none``threshold``multiply` + + +Default Value: power +_(pow(x,gamma) is used to calculate pixel gamma, which produces slightly smoother line and polygon antialiasing than the 'linear' method, while other methods are usually only used to disable AA.)_ + +An Antigrain Geometry specific rendering hint to control the quality of antialiasing. Under the hood in Mapnik this method is used in combination with the 'gamma' value (which defaults to 1). The methods are in the AGG source at https://github.com/mapnik/mapnik/blob/master/deps/agg/include/agg_gamma_functions. +* * * + +##### polygon-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extend outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### polygon-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify geometries by the given tolerance. +* * * + +##### polygon-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify geometries by the given algorithm. +* * * + +##### polygon-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### polygon-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform polygon geometry with specified function. +* * * + +##### polygon-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## line + +##### line-color `color` + + + +Default Value: black +_(black and fully opaque (alpha = 1), same as rgb(0,0,0) or rgba(0,0,0,1).)_ + +The color of a drawn line. +* * * + +##### line-width `float` + + + +Default Value: 1 +_(The line will be rendered 1 pixel wide.)_ + +The width of a line in pixels. +* * * + +##### line-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of a line. +* * * + +##### line-join `keyword` +`miter``miter-revert``round``bevel` + + +Default Value: miter +_(The line joins will be rendered using a miter look.)_ + +The behavior of lines when joining. +* * * + +##### line-cap `keyword` +`butt``round``square` + + +Default Value: butt +_(The line endings will be rendered using a butt look.)_ + +The display of line endings. +* * * + +##### line-gamma `float` + + + +Default Value: 1 +_(Fully antialiased.)_ +Range: 0-1 +Level of antialiasing of stroke line. +* * * + +##### line-gamma-method `keyword` +`power``linear``none``threshold``multiply` + + +Default Value: power +_(pow(x,gamma) is used to calculate pixel gamma, which produces slightly smoother line and polygon antialiasing than the 'linear' method, while other methods are usually only used to disable AA.)_ + +An Antigrain Geometry specific rendering hint to control the quality of antialiasing. Under the hood in Mapnik this method is used in combination with the 'gamma' value (which defaults to 1). The methods are in the AGG source at https://github.com/mapnik/mapnik/blob/master/deps/agg/include/agg_gamma_functions. +* * * + +##### line-dasharray `numbers` + + + +Default Value: none +_(The line will be drawn without dashes.)_ + +A pair of length values [a,b], where (a) is the dash length and (b) is the gap length respectively. More than two values are supported for more complex patterns. +* * * + +##### line-dash-offset `numbers` + + + +Default Value: none +_(The line will be drawn without dashes.)_ + +Valid parameter but not currently used in renderers (only exists for experimental svg support in Mapnik which is not yet enabled). +* * * + +##### line-miterlimit `float` + + + +Default Value: 4 +_(Will auto-convert miters to bevel line joins when theta is less than 29 degrees as per the SVG spec: 'miterLength / stroke-width = 1 / sin ( theta / 2 )'.)_ + +The limit on the ratio of the miter length to the stroke-width. Used to automatically convert miter joins to bevel joins for sharp angles to avoid the miter extending beyond the thickness of the stroking path. Normally will not need to be set, but a larger value can sometimes help avoid jaggy artifacts. +* * * + +##### line-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### line-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify geometries by the given tolerance. +* * * + +##### line-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify geometries by the given algorithm. +* * * + +##### line-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### line-offset `float` + + + +Default Value: 0 +_(Will not be offset.)_ + +Offsets a line a number of pixels parallel to its actual path. Positive values move the line left, negative values move it right (relative to the directionality of the line). +* * * + +##### line-rasterizer `keyword` +`full``fast` + + +Default Value: full +_(The line will be rendered using the highest quality method rather than the fastest.)_ + +Exposes an alternate AGG rendering method that sacrifices some accuracy for speed. +* * * + +##### line-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform line geometry with specified function. +* * * + +##### line-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## markers + +##### marker-file `uri` + + + +Default Value: none +_(An ellipse or circle, if width equals height.)_ + +A file that this marker shows at each placement. If no file is given, the marker will show an ellipse. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### marker-opacity `float` + + + +Default Value: 1 +_(The stroke-opacity and fill-opacity of the marker.)_ + +The overall opacity of the marker, if set, overrides both the opacity of both the fill and stroke. +* * * + +##### marker-fill-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The fill opacity of the marker. +* * * + +##### marker-line-color `color` + + + +Default Value: black +_(The marker will be drawn with a black outline.)_ + +The color of the stroke around the marker. +* * * + +##### marker-line-width `float` + + + +Default Value: 0.5 +_(The marker will be drawn with an outline of .5 pixels wide.)_ + +The width of the stroke around the marker, in pixels. This is positioned on the boundary, so high values can cover the area itself. +* * * + +##### marker-line-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of a line. +* * * + +##### marker-placement `keyword` +`point``line``interior``vertex-first``vertex-last` + + +Default Value: point +_(Place markers at the center point (centroid) of the geometry.)_ + +Attempt to place markers on a point, in the center of a polygon, or if markers-placement:line, then multiple times along a line. 'interior' placement can be used to ensure that points placed on polygons are forced to be inside the polygon interior. The 'vertex-first' and 'vertex-last' options can be used to place markers at the first or last vertex of lines or polygons. +* * * + +##### marker-multi-policy `keyword` +`each``whole``largest` + + +Default Value: each +_(If a feature contains multiple geometries and the placement type is either point or interior then a marker will be rendered for each.)_ + +A special setting to allow the user to control rendering behavior for 'multi-geometries' (when a feature contains multiple geometries). This setting does not apply to markers placed along lines. The 'each' policy is default and means all geometries will get a marker. The 'whole' policy means that the aggregate centroid between all geometries will be used. The 'largest' policy means that only the largest (by bounding box areas) feature will get a rendered marker (this is how text labeling behaves by default). +* * * + +##### marker-type `keyword` +`arrow``ellipse` + + +Default Value: ellipse +_(The marker shape is an ellipse.)_ + +The default marker-type. If a SVG file is not given as the marker-file parameter, the renderer provides either an arrow or an ellipse (a circle if height is equal to width). +* * * + +##### marker-width `float` + + + +Default Value: 10 +_(The marker width is 10 pixels.)_ + +The width of the marker, if using one of the default types. +* * * + +##### marker-height `float` + + + +Default Value: 10 +_(The marker height is 10 pixels.)_ + +The height of the marker, if using one of the default types. +* * * + +##### marker-fill `color` + + + +Default Value: blue +_(The marker fill color is blue.)_ + +The color of the area of the marker. +* * * + +##### marker-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow markers to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping markers are shown or hidden. +* * * + +##### marker-avoid-edges `boolean` + + + +Default Value: false +_(Markers will be potentially placed near tile edges and therefore may look cut off unless they are rendered on each adjacent tile.)_ + +Avoid placing markers that intersect with tile boundaries. +* * * + +##### marker-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache.)_ + +Value to control whether the placement of the feature will prevent the placement of other features. +* * * + +##### marker-spacing `float` + + + +Default Value: 100 +_(In the case of marker-placement:line then draw a marker every 100 pixels along a line.)_ + +Space between repeated markers in pixels. If the spacing is less than the marker size or larger than the line segment length then no marker will be placed. Any value less than 1 will be ignored and the default will be used instead. +* * * + +##### marker-max-error `float` + + + +Default Value: 0.2 +_(N/A: not intended to be changed.)_ + +N/A: not intended to be changed. +* * * + +##### marker-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation.)_ + +Transform marker instance with specified function. Ignores map scale factor. +* * * + +##### marker-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### marker-simplify `float` + + + +Default Value: 0 +_(Geometry will not be simplified.)_ + +geometries are simplified by the given tolerance. +* * * + +##### marker-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +geometries are simplified by the given algorithm. +* * * + +##### marker-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### marker-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform marker geometry with specified function. +* * * + +##### marker-offset `float` + + + +Default Value: 0 +_(Will not be offset.)_ + +Offsets a marker from a line a number of pixels parallel to its actual path. Positive values move the marker left, negative values move it right (relative to the directionality of the line). +* * * + +##### marker-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### marker-direction `keyword` +`auto``auto-down``left``right``left-only``right-only``up``down` + + +Default Value: right +_(Markers are oriented to the right in the line direction.)_ + +How markers should be placed along lines. With the "auto" setting when marker is upside down the marker is automatically rotated by 180 degrees to keep it upright. The "auto-down" value places marker in the opposite orientation to "auto". The "left" or "right" settings can be used to force marker to always be placed along a line in a given direction and therefore disables rotating if marker appears upside down. The "left-only" or "right-only" properties also force a given direction but will discard upside down markers rather than trying to flip it. The "up" and "down" settings don't adjust marker's orientation to the line direction. +* * * + + +## shield + +##### shield-name `string` + + + +Default Value: +_(No text label will be rendered with the shield.)_ + +Value to use for a shield"s text label. Data columns are specified using brackets like [column_name]. +* * * + +##### shield-file `uri` + + + +Default Value: none + + +Image file to render behind the shield text. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### shield-face-name `string` + + + +Default Value: none + + +Font name and style to use for the shield text. +* * * + +##### shield-unlock-image `boolean` + + + +Default Value: false +_(text alignment relative to the shield image uses the center of the image as the anchor for text positioning.)_ + +This parameter should be set to true if you are trying to position text beside rather than on top of the shield image. +* * * + +##### shield-size `float` + + + +Default Value: 10 +_(Font size of 10 will be used to render text.)_ + +The size of the shield text in pixels. +* * * + +##### shield-fill `color` + + + +Default Value: black +_(The shield text will be rendered black.)_ + +The color of the shield text. +* * * + +##### shield-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point +_(One shield will be placed per geometry.)_ + +How this shield should be placed. Point placement places one shield on top of a point geometry and at the centroid of a polygon or the middle point of a line, line places along lines multiple times per feature, vertex places on the vertexes of polygons, and interior attempts to place inside of a polygon. +* * * + +##### shield-avoid-edges `boolean` + + + +Default Value: false +_(Shields will be potentially placed near tile edges and therefore may look cut off unless they are rendered on each adjacent tile.)_ + +Avoid placing shields that intersect with tile boundaries. +* * * + +##### shield-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow shields to overlap with other map elements already placed.)_ + +Control whether overlapping shields are shown or hidden. +* * * + +##### shield-margin `float` + + + +Default Value: 0 +_(No extra margin will be used to determine if a shield collides with any other text, shield, or marker.)_ + +Minimum distance that a shield can be placed from any other text, shield, or marker. +* * * + +##### shield-repeat-distance `float` + + + +Default Value: 0 +_(Shields with the same text will be rendered without restriction.)_ + +Minimum distance between repeated shields. If set this will prevent shields being rendered nearby each other that contain the same text. Similiar to shield-min-distance with the difference that it works the same no matter what placement strategy is used. +* * * + +##### shield-min-distance `float` + + + +Default Value: 0 +_(Shields with the same text will be rendered without restriction.)_ + +Minimum distance to the next shield with the same text. Only works for line placement. +* * * + +##### shield-spacing `float` + + + +Default Value: 0 +_(Only one shield per line will attempt to be placed.)_ + +Distance the renderer should use to try to place repeated shields on a line. +* * * + +##### shield-min-padding `float` + + + +Default Value: 0 +_(No margin will be used to detect if a shield is nearby a tile boundary.)_ + +Minimum distance a shield will be placed from the edge of a tile. This option is similiar to shield-avoid-edges:true except that the extra margin is used to discard cases where the shield+margin are not fully inside the tile. +* * * + +##### shield-label-position-tolerance `float` + + + +Default Value: shield-spacing/2.0 +_(If a shield cannot be placed then the renderer will advance by shield-spacing/2.0 to try placement again.)_ + +Allows the shield to be displaced from its ideal position by a number of pixels (only works with placement:line). +* * * + +##### shield-wrap-width `unsigned` + + + +Default Value: 0 +_(Text will not be wrapped.)_ + +Length of a chunk of text in pixels before wrapping text. If set to zero, text doesn't wrap. +* * * + +##### shield-wrap-before `boolean` + + + +Default Value: false +_(Wrapped lines will be a bit longer than wrap-width.)_ + +Wrap text before wrap-width is reached. +* * * + +##### shield-wrap-character `string` + + + +Default Value: " " +_(Lines will be wrapped when whitespace is encountered.)_ + +Use this character instead of a space to wrap long names. +* * * + +##### shield-halo-fill `color` + + + +Default Value: white +_(The shield halo text will be rendered white.)_ + +Specifies the color of the halo around the text. +* * * + +##### shield-halo-radius `float` + + + +Default Value: 0 +_(no halo.)_ + +Specify the radius of the halo in pixels. +* * * + +##### shield-halo-rasterizer `keyword` +`full``fast` + + +Default Value: full +_(The shield will be rendered using the highest quality method rather than the fastest.)_ + +Exposes an alternate text halo rendering method that sacrifices quality for speed. +* * * + +##### shield-halo-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: +_(No transformation.)_ + +Transform shield halo relative to the actual text with specified function. Allows for shadow or embossed effects. Ignores map scale factor. +* * * + +##### shield-halo-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### shield-halo-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A number from 0 to 1 specifying the opacity for the text halo. +* * * + +##### shield-character-spacing `unsigned` + + + +Default Value: 0 +_(The default character spacing of the font will be used.)_ + +Horizontal spacing between characters (in pixels). Currently works for point placement only, not line placement. +* * * + +##### shield-line-spacing `unsigned` + + + +Default Value: 0 +_(The default font spacing will be used.)_ + +Vertical spacing between lines of multiline labels (in pixels). +* * * + +##### shield-text-dx `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text within shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the shield right. +* * * + +##### shield-text-dy `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text within shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the shield down. +* * * + +##### shield-dx `float` + + + +Default Value: 0 +_(Shield will not be displaced.)_ + +Displace shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right. +* * * + +##### shield-dy `float` + + + +Default Value: 0 +_(Shield will not be displaced.)_ + +Displace shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text down. +* * * + +##### shield-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the image used for the shield. +* * * + +##### shield-text-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the text placed on top of the shield. +* * * + +##### shield-horizontal-alignment `keyword` +`left``middle``right``auto` + + +Default Value: auto +_(TODO.)_ + +The shield's horizontal alignment from its centerpoint. +* * * + +##### shield-vertical-alignment `keyword` +`top``middle``bottom``auto` + + +Default Value: middle +_(TODO.)_ + +The shield's vertical alignment from its centerpoint. +* * * + +##### shield-placement-type `keyword` +`dummy``simple``list` + + +Default Value: dummy +_(Alternative placements will not be enabled.)_ + +Re-position and/or re-size shield to avoid overlaps. "simple" for basic algorithm (using shield-placements string,) "dummy" to turn this feature off. +* * * + +##### shield-placements `string` + + + +Default Value: +_(No alternative placements will be used.)_ + +If "placement-type" is set to "simple", use this "POSITIONS,[SIZES]" string. An example is `shield-placements: "E,NE,SE,W,NW,SW";`. +* * * + +##### shield-text-transform `keyword` +`none``uppercase``lowercase``capitalize``reverse` + + +Default Value: none +_(No text transformation will be applied.)_ + +Transform the case of the characters. +* * * + +##### shield-justify-alignment `keyword` +`left``center``right``auto` + + +Default Value: auto +_(TODO.)_ + +Define how text in a shield's label is justified. +* * * + +##### shield-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation.)_ + +Transform shield instance with specified function. Ignores map scale factor. +* * * + +##### shield-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### shield-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify the geometries used for shield placement by the given tolerance. +* * * + +##### shield-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify the geometries used for shield placement by the given algorithm. +* * * + +##### shield-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out the angles of the geometry used for shield placement. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### shield-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## line-pattern + +##### line-pattern-file `uri` + + + +Default Value: none + + +An image file to be repeated and warped along a line. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### line-pattern-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### line-pattern-opacity `float` + + + +Default Value: 1 +_(The image is rendered without modifications.)_ + +Apply an opacity level to the image used for the pattern. +* * * + +##### line-pattern-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +geometries are simplified by the given tolerance. +* * * + +##### line-pattern-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +geometries are simplified by the given algorithm. +* * * + +##### line-pattern-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### line-pattern-offset `float` + + + +Default Value: 0 +_(The line will not be offset.)_ + +Offsets a line a number of pixels parallel to its actual path. Positive values move the line left, negative values move it right (relative to the directionality of the line). +* * * + +##### line-pattern-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform line geometry with specified function and apply pattern to transformed geometry. +* * * + +##### line-pattern-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## polygon-pattern + +##### polygon-pattern-file `uri` + + + +Default Value: none + + +Image to use as a repeated pattern fill within a polygon. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### polygon-pattern-alignment `keyword` +`global``local` + + +Default Value: global +_(Patterns will be aligned to the map (or tile boundaries) when being repeated across polygons. This is ideal for seamless patterns in tiled rendering.)_ + +Specify whether to align pattern fills to the layer's geometry (local) or to the map (global). +* * * + +##### polygon-pattern-gamma `float` + + + +Default Value: 1 +_(Fully antialiased.)_ +Range: 0-1 +Level of antialiasing of polygon pattern edges. +* * * + +##### polygon-pattern-opacity `float` + + + +Default Value: 1 +_(The image is rendered without modifications.)_ + +Apply an opacity level to the image used for the pattern. +* * * + +##### polygon-pattern-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### polygon-pattern-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +geometries are simplified by the given tolerance. +* * * + +##### polygon-pattern-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +geometries are simplified by the given algorithm. +* * * + +##### polygon-pattern-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### polygon-pattern-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform polygon geometry with specified function and apply pattern to transformed geometry. +* * * + +##### polygon-pattern-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## raster + +##### raster-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the raster symbolizer on top of other symbolizers. +* * * + +##### raster-filter-factor `float` + + + +Default Value: -1 +_(Allow the datasource to choose appropriate downscaling.)_ + +This is used by the Raster or Gdal datasources to pre-downscale images using overviews. Higher numbers can sometimes cause much better scaled image output, at the cost of speed. +* * * + +##### raster-scaling `keyword` +`near``fast``bilinear``bicubic``spline16``spline36``hanning``hamming``hermite``kaiser``quadric``catrom``gaussian``bessel``mitchell``sinc``lanczos``blackman` + + +Default Value: near +_(Nearest neighboor resampling will be used to scale the image to the target size of the map.)_ + +The scaling algorithm used to making different resolution versions of this raster layer. Bilinear is a good compromise between speed and accuracy, while lanczos gives the highest quality. +* * * + +##### raster-mesh-size `unsigned` + + + +Default Value: 16 +_(Reprojection mesh will be 1/16 of the resolution of the source image.)_ + +A reduced resolution mesh is used for raster reprojection, and the total image size is divided by the mesh-size to determine the quality of that mesh. Values for mesh-size larger than the default will result in faster reprojection but might lead to distortion. +* * * + +##### raster-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### raster-colorizer-default-mode `keyword` +`discrete``linear``exact` + + +Default Value: linear +_(A linear interpolation is used to generate colors between the two nearest stops.)_ + +This can be either `discrete`, `linear` or `exact`. If it is not specified then the default is `linear`. +* * * + +##### raster-colorizer-default-color `color` + + + +Default Value: transparent +_(Pixels that are not colored by the colorizer stops will be transparent.)_ + +This can be any color. Sets the color that is applied to all values outside of the range of the colorizer-stops. If not supplied pixels will be fully transparent. +* * * + +##### raster-colorizer-epsilon `float` + + + +Default Value: 1.1920928955078125e-07 +_(Pixels must very closely match the stop filter otherwise they will not be colored.)_ + +This can be any positive floating point value and will be used as a tolerance in floating point comparisions. The higher the value the more likely a stop will match and color data. +* * * + +##### raster-colorizer-stops `tags` + + + +Default Value: +_(No colorization will happen without supplying stops.)_ + +Assigns raster data values to colors. Stops must be listed in ascending order, and contain at a minimum the value and the associated color. You can also include the color-mode as a third argument, like `stop(100,#fff,exact)`. +* * * + + +## point + +##### point-file `uri` + + + +Default Value: none +_(A 4x4 black square will be rendered.)_ + +Image file to represent a point. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### point-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow points to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping points are shown or hidden. +* * * + +##### point-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache.)_ + +Control whether the placement of the feature will prevent the placement of other features. +* * * + +##### point-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A value from 0 to 1 to control the opacity of the point. +* * * + +##### point-placement `keyword` +`centroid``interior` + + +Default Value: centroid +_(The centroid of the geometry will be used to place the point.)_ + +Control how this point should be placed. Centroid calculates the geometric center of a polygon, which can be outside of it, while interior always places inside of a polygon. +* * * + +##### point-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation.)_ + +Transform point instance with specified function. Ignores map scale factor. +* * * + +##### point-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## text + +##### text-name `string` + + + +Default Value: none + + +Value to use for a text label. Data columns are specified using brackets like [column_name]. +* * * + +##### text-face-name `string` + + + +Default Value: none + + +Font name and style to render a label in. +* * * + +##### text-size `float` + + + +Default Value: 10 +_(Font size of 10 will be used to render text.)_ + +Text size in pixels. +* * * + +##### text-ratio `unsigned` + + + +Default Value: 0 +_(TODO.)_ + +Define the amount of text (of the total) present on successive lines when wrapping occurs. +* * * + +##### text-wrap-width `unsigned` + + + +Default Value: 0 +_(Text will not be wrapped.)_ + +Length of a chunk of text in pixels before wrapping text. If set to zero, text doesn't wrap. +* * * + +##### text-wrap-before `boolean` + + + +Default Value: false +_(Wrapped lines will be a bit longer than wrap-width.)_ + +Wrap text before wrap-width is reached. +* * * + +##### text-wrap-character `string` + + + +Default Value: " " +_(Lines will be wrapped when whitespace is encountered.)_ + +Use this character instead of a space to wrap long text. +* * * + +##### text-repeat-wrap-character `boolean` + + + +Default Value: false +_(Character will be removed when used to wrap a line.)_ + +Keep the character used to wrap a line instead of removing it, and repeat it on the new line. +* * * + +##### text-spacing `unsigned` + + + +Default Value: 0 +_(Only one label per line will attempt to be placed.)_ + +Distance the renderer should use to try to place repeated text labels on a line. +* * * + +##### text-character-spacing `float` + + + +Default Value: 0 +_(The default character spacing of the font will be used.)_ + +Horizontal spacing adjustment between characters in pixels. This value is ignored when `horizontal-alignment` is set to `adjust`. Typographic ligatures are turned off when this value is greater than zero. +* * * + +##### text-line-spacing `unsigned` + + + +Default Value: 0 +_(The default font spacing will be used.)_ + +Vertical spacing adjustment between lines in pixels. +* * * + +##### text-label-position-tolerance `float` + + + +Default Value: text-spacing/2.0 +_(If a shield cannot be placed then the renderer will advance by text-spacing/2.0 to try placement again.)_ + +Allows the label to be displaced from its ideal position by a number of pixels (only works with placement:line). +* * * + +##### text-max-char-angle-delta `float` + + + +Default Value: 22.5 +_(The label will not be placed if a character falls on a line with an angle sharper than 22.5 degrees.)_ + +The maximum angle change, in degrees, allowed between adjacent characters in a label. This value internally is converted to radians to the default is 22.5*math.pi/180.0. The higher the value the fewer labels will be placed around around sharp corners. +* * * + +##### text-fill `color` + + + +Default Value: black +_(The text will be rendered black.)_ + +Specifies the color for the text. +* * * + +##### text-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A number from 0 to 1 specifying the opacity for the text. +* * * + +##### text-halo-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A number from 0 to 1 specifying the opacity for the text halo. +* * * + +##### text-halo-fill `color` + + + +Default Value: white +_(The halo will be rendered white.)_ + +Specifies the color of the halo around the text. +* * * + +##### text-halo-radius `float` + + + +Default Value: 0 +_(no halo.)_ + +Specify the radius of the halo in pixels. +* * * + +##### text-halo-rasterizer `keyword` +`full``fast` + + +Default Value: full +_(The text will be rendered using the highest quality method rather than the fastest.)_ + +Exposes an alternate text halo rendering method that sacrifices quality for speed. +* * * + +##### text-halo-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: +_(No transformation.)_ + +Transform text halo relative to the actual text with specified function. Allows for shadow or embossed effects. Ignores map scale factor. +* * * + +##### text-dx `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text by fixed amount, in pixels, +/- along the X axis. With "dummy" placement-type, a positive value displaces to the right. With "simple" placement-type, it is either left, right or unchanged, depending on the placement selected. Any non-zero value implies "horizontal-alignment" changes to "left" by default. Has no effect with 'line' text-placement-type. +* * * + +##### text-dy `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text by fixed amount, in pixels, +/- along the Y axis. With "dummy" placement-type, a positive value displaces downwards. With "simple" placement-type, it is either up, down or unchanged, depending on the placement selected. With "line" placement-type, a positive value displaces above the path. +* * * + +##### text-vertical-alignment `keyword` +`top``middle``bottom``auto` + + +Default Value: auto +_(Default affected by value of dy; "top" for dy>0, "bottom" for dy<0.)_ + +Position of label relative to point position. +* * * + +##### text-avoid-edges `boolean` + + + +Default Value: false +_(Text will be potentially placed near tile edges and therefore may look cut off unless the same text label is rendered on each adjacent tile.)_ + +Avoid placing labels that intersect with tile boundaries. +* * * + +##### text-margin `float` + + + +Default Value: 0 +_(No extra margin will be used to determine if a label collides with any other text, shield, or marker.)_ + +Minimum distance that a label can be placed from any other text, shield, or marker. +* * * + +##### text-repeat-distance `float` + + + +Default Value: 0 +_(Labels with the same text will be rendered without restriction.)_ + +Minimum distance between repeated text. If set this will prevent text labels being rendered nearby each other that contain the same text. Similiar to text-min-distance with the difference that it works the same no matter what placement strategy is used. +* * * + +##### text-min-distance `float` + + + +Default Value: 0 +_(Labels with the same text will be rendered without restriction.)_ + +Minimum distance to the next label with the same text. Only works for line placement. Deprecated: replaced by `text-repeat-distance` and `text-margin` +* * * + +##### text-min-padding `float` + + + +Default Value: 0 +_(No margin will be used to detect if a text label is nearby a tile boundary.)_ + +Minimum distance a text label will be placed from the edge of a tile. This option is similiar to shield-avoid-edges:true except that the extra margin is used to discard cases where the shield+margin are not fully inside the tile. +* * * + +##### text-min-path-length `float` + + + +Default Value: 0 +_(place labels on all geometries no matter how small they are.)_ + +Place labels only on polygons and lines with a bounding width longer than this value (in pixels). +* * * + +##### text-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow text to overlap with other text - overlapping markers will not be shown.)_ + +Control whether overlapping text is shown or hidden. +* * * + +##### text-orientation `float` + + + +Default Value: 0 +_(Text is not rotated and is displayed upright.)_ + +Rotate the text. (only works with text-placement:point). +* * * + +##### text-rotate-displacement `boolean` + + + +Default Value: false +_(Label center is used for rotation.)_ + +Rotates the displacement around the placement origin by the angle given by "orientation". +* * * + +##### text-upright `keyword` +`auto``auto-down``left``right``left-only``right-only` + + +Default Value: auto +_(Text will be positioned upright automatically.)_ + +How this label should be placed along lines. By default when more than half of a label's characters are upside down the label is automatically flipped to keep it upright. By changing this parameter you can prevent this "auto-upright" behavior. The "auto-down" value places text in the opposite orientation to "auto". The "left" or "right" settings can be used to force text to always be placed along a line in a given direction and therefore disables flipping if text appears upside down. The "left-only" or "right-only" properties also force a given direction but will discard upside down text rather than trying to flip it. +* * * + +##### text-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point +_(One shield will be placed per geometry.)_ + +How this label should be placed. Point placement places one label on top of a point geometry and at the centroid of a polygon or the middle point of a line, line places along lines multiple times per feature, vertex places on the vertexes of polygons, and interior attempts to place inside of a polygon. +* * * + +##### text-placement-type `keyword` +`dummy``simple``list` + + +Default Value: dummy +_(Alternative placements will not be enabled.)_ + +Re-position and/or re-size text to avoid overlaps. "simple" for basic algorithm (using text-placements string,) "dummy" to turn this feature off. +* * * + +##### text-placements `string` + + + +Default Value: +_(No alternative placements will be used.)_ + +If "placement-type" is set to "simple", use this "POSITIONS,[SIZES]" string. An example is `text-placements: "E,NE,SE,W,NW,SW";`. +* * * + +##### text-transform `keyword` +`none``uppercase``lowercase``capitalize``reverse` + + +Default Value: none +_(Transform text instance with specified function. Ignores map scale factor.)_ + +Transform the case of the characters. +* * * + +##### text-horizontal-alignment `keyword` +`left``middle``right``auto``adjust` + + +Default Value: auto +_(TODO.)_ + +The text's horizontal alignment from it's centerpoint. If `placement` is set to `line`, then `adjust` can be set to auto-fit the text to the length of the path by dynamically calculating `character-spacing`. +* * * + +##### text-align `keyword` +`left``right``center``auto` + + +Default Value: auto +_(Auto alignment means that text will be centered by default except when using the `placement-type` parameter - in that case either right or left justification will be used automatically depending on where the text could be fit given the `text-placements` directives.)_ + +Define how text is justified. +* * * + +##### text-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### text-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify the geometries used for text placement by the given tolerance. +* * * + +##### text-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify the geometries used for text placement by the given algorithm. +* * * + +##### text-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out the angles of the geometry used for text placement. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### text-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### text-halo-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### text-font-feature-settings `string` + + + +Default Value: +_(Default set of typographic features recommended by OpenType specification. Ligatures are turned off by default when `character-spacing` is greater than zero.)_ + +Comma separated list of OpenType typographic features. The syntax and semantics conforms to `font-feature-settings` from W3C CSS. +* * * + +##### text-largest-bbox-only `boolean` + + + +Default Value: true +_(For multipolygons only polygon with largest bbox area is labeled (does not apply to other geometries).)_ + +Controls default labeling behavior on multipolygons. The default is true and means that only the polygon with largest bbox is labeled. +* * * + + +## building + +##### building-fill `color` + + + +Default Value: The color gray will be used for fill. +_(Gray and fully opaque (alpha = 1), same as rgb(128,128,128) or rgba(128,128,128,1).)_ + +The color of the buildings fill. Note: 0.8 will be used to multiply each color component to auto-generate a darkened wall color. +* * * + +##### building-fill-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the building as a whole, including all walls. +* * * + +##### building-height `float` + + + +Default Value: 0 +_(Buildings will not have a visual height and will instead look like flat polygons.)_ + +The height of the building in pixels. +* * * + + +## debug + +##### debug-mode `string` + + + +Default Value: collision +_(The otherwise invisible collision boxes will be rendered as squares on the map.)_ + +The mode for debug rendering. +* * * + + +## dot + +##### dot-fill `color` + + + +Default Value: gray +_(The dot fill color is gray.)_ + +The color of the area of the dot. +* * * + +##### dot-opacity `float` + + + +Default Value: 1 +_(The opacity of the dot.)_ + +The overall opacity of the dot. +* * * + +##### dot-width `float` + + + +Default Value: 1 +_(The marker width is 1 pixel.)_ + +The width of the dot in pixels. +* * * + +##### dot-height `float` + + + +Default Value: 1 +_(The marker height is 1 pixels.)_ + +The height of the dot in pixels. +* * * + +##### dot-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current layer on top of other layers.)_ + +Composite operation. This defines how this layer should behave relative to layers atop or below it. +* * * + + + + +### Values + +Below is a list of values and an explanation of any expression that can be applied to properties in CartCSS. + +### Color + +CartoCSS accepts a variety of syntaxes for colors - HTML-style hex values, rgb, rgba, hsl, hsla, husl, and husla. It also supports the predefined HTML colors names, like `yellow` and `blue`. + +``` css +#line { +line-color: #ff0; +line-color: #ffff00; +line-color: rgb(255, 255, 0); +line-color: rgba(255, 255, 0, 1); +line-color: hsl(100, 50%, 50%); +line-color: hsla(100, 50%, 50%, 1); +line-color: husl(100, 50%, 50%); // same values yield different color than HSL +line-color: husla(100, 50%, 50%, 1); +line-color: yellow; +} +``` + +Especially of note is the support for hsl and husl, which can be [easier to reason about than rgb()](http://mothereffinghsl.com/). Carto also includes several color operation functions [borrowed from less](http://lesscss.org/functions/#color-operations): + +``` css +// lighten and darken colors +lighten(#ace, 10%); +darken(#ace, 10%); + +// saturate and desaturate +saturate(#550000, 10%); +desaturate(#00ff00, 10%); + +// increase or decrease the opacity of a color +fadein(#fafafa, 10%); +fadeout(#fefefe, 14%); + +// spin rotates a color around the color wheel by degrees +spin(#ff00ff, 10); + +// mix generates a color in between two other colors. +mix(#fff, #000, 50%); + +// get color components +hue(#ff00ff); +saturation(#ff00ff); +lightness(#ff00ff); +alpha(hsla(100, 50%, 50%, 0.5)); +``` + +These functions all take arguments which can be color variables, literal colors, or the results of other functions operating on colors. All the above mentioned functions also come in +a `functionp`-variant (e.g. `lightenp`), which force a given color into perceptual color space. + +### Float + +Float is a fancy way of saying 'number'. In CartoCSS, you specify _just a number_ - unlike CSS, there are no units, but everything is specified in pixels. + +``` css +#line { +line-width: 2; +} +``` + +It's also possible to do simple math with number values: + +``` css +#line { +line-width: 4 / 2; // division +line-width: 4 + 2; // addition +line-width: 4 - 2; // subtraction +line-width: 4 * 2; // multiplication +line-width: 4 % 2; // modulus +} +``` + +### URI + +URI is a fancy way of saying URL. When an argument is a URI, you use the same kind of `url('place.png')` notation that you would with HTML. Quotes around the URL aren't required, but are highly recommended. URIs can be paths to places on your computer, or on the internet. + +```css +#markers { +marker-file: url('marker.png'); +} +``` + +### String + +A string is basically just text. In the case of CartoCSS, you're going to put it in quotes. Strings can be anything, though pay attention to the cases of `text-name` and `shield-name` - they actually will refer to features, which you refer to by putting them in brackets, as seen in the example below. + +```css +#labels { +text-name: "[MY_FIELD]"; +} +``` + +### Boolean + +Boolean means yes or no, so it accepts the values `true` or `false`. + +```css +#markers { +marker-allow-overlap:true; +} +``` + +### Expressions + +Expressions are statements that can include fields, numbers, and other types in a really flexible way. You have run into expressions before, in the realm of 'fields', where you'd specify `"[FIELD]"`, but expressions allow you to drop the quotes and also do quick addition, division, multiplication, and concatenation from within Carto syntax. + +```css +#buildings { +building-height: [HEIGHT_FIELD] * 10; +} +``` + +### Numbers +Numbers are comma-separated lists of one or more number in a specific order. They're used in line dash arrays, in which the numbers specify intervals of line, break, and line again. + +```css +#disputedboundary { +line-dasharray: 1, 4, 2; +} +``` + +### Percentages +In Carto, the percentage symbol, `%` universally means `value/100`. It's meant to be used with ratio-related properties, like opacity rules. + +_You should not use percentages as widths, heights, or other properties - unlike CSS, percentages are not relative to cascaded classes or page size, they're, as stated, simply the value divided by one hundred._ + +```css +#world { +// this syntax +polygon-opacity: 50%; + +// is equivalent to +polygon-opacity: 0.5; +} +``` + +### Functions + +Functions are comma-separated lists of one or more functions. For instance, transforms use the `functions` type to allow for transforms within Carto, which are optionally chainable. + +```css +#point { +point-transform: scale(2, 2); +} +``` diff --git a/docs/3.0.10.md b/docs/3.0.10.md new file mode 100644 index 0000000..ad7ed30 --- /dev/null +++ b/docs/3.0.10.md @@ -0,0 +1,2226 @@ +# Carto documentation + +The following is a list of properties provided in CartoCSS that you can apply to map elements. + +## All elements + +##### image-filters `functions` + +`agg-stack-blur``emboss``blur``gray``sobel``edge-detect``x-gradient``y-gradient``invert``sharpen``color-blind-protanope``color-blind-deuteranope``color-blind-tritanope``colorize-alpha``color-to-alpha``scale-hsla` + +Default Value: none +_(no filters.)_ + +A list of image filters that will be applied to the active rendering canvas for a given style. The presence of one more `image-filters` will trigger a new canvas to be created before starting to render a style and then this canvas will be composited back into the main canvas after rendering all features and after all `image-filters` have been applied. See `direct-image-filters` if you want to apply a filter directly to the main canvas. +* * * + +##### image-filters-inflate `boolean` + + + +Default Value: false +_(No special handling will be done and image filters that blur data will only blur up to the edge of a tile boundary.)_ + +A property that can be set to true to enable using an inflated image internally for seamless blurring across tiles (requires buffered data). +* * * + +##### direct-image-filters `functions` + +`agg-stack-blur``emboss``blur``gray``sobel``edge-detect``x-gradient``y-gradient``invert``sharpen``color-blind-protanope``color-blind-deuteranope``color-blind-tritanope``colorize-alpha``color-to-alpha``scale-hsla` + +Default Value: none +_(no filters.)_ + +A list of image filters to apply to the main canvas (see the `image-filters` doc for how they work on a separate canvas). +* * * + +##### comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current layer on top of other layers.)_ + +Composite operation. This defines how this layer should behave relative to layers atop or below it. +* * * + +##### opacity `float` + + + +Default Value: 1 +_(No separate buffer will be used and no alpha will be applied to the style after rendering.)_ + +An alpha value for the style (which means an alpha applied to all features in separate buffer and then composited back to main buffer). +* * * + + +## map + +##### background-color `color` + + + +Default Value: none +_(Will be rendered transparent.)_ + +Map Background color. +* * * + +##### background-image `uri` + + + +Default Value: +_(No background image will be used.)_ + +An image that is repeated below all features on a map as a background. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### background-image-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(The background-image will be blended with the background normally (placed on top of any existing background-color).)_ + +Set the compositing operation used to blend the image into the background. +* * * + +##### background-image-opacity `float` + + + +Default Value: 1 +_(The image opacity will not be changed when applied to the map background.)_ + +Set the opacity of the image. +* * * + +##### srs `string` + + + +Default Value: +proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs +_(The proj4 literal of EPSG:4326 is assumed to be the Map's spatial reference and all data from layers within this map will be plotted using this coordinate system. If any layers do not declare an srs value then they will be assumed to be in the same srs as the Map and not transformations will be needed to plot them in the Map's coordinate space.)_ + +Map spatial reference (proj4 string). +* * * + +##### buffer-size `float` + + + +Default Value: 0 +_(No buffer will be used.)_ + +Extra tolerance around the map (in pixels) used to ensure labels crossing tile boundaries are equally rendered in each tile (e.g. cut in each tile). Not intended to be used in combination with "avoid-edges". +* * * + +##### maximum-extent `string` + + + +Default Value: -20037508.34,-20037508.34,20037508.34,20037508.34 +_(All data will be clipped to global mercator extent (default is applied in Carto.js).)_ + +An extent to be used to limit the bounds used to query all layers during rendering. Should be minx, miny, maxx, maxy in the coordinates of the Map. +* * * + +##### base `string` + + + +Default Value: +_(This base path defaults to an empty string meaning that any relative paths to files referenced in styles or layers will be interpreted relative to the application process.)_ + +Any relative paths used to reference files will be understood as relative to this directory path if the map is loaded from an in memory object rather than from the filesystem. If the map is loaded from the filesystem and this option is not provided it will be set to the directory of the stylesheet. +* * * + +##### font-directory `uri` + + + +Default Value: none +_(No map-specific fonts will be registered.)_ + +Path to a directory which holds fonts which should be registered when the Map is loaded (in addition to any fonts that may be automatically registered). +* * * + + +## polygon + +##### polygon-fill `color` + + + +Default Value: The color gray will be used for fill. +_(Gray and fully opaque (alpha = 1), same as rgb(128,128,128) or rgba(128,128,128,1).)_ + +Fill color to assign to a polygon. +* * * + +##### polygon-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the polygon. +* * * + +##### polygon-gamma `float` + + + +Default Value: 1 +_(Fully antialiased.)_ +Range: 0-1 +Level of antialiasing of polygon edges. +* * * + +##### polygon-gamma-method `keyword` +`power``linear``none``threshold``multiply` + + +Default Value: power +_(pow(x,gamma) is used to calculate pixel gamma, which produces slightly smoother line and polygon antialiasing than the 'linear' method, while other methods are usually only used to disable AA.)_ + +An Antigrain Geometry specific rendering hint to control the quality of antialiasing. Under the hood in Mapnik this method is used in combination with the 'gamma' value (which defaults to 1). The methods are in the AGG source at https://github.com/mapnik/mapnik/blob/master/deps/agg/include/agg_gamma_functions. +* * * + +##### polygon-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extend outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### polygon-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify geometries by the given tolerance. +* * * + +##### polygon-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify geometries by the given algorithm. +* * * + +##### polygon-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### polygon-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform polygon geometry with specified function. +* * * + +##### polygon-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## line + +##### line-color `color` + + + +Default Value: black +_(black and fully opaque (alpha = 1), same as rgb(0,0,0) or rgba(0,0,0,1).)_ + +The color of a drawn line. +* * * + +##### line-width `float` + + + +Default Value: 1 +_(The line will be rendered 1 pixel wide.)_ + +The width of a line in pixels. +* * * + +##### line-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of a line. +* * * + +##### line-join `keyword` +`miter``miter-revert``round``bevel` + + +Default Value: miter +_(The line joins will be rendered using a miter look.)_ + +The behavior of lines when joining. +* * * + +##### line-cap `keyword` +`butt``round``square` + + +Default Value: butt +_(The line endings will be rendered using a butt look.)_ + +The display of line endings. +* * * + +##### line-gamma `float` + + + +Default Value: 1 +_(Fully antialiased.)_ +Range: 0-1 +Level of antialiasing of stroke line. +* * * + +##### line-gamma-method `keyword` +`power``linear``none``threshold``multiply` + + +Default Value: power +_(pow(x,gamma) is used to calculate pixel gamma, which produces slightly smoother line and polygon antialiasing than the 'linear' method, while other methods are usually only used to disable AA.)_ + +An Antigrain Geometry specific rendering hint to control the quality of antialiasing. Under the hood in Mapnik this method is used in combination with the 'gamma' value (which defaults to 1). The methods are in the AGG source at https://github.com/mapnik/mapnik/blob/master/deps/agg/include/agg_gamma_functions. +* * * + +##### line-dasharray `numbers` + + + +Default Value: none +_(The line will be drawn without dashes.)_ + +A pair of length values [a,b], where (a) is the dash length and (b) is the gap length respectively. More than two values are supported for more complex patterns. +* * * + +##### line-dash-offset `numbers` + + + +Default Value: none +_(The line will be drawn without dashes.)_ + +Valid parameter but not currently used in renderers (only exists for experimental svg support in Mapnik which is not yet enabled). +* * * + +##### line-miterlimit `float` + + + +Default Value: 4 +_(Will auto-convert miters to bevel line joins when theta is less than 29 degrees as per the SVG spec: 'miterLength / stroke-width = 1 / sin ( theta / 2 )'.)_ + +The limit on the ratio of the miter length to the stroke-width. Used to automatically convert miter joins to bevel joins for sharp angles to avoid the miter extending beyond the thickness of the stroking path. Normally will not need to be set, but a larger value can sometimes help avoid jaggy artifacts. +* * * + +##### line-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### line-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify geometries by the given tolerance. +* * * + +##### line-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify geometries by the given algorithm. +* * * + +##### line-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### line-offset `float` + + + +Default Value: 0 +_(Will not be offset.)_ + +Offsets a line a number of pixels parallel to its actual path. Positive values move the line left, negative values move it right (relative to the directionality of the line). +* * * + +##### line-rasterizer `keyword` +`full``fast` + + +Default Value: full +_(The line will be rendered using the highest quality method rather than the fastest.)_ + +Exposes an alternate AGG rendering method that sacrifices some accuracy for speed. +* * * + +##### line-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform line geometry with specified function. +* * * + +##### line-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## markers + +##### marker-file `uri` + + + +Default Value: none +_(An ellipse or circle, if width equals height.)_ + +A file that this marker shows at each placement. If no file is given, the marker will show an ellipse. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### marker-opacity `float` + + + +Default Value: 1 +_(The stroke-opacity and fill-opacity of the marker.)_ + +The overall opacity of the marker, if set, overrides both the opacity of both the fill and stroke. +* * * + +##### marker-fill-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The fill opacity of the marker. +* * * + +##### marker-line-color `color` + + + +Default Value: black +_(The marker will be drawn with a black outline.)_ + +The color of the stroke around the marker. +* * * + +##### marker-line-width `float` + + + +Default Value: 0.5 +_(The marker will be drawn with an outline of .5 pixels wide.)_ + +The width of the stroke around the marker, in pixels. This is positioned on the boundary, so high values can cover the area itself. +* * * + +##### marker-line-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of a line. +* * * + +##### marker-placement `keyword` +`point``line``interior``vertex-first``vertex-last` + + +Default Value: point +_(Place markers at the center point (centroid) of the geometry.)_ + +Attempt to place markers on a point, in the center of a polygon, or if markers-placement:line, then multiple times along a line. 'interior' placement can be used to ensure that points placed on polygons are forced to be inside the polygon interior. The 'vertex-first' and 'vertex-last' options can be used to place markers at the first or last vertex of lines or polygons. +* * * + +##### marker-multi-policy `keyword` +`each``whole``largest` + + +Default Value: each +_(If a feature contains multiple geometries and the placement type is either point or interior then a marker will be rendered for each.)_ + +A special setting to allow the user to control rendering behavior for 'multi-geometries' (when a feature contains multiple geometries). This setting does not apply to markers placed along lines. The 'each' policy is default and means all geometries will get a marker. The 'whole' policy means that the aggregate centroid between all geometries will be used. The 'largest' policy means that only the largest (by bounding box areas) feature will get a rendered marker (this is how text labeling behaves by default). +* * * + +##### marker-type `keyword` +`arrow``ellipse` + + +Default Value: ellipse +_(The marker shape is an ellipse.)_ + +The default marker-type. If a SVG file is not given as the marker-file parameter, the renderer provides either an arrow or an ellipse (a circle if height is equal to width). +* * * + +##### marker-width `float` + + + +Default Value: 10 +_(The marker width is 10 pixels.)_ + +The width of the marker, if using one of the default types. +* * * + +##### marker-height `float` + + + +Default Value: 10 +_(The marker height is 10 pixels.)_ + +The height of the marker, if using one of the default types. +* * * + +##### marker-fill `color` + + + +Default Value: blue +_(The marker fill color is blue.)_ + +The color of the area of the marker. +* * * + +##### marker-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow markers to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping markers are shown or hidden. +* * * + +##### marker-avoid-edges `boolean` + + + +Default Value: false +_(Markers will be potentially placed near tile edges and therefore may look cut off unless they are rendered on each adjacent tile.)_ + +Avoid placing markers that intersect with tile boundaries. +* * * + +##### marker-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache.)_ + +Value to control whether the placement of the feature will prevent the placement of other features. +* * * + +##### marker-spacing `float` + + + +Default Value: 100 +_(In the case of marker-placement:line then draw a marker every 100 pixels along a line.)_ + +Space between repeated markers in pixels. If the spacing is less than the marker size or larger than the line segment length then no marker will be placed. Any value less than 1 will be ignored and the default will be used instead. +* * * + +##### marker-max-error `float` + + + +Default Value: 0.2 +_(N/A: not intended to be changed.)_ + +N/A: not intended to be changed. +* * * + +##### marker-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation.)_ + +Transform marker instance with specified function. Ignores map scale factor. +* * * + +##### marker-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### marker-simplify `float` + + + +Default Value: 0 +_(Geometry will not be simplified.)_ + +geometries are simplified by the given tolerance. +* * * + +##### marker-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +geometries are simplified by the given algorithm. +* * * + +##### marker-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### marker-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform marker geometry with specified function. +* * * + +##### marker-offset `float` + + + +Default Value: 0 +_(Will not be offset.)_ + +Offsets a marker from a line a number of pixels parallel to its actual path. Positive values move the marker left, negative values move it right (relative to the directionality of the line). +* * * + +##### marker-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### marker-direction `keyword` +`auto``auto-down``left``right``left-only``right-only``up``down` + + +Default Value: right +_(Markers are oriented to the right in the line direction.)_ + +How markers should be placed along lines. With the "auto" setting when marker is upside down the marker is automatically rotated by 180 degrees to keep it upright. The "auto-down" value places marker in the opposite orientation to "auto". The "left" or "right" settings can be used to force marker to always be placed along a line in a given direction and therefore disables rotating if marker appears upside down. The "left-only" or "right-only" properties also force a given direction but will discard upside down markers rather than trying to flip it. The "up" and "down" settings don't adjust marker's orientation to the line direction. +* * * + + +## shield + +##### shield-name `string` + + + +Default Value: +_(No text label will be rendered with the shield.)_ + +Value to use for a shield"s text label. Data columns are specified using brackets like [column_name]. +* * * + +##### shield-file `uri` + + + +Default Value: none + + +Image file to render behind the shield text. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### shield-face-name `string` + + + +Default Value: none + + +Font name and style to use for the shield text. +* * * + +##### shield-unlock-image `boolean` + + + +Default Value: false +_(text alignment relative to the shield image uses the center of the image as the anchor for text positioning.)_ + +This parameter should be set to true if you are trying to position text beside rather than on top of the shield image. +* * * + +##### shield-size `float` + + + +Default Value: 10 +_(Font size of 10 will be used to render text.)_ + +The size of the shield text in pixels. +* * * + +##### shield-fill `color` + + + +Default Value: black +_(The shield text will be rendered black.)_ + +The color of the shield text. +* * * + +##### shield-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point +_(One shield will be placed per geometry.)_ + +How this shield should be placed. Point placement places one shield on top of a point geometry and at the centroid of a polygon or the middle point of a line, line places along lines multiple times per feature, vertex places on the vertexes of polygons, and interior attempts to place inside of a polygon. +* * * + +##### shield-avoid-edges `boolean` + + + +Default Value: false +_(Shields will be potentially placed near tile edges and therefore may look cut off unless they are rendered on each adjacent tile.)_ + +Avoid placing shields that intersect with tile boundaries. +* * * + +##### shield-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow shields to overlap with other map elements already placed.)_ + +Control whether overlapping shields are shown or hidden. +* * * + +##### shield-margin `float` + + + +Default Value: 0 +_(No extra margin will be used to determine if a shield collides with any other text, shield, or marker.)_ + +Minimum distance that a shield can be placed from any other text, shield, or marker. +* * * + +##### shield-repeat-distance `float` + + + +Default Value: 0 +_(Shields with the same text will be rendered without restriction.)_ + +Minimum distance between repeated shields. If set this will prevent shields being rendered nearby each other that contain the same text. Similiar to shield-min-distance with the difference that it works the same no matter what placement strategy is used. +* * * + +##### shield-min-distance `float` + + + +Default Value: 0 +_(Shields with the same text will be rendered without restriction.)_ + +Minimum distance to the next shield with the same text. Only works for line placement. +* * * + +##### shield-spacing `float` + + + +Default Value: 0 +_(Only one shield per line will attempt to be placed.)_ + +Distance the renderer should use to try to place repeated shields on a line. +* * * + +##### shield-min-padding `float` + + + +Default Value: 0 +_(No margin will be used to detect if a shield is nearby a tile boundary.)_ + +Minimum distance a shield will be placed from the edge of a tile. This option is similiar to shield-avoid-edges:true except that the extra margin is used to discard cases where the shield+margin are not fully inside the tile. +* * * + +##### shield-label-position-tolerance `float` + + + +Default Value: shield-spacing/2.0 +_(If a shield cannot be placed then the renderer will advance by shield-spacing/2.0 to try placement again.)_ + +Allows the shield to be displaced from its ideal position by a number of pixels (only works with placement:line). +* * * + +##### shield-wrap-width `unsigned` + + + +Default Value: 0 +_(Text will not be wrapped.)_ + +Length of a chunk of text in pixels before wrapping text. If set to zero, text doesn't wrap. +* * * + +##### shield-wrap-before `boolean` + + + +Default Value: false +_(Wrapped lines will be a bit longer than wrap-width.)_ + +Wrap text before wrap-width is reached. +* * * + +##### shield-wrap-character `string` + + + +Default Value: " " +_(Lines will be wrapped when whitespace is encountered.)_ + +Use this character instead of a space to wrap long names. +* * * + +##### shield-halo-fill `color` + + + +Default Value: white +_(The shield halo text will be rendered white.)_ + +Specifies the color of the halo around the text. +* * * + +##### shield-halo-radius `float` + + + +Default Value: 0 +_(no halo.)_ + +Specify the radius of the halo in pixels. +* * * + +##### shield-halo-rasterizer `keyword` +`full``fast` + + +Default Value: full +_(The shield will be rendered using the highest quality method rather than the fastest.)_ + +Exposes an alternate text halo rendering method that sacrifices quality for speed. +* * * + +##### shield-halo-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: +_(No transformation.)_ + +Transform shield halo relative to the actual text with specified function. Allows for shadow or embossed effects. Ignores map scale factor. +* * * + +##### shield-halo-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### shield-halo-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A number from 0 to 1 specifying the opacity for the text halo. +* * * + +##### shield-character-spacing `unsigned` + + + +Default Value: 0 +_(The default character spacing of the font will be used.)_ + +Horizontal spacing between characters (in pixels). Currently works for point placement only, not line placement. +* * * + +##### shield-line-spacing `unsigned` + + + +Default Value: 0 +_(The default font spacing will be used.)_ + +Vertical spacing between lines of multiline labels (in pixels). +* * * + +##### shield-text-dx `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text within shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the shield right. +* * * + +##### shield-text-dy `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text within shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the shield down. +* * * + +##### shield-dx `float` + + + +Default Value: 0 +_(Shield will not be displaced.)_ + +Displace shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right. +* * * + +##### shield-dy `float` + + + +Default Value: 0 +_(Shield will not be displaced.)_ + +Displace shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text down. +* * * + +##### shield-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the image used for the shield. +* * * + +##### shield-text-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the text placed on top of the shield. +* * * + +##### shield-horizontal-alignment `keyword` +`left``middle``right``auto` + + +Default Value: auto +_(TODO.)_ + +The shield's horizontal alignment from its centerpoint. +* * * + +##### shield-vertical-alignment `keyword` +`top``middle``bottom``auto` + + +Default Value: middle +_(TODO.)_ + +The shield's vertical alignment from its centerpoint. +* * * + +##### shield-placement-type `keyword` +`dummy``simple``list` + + +Default Value: dummy +_(Alternative placements will not be enabled.)_ + +Re-position and/or re-size shield to avoid overlaps. "simple" for basic algorithm (using shield-placements string,) "dummy" to turn this feature off. +* * * + +##### shield-placements `string` + + + +Default Value: +_(No alternative placements will be used.)_ + +If "placement-type" is set to "simple", use this "POSITIONS,[SIZES]" string. An example is `shield-placements: "E,NE,SE,W,NW,SW";`. +* * * + +##### shield-text-transform `keyword` +`none``uppercase``lowercase``capitalize``reverse` + + +Default Value: none +_(No text transformation will be applied.)_ + +Transform the case of the characters. +* * * + +##### shield-justify-alignment `keyword` +`left``center``right``auto` + + +Default Value: auto +_(TODO.)_ + +Define how text in a shield's label is justified. +* * * + +##### shield-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation.)_ + +Transform shield instance with specified function. Ignores map scale factor. +* * * + +##### shield-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### shield-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify the geometries used for shield placement by the given tolerance. +* * * + +##### shield-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify the geometries used for shield placement by the given algorithm. +* * * + +##### shield-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out the angles of the geometry used for shield placement. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### shield-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## line-pattern + +##### line-pattern-file `uri` + + + +Default Value: none + + +An image file to be repeated and warped along a line. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### line-pattern-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### line-pattern-opacity `float` + + + +Default Value: 1 +_(The image is rendered without modifications.)_ + +Apply an opacity level to the image used for the pattern. +* * * + +##### line-pattern-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +geometries are simplified by the given tolerance. +* * * + +##### line-pattern-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +geometries are simplified by the given algorithm. +* * * + +##### line-pattern-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### line-pattern-offset `float` + + + +Default Value: 0 +_(The line will not be offset.)_ + +Offsets a line a number of pixels parallel to its actual path. Positive values move the line left, negative values move it right (relative to the directionality of the line). +* * * + +##### line-pattern-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform line geometry with specified function and apply pattern to transformed geometry. +* * * + +##### line-pattern-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## polygon-pattern + +##### polygon-pattern-file `uri` + + + +Default Value: none + + +Image to use as a repeated pattern fill within a polygon. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### polygon-pattern-alignment `keyword` +`global``local` + + +Default Value: global +_(Patterns will be aligned to the map (or tile boundaries) when being repeated across polygons. This is ideal for seamless patterns in tiled rendering.)_ + +Specify whether to align pattern fills to the layer's geometry (local) or to the map (global). +* * * + +##### polygon-pattern-gamma `float` + + + +Default Value: 1 +_(Fully antialiased.)_ +Range: 0-1 +Level of antialiasing of polygon pattern edges. +* * * + +##### polygon-pattern-opacity `float` + + + +Default Value: 1 +_(The image is rendered without modifications.)_ + +Apply an opacity level to the image used for the pattern. +* * * + +##### polygon-pattern-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### polygon-pattern-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +geometries are simplified by the given tolerance. +* * * + +##### polygon-pattern-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +geometries are simplified by the given algorithm. +* * * + +##### polygon-pattern-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### polygon-pattern-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform polygon geometry with specified function and apply pattern to transformed geometry. +* * * + +##### polygon-pattern-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## raster + +##### raster-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the raster symbolizer on top of other symbolizers. +* * * + +##### raster-filter-factor `float` + + + +Default Value: -1 +_(Allow the datasource to choose appropriate downscaling.)_ + +This is used by the Raster or Gdal datasources to pre-downscale images using overviews. Higher numbers can sometimes cause much better scaled image output, at the cost of speed. +* * * + +##### raster-scaling `keyword` +`near``fast``bilinear``bicubic``spline16``spline36``hanning``hamming``hermite``kaiser``quadric``catrom``gaussian``bessel``mitchell``sinc``lanczos``blackman` + + +Default Value: near +_(Nearest neighboor resampling will be used to scale the image to the target size of the map.)_ + +The scaling algorithm used to making different resolution versions of this raster layer. Bilinear is a good compromise between speed and accuracy, while lanczos gives the highest quality. +* * * + +##### raster-mesh-size `unsigned` + + + +Default Value: 16 +_(Reprojection mesh will be 1/16 of the resolution of the source image.)_ + +A reduced resolution mesh is used for raster reprojection, and the total image size is divided by the mesh-size to determine the quality of that mesh. Values for mesh-size larger than the default will result in faster reprojection but might lead to distortion. +* * * + +##### raster-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### raster-colorizer-default-mode `keyword` +`discrete``linear``exact` + + +Default Value: linear +_(A linear interpolation is used to generate colors between the two nearest stops.)_ + +This can be either `discrete`, `linear` or `exact`. If it is not specified then the default is `linear`. +* * * + +##### raster-colorizer-default-color `color` + + + +Default Value: transparent +_(Pixels that are not colored by the colorizer stops will be transparent.)_ + +This can be any color. Sets the color that is applied to all values outside of the range of the colorizer-stops. If not supplied pixels will be fully transparent. +* * * + +##### raster-colorizer-epsilon `float` + + + +Default Value: 1.1920928955078125e-07 +_(Pixels must very closely match the stop filter otherwise they will not be colored.)_ + +This can be any positive floating point value and will be used as a tolerance in floating point comparisions. The higher the value the more likely a stop will match and color data. +* * * + +##### raster-colorizer-stops `tags` + + + +Default Value: +_(No colorization will happen without supplying stops.)_ + +Assigns raster data values to colors. Stops must be listed in ascending order, and contain at a minimum the value and the associated color. You can also include the color-mode as a third argument, like `stop(100,#fff,exact)`. +* * * + + +## point + +##### point-file `uri` + + + +Default Value: none +_(A 4x4 black square will be rendered.)_ + +Image file to represent a point. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### point-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow points to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping points are shown or hidden. +* * * + +##### point-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache.)_ + +Control whether the placement of the feature will prevent the placement of other features. +* * * + +##### point-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A value from 0 to 1 to control the opacity of the point. +* * * + +##### point-placement `keyword` +`centroid``interior` + + +Default Value: centroid +_(The centroid of the geometry will be used to place the point.)_ + +Control how this point should be placed. Centroid calculates the geometric center of a polygon, which can be outside of it, while interior always places inside of a polygon. +* * * + +##### point-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation.)_ + +Transform point instance with specified function. Ignores map scale factor. +* * * + +##### point-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## text + +##### text-name `string` + + + +Default Value: none + + +Value to use for a text label. Data columns are specified using brackets like [column_name]. +* * * + +##### text-face-name `string` + + + +Default Value: none + + +Font name and style to render a label in. +* * * + +##### text-size `float` + + + +Default Value: 10 +_(Font size of 10 will be used to render text.)_ + +Text size in pixels. +* * * + +##### text-ratio `unsigned` + + + +Default Value: 0 +_(TODO.)_ + +Define the amount of text (of the total) present on successive lines when wrapping occurs. +* * * + +##### text-wrap-width `unsigned` + + + +Default Value: 0 +_(Text will not be wrapped.)_ + +Length of a chunk of text in pixels before wrapping text. If set to zero, text doesn't wrap. +* * * + +##### text-wrap-before `boolean` + + + +Default Value: false +_(Wrapped lines will be a bit longer than wrap-width.)_ + +Wrap text before wrap-width is reached. +* * * + +##### text-wrap-character `string` + + + +Default Value: " " +_(Lines will be wrapped when whitespace is encountered.)_ + +Use this character instead of a space to wrap long text. +* * * + +##### text-repeat-wrap-character `boolean` + + + +Default Value: false +_(Character will be removed when used to wrap a line.)_ + +Keep the character used to wrap a line instead of removing it, and repeat it on the new line. +* * * + +##### text-spacing `unsigned` + + + +Default Value: 0 +_(Only one label per line will attempt to be placed.)_ + +Distance the renderer should use to try to place repeated text labels on a line. +* * * + +##### text-character-spacing `float` + + + +Default Value: 0 +_(The default character spacing of the font will be used.)_ + +Horizontal spacing adjustment between characters in pixels. This value is ignored when `horizontal-alignment` is set to `adjust`. Typographic ligatures are turned off when this value is greater than zero. +* * * + +##### text-line-spacing `unsigned` + + + +Default Value: 0 +_(The default font spacing will be used.)_ + +Vertical spacing adjustment between lines in pixels. +* * * + +##### text-label-position-tolerance `float` + + + +Default Value: text-spacing/2.0 +_(If a shield cannot be placed then the renderer will advance by text-spacing/2.0 to try placement again.)_ + +Allows the label to be displaced from its ideal position by a number of pixels (only works with placement:line). +* * * + +##### text-max-char-angle-delta `float` + + + +Default Value: 22.5 +_(The label will not be placed if a character falls on a line with an angle sharper than 22.5 degrees.)_ + +The maximum angle change, in degrees, allowed between adjacent characters in a label. This value internally is converted to radians to the default is 22.5*math.pi/180.0. The higher the value the fewer labels will be placed around around sharp corners. +* * * + +##### text-fill `color` + + + +Default Value: black +_(The text will be rendered black.)_ + +Specifies the color for the text. +* * * + +##### text-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A number from 0 to 1 specifying the opacity for the text. +* * * + +##### text-halo-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A number from 0 to 1 specifying the opacity for the text halo. +* * * + +##### text-halo-fill `color` + + + +Default Value: white +_(The halo will be rendered white.)_ + +Specifies the color of the halo around the text. +* * * + +##### text-halo-radius `float` + + + +Default Value: 0 +_(no halo.)_ + +Specify the radius of the halo in pixels. +* * * + +##### text-halo-rasterizer `keyword` +`full``fast` + + +Default Value: full +_(The text will be rendered using the highest quality method rather than the fastest.)_ + +Exposes an alternate text halo rendering method that sacrifices quality for speed. +* * * + +##### text-halo-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: +_(No transformation.)_ + +Transform text halo relative to the actual text with specified function. Allows for shadow or embossed effects. Ignores map scale factor. +* * * + +##### text-dx `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text by fixed amount, in pixels, +/- along the X axis. With "dummy" placement-type, a positive value displaces to the right. With "simple" placement-type, it is either left, right or unchanged, depending on the placement selected. Any non-zero value implies "horizontal-alignment" changes to "left" by default. Has no effect with 'line' text-placement-type. +* * * + +##### text-dy `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text by fixed amount, in pixels, +/- along the Y axis. With "dummy" placement-type, a positive value displaces downwards. With "simple" placement-type, it is either up, down or unchanged, depending on the placement selected. With "line" placement-type, a positive value displaces above the path. +* * * + +##### text-vertical-alignment `keyword` +`top``middle``bottom``auto` + + +Default Value: auto +_(Default affected by value of dy; "top" for dy>0, "bottom" for dy<0.)_ + +Position of label relative to point position. +* * * + +##### text-avoid-edges `boolean` + + + +Default Value: false +_(Text will be potentially placed near tile edges and therefore may look cut off unless the same text label is rendered on each adjacent tile.)_ + +Avoid placing labels that intersect with tile boundaries. +* * * + +##### text-margin `float` + + + +Default Value: 0 +_(No extra margin will be used to determine if a label collides with any other text, shield, or marker.)_ + +Minimum distance that a label can be placed from any other text, shield, or marker. +* * * + +##### text-repeat-distance `float` + + + +Default Value: 0 +_(Labels with the same text will be rendered without restriction.)_ + +Minimum distance between repeated text. If set this will prevent text labels being rendered nearby each other that contain the same text. Similiar to text-min-distance with the difference that it works the same no matter what placement strategy is used. +* * * + +##### text-min-distance `float` + + + +Default Value: 0 +_(Labels with the same text will be rendered without restriction.)_ + +Minimum distance to the next label with the same text. Only works for line placement. Deprecated: replaced by `text-repeat-distance` and `text-margin` +* * * + +##### text-min-padding `float` + + + +Default Value: 0 +_(No margin will be used to detect if a text label is nearby a tile boundary.)_ + +Minimum distance a text label will be placed from the edge of a tile. This option is similiar to shield-avoid-edges:true except that the extra margin is used to discard cases where the shield+margin are not fully inside the tile. +* * * + +##### text-min-path-length `float` + + + +Default Value: 0 +_(place labels on all geometries no matter how small they are.)_ + +Place labels only on polygons and lines with a bounding width longer than this value (in pixels). +* * * + +##### text-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow text to overlap with other text - overlapping markers will not be shown.)_ + +Control whether overlapping text is shown or hidden. +* * * + +##### text-orientation `float` + + + +Default Value: 0 +_(Text is not rotated and is displayed upright.)_ + +Rotate the text. (only works with text-placement:point). +* * * + +##### text-rotate-displacement `boolean` + + + +Default Value: false +_(Label center is used for rotation.)_ + +Rotates the displacement around the placement origin by the angle given by "orientation". +* * * + +##### text-upright `keyword` +`auto``auto-down``left``right``left-only``right-only` + + +Default Value: auto +_(Text will be positioned upright automatically.)_ + +How this label should be placed along lines. By default when more than half of a label's characters are upside down the label is automatically flipped to keep it upright. By changing this parameter you can prevent this "auto-upright" behavior. The "auto-down" value places text in the opposite orientation to "auto". The "left" or "right" settings can be used to force text to always be placed along a line in a given direction and therefore disables flipping if text appears upside down. The "left-only" or "right-only" properties also force a given direction but will discard upside down text rather than trying to flip it. +* * * + +##### text-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point +_(One shield will be placed per geometry.)_ + +How this label should be placed. Point placement places one label on top of a point geometry and at the centroid of a polygon or the middle point of a line, line places along lines multiple times per feature, vertex places on the vertexes of polygons, and interior attempts to place inside of a polygon. +* * * + +##### text-placement-type `keyword` +`dummy``simple``list` + + +Default Value: dummy +_(Alternative placements will not be enabled.)_ + +Re-position and/or re-size text to avoid overlaps. "simple" for basic algorithm (using text-placements string,) "dummy" to turn this feature off. +* * * + +##### text-placements `string` + + + +Default Value: +_(No alternative placements will be used.)_ + +If "placement-type" is set to "simple", use this "POSITIONS,[SIZES]" string. An example is `text-placements: "E,NE,SE,W,NW,SW";`. +* * * + +##### text-transform `keyword` +`none``uppercase``lowercase``capitalize``reverse` + + +Default Value: none +_(Transform text instance with specified function. Ignores map scale factor.)_ + +Transform the case of the characters. +* * * + +##### text-horizontal-alignment `keyword` +`left``middle``right``auto``adjust` + + +Default Value: auto +_(TODO.)_ + +The text's horizontal alignment from it's centerpoint. If `placement` is set to `line`, then `adjust` can be set to auto-fit the text to the length of the path by dynamically calculating `character-spacing`. +* * * + +##### text-align `keyword` +`left``right``center``auto` + + +Default Value: auto +_(Auto alignment means that text will be centered by default except when using the `placement-type` parameter - in that case either right or left justification will be used automatically depending on where the text could be fit given the `text-placements` directives.)_ + +Define how text is justified. +* * * + +##### text-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### text-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify the geometries used for text placement by the given tolerance. +* * * + +##### text-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify the geometries used for text placement by the given algorithm. +* * * + +##### text-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out the angles of the geometry used for text placement. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### text-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### text-halo-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### text-font-feature-settings `string` + + + +Default Value: +_(Default set of typographic features recommended by OpenType specification. Ligatures are turned off by default when `character-spacing` is greater than zero.)_ + +Comma separated list of OpenType typographic features. The syntax and semantics conforms to `font-feature-settings` from W3C CSS. +* * * + +##### text-largest-bbox-only `boolean` + + + +Default Value: true +_(For multipolygons only polygon with largest bbox area is labeled (does not apply to other geometries).)_ + +Controls default labeling behavior on multipolygons. The default is true and means that only the polygon with largest bbox is labeled. +* * * + + +## building + +##### building-fill `color` + + + +Default Value: The color gray will be used for fill. +_(Gray and fully opaque (alpha = 1), same as rgb(128,128,128) or rgba(128,128,128,1).)_ + +The color of the buildings fill. Note: 0.8 will be used to multiply each color component to auto-generate a darkened wall color. +* * * + +##### building-fill-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the building as a whole, including all walls. +* * * + +##### building-height `float` + + + +Default Value: 0 +_(Buildings will not have a visual height and will instead look like flat polygons.)_ + +The height of the building in pixels. +* * * + + +## debug + +##### debug-mode `string` + + + +Default Value: collision +_(The otherwise invisible collision boxes will be rendered as squares on the map.)_ + +The mode for debug rendering. +* * * + + +## dot + +##### dot-fill `color` + + + +Default Value: gray +_(The dot fill color is gray.)_ + +The color of the area of the dot. +* * * + +##### dot-opacity `float` + + + +Default Value: 1 +_(The opacity of the dot.)_ + +The overall opacity of the dot. +* * * + +##### dot-width `float` + + + +Default Value: 1 +_(The marker width is 1 pixel.)_ + +The width of the dot in pixels. +* * * + +##### dot-height `float` + + + +Default Value: 1 +_(The marker height is 1 pixels.)_ + +The height of the dot in pixels. +* * * + +##### dot-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current layer on top of other layers.)_ + +Composite operation. This defines how this layer should behave relative to layers atop or below it. +* * * + + + + +### Values + +Below is a list of values and an explanation of any expression that can be applied to properties in CartCSS. + +### Color + +CartoCSS accepts a variety of syntaxes for colors - HTML-style hex values, rgb, rgba, hsl, hsla, husl, and husla. It also supports the predefined HTML colors names, like `yellow` and `blue`. + +``` css +#line { +line-color: #ff0; +line-color: #ffff00; +line-color: rgb(255, 255, 0); +line-color: rgba(255, 255, 0, 1); +line-color: hsl(100, 50%, 50%); +line-color: hsla(100, 50%, 50%, 1); +line-color: husl(100, 50%, 50%); // same values yield different color than HSL +line-color: husla(100, 50%, 50%, 1); +line-color: yellow; +} +``` + +Especially of note is the support for hsl and husl, which can be [easier to reason about than rgb()](http://mothereffinghsl.com/). Carto also includes several color operation functions [borrowed from less](http://lesscss.org/functions/#color-operations): + +``` css +// lighten and darken colors +lighten(#ace, 10%); +darken(#ace, 10%); + +// saturate and desaturate +saturate(#550000, 10%); +desaturate(#00ff00, 10%); + +// increase or decrease the opacity of a color +fadein(#fafafa, 10%); +fadeout(#fefefe, 14%); + +// spin rotates a color around the color wheel by degrees +spin(#ff00ff, 10); + +// mix generates a color in between two other colors. +mix(#fff, #000, 50%); + +// get color components +hue(#ff00ff); +saturation(#ff00ff); +lightness(#ff00ff); +alpha(hsla(100, 50%, 50%, 0.5)); +``` + +These functions all take arguments which can be color variables, literal colors, or the results of other functions operating on colors. All the above mentioned functions also come in +a `functionp`-variant (e.g. `lightenp`), which force a given color into perceptual color space. + +### Float + +Float is a fancy way of saying 'number'. In CartoCSS, you specify _just a number_ - unlike CSS, there are no units, but everything is specified in pixels. + +``` css +#line { +line-width: 2; +} +``` + +It's also possible to do simple math with number values: + +``` css +#line { +line-width: 4 / 2; // division +line-width: 4 + 2; // addition +line-width: 4 - 2; // subtraction +line-width: 4 * 2; // multiplication +line-width: 4 % 2; // modulus +} +``` + +### URI + +URI is a fancy way of saying URL. When an argument is a URI, you use the same kind of `url('place.png')` notation that you would with HTML. Quotes around the URL aren't required, but are highly recommended. URIs can be paths to places on your computer, or on the internet. + +```css +#markers { +marker-file: url('marker.png'); +} +``` + +### String + +A string is basically just text. In the case of CartoCSS, you're going to put it in quotes. Strings can be anything, though pay attention to the cases of `text-name` and `shield-name` - they actually will refer to features, which you refer to by putting them in brackets, as seen in the example below. + +```css +#labels { +text-name: "[MY_FIELD]"; +} +``` + +### Boolean + +Boolean means yes or no, so it accepts the values `true` or `false`. + +```css +#markers { +marker-allow-overlap:true; +} +``` + +### Expressions + +Expressions are statements that can include fields, numbers, and other types in a really flexible way. You have run into expressions before, in the realm of 'fields', where you'd specify `"[FIELD]"`, but expressions allow you to drop the quotes and also do quick addition, division, multiplication, and concatenation from within Carto syntax. + +```css +#buildings { +building-height: [HEIGHT_FIELD] * 10; +} +``` + +### Numbers +Numbers are comma-separated lists of one or more number in a specific order. They're used in line dash arrays, in which the numbers specify intervals of line, break, and line again. + +```css +#disputedboundary { +line-dasharray: 1, 4, 2; +} +``` + +### Percentages +In Carto, the percentage symbol, `%` universally means `value/100`. It's meant to be used with ratio-related properties, like opacity rules. + +_You should not use percentages as widths, heights, or other properties - unlike CSS, percentages are not relative to cascaded classes or page size, they're, as stated, simply the value divided by one hundred._ + +```css +#world { +// this syntax +polygon-opacity: 50%; + +// is equivalent to +polygon-opacity: 0.5; +} +``` + +### Functions + +Functions are comma-separated lists of one or more functions. For instance, transforms use the `functions` type to allow for transforms within Carto, which are optionally chainable. + +```css +#point { +point-transform: scale(2, 2); +} +``` diff --git a/docs/3.0.3.md b/docs/3.0.3.md new file mode 100644 index 0000000..ad7ed30 --- /dev/null +++ b/docs/3.0.3.md @@ -0,0 +1,2226 @@ +# Carto documentation + +The following is a list of properties provided in CartoCSS that you can apply to map elements. + +## All elements + +##### image-filters `functions` + +`agg-stack-blur``emboss``blur``gray``sobel``edge-detect``x-gradient``y-gradient``invert``sharpen``color-blind-protanope``color-blind-deuteranope``color-blind-tritanope``colorize-alpha``color-to-alpha``scale-hsla` + +Default Value: none +_(no filters.)_ + +A list of image filters that will be applied to the active rendering canvas for a given style. The presence of one more `image-filters` will trigger a new canvas to be created before starting to render a style and then this canvas will be composited back into the main canvas after rendering all features and after all `image-filters` have been applied. See `direct-image-filters` if you want to apply a filter directly to the main canvas. +* * * + +##### image-filters-inflate `boolean` + + + +Default Value: false +_(No special handling will be done and image filters that blur data will only blur up to the edge of a tile boundary.)_ + +A property that can be set to true to enable using an inflated image internally for seamless blurring across tiles (requires buffered data). +* * * + +##### direct-image-filters `functions` + +`agg-stack-blur``emboss``blur``gray``sobel``edge-detect``x-gradient``y-gradient``invert``sharpen``color-blind-protanope``color-blind-deuteranope``color-blind-tritanope``colorize-alpha``color-to-alpha``scale-hsla` + +Default Value: none +_(no filters.)_ + +A list of image filters to apply to the main canvas (see the `image-filters` doc for how they work on a separate canvas). +* * * + +##### comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current layer on top of other layers.)_ + +Composite operation. This defines how this layer should behave relative to layers atop or below it. +* * * + +##### opacity `float` + + + +Default Value: 1 +_(No separate buffer will be used and no alpha will be applied to the style after rendering.)_ + +An alpha value for the style (which means an alpha applied to all features in separate buffer and then composited back to main buffer). +* * * + + +## map + +##### background-color `color` + + + +Default Value: none +_(Will be rendered transparent.)_ + +Map Background color. +* * * + +##### background-image `uri` + + + +Default Value: +_(No background image will be used.)_ + +An image that is repeated below all features on a map as a background. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### background-image-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(The background-image will be blended with the background normally (placed on top of any existing background-color).)_ + +Set the compositing operation used to blend the image into the background. +* * * + +##### background-image-opacity `float` + + + +Default Value: 1 +_(The image opacity will not be changed when applied to the map background.)_ + +Set the opacity of the image. +* * * + +##### srs `string` + + + +Default Value: +proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs +_(The proj4 literal of EPSG:4326 is assumed to be the Map's spatial reference and all data from layers within this map will be plotted using this coordinate system. If any layers do not declare an srs value then they will be assumed to be in the same srs as the Map and not transformations will be needed to plot them in the Map's coordinate space.)_ + +Map spatial reference (proj4 string). +* * * + +##### buffer-size `float` + + + +Default Value: 0 +_(No buffer will be used.)_ + +Extra tolerance around the map (in pixels) used to ensure labels crossing tile boundaries are equally rendered in each tile (e.g. cut in each tile). Not intended to be used in combination with "avoid-edges". +* * * + +##### maximum-extent `string` + + + +Default Value: -20037508.34,-20037508.34,20037508.34,20037508.34 +_(All data will be clipped to global mercator extent (default is applied in Carto.js).)_ + +An extent to be used to limit the bounds used to query all layers during rendering. Should be minx, miny, maxx, maxy in the coordinates of the Map. +* * * + +##### base `string` + + + +Default Value: +_(This base path defaults to an empty string meaning that any relative paths to files referenced in styles or layers will be interpreted relative to the application process.)_ + +Any relative paths used to reference files will be understood as relative to this directory path if the map is loaded from an in memory object rather than from the filesystem. If the map is loaded from the filesystem and this option is not provided it will be set to the directory of the stylesheet. +* * * + +##### font-directory `uri` + + + +Default Value: none +_(No map-specific fonts will be registered.)_ + +Path to a directory which holds fonts which should be registered when the Map is loaded (in addition to any fonts that may be automatically registered). +* * * + + +## polygon + +##### polygon-fill `color` + + + +Default Value: The color gray will be used for fill. +_(Gray and fully opaque (alpha = 1), same as rgb(128,128,128) or rgba(128,128,128,1).)_ + +Fill color to assign to a polygon. +* * * + +##### polygon-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the polygon. +* * * + +##### polygon-gamma `float` + + + +Default Value: 1 +_(Fully antialiased.)_ +Range: 0-1 +Level of antialiasing of polygon edges. +* * * + +##### polygon-gamma-method `keyword` +`power``linear``none``threshold``multiply` + + +Default Value: power +_(pow(x,gamma) is used to calculate pixel gamma, which produces slightly smoother line and polygon antialiasing than the 'linear' method, while other methods are usually only used to disable AA.)_ + +An Antigrain Geometry specific rendering hint to control the quality of antialiasing. Under the hood in Mapnik this method is used in combination with the 'gamma' value (which defaults to 1). The methods are in the AGG source at https://github.com/mapnik/mapnik/blob/master/deps/agg/include/agg_gamma_functions. +* * * + +##### polygon-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extend outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### polygon-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify geometries by the given tolerance. +* * * + +##### polygon-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify geometries by the given algorithm. +* * * + +##### polygon-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### polygon-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform polygon geometry with specified function. +* * * + +##### polygon-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## line + +##### line-color `color` + + + +Default Value: black +_(black and fully opaque (alpha = 1), same as rgb(0,0,0) or rgba(0,0,0,1).)_ + +The color of a drawn line. +* * * + +##### line-width `float` + + + +Default Value: 1 +_(The line will be rendered 1 pixel wide.)_ + +The width of a line in pixels. +* * * + +##### line-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of a line. +* * * + +##### line-join `keyword` +`miter``miter-revert``round``bevel` + + +Default Value: miter +_(The line joins will be rendered using a miter look.)_ + +The behavior of lines when joining. +* * * + +##### line-cap `keyword` +`butt``round``square` + + +Default Value: butt +_(The line endings will be rendered using a butt look.)_ + +The display of line endings. +* * * + +##### line-gamma `float` + + + +Default Value: 1 +_(Fully antialiased.)_ +Range: 0-1 +Level of antialiasing of stroke line. +* * * + +##### line-gamma-method `keyword` +`power``linear``none``threshold``multiply` + + +Default Value: power +_(pow(x,gamma) is used to calculate pixel gamma, which produces slightly smoother line and polygon antialiasing than the 'linear' method, while other methods are usually only used to disable AA.)_ + +An Antigrain Geometry specific rendering hint to control the quality of antialiasing. Under the hood in Mapnik this method is used in combination with the 'gamma' value (which defaults to 1). The methods are in the AGG source at https://github.com/mapnik/mapnik/blob/master/deps/agg/include/agg_gamma_functions. +* * * + +##### line-dasharray `numbers` + + + +Default Value: none +_(The line will be drawn without dashes.)_ + +A pair of length values [a,b], where (a) is the dash length and (b) is the gap length respectively. More than two values are supported for more complex patterns. +* * * + +##### line-dash-offset `numbers` + + + +Default Value: none +_(The line will be drawn without dashes.)_ + +Valid parameter but not currently used in renderers (only exists for experimental svg support in Mapnik which is not yet enabled). +* * * + +##### line-miterlimit `float` + + + +Default Value: 4 +_(Will auto-convert miters to bevel line joins when theta is less than 29 degrees as per the SVG spec: 'miterLength / stroke-width = 1 / sin ( theta / 2 )'.)_ + +The limit on the ratio of the miter length to the stroke-width. Used to automatically convert miter joins to bevel joins for sharp angles to avoid the miter extending beyond the thickness of the stroking path. Normally will not need to be set, but a larger value can sometimes help avoid jaggy artifacts. +* * * + +##### line-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### line-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify geometries by the given tolerance. +* * * + +##### line-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify geometries by the given algorithm. +* * * + +##### line-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### line-offset `float` + + + +Default Value: 0 +_(Will not be offset.)_ + +Offsets a line a number of pixels parallel to its actual path. Positive values move the line left, negative values move it right (relative to the directionality of the line). +* * * + +##### line-rasterizer `keyword` +`full``fast` + + +Default Value: full +_(The line will be rendered using the highest quality method rather than the fastest.)_ + +Exposes an alternate AGG rendering method that sacrifices some accuracy for speed. +* * * + +##### line-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform line geometry with specified function. +* * * + +##### line-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## markers + +##### marker-file `uri` + + + +Default Value: none +_(An ellipse or circle, if width equals height.)_ + +A file that this marker shows at each placement. If no file is given, the marker will show an ellipse. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### marker-opacity `float` + + + +Default Value: 1 +_(The stroke-opacity and fill-opacity of the marker.)_ + +The overall opacity of the marker, if set, overrides both the opacity of both the fill and stroke. +* * * + +##### marker-fill-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The fill opacity of the marker. +* * * + +##### marker-line-color `color` + + + +Default Value: black +_(The marker will be drawn with a black outline.)_ + +The color of the stroke around the marker. +* * * + +##### marker-line-width `float` + + + +Default Value: 0.5 +_(The marker will be drawn with an outline of .5 pixels wide.)_ + +The width of the stroke around the marker, in pixels. This is positioned on the boundary, so high values can cover the area itself. +* * * + +##### marker-line-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of a line. +* * * + +##### marker-placement `keyword` +`point``line``interior``vertex-first``vertex-last` + + +Default Value: point +_(Place markers at the center point (centroid) of the geometry.)_ + +Attempt to place markers on a point, in the center of a polygon, or if markers-placement:line, then multiple times along a line. 'interior' placement can be used to ensure that points placed on polygons are forced to be inside the polygon interior. The 'vertex-first' and 'vertex-last' options can be used to place markers at the first or last vertex of lines or polygons. +* * * + +##### marker-multi-policy `keyword` +`each``whole``largest` + + +Default Value: each +_(If a feature contains multiple geometries and the placement type is either point or interior then a marker will be rendered for each.)_ + +A special setting to allow the user to control rendering behavior for 'multi-geometries' (when a feature contains multiple geometries). This setting does not apply to markers placed along lines. The 'each' policy is default and means all geometries will get a marker. The 'whole' policy means that the aggregate centroid between all geometries will be used. The 'largest' policy means that only the largest (by bounding box areas) feature will get a rendered marker (this is how text labeling behaves by default). +* * * + +##### marker-type `keyword` +`arrow``ellipse` + + +Default Value: ellipse +_(The marker shape is an ellipse.)_ + +The default marker-type. If a SVG file is not given as the marker-file parameter, the renderer provides either an arrow or an ellipse (a circle if height is equal to width). +* * * + +##### marker-width `float` + + + +Default Value: 10 +_(The marker width is 10 pixels.)_ + +The width of the marker, if using one of the default types. +* * * + +##### marker-height `float` + + + +Default Value: 10 +_(The marker height is 10 pixels.)_ + +The height of the marker, if using one of the default types. +* * * + +##### marker-fill `color` + + + +Default Value: blue +_(The marker fill color is blue.)_ + +The color of the area of the marker. +* * * + +##### marker-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow markers to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping markers are shown or hidden. +* * * + +##### marker-avoid-edges `boolean` + + + +Default Value: false +_(Markers will be potentially placed near tile edges and therefore may look cut off unless they are rendered on each adjacent tile.)_ + +Avoid placing markers that intersect with tile boundaries. +* * * + +##### marker-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache.)_ + +Value to control whether the placement of the feature will prevent the placement of other features. +* * * + +##### marker-spacing `float` + + + +Default Value: 100 +_(In the case of marker-placement:line then draw a marker every 100 pixels along a line.)_ + +Space between repeated markers in pixels. If the spacing is less than the marker size or larger than the line segment length then no marker will be placed. Any value less than 1 will be ignored and the default will be used instead. +* * * + +##### marker-max-error `float` + + + +Default Value: 0.2 +_(N/A: not intended to be changed.)_ + +N/A: not intended to be changed. +* * * + +##### marker-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation.)_ + +Transform marker instance with specified function. Ignores map scale factor. +* * * + +##### marker-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### marker-simplify `float` + + + +Default Value: 0 +_(Geometry will not be simplified.)_ + +geometries are simplified by the given tolerance. +* * * + +##### marker-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +geometries are simplified by the given algorithm. +* * * + +##### marker-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### marker-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform marker geometry with specified function. +* * * + +##### marker-offset `float` + + + +Default Value: 0 +_(Will not be offset.)_ + +Offsets a marker from a line a number of pixels parallel to its actual path. Positive values move the marker left, negative values move it right (relative to the directionality of the line). +* * * + +##### marker-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### marker-direction `keyword` +`auto``auto-down``left``right``left-only``right-only``up``down` + + +Default Value: right +_(Markers are oriented to the right in the line direction.)_ + +How markers should be placed along lines. With the "auto" setting when marker is upside down the marker is automatically rotated by 180 degrees to keep it upright. The "auto-down" value places marker in the opposite orientation to "auto". The "left" or "right" settings can be used to force marker to always be placed along a line in a given direction and therefore disables rotating if marker appears upside down. The "left-only" or "right-only" properties also force a given direction but will discard upside down markers rather than trying to flip it. The "up" and "down" settings don't adjust marker's orientation to the line direction. +* * * + + +## shield + +##### shield-name `string` + + + +Default Value: +_(No text label will be rendered with the shield.)_ + +Value to use for a shield"s text label. Data columns are specified using brackets like [column_name]. +* * * + +##### shield-file `uri` + + + +Default Value: none + + +Image file to render behind the shield text. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### shield-face-name `string` + + + +Default Value: none + + +Font name and style to use for the shield text. +* * * + +##### shield-unlock-image `boolean` + + + +Default Value: false +_(text alignment relative to the shield image uses the center of the image as the anchor for text positioning.)_ + +This parameter should be set to true if you are trying to position text beside rather than on top of the shield image. +* * * + +##### shield-size `float` + + + +Default Value: 10 +_(Font size of 10 will be used to render text.)_ + +The size of the shield text in pixels. +* * * + +##### shield-fill `color` + + + +Default Value: black +_(The shield text will be rendered black.)_ + +The color of the shield text. +* * * + +##### shield-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point +_(One shield will be placed per geometry.)_ + +How this shield should be placed. Point placement places one shield on top of a point geometry and at the centroid of a polygon or the middle point of a line, line places along lines multiple times per feature, vertex places on the vertexes of polygons, and interior attempts to place inside of a polygon. +* * * + +##### shield-avoid-edges `boolean` + + + +Default Value: false +_(Shields will be potentially placed near tile edges and therefore may look cut off unless they are rendered on each adjacent tile.)_ + +Avoid placing shields that intersect with tile boundaries. +* * * + +##### shield-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow shields to overlap with other map elements already placed.)_ + +Control whether overlapping shields are shown or hidden. +* * * + +##### shield-margin `float` + + + +Default Value: 0 +_(No extra margin will be used to determine if a shield collides with any other text, shield, or marker.)_ + +Minimum distance that a shield can be placed from any other text, shield, or marker. +* * * + +##### shield-repeat-distance `float` + + + +Default Value: 0 +_(Shields with the same text will be rendered without restriction.)_ + +Minimum distance between repeated shields. If set this will prevent shields being rendered nearby each other that contain the same text. Similiar to shield-min-distance with the difference that it works the same no matter what placement strategy is used. +* * * + +##### shield-min-distance `float` + + + +Default Value: 0 +_(Shields with the same text will be rendered without restriction.)_ + +Minimum distance to the next shield with the same text. Only works for line placement. +* * * + +##### shield-spacing `float` + + + +Default Value: 0 +_(Only one shield per line will attempt to be placed.)_ + +Distance the renderer should use to try to place repeated shields on a line. +* * * + +##### shield-min-padding `float` + + + +Default Value: 0 +_(No margin will be used to detect if a shield is nearby a tile boundary.)_ + +Minimum distance a shield will be placed from the edge of a tile. This option is similiar to shield-avoid-edges:true except that the extra margin is used to discard cases where the shield+margin are not fully inside the tile. +* * * + +##### shield-label-position-tolerance `float` + + + +Default Value: shield-spacing/2.0 +_(If a shield cannot be placed then the renderer will advance by shield-spacing/2.0 to try placement again.)_ + +Allows the shield to be displaced from its ideal position by a number of pixels (only works with placement:line). +* * * + +##### shield-wrap-width `unsigned` + + + +Default Value: 0 +_(Text will not be wrapped.)_ + +Length of a chunk of text in pixels before wrapping text. If set to zero, text doesn't wrap. +* * * + +##### shield-wrap-before `boolean` + + + +Default Value: false +_(Wrapped lines will be a bit longer than wrap-width.)_ + +Wrap text before wrap-width is reached. +* * * + +##### shield-wrap-character `string` + + + +Default Value: " " +_(Lines will be wrapped when whitespace is encountered.)_ + +Use this character instead of a space to wrap long names. +* * * + +##### shield-halo-fill `color` + + + +Default Value: white +_(The shield halo text will be rendered white.)_ + +Specifies the color of the halo around the text. +* * * + +##### shield-halo-radius `float` + + + +Default Value: 0 +_(no halo.)_ + +Specify the radius of the halo in pixels. +* * * + +##### shield-halo-rasterizer `keyword` +`full``fast` + + +Default Value: full +_(The shield will be rendered using the highest quality method rather than the fastest.)_ + +Exposes an alternate text halo rendering method that sacrifices quality for speed. +* * * + +##### shield-halo-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: +_(No transformation.)_ + +Transform shield halo relative to the actual text with specified function. Allows for shadow or embossed effects. Ignores map scale factor. +* * * + +##### shield-halo-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### shield-halo-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A number from 0 to 1 specifying the opacity for the text halo. +* * * + +##### shield-character-spacing `unsigned` + + + +Default Value: 0 +_(The default character spacing of the font will be used.)_ + +Horizontal spacing between characters (in pixels). Currently works for point placement only, not line placement. +* * * + +##### shield-line-spacing `unsigned` + + + +Default Value: 0 +_(The default font spacing will be used.)_ + +Vertical spacing between lines of multiline labels (in pixels). +* * * + +##### shield-text-dx `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text within shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the shield right. +* * * + +##### shield-text-dy `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text within shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the shield down. +* * * + +##### shield-dx `float` + + + +Default Value: 0 +_(Shield will not be displaced.)_ + +Displace shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right. +* * * + +##### shield-dy `float` + + + +Default Value: 0 +_(Shield will not be displaced.)_ + +Displace shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text down. +* * * + +##### shield-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the image used for the shield. +* * * + +##### shield-text-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the text placed on top of the shield. +* * * + +##### shield-horizontal-alignment `keyword` +`left``middle``right``auto` + + +Default Value: auto +_(TODO.)_ + +The shield's horizontal alignment from its centerpoint. +* * * + +##### shield-vertical-alignment `keyword` +`top``middle``bottom``auto` + + +Default Value: middle +_(TODO.)_ + +The shield's vertical alignment from its centerpoint. +* * * + +##### shield-placement-type `keyword` +`dummy``simple``list` + + +Default Value: dummy +_(Alternative placements will not be enabled.)_ + +Re-position and/or re-size shield to avoid overlaps. "simple" for basic algorithm (using shield-placements string,) "dummy" to turn this feature off. +* * * + +##### shield-placements `string` + + + +Default Value: +_(No alternative placements will be used.)_ + +If "placement-type" is set to "simple", use this "POSITIONS,[SIZES]" string. An example is `shield-placements: "E,NE,SE,W,NW,SW";`. +* * * + +##### shield-text-transform `keyword` +`none``uppercase``lowercase``capitalize``reverse` + + +Default Value: none +_(No text transformation will be applied.)_ + +Transform the case of the characters. +* * * + +##### shield-justify-alignment `keyword` +`left``center``right``auto` + + +Default Value: auto +_(TODO.)_ + +Define how text in a shield's label is justified. +* * * + +##### shield-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation.)_ + +Transform shield instance with specified function. Ignores map scale factor. +* * * + +##### shield-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### shield-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify the geometries used for shield placement by the given tolerance. +* * * + +##### shield-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify the geometries used for shield placement by the given algorithm. +* * * + +##### shield-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out the angles of the geometry used for shield placement. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### shield-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## line-pattern + +##### line-pattern-file `uri` + + + +Default Value: none + + +An image file to be repeated and warped along a line. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### line-pattern-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### line-pattern-opacity `float` + + + +Default Value: 1 +_(The image is rendered without modifications.)_ + +Apply an opacity level to the image used for the pattern. +* * * + +##### line-pattern-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +geometries are simplified by the given tolerance. +* * * + +##### line-pattern-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +geometries are simplified by the given algorithm. +* * * + +##### line-pattern-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### line-pattern-offset `float` + + + +Default Value: 0 +_(The line will not be offset.)_ + +Offsets a line a number of pixels parallel to its actual path. Positive values move the line left, negative values move it right (relative to the directionality of the line). +* * * + +##### line-pattern-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform line geometry with specified function and apply pattern to transformed geometry. +* * * + +##### line-pattern-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## polygon-pattern + +##### polygon-pattern-file `uri` + + + +Default Value: none + + +Image to use as a repeated pattern fill within a polygon. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### polygon-pattern-alignment `keyword` +`global``local` + + +Default Value: global +_(Patterns will be aligned to the map (or tile boundaries) when being repeated across polygons. This is ideal for seamless patterns in tiled rendering.)_ + +Specify whether to align pattern fills to the layer's geometry (local) or to the map (global). +* * * + +##### polygon-pattern-gamma `float` + + + +Default Value: 1 +_(Fully antialiased.)_ +Range: 0-1 +Level of antialiasing of polygon pattern edges. +* * * + +##### polygon-pattern-opacity `float` + + + +Default Value: 1 +_(The image is rendered without modifications.)_ + +Apply an opacity level to the image used for the pattern. +* * * + +##### polygon-pattern-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### polygon-pattern-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +geometries are simplified by the given tolerance. +* * * + +##### polygon-pattern-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +geometries are simplified by the given algorithm. +* * * + +##### polygon-pattern-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### polygon-pattern-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform polygon geometry with specified function and apply pattern to transformed geometry. +* * * + +##### polygon-pattern-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## raster + +##### raster-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the raster symbolizer on top of other symbolizers. +* * * + +##### raster-filter-factor `float` + + + +Default Value: -1 +_(Allow the datasource to choose appropriate downscaling.)_ + +This is used by the Raster or Gdal datasources to pre-downscale images using overviews. Higher numbers can sometimes cause much better scaled image output, at the cost of speed. +* * * + +##### raster-scaling `keyword` +`near``fast``bilinear``bicubic``spline16``spline36``hanning``hamming``hermite``kaiser``quadric``catrom``gaussian``bessel``mitchell``sinc``lanczos``blackman` + + +Default Value: near +_(Nearest neighboor resampling will be used to scale the image to the target size of the map.)_ + +The scaling algorithm used to making different resolution versions of this raster layer. Bilinear is a good compromise between speed and accuracy, while lanczos gives the highest quality. +* * * + +##### raster-mesh-size `unsigned` + + + +Default Value: 16 +_(Reprojection mesh will be 1/16 of the resolution of the source image.)_ + +A reduced resolution mesh is used for raster reprojection, and the total image size is divided by the mesh-size to determine the quality of that mesh. Values for mesh-size larger than the default will result in faster reprojection but might lead to distortion. +* * * + +##### raster-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### raster-colorizer-default-mode `keyword` +`discrete``linear``exact` + + +Default Value: linear +_(A linear interpolation is used to generate colors between the two nearest stops.)_ + +This can be either `discrete`, `linear` or `exact`. If it is not specified then the default is `linear`. +* * * + +##### raster-colorizer-default-color `color` + + + +Default Value: transparent +_(Pixels that are not colored by the colorizer stops will be transparent.)_ + +This can be any color. Sets the color that is applied to all values outside of the range of the colorizer-stops. If not supplied pixels will be fully transparent. +* * * + +##### raster-colorizer-epsilon `float` + + + +Default Value: 1.1920928955078125e-07 +_(Pixels must very closely match the stop filter otherwise they will not be colored.)_ + +This can be any positive floating point value and will be used as a tolerance in floating point comparisions. The higher the value the more likely a stop will match and color data. +* * * + +##### raster-colorizer-stops `tags` + + + +Default Value: +_(No colorization will happen without supplying stops.)_ + +Assigns raster data values to colors. Stops must be listed in ascending order, and contain at a minimum the value and the associated color. You can also include the color-mode as a third argument, like `stop(100,#fff,exact)`. +* * * + + +## point + +##### point-file `uri` + + + +Default Value: none +_(A 4x4 black square will be rendered.)_ + +Image file to represent a point. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### point-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow points to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping points are shown or hidden. +* * * + +##### point-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache.)_ + +Control whether the placement of the feature will prevent the placement of other features. +* * * + +##### point-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A value from 0 to 1 to control the opacity of the point. +* * * + +##### point-placement `keyword` +`centroid``interior` + + +Default Value: centroid +_(The centroid of the geometry will be used to place the point.)_ + +Control how this point should be placed. Centroid calculates the geometric center of a polygon, which can be outside of it, while interior always places inside of a polygon. +* * * + +##### point-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation.)_ + +Transform point instance with specified function. Ignores map scale factor. +* * * + +##### point-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## text + +##### text-name `string` + + + +Default Value: none + + +Value to use for a text label. Data columns are specified using brackets like [column_name]. +* * * + +##### text-face-name `string` + + + +Default Value: none + + +Font name and style to render a label in. +* * * + +##### text-size `float` + + + +Default Value: 10 +_(Font size of 10 will be used to render text.)_ + +Text size in pixels. +* * * + +##### text-ratio `unsigned` + + + +Default Value: 0 +_(TODO.)_ + +Define the amount of text (of the total) present on successive lines when wrapping occurs. +* * * + +##### text-wrap-width `unsigned` + + + +Default Value: 0 +_(Text will not be wrapped.)_ + +Length of a chunk of text in pixels before wrapping text. If set to zero, text doesn't wrap. +* * * + +##### text-wrap-before `boolean` + + + +Default Value: false +_(Wrapped lines will be a bit longer than wrap-width.)_ + +Wrap text before wrap-width is reached. +* * * + +##### text-wrap-character `string` + + + +Default Value: " " +_(Lines will be wrapped when whitespace is encountered.)_ + +Use this character instead of a space to wrap long text. +* * * + +##### text-repeat-wrap-character `boolean` + + + +Default Value: false +_(Character will be removed when used to wrap a line.)_ + +Keep the character used to wrap a line instead of removing it, and repeat it on the new line. +* * * + +##### text-spacing `unsigned` + + + +Default Value: 0 +_(Only one label per line will attempt to be placed.)_ + +Distance the renderer should use to try to place repeated text labels on a line. +* * * + +##### text-character-spacing `float` + + + +Default Value: 0 +_(The default character spacing of the font will be used.)_ + +Horizontal spacing adjustment between characters in pixels. This value is ignored when `horizontal-alignment` is set to `adjust`. Typographic ligatures are turned off when this value is greater than zero. +* * * + +##### text-line-spacing `unsigned` + + + +Default Value: 0 +_(The default font spacing will be used.)_ + +Vertical spacing adjustment between lines in pixels. +* * * + +##### text-label-position-tolerance `float` + + + +Default Value: text-spacing/2.0 +_(If a shield cannot be placed then the renderer will advance by text-spacing/2.0 to try placement again.)_ + +Allows the label to be displaced from its ideal position by a number of pixels (only works with placement:line). +* * * + +##### text-max-char-angle-delta `float` + + + +Default Value: 22.5 +_(The label will not be placed if a character falls on a line with an angle sharper than 22.5 degrees.)_ + +The maximum angle change, in degrees, allowed between adjacent characters in a label. This value internally is converted to radians to the default is 22.5*math.pi/180.0. The higher the value the fewer labels will be placed around around sharp corners. +* * * + +##### text-fill `color` + + + +Default Value: black +_(The text will be rendered black.)_ + +Specifies the color for the text. +* * * + +##### text-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A number from 0 to 1 specifying the opacity for the text. +* * * + +##### text-halo-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A number from 0 to 1 specifying the opacity for the text halo. +* * * + +##### text-halo-fill `color` + + + +Default Value: white +_(The halo will be rendered white.)_ + +Specifies the color of the halo around the text. +* * * + +##### text-halo-radius `float` + + + +Default Value: 0 +_(no halo.)_ + +Specify the radius of the halo in pixels. +* * * + +##### text-halo-rasterizer `keyword` +`full``fast` + + +Default Value: full +_(The text will be rendered using the highest quality method rather than the fastest.)_ + +Exposes an alternate text halo rendering method that sacrifices quality for speed. +* * * + +##### text-halo-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: +_(No transformation.)_ + +Transform text halo relative to the actual text with specified function. Allows for shadow or embossed effects. Ignores map scale factor. +* * * + +##### text-dx `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text by fixed amount, in pixels, +/- along the X axis. With "dummy" placement-type, a positive value displaces to the right. With "simple" placement-type, it is either left, right or unchanged, depending on the placement selected. Any non-zero value implies "horizontal-alignment" changes to "left" by default. Has no effect with 'line' text-placement-type. +* * * + +##### text-dy `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text by fixed amount, in pixels, +/- along the Y axis. With "dummy" placement-type, a positive value displaces downwards. With "simple" placement-type, it is either up, down or unchanged, depending on the placement selected. With "line" placement-type, a positive value displaces above the path. +* * * + +##### text-vertical-alignment `keyword` +`top``middle``bottom``auto` + + +Default Value: auto +_(Default affected by value of dy; "top" for dy>0, "bottom" for dy<0.)_ + +Position of label relative to point position. +* * * + +##### text-avoid-edges `boolean` + + + +Default Value: false +_(Text will be potentially placed near tile edges and therefore may look cut off unless the same text label is rendered on each adjacent tile.)_ + +Avoid placing labels that intersect with tile boundaries. +* * * + +##### text-margin `float` + + + +Default Value: 0 +_(No extra margin will be used to determine if a label collides with any other text, shield, or marker.)_ + +Minimum distance that a label can be placed from any other text, shield, or marker. +* * * + +##### text-repeat-distance `float` + + + +Default Value: 0 +_(Labels with the same text will be rendered without restriction.)_ + +Minimum distance between repeated text. If set this will prevent text labels being rendered nearby each other that contain the same text. Similiar to text-min-distance with the difference that it works the same no matter what placement strategy is used. +* * * + +##### text-min-distance `float` + + + +Default Value: 0 +_(Labels with the same text will be rendered without restriction.)_ + +Minimum distance to the next label with the same text. Only works for line placement. Deprecated: replaced by `text-repeat-distance` and `text-margin` +* * * + +##### text-min-padding `float` + + + +Default Value: 0 +_(No margin will be used to detect if a text label is nearby a tile boundary.)_ + +Minimum distance a text label will be placed from the edge of a tile. This option is similiar to shield-avoid-edges:true except that the extra margin is used to discard cases where the shield+margin are not fully inside the tile. +* * * + +##### text-min-path-length `float` + + + +Default Value: 0 +_(place labels on all geometries no matter how small they are.)_ + +Place labels only on polygons and lines with a bounding width longer than this value (in pixels). +* * * + +##### text-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow text to overlap with other text - overlapping markers will not be shown.)_ + +Control whether overlapping text is shown or hidden. +* * * + +##### text-orientation `float` + + + +Default Value: 0 +_(Text is not rotated and is displayed upright.)_ + +Rotate the text. (only works with text-placement:point). +* * * + +##### text-rotate-displacement `boolean` + + + +Default Value: false +_(Label center is used for rotation.)_ + +Rotates the displacement around the placement origin by the angle given by "orientation". +* * * + +##### text-upright `keyword` +`auto``auto-down``left``right``left-only``right-only` + + +Default Value: auto +_(Text will be positioned upright automatically.)_ + +How this label should be placed along lines. By default when more than half of a label's characters are upside down the label is automatically flipped to keep it upright. By changing this parameter you can prevent this "auto-upright" behavior. The "auto-down" value places text in the opposite orientation to "auto". The "left" or "right" settings can be used to force text to always be placed along a line in a given direction and therefore disables flipping if text appears upside down. The "left-only" or "right-only" properties also force a given direction but will discard upside down text rather than trying to flip it. +* * * + +##### text-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point +_(One shield will be placed per geometry.)_ + +How this label should be placed. Point placement places one label on top of a point geometry and at the centroid of a polygon or the middle point of a line, line places along lines multiple times per feature, vertex places on the vertexes of polygons, and interior attempts to place inside of a polygon. +* * * + +##### text-placement-type `keyword` +`dummy``simple``list` + + +Default Value: dummy +_(Alternative placements will not be enabled.)_ + +Re-position and/or re-size text to avoid overlaps. "simple" for basic algorithm (using text-placements string,) "dummy" to turn this feature off. +* * * + +##### text-placements `string` + + + +Default Value: +_(No alternative placements will be used.)_ + +If "placement-type" is set to "simple", use this "POSITIONS,[SIZES]" string. An example is `text-placements: "E,NE,SE,W,NW,SW";`. +* * * + +##### text-transform `keyword` +`none``uppercase``lowercase``capitalize``reverse` + + +Default Value: none +_(Transform text instance with specified function. Ignores map scale factor.)_ + +Transform the case of the characters. +* * * + +##### text-horizontal-alignment `keyword` +`left``middle``right``auto``adjust` + + +Default Value: auto +_(TODO.)_ + +The text's horizontal alignment from it's centerpoint. If `placement` is set to `line`, then `adjust` can be set to auto-fit the text to the length of the path by dynamically calculating `character-spacing`. +* * * + +##### text-align `keyword` +`left``right``center``auto` + + +Default Value: auto +_(Auto alignment means that text will be centered by default except when using the `placement-type` parameter - in that case either right or left justification will be used automatically depending on where the text could be fit given the `text-placements` directives.)_ + +Define how text is justified. +* * * + +##### text-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### text-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify the geometries used for text placement by the given tolerance. +* * * + +##### text-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify the geometries used for text placement by the given algorithm. +* * * + +##### text-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out the angles of the geometry used for text placement. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### text-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### text-halo-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### text-font-feature-settings `string` + + + +Default Value: +_(Default set of typographic features recommended by OpenType specification. Ligatures are turned off by default when `character-spacing` is greater than zero.)_ + +Comma separated list of OpenType typographic features. The syntax and semantics conforms to `font-feature-settings` from W3C CSS. +* * * + +##### text-largest-bbox-only `boolean` + + + +Default Value: true +_(For multipolygons only polygon with largest bbox area is labeled (does not apply to other geometries).)_ + +Controls default labeling behavior on multipolygons. The default is true and means that only the polygon with largest bbox is labeled. +* * * + + +## building + +##### building-fill `color` + + + +Default Value: The color gray will be used for fill. +_(Gray and fully opaque (alpha = 1), same as rgb(128,128,128) or rgba(128,128,128,1).)_ + +The color of the buildings fill. Note: 0.8 will be used to multiply each color component to auto-generate a darkened wall color. +* * * + +##### building-fill-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the building as a whole, including all walls. +* * * + +##### building-height `float` + + + +Default Value: 0 +_(Buildings will not have a visual height and will instead look like flat polygons.)_ + +The height of the building in pixels. +* * * + + +## debug + +##### debug-mode `string` + + + +Default Value: collision +_(The otherwise invisible collision boxes will be rendered as squares on the map.)_ + +The mode for debug rendering. +* * * + + +## dot + +##### dot-fill `color` + + + +Default Value: gray +_(The dot fill color is gray.)_ + +The color of the area of the dot. +* * * + +##### dot-opacity `float` + + + +Default Value: 1 +_(The opacity of the dot.)_ + +The overall opacity of the dot. +* * * + +##### dot-width `float` + + + +Default Value: 1 +_(The marker width is 1 pixel.)_ + +The width of the dot in pixels. +* * * + +##### dot-height `float` + + + +Default Value: 1 +_(The marker height is 1 pixels.)_ + +The height of the dot in pixels. +* * * + +##### dot-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current layer on top of other layers.)_ + +Composite operation. This defines how this layer should behave relative to layers atop or below it. +* * * + + + + +### Values + +Below is a list of values and an explanation of any expression that can be applied to properties in CartCSS. + +### Color + +CartoCSS accepts a variety of syntaxes for colors - HTML-style hex values, rgb, rgba, hsl, hsla, husl, and husla. It also supports the predefined HTML colors names, like `yellow` and `blue`. + +``` css +#line { +line-color: #ff0; +line-color: #ffff00; +line-color: rgb(255, 255, 0); +line-color: rgba(255, 255, 0, 1); +line-color: hsl(100, 50%, 50%); +line-color: hsla(100, 50%, 50%, 1); +line-color: husl(100, 50%, 50%); // same values yield different color than HSL +line-color: husla(100, 50%, 50%, 1); +line-color: yellow; +} +``` + +Especially of note is the support for hsl and husl, which can be [easier to reason about than rgb()](http://mothereffinghsl.com/). Carto also includes several color operation functions [borrowed from less](http://lesscss.org/functions/#color-operations): + +``` css +// lighten and darken colors +lighten(#ace, 10%); +darken(#ace, 10%); + +// saturate and desaturate +saturate(#550000, 10%); +desaturate(#00ff00, 10%); + +// increase or decrease the opacity of a color +fadein(#fafafa, 10%); +fadeout(#fefefe, 14%); + +// spin rotates a color around the color wheel by degrees +spin(#ff00ff, 10); + +// mix generates a color in between two other colors. +mix(#fff, #000, 50%); + +// get color components +hue(#ff00ff); +saturation(#ff00ff); +lightness(#ff00ff); +alpha(hsla(100, 50%, 50%, 0.5)); +``` + +These functions all take arguments which can be color variables, literal colors, or the results of other functions operating on colors. All the above mentioned functions also come in +a `functionp`-variant (e.g. `lightenp`), which force a given color into perceptual color space. + +### Float + +Float is a fancy way of saying 'number'. In CartoCSS, you specify _just a number_ - unlike CSS, there are no units, but everything is specified in pixels. + +``` css +#line { +line-width: 2; +} +``` + +It's also possible to do simple math with number values: + +``` css +#line { +line-width: 4 / 2; // division +line-width: 4 + 2; // addition +line-width: 4 - 2; // subtraction +line-width: 4 * 2; // multiplication +line-width: 4 % 2; // modulus +} +``` + +### URI + +URI is a fancy way of saying URL. When an argument is a URI, you use the same kind of `url('place.png')` notation that you would with HTML. Quotes around the URL aren't required, but are highly recommended. URIs can be paths to places on your computer, or on the internet. + +```css +#markers { +marker-file: url('marker.png'); +} +``` + +### String + +A string is basically just text. In the case of CartoCSS, you're going to put it in quotes. Strings can be anything, though pay attention to the cases of `text-name` and `shield-name` - they actually will refer to features, which you refer to by putting them in brackets, as seen in the example below. + +```css +#labels { +text-name: "[MY_FIELD]"; +} +``` + +### Boolean + +Boolean means yes or no, so it accepts the values `true` or `false`. + +```css +#markers { +marker-allow-overlap:true; +} +``` + +### Expressions + +Expressions are statements that can include fields, numbers, and other types in a really flexible way. You have run into expressions before, in the realm of 'fields', where you'd specify `"[FIELD]"`, but expressions allow you to drop the quotes and also do quick addition, division, multiplication, and concatenation from within Carto syntax. + +```css +#buildings { +building-height: [HEIGHT_FIELD] * 10; +} +``` + +### Numbers +Numbers are comma-separated lists of one or more number in a specific order. They're used in line dash arrays, in which the numbers specify intervals of line, break, and line again. + +```css +#disputedboundary { +line-dasharray: 1, 4, 2; +} +``` + +### Percentages +In Carto, the percentage symbol, `%` universally means `value/100`. It's meant to be used with ratio-related properties, like opacity rules. + +_You should not use percentages as widths, heights, or other properties - unlike CSS, percentages are not relative to cascaded classes or page size, they're, as stated, simply the value divided by one hundred._ + +```css +#world { +// this syntax +polygon-opacity: 50%; + +// is equivalent to +polygon-opacity: 0.5; +} +``` + +### Functions + +Functions are comma-separated lists of one or more functions. For instance, transforms use the `functions` type to allow for transforms within Carto, which are optionally chainable. + +```css +#point { +point-transform: scale(2, 2); +} +``` diff --git a/docs/3.0.4.md b/docs/3.0.4.md new file mode 100644 index 0000000..ad7ed30 --- /dev/null +++ b/docs/3.0.4.md @@ -0,0 +1,2226 @@ +# Carto documentation + +The following is a list of properties provided in CartoCSS that you can apply to map elements. + +## All elements + +##### image-filters `functions` + +`agg-stack-blur``emboss``blur``gray``sobel``edge-detect``x-gradient``y-gradient``invert``sharpen``color-blind-protanope``color-blind-deuteranope``color-blind-tritanope``colorize-alpha``color-to-alpha``scale-hsla` + +Default Value: none +_(no filters.)_ + +A list of image filters that will be applied to the active rendering canvas for a given style. The presence of one more `image-filters` will trigger a new canvas to be created before starting to render a style and then this canvas will be composited back into the main canvas after rendering all features and after all `image-filters` have been applied. See `direct-image-filters` if you want to apply a filter directly to the main canvas. +* * * + +##### image-filters-inflate `boolean` + + + +Default Value: false +_(No special handling will be done and image filters that blur data will only blur up to the edge of a tile boundary.)_ + +A property that can be set to true to enable using an inflated image internally for seamless blurring across tiles (requires buffered data). +* * * + +##### direct-image-filters `functions` + +`agg-stack-blur``emboss``blur``gray``sobel``edge-detect``x-gradient``y-gradient``invert``sharpen``color-blind-protanope``color-blind-deuteranope``color-blind-tritanope``colorize-alpha``color-to-alpha``scale-hsla` + +Default Value: none +_(no filters.)_ + +A list of image filters to apply to the main canvas (see the `image-filters` doc for how they work on a separate canvas). +* * * + +##### comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current layer on top of other layers.)_ + +Composite operation. This defines how this layer should behave relative to layers atop or below it. +* * * + +##### opacity `float` + + + +Default Value: 1 +_(No separate buffer will be used and no alpha will be applied to the style after rendering.)_ + +An alpha value for the style (which means an alpha applied to all features in separate buffer and then composited back to main buffer). +* * * + + +## map + +##### background-color `color` + + + +Default Value: none +_(Will be rendered transparent.)_ + +Map Background color. +* * * + +##### background-image `uri` + + + +Default Value: +_(No background image will be used.)_ + +An image that is repeated below all features on a map as a background. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### background-image-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(The background-image will be blended with the background normally (placed on top of any existing background-color).)_ + +Set the compositing operation used to blend the image into the background. +* * * + +##### background-image-opacity `float` + + + +Default Value: 1 +_(The image opacity will not be changed when applied to the map background.)_ + +Set the opacity of the image. +* * * + +##### srs `string` + + + +Default Value: +proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs +_(The proj4 literal of EPSG:4326 is assumed to be the Map's spatial reference and all data from layers within this map will be plotted using this coordinate system. If any layers do not declare an srs value then they will be assumed to be in the same srs as the Map and not transformations will be needed to plot them in the Map's coordinate space.)_ + +Map spatial reference (proj4 string). +* * * + +##### buffer-size `float` + + + +Default Value: 0 +_(No buffer will be used.)_ + +Extra tolerance around the map (in pixels) used to ensure labels crossing tile boundaries are equally rendered in each tile (e.g. cut in each tile). Not intended to be used in combination with "avoid-edges". +* * * + +##### maximum-extent `string` + + + +Default Value: -20037508.34,-20037508.34,20037508.34,20037508.34 +_(All data will be clipped to global mercator extent (default is applied in Carto.js).)_ + +An extent to be used to limit the bounds used to query all layers during rendering. Should be minx, miny, maxx, maxy in the coordinates of the Map. +* * * + +##### base `string` + + + +Default Value: +_(This base path defaults to an empty string meaning that any relative paths to files referenced in styles or layers will be interpreted relative to the application process.)_ + +Any relative paths used to reference files will be understood as relative to this directory path if the map is loaded from an in memory object rather than from the filesystem. If the map is loaded from the filesystem and this option is not provided it will be set to the directory of the stylesheet. +* * * + +##### font-directory `uri` + + + +Default Value: none +_(No map-specific fonts will be registered.)_ + +Path to a directory which holds fonts which should be registered when the Map is loaded (in addition to any fonts that may be automatically registered). +* * * + + +## polygon + +##### polygon-fill `color` + + + +Default Value: The color gray will be used for fill. +_(Gray and fully opaque (alpha = 1), same as rgb(128,128,128) or rgba(128,128,128,1).)_ + +Fill color to assign to a polygon. +* * * + +##### polygon-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the polygon. +* * * + +##### polygon-gamma `float` + + + +Default Value: 1 +_(Fully antialiased.)_ +Range: 0-1 +Level of antialiasing of polygon edges. +* * * + +##### polygon-gamma-method `keyword` +`power``linear``none``threshold``multiply` + + +Default Value: power +_(pow(x,gamma) is used to calculate pixel gamma, which produces slightly smoother line and polygon antialiasing than the 'linear' method, while other methods are usually only used to disable AA.)_ + +An Antigrain Geometry specific rendering hint to control the quality of antialiasing. Under the hood in Mapnik this method is used in combination with the 'gamma' value (which defaults to 1). The methods are in the AGG source at https://github.com/mapnik/mapnik/blob/master/deps/agg/include/agg_gamma_functions. +* * * + +##### polygon-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extend outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### polygon-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify geometries by the given tolerance. +* * * + +##### polygon-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify geometries by the given algorithm. +* * * + +##### polygon-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### polygon-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform polygon geometry with specified function. +* * * + +##### polygon-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## line + +##### line-color `color` + + + +Default Value: black +_(black and fully opaque (alpha = 1), same as rgb(0,0,0) or rgba(0,0,0,1).)_ + +The color of a drawn line. +* * * + +##### line-width `float` + + + +Default Value: 1 +_(The line will be rendered 1 pixel wide.)_ + +The width of a line in pixels. +* * * + +##### line-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of a line. +* * * + +##### line-join `keyword` +`miter``miter-revert``round``bevel` + + +Default Value: miter +_(The line joins will be rendered using a miter look.)_ + +The behavior of lines when joining. +* * * + +##### line-cap `keyword` +`butt``round``square` + + +Default Value: butt +_(The line endings will be rendered using a butt look.)_ + +The display of line endings. +* * * + +##### line-gamma `float` + + + +Default Value: 1 +_(Fully antialiased.)_ +Range: 0-1 +Level of antialiasing of stroke line. +* * * + +##### line-gamma-method `keyword` +`power``linear``none``threshold``multiply` + + +Default Value: power +_(pow(x,gamma) is used to calculate pixel gamma, which produces slightly smoother line and polygon antialiasing than the 'linear' method, while other methods are usually only used to disable AA.)_ + +An Antigrain Geometry specific rendering hint to control the quality of antialiasing. Under the hood in Mapnik this method is used in combination with the 'gamma' value (which defaults to 1). The methods are in the AGG source at https://github.com/mapnik/mapnik/blob/master/deps/agg/include/agg_gamma_functions. +* * * + +##### line-dasharray `numbers` + + + +Default Value: none +_(The line will be drawn without dashes.)_ + +A pair of length values [a,b], where (a) is the dash length and (b) is the gap length respectively. More than two values are supported for more complex patterns. +* * * + +##### line-dash-offset `numbers` + + + +Default Value: none +_(The line will be drawn without dashes.)_ + +Valid parameter but not currently used in renderers (only exists for experimental svg support in Mapnik which is not yet enabled). +* * * + +##### line-miterlimit `float` + + + +Default Value: 4 +_(Will auto-convert miters to bevel line joins when theta is less than 29 degrees as per the SVG spec: 'miterLength / stroke-width = 1 / sin ( theta / 2 )'.)_ + +The limit on the ratio of the miter length to the stroke-width. Used to automatically convert miter joins to bevel joins for sharp angles to avoid the miter extending beyond the thickness of the stroking path. Normally will not need to be set, but a larger value can sometimes help avoid jaggy artifacts. +* * * + +##### line-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### line-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify geometries by the given tolerance. +* * * + +##### line-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify geometries by the given algorithm. +* * * + +##### line-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### line-offset `float` + + + +Default Value: 0 +_(Will not be offset.)_ + +Offsets a line a number of pixels parallel to its actual path. Positive values move the line left, negative values move it right (relative to the directionality of the line). +* * * + +##### line-rasterizer `keyword` +`full``fast` + + +Default Value: full +_(The line will be rendered using the highest quality method rather than the fastest.)_ + +Exposes an alternate AGG rendering method that sacrifices some accuracy for speed. +* * * + +##### line-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform line geometry with specified function. +* * * + +##### line-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## markers + +##### marker-file `uri` + + + +Default Value: none +_(An ellipse or circle, if width equals height.)_ + +A file that this marker shows at each placement. If no file is given, the marker will show an ellipse. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### marker-opacity `float` + + + +Default Value: 1 +_(The stroke-opacity and fill-opacity of the marker.)_ + +The overall opacity of the marker, if set, overrides both the opacity of both the fill and stroke. +* * * + +##### marker-fill-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The fill opacity of the marker. +* * * + +##### marker-line-color `color` + + + +Default Value: black +_(The marker will be drawn with a black outline.)_ + +The color of the stroke around the marker. +* * * + +##### marker-line-width `float` + + + +Default Value: 0.5 +_(The marker will be drawn with an outline of .5 pixels wide.)_ + +The width of the stroke around the marker, in pixels. This is positioned on the boundary, so high values can cover the area itself. +* * * + +##### marker-line-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of a line. +* * * + +##### marker-placement `keyword` +`point``line``interior``vertex-first``vertex-last` + + +Default Value: point +_(Place markers at the center point (centroid) of the geometry.)_ + +Attempt to place markers on a point, in the center of a polygon, or if markers-placement:line, then multiple times along a line. 'interior' placement can be used to ensure that points placed on polygons are forced to be inside the polygon interior. The 'vertex-first' and 'vertex-last' options can be used to place markers at the first or last vertex of lines or polygons. +* * * + +##### marker-multi-policy `keyword` +`each``whole``largest` + + +Default Value: each +_(If a feature contains multiple geometries and the placement type is either point or interior then a marker will be rendered for each.)_ + +A special setting to allow the user to control rendering behavior for 'multi-geometries' (when a feature contains multiple geometries). This setting does not apply to markers placed along lines. The 'each' policy is default and means all geometries will get a marker. The 'whole' policy means that the aggregate centroid between all geometries will be used. The 'largest' policy means that only the largest (by bounding box areas) feature will get a rendered marker (this is how text labeling behaves by default). +* * * + +##### marker-type `keyword` +`arrow``ellipse` + + +Default Value: ellipse +_(The marker shape is an ellipse.)_ + +The default marker-type. If a SVG file is not given as the marker-file parameter, the renderer provides either an arrow or an ellipse (a circle if height is equal to width). +* * * + +##### marker-width `float` + + + +Default Value: 10 +_(The marker width is 10 pixels.)_ + +The width of the marker, if using one of the default types. +* * * + +##### marker-height `float` + + + +Default Value: 10 +_(The marker height is 10 pixels.)_ + +The height of the marker, if using one of the default types. +* * * + +##### marker-fill `color` + + + +Default Value: blue +_(The marker fill color is blue.)_ + +The color of the area of the marker. +* * * + +##### marker-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow markers to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping markers are shown or hidden. +* * * + +##### marker-avoid-edges `boolean` + + + +Default Value: false +_(Markers will be potentially placed near tile edges and therefore may look cut off unless they are rendered on each adjacent tile.)_ + +Avoid placing markers that intersect with tile boundaries. +* * * + +##### marker-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache.)_ + +Value to control whether the placement of the feature will prevent the placement of other features. +* * * + +##### marker-spacing `float` + + + +Default Value: 100 +_(In the case of marker-placement:line then draw a marker every 100 pixels along a line.)_ + +Space between repeated markers in pixels. If the spacing is less than the marker size or larger than the line segment length then no marker will be placed. Any value less than 1 will be ignored and the default will be used instead. +* * * + +##### marker-max-error `float` + + + +Default Value: 0.2 +_(N/A: not intended to be changed.)_ + +N/A: not intended to be changed. +* * * + +##### marker-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation.)_ + +Transform marker instance with specified function. Ignores map scale factor. +* * * + +##### marker-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### marker-simplify `float` + + + +Default Value: 0 +_(Geometry will not be simplified.)_ + +geometries are simplified by the given tolerance. +* * * + +##### marker-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +geometries are simplified by the given algorithm. +* * * + +##### marker-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### marker-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform marker geometry with specified function. +* * * + +##### marker-offset `float` + + + +Default Value: 0 +_(Will not be offset.)_ + +Offsets a marker from a line a number of pixels parallel to its actual path. Positive values move the marker left, negative values move it right (relative to the directionality of the line). +* * * + +##### marker-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### marker-direction `keyword` +`auto``auto-down``left``right``left-only``right-only``up``down` + + +Default Value: right +_(Markers are oriented to the right in the line direction.)_ + +How markers should be placed along lines. With the "auto" setting when marker is upside down the marker is automatically rotated by 180 degrees to keep it upright. The "auto-down" value places marker in the opposite orientation to "auto". The "left" or "right" settings can be used to force marker to always be placed along a line in a given direction and therefore disables rotating if marker appears upside down. The "left-only" or "right-only" properties also force a given direction but will discard upside down markers rather than trying to flip it. The "up" and "down" settings don't adjust marker's orientation to the line direction. +* * * + + +## shield + +##### shield-name `string` + + + +Default Value: +_(No text label will be rendered with the shield.)_ + +Value to use for a shield"s text label. Data columns are specified using brackets like [column_name]. +* * * + +##### shield-file `uri` + + + +Default Value: none + + +Image file to render behind the shield text. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### shield-face-name `string` + + + +Default Value: none + + +Font name and style to use for the shield text. +* * * + +##### shield-unlock-image `boolean` + + + +Default Value: false +_(text alignment relative to the shield image uses the center of the image as the anchor for text positioning.)_ + +This parameter should be set to true if you are trying to position text beside rather than on top of the shield image. +* * * + +##### shield-size `float` + + + +Default Value: 10 +_(Font size of 10 will be used to render text.)_ + +The size of the shield text in pixels. +* * * + +##### shield-fill `color` + + + +Default Value: black +_(The shield text will be rendered black.)_ + +The color of the shield text. +* * * + +##### shield-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point +_(One shield will be placed per geometry.)_ + +How this shield should be placed. Point placement places one shield on top of a point geometry and at the centroid of a polygon or the middle point of a line, line places along lines multiple times per feature, vertex places on the vertexes of polygons, and interior attempts to place inside of a polygon. +* * * + +##### shield-avoid-edges `boolean` + + + +Default Value: false +_(Shields will be potentially placed near tile edges and therefore may look cut off unless they are rendered on each adjacent tile.)_ + +Avoid placing shields that intersect with tile boundaries. +* * * + +##### shield-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow shields to overlap with other map elements already placed.)_ + +Control whether overlapping shields are shown or hidden. +* * * + +##### shield-margin `float` + + + +Default Value: 0 +_(No extra margin will be used to determine if a shield collides with any other text, shield, or marker.)_ + +Minimum distance that a shield can be placed from any other text, shield, or marker. +* * * + +##### shield-repeat-distance `float` + + + +Default Value: 0 +_(Shields with the same text will be rendered without restriction.)_ + +Minimum distance between repeated shields. If set this will prevent shields being rendered nearby each other that contain the same text. Similiar to shield-min-distance with the difference that it works the same no matter what placement strategy is used. +* * * + +##### shield-min-distance `float` + + + +Default Value: 0 +_(Shields with the same text will be rendered without restriction.)_ + +Minimum distance to the next shield with the same text. Only works for line placement. +* * * + +##### shield-spacing `float` + + + +Default Value: 0 +_(Only one shield per line will attempt to be placed.)_ + +Distance the renderer should use to try to place repeated shields on a line. +* * * + +##### shield-min-padding `float` + + + +Default Value: 0 +_(No margin will be used to detect if a shield is nearby a tile boundary.)_ + +Minimum distance a shield will be placed from the edge of a tile. This option is similiar to shield-avoid-edges:true except that the extra margin is used to discard cases where the shield+margin are not fully inside the tile. +* * * + +##### shield-label-position-tolerance `float` + + + +Default Value: shield-spacing/2.0 +_(If a shield cannot be placed then the renderer will advance by shield-spacing/2.0 to try placement again.)_ + +Allows the shield to be displaced from its ideal position by a number of pixels (only works with placement:line). +* * * + +##### shield-wrap-width `unsigned` + + + +Default Value: 0 +_(Text will not be wrapped.)_ + +Length of a chunk of text in pixels before wrapping text. If set to zero, text doesn't wrap. +* * * + +##### shield-wrap-before `boolean` + + + +Default Value: false +_(Wrapped lines will be a bit longer than wrap-width.)_ + +Wrap text before wrap-width is reached. +* * * + +##### shield-wrap-character `string` + + + +Default Value: " " +_(Lines will be wrapped when whitespace is encountered.)_ + +Use this character instead of a space to wrap long names. +* * * + +##### shield-halo-fill `color` + + + +Default Value: white +_(The shield halo text will be rendered white.)_ + +Specifies the color of the halo around the text. +* * * + +##### shield-halo-radius `float` + + + +Default Value: 0 +_(no halo.)_ + +Specify the radius of the halo in pixels. +* * * + +##### shield-halo-rasterizer `keyword` +`full``fast` + + +Default Value: full +_(The shield will be rendered using the highest quality method rather than the fastest.)_ + +Exposes an alternate text halo rendering method that sacrifices quality for speed. +* * * + +##### shield-halo-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: +_(No transformation.)_ + +Transform shield halo relative to the actual text with specified function. Allows for shadow or embossed effects. Ignores map scale factor. +* * * + +##### shield-halo-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### shield-halo-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A number from 0 to 1 specifying the opacity for the text halo. +* * * + +##### shield-character-spacing `unsigned` + + + +Default Value: 0 +_(The default character spacing of the font will be used.)_ + +Horizontal spacing between characters (in pixels). Currently works for point placement only, not line placement. +* * * + +##### shield-line-spacing `unsigned` + + + +Default Value: 0 +_(The default font spacing will be used.)_ + +Vertical spacing between lines of multiline labels (in pixels). +* * * + +##### shield-text-dx `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text within shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the shield right. +* * * + +##### shield-text-dy `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text within shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the shield down. +* * * + +##### shield-dx `float` + + + +Default Value: 0 +_(Shield will not be displaced.)_ + +Displace shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right. +* * * + +##### shield-dy `float` + + + +Default Value: 0 +_(Shield will not be displaced.)_ + +Displace shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text down. +* * * + +##### shield-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the image used for the shield. +* * * + +##### shield-text-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the text placed on top of the shield. +* * * + +##### shield-horizontal-alignment `keyword` +`left``middle``right``auto` + + +Default Value: auto +_(TODO.)_ + +The shield's horizontal alignment from its centerpoint. +* * * + +##### shield-vertical-alignment `keyword` +`top``middle``bottom``auto` + + +Default Value: middle +_(TODO.)_ + +The shield's vertical alignment from its centerpoint. +* * * + +##### shield-placement-type `keyword` +`dummy``simple``list` + + +Default Value: dummy +_(Alternative placements will not be enabled.)_ + +Re-position and/or re-size shield to avoid overlaps. "simple" for basic algorithm (using shield-placements string,) "dummy" to turn this feature off. +* * * + +##### shield-placements `string` + + + +Default Value: +_(No alternative placements will be used.)_ + +If "placement-type" is set to "simple", use this "POSITIONS,[SIZES]" string. An example is `shield-placements: "E,NE,SE,W,NW,SW";`. +* * * + +##### shield-text-transform `keyword` +`none``uppercase``lowercase``capitalize``reverse` + + +Default Value: none +_(No text transformation will be applied.)_ + +Transform the case of the characters. +* * * + +##### shield-justify-alignment `keyword` +`left``center``right``auto` + + +Default Value: auto +_(TODO.)_ + +Define how text in a shield's label is justified. +* * * + +##### shield-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation.)_ + +Transform shield instance with specified function. Ignores map scale factor. +* * * + +##### shield-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### shield-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify the geometries used for shield placement by the given tolerance. +* * * + +##### shield-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify the geometries used for shield placement by the given algorithm. +* * * + +##### shield-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out the angles of the geometry used for shield placement. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### shield-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## line-pattern + +##### line-pattern-file `uri` + + + +Default Value: none + + +An image file to be repeated and warped along a line. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### line-pattern-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### line-pattern-opacity `float` + + + +Default Value: 1 +_(The image is rendered without modifications.)_ + +Apply an opacity level to the image used for the pattern. +* * * + +##### line-pattern-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +geometries are simplified by the given tolerance. +* * * + +##### line-pattern-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +geometries are simplified by the given algorithm. +* * * + +##### line-pattern-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### line-pattern-offset `float` + + + +Default Value: 0 +_(The line will not be offset.)_ + +Offsets a line a number of pixels parallel to its actual path. Positive values move the line left, negative values move it right (relative to the directionality of the line). +* * * + +##### line-pattern-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform line geometry with specified function and apply pattern to transformed geometry. +* * * + +##### line-pattern-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## polygon-pattern + +##### polygon-pattern-file `uri` + + + +Default Value: none + + +Image to use as a repeated pattern fill within a polygon. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### polygon-pattern-alignment `keyword` +`global``local` + + +Default Value: global +_(Patterns will be aligned to the map (or tile boundaries) when being repeated across polygons. This is ideal for seamless patterns in tiled rendering.)_ + +Specify whether to align pattern fills to the layer's geometry (local) or to the map (global). +* * * + +##### polygon-pattern-gamma `float` + + + +Default Value: 1 +_(Fully antialiased.)_ +Range: 0-1 +Level of antialiasing of polygon pattern edges. +* * * + +##### polygon-pattern-opacity `float` + + + +Default Value: 1 +_(The image is rendered without modifications.)_ + +Apply an opacity level to the image used for the pattern. +* * * + +##### polygon-pattern-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### polygon-pattern-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +geometries are simplified by the given tolerance. +* * * + +##### polygon-pattern-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +geometries are simplified by the given algorithm. +* * * + +##### polygon-pattern-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### polygon-pattern-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform polygon geometry with specified function and apply pattern to transformed geometry. +* * * + +##### polygon-pattern-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## raster + +##### raster-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the raster symbolizer on top of other symbolizers. +* * * + +##### raster-filter-factor `float` + + + +Default Value: -1 +_(Allow the datasource to choose appropriate downscaling.)_ + +This is used by the Raster or Gdal datasources to pre-downscale images using overviews. Higher numbers can sometimes cause much better scaled image output, at the cost of speed. +* * * + +##### raster-scaling `keyword` +`near``fast``bilinear``bicubic``spline16``spline36``hanning``hamming``hermite``kaiser``quadric``catrom``gaussian``bessel``mitchell``sinc``lanczos``blackman` + + +Default Value: near +_(Nearest neighboor resampling will be used to scale the image to the target size of the map.)_ + +The scaling algorithm used to making different resolution versions of this raster layer. Bilinear is a good compromise between speed and accuracy, while lanczos gives the highest quality. +* * * + +##### raster-mesh-size `unsigned` + + + +Default Value: 16 +_(Reprojection mesh will be 1/16 of the resolution of the source image.)_ + +A reduced resolution mesh is used for raster reprojection, and the total image size is divided by the mesh-size to determine the quality of that mesh. Values for mesh-size larger than the default will result in faster reprojection but might lead to distortion. +* * * + +##### raster-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### raster-colorizer-default-mode `keyword` +`discrete``linear``exact` + + +Default Value: linear +_(A linear interpolation is used to generate colors between the two nearest stops.)_ + +This can be either `discrete`, `linear` or `exact`. If it is not specified then the default is `linear`. +* * * + +##### raster-colorizer-default-color `color` + + + +Default Value: transparent +_(Pixels that are not colored by the colorizer stops will be transparent.)_ + +This can be any color. Sets the color that is applied to all values outside of the range of the colorizer-stops. If not supplied pixels will be fully transparent. +* * * + +##### raster-colorizer-epsilon `float` + + + +Default Value: 1.1920928955078125e-07 +_(Pixels must very closely match the stop filter otherwise they will not be colored.)_ + +This can be any positive floating point value and will be used as a tolerance in floating point comparisions. The higher the value the more likely a stop will match and color data. +* * * + +##### raster-colorizer-stops `tags` + + + +Default Value: +_(No colorization will happen without supplying stops.)_ + +Assigns raster data values to colors. Stops must be listed in ascending order, and contain at a minimum the value and the associated color. You can also include the color-mode as a third argument, like `stop(100,#fff,exact)`. +* * * + + +## point + +##### point-file `uri` + + + +Default Value: none +_(A 4x4 black square will be rendered.)_ + +Image file to represent a point. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### point-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow points to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping points are shown or hidden. +* * * + +##### point-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache.)_ + +Control whether the placement of the feature will prevent the placement of other features. +* * * + +##### point-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A value from 0 to 1 to control the opacity of the point. +* * * + +##### point-placement `keyword` +`centroid``interior` + + +Default Value: centroid +_(The centroid of the geometry will be used to place the point.)_ + +Control how this point should be placed. Centroid calculates the geometric center of a polygon, which can be outside of it, while interior always places inside of a polygon. +* * * + +##### point-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation.)_ + +Transform point instance with specified function. Ignores map scale factor. +* * * + +##### point-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## text + +##### text-name `string` + + + +Default Value: none + + +Value to use for a text label. Data columns are specified using brackets like [column_name]. +* * * + +##### text-face-name `string` + + + +Default Value: none + + +Font name and style to render a label in. +* * * + +##### text-size `float` + + + +Default Value: 10 +_(Font size of 10 will be used to render text.)_ + +Text size in pixels. +* * * + +##### text-ratio `unsigned` + + + +Default Value: 0 +_(TODO.)_ + +Define the amount of text (of the total) present on successive lines when wrapping occurs. +* * * + +##### text-wrap-width `unsigned` + + + +Default Value: 0 +_(Text will not be wrapped.)_ + +Length of a chunk of text in pixels before wrapping text. If set to zero, text doesn't wrap. +* * * + +##### text-wrap-before `boolean` + + + +Default Value: false +_(Wrapped lines will be a bit longer than wrap-width.)_ + +Wrap text before wrap-width is reached. +* * * + +##### text-wrap-character `string` + + + +Default Value: " " +_(Lines will be wrapped when whitespace is encountered.)_ + +Use this character instead of a space to wrap long text. +* * * + +##### text-repeat-wrap-character `boolean` + + + +Default Value: false +_(Character will be removed when used to wrap a line.)_ + +Keep the character used to wrap a line instead of removing it, and repeat it on the new line. +* * * + +##### text-spacing `unsigned` + + + +Default Value: 0 +_(Only one label per line will attempt to be placed.)_ + +Distance the renderer should use to try to place repeated text labels on a line. +* * * + +##### text-character-spacing `float` + + + +Default Value: 0 +_(The default character spacing of the font will be used.)_ + +Horizontal spacing adjustment between characters in pixels. This value is ignored when `horizontal-alignment` is set to `adjust`. Typographic ligatures are turned off when this value is greater than zero. +* * * + +##### text-line-spacing `unsigned` + + + +Default Value: 0 +_(The default font spacing will be used.)_ + +Vertical spacing adjustment between lines in pixels. +* * * + +##### text-label-position-tolerance `float` + + + +Default Value: text-spacing/2.0 +_(If a shield cannot be placed then the renderer will advance by text-spacing/2.0 to try placement again.)_ + +Allows the label to be displaced from its ideal position by a number of pixels (only works with placement:line). +* * * + +##### text-max-char-angle-delta `float` + + + +Default Value: 22.5 +_(The label will not be placed if a character falls on a line with an angle sharper than 22.5 degrees.)_ + +The maximum angle change, in degrees, allowed between adjacent characters in a label. This value internally is converted to radians to the default is 22.5*math.pi/180.0. The higher the value the fewer labels will be placed around around sharp corners. +* * * + +##### text-fill `color` + + + +Default Value: black +_(The text will be rendered black.)_ + +Specifies the color for the text. +* * * + +##### text-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A number from 0 to 1 specifying the opacity for the text. +* * * + +##### text-halo-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A number from 0 to 1 specifying the opacity for the text halo. +* * * + +##### text-halo-fill `color` + + + +Default Value: white +_(The halo will be rendered white.)_ + +Specifies the color of the halo around the text. +* * * + +##### text-halo-radius `float` + + + +Default Value: 0 +_(no halo.)_ + +Specify the radius of the halo in pixels. +* * * + +##### text-halo-rasterizer `keyword` +`full``fast` + + +Default Value: full +_(The text will be rendered using the highest quality method rather than the fastest.)_ + +Exposes an alternate text halo rendering method that sacrifices quality for speed. +* * * + +##### text-halo-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: +_(No transformation.)_ + +Transform text halo relative to the actual text with specified function. Allows for shadow or embossed effects. Ignores map scale factor. +* * * + +##### text-dx `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text by fixed amount, in pixels, +/- along the X axis. With "dummy" placement-type, a positive value displaces to the right. With "simple" placement-type, it is either left, right or unchanged, depending on the placement selected. Any non-zero value implies "horizontal-alignment" changes to "left" by default. Has no effect with 'line' text-placement-type. +* * * + +##### text-dy `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text by fixed amount, in pixels, +/- along the Y axis. With "dummy" placement-type, a positive value displaces downwards. With "simple" placement-type, it is either up, down or unchanged, depending on the placement selected. With "line" placement-type, a positive value displaces above the path. +* * * + +##### text-vertical-alignment `keyword` +`top``middle``bottom``auto` + + +Default Value: auto +_(Default affected by value of dy; "top" for dy>0, "bottom" for dy<0.)_ + +Position of label relative to point position. +* * * + +##### text-avoid-edges `boolean` + + + +Default Value: false +_(Text will be potentially placed near tile edges and therefore may look cut off unless the same text label is rendered on each adjacent tile.)_ + +Avoid placing labels that intersect with tile boundaries. +* * * + +##### text-margin `float` + + + +Default Value: 0 +_(No extra margin will be used to determine if a label collides with any other text, shield, or marker.)_ + +Minimum distance that a label can be placed from any other text, shield, or marker. +* * * + +##### text-repeat-distance `float` + + + +Default Value: 0 +_(Labels with the same text will be rendered without restriction.)_ + +Minimum distance between repeated text. If set this will prevent text labels being rendered nearby each other that contain the same text. Similiar to text-min-distance with the difference that it works the same no matter what placement strategy is used. +* * * + +##### text-min-distance `float` + + + +Default Value: 0 +_(Labels with the same text will be rendered without restriction.)_ + +Minimum distance to the next label with the same text. Only works for line placement. Deprecated: replaced by `text-repeat-distance` and `text-margin` +* * * + +##### text-min-padding `float` + + + +Default Value: 0 +_(No margin will be used to detect if a text label is nearby a tile boundary.)_ + +Minimum distance a text label will be placed from the edge of a tile. This option is similiar to shield-avoid-edges:true except that the extra margin is used to discard cases where the shield+margin are not fully inside the tile. +* * * + +##### text-min-path-length `float` + + + +Default Value: 0 +_(place labels on all geometries no matter how small they are.)_ + +Place labels only on polygons and lines with a bounding width longer than this value (in pixels). +* * * + +##### text-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow text to overlap with other text - overlapping markers will not be shown.)_ + +Control whether overlapping text is shown or hidden. +* * * + +##### text-orientation `float` + + + +Default Value: 0 +_(Text is not rotated and is displayed upright.)_ + +Rotate the text. (only works with text-placement:point). +* * * + +##### text-rotate-displacement `boolean` + + + +Default Value: false +_(Label center is used for rotation.)_ + +Rotates the displacement around the placement origin by the angle given by "orientation". +* * * + +##### text-upright `keyword` +`auto``auto-down``left``right``left-only``right-only` + + +Default Value: auto +_(Text will be positioned upright automatically.)_ + +How this label should be placed along lines. By default when more than half of a label's characters are upside down the label is automatically flipped to keep it upright. By changing this parameter you can prevent this "auto-upright" behavior. The "auto-down" value places text in the opposite orientation to "auto". The "left" or "right" settings can be used to force text to always be placed along a line in a given direction and therefore disables flipping if text appears upside down. The "left-only" or "right-only" properties also force a given direction but will discard upside down text rather than trying to flip it. +* * * + +##### text-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point +_(One shield will be placed per geometry.)_ + +How this label should be placed. Point placement places one label on top of a point geometry and at the centroid of a polygon or the middle point of a line, line places along lines multiple times per feature, vertex places on the vertexes of polygons, and interior attempts to place inside of a polygon. +* * * + +##### text-placement-type `keyword` +`dummy``simple``list` + + +Default Value: dummy +_(Alternative placements will not be enabled.)_ + +Re-position and/or re-size text to avoid overlaps. "simple" for basic algorithm (using text-placements string,) "dummy" to turn this feature off. +* * * + +##### text-placements `string` + + + +Default Value: +_(No alternative placements will be used.)_ + +If "placement-type" is set to "simple", use this "POSITIONS,[SIZES]" string. An example is `text-placements: "E,NE,SE,W,NW,SW";`. +* * * + +##### text-transform `keyword` +`none``uppercase``lowercase``capitalize``reverse` + + +Default Value: none +_(Transform text instance with specified function. Ignores map scale factor.)_ + +Transform the case of the characters. +* * * + +##### text-horizontal-alignment `keyword` +`left``middle``right``auto``adjust` + + +Default Value: auto +_(TODO.)_ + +The text's horizontal alignment from it's centerpoint. If `placement` is set to `line`, then `adjust` can be set to auto-fit the text to the length of the path by dynamically calculating `character-spacing`. +* * * + +##### text-align `keyword` +`left``right``center``auto` + + +Default Value: auto +_(Auto alignment means that text will be centered by default except when using the `placement-type` parameter - in that case either right or left justification will be used automatically depending on where the text could be fit given the `text-placements` directives.)_ + +Define how text is justified. +* * * + +##### text-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### text-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify the geometries used for text placement by the given tolerance. +* * * + +##### text-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify the geometries used for text placement by the given algorithm. +* * * + +##### text-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out the angles of the geometry used for text placement. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### text-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### text-halo-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### text-font-feature-settings `string` + + + +Default Value: +_(Default set of typographic features recommended by OpenType specification. Ligatures are turned off by default when `character-spacing` is greater than zero.)_ + +Comma separated list of OpenType typographic features. The syntax and semantics conforms to `font-feature-settings` from W3C CSS. +* * * + +##### text-largest-bbox-only `boolean` + + + +Default Value: true +_(For multipolygons only polygon with largest bbox area is labeled (does not apply to other geometries).)_ + +Controls default labeling behavior on multipolygons. The default is true and means that only the polygon with largest bbox is labeled. +* * * + + +## building + +##### building-fill `color` + + + +Default Value: The color gray will be used for fill. +_(Gray and fully opaque (alpha = 1), same as rgb(128,128,128) or rgba(128,128,128,1).)_ + +The color of the buildings fill. Note: 0.8 will be used to multiply each color component to auto-generate a darkened wall color. +* * * + +##### building-fill-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the building as a whole, including all walls. +* * * + +##### building-height `float` + + + +Default Value: 0 +_(Buildings will not have a visual height and will instead look like flat polygons.)_ + +The height of the building in pixels. +* * * + + +## debug + +##### debug-mode `string` + + + +Default Value: collision +_(The otherwise invisible collision boxes will be rendered as squares on the map.)_ + +The mode for debug rendering. +* * * + + +## dot + +##### dot-fill `color` + + + +Default Value: gray +_(The dot fill color is gray.)_ + +The color of the area of the dot. +* * * + +##### dot-opacity `float` + + + +Default Value: 1 +_(The opacity of the dot.)_ + +The overall opacity of the dot. +* * * + +##### dot-width `float` + + + +Default Value: 1 +_(The marker width is 1 pixel.)_ + +The width of the dot in pixels. +* * * + +##### dot-height `float` + + + +Default Value: 1 +_(The marker height is 1 pixels.)_ + +The height of the dot in pixels. +* * * + +##### dot-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current layer on top of other layers.)_ + +Composite operation. This defines how this layer should behave relative to layers atop or below it. +* * * + + + + +### Values + +Below is a list of values and an explanation of any expression that can be applied to properties in CartCSS. + +### Color + +CartoCSS accepts a variety of syntaxes for colors - HTML-style hex values, rgb, rgba, hsl, hsla, husl, and husla. It also supports the predefined HTML colors names, like `yellow` and `blue`. + +``` css +#line { +line-color: #ff0; +line-color: #ffff00; +line-color: rgb(255, 255, 0); +line-color: rgba(255, 255, 0, 1); +line-color: hsl(100, 50%, 50%); +line-color: hsla(100, 50%, 50%, 1); +line-color: husl(100, 50%, 50%); // same values yield different color than HSL +line-color: husla(100, 50%, 50%, 1); +line-color: yellow; +} +``` + +Especially of note is the support for hsl and husl, which can be [easier to reason about than rgb()](http://mothereffinghsl.com/). Carto also includes several color operation functions [borrowed from less](http://lesscss.org/functions/#color-operations): + +``` css +// lighten and darken colors +lighten(#ace, 10%); +darken(#ace, 10%); + +// saturate and desaturate +saturate(#550000, 10%); +desaturate(#00ff00, 10%); + +// increase or decrease the opacity of a color +fadein(#fafafa, 10%); +fadeout(#fefefe, 14%); + +// spin rotates a color around the color wheel by degrees +spin(#ff00ff, 10); + +// mix generates a color in between two other colors. +mix(#fff, #000, 50%); + +// get color components +hue(#ff00ff); +saturation(#ff00ff); +lightness(#ff00ff); +alpha(hsla(100, 50%, 50%, 0.5)); +``` + +These functions all take arguments which can be color variables, literal colors, or the results of other functions operating on colors. All the above mentioned functions also come in +a `functionp`-variant (e.g. `lightenp`), which force a given color into perceptual color space. + +### Float + +Float is a fancy way of saying 'number'. In CartoCSS, you specify _just a number_ - unlike CSS, there are no units, but everything is specified in pixels. + +``` css +#line { +line-width: 2; +} +``` + +It's also possible to do simple math with number values: + +``` css +#line { +line-width: 4 / 2; // division +line-width: 4 + 2; // addition +line-width: 4 - 2; // subtraction +line-width: 4 * 2; // multiplication +line-width: 4 % 2; // modulus +} +``` + +### URI + +URI is a fancy way of saying URL. When an argument is a URI, you use the same kind of `url('place.png')` notation that you would with HTML. Quotes around the URL aren't required, but are highly recommended. URIs can be paths to places on your computer, or on the internet. + +```css +#markers { +marker-file: url('marker.png'); +} +``` + +### String + +A string is basically just text. In the case of CartoCSS, you're going to put it in quotes. Strings can be anything, though pay attention to the cases of `text-name` and `shield-name` - they actually will refer to features, which you refer to by putting them in brackets, as seen in the example below. + +```css +#labels { +text-name: "[MY_FIELD]"; +} +``` + +### Boolean + +Boolean means yes or no, so it accepts the values `true` or `false`. + +```css +#markers { +marker-allow-overlap:true; +} +``` + +### Expressions + +Expressions are statements that can include fields, numbers, and other types in a really flexible way. You have run into expressions before, in the realm of 'fields', where you'd specify `"[FIELD]"`, but expressions allow you to drop the quotes and also do quick addition, division, multiplication, and concatenation from within Carto syntax. + +```css +#buildings { +building-height: [HEIGHT_FIELD] * 10; +} +``` + +### Numbers +Numbers are comma-separated lists of one or more number in a specific order. They're used in line dash arrays, in which the numbers specify intervals of line, break, and line again. + +```css +#disputedboundary { +line-dasharray: 1, 4, 2; +} +``` + +### Percentages +In Carto, the percentage symbol, `%` universally means `value/100`. It's meant to be used with ratio-related properties, like opacity rules. + +_You should not use percentages as widths, heights, or other properties - unlike CSS, percentages are not relative to cascaded classes or page size, they're, as stated, simply the value divided by one hundred._ + +```css +#world { +// this syntax +polygon-opacity: 50%; + +// is equivalent to +polygon-opacity: 0.5; +} +``` + +### Functions + +Functions are comma-separated lists of one or more functions. For instance, transforms use the `functions` type to allow for transforms within Carto, which are optionally chainable. + +```css +#point { +point-transform: scale(2, 2); +} +``` diff --git a/docs/3.0.5.md b/docs/3.0.5.md new file mode 100644 index 0000000..ad7ed30 --- /dev/null +++ b/docs/3.0.5.md @@ -0,0 +1,2226 @@ +# Carto documentation + +The following is a list of properties provided in CartoCSS that you can apply to map elements. + +## All elements + +##### image-filters `functions` + +`agg-stack-blur``emboss``blur``gray``sobel``edge-detect``x-gradient``y-gradient``invert``sharpen``color-blind-protanope``color-blind-deuteranope``color-blind-tritanope``colorize-alpha``color-to-alpha``scale-hsla` + +Default Value: none +_(no filters.)_ + +A list of image filters that will be applied to the active rendering canvas for a given style. The presence of one more `image-filters` will trigger a new canvas to be created before starting to render a style and then this canvas will be composited back into the main canvas after rendering all features and after all `image-filters` have been applied. See `direct-image-filters` if you want to apply a filter directly to the main canvas. +* * * + +##### image-filters-inflate `boolean` + + + +Default Value: false +_(No special handling will be done and image filters that blur data will only blur up to the edge of a tile boundary.)_ + +A property that can be set to true to enable using an inflated image internally for seamless blurring across tiles (requires buffered data). +* * * + +##### direct-image-filters `functions` + +`agg-stack-blur``emboss``blur``gray``sobel``edge-detect``x-gradient``y-gradient``invert``sharpen``color-blind-protanope``color-blind-deuteranope``color-blind-tritanope``colorize-alpha``color-to-alpha``scale-hsla` + +Default Value: none +_(no filters.)_ + +A list of image filters to apply to the main canvas (see the `image-filters` doc for how they work on a separate canvas). +* * * + +##### comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current layer on top of other layers.)_ + +Composite operation. This defines how this layer should behave relative to layers atop or below it. +* * * + +##### opacity `float` + + + +Default Value: 1 +_(No separate buffer will be used and no alpha will be applied to the style after rendering.)_ + +An alpha value for the style (which means an alpha applied to all features in separate buffer and then composited back to main buffer). +* * * + + +## map + +##### background-color `color` + + + +Default Value: none +_(Will be rendered transparent.)_ + +Map Background color. +* * * + +##### background-image `uri` + + + +Default Value: +_(No background image will be used.)_ + +An image that is repeated below all features on a map as a background. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### background-image-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(The background-image will be blended with the background normally (placed on top of any existing background-color).)_ + +Set the compositing operation used to blend the image into the background. +* * * + +##### background-image-opacity `float` + + + +Default Value: 1 +_(The image opacity will not be changed when applied to the map background.)_ + +Set the opacity of the image. +* * * + +##### srs `string` + + + +Default Value: +proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs +_(The proj4 literal of EPSG:4326 is assumed to be the Map's spatial reference and all data from layers within this map will be plotted using this coordinate system. If any layers do not declare an srs value then they will be assumed to be in the same srs as the Map and not transformations will be needed to plot them in the Map's coordinate space.)_ + +Map spatial reference (proj4 string). +* * * + +##### buffer-size `float` + + + +Default Value: 0 +_(No buffer will be used.)_ + +Extra tolerance around the map (in pixels) used to ensure labels crossing tile boundaries are equally rendered in each tile (e.g. cut in each tile). Not intended to be used in combination with "avoid-edges". +* * * + +##### maximum-extent `string` + + + +Default Value: -20037508.34,-20037508.34,20037508.34,20037508.34 +_(All data will be clipped to global mercator extent (default is applied in Carto.js).)_ + +An extent to be used to limit the bounds used to query all layers during rendering. Should be minx, miny, maxx, maxy in the coordinates of the Map. +* * * + +##### base `string` + + + +Default Value: +_(This base path defaults to an empty string meaning that any relative paths to files referenced in styles or layers will be interpreted relative to the application process.)_ + +Any relative paths used to reference files will be understood as relative to this directory path if the map is loaded from an in memory object rather than from the filesystem. If the map is loaded from the filesystem and this option is not provided it will be set to the directory of the stylesheet. +* * * + +##### font-directory `uri` + + + +Default Value: none +_(No map-specific fonts will be registered.)_ + +Path to a directory which holds fonts which should be registered when the Map is loaded (in addition to any fonts that may be automatically registered). +* * * + + +## polygon + +##### polygon-fill `color` + + + +Default Value: The color gray will be used for fill. +_(Gray and fully opaque (alpha = 1), same as rgb(128,128,128) or rgba(128,128,128,1).)_ + +Fill color to assign to a polygon. +* * * + +##### polygon-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the polygon. +* * * + +##### polygon-gamma `float` + + + +Default Value: 1 +_(Fully antialiased.)_ +Range: 0-1 +Level of antialiasing of polygon edges. +* * * + +##### polygon-gamma-method `keyword` +`power``linear``none``threshold``multiply` + + +Default Value: power +_(pow(x,gamma) is used to calculate pixel gamma, which produces slightly smoother line and polygon antialiasing than the 'linear' method, while other methods are usually only used to disable AA.)_ + +An Antigrain Geometry specific rendering hint to control the quality of antialiasing. Under the hood in Mapnik this method is used in combination with the 'gamma' value (which defaults to 1). The methods are in the AGG source at https://github.com/mapnik/mapnik/blob/master/deps/agg/include/agg_gamma_functions. +* * * + +##### polygon-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extend outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### polygon-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify geometries by the given tolerance. +* * * + +##### polygon-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify geometries by the given algorithm. +* * * + +##### polygon-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### polygon-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform polygon geometry with specified function. +* * * + +##### polygon-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## line + +##### line-color `color` + + + +Default Value: black +_(black and fully opaque (alpha = 1), same as rgb(0,0,0) or rgba(0,0,0,1).)_ + +The color of a drawn line. +* * * + +##### line-width `float` + + + +Default Value: 1 +_(The line will be rendered 1 pixel wide.)_ + +The width of a line in pixels. +* * * + +##### line-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of a line. +* * * + +##### line-join `keyword` +`miter``miter-revert``round``bevel` + + +Default Value: miter +_(The line joins will be rendered using a miter look.)_ + +The behavior of lines when joining. +* * * + +##### line-cap `keyword` +`butt``round``square` + + +Default Value: butt +_(The line endings will be rendered using a butt look.)_ + +The display of line endings. +* * * + +##### line-gamma `float` + + + +Default Value: 1 +_(Fully antialiased.)_ +Range: 0-1 +Level of antialiasing of stroke line. +* * * + +##### line-gamma-method `keyword` +`power``linear``none``threshold``multiply` + + +Default Value: power +_(pow(x,gamma) is used to calculate pixel gamma, which produces slightly smoother line and polygon antialiasing than the 'linear' method, while other methods are usually only used to disable AA.)_ + +An Antigrain Geometry specific rendering hint to control the quality of antialiasing. Under the hood in Mapnik this method is used in combination with the 'gamma' value (which defaults to 1). The methods are in the AGG source at https://github.com/mapnik/mapnik/blob/master/deps/agg/include/agg_gamma_functions. +* * * + +##### line-dasharray `numbers` + + + +Default Value: none +_(The line will be drawn without dashes.)_ + +A pair of length values [a,b], where (a) is the dash length and (b) is the gap length respectively. More than two values are supported for more complex patterns. +* * * + +##### line-dash-offset `numbers` + + + +Default Value: none +_(The line will be drawn without dashes.)_ + +Valid parameter but not currently used in renderers (only exists for experimental svg support in Mapnik which is not yet enabled). +* * * + +##### line-miterlimit `float` + + + +Default Value: 4 +_(Will auto-convert miters to bevel line joins when theta is less than 29 degrees as per the SVG spec: 'miterLength / stroke-width = 1 / sin ( theta / 2 )'.)_ + +The limit on the ratio of the miter length to the stroke-width. Used to automatically convert miter joins to bevel joins for sharp angles to avoid the miter extending beyond the thickness of the stroking path. Normally will not need to be set, but a larger value can sometimes help avoid jaggy artifacts. +* * * + +##### line-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### line-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify geometries by the given tolerance. +* * * + +##### line-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify geometries by the given algorithm. +* * * + +##### line-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### line-offset `float` + + + +Default Value: 0 +_(Will not be offset.)_ + +Offsets a line a number of pixels parallel to its actual path. Positive values move the line left, negative values move it right (relative to the directionality of the line). +* * * + +##### line-rasterizer `keyword` +`full``fast` + + +Default Value: full +_(The line will be rendered using the highest quality method rather than the fastest.)_ + +Exposes an alternate AGG rendering method that sacrifices some accuracy for speed. +* * * + +##### line-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform line geometry with specified function. +* * * + +##### line-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## markers + +##### marker-file `uri` + + + +Default Value: none +_(An ellipse or circle, if width equals height.)_ + +A file that this marker shows at each placement. If no file is given, the marker will show an ellipse. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### marker-opacity `float` + + + +Default Value: 1 +_(The stroke-opacity and fill-opacity of the marker.)_ + +The overall opacity of the marker, if set, overrides both the opacity of both the fill and stroke. +* * * + +##### marker-fill-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The fill opacity of the marker. +* * * + +##### marker-line-color `color` + + + +Default Value: black +_(The marker will be drawn with a black outline.)_ + +The color of the stroke around the marker. +* * * + +##### marker-line-width `float` + + + +Default Value: 0.5 +_(The marker will be drawn with an outline of .5 pixels wide.)_ + +The width of the stroke around the marker, in pixels. This is positioned on the boundary, so high values can cover the area itself. +* * * + +##### marker-line-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of a line. +* * * + +##### marker-placement `keyword` +`point``line``interior``vertex-first``vertex-last` + + +Default Value: point +_(Place markers at the center point (centroid) of the geometry.)_ + +Attempt to place markers on a point, in the center of a polygon, or if markers-placement:line, then multiple times along a line. 'interior' placement can be used to ensure that points placed on polygons are forced to be inside the polygon interior. The 'vertex-first' and 'vertex-last' options can be used to place markers at the first or last vertex of lines or polygons. +* * * + +##### marker-multi-policy `keyword` +`each``whole``largest` + + +Default Value: each +_(If a feature contains multiple geometries and the placement type is either point or interior then a marker will be rendered for each.)_ + +A special setting to allow the user to control rendering behavior for 'multi-geometries' (when a feature contains multiple geometries). This setting does not apply to markers placed along lines. The 'each' policy is default and means all geometries will get a marker. The 'whole' policy means that the aggregate centroid between all geometries will be used. The 'largest' policy means that only the largest (by bounding box areas) feature will get a rendered marker (this is how text labeling behaves by default). +* * * + +##### marker-type `keyword` +`arrow``ellipse` + + +Default Value: ellipse +_(The marker shape is an ellipse.)_ + +The default marker-type. If a SVG file is not given as the marker-file parameter, the renderer provides either an arrow or an ellipse (a circle if height is equal to width). +* * * + +##### marker-width `float` + + + +Default Value: 10 +_(The marker width is 10 pixels.)_ + +The width of the marker, if using one of the default types. +* * * + +##### marker-height `float` + + + +Default Value: 10 +_(The marker height is 10 pixels.)_ + +The height of the marker, if using one of the default types. +* * * + +##### marker-fill `color` + + + +Default Value: blue +_(The marker fill color is blue.)_ + +The color of the area of the marker. +* * * + +##### marker-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow markers to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping markers are shown or hidden. +* * * + +##### marker-avoid-edges `boolean` + + + +Default Value: false +_(Markers will be potentially placed near tile edges and therefore may look cut off unless they are rendered on each adjacent tile.)_ + +Avoid placing markers that intersect with tile boundaries. +* * * + +##### marker-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache.)_ + +Value to control whether the placement of the feature will prevent the placement of other features. +* * * + +##### marker-spacing `float` + + + +Default Value: 100 +_(In the case of marker-placement:line then draw a marker every 100 pixels along a line.)_ + +Space between repeated markers in pixels. If the spacing is less than the marker size or larger than the line segment length then no marker will be placed. Any value less than 1 will be ignored and the default will be used instead. +* * * + +##### marker-max-error `float` + + + +Default Value: 0.2 +_(N/A: not intended to be changed.)_ + +N/A: not intended to be changed. +* * * + +##### marker-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation.)_ + +Transform marker instance with specified function. Ignores map scale factor. +* * * + +##### marker-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### marker-simplify `float` + + + +Default Value: 0 +_(Geometry will not be simplified.)_ + +geometries are simplified by the given tolerance. +* * * + +##### marker-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +geometries are simplified by the given algorithm. +* * * + +##### marker-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### marker-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform marker geometry with specified function. +* * * + +##### marker-offset `float` + + + +Default Value: 0 +_(Will not be offset.)_ + +Offsets a marker from a line a number of pixels parallel to its actual path. Positive values move the marker left, negative values move it right (relative to the directionality of the line). +* * * + +##### marker-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### marker-direction `keyword` +`auto``auto-down``left``right``left-only``right-only``up``down` + + +Default Value: right +_(Markers are oriented to the right in the line direction.)_ + +How markers should be placed along lines. With the "auto" setting when marker is upside down the marker is automatically rotated by 180 degrees to keep it upright. The "auto-down" value places marker in the opposite orientation to "auto". The "left" or "right" settings can be used to force marker to always be placed along a line in a given direction and therefore disables rotating if marker appears upside down. The "left-only" or "right-only" properties also force a given direction but will discard upside down markers rather than trying to flip it. The "up" and "down" settings don't adjust marker's orientation to the line direction. +* * * + + +## shield + +##### shield-name `string` + + + +Default Value: +_(No text label will be rendered with the shield.)_ + +Value to use for a shield"s text label. Data columns are specified using brackets like [column_name]. +* * * + +##### shield-file `uri` + + + +Default Value: none + + +Image file to render behind the shield text. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### shield-face-name `string` + + + +Default Value: none + + +Font name and style to use for the shield text. +* * * + +##### shield-unlock-image `boolean` + + + +Default Value: false +_(text alignment relative to the shield image uses the center of the image as the anchor for text positioning.)_ + +This parameter should be set to true if you are trying to position text beside rather than on top of the shield image. +* * * + +##### shield-size `float` + + + +Default Value: 10 +_(Font size of 10 will be used to render text.)_ + +The size of the shield text in pixels. +* * * + +##### shield-fill `color` + + + +Default Value: black +_(The shield text will be rendered black.)_ + +The color of the shield text. +* * * + +##### shield-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point +_(One shield will be placed per geometry.)_ + +How this shield should be placed. Point placement places one shield on top of a point geometry and at the centroid of a polygon or the middle point of a line, line places along lines multiple times per feature, vertex places on the vertexes of polygons, and interior attempts to place inside of a polygon. +* * * + +##### shield-avoid-edges `boolean` + + + +Default Value: false +_(Shields will be potentially placed near tile edges and therefore may look cut off unless they are rendered on each adjacent tile.)_ + +Avoid placing shields that intersect with tile boundaries. +* * * + +##### shield-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow shields to overlap with other map elements already placed.)_ + +Control whether overlapping shields are shown or hidden. +* * * + +##### shield-margin `float` + + + +Default Value: 0 +_(No extra margin will be used to determine if a shield collides with any other text, shield, or marker.)_ + +Minimum distance that a shield can be placed from any other text, shield, or marker. +* * * + +##### shield-repeat-distance `float` + + + +Default Value: 0 +_(Shields with the same text will be rendered without restriction.)_ + +Minimum distance between repeated shields. If set this will prevent shields being rendered nearby each other that contain the same text. Similiar to shield-min-distance with the difference that it works the same no matter what placement strategy is used. +* * * + +##### shield-min-distance `float` + + + +Default Value: 0 +_(Shields with the same text will be rendered without restriction.)_ + +Minimum distance to the next shield with the same text. Only works for line placement. +* * * + +##### shield-spacing `float` + + + +Default Value: 0 +_(Only one shield per line will attempt to be placed.)_ + +Distance the renderer should use to try to place repeated shields on a line. +* * * + +##### shield-min-padding `float` + + + +Default Value: 0 +_(No margin will be used to detect if a shield is nearby a tile boundary.)_ + +Minimum distance a shield will be placed from the edge of a tile. This option is similiar to shield-avoid-edges:true except that the extra margin is used to discard cases where the shield+margin are not fully inside the tile. +* * * + +##### shield-label-position-tolerance `float` + + + +Default Value: shield-spacing/2.0 +_(If a shield cannot be placed then the renderer will advance by shield-spacing/2.0 to try placement again.)_ + +Allows the shield to be displaced from its ideal position by a number of pixels (only works with placement:line). +* * * + +##### shield-wrap-width `unsigned` + + + +Default Value: 0 +_(Text will not be wrapped.)_ + +Length of a chunk of text in pixels before wrapping text. If set to zero, text doesn't wrap. +* * * + +##### shield-wrap-before `boolean` + + + +Default Value: false +_(Wrapped lines will be a bit longer than wrap-width.)_ + +Wrap text before wrap-width is reached. +* * * + +##### shield-wrap-character `string` + + + +Default Value: " " +_(Lines will be wrapped when whitespace is encountered.)_ + +Use this character instead of a space to wrap long names. +* * * + +##### shield-halo-fill `color` + + + +Default Value: white +_(The shield halo text will be rendered white.)_ + +Specifies the color of the halo around the text. +* * * + +##### shield-halo-radius `float` + + + +Default Value: 0 +_(no halo.)_ + +Specify the radius of the halo in pixels. +* * * + +##### shield-halo-rasterizer `keyword` +`full``fast` + + +Default Value: full +_(The shield will be rendered using the highest quality method rather than the fastest.)_ + +Exposes an alternate text halo rendering method that sacrifices quality for speed. +* * * + +##### shield-halo-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: +_(No transformation.)_ + +Transform shield halo relative to the actual text with specified function. Allows for shadow or embossed effects. Ignores map scale factor. +* * * + +##### shield-halo-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### shield-halo-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A number from 0 to 1 specifying the opacity for the text halo. +* * * + +##### shield-character-spacing `unsigned` + + + +Default Value: 0 +_(The default character spacing of the font will be used.)_ + +Horizontal spacing between characters (in pixels). Currently works for point placement only, not line placement. +* * * + +##### shield-line-spacing `unsigned` + + + +Default Value: 0 +_(The default font spacing will be used.)_ + +Vertical spacing between lines of multiline labels (in pixels). +* * * + +##### shield-text-dx `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text within shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the shield right. +* * * + +##### shield-text-dy `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text within shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the shield down. +* * * + +##### shield-dx `float` + + + +Default Value: 0 +_(Shield will not be displaced.)_ + +Displace shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right. +* * * + +##### shield-dy `float` + + + +Default Value: 0 +_(Shield will not be displaced.)_ + +Displace shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text down. +* * * + +##### shield-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the image used for the shield. +* * * + +##### shield-text-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the text placed on top of the shield. +* * * + +##### shield-horizontal-alignment `keyword` +`left``middle``right``auto` + + +Default Value: auto +_(TODO.)_ + +The shield's horizontal alignment from its centerpoint. +* * * + +##### shield-vertical-alignment `keyword` +`top``middle``bottom``auto` + + +Default Value: middle +_(TODO.)_ + +The shield's vertical alignment from its centerpoint. +* * * + +##### shield-placement-type `keyword` +`dummy``simple``list` + + +Default Value: dummy +_(Alternative placements will not be enabled.)_ + +Re-position and/or re-size shield to avoid overlaps. "simple" for basic algorithm (using shield-placements string,) "dummy" to turn this feature off. +* * * + +##### shield-placements `string` + + + +Default Value: +_(No alternative placements will be used.)_ + +If "placement-type" is set to "simple", use this "POSITIONS,[SIZES]" string. An example is `shield-placements: "E,NE,SE,W,NW,SW";`. +* * * + +##### shield-text-transform `keyword` +`none``uppercase``lowercase``capitalize``reverse` + + +Default Value: none +_(No text transformation will be applied.)_ + +Transform the case of the characters. +* * * + +##### shield-justify-alignment `keyword` +`left``center``right``auto` + + +Default Value: auto +_(TODO.)_ + +Define how text in a shield's label is justified. +* * * + +##### shield-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation.)_ + +Transform shield instance with specified function. Ignores map scale factor. +* * * + +##### shield-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### shield-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify the geometries used for shield placement by the given tolerance. +* * * + +##### shield-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify the geometries used for shield placement by the given algorithm. +* * * + +##### shield-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out the angles of the geometry used for shield placement. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### shield-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## line-pattern + +##### line-pattern-file `uri` + + + +Default Value: none + + +An image file to be repeated and warped along a line. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### line-pattern-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### line-pattern-opacity `float` + + + +Default Value: 1 +_(The image is rendered without modifications.)_ + +Apply an opacity level to the image used for the pattern. +* * * + +##### line-pattern-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +geometries are simplified by the given tolerance. +* * * + +##### line-pattern-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +geometries are simplified by the given algorithm. +* * * + +##### line-pattern-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### line-pattern-offset `float` + + + +Default Value: 0 +_(The line will not be offset.)_ + +Offsets a line a number of pixels parallel to its actual path. Positive values move the line left, negative values move it right (relative to the directionality of the line). +* * * + +##### line-pattern-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform line geometry with specified function and apply pattern to transformed geometry. +* * * + +##### line-pattern-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## polygon-pattern + +##### polygon-pattern-file `uri` + + + +Default Value: none + + +Image to use as a repeated pattern fill within a polygon. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### polygon-pattern-alignment `keyword` +`global``local` + + +Default Value: global +_(Patterns will be aligned to the map (or tile boundaries) when being repeated across polygons. This is ideal for seamless patterns in tiled rendering.)_ + +Specify whether to align pattern fills to the layer's geometry (local) or to the map (global). +* * * + +##### polygon-pattern-gamma `float` + + + +Default Value: 1 +_(Fully antialiased.)_ +Range: 0-1 +Level of antialiasing of polygon pattern edges. +* * * + +##### polygon-pattern-opacity `float` + + + +Default Value: 1 +_(The image is rendered without modifications.)_ + +Apply an opacity level to the image used for the pattern. +* * * + +##### polygon-pattern-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### polygon-pattern-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +geometries are simplified by the given tolerance. +* * * + +##### polygon-pattern-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +geometries are simplified by the given algorithm. +* * * + +##### polygon-pattern-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### polygon-pattern-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform polygon geometry with specified function and apply pattern to transformed geometry. +* * * + +##### polygon-pattern-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## raster + +##### raster-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the raster symbolizer on top of other symbolizers. +* * * + +##### raster-filter-factor `float` + + + +Default Value: -1 +_(Allow the datasource to choose appropriate downscaling.)_ + +This is used by the Raster or Gdal datasources to pre-downscale images using overviews. Higher numbers can sometimes cause much better scaled image output, at the cost of speed. +* * * + +##### raster-scaling `keyword` +`near``fast``bilinear``bicubic``spline16``spline36``hanning``hamming``hermite``kaiser``quadric``catrom``gaussian``bessel``mitchell``sinc``lanczos``blackman` + + +Default Value: near +_(Nearest neighboor resampling will be used to scale the image to the target size of the map.)_ + +The scaling algorithm used to making different resolution versions of this raster layer. Bilinear is a good compromise between speed and accuracy, while lanczos gives the highest quality. +* * * + +##### raster-mesh-size `unsigned` + + + +Default Value: 16 +_(Reprojection mesh will be 1/16 of the resolution of the source image.)_ + +A reduced resolution mesh is used for raster reprojection, and the total image size is divided by the mesh-size to determine the quality of that mesh. Values for mesh-size larger than the default will result in faster reprojection but might lead to distortion. +* * * + +##### raster-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### raster-colorizer-default-mode `keyword` +`discrete``linear``exact` + + +Default Value: linear +_(A linear interpolation is used to generate colors between the two nearest stops.)_ + +This can be either `discrete`, `linear` or `exact`. If it is not specified then the default is `linear`. +* * * + +##### raster-colorizer-default-color `color` + + + +Default Value: transparent +_(Pixels that are not colored by the colorizer stops will be transparent.)_ + +This can be any color. Sets the color that is applied to all values outside of the range of the colorizer-stops. If not supplied pixels will be fully transparent. +* * * + +##### raster-colorizer-epsilon `float` + + + +Default Value: 1.1920928955078125e-07 +_(Pixels must very closely match the stop filter otherwise they will not be colored.)_ + +This can be any positive floating point value and will be used as a tolerance in floating point comparisions. The higher the value the more likely a stop will match and color data. +* * * + +##### raster-colorizer-stops `tags` + + + +Default Value: +_(No colorization will happen without supplying stops.)_ + +Assigns raster data values to colors. Stops must be listed in ascending order, and contain at a minimum the value and the associated color. You can also include the color-mode as a third argument, like `stop(100,#fff,exact)`. +* * * + + +## point + +##### point-file `uri` + + + +Default Value: none +_(A 4x4 black square will be rendered.)_ + +Image file to represent a point. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### point-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow points to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping points are shown or hidden. +* * * + +##### point-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache.)_ + +Control whether the placement of the feature will prevent the placement of other features. +* * * + +##### point-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A value from 0 to 1 to control the opacity of the point. +* * * + +##### point-placement `keyword` +`centroid``interior` + + +Default Value: centroid +_(The centroid of the geometry will be used to place the point.)_ + +Control how this point should be placed. Centroid calculates the geometric center of a polygon, which can be outside of it, while interior always places inside of a polygon. +* * * + +##### point-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation.)_ + +Transform point instance with specified function. Ignores map scale factor. +* * * + +##### point-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## text + +##### text-name `string` + + + +Default Value: none + + +Value to use for a text label. Data columns are specified using brackets like [column_name]. +* * * + +##### text-face-name `string` + + + +Default Value: none + + +Font name and style to render a label in. +* * * + +##### text-size `float` + + + +Default Value: 10 +_(Font size of 10 will be used to render text.)_ + +Text size in pixels. +* * * + +##### text-ratio `unsigned` + + + +Default Value: 0 +_(TODO.)_ + +Define the amount of text (of the total) present on successive lines when wrapping occurs. +* * * + +##### text-wrap-width `unsigned` + + + +Default Value: 0 +_(Text will not be wrapped.)_ + +Length of a chunk of text in pixels before wrapping text. If set to zero, text doesn't wrap. +* * * + +##### text-wrap-before `boolean` + + + +Default Value: false +_(Wrapped lines will be a bit longer than wrap-width.)_ + +Wrap text before wrap-width is reached. +* * * + +##### text-wrap-character `string` + + + +Default Value: " " +_(Lines will be wrapped when whitespace is encountered.)_ + +Use this character instead of a space to wrap long text. +* * * + +##### text-repeat-wrap-character `boolean` + + + +Default Value: false +_(Character will be removed when used to wrap a line.)_ + +Keep the character used to wrap a line instead of removing it, and repeat it on the new line. +* * * + +##### text-spacing `unsigned` + + + +Default Value: 0 +_(Only one label per line will attempt to be placed.)_ + +Distance the renderer should use to try to place repeated text labels on a line. +* * * + +##### text-character-spacing `float` + + + +Default Value: 0 +_(The default character spacing of the font will be used.)_ + +Horizontal spacing adjustment between characters in pixels. This value is ignored when `horizontal-alignment` is set to `adjust`. Typographic ligatures are turned off when this value is greater than zero. +* * * + +##### text-line-spacing `unsigned` + + + +Default Value: 0 +_(The default font spacing will be used.)_ + +Vertical spacing adjustment between lines in pixels. +* * * + +##### text-label-position-tolerance `float` + + + +Default Value: text-spacing/2.0 +_(If a shield cannot be placed then the renderer will advance by text-spacing/2.0 to try placement again.)_ + +Allows the label to be displaced from its ideal position by a number of pixels (only works with placement:line). +* * * + +##### text-max-char-angle-delta `float` + + + +Default Value: 22.5 +_(The label will not be placed if a character falls on a line with an angle sharper than 22.5 degrees.)_ + +The maximum angle change, in degrees, allowed between adjacent characters in a label. This value internally is converted to radians to the default is 22.5*math.pi/180.0. The higher the value the fewer labels will be placed around around sharp corners. +* * * + +##### text-fill `color` + + + +Default Value: black +_(The text will be rendered black.)_ + +Specifies the color for the text. +* * * + +##### text-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A number from 0 to 1 specifying the opacity for the text. +* * * + +##### text-halo-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A number from 0 to 1 specifying the opacity for the text halo. +* * * + +##### text-halo-fill `color` + + + +Default Value: white +_(The halo will be rendered white.)_ + +Specifies the color of the halo around the text. +* * * + +##### text-halo-radius `float` + + + +Default Value: 0 +_(no halo.)_ + +Specify the radius of the halo in pixels. +* * * + +##### text-halo-rasterizer `keyword` +`full``fast` + + +Default Value: full +_(The text will be rendered using the highest quality method rather than the fastest.)_ + +Exposes an alternate text halo rendering method that sacrifices quality for speed. +* * * + +##### text-halo-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: +_(No transformation.)_ + +Transform text halo relative to the actual text with specified function. Allows for shadow or embossed effects. Ignores map scale factor. +* * * + +##### text-dx `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text by fixed amount, in pixels, +/- along the X axis. With "dummy" placement-type, a positive value displaces to the right. With "simple" placement-type, it is either left, right or unchanged, depending on the placement selected. Any non-zero value implies "horizontal-alignment" changes to "left" by default. Has no effect with 'line' text-placement-type. +* * * + +##### text-dy `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text by fixed amount, in pixels, +/- along the Y axis. With "dummy" placement-type, a positive value displaces downwards. With "simple" placement-type, it is either up, down or unchanged, depending on the placement selected. With "line" placement-type, a positive value displaces above the path. +* * * + +##### text-vertical-alignment `keyword` +`top``middle``bottom``auto` + + +Default Value: auto +_(Default affected by value of dy; "top" for dy>0, "bottom" for dy<0.)_ + +Position of label relative to point position. +* * * + +##### text-avoid-edges `boolean` + + + +Default Value: false +_(Text will be potentially placed near tile edges and therefore may look cut off unless the same text label is rendered on each adjacent tile.)_ + +Avoid placing labels that intersect with tile boundaries. +* * * + +##### text-margin `float` + + + +Default Value: 0 +_(No extra margin will be used to determine if a label collides with any other text, shield, or marker.)_ + +Minimum distance that a label can be placed from any other text, shield, or marker. +* * * + +##### text-repeat-distance `float` + + + +Default Value: 0 +_(Labels with the same text will be rendered without restriction.)_ + +Minimum distance between repeated text. If set this will prevent text labels being rendered nearby each other that contain the same text. Similiar to text-min-distance with the difference that it works the same no matter what placement strategy is used. +* * * + +##### text-min-distance `float` + + + +Default Value: 0 +_(Labels with the same text will be rendered without restriction.)_ + +Minimum distance to the next label with the same text. Only works for line placement. Deprecated: replaced by `text-repeat-distance` and `text-margin` +* * * + +##### text-min-padding `float` + + + +Default Value: 0 +_(No margin will be used to detect if a text label is nearby a tile boundary.)_ + +Minimum distance a text label will be placed from the edge of a tile. This option is similiar to shield-avoid-edges:true except that the extra margin is used to discard cases where the shield+margin are not fully inside the tile. +* * * + +##### text-min-path-length `float` + + + +Default Value: 0 +_(place labels on all geometries no matter how small they are.)_ + +Place labels only on polygons and lines with a bounding width longer than this value (in pixels). +* * * + +##### text-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow text to overlap with other text - overlapping markers will not be shown.)_ + +Control whether overlapping text is shown or hidden. +* * * + +##### text-orientation `float` + + + +Default Value: 0 +_(Text is not rotated and is displayed upright.)_ + +Rotate the text. (only works with text-placement:point). +* * * + +##### text-rotate-displacement `boolean` + + + +Default Value: false +_(Label center is used for rotation.)_ + +Rotates the displacement around the placement origin by the angle given by "orientation". +* * * + +##### text-upright `keyword` +`auto``auto-down``left``right``left-only``right-only` + + +Default Value: auto +_(Text will be positioned upright automatically.)_ + +How this label should be placed along lines. By default when more than half of a label's characters are upside down the label is automatically flipped to keep it upright. By changing this parameter you can prevent this "auto-upright" behavior. The "auto-down" value places text in the opposite orientation to "auto". The "left" or "right" settings can be used to force text to always be placed along a line in a given direction and therefore disables flipping if text appears upside down. The "left-only" or "right-only" properties also force a given direction but will discard upside down text rather than trying to flip it. +* * * + +##### text-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point +_(One shield will be placed per geometry.)_ + +How this label should be placed. Point placement places one label on top of a point geometry and at the centroid of a polygon or the middle point of a line, line places along lines multiple times per feature, vertex places on the vertexes of polygons, and interior attempts to place inside of a polygon. +* * * + +##### text-placement-type `keyword` +`dummy``simple``list` + + +Default Value: dummy +_(Alternative placements will not be enabled.)_ + +Re-position and/or re-size text to avoid overlaps. "simple" for basic algorithm (using text-placements string,) "dummy" to turn this feature off. +* * * + +##### text-placements `string` + + + +Default Value: +_(No alternative placements will be used.)_ + +If "placement-type" is set to "simple", use this "POSITIONS,[SIZES]" string. An example is `text-placements: "E,NE,SE,W,NW,SW";`. +* * * + +##### text-transform `keyword` +`none``uppercase``lowercase``capitalize``reverse` + + +Default Value: none +_(Transform text instance with specified function. Ignores map scale factor.)_ + +Transform the case of the characters. +* * * + +##### text-horizontal-alignment `keyword` +`left``middle``right``auto``adjust` + + +Default Value: auto +_(TODO.)_ + +The text's horizontal alignment from it's centerpoint. If `placement` is set to `line`, then `adjust` can be set to auto-fit the text to the length of the path by dynamically calculating `character-spacing`. +* * * + +##### text-align `keyword` +`left``right``center``auto` + + +Default Value: auto +_(Auto alignment means that text will be centered by default except when using the `placement-type` parameter - in that case either right or left justification will be used automatically depending on where the text could be fit given the `text-placements` directives.)_ + +Define how text is justified. +* * * + +##### text-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### text-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify the geometries used for text placement by the given tolerance. +* * * + +##### text-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify the geometries used for text placement by the given algorithm. +* * * + +##### text-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out the angles of the geometry used for text placement. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### text-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### text-halo-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### text-font-feature-settings `string` + + + +Default Value: +_(Default set of typographic features recommended by OpenType specification. Ligatures are turned off by default when `character-spacing` is greater than zero.)_ + +Comma separated list of OpenType typographic features. The syntax and semantics conforms to `font-feature-settings` from W3C CSS. +* * * + +##### text-largest-bbox-only `boolean` + + + +Default Value: true +_(For multipolygons only polygon with largest bbox area is labeled (does not apply to other geometries).)_ + +Controls default labeling behavior on multipolygons. The default is true and means that only the polygon with largest bbox is labeled. +* * * + + +## building + +##### building-fill `color` + + + +Default Value: The color gray will be used for fill. +_(Gray and fully opaque (alpha = 1), same as rgb(128,128,128) or rgba(128,128,128,1).)_ + +The color of the buildings fill. Note: 0.8 will be used to multiply each color component to auto-generate a darkened wall color. +* * * + +##### building-fill-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the building as a whole, including all walls. +* * * + +##### building-height `float` + + + +Default Value: 0 +_(Buildings will not have a visual height and will instead look like flat polygons.)_ + +The height of the building in pixels. +* * * + + +## debug + +##### debug-mode `string` + + + +Default Value: collision +_(The otherwise invisible collision boxes will be rendered as squares on the map.)_ + +The mode for debug rendering. +* * * + + +## dot + +##### dot-fill `color` + + + +Default Value: gray +_(The dot fill color is gray.)_ + +The color of the area of the dot. +* * * + +##### dot-opacity `float` + + + +Default Value: 1 +_(The opacity of the dot.)_ + +The overall opacity of the dot. +* * * + +##### dot-width `float` + + + +Default Value: 1 +_(The marker width is 1 pixel.)_ + +The width of the dot in pixels. +* * * + +##### dot-height `float` + + + +Default Value: 1 +_(The marker height is 1 pixels.)_ + +The height of the dot in pixels. +* * * + +##### dot-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current layer on top of other layers.)_ + +Composite operation. This defines how this layer should behave relative to layers atop or below it. +* * * + + + + +### Values + +Below is a list of values and an explanation of any expression that can be applied to properties in CartCSS. + +### Color + +CartoCSS accepts a variety of syntaxes for colors - HTML-style hex values, rgb, rgba, hsl, hsla, husl, and husla. It also supports the predefined HTML colors names, like `yellow` and `blue`. + +``` css +#line { +line-color: #ff0; +line-color: #ffff00; +line-color: rgb(255, 255, 0); +line-color: rgba(255, 255, 0, 1); +line-color: hsl(100, 50%, 50%); +line-color: hsla(100, 50%, 50%, 1); +line-color: husl(100, 50%, 50%); // same values yield different color than HSL +line-color: husla(100, 50%, 50%, 1); +line-color: yellow; +} +``` + +Especially of note is the support for hsl and husl, which can be [easier to reason about than rgb()](http://mothereffinghsl.com/). Carto also includes several color operation functions [borrowed from less](http://lesscss.org/functions/#color-operations): + +``` css +// lighten and darken colors +lighten(#ace, 10%); +darken(#ace, 10%); + +// saturate and desaturate +saturate(#550000, 10%); +desaturate(#00ff00, 10%); + +// increase or decrease the opacity of a color +fadein(#fafafa, 10%); +fadeout(#fefefe, 14%); + +// spin rotates a color around the color wheel by degrees +spin(#ff00ff, 10); + +// mix generates a color in between two other colors. +mix(#fff, #000, 50%); + +// get color components +hue(#ff00ff); +saturation(#ff00ff); +lightness(#ff00ff); +alpha(hsla(100, 50%, 50%, 0.5)); +``` + +These functions all take arguments which can be color variables, literal colors, or the results of other functions operating on colors. All the above mentioned functions also come in +a `functionp`-variant (e.g. `lightenp`), which force a given color into perceptual color space. + +### Float + +Float is a fancy way of saying 'number'. In CartoCSS, you specify _just a number_ - unlike CSS, there are no units, but everything is specified in pixels. + +``` css +#line { +line-width: 2; +} +``` + +It's also possible to do simple math with number values: + +``` css +#line { +line-width: 4 / 2; // division +line-width: 4 + 2; // addition +line-width: 4 - 2; // subtraction +line-width: 4 * 2; // multiplication +line-width: 4 % 2; // modulus +} +``` + +### URI + +URI is a fancy way of saying URL. When an argument is a URI, you use the same kind of `url('place.png')` notation that you would with HTML. Quotes around the URL aren't required, but are highly recommended. URIs can be paths to places on your computer, or on the internet. + +```css +#markers { +marker-file: url('marker.png'); +} +``` + +### String + +A string is basically just text. In the case of CartoCSS, you're going to put it in quotes. Strings can be anything, though pay attention to the cases of `text-name` and `shield-name` - they actually will refer to features, which you refer to by putting them in brackets, as seen in the example below. + +```css +#labels { +text-name: "[MY_FIELD]"; +} +``` + +### Boolean + +Boolean means yes or no, so it accepts the values `true` or `false`. + +```css +#markers { +marker-allow-overlap:true; +} +``` + +### Expressions + +Expressions are statements that can include fields, numbers, and other types in a really flexible way. You have run into expressions before, in the realm of 'fields', where you'd specify `"[FIELD]"`, but expressions allow you to drop the quotes and also do quick addition, division, multiplication, and concatenation from within Carto syntax. + +```css +#buildings { +building-height: [HEIGHT_FIELD] * 10; +} +``` + +### Numbers +Numbers are comma-separated lists of one or more number in a specific order. They're used in line dash arrays, in which the numbers specify intervals of line, break, and line again. + +```css +#disputedboundary { +line-dasharray: 1, 4, 2; +} +``` + +### Percentages +In Carto, the percentage symbol, `%` universally means `value/100`. It's meant to be used with ratio-related properties, like opacity rules. + +_You should not use percentages as widths, heights, or other properties - unlike CSS, percentages are not relative to cascaded classes or page size, they're, as stated, simply the value divided by one hundred._ + +```css +#world { +// this syntax +polygon-opacity: 50%; + +// is equivalent to +polygon-opacity: 0.5; +} +``` + +### Functions + +Functions are comma-separated lists of one or more functions. For instance, transforms use the `functions` type to allow for transforms within Carto, which are optionally chainable. + +```css +#point { +point-transform: scale(2, 2); +} +``` diff --git a/docs/3.0.6.md b/docs/3.0.6.md new file mode 100644 index 0000000..ad7ed30 --- /dev/null +++ b/docs/3.0.6.md @@ -0,0 +1,2226 @@ +# Carto documentation + +The following is a list of properties provided in CartoCSS that you can apply to map elements. + +## All elements + +##### image-filters `functions` + +`agg-stack-blur``emboss``blur``gray``sobel``edge-detect``x-gradient``y-gradient``invert``sharpen``color-blind-protanope``color-blind-deuteranope``color-blind-tritanope``colorize-alpha``color-to-alpha``scale-hsla` + +Default Value: none +_(no filters.)_ + +A list of image filters that will be applied to the active rendering canvas for a given style. The presence of one more `image-filters` will trigger a new canvas to be created before starting to render a style and then this canvas will be composited back into the main canvas after rendering all features and after all `image-filters` have been applied. See `direct-image-filters` if you want to apply a filter directly to the main canvas. +* * * + +##### image-filters-inflate `boolean` + + + +Default Value: false +_(No special handling will be done and image filters that blur data will only blur up to the edge of a tile boundary.)_ + +A property that can be set to true to enable using an inflated image internally for seamless blurring across tiles (requires buffered data). +* * * + +##### direct-image-filters `functions` + +`agg-stack-blur``emboss``blur``gray``sobel``edge-detect``x-gradient``y-gradient``invert``sharpen``color-blind-protanope``color-blind-deuteranope``color-blind-tritanope``colorize-alpha``color-to-alpha``scale-hsla` + +Default Value: none +_(no filters.)_ + +A list of image filters to apply to the main canvas (see the `image-filters` doc for how they work on a separate canvas). +* * * + +##### comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current layer on top of other layers.)_ + +Composite operation. This defines how this layer should behave relative to layers atop or below it. +* * * + +##### opacity `float` + + + +Default Value: 1 +_(No separate buffer will be used and no alpha will be applied to the style after rendering.)_ + +An alpha value for the style (which means an alpha applied to all features in separate buffer and then composited back to main buffer). +* * * + + +## map + +##### background-color `color` + + + +Default Value: none +_(Will be rendered transparent.)_ + +Map Background color. +* * * + +##### background-image `uri` + + + +Default Value: +_(No background image will be used.)_ + +An image that is repeated below all features on a map as a background. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### background-image-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(The background-image will be blended with the background normally (placed on top of any existing background-color).)_ + +Set the compositing operation used to blend the image into the background. +* * * + +##### background-image-opacity `float` + + + +Default Value: 1 +_(The image opacity will not be changed when applied to the map background.)_ + +Set the opacity of the image. +* * * + +##### srs `string` + + + +Default Value: +proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs +_(The proj4 literal of EPSG:4326 is assumed to be the Map's spatial reference and all data from layers within this map will be plotted using this coordinate system. If any layers do not declare an srs value then they will be assumed to be in the same srs as the Map and not transformations will be needed to plot them in the Map's coordinate space.)_ + +Map spatial reference (proj4 string). +* * * + +##### buffer-size `float` + + + +Default Value: 0 +_(No buffer will be used.)_ + +Extra tolerance around the map (in pixels) used to ensure labels crossing tile boundaries are equally rendered in each tile (e.g. cut in each tile). Not intended to be used in combination with "avoid-edges". +* * * + +##### maximum-extent `string` + + + +Default Value: -20037508.34,-20037508.34,20037508.34,20037508.34 +_(All data will be clipped to global mercator extent (default is applied in Carto.js).)_ + +An extent to be used to limit the bounds used to query all layers during rendering. Should be minx, miny, maxx, maxy in the coordinates of the Map. +* * * + +##### base `string` + + + +Default Value: +_(This base path defaults to an empty string meaning that any relative paths to files referenced in styles or layers will be interpreted relative to the application process.)_ + +Any relative paths used to reference files will be understood as relative to this directory path if the map is loaded from an in memory object rather than from the filesystem. If the map is loaded from the filesystem and this option is not provided it will be set to the directory of the stylesheet. +* * * + +##### font-directory `uri` + + + +Default Value: none +_(No map-specific fonts will be registered.)_ + +Path to a directory which holds fonts which should be registered when the Map is loaded (in addition to any fonts that may be automatically registered). +* * * + + +## polygon + +##### polygon-fill `color` + + + +Default Value: The color gray will be used for fill. +_(Gray and fully opaque (alpha = 1), same as rgb(128,128,128) or rgba(128,128,128,1).)_ + +Fill color to assign to a polygon. +* * * + +##### polygon-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the polygon. +* * * + +##### polygon-gamma `float` + + + +Default Value: 1 +_(Fully antialiased.)_ +Range: 0-1 +Level of antialiasing of polygon edges. +* * * + +##### polygon-gamma-method `keyword` +`power``linear``none``threshold``multiply` + + +Default Value: power +_(pow(x,gamma) is used to calculate pixel gamma, which produces slightly smoother line and polygon antialiasing than the 'linear' method, while other methods are usually only used to disable AA.)_ + +An Antigrain Geometry specific rendering hint to control the quality of antialiasing. Under the hood in Mapnik this method is used in combination with the 'gamma' value (which defaults to 1). The methods are in the AGG source at https://github.com/mapnik/mapnik/blob/master/deps/agg/include/agg_gamma_functions. +* * * + +##### polygon-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extend outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### polygon-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify geometries by the given tolerance. +* * * + +##### polygon-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify geometries by the given algorithm. +* * * + +##### polygon-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### polygon-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform polygon geometry with specified function. +* * * + +##### polygon-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## line + +##### line-color `color` + + + +Default Value: black +_(black and fully opaque (alpha = 1), same as rgb(0,0,0) or rgba(0,0,0,1).)_ + +The color of a drawn line. +* * * + +##### line-width `float` + + + +Default Value: 1 +_(The line will be rendered 1 pixel wide.)_ + +The width of a line in pixels. +* * * + +##### line-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of a line. +* * * + +##### line-join `keyword` +`miter``miter-revert``round``bevel` + + +Default Value: miter +_(The line joins will be rendered using a miter look.)_ + +The behavior of lines when joining. +* * * + +##### line-cap `keyword` +`butt``round``square` + + +Default Value: butt +_(The line endings will be rendered using a butt look.)_ + +The display of line endings. +* * * + +##### line-gamma `float` + + + +Default Value: 1 +_(Fully antialiased.)_ +Range: 0-1 +Level of antialiasing of stroke line. +* * * + +##### line-gamma-method `keyword` +`power``linear``none``threshold``multiply` + + +Default Value: power +_(pow(x,gamma) is used to calculate pixel gamma, which produces slightly smoother line and polygon antialiasing than the 'linear' method, while other methods are usually only used to disable AA.)_ + +An Antigrain Geometry specific rendering hint to control the quality of antialiasing. Under the hood in Mapnik this method is used in combination with the 'gamma' value (which defaults to 1). The methods are in the AGG source at https://github.com/mapnik/mapnik/blob/master/deps/agg/include/agg_gamma_functions. +* * * + +##### line-dasharray `numbers` + + + +Default Value: none +_(The line will be drawn without dashes.)_ + +A pair of length values [a,b], where (a) is the dash length and (b) is the gap length respectively. More than two values are supported for more complex patterns. +* * * + +##### line-dash-offset `numbers` + + + +Default Value: none +_(The line will be drawn without dashes.)_ + +Valid parameter but not currently used in renderers (only exists for experimental svg support in Mapnik which is not yet enabled). +* * * + +##### line-miterlimit `float` + + + +Default Value: 4 +_(Will auto-convert miters to bevel line joins when theta is less than 29 degrees as per the SVG spec: 'miterLength / stroke-width = 1 / sin ( theta / 2 )'.)_ + +The limit on the ratio of the miter length to the stroke-width. Used to automatically convert miter joins to bevel joins for sharp angles to avoid the miter extending beyond the thickness of the stroking path. Normally will not need to be set, but a larger value can sometimes help avoid jaggy artifacts. +* * * + +##### line-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### line-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify geometries by the given tolerance. +* * * + +##### line-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify geometries by the given algorithm. +* * * + +##### line-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### line-offset `float` + + + +Default Value: 0 +_(Will not be offset.)_ + +Offsets a line a number of pixels parallel to its actual path. Positive values move the line left, negative values move it right (relative to the directionality of the line). +* * * + +##### line-rasterizer `keyword` +`full``fast` + + +Default Value: full +_(The line will be rendered using the highest quality method rather than the fastest.)_ + +Exposes an alternate AGG rendering method that sacrifices some accuracy for speed. +* * * + +##### line-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform line geometry with specified function. +* * * + +##### line-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## markers + +##### marker-file `uri` + + + +Default Value: none +_(An ellipse or circle, if width equals height.)_ + +A file that this marker shows at each placement. If no file is given, the marker will show an ellipse. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### marker-opacity `float` + + + +Default Value: 1 +_(The stroke-opacity and fill-opacity of the marker.)_ + +The overall opacity of the marker, if set, overrides both the opacity of both the fill and stroke. +* * * + +##### marker-fill-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The fill opacity of the marker. +* * * + +##### marker-line-color `color` + + + +Default Value: black +_(The marker will be drawn with a black outline.)_ + +The color of the stroke around the marker. +* * * + +##### marker-line-width `float` + + + +Default Value: 0.5 +_(The marker will be drawn with an outline of .5 pixels wide.)_ + +The width of the stroke around the marker, in pixels. This is positioned on the boundary, so high values can cover the area itself. +* * * + +##### marker-line-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of a line. +* * * + +##### marker-placement `keyword` +`point``line``interior``vertex-first``vertex-last` + + +Default Value: point +_(Place markers at the center point (centroid) of the geometry.)_ + +Attempt to place markers on a point, in the center of a polygon, or if markers-placement:line, then multiple times along a line. 'interior' placement can be used to ensure that points placed on polygons are forced to be inside the polygon interior. The 'vertex-first' and 'vertex-last' options can be used to place markers at the first or last vertex of lines or polygons. +* * * + +##### marker-multi-policy `keyword` +`each``whole``largest` + + +Default Value: each +_(If a feature contains multiple geometries and the placement type is either point or interior then a marker will be rendered for each.)_ + +A special setting to allow the user to control rendering behavior for 'multi-geometries' (when a feature contains multiple geometries). This setting does not apply to markers placed along lines. The 'each' policy is default and means all geometries will get a marker. The 'whole' policy means that the aggregate centroid between all geometries will be used. The 'largest' policy means that only the largest (by bounding box areas) feature will get a rendered marker (this is how text labeling behaves by default). +* * * + +##### marker-type `keyword` +`arrow``ellipse` + + +Default Value: ellipse +_(The marker shape is an ellipse.)_ + +The default marker-type. If a SVG file is not given as the marker-file parameter, the renderer provides either an arrow or an ellipse (a circle if height is equal to width). +* * * + +##### marker-width `float` + + + +Default Value: 10 +_(The marker width is 10 pixels.)_ + +The width of the marker, if using one of the default types. +* * * + +##### marker-height `float` + + + +Default Value: 10 +_(The marker height is 10 pixels.)_ + +The height of the marker, if using one of the default types. +* * * + +##### marker-fill `color` + + + +Default Value: blue +_(The marker fill color is blue.)_ + +The color of the area of the marker. +* * * + +##### marker-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow markers to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping markers are shown or hidden. +* * * + +##### marker-avoid-edges `boolean` + + + +Default Value: false +_(Markers will be potentially placed near tile edges and therefore may look cut off unless they are rendered on each adjacent tile.)_ + +Avoid placing markers that intersect with tile boundaries. +* * * + +##### marker-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache.)_ + +Value to control whether the placement of the feature will prevent the placement of other features. +* * * + +##### marker-spacing `float` + + + +Default Value: 100 +_(In the case of marker-placement:line then draw a marker every 100 pixels along a line.)_ + +Space between repeated markers in pixels. If the spacing is less than the marker size or larger than the line segment length then no marker will be placed. Any value less than 1 will be ignored and the default will be used instead. +* * * + +##### marker-max-error `float` + + + +Default Value: 0.2 +_(N/A: not intended to be changed.)_ + +N/A: not intended to be changed. +* * * + +##### marker-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation.)_ + +Transform marker instance with specified function. Ignores map scale factor. +* * * + +##### marker-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### marker-simplify `float` + + + +Default Value: 0 +_(Geometry will not be simplified.)_ + +geometries are simplified by the given tolerance. +* * * + +##### marker-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +geometries are simplified by the given algorithm. +* * * + +##### marker-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### marker-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform marker geometry with specified function. +* * * + +##### marker-offset `float` + + + +Default Value: 0 +_(Will not be offset.)_ + +Offsets a marker from a line a number of pixels parallel to its actual path. Positive values move the marker left, negative values move it right (relative to the directionality of the line). +* * * + +##### marker-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### marker-direction `keyword` +`auto``auto-down``left``right``left-only``right-only``up``down` + + +Default Value: right +_(Markers are oriented to the right in the line direction.)_ + +How markers should be placed along lines. With the "auto" setting when marker is upside down the marker is automatically rotated by 180 degrees to keep it upright. The "auto-down" value places marker in the opposite orientation to "auto". The "left" or "right" settings can be used to force marker to always be placed along a line in a given direction and therefore disables rotating if marker appears upside down. The "left-only" or "right-only" properties also force a given direction but will discard upside down markers rather than trying to flip it. The "up" and "down" settings don't adjust marker's orientation to the line direction. +* * * + + +## shield + +##### shield-name `string` + + + +Default Value: +_(No text label will be rendered with the shield.)_ + +Value to use for a shield"s text label. Data columns are specified using brackets like [column_name]. +* * * + +##### shield-file `uri` + + + +Default Value: none + + +Image file to render behind the shield text. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### shield-face-name `string` + + + +Default Value: none + + +Font name and style to use for the shield text. +* * * + +##### shield-unlock-image `boolean` + + + +Default Value: false +_(text alignment relative to the shield image uses the center of the image as the anchor for text positioning.)_ + +This parameter should be set to true if you are trying to position text beside rather than on top of the shield image. +* * * + +##### shield-size `float` + + + +Default Value: 10 +_(Font size of 10 will be used to render text.)_ + +The size of the shield text in pixels. +* * * + +##### shield-fill `color` + + + +Default Value: black +_(The shield text will be rendered black.)_ + +The color of the shield text. +* * * + +##### shield-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point +_(One shield will be placed per geometry.)_ + +How this shield should be placed. Point placement places one shield on top of a point geometry and at the centroid of a polygon or the middle point of a line, line places along lines multiple times per feature, vertex places on the vertexes of polygons, and interior attempts to place inside of a polygon. +* * * + +##### shield-avoid-edges `boolean` + + + +Default Value: false +_(Shields will be potentially placed near tile edges and therefore may look cut off unless they are rendered on each adjacent tile.)_ + +Avoid placing shields that intersect with tile boundaries. +* * * + +##### shield-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow shields to overlap with other map elements already placed.)_ + +Control whether overlapping shields are shown or hidden. +* * * + +##### shield-margin `float` + + + +Default Value: 0 +_(No extra margin will be used to determine if a shield collides with any other text, shield, or marker.)_ + +Minimum distance that a shield can be placed from any other text, shield, or marker. +* * * + +##### shield-repeat-distance `float` + + + +Default Value: 0 +_(Shields with the same text will be rendered without restriction.)_ + +Minimum distance between repeated shields. If set this will prevent shields being rendered nearby each other that contain the same text. Similiar to shield-min-distance with the difference that it works the same no matter what placement strategy is used. +* * * + +##### shield-min-distance `float` + + + +Default Value: 0 +_(Shields with the same text will be rendered without restriction.)_ + +Minimum distance to the next shield with the same text. Only works for line placement. +* * * + +##### shield-spacing `float` + + + +Default Value: 0 +_(Only one shield per line will attempt to be placed.)_ + +Distance the renderer should use to try to place repeated shields on a line. +* * * + +##### shield-min-padding `float` + + + +Default Value: 0 +_(No margin will be used to detect if a shield is nearby a tile boundary.)_ + +Minimum distance a shield will be placed from the edge of a tile. This option is similiar to shield-avoid-edges:true except that the extra margin is used to discard cases where the shield+margin are not fully inside the tile. +* * * + +##### shield-label-position-tolerance `float` + + + +Default Value: shield-spacing/2.0 +_(If a shield cannot be placed then the renderer will advance by shield-spacing/2.0 to try placement again.)_ + +Allows the shield to be displaced from its ideal position by a number of pixels (only works with placement:line). +* * * + +##### shield-wrap-width `unsigned` + + + +Default Value: 0 +_(Text will not be wrapped.)_ + +Length of a chunk of text in pixels before wrapping text. If set to zero, text doesn't wrap. +* * * + +##### shield-wrap-before `boolean` + + + +Default Value: false +_(Wrapped lines will be a bit longer than wrap-width.)_ + +Wrap text before wrap-width is reached. +* * * + +##### shield-wrap-character `string` + + + +Default Value: " " +_(Lines will be wrapped when whitespace is encountered.)_ + +Use this character instead of a space to wrap long names. +* * * + +##### shield-halo-fill `color` + + + +Default Value: white +_(The shield halo text will be rendered white.)_ + +Specifies the color of the halo around the text. +* * * + +##### shield-halo-radius `float` + + + +Default Value: 0 +_(no halo.)_ + +Specify the radius of the halo in pixels. +* * * + +##### shield-halo-rasterizer `keyword` +`full``fast` + + +Default Value: full +_(The shield will be rendered using the highest quality method rather than the fastest.)_ + +Exposes an alternate text halo rendering method that sacrifices quality for speed. +* * * + +##### shield-halo-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: +_(No transformation.)_ + +Transform shield halo relative to the actual text with specified function. Allows for shadow or embossed effects. Ignores map scale factor. +* * * + +##### shield-halo-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### shield-halo-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A number from 0 to 1 specifying the opacity for the text halo. +* * * + +##### shield-character-spacing `unsigned` + + + +Default Value: 0 +_(The default character spacing of the font will be used.)_ + +Horizontal spacing between characters (in pixels). Currently works for point placement only, not line placement. +* * * + +##### shield-line-spacing `unsigned` + + + +Default Value: 0 +_(The default font spacing will be used.)_ + +Vertical spacing between lines of multiline labels (in pixels). +* * * + +##### shield-text-dx `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text within shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the shield right. +* * * + +##### shield-text-dy `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text within shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the shield down. +* * * + +##### shield-dx `float` + + + +Default Value: 0 +_(Shield will not be displaced.)_ + +Displace shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right. +* * * + +##### shield-dy `float` + + + +Default Value: 0 +_(Shield will not be displaced.)_ + +Displace shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text down. +* * * + +##### shield-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the image used for the shield. +* * * + +##### shield-text-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the text placed on top of the shield. +* * * + +##### shield-horizontal-alignment `keyword` +`left``middle``right``auto` + + +Default Value: auto +_(TODO.)_ + +The shield's horizontal alignment from its centerpoint. +* * * + +##### shield-vertical-alignment `keyword` +`top``middle``bottom``auto` + + +Default Value: middle +_(TODO.)_ + +The shield's vertical alignment from its centerpoint. +* * * + +##### shield-placement-type `keyword` +`dummy``simple``list` + + +Default Value: dummy +_(Alternative placements will not be enabled.)_ + +Re-position and/or re-size shield to avoid overlaps. "simple" for basic algorithm (using shield-placements string,) "dummy" to turn this feature off. +* * * + +##### shield-placements `string` + + + +Default Value: +_(No alternative placements will be used.)_ + +If "placement-type" is set to "simple", use this "POSITIONS,[SIZES]" string. An example is `shield-placements: "E,NE,SE,W,NW,SW";`. +* * * + +##### shield-text-transform `keyword` +`none``uppercase``lowercase``capitalize``reverse` + + +Default Value: none +_(No text transformation will be applied.)_ + +Transform the case of the characters. +* * * + +##### shield-justify-alignment `keyword` +`left``center``right``auto` + + +Default Value: auto +_(TODO.)_ + +Define how text in a shield's label is justified. +* * * + +##### shield-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation.)_ + +Transform shield instance with specified function. Ignores map scale factor. +* * * + +##### shield-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### shield-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify the geometries used for shield placement by the given tolerance. +* * * + +##### shield-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify the geometries used for shield placement by the given algorithm. +* * * + +##### shield-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out the angles of the geometry used for shield placement. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### shield-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## line-pattern + +##### line-pattern-file `uri` + + + +Default Value: none + + +An image file to be repeated and warped along a line. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### line-pattern-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### line-pattern-opacity `float` + + + +Default Value: 1 +_(The image is rendered without modifications.)_ + +Apply an opacity level to the image used for the pattern. +* * * + +##### line-pattern-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +geometries are simplified by the given tolerance. +* * * + +##### line-pattern-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +geometries are simplified by the given algorithm. +* * * + +##### line-pattern-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### line-pattern-offset `float` + + + +Default Value: 0 +_(The line will not be offset.)_ + +Offsets a line a number of pixels parallel to its actual path. Positive values move the line left, negative values move it right (relative to the directionality of the line). +* * * + +##### line-pattern-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform line geometry with specified function and apply pattern to transformed geometry. +* * * + +##### line-pattern-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## polygon-pattern + +##### polygon-pattern-file `uri` + + + +Default Value: none + + +Image to use as a repeated pattern fill within a polygon. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### polygon-pattern-alignment `keyword` +`global``local` + + +Default Value: global +_(Patterns will be aligned to the map (or tile boundaries) when being repeated across polygons. This is ideal for seamless patterns in tiled rendering.)_ + +Specify whether to align pattern fills to the layer's geometry (local) or to the map (global). +* * * + +##### polygon-pattern-gamma `float` + + + +Default Value: 1 +_(Fully antialiased.)_ +Range: 0-1 +Level of antialiasing of polygon pattern edges. +* * * + +##### polygon-pattern-opacity `float` + + + +Default Value: 1 +_(The image is rendered without modifications.)_ + +Apply an opacity level to the image used for the pattern. +* * * + +##### polygon-pattern-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### polygon-pattern-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +geometries are simplified by the given tolerance. +* * * + +##### polygon-pattern-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +geometries are simplified by the given algorithm. +* * * + +##### polygon-pattern-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### polygon-pattern-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform polygon geometry with specified function and apply pattern to transformed geometry. +* * * + +##### polygon-pattern-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## raster + +##### raster-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the raster symbolizer on top of other symbolizers. +* * * + +##### raster-filter-factor `float` + + + +Default Value: -1 +_(Allow the datasource to choose appropriate downscaling.)_ + +This is used by the Raster or Gdal datasources to pre-downscale images using overviews. Higher numbers can sometimes cause much better scaled image output, at the cost of speed. +* * * + +##### raster-scaling `keyword` +`near``fast``bilinear``bicubic``spline16``spline36``hanning``hamming``hermite``kaiser``quadric``catrom``gaussian``bessel``mitchell``sinc``lanczos``blackman` + + +Default Value: near +_(Nearest neighboor resampling will be used to scale the image to the target size of the map.)_ + +The scaling algorithm used to making different resolution versions of this raster layer. Bilinear is a good compromise between speed and accuracy, while lanczos gives the highest quality. +* * * + +##### raster-mesh-size `unsigned` + + + +Default Value: 16 +_(Reprojection mesh will be 1/16 of the resolution of the source image.)_ + +A reduced resolution mesh is used for raster reprojection, and the total image size is divided by the mesh-size to determine the quality of that mesh. Values for mesh-size larger than the default will result in faster reprojection but might lead to distortion. +* * * + +##### raster-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### raster-colorizer-default-mode `keyword` +`discrete``linear``exact` + + +Default Value: linear +_(A linear interpolation is used to generate colors between the two nearest stops.)_ + +This can be either `discrete`, `linear` or `exact`. If it is not specified then the default is `linear`. +* * * + +##### raster-colorizer-default-color `color` + + + +Default Value: transparent +_(Pixels that are not colored by the colorizer stops will be transparent.)_ + +This can be any color. Sets the color that is applied to all values outside of the range of the colorizer-stops. If not supplied pixels will be fully transparent. +* * * + +##### raster-colorizer-epsilon `float` + + + +Default Value: 1.1920928955078125e-07 +_(Pixels must very closely match the stop filter otherwise they will not be colored.)_ + +This can be any positive floating point value and will be used as a tolerance in floating point comparisions. The higher the value the more likely a stop will match and color data. +* * * + +##### raster-colorizer-stops `tags` + + + +Default Value: +_(No colorization will happen without supplying stops.)_ + +Assigns raster data values to colors. Stops must be listed in ascending order, and contain at a minimum the value and the associated color. You can also include the color-mode as a third argument, like `stop(100,#fff,exact)`. +* * * + + +## point + +##### point-file `uri` + + + +Default Value: none +_(A 4x4 black square will be rendered.)_ + +Image file to represent a point. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### point-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow points to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping points are shown or hidden. +* * * + +##### point-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache.)_ + +Control whether the placement of the feature will prevent the placement of other features. +* * * + +##### point-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A value from 0 to 1 to control the opacity of the point. +* * * + +##### point-placement `keyword` +`centroid``interior` + + +Default Value: centroid +_(The centroid of the geometry will be used to place the point.)_ + +Control how this point should be placed. Centroid calculates the geometric center of a polygon, which can be outside of it, while interior always places inside of a polygon. +* * * + +##### point-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation.)_ + +Transform point instance with specified function. Ignores map scale factor. +* * * + +##### point-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## text + +##### text-name `string` + + + +Default Value: none + + +Value to use for a text label. Data columns are specified using brackets like [column_name]. +* * * + +##### text-face-name `string` + + + +Default Value: none + + +Font name and style to render a label in. +* * * + +##### text-size `float` + + + +Default Value: 10 +_(Font size of 10 will be used to render text.)_ + +Text size in pixels. +* * * + +##### text-ratio `unsigned` + + + +Default Value: 0 +_(TODO.)_ + +Define the amount of text (of the total) present on successive lines when wrapping occurs. +* * * + +##### text-wrap-width `unsigned` + + + +Default Value: 0 +_(Text will not be wrapped.)_ + +Length of a chunk of text in pixels before wrapping text. If set to zero, text doesn't wrap. +* * * + +##### text-wrap-before `boolean` + + + +Default Value: false +_(Wrapped lines will be a bit longer than wrap-width.)_ + +Wrap text before wrap-width is reached. +* * * + +##### text-wrap-character `string` + + + +Default Value: " " +_(Lines will be wrapped when whitespace is encountered.)_ + +Use this character instead of a space to wrap long text. +* * * + +##### text-repeat-wrap-character `boolean` + + + +Default Value: false +_(Character will be removed when used to wrap a line.)_ + +Keep the character used to wrap a line instead of removing it, and repeat it on the new line. +* * * + +##### text-spacing `unsigned` + + + +Default Value: 0 +_(Only one label per line will attempt to be placed.)_ + +Distance the renderer should use to try to place repeated text labels on a line. +* * * + +##### text-character-spacing `float` + + + +Default Value: 0 +_(The default character spacing of the font will be used.)_ + +Horizontal spacing adjustment between characters in pixels. This value is ignored when `horizontal-alignment` is set to `adjust`. Typographic ligatures are turned off when this value is greater than zero. +* * * + +##### text-line-spacing `unsigned` + + + +Default Value: 0 +_(The default font spacing will be used.)_ + +Vertical spacing adjustment between lines in pixels. +* * * + +##### text-label-position-tolerance `float` + + + +Default Value: text-spacing/2.0 +_(If a shield cannot be placed then the renderer will advance by text-spacing/2.0 to try placement again.)_ + +Allows the label to be displaced from its ideal position by a number of pixels (only works with placement:line). +* * * + +##### text-max-char-angle-delta `float` + + + +Default Value: 22.5 +_(The label will not be placed if a character falls on a line with an angle sharper than 22.5 degrees.)_ + +The maximum angle change, in degrees, allowed between adjacent characters in a label. This value internally is converted to radians to the default is 22.5*math.pi/180.0. The higher the value the fewer labels will be placed around around sharp corners. +* * * + +##### text-fill `color` + + + +Default Value: black +_(The text will be rendered black.)_ + +Specifies the color for the text. +* * * + +##### text-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A number from 0 to 1 specifying the opacity for the text. +* * * + +##### text-halo-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A number from 0 to 1 specifying the opacity for the text halo. +* * * + +##### text-halo-fill `color` + + + +Default Value: white +_(The halo will be rendered white.)_ + +Specifies the color of the halo around the text. +* * * + +##### text-halo-radius `float` + + + +Default Value: 0 +_(no halo.)_ + +Specify the radius of the halo in pixels. +* * * + +##### text-halo-rasterizer `keyword` +`full``fast` + + +Default Value: full +_(The text will be rendered using the highest quality method rather than the fastest.)_ + +Exposes an alternate text halo rendering method that sacrifices quality for speed. +* * * + +##### text-halo-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: +_(No transformation.)_ + +Transform text halo relative to the actual text with specified function. Allows for shadow or embossed effects. Ignores map scale factor. +* * * + +##### text-dx `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text by fixed amount, in pixels, +/- along the X axis. With "dummy" placement-type, a positive value displaces to the right. With "simple" placement-type, it is either left, right or unchanged, depending on the placement selected. Any non-zero value implies "horizontal-alignment" changes to "left" by default. Has no effect with 'line' text-placement-type. +* * * + +##### text-dy `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text by fixed amount, in pixels, +/- along the Y axis. With "dummy" placement-type, a positive value displaces downwards. With "simple" placement-type, it is either up, down or unchanged, depending on the placement selected. With "line" placement-type, a positive value displaces above the path. +* * * + +##### text-vertical-alignment `keyword` +`top``middle``bottom``auto` + + +Default Value: auto +_(Default affected by value of dy; "top" for dy>0, "bottom" for dy<0.)_ + +Position of label relative to point position. +* * * + +##### text-avoid-edges `boolean` + + + +Default Value: false +_(Text will be potentially placed near tile edges and therefore may look cut off unless the same text label is rendered on each adjacent tile.)_ + +Avoid placing labels that intersect with tile boundaries. +* * * + +##### text-margin `float` + + + +Default Value: 0 +_(No extra margin will be used to determine if a label collides with any other text, shield, or marker.)_ + +Minimum distance that a label can be placed from any other text, shield, or marker. +* * * + +##### text-repeat-distance `float` + + + +Default Value: 0 +_(Labels with the same text will be rendered without restriction.)_ + +Minimum distance between repeated text. If set this will prevent text labels being rendered nearby each other that contain the same text. Similiar to text-min-distance with the difference that it works the same no matter what placement strategy is used. +* * * + +##### text-min-distance `float` + + + +Default Value: 0 +_(Labels with the same text will be rendered without restriction.)_ + +Minimum distance to the next label with the same text. Only works for line placement. Deprecated: replaced by `text-repeat-distance` and `text-margin` +* * * + +##### text-min-padding `float` + + + +Default Value: 0 +_(No margin will be used to detect if a text label is nearby a tile boundary.)_ + +Minimum distance a text label will be placed from the edge of a tile. This option is similiar to shield-avoid-edges:true except that the extra margin is used to discard cases where the shield+margin are not fully inside the tile. +* * * + +##### text-min-path-length `float` + + + +Default Value: 0 +_(place labels on all geometries no matter how small they are.)_ + +Place labels only on polygons and lines with a bounding width longer than this value (in pixels). +* * * + +##### text-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow text to overlap with other text - overlapping markers will not be shown.)_ + +Control whether overlapping text is shown or hidden. +* * * + +##### text-orientation `float` + + + +Default Value: 0 +_(Text is not rotated and is displayed upright.)_ + +Rotate the text. (only works with text-placement:point). +* * * + +##### text-rotate-displacement `boolean` + + + +Default Value: false +_(Label center is used for rotation.)_ + +Rotates the displacement around the placement origin by the angle given by "orientation". +* * * + +##### text-upright `keyword` +`auto``auto-down``left``right``left-only``right-only` + + +Default Value: auto +_(Text will be positioned upright automatically.)_ + +How this label should be placed along lines. By default when more than half of a label's characters are upside down the label is automatically flipped to keep it upright. By changing this parameter you can prevent this "auto-upright" behavior. The "auto-down" value places text in the opposite orientation to "auto". The "left" or "right" settings can be used to force text to always be placed along a line in a given direction and therefore disables flipping if text appears upside down. The "left-only" or "right-only" properties also force a given direction but will discard upside down text rather than trying to flip it. +* * * + +##### text-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point +_(One shield will be placed per geometry.)_ + +How this label should be placed. Point placement places one label on top of a point geometry and at the centroid of a polygon or the middle point of a line, line places along lines multiple times per feature, vertex places on the vertexes of polygons, and interior attempts to place inside of a polygon. +* * * + +##### text-placement-type `keyword` +`dummy``simple``list` + + +Default Value: dummy +_(Alternative placements will not be enabled.)_ + +Re-position and/or re-size text to avoid overlaps. "simple" for basic algorithm (using text-placements string,) "dummy" to turn this feature off. +* * * + +##### text-placements `string` + + + +Default Value: +_(No alternative placements will be used.)_ + +If "placement-type" is set to "simple", use this "POSITIONS,[SIZES]" string. An example is `text-placements: "E,NE,SE,W,NW,SW";`. +* * * + +##### text-transform `keyword` +`none``uppercase``lowercase``capitalize``reverse` + + +Default Value: none +_(Transform text instance with specified function. Ignores map scale factor.)_ + +Transform the case of the characters. +* * * + +##### text-horizontal-alignment `keyword` +`left``middle``right``auto``adjust` + + +Default Value: auto +_(TODO.)_ + +The text's horizontal alignment from it's centerpoint. If `placement` is set to `line`, then `adjust` can be set to auto-fit the text to the length of the path by dynamically calculating `character-spacing`. +* * * + +##### text-align `keyword` +`left``right``center``auto` + + +Default Value: auto +_(Auto alignment means that text will be centered by default except when using the `placement-type` parameter - in that case either right or left justification will be used automatically depending on where the text could be fit given the `text-placements` directives.)_ + +Define how text is justified. +* * * + +##### text-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### text-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify the geometries used for text placement by the given tolerance. +* * * + +##### text-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify the geometries used for text placement by the given algorithm. +* * * + +##### text-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out the angles of the geometry used for text placement. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### text-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### text-halo-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### text-font-feature-settings `string` + + + +Default Value: +_(Default set of typographic features recommended by OpenType specification. Ligatures are turned off by default when `character-spacing` is greater than zero.)_ + +Comma separated list of OpenType typographic features. The syntax and semantics conforms to `font-feature-settings` from W3C CSS. +* * * + +##### text-largest-bbox-only `boolean` + + + +Default Value: true +_(For multipolygons only polygon with largest bbox area is labeled (does not apply to other geometries).)_ + +Controls default labeling behavior on multipolygons. The default is true and means that only the polygon with largest bbox is labeled. +* * * + + +## building + +##### building-fill `color` + + + +Default Value: The color gray will be used for fill. +_(Gray and fully opaque (alpha = 1), same as rgb(128,128,128) or rgba(128,128,128,1).)_ + +The color of the buildings fill. Note: 0.8 will be used to multiply each color component to auto-generate a darkened wall color. +* * * + +##### building-fill-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the building as a whole, including all walls. +* * * + +##### building-height `float` + + + +Default Value: 0 +_(Buildings will not have a visual height and will instead look like flat polygons.)_ + +The height of the building in pixels. +* * * + + +## debug + +##### debug-mode `string` + + + +Default Value: collision +_(The otherwise invisible collision boxes will be rendered as squares on the map.)_ + +The mode for debug rendering. +* * * + + +## dot + +##### dot-fill `color` + + + +Default Value: gray +_(The dot fill color is gray.)_ + +The color of the area of the dot. +* * * + +##### dot-opacity `float` + + + +Default Value: 1 +_(The opacity of the dot.)_ + +The overall opacity of the dot. +* * * + +##### dot-width `float` + + + +Default Value: 1 +_(The marker width is 1 pixel.)_ + +The width of the dot in pixels. +* * * + +##### dot-height `float` + + + +Default Value: 1 +_(The marker height is 1 pixels.)_ + +The height of the dot in pixels. +* * * + +##### dot-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current layer on top of other layers.)_ + +Composite operation. This defines how this layer should behave relative to layers atop or below it. +* * * + + + + +### Values + +Below is a list of values and an explanation of any expression that can be applied to properties in CartCSS. + +### Color + +CartoCSS accepts a variety of syntaxes for colors - HTML-style hex values, rgb, rgba, hsl, hsla, husl, and husla. It also supports the predefined HTML colors names, like `yellow` and `blue`. + +``` css +#line { +line-color: #ff0; +line-color: #ffff00; +line-color: rgb(255, 255, 0); +line-color: rgba(255, 255, 0, 1); +line-color: hsl(100, 50%, 50%); +line-color: hsla(100, 50%, 50%, 1); +line-color: husl(100, 50%, 50%); // same values yield different color than HSL +line-color: husla(100, 50%, 50%, 1); +line-color: yellow; +} +``` + +Especially of note is the support for hsl and husl, which can be [easier to reason about than rgb()](http://mothereffinghsl.com/). Carto also includes several color operation functions [borrowed from less](http://lesscss.org/functions/#color-operations): + +``` css +// lighten and darken colors +lighten(#ace, 10%); +darken(#ace, 10%); + +// saturate and desaturate +saturate(#550000, 10%); +desaturate(#00ff00, 10%); + +// increase or decrease the opacity of a color +fadein(#fafafa, 10%); +fadeout(#fefefe, 14%); + +// spin rotates a color around the color wheel by degrees +spin(#ff00ff, 10); + +// mix generates a color in between two other colors. +mix(#fff, #000, 50%); + +// get color components +hue(#ff00ff); +saturation(#ff00ff); +lightness(#ff00ff); +alpha(hsla(100, 50%, 50%, 0.5)); +``` + +These functions all take arguments which can be color variables, literal colors, or the results of other functions operating on colors. All the above mentioned functions also come in +a `functionp`-variant (e.g. `lightenp`), which force a given color into perceptual color space. + +### Float + +Float is a fancy way of saying 'number'. In CartoCSS, you specify _just a number_ - unlike CSS, there are no units, but everything is specified in pixels. + +``` css +#line { +line-width: 2; +} +``` + +It's also possible to do simple math with number values: + +``` css +#line { +line-width: 4 / 2; // division +line-width: 4 + 2; // addition +line-width: 4 - 2; // subtraction +line-width: 4 * 2; // multiplication +line-width: 4 % 2; // modulus +} +``` + +### URI + +URI is a fancy way of saying URL. When an argument is a URI, you use the same kind of `url('place.png')` notation that you would with HTML. Quotes around the URL aren't required, but are highly recommended. URIs can be paths to places on your computer, or on the internet. + +```css +#markers { +marker-file: url('marker.png'); +} +``` + +### String + +A string is basically just text. In the case of CartoCSS, you're going to put it in quotes. Strings can be anything, though pay attention to the cases of `text-name` and `shield-name` - they actually will refer to features, which you refer to by putting them in brackets, as seen in the example below. + +```css +#labels { +text-name: "[MY_FIELD]"; +} +``` + +### Boolean + +Boolean means yes or no, so it accepts the values `true` or `false`. + +```css +#markers { +marker-allow-overlap:true; +} +``` + +### Expressions + +Expressions are statements that can include fields, numbers, and other types in a really flexible way. You have run into expressions before, in the realm of 'fields', where you'd specify `"[FIELD]"`, but expressions allow you to drop the quotes and also do quick addition, division, multiplication, and concatenation from within Carto syntax. + +```css +#buildings { +building-height: [HEIGHT_FIELD] * 10; +} +``` + +### Numbers +Numbers are comma-separated lists of one or more number in a specific order. They're used in line dash arrays, in which the numbers specify intervals of line, break, and line again. + +```css +#disputedboundary { +line-dasharray: 1, 4, 2; +} +``` + +### Percentages +In Carto, the percentage symbol, `%` universally means `value/100`. It's meant to be used with ratio-related properties, like opacity rules. + +_You should not use percentages as widths, heights, or other properties - unlike CSS, percentages are not relative to cascaded classes or page size, they're, as stated, simply the value divided by one hundred._ + +```css +#world { +// this syntax +polygon-opacity: 50%; + +// is equivalent to +polygon-opacity: 0.5; +} +``` + +### Functions + +Functions are comma-separated lists of one or more functions. For instance, transforms use the `functions` type to allow for transforms within Carto, which are optionally chainable. + +```css +#point { +point-transform: scale(2, 2); +} +``` diff --git a/docs/3.0.7.md b/docs/3.0.7.md new file mode 100644 index 0000000..ad7ed30 --- /dev/null +++ b/docs/3.0.7.md @@ -0,0 +1,2226 @@ +# Carto documentation + +The following is a list of properties provided in CartoCSS that you can apply to map elements. + +## All elements + +##### image-filters `functions` + +`agg-stack-blur``emboss``blur``gray``sobel``edge-detect``x-gradient``y-gradient``invert``sharpen``color-blind-protanope``color-blind-deuteranope``color-blind-tritanope``colorize-alpha``color-to-alpha``scale-hsla` + +Default Value: none +_(no filters.)_ + +A list of image filters that will be applied to the active rendering canvas for a given style. The presence of one more `image-filters` will trigger a new canvas to be created before starting to render a style and then this canvas will be composited back into the main canvas after rendering all features and after all `image-filters` have been applied. See `direct-image-filters` if you want to apply a filter directly to the main canvas. +* * * + +##### image-filters-inflate `boolean` + + + +Default Value: false +_(No special handling will be done and image filters that blur data will only blur up to the edge of a tile boundary.)_ + +A property that can be set to true to enable using an inflated image internally for seamless blurring across tiles (requires buffered data). +* * * + +##### direct-image-filters `functions` + +`agg-stack-blur``emboss``blur``gray``sobel``edge-detect``x-gradient``y-gradient``invert``sharpen``color-blind-protanope``color-blind-deuteranope``color-blind-tritanope``colorize-alpha``color-to-alpha``scale-hsla` + +Default Value: none +_(no filters.)_ + +A list of image filters to apply to the main canvas (see the `image-filters` doc for how they work on a separate canvas). +* * * + +##### comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current layer on top of other layers.)_ + +Composite operation. This defines how this layer should behave relative to layers atop or below it. +* * * + +##### opacity `float` + + + +Default Value: 1 +_(No separate buffer will be used and no alpha will be applied to the style after rendering.)_ + +An alpha value for the style (which means an alpha applied to all features in separate buffer and then composited back to main buffer). +* * * + + +## map + +##### background-color `color` + + + +Default Value: none +_(Will be rendered transparent.)_ + +Map Background color. +* * * + +##### background-image `uri` + + + +Default Value: +_(No background image will be used.)_ + +An image that is repeated below all features on a map as a background. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### background-image-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(The background-image will be blended with the background normally (placed on top of any existing background-color).)_ + +Set the compositing operation used to blend the image into the background. +* * * + +##### background-image-opacity `float` + + + +Default Value: 1 +_(The image opacity will not be changed when applied to the map background.)_ + +Set the opacity of the image. +* * * + +##### srs `string` + + + +Default Value: +proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs +_(The proj4 literal of EPSG:4326 is assumed to be the Map's spatial reference and all data from layers within this map will be plotted using this coordinate system. If any layers do not declare an srs value then they will be assumed to be in the same srs as the Map and not transformations will be needed to plot them in the Map's coordinate space.)_ + +Map spatial reference (proj4 string). +* * * + +##### buffer-size `float` + + + +Default Value: 0 +_(No buffer will be used.)_ + +Extra tolerance around the map (in pixels) used to ensure labels crossing tile boundaries are equally rendered in each tile (e.g. cut in each tile). Not intended to be used in combination with "avoid-edges". +* * * + +##### maximum-extent `string` + + + +Default Value: -20037508.34,-20037508.34,20037508.34,20037508.34 +_(All data will be clipped to global mercator extent (default is applied in Carto.js).)_ + +An extent to be used to limit the bounds used to query all layers during rendering. Should be minx, miny, maxx, maxy in the coordinates of the Map. +* * * + +##### base `string` + + + +Default Value: +_(This base path defaults to an empty string meaning that any relative paths to files referenced in styles or layers will be interpreted relative to the application process.)_ + +Any relative paths used to reference files will be understood as relative to this directory path if the map is loaded from an in memory object rather than from the filesystem. If the map is loaded from the filesystem and this option is not provided it will be set to the directory of the stylesheet. +* * * + +##### font-directory `uri` + + + +Default Value: none +_(No map-specific fonts will be registered.)_ + +Path to a directory which holds fonts which should be registered when the Map is loaded (in addition to any fonts that may be automatically registered). +* * * + + +## polygon + +##### polygon-fill `color` + + + +Default Value: The color gray will be used for fill. +_(Gray and fully opaque (alpha = 1), same as rgb(128,128,128) or rgba(128,128,128,1).)_ + +Fill color to assign to a polygon. +* * * + +##### polygon-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the polygon. +* * * + +##### polygon-gamma `float` + + + +Default Value: 1 +_(Fully antialiased.)_ +Range: 0-1 +Level of antialiasing of polygon edges. +* * * + +##### polygon-gamma-method `keyword` +`power``linear``none``threshold``multiply` + + +Default Value: power +_(pow(x,gamma) is used to calculate pixel gamma, which produces slightly smoother line and polygon antialiasing than the 'linear' method, while other methods are usually only used to disable AA.)_ + +An Antigrain Geometry specific rendering hint to control the quality of antialiasing. Under the hood in Mapnik this method is used in combination with the 'gamma' value (which defaults to 1). The methods are in the AGG source at https://github.com/mapnik/mapnik/blob/master/deps/agg/include/agg_gamma_functions. +* * * + +##### polygon-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extend outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### polygon-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify geometries by the given tolerance. +* * * + +##### polygon-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify geometries by the given algorithm. +* * * + +##### polygon-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### polygon-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform polygon geometry with specified function. +* * * + +##### polygon-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## line + +##### line-color `color` + + + +Default Value: black +_(black and fully opaque (alpha = 1), same as rgb(0,0,0) or rgba(0,0,0,1).)_ + +The color of a drawn line. +* * * + +##### line-width `float` + + + +Default Value: 1 +_(The line will be rendered 1 pixel wide.)_ + +The width of a line in pixels. +* * * + +##### line-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of a line. +* * * + +##### line-join `keyword` +`miter``miter-revert``round``bevel` + + +Default Value: miter +_(The line joins will be rendered using a miter look.)_ + +The behavior of lines when joining. +* * * + +##### line-cap `keyword` +`butt``round``square` + + +Default Value: butt +_(The line endings will be rendered using a butt look.)_ + +The display of line endings. +* * * + +##### line-gamma `float` + + + +Default Value: 1 +_(Fully antialiased.)_ +Range: 0-1 +Level of antialiasing of stroke line. +* * * + +##### line-gamma-method `keyword` +`power``linear``none``threshold``multiply` + + +Default Value: power +_(pow(x,gamma) is used to calculate pixel gamma, which produces slightly smoother line and polygon antialiasing than the 'linear' method, while other methods are usually only used to disable AA.)_ + +An Antigrain Geometry specific rendering hint to control the quality of antialiasing. Under the hood in Mapnik this method is used in combination with the 'gamma' value (which defaults to 1). The methods are in the AGG source at https://github.com/mapnik/mapnik/blob/master/deps/agg/include/agg_gamma_functions. +* * * + +##### line-dasharray `numbers` + + + +Default Value: none +_(The line will be drawn without dashes.)_ + +A pair of length values [a,b], where (a) is the dash length and (b) is the gap length respectively. More than two values are supported for more complex patterns. +* * * + +##### line-dash-offset `numbers` + + + +Default Value: none +_(The line will be drawn without dashes.)_ + +Valid parameter but not currently used in renderers (only exists for experimental svg support in Mapnik which is not yet enabled). +* * * + +##### line-miterlimit `float` + + + +Default Value: 4 +_(Will auto-convert miters to bevel line joins when theta is less than 29 degrees as per the SVG spec: 'miterLength / stroke-width = 1 / sin ( theta / 2 )'.)_ + +The limit on the ratio of the miter length to the stroke-width. Used to automatically convert miter joins to bevel joins for sharp angles to avoid the miter extending beyond the thickness of the stroking path. Normally will not need to be set, but a larger value can sometimes help avoid jaggy artifacts. +* * * + +##### line-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### line-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify geometries by the given tolerance. +* * * + +##### line-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify geometries by the given algorithm. +* * * + +##### line-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### line-offset `float` + + + +Default Value: 0 +_(Will not be offset.)_ + +Offsets a line a number of pixels parallel to its actual path. Positive values move the line left, negative values move it right (relative to the directionality of the line). +* * * + +##### line-rasterizer `keyword` +`full``fast` + + +Default Value: full +_(The line will be rendered using the highest quality method rather than the fastest.)_ + +Exposes an alternate AGG rendering method that sacrifices some accuracy for speed. +* * * + +##### line-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform line geometry with specified function. +* * * + +##### line-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## markers + +##### marker-file `uri` + + + +Default Value: none +_(An ellipse or circle, if width equals height.)_ + +A file that this marker shows at each placement. If no file is given, the marker will show an ellipse. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### marker-opacity `float` + + + +Default Value: 1 +_(The stroke-opacity and fill-opacity of the marker.)_ + +The overall opacity of the marker, if set, overrides both the opacity of both the fill and stroke. +* * * + +##### marker-fill-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The fill opacity of the marker. +* * * + +##### marker-line-color `color` + + + +Default Value: black +_(The marker will be drawn with a black outline.)_ + +The color of the stroke around the marker. +* * * + +##### marker-line-width `float` + + + +Default Value: 0.5 +_(The marker will be drawn with an outline of .5 pixels wide.)_ + +The width of the stroke around the marker, in pixels. This is positioned on the boundary, so high values can cover the area itself. +* * * + +##### marker-line-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of a line. +* * * + +##### marker-placement `keyword` +`point``line``interior``vertex-first``vertex-last` + + +Default Value: point +_(Place markers at the center point (centroid) of the geometry.)_ + +Attempt to place markers on a point, in the center of a polygon, or if markers-placement:line, then multiple times along a line. 'interior' placement can be used to ensure that points placed on polygons are forced to be inside the polygon interior. The 'vertex-first' and 'vertex-last' options can be used to place markers at the first or last vertex of lines or polygons. +* * * + +##### marker-multi-policy `keyword` +`each``whole``largest` + + +Default Value: each +_(If a feature contains multiple geometries and the placement type is either point or interior then a marker will be rendered for each.)_ + +A special setting to allow the user to control rendering behavior for 'multi-geometries' (when a feature contains multiple geometries). This setting does not apply to markers placed along lines. The 'each' policy is default and means all geometries will get a marker. The 'whole' policy means that the aggregate centroid between all geometries will be used. The 'largest' policy means that only the largest (by bounding box areas) feature will get a rendered marker (this is how text labeling behaves by default). +* * * + +##### marker-type `keyword` +`arrow``ellipse` + + +Default Value: ellipse +_(The marker shape is an ellipse.)_ + +The default marker-type. If a SVG file is not given as the marker-file parameter, the renderer provides either an arrow or an ellipse (a circle if height is equal to width). +* * * + +##### marker-width `float` + + + +Default Value: 10 +_(The marker width is 10 pixels.)_ + +The width of the marker, if using one of the default types. +* * * + +##### marker-height `float` + + + +Default Value: 10 +_(The marker height is 10 pixels.)_ + +The height of the marker, if using one of the default types. +* * * + +##### marker-fill `color` + + + +Default Value: blue +_(The marker fill color is blue.)_ + +The color of the area of the marker. +* * * + +##### marker-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow markers to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping markers are shown or hidden. +* * * + +##### marker-avoid-edges `boolean` + + + +Default Value: false +_(Markers will be potentially placed near tile edges and therefore may look cut off unless they are rendered on each adjacent tile.)_ + +Avoid placing markers that intersect with tile boundaries. +* * * + +##### marker-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache.)_ + +Value to control whether the placement of the feature will prevent the placement of other features. +* * * + +##### marker-spacing `float` + + + +Default Value: 100 +_(In the case of marker-placement:line then draw a marker every 100 pixels along a line.)_ + +Space between repeated markers in pixels. If the spacing is less than the marker size or larger than the line segment length then no marker will be placed. Any value less than 1 will be ignored and the default will be used instead. +* * * + +##### marker-max-error `float` + + + +Default Value: 0.2 +_(N/A: not intended to be changed.)_ + +N/A: not intended to be changed. +* * * + +##### marker-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation.)_ + +Transform marker instance with specified function. Ignores map scale factor. +* * * + +##### marker-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### marker-simplify `float` + + + +Default Value: 0 +_(Geometry will not be simplified.)_ + +geometries are simplified by the given tolerance. +* * * + +##### marker-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +geometries are simplified by the given algorithm. +* * * + +##### marker-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### marker-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform marker geometry with specified function. +* * * + +##### marker-offset `float` + + + +Default Value: 0 +_(Will not be offset.)_ + +Offsets a marker from a line a number of pixels parallel to its actual path. Positive values move the marker left, negative values move it right (relative to the directionality of the line). +* * * + +##### marker-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### marker-direction `keyword` +`auto``auto-down``left``right``left-only``right-only``up``down` + + +Default Value: right +_(Markers are oriented to the right in the line direction.)_ + +How markers should be placed along lines. With the "auto" setting when marker is upside down the marker is automatically rotated by 180 degrees to keep it upright. The "auto-down" value places marker in the opposite orientation to "auto". The "left" or "right" settings can be used to force marker to always be placed along a line in a given direction and therefore disables rotating if marker appears upside down. The "left-only" or "right-only" properties also force a given direction but will discard upside down markers rather than trying to flip it. The "up" and "down" settings don't adjust marker's orientation to the line direction. +* * * + + +## shield + +##### shield-name `string` + + + +Default Value: +_(No text label will be rendered with the shield.)_ + +Value to use for a shield"s text label. Data columns are specified using brackets like [column_name]. +* * * + +##### shield-file `uri` + + + +Default Value: none + + +Image file to render behind the shield text. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### shield-face-name `string` + + + +Default Value: none + + +Font name and style to use for the shield text. +* * * + +##### shield-unlock-image `boolean` + + + +Default Value: false +_(text alignment relative to the shield image uses the center of the image as the anchor for text positioning.)_ + +This parameter should be set to true if you are trying to position text beside rather than on top of the shield image. +* * * + +##### shield-size `float` + + + +Default Value: 10 +_(Font size of 10 will be used to render text.)_ + +The size of the shield text in pixels. +* * * + +##### shield-fill `color` + + + +Default Value: black +_(The shield text will be rendered black.)_ + +The color of the shield text. +* * * + +##### shield-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point +_(One shield will be placed per geometry.)_ + +How this shield should be placed. Point placement places one shield on top of a point geometry and at the centroid of a polygon or the middle point of a line, line places along lines multiple times per feature, vertex places on the vertexes of polygons, and interior attempts to place inside of a polygon. +* * * + +##### shield-avoid-edges `boolean` + + + +Default Value: false +_(Shields will be potentially placed near tile edges and therefore may look cut off unless they are rendered on each adjacent tile.)_ + +Avoid placing shields that intersect with tile boundaries. +* * * + +##### shield-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow shields to overlap with other map elements already placed.)_ + +Control whether overlapping shields are shown or hidden. +* * * + +##### shield-margin `float` + + + +Default Value: 0 +_(No extra margin will be used to determine if a shield collides with any other text, shield, or marker.)_ + +Minimum distance that a shield can be placed from any other text, shield, or marker. +* * * + +##### shield-repeat-distance `float` + + + +Default Value: 0 +_(Shields with the same text will be rendered without restriction.)_ + +Minimum distance between repeated shields. If set this will prevent shields being rendered nearby each other that contain the same text. Similiar to shield-min-distance with the difference that it works the same no matter what placement strategy is used. +* * * + +##### shield-min-distance `float` + + + +Default Value: 0 +_(Shields with the same text will be rendered without restriction.)_ + +Minimum distance to the next shield with the same text. Only works for line placement. +* * * + +##### shield-spacing `float` + + + +Default Value: 0 +_(Only one shield per line will attempt to be placed.)_ + +Distance the renderer should use to try to place repeated shields on a line. +* * * + +##### shield-min-padding `float` + + + +Default Value: 0 +_(No margin will be used to detect if a shield is nearby a tile boundary.)_ + +Minimum distance a shield will be placed from the edge of a tile. This option is similiar to shield-avoid-edges:true except that the extra margin is used to discard cases where the shield+margin are not fully inside the tile. +* * * + +##### shield-label-position-tolerance `float` + + + +Default Value: shield-spacing/2.0 +_(If a shield cannot be placed then the renderer will advance by shield-spacing/2.0 to try placement again.)_ + +Allows the shield to be displaced from its ideal position by a number of pixels (only works with placement:line). +* * * + +##### shield-wrap-width `unsigned` + + + +Default Value: 0 +_(Text will not be wrapped.)_ + +Length of a chunk of text in pixels before wrapping text. If set to zero, text doesn't wrap. +* * * + +##### shield-wrap-before `boolean` + + + +Default Value: false +_(Wrapped lines will be a bit longer than wrap-width.)_ + +Wrap text before wrap-width is reached. +* * * + +##### shield-wrap-character `string` + + + +Default Value: " " +_(Lines will be wrapped when whitespace is encountered.)_ + +Use this character instead of a space to wrap long names. +* * * + +##### shield-halo-fill `color` + + + +Default Value: white +_(The shield halo text will be rendered white.)_ + +Specifies the color of the halo around the text. +* * * + +##### shield-halo-radius `float` + + + +Default Value: 0 +_(no halo.)_ + +Specify the radius of the halo in pixels. +* * * + +##### shield-halo-rasterizer `keyword` +`full``fast` + + +Default Value: full +_(The shield will be rendered using the highest quality method rather than the fastest.)_ + +Exposes an alternate text halo rendering method that sacrifices quality for speed. +* * * + +##### shield-halo-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: +_(No transformation.)_ + +Transform shield halo relative to the actual text with specified function. Allows for shadow or embossed effects. Ignores map scale factor. +* * * + +##### shield-halo-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### shield-halo-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A number from 0 to 1 specifying the opacity for the text halo. +* * * + +##### shield-character-spacing `unsigned` + + + +Default Value: 0 +_(The default character spacing of the font will be used.)_ + +Horizontal spacing between characters (in pixels). Currently works for point placement only, not line placement. +* * * + +##### shield-line-spacing `unsigned` + + + +Default Value: 0 +_(The default font spacing will be used.)_ + +Vertical spacing between lines of multiline labels (in pixels). +* * * + +##### shield-text-dx `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text within shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the shield right. +* * * + +##### shield-text-dy `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text within shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the shield down. +* * * + +##### shield-dx `float` + + + +Default Value: 0 +_(Shield will not be displaced.)_ + +Displace shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right. +* * * + +##### shield-dy `float` + + + +Default Value: 0 +_(Shield will not be displaced.)_ + +Displace shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text down. +* * * + +##### shield-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the image used for the shield. +* * * + +##### shield-text-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the text placed on top of the shield. +* * * + +##### shield-horizontal-alignment `keyword` +`left``middle``right``auto` + + +Default Value: auto +_(TODO.)_ + +The shield's horizontal alignment from its centerpoint. +* * * + +##### shield-vertical-alignment `keyword` +`top``middle``bottom``auto` + + +Default Value: middle +_(TODO.)_ + +The shield's vertical alignment from its centerpoint. +* * * + +##### shield-placement-type `keyword` +`dummy``simple``list` + + +Default Value: dummy +_(Alternative placements will not be enabled.)_ + +Re-position and/or re-size shield to avoid overlaps. "simple" for basic algorithm (using shield-placements string,) "dummy" to turn this feature off. +* * * + +##### shield-placements `string` + + + +Default Value: +_(No alternative placements will be used.)_ + +If "placement-type" is set to "simple", use this "POSITIONS,[SIZES]" string. An example is `shield-placements: "E,NE,SE,W,NW,SW";`. +* * * + +##### shield-text-transform `keyword` +`none``uppercase``lowercase``capitalize``reverse` + + +Default Value: none +_(No text transformation will be applied.)_ + +Transform the case of the characters. +* * * + +##### shield-justify-alignment `keyword` +`left``center``right``auto` + + +Default Value: auto +_(TODO.)_ + +Define how text in a shield's label is justified. +* * * + +##### shield-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation.)_ + +Transform shield instance with specified function. Ignores map scale factor. +* * * + +##### shield-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### shield-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify the geometries used for shield placement by the given tolerance. +* * * + +##### shield-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify the geometries used for shield placement by the given algorithm. +* * * + +##### shield-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out the angles of the geometry used for shield placement. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### shield-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## line-pattern + +##### line-pattern-file `uri` + + + +Default Value: none + + +An image file to be repeated and warped along a line. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### line-pattern-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### line-pattern-opacity `float` + + + +Default Value: 1 +_(The image is rendered without modifications.)_ + +Apply an opacity level to the image used for the pattern. +* * * + +##### line-pattern-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +geometries are simplified by the given tolerance. +* * * + +##### line-pattern-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +geometries are simplified by the given algorithm. +* * * + +##### line-pattern-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### line-pattern-offset `float` + + + +Default Value: 0 +_(The line will not be offset.)_ + +Offsets a line a number of pixels parallel to its actual path. Positive values move the line left, negative values move it right (relative to the directionality of the line). +* * * + +##### line-pattern-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform line geometry with specified function and apply pattern to transformed geometry. +* * * + +##### line-pattern-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## polygon-pattern + +##### polygon-pattern-file `uri` + + + +Default Value: none + + +Image to use as a repeated pattern fill within a polygon. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### polygon-pattern-alignment `keyword` +`global``local` + + +Default Value: global +_(Patterns will be aligned to the map (or tile boundaries) when being repeated across polygons. This is ideal for seamless patterns in tiled rendering.)_ + +Specify whether to align pattern fills to the layer's geometry (local) or to the map (global). +* * * + +##### polygon-pattern-gamma `float` + + + +Default Value: 1 +_(Fully antialiased.)_ +Range: 0-1 +Level of antialiasing of polygon pattern edges. +* * * + +##### polygon-pattern-opacity `float` + + + +Default Value: 1 +_(The image is rendered without modifications.)_ + +Apply an opacity level to the image used for the pattern. +* * * + +##### polygon-pattern-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### polygon-pattern-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +geometries are simplified by the given tolerance. +* * * + +##### polygon-pattern-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +geometries are simplified by the given algorithm. +* * * + +##### polygon-pattern-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### polygon-pattern-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform polygon geometry with specified function and apply pattern to transformed geometry. +* * * + +##### polygon-pattern-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## raster + +##### raster-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the raster symbolizer on top of other symbolizers. +* * * + +##### raster-filter-factor `float` + + + +Default Value: -1 +_(Allow the datasource to choose appropriate downscaling.)_ + +This is used by the Raster or Gdal datasources to pre-downscale images using overviews. Higher numbers can sometimes cause much better scaled image output, at the cost of speed. +* * * + +##### raster-scaling `keyword` +`near``fast``bilinear``bicubic``spline16``spline36``hanning``hamming``hermite``kaiser``quadric``catrom``gaussian``bessel``mitchell``sinc``lanczos``blackman` + + +Default Value: near +_(Nearest neighboor resampling will be used to scale the image to the target size of the map.)_ + +The scaling algorithm used to making different resolution versions of this raster layer. Bilinear is a good compromise between speed and accuracy, while lanczos gives the highest quality. +* * * + +##### raster-mesh-size `unsigned` + + + +Default Value: 16 +_(Reprojection mesh will be 1/16 of the resolution of the source image.)_ + +A reduced resolution mesh is used for raster reprojection, and the total image size is divided by the mesh-size to determine the quality of that mesh. Values for mesh-size larger than the default will result in faster reprojection but might lead to distortion. +* * * + +##### raster-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### raster-colorizer-default-mode `keyword` +`discrete``linear``exact` + + +Default Value: linear +_(A linear interpolation is used to generate colors between the two nearest stops.)_ + +This can be either `discrete`, `linear` or `exact`. If it is not specified then the default is `linear`. +* * * + +##### raster-colorizer-default-color `color` + + + +Default Value: transparent +_(Pixels that are not colored by the colorizer stops will be transparent.)_ + +This can be any color. Sets the color that is applied to all values outside of the range of the colorizer-stops. If not supplied pixels will be fully transparent. +* * * + +##### raster-colorizer-epsilon `float` + + + +Default Value: 1.1920928955078125e-07 +_(Pixels must very closely match the stop filter otherwise they will not be colored.)_ + +This can be any positive floating point value and will be used as a tolerance in floating point comparisions. The higher the value the more likely a stop will match and color data. +* * * + +##### raster-colorizer-stops `tags` + + + +Default Value: +_(No colorization will happen without supplying stops.)_ + +Assigns raster data values to colors. Stops must be listed in ascending order, and contain at a minimum the value and the associated color. You can also include the color-mode as a third argument, like `stop(100,#fff,exact)`. +* * * + + +## point + +##### point-file `uri` + + + +Default Value: none +_(A 4x4 black square will be rendered.)_ + +Image file to represent a point. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### point-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow points to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping points are shown or hidden. +* * * + +##### point-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache.)_ + +Control whether the placement of the feature will prevent the placement of other features. +* * * + +##### point-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A value from 0 to 1 to control the opacity of the point. +* * * + +##### point-placement `keyword` +`centroid``interior` + + +Default Value: centroid +_(The centroid of the geometry will be used to place the point.)_ + +Control how this point should be placed. Centroid calculates the geometric center of a polygon, which can be outside of it, while interior always places inside of a polygon. +* * * + +##### point-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation.)_ + +Transform point instance with specified function. Ignores map scale factor. +* * * + +##### point-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## text + +##### text-name `string` + + + +Default Value: none + + +Value to use for a text label. Data columns are specified using brackets like [column_name]. +* * * + +##### text-face-name `string` + + + +Default Value: none + + +Font name and style to render a label in. +* * * + +##### text-size `float` + + + +Default Value: 10 +_(Font size of 10 will be used to render text.)_ + +Text size in pixels. +* * * + +##### text-ratio `unsigned` + + + +Default Value: 0 +_(TODO.)_ + +Define the amount of text (of the total) present on successive lines when wrapping occurs. +* * * + +##### text-wrap-width `unsigned` + + + +Default Value: 0 +_(Text will not be wrapped.)_ + +Length of a chunk of text in pixels before wrapping text. If set to zero, text doesn't wrap. +* * * + +##### text-wrap-before `boolean` + + + +Default Value: false +_(Wrapped lines will be a bit longer than wrap-width.)_ + +Wrap text before wrap-width is reached. +* * * + +##### text-wrap-character `string` + + + +Default Value: " " +_(Lines will be wrapped when whitespace is encountered.)_ + +Use this character instead of a space to wrap long text. +* * * + +##### text-repeat-wrap-character `boolean` + + + +Default Value: false +_(Character will be removed when used to wrap a line.)_ + +Keep the character used to wrap a line instead of removing it, and repeat it on the new line. +* * * + +##### text-spacing `unsigned` + + + +Default Value: 0 +_(Only one label per line will attempt to be placed.)_ + +Distance the renderer should use to try to place repeated text labels on a line. +* * * + +##### text-character-spacing `float` + + + +Default Value: 0 +_(The default character spacing of the font will be used.)_ + +Horizontal spacing adjustment between characters in pixels. This value is ignored when `horizontal-alignment` is set to `adjust`. Typographic ligatures are turned off when this value is greater than zero. +* * * + +##### text-line-spacing `unsigned` + + + +Default Value: 0 +_(The default font spacing will be used.)_ + +Vertical spacing adjustment between lines in pixels. +* * * + +##### text-label-position-tolerance `float` + + + +Default Value: text-spacing/2.0 +_(If a shield cannot be placed then the renderer will advance by text-spacing/2.0 to try placement again.)_ + +Allows the label to be displaced from its ideal position by a number of pixels (only works with placement:line). +* * * + +##### text-max-char-angle-delta `float` + + + +Default Value: 22.5 +_(The label will not be placed if a character falls on a line with an angle sharper than 22.5 degrees.)_ + +The maximum angle change, in degrees, allowed between adjacent characters in a label. This value internally is converted to radians to the default is 22.5*math.pi/180.0. The higher the value the fewer labels will be placed around around sharp corners. +* * * + +##### text-fill `color` + + + +Default Value: black +_(The text will be rendered black.)_ + +Specifies the color for the text. +* * * + +##### text-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A number from 0 to 1 specifying the opacity for the text. +* * * + +##### text-halo-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A number from 0 to 1 specifying the opacity for the text halo. +* * * + +##### text-halo-fill `color` + + + +Default Value: white +_(The halo will be rendered white.)_ + +Specifies the color of the halo around the text. +* * * + +##### text-halo-radius `float` + + + +Default Value: 0 +_(no halo.)_ + +Specify the radius of the halo in pixels. +* * * + +##### text-halo-rasterizer `keyword` +`full``fast` + + +Default Value: full +_(The text will be rendered using the highest quality method rather than the fastest.)_ + +Exposes an alternate text halo rendering method that sacrifices quality for speed. +* * * + +##### text-halo-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: +_(No transformation.)_ + +Transform text halo relative to the actual text with specified function. Allows for shadow or embossed effects. Ignores map scale factor. +* * * + +##### text-dx `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text by fixed amount, in pixels, +/- along the X axis. With "dummy" placement-type, a positive value displaces to the right. With "simple" placement-type, it is either left, right or unchanged, depending on the placement selected. Any non-zero value implies "horizontal-alignment" changes to "left" by default. Has no effect with 'line' text-placement-type. +* * * + +##### text-dy `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text by fixed amount, in pixels, +/- along the Y axis. With "dummy" placement-type, a positive value displaces downwards. With "simple" placement-type, it is either up, down or unchanged, depending on the placement selected. With "line" placement-type, a positive value displaces above the path. +* * * + +##### text-vertical-alignment `keyword` +`top``middle``bottom``auto` + + +Default Value: auto +_(Default affected by value of dy; "top" for dy>0, "bottom" for dy<0.)_ + +Position of label relative to point position. +* * * + +##### text-avoid-edges `boolean` + + + +Default Value: false +_(Text will be potentially placed near tile edges and therefore may look cut off unless the same text label is rendered on each adjacent tile.)_ + +Avoid placing labels that intersect with tile boundaries. +* * * + +##### text-margin `float` + + + +Default Value: 0 +_(No extra margin will be used to determine if a label collides with any other text, shield, or marker.)_ + +Minimum distance that a label can be placed from any other text, shield, or marker. +* * * + +##### text-repeat-distance `float` + + + +Default Value: 0 +_(Labels with the same text will be rendered without restriction.)_ + +Minimum distance between repeated text. If set this will prevent text labels being rendered nearby each other that contain the same text. Similiar to text-min-distance with the difference that it works the same no matter what placement strategy is used. +* * * + +##### text-min-distance `float` + + + +Default Value: 0 +_(Labels with the same text will be rendered without restriction.)_ + +Minimum distance to the next label with the same text. Only works for line placement. Deprecated: replaced by `text-repeat-distance` and `text-margin` +* * * + +##### text-min-padding `float` + + + +Default Value: 0 +_(No margin will be used to detect if a text label is nearby a tile boundary.)_ + +Minimum distance a text label will be placed from the edge of a tile. This option is similiar to shield-avoid-edges:true except that the extra margin is used to discard cases where the shield+margin are not fully inside the tile. +* * * + +##### text-min-path-length `float` + + + +Default Value: 0 +_(place labels on all geometries no matter how small they are.)_ + +Place labels only on polygons and lines with a bounding width longer than this value (in pixels). +* * * + +##### text-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow text to overlap with other text - overlapping markers will not be shown.)_ + +Control whether overlapping text is shown or hidden. +* * * + +##### text-orientation `float` + + + +Default Value: 0 +_(Text is not rotated and is displayed upright.)_ + +Rotate the text. (only works with text-placement:point). +* * * + +##### text-rotate-displacement `boolean` + + + +Default Value: false +_(Label center is used for rotation.)_ + +Rotates the displacement around the placement origin by the angle given by "orientation". +* * * + +##### text-upright `keyword` +`auto``auto-down``left``right``left-only``right-only` + + +Default Value: auto +_(Text will be positioned upright automatically.)_ + +How this label should be placed along lines. By default when more than half of a label's characters are upside down the label is automatically flipped to keep it upright. By changing this parameter you can prevent this "auto-upright" behavior. The "auto-down" value places text in the opposite orientation to "auto". The "left" or "right" settings can be used to force text to always be placed along a line in a given direction and therefore disables flipping if text appears upside down. The "left-only" or "right-only" properties also force a given direction but will discard upside down text rather than trying to flip it. +* * * + +##### text-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point +_(One shield will be placed per geometry.)_ + +How this label should be placed. Point placement places one label on top of a point geometry and at the centroid of a polygon or the middle point of a line, line places along lines multiple times per feature, vertex places on the vertexes of polygons, and interior attempts to place inside of a polygon. +* * * + +##### text-placement-type `keyword` +`dummy``simple``list` + + +Default Value: dummy +_(Alternative placements will not be enabled.)_ + +Re-position and/or re-size text to avoid overlaps. "simple" for basic algorithm (using text-placements string,) "dummy" to turn this feature off. +* * * + +##### text-placements `string` + + + +Default Value: +_(No alternative placements will be used.)_ + +If "placement-type" is set to "simple", use this "POSITIONS,[SIZES]" string. An example is `text-placements: "E,NE,SE,W,NW,SW";`. +* * * + +##### text-transform `keyword` +`none``uppercase``lowercase``capitalize``reverse` + + +Default Value: none +_(Transform text instance with specified function. Ignores map scale factor.)_ + +Transform the case of the characters. +* * * + +##### text-horizontal-alignment `keyword` +`left``middle``right``auto``adjust` + + +Default Value: auto +_(TODO.)_ + +The text's horizontal alignment from it's centerpoint. If `placement` is set to `line`, then `adjust` can be set to auto-fit the text to the length of the path by dynamically calculating `character-spacing`. +* * * + +##### text-align `keyword` +`left``right``center``auto` + + +Default Value: auto +_(Auto alignment means that text will be centered by default except when using the `placement-type` parameter - in that case either right or left justification will be used automatically depending on where the text could be fit given the `text-placements` directives.)_ + +Define how text is justified. +* * * + +##### text-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### text-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify the geometries used for text placement by the given tolerance. +* * * + +##### text-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify the geometries used for text placement by the given algorithm. +* * * + +##### text-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out the angles of the geometry used for text placement. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### text-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### text-halo-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### text-font-feature-settings `string` + + + +Default Value: +_(Default set of typographic features recommended by OpenType specification. Ligatures are turned off by default when `character-spacing` is greater than zero.)_ + +Comma separated list of OpenType typographic features. The syntax and semantics conforms to `font-feature-settings` from W3C CSS. +* * * + +##### text-largest-bbox-only `boolean` + + + +Default Value: true +_(For multipolygons only polygon with largest bbox area is labeled (does not apply to other geometries).)_ + +Controls default labeling behavior on multipolygons. The default is true and means that only the polygon with largest bbox is labeled. +* * * + + +## building + +##### building-fill `color` + + + +Default Value: The color gray will be used for fill. +_(Gray and fully opaque (alpha = 1), same as rgb(128,128,128) or rgba(128,128,128,1).)_ + +The color of the buildings fill. Note: 0.8 will be used to multiply each color component to auto-generate a darkened wall color. +* * * + +##### building-fill-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the building as a whole, including all walls. +* * * + +##### building-height `float` + + + +Default Value: 0 +_(Buildings will not have a visual height and will instead look like flat polygons.)_ + +The height of the building in pixels. +* * * + + +## debug + +##### debug-mode `string` + + + +Default Value: collision +_(The otherwise invisible collision boxes will be rendered as squares on the map.)_ + +The mode for debug rendering. +* * * + + +## dot + +##### dot-fill `color` + + + +Default Value: gray +_(The dot fill color is gray.)_ + +The color of the area of the dot. +* * * + +##### dot-opacity `float` + + + +Default Value: 1 +_(The opacity of the dot.)_ + +The overall opacity of the dot. +* * * + +##### dot-width `float` + + + +Default Value: 1 +_(The marker width is 1 pixel.)_ + +The width of the dot in pixels. +* * * + +##### dot-height `float` + + + +Default Value: 1 +_(The marker height is 1 pixels.)_ + +The height of the dot in pixels. +* * * + +##### dot-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current layer on top of other layers.)_ + +Composite operation. This defines how this layer should behave relative to layers atop or below it. +* * * + + + + +### Values + +Below is a list of values and an explanation of any expression that can be applied to properties in CartCSS. + +### Color + +CartoCSS accepts a variety of syntaxes for colors - HTML-style hex values, rgb, rgba, hsl, hsla, husl, and husla. It also supports the predefined HTML colors names, like `yellow` and `blue`. + +``` css +#line { +line-color: #ff0; +line-color: #ffff00; +line-color: rgb(255, 255, 0); +line-color: rgba(255, 255, 0, 1); +line-color: hsl(100, 50%, 50%); +line-color: hsla(100, 50%, 50%, 1); +line-color: husl(100, 50%, 50%); // same values yield different color than HSL +line-color: husla(100, 50%, 50%, 1); +line-color: yellow; +} +``` + +Especially of note is the support for hsl and husl, which can be [easier to reason about than rgb()](http://mothereffinghsl.com/). Carto also includes several color operation functions [borrowed from less](http://lesscss.org/functions/#color-operations): + +``` css +// lighten and darken colors +lighten(#ace, 10%); +darken(#ace, 10%); + +// saturate and desaturate +saturate(#550000, 10%); +desaturate(#00ff00, 10%); + +// increase or decrease the opacity of a color +fadein(#fafafa, 10%); +fadeout(#fefefe, 14%); + +// spin rotates a color around the color wheel by degrees +spin(#ff00ff, 10); + +// mix generates a color in between two other colors. +mix(#fff, #000, 50%); + +// get color components +hue(#ff00ff); +saturation(#ff00ff); +lightness(#ff00ff); +alpha(hsla(100, 50%, 50%, 0.5)); +``` + +These functions all take arguments which can be color variables, literal colors, or the results of other functions operating on colors. All the above mentioned functions also come in +a `functionp`-variant (e.g. `lightenp`), which force a given color into perceptual color space. + +### Float + +Float is a fancy way of saying 'number'. In CartoCSS, you specify _just a number_ - unlike CSS, there are no units, but everything is specified in pixels. + +``` css +#line { +line-width: 2; +} +``` + +It's also possible to do simple math with number values: + +``` css +#line { +line-width: 4 / 2; // division +line-width: 4 + 2; // addition +line-width: 4 - 2; // subtraction +line-width: 4 * 2; // multiplication +line-width: 4 % 2; // modulus +} +``` + +### URI + +URI is a fancy way of saying URL. When an argument is a URI, you use the same kind of `url('place.png')` notation that you would with HTML. Quotes around the URL aren't required, but are highly recommended. URIs can be paths to places on your computer, or on the internet. + +```css +#markers { +marker-file: url('marker.png'); +} +``` + +### String + +A string is basically just text. In the case of CartoCSS, you're going to put it in quotes. Strings can be anything, though pay attention to the cases of `text-name` and `shield-name` - they actually will refer to features, which you refer to by putting them in brackets, as seen in the example below. + +```css +#labels { +text-name: "[MY_FIELD]"; +} +``` + +### Boolean + +Boolean means yes or no, so it accepts the values `true` or `false`. + +```css +#markers { +marker-allow-overlap:true; +} +``` + +### Expressions + +Expressions are statements that can include fields, numbers, and other types in a really flexible way. You have run into expressions before, in the realm of 'fields', where you'd specify `"[FIELD]"`, but expressions allow you to drop the quotes and also do quick addition, division, multiplication, and concatenation from within Carto syntax. + +```css +#buildings { +building-height: [HEIGHT_FIELD] * 10; +} +``` + +### Numbers +Numbers are comma-separated lists of one or more number in a specific order. They're used in line dash arrays, in which the numbers specify intervals of line, break, and line again. + +```css +#disputedboundary { +line-dasharray: 1, 4, 2; +} +``` + +### Percentages +In Carto, the percentage symbol, `%` universally means `value/100`. It's meant to be used with ratio-related properties, like opacity rules. + +_You should not use percentages as widths, heights, or other properties - unlike CSS, percentages are not relative to cascaded classes or page size, they're, as stated, simply the value divided by one hundred._ + +```css +#world { +// this syntax +polygon-opacity: 50%; + +// is equivalent to +polygon-opacity: 0.5; +} +``` + +### Functions + +Functions are comma-separated lists of one or more functions. For instance, transforms use the `functions` type to allow for transforms within Carto, which are optionally chainable. + +```css +#point { +point-transform: scale(2, 2); +} +``` diff --git a/docs/3.0.9.md b/docs/3.0.9.md new file mode 100644 index 0000000..ad7ed30 --- /dev/null +++ b/docs/3.0.9.md @@ -0,0 +1,2226 @@ +# Carto documentation + +The following is a list of properties provided in CartoCSS that you can apply to map elements. + +## All elements + +##### image-filters `functions` + +`agg-stack-blur``emboss``blur``gray``sobel``edge-detect``x-gradient``y-gradient``invert``sharpen``color-blind-protanope``color-blind-deuteranope``color-blind-tritanope``colorize-alpha``color-to-alpha``scale-hsla` + +Default Value: none +_(no filters.)_ + +A list of image filters that will be applied to the active rendering canvas for a given style. The presence of one more `image-filters` will trigger a new canvas to be created before starting to render a style and then this canvas will be composited back into the main canvas after rendering all features and after all `image-filters` have been applied. See `direct-image-filters` if you want to apply a filter directly to the main canvas. +* * * + +##### image-filters-inflate `boolean` + + + +Default Value: false +_(No special handling will be done and image filters that blur data will only blur up to the edge of a tile boundary.)_ + +A property that can be set to true to enable using an inflated image internally for seamless blurring across tiles (requires buffered data). +* * * + +##### direct-image-filters `functions` + +`agg-stack-blur``emboss``blur``gray``sobel``edge-detect``x-gradient``y-gradient``invert``sharpen``color-blind-protanope``color-blind-deuteranope``color-blind-tritanope``colorize-alpha``color-to-alpha``scale-hsla` + +Default Value: none +_(no filters.)_ + +A list of image filters to apply to the main canvas (see the `image-filters` doc for how they work on a separate canvas). +* * * + +##### comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current layer on top of other layers.)_ + +Composite operation. This defines how this layer should behave relative to layers atop or below it. +* * * + +##### opacity `float` + + + +Default Value: 1 +_(No separate buffer will be used and no alpha will be applied to the style after rendering.)_ + +An alpha value for the style (which means an alpha applied to all features in separate buffer and then composited back to main buffer). +* * * + + +## map + +##### background-color `color` + + + +Default Value: none +_(Will be rendered transparent.)_ + +Map Background color. +* * * + +##### background-image `uri` + + + +Default Value: +_(No background image will be used.)_ + +An image that is repeated below all features on a map as a background. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### background-image-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(The background-image will be blended with the background normally (placed on top of any existing background-color).)_ + +Set the compositing operation used to blend the image into the background. +* * * + +##### background-image-opacity `float` + + + +Default Value: 1 +_(The image opacity will not be changed when applied to the map background.)_ + +Set the opacity of the image. +* * * + +##### srs `string` + + + +Default Value: +proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs +_(The proj4 literal of EPSG:4326 is assumed to be the Map's spatial reference and all data from layers within this map will be plotted using this coordinate system. If any layers do not declare an srs value then they will be assumed to be in the same srs as the Map and not transformations will be needed to plot them in the Map's coordinate space.)_ + +Map spatial reference (proj4 string). +* * * + +##### buffer-size `float` + + + +Default Value: 0 +_(No buffer will be used.)_ + +Extra tolerance around the map (in pixels) used to ensure labels crossing tile boundaries are equally rendered in each tile (e.g. cut in each tile). Not intended to be used in combination with "avoid-edges". +* * * + +##### maximum-extent `string` + + + +Default Value: -20037508.34,-20037508.34,20037508.34,20037508.34 +_(All data will be clipped to global mercator extent (default is applied in Carto.js).)_ + +An extent to be used to limit the bounds used to query all layers during rendering. Should be minx, miny, maxx, maxy in the coordinates of the Map. +* * * + +##### base `string` + + + +Default Value: +_(This base path defaults to an empty string meaning that any relative paths to files referenced in styles or layers will be interpreted relative to the application process.)_ + +Any relative paths used to reference files will be understood as relative to this directory path if the map is loaded from an in memory object rather than from the filesystem. If the map is loaded from the filesystem and this option is not provided it will be set to the directory of the stylesheet. +* * * + +##### font-directory `uri` + + + +Default Value: none +_(No map-specific fonts will be registered.)_ + +Path to a directory which holds fonts which should be registered when the Map is loaded (in addition to any fonts that may be automatically registered). +* * * + + +## polygon + +##### polygon-fill `color` + + + +Default Value: The color gray will be used for fill. +_(Gray and fully opaque (alpha = 1), same as rgb(128,128,128) or rgba(128,128,128,1).)_ + +Fill color to assign to a polygon. +* * * + +##### polygon-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the polygon. +* * * + +##### polygon-gamma `float` + + + +Default Value: 1 +_(Fully antialiased.)_ +Range: 0-1 +Level of antialiasing of polygon edges. +* * * + +##### polygon-gamma-method `keyword` +`power``linear``none``threshold``multiply` + + +Default Value: power +_(pow(x,gamma) is used to calculate pixel gamma, which produces slightly smoother line and polygon antialiasing than the 'linear' method, while other methods are usually only used to disable AA.)_ + +An Antigrain Geometry specific rendering hint to control the quality of antialiasing. Under the hood in Mapnik this method is used in combination with the 'gamma' value (which defaults to 1). The methods are in the AGG source at https://github.com/mapnik/mapnik/blob/master/deps/agg/include/agg_gamma_functions. +* * * + +##### polygon-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extend outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### polygon-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify geometries by the given tolerance. +* * * + +##### polygon-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify geometries by the given algorithm. +* * * + +##### polygon-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### polygon-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform polygon geometry with specified function. +* * * + +##### polygon-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## line + +##### line-color `color` + + + +Default Value: black +_(black and fully opaque (alpha = 1), same as rgb(0,0,0) or rgba(0,0,0,1).)_ + +The color of a drawn line. +* * * + +##### line-width `float` + + + +Default Value: 1 +_(The line will be rendered 1 pixel wide.)_ + +The width of a line in pixels. +* * * + +##### line-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of a line. +* * * + +##### line-join `keyword` +`miter``miter-revert``round``bevel` + + +Default Value: miter +_(The line joins will be rendered using a miter look.)_ + +The behavior of lines when joining. +* * * + +##### line-cap `keyword` +`butt``round``square` + + +Default Value: butt +_(The line endings will be rendered using a butt look.)_ + +The display of line endings. +* * * + +##### line-gamma `float` + + + +Default Value: 1 +_(Fully antialiased.)_ +Range: 0-1 +Level of antialiasing of stroke line. +* * * + +##### line-gamma-method `keyword` +`power``linear``none``threshold``multiply` + + +Default Value: power +_(pow(x,gamma) is used to calculate pixel gamma, which produces slightly smoother line and polygon antialiasing than the 'linear' method, while other methods are usually only used to disable AA.)_ + +An Antigrain Geometry specific rendering hint to control the quality of antialiasing. Under the hood in Mapnik this method is used in combination with the 'gamma' value (which defaults to 1). The methods are in the AGG source at https://github.com/mapnik/mapnik/blob/master/deps/agg/include/agg_gamma_functions. +* * * + +##### line-dasharray `numbers` + + + +Default Value: none +_(The line will be drawn without dashes.)_ + +A pair of length values [a,b], where (a) is the dash length and (b) is the gap length respectively. More than two values are supported for more complex patterns. +* * * + +##### line-dash-offset `numbers` + + + +Default Value: none +_(The line will be drawn without dashes.)_ + +Valid parameter but not currently used in renderers (only exists for experimental svg support in Mapnik which is not yet enabled). +* * * + +##### line-miterlimit `float` + + + +Default Value: 4 +_(Will auto-convert miters to bevel line joins when theta is less than 29 degrees as per the SVG spec: 'miterLength / stroke-width = 1 / sin ( theta / 2 )'.)_ + +The limit on the ratio of the miter length to the stroke-width. Used to automatically convert miter joins to bevel joins for sharp angles to avoid the miter extending beyond the thickness of the stroking path. Normally will not need to be set, but a larger value can sometimes help avoid jaggy artifacts. +* * * + +##### line-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### line-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify geometries by the given tolerance. +* * * + +##### line-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify geometries by the given algorithm. +* * * + +##### line-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### line-offset `float` + + + +Default Value: 0 +_(Will not be offset.)_ + +Offsets a line a number of pixels parallel to its actual path. Positive values move the line left, negative values move it right (relative to the directionality of the line). +* * * + +##### line-rasterizer `keyword` +`full``fast` + + +Default Value: full +_(The line will be rendered using the highest quality method rather than the fastest.)_ + +Exposes an alternate AGG rendering method that sacrifices some accuracy for speed. +* * * + +##### line-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform line geometry with specified function. +* * * + +##### line-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## markers + +##### marker-file `uri` + + + +Default Value: none +_(An ellipse or circle, if width equals height.)_ + +A file that this marker shows at each placement. If no file is given, the marker will show an ellipse. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### marker-opacity `float` + + + +Default Value: 1 +_(The stroke-opacity and fill-opacity of the marker.)_ + +The overall opacity of the marker, if set, overrides both the opacity of both the fill and stroke. +* * * + +##### marker-fill-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The fill opacity of the marker. +* * * + +##### marker-line-color `color` + + + +Default Value: black +_(The marker will be drawn with a black outline.)_ + +The color of the stroke around the marker. +* * * + +##### marker-line-width `float` + + + +Default Value: 0.5 +_(The marker will be drawn with an outline of .5 pixels wide.)_ + +The width of the stroke around the marker, in pixels. This is positioned on the boundary, so high values can cover the area itself. +* * * + +##### marker-line-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of a line. +* * * + +##### marker-placement `keyword` +`point``line``interior``vertex-first``vertex-last` + + +Default Value: point +_(Place markers at the center point (centroid) of the geometry.)_ + +Attempt to place markers on a point, in the center of a polygon, or if markers-placement:line, then multiple times along a line. 'interior' placement can be used to ensure that points placed on polygons are forced to be inside the polygon interior. The 'vertex-first' and 'vertex-last' options can be used to place markers at the first or last vertex of lines or polygons. +* * * + +##### marker-multi-policy `keyword` +`each``whole``largest` + + +Default Value: each +_(If a feature contains multiple geometries and the placement type is either point or interior then a marker will be rendered for each.)_ + +A special setting to allow the user to control rendering behavior for 'multi-geometries' (when a feature contains multiple geometries). This setting does not apply to markers placed along lines. The 'each' policy is default and means all geometries will get a marker. The 'whole' policy means that the aggregate centroid between all geometries will be used. The 'largest' policy means that only the largest (by bounding box areas) feature will get a rendered marker (this is how text labeling behaves by default). +* * * + +##### marker-type `keyword` +`arrow``ellipse` + + +Default Value: ellipse +_(The marker shape is an ellipse.)_ + +The default marker-type. If a SVG file is not given as the marker-file parameter, the renderer provides either an arrow or an ellipse (a circle if height is equal to width). +* * * + +##### marker-width `float` + + + +Default Value: 10 +_(The marker width is 10 pixels.)_ + +The width of the marker, if using one of the default types. +* * * + +##### marker-height `float` + + + +Default Value: 10 +_(The marker height is 10 pixels.)_ + +The height of the marker, if using one of the default types. +* * * + +##### marker-fill `color` + + + +Default Value: blue +_(The marker fill color is blue.)_ + +The color of the area of the marker. +* * * + +##### marker-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow markers to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping markers are shown or hidden. +* * * + +##### marker-avoid-edges `boolean` + + + +Default Value: false +_(Markers will be potentially placed near tile edges and therefore may look cut off unless they are rendered on each adjacent tile.)_ + +Avoid placing markers that intersect with tile boundaries. +* * * + +##### marker-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache.)_ + +Value to control whether the placement of the feature will prevent the placement of other features. +* * * + +##### marker-spacing `float` + + + +Default Value: 100 +_(In the case of marker-placement:line then draw a marker every 100 pixels along a line.)_ + +Space between repeated markers in pixels. If the spacing is less than the marker size or larger than the line segment length then no marker will be placed. Any value less than 1 will be ignored and the default will be used instead. +* * * + +##### marker-max-error `float` + + + +Default Value: 0.2 +_(N/A: not intended to be changed.)_ + +N/A: not intended to be changed. +* * * + +##### marker-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation.)_ + +Transform marker instance with specified function. Ignores map scale factor. +* * * + +##### marker-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### marker-simplify `float` + + + +Default Value: 0 +_(Geometry will not be simplified.)_ + +geometries are simplified by the given tolerance. +* * * + +##### marker-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +geometries are simplified by the given algorithm. +* * * + +##### marker-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### marker-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform marker geometry with specified function. +* * * + +##### marker-offset `float` + + + +Default Value: 0 +_(Will not be offset.)_ + +Offsets a marker from a line a number of pixels parallel to its actual path. Positive values move the marker left, negative values move it right (relative to the directionality of the line). +* * * + +##### marker-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### marker-direction `keyword` +`auto``auto-down``left``right``left-only``right-only``up``down` + + +Default Value: right +_(Markers are oriented to the right in the line direction.)_ + +How markers should be placed along lines. With the "auto" setting when marker is upside down the marker is automatically rotated by 180 degrees to keep it upright. The "auto-down" value places marker in the opposite orientation to "auto". The "left" or "right" settings can be used to force marker to always be placed along a line in a given direction and therefore disables rotating if marker appears upside down. The "left-only" or "right-only" properties also force a given direction but will discard upside down markers rather than trying to flip it. The "up" and "down" settings don't adjust marker's orientation to the line direction. +* * * + + +## shield + +##### shield-name `string` + + + +Default Value: +_(No text label will be rendered with the shield.)_ + +Value to use for a shield"s text label. Data columns are specified using brackets like [column_name]. +* * * + +##### shield-file `uri` + + + +Default Value: none + + +Image file to render behind the shield text. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### shield-face-name `string` + + + +Default Value: none + + +Font name and style to use for the shield text. +* * * + +##### shield-unlock-image `boolean` + + + +Default Value: false +_(text alignment relative to the shield image uses the center of the image as the anchor for text positioning.)_ + +This parameter should be set to true if you are trying to position text beside rather than on top of the shield image. +* * * + +##### shield-size `float` + + + +Default Value: 10 +_(Font size of 10 will be used to render text.)_ + +The size of the shield text in pixels. +* * * + +##### shield-fill `color` + + + +Default Value: black +_(The shield text will be rendered black.)_ + +The color of the shield text. +* * * + +##### shield-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point +_(One shield will be placed per geometry.)_ + +How this shield should be placed. Point placement places one shield on top of a point geometry and at the centroid of a polygon or the middle point of a line, line places along lines multiple times per feature, vertex places on the vertexes of polygons, and interior attempts to place inside of a polygon. +* * * + +##### shield-avoid-edges `boolean` + + + +Default Value: false +_(Shields will be potentially placed near tile edges and therefore may look cut off unless they are rendered on each adjacent tile.)_ + +Avoid placing shields that intersect with tile boundaries. +* * * + +##### shield-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow shields to overlap with other map elements already placed.)_ + +Control whether overlapping shields are shown or hidden. +* * * + +##### shield-margin `float` + + + +Default Value: 0 +_(No extra margin will be used to determine if a shield collides with any other text, shield, or marker.)_ + +Minimum distance that a shield can be placed from any other text, shield, or marker. +* * * + +##### shield-repeat-distance `float` + + + +Default Value: 0 +_(Shields with the same text will be rendered without restriction.)_ + +Minimum distance between repeated shields. If set this will prevent shields being rendered nearby each other that contain the same text. Similiar to shield-min-distance with the difference that it works the same no matter what placement strategy is used. +* * * + +##### shield-min-distance `float` + + + +Default Value: 0 +_(Shields with the same text will be rendered without restriction.)_ + +Minimum distance to the next shield with the same text. Only works for line placement. +* * * + +##### shield-spacing `float` + + + +Default Value: 0 +_(Only one shield per line will attempt to be placed.)_ + +Distance the renderer should use to try to place repeated shields on a line. +* * * + +##### shield-min-padding `float` + + + +Default Value: 0 +_(No margin will be used to detect if a shield is nearby a tile boundary.)_ + +Minimum distance a shield will be placed from the edge of a tile. This option is similiar to shield-avoid-edges:true except that the extra margin is used to discard cases where the shield+margin are not fully inside the tile. +* * * + +##### shield-label-position-tolerance `float` + + + +Default Value: shield-spacing/2.0 +_(If a shield cannot be placed then the renderer will advance by shield-spacing/2.0 to try placement again.)_ + +Allows the shield to be displaced from its ideal position by a number of pixels (only works with placement:line). +* * * + +##### shield-wrap-width `unsigned` + + + +Default Value: 0 +_(Text will not be wrapped.)_ + +Length of a chunk of text in pixels before wrapping text. If set to zero, text doesn't wrap. +* * * + +##### shield-wrap-before `boolean` + + + +Default Value: false +_(Wrapped lines will be a bit longer than wrap-width.)_ + +Wrap text before wrap-width is reached. +* * * + +##### shield-wrap-character `string` + + + +Default Value: " " +_(Lines will be wrapped when whitespace is encountered.)_ + +Use this character instead of a space to wrap long names. +* * * + +##### shield-halo-fill `color` + + + +Default Value: white +_(The shield halo text will be rendered white.)_ + +Specifies the color of the halo around the text. +* * * + +##### shield-halo-radius `float` + + + +Default Value: 0 +_(no halo.)_ + +Specify the radius of the halo in pixels. +* * * + +##### shield-halo-rasterizer `keyword` +`full``fast` + + +Default Value: full +_(The shield will be rendered using the highest quality method rather than the fastest.)_ + +Exposes an alternate text halo rendering method that sacrifices quality for speed. +* * * + +##### shield-halo-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: +_(No transformation.)_ + +Transform shield halo relative to the actual text with specified function. Allows for shadow or embossed effects. Ignores map scale factor. +* * * + +##### shield-halo-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### shield-halo-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A number from 0 to 1 specifying the opacity for the text halo. +* * * + +##### shield-character-spacing `unsigned` + + + +Default Value: 0 +_(The default character spacing of the font will be used.)_ + +Horizontal spacing between characters (in pixels). Currently works for point placement only, not line placement. +* * * + +##### shield-line-spacing `unsigned` + + + +Default Value: 0 +_(The default font spacing will be used.)_ + +Vertical spacing between lines of multiline labels (in pixels). +* * * + +##### shield-text-dx `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text within shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the shield right. +* * * + +##### shield-text-dy `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text within shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the shield down. +* * * + +##### shield-dx `float` + + + +Default Value: 0 +_(Shield will not be displaced.)_ + +Displace shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right. +* * * + +##### shield-dy `float` + + + +Default Value: 0 +_(Shield will not be displaced.)_ + +Displace shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text down. +* * * + +##### shield-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the image used for the shield. +* * * + +##### shield-text-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the text placed on top of the shield. +* * * + +##### shield-horizontal-alignment `keyword` +`left``middle``right``auto` + + +Default Value: auto +_(TODO.)_ + +The shield's horizontal alignment from its centerpoint. +* * * + +##### shield-vertical-alignment `keyword` +`top``middle``bottom``auto` + + +Default Value: middle +_(TODO.)_ + +The shield's vertical alignment from its centerpoint. +* * * + +##### shield-placement-type `keyword` +`dummy``simple``list` + + +Default Value: dummy +_(Alternative placements will not be enabled.)_ + +Re-position and/or re-size shield to avoid overlaps. "simple" for basic algorithm (using shield-placements string,) "dummy" to turn this feature off. +* * * + +##### shield-placements `string` + + + +Default Value: +_(No alternative placements will be used.)_ + +If "placement-type" is set to "simple", use this "POSITIONS,[SIZES]" string. An example is `shield-placements: "E,NE,SE,W,NW,SW";`. +* * * + +##### shield-text-transform `keyword` +`none``uppercase``lowercase``capitalize``reverse` + + +Default Value: none +_(No text transformation will be applied.)_ + +Transform the case of the characters. +* * * + +##### shield-justify-alignment `keyword` +`left``center``right``auto` + + +Default Value: auto +_(TODO.)_ + +Define how text in a shield's label is justified. +* * * + +##### shield-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation.)_ + +Transform shield instance with specified function. Ignores map scale factor. +* * * + +##### shield-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### shield-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify the geometries used for shield placement by the given tolerance. +* * * + +##### shield-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify the geometries used for shield placement by the given algorithm. +* * * + +##### shield-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out the angles of the geometry used for shield placement. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### shield-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## line-pattern + +##### line-pattern-file `uri` + + + +Default Value: none + + +An image file to be repeated and warped along a line. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### line-pattern-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### line-pattern-opacity `float` + + + +Default Value: 1 +_(The image is rendered without modifications.)_ + +Apply an opacity level to the image used for the pattern. +* * * + +##### line-pattern-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +geometries are simplified by the given tolerance. +* * * + +##### line-pattern-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +geometries are simplified by the given algorithm. +* * * + +##### line-pattern-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### line-pattern-offset `float` + + + +Default Value: 0 +_(The line will not be offset.)_ + +Offsets a line a number of pixels parallel to its actual path. Positive values move the line left, negative values move it right (relative to the directionality of the line). +* * * + +##### line-pattern-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform line geometry with specified function and apply pattern to transformed geometry. +* * * + +##### line-pattern-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## polygon-pattern + +##### polygon-pattern-file `uri` + + + +Default Value: none + + +Image to use as a repeated pattern fill within a polygon. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### polygon-pattern-alignment `keyword` +`global``local` + + +Default Value: global +_(Patterns will be aligned to the map (or tile boundaries) when being repeated across polygons. This is ideal for seamless patterns in tiled rendering.)_ + +Specify whether to align pattern fills to the layer's geometry (local) or to the map (global). +* * * + +##### polygon-pattern-gamma `float` + + + +Default Value: 1 +_(Fully antialiased.)_ +Range: 0-1 +Level of antialiasing of polygon pattern edges. +* * * + +##### polygon-pattern-opacity `float` + + + +Default Value: 1 +_(The image is rendered without modifications.)_ + +Apply an opacity level to the image used for the pattern. +* * * + +##### polygon-pattern-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### polygon-pattern-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +geometries are simplified by the given tolerance. +* * * + +##### polygon-pattern-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +geometries are simplified by the given algorithm. +* * * + +##### polygon-pattern-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### polygon-pattern-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform polygon geometry with specified function and apply pattern to transformed geometry. +* * * + +##### polygon-pattern-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## raster + +##### raster-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the raster symbolizer on top of other symbolizers. +* * * + +##### raster-filter-factor `float` + + + +Default Value: -1 +_(Allow the datasource to choose appropriate downscaling.)_ + +This is used by the Raster or Gdal datasources to pre-downscale images using overviews. Higher numbers can sometimes cause much better scaled image output, at the cost of speed. +* * * + +##### raster-scaling `keyword` +`near``fast``bilinear``bicubic``spline16``spline36``hanning``hamming``hermite``kaiser``quadric``catrom``gaussian``bessel``mitchell``sinc``lanczos``blackman` + + +Default Value: near +_(Nearest neighboor resampling will be used to scale the image to the target size of the map.)_ + +The scaling algorithm used to making different resolution versions of this raster layer. Bilinear is a good compromise between speed and accuracy, while lanczos gives the highest quality. +* * * + +##### raster-mesh-size `unsigned` + + + +Default Value: 16 +_(Reprojection mesh will be 1/16 of the resolution of the source image.)_ + +A reduced resolution mesh is used for raster reprojection, and the total image size is divided by the mesh-size to determine the quality of that mesh. Values for mesh-size larger than the default will result in faster reprojection but might lead to distortion. +* * * + +##### raster-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### raster-colorizer-default-mode `keyword` +`discrete``linear``exact` + + +Default Value: linear +_(A linear interpolation is used to generate colors between the two nearest stops.)_ + +This can be either `discrete`, `linear` or `exact`. If it is not specified then the default is `linear`. +* * * + +##### raster-colorizer-default-color `color` + + + +Default Value: transparent +_(Pixels that are not colored by the colorizer stops will be transparent.)_ + +This can be any color. Sets the color that is applied to all values outside of the range of the colorizer-stops. If not supplied pixels will be fully transparent. +* * * + +##### raster-colorizer-epsilon `float` + + + +Default Value: 1.1920928955078125e-07 +_(Pixels must very closely match the stop filter otherwise they will not be colored.)_ + +This can be any positive floating point value and will be used as a tolerance in floating point comparisions. The higher the value the more likely a stop will match and color data. +* * * + +##### raster-colorizer-stops `tags` + + + +Default Value: +_(No colorization will happen without supplying stops.)_ + +Assigns raster data values to colors. Stops must be listed in ascending order, and contain at a minimum the value and the associated color. You can also include the color-mode as a third argument, like `stop(100,#fff,exact)`. +* * * + + +## point + +##### point-file `uri` + + + +Default Value: none +_(A 4x4 black square will be rendered.)_ + +Image file to represent a point. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### point-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow points to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping points are shown or hidden. +* * * + +##### point-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache.)_ + +Control whether the placement of the feature will prevent the placement of other features. +* * * + +##### point-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A value from 0 to 1 to control the opacity of the point. +* * * + +##### point-placement `keyword` +`centroid``interior` + + +Default Value: centroid +_(The centroid of the geometry will be used to place the point.)_ + +Control how this point should be placed. Centroid calculates the geometric center of a polygon, which can be outside of it, while interior always places inside of a polygon. +* * * + +##### point-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation.)_ + +Transform point instance with specified function. Ignores map scale factor. +* * * + +##### point-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## text + +##### text-name `string` + + + +Default Value: none + + +Value to use for a text label. Data columns are specified using brackets like [column_name]. +* * * + +##### text-face-name `string` + + + +Default Value: none + + +Font name and style to render a label in. +* * * + +##### text-size `float` + + + +Default Value: 10 +_(Font size of 10 will be used to render text.)_ + +Text size in pixels. +* * * + +##### text-ratio `unsigned` + + + +Default Value: 0 +_(TODO.)_ + +Define the amount of text (of the total) present on successive lines when wrapping occurs. +* * * + +##### text-wrap-width `unsigned` + + + +Default Value: 0 +_(Text will not be wrapped.)_ + +Length of a chunk of text in pixels before wrapping text. If set to zero, text doesn't wrap. +* * * + +##### text-wrap-before `boolean` + + + +Default Value: false +_(Wrapped lines will be a bit longer than wrap-width.)_ + +Wrap text before wrap-width is reached. +* * * + +##### text-wrap-character `string` + + + +Default Value: " " +_(Lines will be wrapped when whitespace is encountered.)_ + +Use this character instead of a space to wrap long text. +* * * + +##### text-repeat-wrap-character `boolean` + + + +Default Value: false +_(Character will be removed when used to wrap a line.)_ + +Keep the character used to wrap a line instead of removing it, and repeat it on the new line. +* * * + +##### text-spacing `unsigned` + + + +Default Value: 0 +_(Only one label per line will attempt to be placed.)_ + +Distance the renderer should use to try to place repeated text labels on a line. +* * * + +##### text-character-spacing `float` + + + +Default Value: 0 +_(The default character spacing of the font will be used.)_ + +Horizontal spacing adjustment between characters in pixels. This value is ignored when `horizontal-alignment` is set to `adjust`. Typographic ligatures are turned off when this value is greater than zero. +* * * + +##### text-line-spacing `unsigned` + + + +Default Value: 0 +_(The default font spacing will be used.)_ + +Vertical spacing adjustment between lines in pixels. +* * * + +##### text-label-position-tolerance `float` + + + +Default Value: text-spacing/2.0 +_(If a shield cannot be placed then the renderer will advance by text-spacing/2.0 to try placement again.)_ + +Allows the label to be displaced from its ideal position by a number of pixels (only works with placement:line). +* * * + +##### text-max-char-angle-delta `float` + + + +Default Value: 22.5 +_(The label will not be placed if a character falls on a line with an angle sharper than 22.5 degrees.)_ + +The maximum angle change, in degrees, allowed between adjacent characters in a label. This value internally is converted to radians to the default is 22.5*math.pi/180.0. The higher the value the fewer labels will be placed around around sharp corners. +* * * + +##### text-fill `color` + + + +Default Value: black +_(The text will be rendered black.)_ + +Specifies the color for the text. +* * * + +##### text-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A number from 0 to 1 specifying the opacity for the text. +* * * + +##### text-halo-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A number from 0 to 1 specifying the opacity for the text halo. +* * * + +##### text-halo-fill `color` + + + +Default Value: white +_(The halo will be rendered white.)_ + +Specifies the color of the halo around the text. +* * * + +##### text-halo-radius `float` + + + +Default Value: 0 +_(no halo.)_ + +Specify the radius of the halo in pixels. +* * * + +##### text-halo-rasterizer `keyword` +`full``fast` + + +Default Value: full +_(The text will be rendered using the highest quality method rather than the fastest.)_ + +Exposes an alternate text halo rendering method that sacrifices quality for speed. +* * * + +##### text-halo-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: +_(No transformation.)_ + +Transform text halo relative to the actual text with specified function. Allows for shadow or embossed effects. Ignores map scale factor. +* * * + +##### text-dx `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text by fixed amount, in pixels, +/- along the X axis. With "dummy" placement-type, a positive value displaces to the right. With "simple" placement-type, it is either left, right or unchanged, depending on the placement selected. Any non-zero value implies "horizontal-alignment" changes to "left" by default. Has no effect with 'line' text-placement-type. +* * * + +##### text-dy `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text by fixed amount, in pixels, +/- along the Y axis. With "dummy" placement-type, a positive value displaces downwards. With "simple" placement-type, it is either up, down or unchanged, depending on the placement selected. With "line" placement-type, a positive value displaces above the path. +* * * + +##### text-vertical-alignment `keyword` +`top``middle``bottom``auto` + + +Default Value: auto +_(Default affected by value of dy; "top" for dy>0, "bottom" for dy<0.)_ + +Position of label relative to point position. +* * * + +##### text-avoid-edges `boolean` + + + +Default Value: false +_(Text will be potentially placed near tile edges and therefore may look cut off unless the same text label is rendered on each adjacent tile.)_ + +Avoid placing labels that intersect with tile boundaries. +* * * + +##### text-margin `float` + + + +Default Value: 0 +_(No extra margin will be used to determine if a label collides with any other text, shield, or marker.)_ + +Minimum distance that a label can be placed from any other text, shield, or marker. +* * * + +##### text-repeat-distance `float` + + + +Default Value: 0 +_(Labels with the same text will be rendered without restriction.)_ + +Minimum distance between repeated text. If set this will prevent text labels being rendered nearby each other that contain the same text. Similiar to text-min-distance with the difference that it works the same no matter what placement strategy is used. +* * * + +##### text-min-distance `float` + + + +Default Value: 0 +_(Labels with the same text will be rendered without restriction.)_ + +Minimum distance to the next label with the same text. Only works for line placement. Deprecated: replaced by `text-repeat-distance` and `text-margin` +* * * + +##### text-min-padding `float` + + + +Default Value: 0 +_(No margin will be used to detect if a text label is nearby a tile boundary.)_ + +Minimum distance a text label will be placed from the edge of a tile. This option is similiar to shield-avoid-edges:true except that the extra margin is used to discard cases where the shield+margin are not fully inside the tile. +* * * + +##### text-min-path-length `float` + + + +Default Value: 0 +_(place labels on all geometries no matter how small they are.)_ + +Place labels only on polygons and lines with a bounding width longer than this value (in pixels). +* * * + +##### text-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow text to overlap with other text - overlapping markers will not be shown.)_ + +Control whether overlapping text is shown or hidden. +* * * + +##### text-orientation `float` + + + +Default Value: 0 +_(Text is not rotated and is displayed upright.)_ + +Rotate the text. (only works with text-placement:point). +* * * + +##### text-rotate-displacement `boolean` + + + +Default Value: false +_(Label center is used for rotation.)_ + +Rotates the displacement around the placement origin by the angle given by "orientation". +* * * + +##### text-upright `keyword` +`auto``auto-down``left``right``left-only``right-only` + + +Default Value: auto +_(Text will be positioned upright automatically.)_ + +How this label should be placed along lines. By default when more than half of a label's characters are upside down the label is automatically flipped to keep it upright. By changing this parameter you can prevent this "auto-upright" behavior. The "auto-down" value places text in the opposite orientation to "auto". The "left" or "right" settings can be used to force text to always be placed along a line in a given direction and therefore disables flipping if text appears upside down. The "left-only" or "right-only" properties also force a given direction but will discard upside down text rather than trying to flip it. +* * * + +##### text-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point +_(One shield will be placed per geometry.)_ + +How this label should be placed. Point placement places one label on top of a point geometry and at the centroid of a polygon or the middle point of a line, line places along lines multiple times per feature, vertex places on the vertexes of polygons, and interior attempts to place inside of a polygon. +* * * + +##### text-placement-type `keyword` +`dummy``simple``list` + + +Default Value: dummy +_(Alternative placements will not be enabled.)_ + +Re-position and/or re-size text to avoid overlaps. "simple" for basic algorithm (using text-placements string,) "dummy" to turn this feature off. +* * * + +##### text-placements `string` + + + +Default Value: +_(No alternative placements will be used.)_ + +If "placement-type" is set to "simple", use this "POSITIONS,[SIZES]" string. An example is `text-placements: "E,NE,SE,W,NW,SW";`. +* * * + +##### text-transform `keyword` +`none``uppercase``lowercase``capitalize``reverse` + + +Default Value: none +_(Transform text instance with specified function. Ignores map scale factor.)_ + +Transform the case of the characters. +* * * + +##### text-horizontal-alignment `keyword` +`left``middle``right``auto``adjust` + + +Default Value: auto +_(TODO.)_ + +The text's horizontal alignment from it's centerpoint. If `placement` is set to `line`, then `adjust` can be set to auto-fit the text to the length of the path by dynamically calculating `character-spacing`. +* * * + +##### text-align `keyword` +`left``right``center``auto` + + +Default Value: auto +_(Auto alignment means that text will be centered by default except when using the `placement-type` parameter - in that case either right or left justification will be used automatically depending on where the text could be fit given the `text-placements` directives.)_ + +Define how text is justified. +* * * + +##### text-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### text-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify the geometries used for text placement by the given tolerance. +* * * + +##### text-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify the geometries used for text placement by the given algorithm. +* * * + +##### text-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out the angles of the geometry used for text placement. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### text-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### text-halo-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### text-font-feature-settings `string` + + + +Default Value: +_(Default set of typographic features recommended by OpenType specification. Ligatures are turned off by default when `character-spacing` is greater than zero.)_ + +Comma separated list of OpenType typographic features. The syntax and semantics conforms to `font-feature-settings` from W3C CSS. +* * * + +##### text-largest-bbox-only `boolean` + + + +Default Value: true +_(For multipolygons only polygon with largest bbox area is labeled (does not apply to other geometries).)_ + +Controls default labeling behavior on multipolygons. The default is true and means that only the polygon with largest bbox is labeled. +* * * + + +## building + +##### building-fill `color` + + + +Default Value: The color gray will be used for fill. +_(Gray and fully opaque (alpha = 1), same as rgb(128,128,128) or rgba(128,128,128,1).)_ + +The color of the buildings fill. Note: 0.8 will be used to multiply each color component to auto-generate a darkened wall color. +* * * + +##### building-fill-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the building as a whole, including all walls. +* * * + +##### building-height `float` + + + +Default Value: 0 +_(Buildings will not have a visual height and will instead look like flat polygons.)_ + +The height of the building in pixels. +* * * + + +## debug + +##### debug-mode `string` + + + +Default Value: collision +_(The otherwise invisible collision boxes will be rendered as squares on the map.)_ + +The mode for debug rendering. +* * * + + +## dot + +##### dot-fill `color` + + + +Default Value: gray +_(The dot fill color is gray.)_ + +The color of the area of the dot. +* * * + +##### dot-opacity `float` + + + +Default Value: 1 +_(The opacity of the dot.)_ + +The overall opacity of the dot. +* * * + +##### dot-width `float` + + + +Default Value: 1 +_(The marker width is 1 pixel.)_ + +The width of the dot in pixels. +* * * + +##### dot-height `float` + + + +Default Value: 1 +_(The marker height is 1 pixels.)_ + +The height of the dot in pixels. +* * * + +##### dot-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current layer on top of other layers.)_ + +Composite operation. This defines how this layer should behave relative to layers atop or below it. +* * * + + + + +### Values + +Below is a list of values and an explanation of any expression that can be applied to properties in CartCSS. + +### Color + +CartoCSS accepts a variety of syntaxes for colors - HTML-style hex values, rgb, rgba, hsl, hsla, husl, and husla. It also supports the predefined HTML colors names, like `yellow` and `blue`. + +``` css +#line { +line-color: #ff0; +line-color: #ffff00; +line-color: rgb(255, 255, 0); +line-color: rgba(255, 255, 0, 1); +line-color: hsl(100, 50%, 50%); +line-color: hsla(100, 50%, 50%, 1); +line-color: husl(100, 50%, 50%); // same values yield different color than HSL +line-color: husla(100, 50%, 50%, 1); +line-color: yellow; +} +``` + +Especially of note is the support for hsl and husl, which can be [easier to reason about than rgb()](http://mothereffinghsl.com/). Carto also includes several color operation functions [borrowed from less](http://lesscss.org/functions/#color-operations): + +``` css +// lighten and darken colors +lighten(#ace, 10%); +darken(#ace, 10%); + +// saturate and desaturate +saturate(#550000, 10%); +desaturate(#00ff00, 10%); + +// increase or decrease the opacity of a color +fadein(#fafafa, 10%); +fadeout(#fefefe, 14%); + +// spin rotates a color around the color wheel by degrees +spin(#ff00ff, 10); + +// mix generates a color in between two other colors. +mix(#fff, #000, 50%); + +// get color components +hue(#ff00ff); +saturation(#ff00ff); +lightness(#ff00ff); +alpha(hsla(100, 50%, 50%, 0.5)); +``` + +These functions all take arguments which can be color variables, literal colors, or the results of other functions operating on colors. All the above mentioned functions also come in +a `functionp`-variant (e.g. `lightenp`), which force a given color into perceptual color space. + +### Float + +Float is a fancy way of saying 'number'. In CartoCSS, you specify _just a number_ - unlike CSS, there are no units, but everything is specified in pixels. + +``` css +#line { +line-width: 2; +} +``` + +It's also possible to do simple math with number values: + +``` css +#line { +line-width: 4 / 2; // division +line-width: 4 + 2; // addition +line-width: 4 - 2; // subtraction +line-width: 4 * 2; // multiplication +line-width: 4 % 2; // modulus +} +``` + +### URI + +URI is a fancy way of saying URL. When an argument is a URI, you use the same kind of `url('place.png')` notation that you would with HTML. Quotes around the URL aren't required, but are highly recommended. URIs can be paths to places on your computer, or on the internet. + +```css +#markers { +marker-file: url('marker.png'); +} +``` + +### String + +A string is basically just text. In the case of CartoCSS, you're going to put it in quotes. Strings can be anything, though pay attention to the cases of `text-name` and `shield-name` - they actually will refer to features, which you refer to by putting them in brackets, as seen in the example below. + +```css +#labels { +text-name: "[MY_FIELD]"; +} +``` + +### Boolean + +Boolean means yes or no, so it accepts the values `true` or `false`. + +```css +#markers { +marker-allow-overlap:true; +} +``` + +### Expressions + +Expressions are statements that can include fields, numbers, and other types in a really flexible way. You have run into expressions before, in the realm of 'fields', where you'd specify `"[FIELD]"`, but expressions allow you to drop the quotes and also do quick addition, division, multiplication, and concatenation from within Carto syntax. + +```css +#buildings { +building-height: [HEIGHT_FIELD] * 10; +} +``` + +### Numbers +Numbers are comma-separated lists of one or more number in a specific order. They're used in line dash arrays, in which the numbers specify intervals of line, break, and line again. + +```css +#disputedboundary { +line-dasharray: 1, 4, 2; +} +``` + +### Percentages +In Carto, the percentage symbol, `%` universally means `value/100`. It's meant to be used with ratio-related properties, like opacity rules. + +_You should not use percentages as widths, heights, or other properties - unlike CSS, percentages are not relative to cascaded classes or page size, they're, as stated, simply the value divided by one hundred._ + +```css +#world { +// this syntax +polygon-opacity: 50%; + +// is equivalent to +polygon-opacity: 0.5; +} +``` + +### Functions + +Functions are comma-separated lists of one or more functions. For instance, transforms use the `functions` type to allow for transforms within Carto, which are optionally chainable. + +```css +#point { +point-transform: scale(2, 2); +} +``` diff --git a/docs/latest.md b/docs/latest.md new file mode 100644 index 0000000..ad7ed30 --- /dev/null +++ b/docs/latest.md @@ -0,0 +1,2226 @@ +# Carto documentation + +The following is a list of properties provided in CartoCSS that you can apply to map elements. + +## All elements + +##### image-filters `functions` + +`agg-stack-blur``emboss``blur``gray``sobel``edge-detect``x-gradient``y-gradient``invert``sharpen``color-blind-protanope``color-blind-deuteranope``color-blind-tritanope``colorize-alpha``color-to-alpha``scale-hsla` + +Default Value: none +_(no filters.)_ + +A list of image filters that will be applied to the active rendering canvas for a given style. The presence of one more `image-filters` will trigger a new canvas to be created before starting to render a style and then this canvas will be composited back into the main canvas after rendering all features and after all `image-filters` have been applied. See `direct-image-filters` if you want to apply a filter directly to the main canvas. +* * * + +##### image-filters-inflate `boolean` + + + +Default Value: false +_(No special handling will be done and image filters that blur data will only blur up to the edge of a tile boundary.)_ + +A property that can be set to true to enable using an inflated image internally for seamless blurring across tiles (requires buffered data). +* * * + +##### direct-image-filters `functions` + +`agg-stack-blur``emboss``blur``gray``sobel``edge-detect``x-gradient``y-gradient``invert``sharpen``color-blind-protanope``color-blind-deuteranope``color-blind-tritanope``colorize-alpha``color-to-alpha``scale-hsla` + +Default Value: none +_(no filters.)_ + +A list of image filters to apply to the main canvas (see the `image-filters` doc for how they work on a separate canvas). +* * * + +##### comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current layer on top of other layers.)_ + +Composite operation. This defines how this layer should behave relative to layers atop or below it. +* * * + +##### opacity `float` + + + +Default Value: 1 +_(No separate buffer will be used and no alpha will be applied to the style after rendering.)_ + +An alpha value for the style (which means an alpha applied to all features in separate buffer and then composited back to main buffer). +* * * + + +## map + +##### background-color `color` + + + +Default Value: none +_(Will be rendered transparent.)_ + +Map Background color. +* * * + +##### background-image `uri` + + + +Default Value: +_(No background image will be used.)_ + +An image that is repeated below all features on a map as a background. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### background-image-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(The background-image will be blended with the background normally (placed on top of any existing background-color).)_ + +Set the compositing operation used to blend the image into the background. +* * * + +##### background-image-opacity `float` + + + +Default Value: 1 +_(The image opacity will not be changed when applied to the map background.)_ + +Set the opacity of the image. +* * * + +##### srs `string` + + + +Default Value: +proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs +_(The proj4 literal of EPSG:4326 is assumed to be the Map's spatial reference and all data from layers within this map will be plotted using this coordinate system. If any layers do not declare an srs value then they will be assumed to be in the same srs as the Map and not transformations will be needed to plot them in the Map's coordinate space.)_ + +Map spatial reference (proj4 string). +* * * + +##### buffer-size `float` + + + +Default Value: 0 +_(No buffer will be used.)_ + +Extra tolerance around the map (in pixels) used to ensure labels crossing tile boundaries are equally rendered in each tile (e.g. cut in each tile). Not intended to be used in combination with "avoid-edges". +* * * + +##### maximum-extent `string` + + + +Default Value: -20037508.34,-20037508.34,20037508.34,20037508.34 +_(All data will be clipped to global mercator extent (default is applied in Carto.js).)_ + +An extent to be used to limit the bounds used to query all layers during rendering. Should be minx, miny, maxx, maxy in the coordinates of the Map. +* * * + +##### base `string` + + + +Default Value: +_(This base path defaults to an empty string meaning that any relative paths to files referenced in styles or layers will be interpreted relative to the application process.)_ + +Any relative paths used to reference files will be understood as relative to this directory path if the map is loaded from an in memory object rather than from the filesystem. If the map is loaded from the filesystem and this option is not provided it will be set to the directory of the stylesheet. +* * * + +##### font-directory `uri` + + + +Default Value: none +_(No map-specific fonts will be registered.)_ + +Path to a directory which holds fonts which should be registered when the Map is loaded (in addition to any fonts that may be automatically registered). +* * * + + +## polygon + +##### polygon-fill `color` + + + +Default Value: The color gray will be used for fill. +_(Gray and fully opaque (alpha = 1), same as rgb(128,128,128) or rgba(128,128,128,1).)_ + +Fill color to assign to a polygon. +* * * + +##### polygon-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the polygon. +* * * + +##### polygon-gamma `float` + + + +Default Value: 1 +_(Fully antialiased.)_ +Range: 0-1 +Level of antialiasing of polygon edges. +* * * + +##### polygon-gamma-method `keyword` +`power``linear``none``threshold``multiply` + + +Default Value: power +_(pow(x,gamma) is used to calculate pixel gamma, which produces slightly smoother line and polygon antialiasing than the 'linear' method, while other methods are usually only used to disable AA.)_ + +An Antigrain Geometry specific rendering hint to control the quality of antialiasing. Under the hood in Mapnik this method is used in combination with the 'gamma' value (which defaults to 1). The methods are in the AGG source at https://github.com/mapnik/mapnik/blob/master/deps/agg/include/agg_gamma_functions. +* * * + +##### polygon-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extend outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### polygon-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify geometries by the given tolerance. +* * * + +##### polygon-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify geometries by the given algorithm. +* * * + +##### polygon-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### polygon-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform polygon geometry with specified function. +* * * + +##### polygon-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## line + +##### line-color `color` + + + +Default Value: black +_(black and fully opaque (alpha = 1), same as rgb(0,0,0) or rgba(0,0,0,1).)_ + +The color of a drawn line. +* * * + +##### line-width `float` + + + +Default Value: 1 +_(The line will be rendered 1 pixel wide.)_ + +The width of a line in pixels. +* * * + +##### line-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of a line. +* * * + +##### line-join `keyword` +`miter``miter-revert``round``bevel` + + +Default Value: miter +_(The line joins will be rendered using a miter look.)_ + +The behavior of lines when joining. +* * * + +##### line-cap `keyword` +`butt``round``square` + + +Default Value: butt +_(The line endings will be rendered using a butt look.)_ + +The display of line endings. +* * * + +##### line-gamma `float` + + + +Default Value: 1 +_(Fully antialiased.)_ +Range: 0-1 +Level of antialiasing of stroke line. +* * * + +##### line-gamma-method `keyword` +`power``linear``none``threshold``multiply` + + +Default Value: power +_(pow(x,gamma) is used to calculate pixel gamma, which produces slightly smoother line and polygon antialiasing than the 'linear' method, while other methods are usually only used to disable AA.)_ + +An Antigrain Geometry specific rendering hint to control the quality of antialiasing. Under the hood in Mapnik this method is used in combination with the 'gamma' value (which defaults to 1). The methods are in the AGG source at https://github.com/mapnik/mapnik/blob/master/deps/agg/include/agg_gamma_functions. +* * * + +##### line-dasharray `numbers` + + + +Default Value: none +_(The line will be drawn without dashes.)_ + +A pair of length values [a,b], where (a) is the dash length and (b) is the gap length respectively. More than two values are supported for more complex patterns. +* * * + +##### line-dash-offset `numbers` + + + +Default Value: none +_(The line will be drawn without dashes.)_ + +Valid parameter but not currently used in renderers (only exists for experimental svg support in Mapnik which is not yet enabled). +* * * + +##### line-miterlimit `float` + + + +Default Value: 4 +_(Will auto-convert miters to bevel line joins when theta is less than 29 degrees as per the SVG spec: 'miterLength / stroke-width = 1 / sin ( theta / 2 )'.)_ + +The limit on the ratio of the miter length to the stroke-width. Used to automatically convert miter joins to bevel joins for sharp angles to avoid the miter extending beyond the thickness of the stroking path. Normally will not need to be set, but a larger value can sometimes help avoid jaggy artifacts. +* * * + +##### line-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### line-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify geometries by the given tolerance. +* * * + +##### line-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify geometries by the given algorithm. +* * * + +##### line-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### line-offset `float` + + + +Default Value: 0 +_(Will not be offset.)_ + +Offsets a line a number of pixels parallel to its actual path. Positive values move the line left, negative values move it right (relative to the directionality of the line). +* * * + +##### line-rasterizer `keyword` +`full``fast` + + +Default Value: full +_(The line will be rendered using the highest quality method rather than the fastest.)_ + +Exposes an alternate AGG rendering method that sacrifices some accuracy for speed. +* * * + +##### line-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform line geometry with specified function. +* * * + +##### line-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## markers + +##### marker-file `uri` + + + +Default Value: none +_(An ellipse or circle, if width equals height.)_ + +A file that this marker shows at each placement. If no file is given, the marker will show an ellipse. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### marker-opacity `float` + + + +Default Value: 1 +_(The stroke-opacity and fill-opacity of the marker.)_ + +The overall opacity of the marker, if set, overrides both the opacity of both the fill and stroke. +* * * + +##### marker-fill-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The fill opacity of the marker. +* * * + +##### marker-line-color `color` + + + +Default Value: black +_(The marker will be drawn with a black outline.)_ + +The color of the stroke around the marker. +* * * + +##### marker-line-width `float` + + + +Default Value: 0.5 +_(The marker will be drawn with an outline of .5 pixels wide.)_ + +The width of the stroke around the marker, in pixels. This is positioned on the boundary, so high values can cover the area itself. +* * * + +##### marker-line-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of a line. +* * * + +##### marker-placement `keyword` +`point``line``interior``vertex-first``vertex-last` + + +Default Value: point +_(Place markers at the center point (centroid) of the geometry.)_ + +Attempt to place markers on a point, in the center of a polygon, or if markers-placement:line, then multiple times along a line. 'interior' placement can be used to ensure that points placed on polygons are forced to be inside the polygon interior. The 'vertex-first' and 'vertex-last' options can be used to place markers at the first or last vertex of lines or polygons. +* * * + +##### marker-multi-policy `keyword` +`each``whole``largest` + + +Default Value: each +_(If a feature contains multiple geometries and the placement type is either point or interior then a marker will be rendered for each.)_ + +A special setting to allow the user to control rendering behavior for 'multi-geometries' (when a feature contains multiple geometries). This setting does not apply to markers placed along lines. The 'each' policy is default and means all geometries will get a marker. The 'whole' policy means that the aggregate centroid between all geometries will be used. The 'largest' policy means that only the largest (by bounding box areas) feature will get a rendered marker (this is how text labeling behaves by default). +* * * + +##### marker-type `keyword` +`arrow``ellipse` + + +Default Value: ellipse +_(The marker shape is an ellipse.)_ + +The default marker-type. If a SVG file is not given as the marker-file parameter, the renderer provides either an arrow or an ellipse (a circle if height is equal to width). +* * * + +##### marker-width `float` + + + +Default Value: 10 +_(The marker width is 10 pixels.)_ + +The width of the marker, if using one of the default types. +* * * + +##### marker-height `float` + + + +Default Value: 10 +_(The marker height is 10 pixels.)_ + +The height of the marker, if using one of the default types. +* * * + +##### marker-fill `color` + + + +Default Value: blue +_(The marker fill color is blue.)_ + +The color of the area of the marker. +* * * + +##### marker-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow markers to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping markers are shown or hidden. +* * * + +##### marker-avoid-edges `boolean` + + + +Default Value: false +_(Markers will be potentially placed near tile edges and therefore may look cut off unless they are rendered on each adjacent tile.)_ + +Avoid placing markers that intersect with tile boundaries. +* * * + +##### marker-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache.)_ + +Value to control whether the placement of the feature will prevent the placement of other features. +* * * + +##### marker-spacing `float` + + + +Default Value: 100 +_(In the case of marker-placement:line then draw a marker every 100 pixels along a line.)_ + +Space between repeated markers in pixels. If the spacing is less than the marker size or larger than the line segment length then no marker will be placed. Any value less than 1 will be ignored and the default will be used instead. +* * * + +##### marker-max-error `float` + + + +Default Value: 0.2 +_(N/A: not intended to be changed.)_ + +N/A: not intended to be changed. +* * * + +##### marker-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation.)_ + +Transform marker instance with specified function. Ignores map scale factor. +* * * + +##### marker-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### marker-simplify `float` + + + +Default Value: 0 +_(Geometry will not be simplified.)_ + +geometries are simplified by the given tolerance. +* * * + +##### marker-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +geometries are simplified by the given algorithm. +* * * + +##### marker-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### marker-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform marker geometry with specified function. +* * * + +##### marker-offset `float` + + + +Default Value: 0 +_(Will not be offset.)_ + +Offsets a marker from a line a number of pixels parallel to its actual path. Positive values move the marker left, negative values move it right (relative to the directionality of the line). +* * * + +##### marker-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### marker-direction `keyword` +`auto``auto-down``left``right``left-only``right-only``up``down` + + +Default Value: right +_(Markers are oriented to the right in the line direction.)_ + +How markers should be placed along lines. With the "auto" setting when marker is upside down the marker is automatically rotated by 180 degrees to keep it upright. The "auto-down" value places marker in the opposite orientation to "auto". The "left" or "right" settings can be used to force marker to always be placed along a line in a given direction and therefore disables rotating if marker appears upside down. The "left-only" or "right-only" properties also force a given direction but will discard upside down markers rather than trying to flip it. The "up" and "down" settings don't adjust marker's orientation to the line direction. +* * * + + +## shield + +##### shield-name `string` + + + +Default Value: +_(No text label will be rendered with the shield.)_ + +Value to use for a shield"s text label. Data columns are specified using brackets like [column_name]. +* * * + +##### shield-file `uri` + + + +Default Value: none + + +Image file to render behind the shield text. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### shield-face-name `string` + + + +Default Value: none + + +Font name and style to use for the shield text. +* * * + +##### shield-unlock-image `boolean` + + + +Default Value: false +_(text alignment relative to the shield image uses the center of the image as the anchor for text positioning.)_ + +This parameter should be set to true if you are trying to position text beside rather than on top of the shield image. +* * * + +##### shield-size `float` + + + +Default Value: 10 +_(Font size of 10 will be used to render text.)_ + +The size of the shield text in pixels. +* * * + +##### shield-fill `color` + + + +Default Value: black +_(The shield text will be rendered black.)_ + +The color of the shield text. +* * * + +##### shield-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point +_(One shield will be placed per geometry.)_ + +How this shield should be placed. Point placement places one shield on top of a point geometry and at the centroid of a polygon or the middle point of a line, line places along lines multiple times per feature, vertex places on the vertexes of polygons, and interior attempts to place inside of a polygon. +* * * + +##### shield-avoid-edges `boolean` + + + +Default Value: false +_(Shields will be potentially placed near tile edges and therefore may look cut off unless they are rendered on each adjacent tile.)_ + +Avoid placing shields that intersect with tile boundaries. +* * * + +##### shield-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow shields to overlap with other map elements already placed.)_ + +Control whether overlapping shields are shown or hidden. +* * * + +##### shield-margin `float` + + + +Default Value: 0 +_(No extra margin will be used to determine if a shield collides with any other text, shield, or marker.)_ + +Minimum distance that a shield can be placed from any other text, shield, or marker. +* * * + +##### shield-repeat-distance `float` + + + +Default Value: 0 +_(Shields with the same text will be rendered without restriction.)_ + +Minimum distance between repeated shields. If set this will prevent shields being rendered nearby each other that contain the same text. Similiar to shield-min-distance with the difference that it works the same no matter what placement strategy is used. +* * * + +##### shield-min-distance `float` + + + +Default Value: 0 +_(Shields with the same text will be rendered without restriction.)_ + +Minimum distance to the next shield with the same text. Only works for line placement. +* * * + +##### shield-spacing `float` + + + +Default Value: 0 +_(Only one shield per line will attempt to be placed.)_ + +Distance the renderer should use to try to place repeated shields on a line. +* * * + +##### shield-min-padding `float` + + + +Default Value: 0 +_(No margin will be used to detect if a shield is nearby a tile boundary.)_ + +Minimum distance a shield will be placed from the edge of a tile. This option is similiar to shield-avoid-edges:true except that the extra margin is used to discard cases where the shield+margin are not fully inside the tile. +* * * + +##### shield-label-position-tolerance `float` + + + +Default Value: shield-spacing/2.0 +_(If a shield cannot be placed then the renderer will advance by shield-spacing/2.0 to try placement again.)_ + +Allows the shield to be displaced from its ideal position by a number of pixels (only works with placement:line). +* * * + +##### shield-wrap-width `unsigned` + + + +Default Value: 0 +_(Text will not be wrapped.)_ + +Length of a chunk of text in pixels before wrapping text. If set to zero, text doesn't wrap. +* * * + +##### shield-wrap-before `boolean` + + + +Default Value: false +_(Wrapped lines will be a bit longer than wrap-width.)_ + +Wrap text before wrap-width is reached. +* * * + +##### shield-wrap-character `string` + + + +Default Value: " " +_(Lines will be wrapped when whitespace is encountered.)_ + +Use this character instead of a space to wrap long names. +* * * + +##### shield-halo-fill `color` + + + +Default Value: white +_(The shield halo text will be rendered white.)_ + +Specifies the color of the halo around the text. +* * * + +##### shield-halo-radius `float` + + + +Default Value: 0 +_(no halo.)_ + +Specify the radius of the halo in pixels. +* * * + +##### shield-halo-rasterizer `keyword` +`full``fast` + + +Default Value: full +_(The shield will be rendered using the highest quality method rather than the fastest.)_ + +Exposes an alternate text halo rendering method that sacrifices quality for speed. +* * * + +##### shield-halo-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: +_(No transformation.)_ + +Transform shield halo relative to the actual text with specified function. Allows for shadow or embossed effects. Ignores map scale factor. +* * * + +##### shield-halo-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### shield-halo-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A number from 0 to 1 specifying the opacity for the text halo. +* * * + +##### shield-character-spacing `unsigned` + + + +Default Value: 0 +_(The default character spacing of the font will be used.)_ + +Horizontal spacing between characters (in pixels). Currently works for point placement only, not line placement. +* * * + +##### shield-line-spacing `unsigned` + + + +Default Value: 0 +_(The default font spacing will be used.)_ + +Vertical spacing between lines of multiline labels (in pixels). +* * * + +##### shield-text-dx `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text within shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the shield right. +* * * + +##### shield-text-dy `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text within shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the shield down. +* * * + +##### shield-dx `float` + + + +Default Value: 0 +_(Shield will not be displaced.)_ + +Displace shield by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right. +* * * + +##### shield-dy `float` + + + +Default Value: 0 +_(Shield will not be displaced.)_ + +Displace shield by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text down. +* * * + +##### shield-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the image used for the shield. +* * * + +##### shield-text-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the text placed on top of the shield. +* * * + +##### shield-horizontal-alignment `keyword` +`left``middle``right``auto` + + +Default Value: auto +_(TODO.)_ + +The shield's horizontal alignment from its centerpoint. +* * * + +##### shield-vertical-alignment `keyword` +`top``middle``bottom``auto` + + +Default Value: middle +_(TODO.)_ + +The shield's vertical alignment from its centerpoint. +* * * + +##### shield-placement-type `keyword` +`dummy``simple``list` + + +Default Value: dummy +_(Alternative placements will not be enabled.)_ + +Re-position and/or re-size shield to avoid overlaps. "simple" for basic algorithm (using shield-placements string,) "dummy" to turn this feature off. +* * * + +##### shield-placements `string` + + + +Default Value: +_(No alternative placements will be used.)_ + +If "placement-type" is set to "simple", use this "POSITIONS,[SIZES]" string. An example is `shield-placements: "E,NE,SE,W,NW,SW";`. +* * * + +##### shield-text-transform `keyword` +`none``uppercase``lowercase``capitalize``reverse` + + +Default Value: none +_(No text transformation will be applied.)_ + +Transform the case of the characters. +* * * + +##### shield-justify-alignment `keyword` +`left``center``right``auto` + + +Default Value: auto +_(TODO.)_ + +Define how text in a shield's label is justified. +* * * + +##### shield-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation.)_ + +Transform shield instance with specified function. Ignores map scale factor. +* * * + +##### shield-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### shield-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify the geometries used for shield placement by the given tolerance. +* * * + +##### shield-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify the geometries used for shield placement by the given algorithm. +* * * + +##### shield-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out the angles of the geometry used for shield placement. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### shield-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## line-pattern + +##### line-pattern-file `uri` + + + +Default Value: none + + +An image file to be repeated and warped along a line. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### line-pattern-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### line-pattern-opacity `float` + + + +Default Value: 1 +_(The image is rendered without modifications.)_ + +Apply an opacity level to the image used for the pattern. +* * * + +##### line-pattern-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +geometries are simplified by the given tolerance. +* * * + +##### line-pattern-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +geometries are simplified by the given algorithm. +* * * + +##### line-pattern-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### line-pattern-offset `float` + + + +Default Value: 0 +_(The line will not be offset.)_ + +Offsets a line a number of pixels parallel to its actual path. Positive values move the line left, negative values move it right (relative to the directionality of the line). +* * * + +##### line-pattern-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform line geometry with specified function and apply pattern to transformed geometry. +* * * + +##### line-pattern-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## polygon-pattern + +##### polygon-pattern-file `uri` + + + +Default Value: none + + +Image to use as a repeated pattern fill within a polygon. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### polygon-pattern-alignment `keyword` +`global``local` + + +Default Value: global +_(Patterns will be aligned to the map (or tile boundaries) when being repeated across polygons. This is ideal for seamless patterns in tiled rendering.)_ + +Specify whether to align pattern fills to the layer's geometry (local) or to the map (global). +* * * + +##### polygon-pattern-gamma `float` + + + +Default Value: 1 +_(Fully antialiased.)_ +Range: 0-1 +Level of antialiasing of polygon pattern edges. +* * * + +##### polygon-pattern-opacity `float` + + + +Default Value: 1 +_(The image is rendered without modifications.)_ + +Apply an opacity level to the image used for the pattern. +* * * + +##### polygon-pattern-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### polygon-pattern-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +geometries are simplified by the given tolerance. +* * * + +##### polygon-pattern-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +geometries are simplified by the given algorithm. +* * * + +##### polygon-pattern-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out geometry angles. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### polygon-pattern-geometry-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(The geometry will not be transformed.)_ + +Transform polygon geometry with specified function and apply pattern to transformed geometry. +* * * + +##### polygon-pattern-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## raster + +##### raster-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the raster symbolizer on top of other symbolizers. +* * * + +##### raster-filter-factor `float` + + + +Default Value: -1 +_(Allow the datasource to choose appropriate downscaling.)_ + +This is used by the Raster or Gdal datasources to pre-downscale images using overviews. Higher numbers can sometimes cause much better scaled image output, at the cost of speed. +* * * + +##### raster-scaling `keyword` +`near``fast``bilinear``bicubic``spline16``spline36``hanning``hamming``hermite``kaiser``quadric``catrom``gaussian``bessel``mitchell``sinc``lanczos``blackman` + + +Default Value: near +_(Nearest neighboor resampling will be used to scale the image to the target size of the map.)_ + +The scaling algorithm used to making different resolution versions of this raster layer. Bilinear is a good compromise between speed and accuracy, while lanczos gives the highest quality. +* * * + +##### raster-mesh-size `unsigned` + + + +Default Value: 16 +_(Reprojection mesh will be 1/16 of the resolution of the source image.)_ + +A reduced resolution mesh is used for raster reprojection, and the total image size is divided by the mesh-size to determine the quality of that mesh. Values for mesh-size larger than the default will result in faster reprojection but might lead to distortion. +* * * + +##### raster-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### raster-colorizer-default-mode `keyword` +`discrete``linear``exact` + + +Default Value: linear +_(A linear interpolation is used to generate colors between the two nearest stops.)_ + +This can be either `discrete`, `linear` or `exact`. If it is not specified then the default is `linear`. +* * * + +##### raster-colorizer-default-color `color` + + + +Default Value: transparent +_(Pixels that are not colored by the colorizer stops will be transparent.)_ + +This can be any color. Sets the color that is applied to all values outside of the range of the colorizer-stops. If not supplied pixels will be fully transparent. +* * * + +##### raster-colorizer-epsilon `float` + + + +Default Value: 1.1920928955078125e-07 +_(Pixels must very closely match the stop filter otherwise they will not be colored.)_ + +This can be any positive floating point value and will be used as a tolerance in floating point comparisions. The higher the value the more likely a stop will match and color data. +* * * + +##### raster-colorizer-stops `tags` + + + +Default Value: +_(No colorization will happen without supplying stops.)_ + +Assigns raster data values to colors. Stops must be listed in ascending order, and contain at a minimum the value and the associated color. You can also include the color-mode as a third argument, like `stop(100,#fff,exact)`. +* * * + + +## point + +##### point-file `uri` + + + +Default Value: none +_(A 4x4 black square will be rendered.)_ + +Image file to represent a point. Accepted formats: svg, jpg, png, tiff, and webp. +* * * + +##### point-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow points to overlap with each other - overlapping markers will not be shown.)_ + +Control whether overlapping points are shown or hidden. +* * * + +##### point-ignore-placement `boolean` + + + +Default Value: false +_(do not store the bbox of this geometry in the collision detector cache.)_ + +Control whether the placement of the feature will prevent the placement of other features. +* * * + +##### point-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A value from 0 to 1 to control the opacity of the point. +* * * + +##### point-placement `keyword` +`centroid``interior` + + +Default Value: centroid +_(The centroid of the geometry will be used to place the point.)_ + +Control how this point should be placed. Centroid calculates the geometric center of a polygon, which can be outside of it, while interior always places inside of a polygon. +* * * + +##### point-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: none +_(No transformation.)_ + +Transform point instance with specified function. Ignores map scale factor. +* * * + +##### point-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + + +## text + +##### text-name `string` + + + +Default Value: none + + +Value to use for a text label. Data columns are specified using brackets like [column_name]. +* * * + +##### text-face-name `string` + + + +Default Value: none + + +Font name and style to render a label in. +* * * + +##### text-size `float` + + + +Default Value: 10 +_(Font size of 10 will be used to render text.)_ + +Text size in pixels. +* * * + +##### text-ratio `unsigned` + + + +Default Value: 0 +_(TODO.)_ + +Define the amount of text (of the total) present on successive lines when wrapping occurs. +* * * + +##### text-wrap-width `unsigned` + + + +Default Value: 0 +_(Text will not be wrapped.)_ + +Length of a chunk of text in pixels before wrapping text. If set to zero, text doesn't wrap. +* * * + +##### text-wrap-before `boolean` + + + +Default Value: false +_(Wrapped lines will be a bit longer than wrap-width.)_ + +Wrap text before wrap-width is reached. +* * * + +##### text-wrap-character `string` + + + +Default Value: " " +_(Lines will be wrapped when whitespace is encountered.)_ + +Use this character instead of a space to wrap long text. +* * * + +##### text-repeat-wrap-character `boolean` + + + +Default Value: false +_(Character will be removed when used to wrap a line.)_ + +Keep the character used to wrap a line instead of removing it, and repeat it on the new line. +* * * + +##### text-spacing `unsigned` + + + +Default Value: 0 +_(Only one label per line will attempt to be placed.)_ + +Distance the renderer should use to try to place repeated text labels on a line. +* * * + +##### text-character-spacing `float` + + + +Default Value: 0 +_(The default character spacing of the font will be used.)_ + +Horizontal spacing adjustment between characters in pixels. This value is ignored when `horizontal-alignment` is set to `adjust`. Typographic ligatures are turned off when this value is greater than zero. +* * * + +##### text-line-spacing `unsigned` + + + +Default Value: 0 +_(The default font spacing will be used.)_ + +Vertical spacing adjustment between lines in pixels. +* * * + +##### text-label-position-tolerance `float` + + + +Default Value: text-spacing/2.0 +_(If a shield cannot be placed then the renderer will advance by text-spacing/2.0 to try placement again.)_ + +Allows the label to be displaced from its ideal position by a number of pixels (only works with placement:line). +* * * + +##### text-max-char-angle-delta `float` + + + +Default Value: 22.5 +_(The label will not be placed if a character falls on a line with an angle sharper than 22.5 degrees.)_ + +The maximum angle change, in degrees, allowed between adjacent characters in a label. This value internally is converted to radians to the default is 22.5*math.pi/180.0. The higher the value the fewer labels will be placed around around sharp corners. +* * * + +##### text-fill `color` + + + +Default Value: black +_(The text will be rendered black.)_ + +Specifies the color for the text. +* * * + +##### text-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A number from 0 to 1 specifying the opacity for the text. +* * * + +##### text-halo-opacity `float` + + + +Default Value: 1 +_(Fully opaque.)_ + +A number from 0 to 1 specifying the opacity for the text halo. +* * * + +##### text-halo-fill `color` + + + +Default Value: white +_(The halo will be rendered white.)_ + +Specifies the color of the halo around the text. +* * * + +##### text-halo-radius `float` + + + +Default Value: 0 +_(no halo.)_ + +Specify the radius of the halo in pixels. +* * * + +##### text-halo-rasterizer `keyword` +`full``fast` + + +Default Value: full +_(The text will be rendered using the highest quality method rather than the fastest.)_ + +Exposes an alternate text halo rendering method that sacrifices quality for speed. +* * * + +##### text-halo-transform `functions` + +`matrix``translate``scale``rotate``skewX``skewY` + +Default Value: +_(No transformation.)_ + +Transform text halo relative to the actual text with specified function. Allows for shadow or embossed effects. Ignores map scale factor. +* * * + +##### text-dx `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text by fixed amount, in pixels, +/- along the X axis. With "dummy" placement-type, a positive value displaces to the right. With "simple" placement-type, it is either left, right or unchanged, depending on the placement selected. Any non-zero value implies "horizontal-alignment" changes to "left" by default. Has no effect with 'line' text-placement-type. +* * * + +##### text-dy `float` + + + +Default Value: 0 +_(Text will not be displaced.)_ + +Displace text by fixed amount, in pixels, +/- along the Y axis. With "dummy" placement-type, a positive value displaces downwards. With "simple" placement-type, it is either up, down or unchanged, depending on the placement selected. With "line" placement-type, a positive value displaces above the path. +* * * + +##### text-vertical-alignment `keyword` +`top``middle``bottom``auto` + + +Default Value: auto +_(Default affected by value of dy; "top" for dy>0, "bottom" for dy<0.)_ + +Position of label relative to point position. +* * * + +##### text-avoid-edges `boolean` + + + +Default Value: false +_(Text will be potentially placed near tile edges and therefore may look cut off unless the same text label is rendered on each adjacent tile.)_ + +Avoid placing labels that intersect with tile boundaries. +* * * + +##### text-margin `float` + + + +Default Value: 0 +_(No extra margin will be used to determine if a label collides with any other text, shield, or marker.)_ + +Minimum distance that a label can be placed from any other text, shield, or marker. +* * * + +##### text-repeat-distance `float` + + + +Default Value: 0 +_(Labels with the same text will be rendered without restriction.)_ + +Minimum distance between repeated text. If set this will prevent text labels being rendered nearby each other that contain the same text. Similiar to text-min-distance with the difference that it works the same no matter what placement strategy is used. +* * * + +##### text-min-distance `float` + + + +Default Value: 0 +_(Labels with the same text will be rendered without restriction.)_ + +Minimum distance to the next label with the same text. Only works for line placement. Deprecated: replaced by `text-repeat-distance` and `text-margin` +* * * + +##### text-min-padding `float` + + + +Default Value: 0 +_(No margin will be used to detect if a text label is nearby a tile boundary.)_ + +Minimum distance a text label will be placed from the edge of a tile. This option is similiar to shield-avoid-edges:true except that the extra margin is used to discard cases where the shield+margin are not fully inside the tile. +* * * + +##### text-min-path-length `float` + + + +Default Value: 0 +_(place labels on all geometries no matter how small they are.)_ + +Place labels only on polygons and lines with a bounding width longer than this value (in pixels). +* * * + +##### text-allow-overlap `boolean` + + + +Default Value: false +_(Do not allow text to overlap with other text - overlapping markers will not be shown.)_ + +Control whether overlapping text is shown or hidden. +* * * + +##### text-orientation `float` + + + +Default Value: 0 +_(Text is not rotated and is displayed upright.)_ + +Rotate the text. (only works with text-placement:point). +* * * + +##### text-rotate-displacement `boolean` + + + +Default Value: false +_(Label center is used for rotation.)_ + +Rotates the displacement around the placement origin by the angle given by "orientation". +* * * + +##### text-upright `keyword` +`auto``auto-down``left``right``left-only``right-only` + + +Default Value: auto +_(Text will be positioned upright automatically.)_ + +How this label should be placed along lines. By default when more than half of a label's characters are upside down the label is automatically flipped to keep it upright. By changing this parameter you can prevent this "auto-upright" behavior. The "auto-down" value places text in the opposite orientation to "auto". The "left" or "right" settings can be used to force text to always be placed along a line in a given direction and therefore disables flipping if text appears upside down. The "left-only" or "right-only" properties also force a given direction but will discard upside down text rather than trying to flip it. +* * * + +##### text-placement `keyword` +`point``line``vertex``interior` + + +Default Value: point +_(One shield will be placed per geometry.)_ + +How this label should be placed. Point placement places one label on top of a point geometry and at the centroid of a polygon or the middle point of a line, line places along lines multiple times per feature, vertex places on the vertexes of polygons, and interior attempts to place inside of a polygon. +* * * + +##### text-placement-type `keyword` +`dummy``simple``list` + + +Default Value: dummy +_(Alternative placements will not be enabled.)_ + +Re-position and/or re-size text to avoid overlaps. "simple" for basic algorithm (using text-placements string,) "dummy" to turn this feature off. +* * * + +##### text-placements `string` + + + +Default Value: +_(No alternative placements will be used.)_ + +If "placement-type" is set to "simple", use this "POSITIONS,[SIZES]" string. An example is `text-placements: "E,NE,SE,W,NW,SW";`. +* * * + +##### text-transform `keyword` +`none``uppercase``lowercase``capitalize``reverse` + + +Default Value: none +_(Transform text instance with specified function. Ignores map scale factor.)_ + +Transform the case of the characters. +* * * + +##### text-horizontal-alignment `keyword` +`left``middle``right``auto``adjust` + + +Default Value: auto +_(TODO.)_ + +The text's horizontal alignment from it's centerpoint. If `placement` is set to `line`, then `adjust` can be set to auto-fit the text to the length of the path by dynamically calculating `character-spacing`. +* * * + +##### text-align `keyword` +`left``right``center``auto` + + +Default Value: auto +_(Auto alignment means that text will be centered by default except when using the `placement-type` parameter - in that case either right or left justification will be used automatically depending on where the text could be fit given the `text-placements` directives.)_ + +Define how text is justified. +* * * + +##### text-clip `boolean` + + + +Default Value: false +_(The geometry will not be clipped to map bounds before rendering.)_ + +Turning on clipping can help performance in the case that the boundaries of the geometry extent outside of tile extents. But clipping can result in undesirable rendering artifacts in rare cases. +* * * + +##### text-simplify `float` + + + +Default Value: 0 +_(geometry will not be simplified.)_ + +Simplify the geometries used for text placement by the given tolerance. +* * * + +##### text-simplify-algorithm `keyword` +`radial-distance``zhao-saalfeld``visvalingam-whyatt` + + +Default Value: radial-distance +_(The geometry will be simplified using the radial distance algorithm.)_ + +Simplify the geometries used for text placement by the given algorithm. +* * * + +##### text-smooth `float` + + + +Default Value: 0 +_(No smoothing.)_ +Range: 0-1 +Smooths out the angles of the geometry used for text placement. 0 is no smoothing, 1 is fully smoothed. Values greater than 1 will produce wild, looping geometries. +* * * + +##### text-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### text-halo-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``screen``overlay``darken``lighten``color-dodge``color-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current symbolizer on top of other symbolizer.)_ + +Composite operation. This defines how this symbolizer should behave relative to symbolizers atop or below it. +* * * + +##### text-font-feature-settings `string` + + + +Default Value: +_(Default set of typographic features recommended by OpenType specification. Ligatures are turned off by default when `character-spacing` is greater than zero.)_ + +Comma separated list of OpenType typographic features. The syntax and semantics conforms to `font-feature-settings` from W3C CSS. +* * * + +##### text-largest-bbox-only `boolean` + + + +Default Value: true +_(For multipolygons only polygon with largest bbox area is labeled (does not apply to other geometries).)_ + +Controls default labeling behavior on multipolygons. The default is true and means that only the polygon with largest bbox is labeled. +* * * + + +## building + +##### building-fill `color` + + + +Default Value: The color gray will be used for fill. +_(Gray and fully opaque (alpha = 1), same as rgb(128,128,128) or rgba(128,128,128,1).)_ + +The color of the buildings fill. Note: 0.8 will be used to multiply each color component to auto-generate a darkened wall color. +* * * + +##### building-fill-opacity `float` + + + +Default Value: 1 +_(Color is fully opaque.)_ + +The opacity of the building as a whole, including all walls. +* * * + +##### building-height `float` + + + +Default Value: 0 +_(Buildings will not have a visual height and will instead look like flat polygons.)_ + +The height of the building in pixels. +* * * + + +## debug + +##### debug-mode `string` + + + +Default Value: collision +_(The otherwise invisible collision boxes will be rendered as squares on the map.)_ + +The mode for debug rendering. +* * * + + +## dot + +##### dot-fill `color` + + + +Default Value: gray +_(The dot fill color is gray.)_ + +The color of the area of the dot. +* * * + +##### dot-opacity `float` + + + +Default Value: 1 +_(The opacity of the dot.)_ + +The overall opacity of the dot. +* * * + +##### dot-width `float` + + + +Default Value: 1 +_(The marker width is 1 pixel.)_ + +The width of the dot in pixels. +* * * + +##### dot-height `float` + + + +Default Value: 1 +_(The marker height is 1 pixels.)_ + +The height of the dot in pixels. +* * * + +##### dot-comp-op `keyword` +`clear``src``dst``src-over``dst-over``src-in``dst-in``src-out``dst-out``src-atop``dst-atop``xor``plus``minus``multiply``divide``screen``overlay``darken``lighten``color-dodge``color-burn``linear-dodge``linear-burn``hard-light``soft-light``difference``exclusion``contrast``invert``invert-rgb``grain-merge``grain-extract``hue``saturation``color``value` + + +Default Value: src-over +_(Add the current layer on top of other layers.)_ + +Composite operation. This defines how this layer should behave relative to layers atop or below it. +* * * + + + + +### Values + +Below is a list of values and an explanation of any expression that can be applied to properties in CartCSS. + +### Color + +CartoCSS accepts a variety of syntaxes for colors - HTML-style hex values, rgb, rgba, hsl, hsla, husl, and husla. It also supports the predefined HTML colors names, like `yellow` and `blue`. + +``` css +#line { +line-color: #ff0; +line-color: #ffff00; +line-color: rgb(255, 255, 0); +line-color: rgba(255, 255, 0, 1); +line-color: hsl(100, 50%, 50%); +line-color: hsla(100, 50%, 50%, 1); +line-color: husl(100, 50%, 50%); // same values yield different color than HSL +line-color: husla(100, 50%, 50%, 1); +line-color: yellow; +} +``` + +Especially of note is the support for hsl and husl, which can be [easier to reason about than rgb()](http://mothereffinghsl.com/). Carto also includes several color operation functions [borrowed from less](http://lesscss.org/functions/#color-operations): + +``` css +// lighten and darken colors +lighten(#ace, 10%); +darken(#ace, 10%); + +// saturate and desaturate +saturate(#550000, 10%); +desaturate(#00ff00, 10%); + +// increase or decrease the opacity of a color +fadein(#fafafa, 10%); +fadeout(#fefefe, 14%); + +// spin rotates a color around the color wheel by degrees +spin(#ff00ff, 10); + +// mix generates a color in between two other colors. +mix(#fff, #000, 50%); + +// get color components +hue(#ff00ff); +saturation(#ff00ff); +lightness(#ff00ff); +alpha(hsla(100, 50%, 50%, 0.5)); +``` + +These functions all take arguments which can be color variables, literal colors, or the results of other functions operating on colors. All the above mentioned functions also come in +a `functionp`-variant (e.g. `lightenp`), which force a given color into perceptual color space. + +### Float + +Float is a fancy way of saying 'number'. In CartoCSS, you specify _just a number_ - unlike CSS, there are no units, but everything is specified in pixels. + +``` css +#line { +line-width: 2; +} +``` + +It's also possible to do simple math with number values: + +``` css +#line { +line-width: 4 / 2; // division +line-width: 4 + 2; // addition +line-width: 4 - 2; // subtraction +line-width: 4 * 2; // multiplication +line-width: 4 % 2; // modulus +} +``` + +### URI + +URI is a fancy way of saying URL. When an argument is a URI, you use the same kind of `url('place.png')` notation that you would with HTML. Quotes around the URL aren't required, but are highly recommended. URIs can be paths to places on your computer, or on the internet. + +```css +#markers { +marker-file: url('marker.png'); +} +``` + +### String + +A string is basically just text. In the case of CartoCSS, you're going to put it in quotes. Strings can be anything, though pay attention to the cases of `text-name` and `shield-name` - they actually will refer to features, which you refer to by putting them in brackets, as seen in the example below. + +```css +#labels { +text-name: "[MY_FIELD]"; +} +``` + +### Boolean + +Boolean means yes or no, so it accepts the values `true` or `false`. + +```css +#markers { +marker-allow-overlap:true; +} +``` + +### Expressions + +Expressions are statements that can include fields, numbers, and other types in a really flexible way. You have run into expressions before, in the realm of 'fields', where you'd specify `"[FIELD]"`, but expressions allow you to drop the quotes and also do quick addition, division, multiplication, and concatenation from within Carto syntax. + +```css +#buildings { +building-height: [HEIGHT_FIELD] * 10; +} +``` + +### Numbers +Numbers are comma-separated lists of one or more number in a specific order. They're used in line dash arrays, in which the numbers specify intervals of line, break, and line again. + +```css +#disputedboundary { +line-dasharray: 1, 4, 2; +} +``` + +### Percentages +In Carto, the percentage symbol, `%` universally means `value/100`. It's meant to be used with ratio-related properties, like opacity rules. + +_You should not use percentages as widths, heights, or other properties - unlike CSS, percentages are not relative to cascaded classes or page size, they're, as stated, simply the value divided by one hundred._ + +```css +#world { +// this syntax +polygon-opacity: 50%; + +// is equivalent to +polygon-opacity: 0.5; +} +``` + +### Functions + +Functions are comma-separated lists of one or more functions. For instance, transforms use the `functions` type to allow for transforms within Carto, which are optionally chainable. + +```css +#point { +point-transform: scale(2, 2); +} +``` diff --git a/lib/carto/functions.js b/lib/carto/functions.js index f5c3b7f..66ae3f5 100644 --- a/lib/carto/functions.js +++ b/lib/carto/functions.js @@ -1,3 +1,7 @@ +var chroma = require('chroma-js'), + husl = require('husl'), + _ = require('lodash'); + (function (tree) { tree.functions = { @@ -8,7 +12,17 @@ tree.functions = { var rgb = [r, g, b].map(function (c) { return number(c); }); a = number(a); if (rgb.some(isNaN) || isNaN(a)) return null; - return new tree.Color(rgb, a); + + this.rgb[0] = Math.max(0, Math.min(this.rgb[0], 255)); + this.rgb[1] = Math.max(0, Math.min(this.rgb[1], 255)); + this.rgb[2] = Math.max(0, Math.min(this.rgb[2], 255)); + + var hsl = chroma(rgb).hsl(); + if (isNaN(hsl[0])) { + hsl[0] = 0; + } + + return new tree.Color(hsl, a); }, // Only require val stop: function (val) { @@ -33,98 +47,170 @@ tree.functions = { return this.hsla(h, s, l, 1.0); }, hsla: function (h, s, l, a) { - h = (number(h) % 360) / 360; - s = number(s); l = number(l); a = number(a); - if ([h, s, l, a].some(isNaN)) return null; - - var m2 = l <= 0.5 ? l * (s + 1) : l + s - l * s, - m1 = l * 2 - m2; - - return this.rgba(hue(h + 1/3) * 255, - hue(h) * 255, - hue(h - 1/3) * 255, - a); - - function hue(h) { - h = h < 0 ? h + 1 : (h > 1 ? h - 1 : h); - if (h * 6 < 1) return m1 + (m2 - m1) * h * 6; - else if (h * 2 < 1) return m2; - else if (h * 3 < 2) return m1 + (m2 - m1) * (2/3 - h) * 6; - else return m1; - } + var hsl = [h, s, l].map(function (c) { return number(c); }); + a = number(a); + if (hsl.some(isNaN) || isNaN(a)) return null; + + return new tree.Color(hsl, a, false); + }, + husl: function (h, s, l) { + return this.husla(h, s, l, 1.0); + }, + husla: function (h, s, l, a) { + var hsl = [h, s, l].map(function (c) { return number(c); }); + a = number(a); + if (hsl.some(isNaN) || isNaN(a)) return null; + + return new tree.Color(hsl, a, true); }, hue: function (color) { - if (!('toHSL' in color)) return null; - return new tree.Dimension(Math.round(color.toHSL().h)); + if (!('getComponents' in color)) return null; + var comp = color.getComponents(); + if (comp.perceptual) { + if (!('toStandard' in color)) return null; + color = color.toStandard(); + comp = color.getComponents(); + } + return new tree.Dimension(Math.round(comp.h)); + }, + huep: function (color) { + if (!('getComponents' in color)) return null; + var comp = color.getComponents(); + if (!comp.perceptual) { + if (!('toPerceptual' in color)) return null; + color = color.toPerceptual(); + comp = color.getComponents(); + } + return new tree.Dimension(Math.round(comp.h)); }, saturation: function (color) { - if (!('toHSL' in color)) return null; - return new tree.Dimension(Math.round(color.toHSL().s * 100), '%'); + if (!('getComponents' in color)) return null; + var comp = color.getComponents(); + if (comp.perceptual) { + if (!('toStandard' in color)) return null; + color = color.toStandard(); + comp = color.getComponents(); + } + return new tree.Dimension(Math.round(comp.s * 100), '%'); + }, + saturationp: function (color) { + if (!('getComponents' in color)) return null; + var comp = color.getComponents(); + if (!comp.perceptual) { + if (!('toPerceptual' in color)) return null; + color = color.toPerceptual(); + comp = color.getComponents(); + } + return new tree.Dimension(Math.round(comp.s * 100), '%'); }, lightness: function (color) { - if (!('toHSL' in color)) return null; - return new tree.Dimension(Math.round(color.toHSL().l * 100), '%'); + if (!('getComponents' in color)) return null; + var comp = color.getComponents(); + if (comp.perceptual) { + if (!('toStandard' in color)) return null; + color = color.toStandard(); + comp = color.getComponents(); + } + return new tree.Dimension(Math.round(comp.l * 100), '%'); + }, + lightnessp: function (color) { + if (!('getComponents' in color)) return null; + var comp = color.getComponents(); + if (!comp.perceptual) { + if (!('toPerceptual' in color)) return null; + color = color.toPerceptual(); + comp = color.getComponents(); + } + return new tree.Dimension(Math.round(comp.l * 100), '%'); }, alpha: function (color) { - if (!('toHSL' in color)) return null; - return new tree.Dimension(color.toHSL().a); + if (!('getComponents' in color)) return null; + var comp = color.getComponents(); + return new tree.Dimension(comp.a); }, saturate: function (color, amount) { - if (!('toHSL' in color)) return null; - var hsl = color.toHSL(); + if (!('getComponents' in color)) return null; + var comp = color.getComponents(); - hsl.s += amount.value / 100; - hsl.s = clamp(hsl.s); - return hsla(hsl); + comp.s += amount.value / 100; + comp.s = clamp(comp.s); + return new tree.Color([comp.h, comp.s, comp.l], comp.a, comp.perceptual); + }, + saturatep: function (color, amount) { + if (!('toPerceptual' in color)) return null; + return this.saturate(color.toPerceptual(), amount); }, desaturate: function (color, amount) { - if (!('toHSL' in color)) return null; - var hsl = color.toHSL(); + if (!('getComponents' in color)) return null; + var comp = color.getComponents(); - hsl.s -= amount.value / 100; - hsl.s = clamp(hsl.s); - return hsla(hsl); + comp.s -= amount.value / 100; + comp.s = clamp(comp.s); + return new tree.Color([comp.h, comp.s, comp.l], comp.a, comp.perceptual); + }, + desaturatep: function (color, amount) { + if (!('toPerceptual' in color)) return null; + return this.desaturate(color.toPerceptual(), amount); }, lighten: function (color, amount) { - if (!('toHSL' in color)) return null; - var hsl = color.toHSL(); + if (!('getComponents' in color)) return null; + var comp = color.getComponents(); - hsl.l += amount.value / 100; - hsl.l = clamp(hsl.l); - return hsla(hsl); + comp.l += amount.value / 100; + comp.l = clamp(comp.l); + return new tree.Color([comp.h, comp.s, comp.l], comp.a, comp.perceptual); + }, + lightenp: function (color, amount) { + if (!('toPerceptual' in color)) return null; + return this.lighten(color.toPerceptual(), amount); }, darken: function (color, amount) { - if (!('toHSL' in color)) return null; - var hsl = color.toHSL(); + if (!('getComponents' in color)) return null; + var comp = color.getComponents(); - hsl.l -= amount.value / 100; - hsl.l = clamp(hsl.l); - return hsla(hsl); + comp.l -= amount.value / 100; + comp.l = clamp(comp.l); + return new tree.Color([comp.h, comp.s, comp.l], comp.a, comp.perceptual); + }, + darkenp: function (color, amount) { + if (!('toPerceptual' in color)) return null; + return this.darken(color.toPerceptual(), amount); }, fadein: function (color, amount) { - if (!('toHSL' in color)) return null; - var hsl = color.toHSL(); + if (!('getComponents' in color)) return null; + var comp = color.getComponents(); - hsl.a += amount.value / 100; - hsl.a = clamp(hsl.a); - return hsla(hsl); + comp.a += amount.value / 100; + comp.a = clamp(comp.a); + return new tree.Color([comp.h, comp.s, comp.l], comp.a, comp.perceptual); + }, + fadeinp: function (color, amount) { + if (!('toPerceptual' in color)) return null; + return this.fadein(color.toPerceptual(), amount); }, fadeout: function (color, amount) { - if (!('toHSL' in color)) return null; - var hsl = color.toHSL(); + if (!('getComponents' in color)) return null; + var comp = color.getComponents(); - hsl.a -= amount.value / 100; - hsl.a = clamp(hsl.a); - return hsla(hsl); + comp.a -= amount.value / 100; + comp.a = clamp(comp.a); + return new tree.Color([comp.h, comp.s, comp.l], comp.a, comp.perceptual); + }, + fadeoutp: function (color, amount) { + if (!('toPerceptual' in color)) return null; + return this.fadeout(color.toPerceptual(), amount); }, spin: function (color, amount) { - if (!('toHSL' in color)) return null; - var hsl = color.toHSL(); - var hue = (hsl.h + amount.value) % 360; - - hsl.h = hue < 0 ? 360 + hue : hue; + if (!('getComponents' in color)) return null; + var comp = color.getComponents(); - return hsla(hsl); + var hue = (comp.h + amount.value) % 360; + comp.h = hue < 0 ? 360 + hue : hue; + return new tree.Color([comp.h, comp.s, comp.l], comp.a, comp.perceptual); + }, + spinp: function (color, amount) { + if (!('toPerceptual' in color)) return null; + return this.spin(color.toPerceptual(), amount); }, replace: function (entity, a, b) { if (entity.is === 'field') { @@ -133,28 +219,61 @@ tree.functions = { return entity.replace(a, b); } }, - // - // Copyright (c) 2006-2009 Hampton Catlin, Nathan Weizenbaum, and Chris Eppstein - // http://sass-lang.com - // mix: function (color1, color2, weight) { + if (!('isPerceptual' in color1) || !('isPerceptual' in color2) + || !('toString' in color1) || !('toString' in color2) + || !('getComponents' in color1) || !('getComponents' in color2)) return null; + + var perceptual = color1.isPerceptual() || color2.isPerceptual(); + + if (color1.isPerceptual() && !color2.isPerceptual()) { + color2 = color2.toPerceptual(); + } + else if (!color1.toPerceptual() && color2.toPerceptual()) { + color1 = color1.toPerceptual(); + } + + var rgb1 = chroma(color1.toString()).rgb(); + var rgb2 = chroma(color2.toString()).rgb(); + var p = weight.value / 100.0; - var w = p * 2 - 1; - var a = color1.toHSL().a - color2.toHSL().a; + var alpha = color1.getComponents().a * p + color2.getComponents().a * (1 - p); + var a = color1.getComponents().a - color2.getComponents().a; + var w = p * 2 - 1; var w1 = (((w * a == -1) ? w : (w + a) / (1 + w * a)) + 1) / 2.0; var w2 = 1 - w1; - var rgb = [color1.rgb[0] * w1 + color2.rgb[0] * w2, - color1.rgb[1] * w1 + color2.rgb[1] * w2, - color1.rgb[2] * w1 + color2.rgb[2] * w2]; + var rgb = [rgb1[0] * w1 + rgb2[0] * w2, + rgb1[1] * w1 + rgb2[1] * w2, + rgb1[2] * w1 + rgb2[2] * w2]; - var alpha = color1.alpha * p + color2.alpha * (1 - p); + var mix = null; + if (perceptual) { + var normalize = function (x) { + return x / 255; + }; + mix = husl.fromRGB.apply(this, _.map(rgb, normalize)); + mix[1] = mix[1] / 100; + mix[2] = mix[2] / 100; + } + else { + mix = chroma(rgb).hsl(); + } - return new tree.Color(rgb, alpha); + return new tree.Color(mix, alpha, perceptual); }, greyscale: function (color) { - return this.desaturate(color, new tree.Dimension(100)); + if (!('getComponents' in color)) return null; + var comp = color.getComponents(); + + comp.s -= 1; + comp.s = clamp(comp.s); + return new tree.Color([comp.h, comp.s, comp.l], comp.a, comp.perceptual); + }, + greyscalep: function (color) { + if (!('toPerceptual' in color)) return null; + return this.greyscale(color.toPerceptual()); }, '%': function (quoted /* arg, arg, ...*/) { var args = Array.prototype.slice.call(arguments, 1), @@ -190,10 +309,6 @@ tree.functions['scale-hsla'] = function(h0,h1,s0,s1,l0,l1,a0,a1) { return new tree.ImageFilter('scale-hsla', [h0,h1,s0,s1,l0,l1,a0,a1]); }; -function hsla(h) { - return tree.functions.hsla(h.h, h.s, h.l, h.a); -} - function number(n) { if (n instanceof tree.Dimension) { return parseFloat(n.unit == '%' ? n.value / 100 : n.value); diff --git a/lib/carto/index.js b/lib/carto/index.js index a0265d8..d108731 100644 --- a/lib/carto/index.js +++ b/lib/carto/index.js @@ -49,7 +49,7 @@ var carto = { if (typeof(extract[2]) === 'string') { error.push(stylize((ctx.line + 1) + ' ' + extract[2], 'grey')); } - error = options.indent + error.join('\n' + options.indent) + '\033[0m\n'; + error = options.indent + error.join('\n' + options.indent) + '\x1B[0m\n'; message = options.indent + message + stylize(ctx.message, 'red'); if (ctx.filename) (message += stylize(' in ', 'red') + ctx.filename); @@ -88,6 +88,6 @@ function stylize(str, style) { 'red' : [31, 39], 'grey' : [90, 39] }; - return '\033[' + styles[style][0] + 'm' + str + - '\033[' + styles[style][1] + 'm'; + return '\x1B[' + styles[style][0] + 'm' + str + + '\x1B[' + styles[style][1] + 'm'; } diff --git a/lib/carto/parser.js b/lib/carto/parser.js index 74f6033..5708ec8 100644 --- a/lib/carto/parser.js +++ b/lib/carto/parser.js @@ -1,6 +1,7 @@ var carto = exports, tree = require('./tree'), - _ = require('underscore'); + _ = require('lodash'), + chroma = require('chroma-js'); // Token matching is done with the `$` function, which either takes // a terminal string or regexp, or a non-terminal function to call. @@ -20,7 +21,8 @@ carto.Parser = function Parser(env) { // This function is called after all files // have been imported through `@import`. - var finish = function() {}; + + var finish = function() {}; // eslint-disable-line function save() { temp = chunks[j]; @@ -43,7 +45,7 @@ carto.Parser = function Parser(env) { // Parse from a token, regexp or string, and move forward if match // function $(tok) { - var match, args, length, c, index, endIndex, k; + var match, length, c, endIndex; // Non-terminal if (tok instanceof Function) { @@ -116,7 +118,7 @@ carto.Parser = function Parser(env) { message: 'Parse error.', line: 0, column: -1 - }); + }).value(); if (err.filename && that.env.inputs && that.env.inputs[err.filename]) { einput = that.env.inputs[err.filename]; @@ -128,7 +130,7 @@ carto.Parser = function Parser(env) { for (var n = err.index; n >= 0 && einput.charAt(n) !== '\n'; n--) { err.column++; } - return new Error(_('<%=filename%>:<%=line%>:<%=column%> <%=message%>').template(err)); + return new Error(_.template('<%=filename%>:<%=line%>:<%=column%> <%=message%>')(err)); } this.env = env = env || {}; @@ -141,7 +143,7 @@ carto.Parser = function Parser(env) { // Parse an input string into an abstract syntax tree. // Throws an error on parse errors. parse: function(str) { - var root, start, end, zone, line, lines, buff = [], c, error = null; + var root, error = null; i = j = current = furthest = 0; chunks = []; @@ -150,8 +152,6 @@ carto.Parser = function Parser(env) { that.env.inputs[env.filename] = input; } - var early_exit = false; - // Split the input into chunks. chunks = (function (chunks) { var j = 0, @@ -165,7 +165,8 @@ carto.Parser = function Parser(env) { for (var i = 0, c, cc; i < input.length;) { skip.lastIndex = i; - if (match = skip.exec(input)) { + match = skip.exec(input); + if (match) { if (match.index === i) { i += match[0].length; chunk.push(match[0]); @@ -174,7 +175,8 @@ carto.Parser = function Parser(env) { c = input.charAt(i); comment.lastIndex = string.lastIndex = i; - if (match = string.exec(input)) { + match = string.exec(input) + if (match) { if (match.index === i) { i += match[0].length; chunk.push(match[0]); @@ -185,7 +187,8 @@ carto.Parser = function Parser(env) { if (!inParam && c === '/') { cc = input.charAt(i + 1); if (cc === '/' || cc === '*') { - if (match = comment.exec(input)) { + match = comment.exec(input); + if (match) { if (match.index === i) { i += match[0].length; chunk.push(match[0]); @@ -195,6 +198,7 @@ carto.Parser = function Parser(env) { } } + /*eslint-disable no-fallthrough */ switch (c) { case '{': if (! inParam) { level ++; chunk.push(c); break; } case '}': if (! inParam) { level --; chunk.push(c); chunks[++j] = chunk = []; break; } @@ -203,6 +207,8 @@ carto.Parser = function Parser(env) { default: chunk.push(c); } + /*eslint-enable no-fallthrough */ + i++; } if (level !== 0) { @@ -223,7 +229,7 @@ carto.Parser = function Parser(env) { // Start with the primary rule. // The whole syntax tree is held under a Ruleset node, // with the `root` property set to true, so no `{}` are - // output. The callback is called when the input is parsed. + // output. root = new tree.Ruleset([], $(this.parsers.primary)); root.root = true; @@ -316,13 +322,12 @@ carto.Parser = function Parser(env) { // but keep the LeSS comments `//` silent, by just skipping // over them. comment: function() { - var comment; - if (input.charAt(i) !== '/') return; + var comment = $(/^\/\*(?:[^*]|\*+[^\/*])*\*+\/\n?/); if (input.charAt(i + 1) === '/') { return new tree.Comment($(/^\/\/.*/), true); - } else if (comment = $(/^\/\*(?:[^*]|\*+[^\/*])*\*+\/\n?/)) { + } else if (comment) { return new tree.Comment(comment); } }, @@ -395,9 +400,11 @@ carto.Parser = function Parser(env) { 'arguments': function() { var args = [], arg; - while (arg = $(this.expression)) { + arg = $(this.expression); + while (arg) { args.push(arg); if (! $(',')) { break; } + arg = $(this.expression); } return args; @@ -446,14 +453,21 @@ carto.Parser = function Parser(env) { hexcolor: function() { var rgb; if (input.charAt(i) === '#' && (rgb = $(/^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})/))) { - return new tree.Color(rgb[1]); + var hsl = chroma(rgb[0]).hsl(); + return new tree.Color(hsl, 1, false); } }, keywordcolor: function() { var rgb = chunks[j].match(/^[a-z]+/); if (rgb && rgb[0] in tree.Reference.data.colors) { - return new tree.Color(tree.Reference.data.colors[$(/^[a-z]+/)]); + var data = tree.Reference.data.colors[$(/^[a-z]+/)]; + var a = 1; + if (data.length > 3) { + a = data[3]; + } + var hsl = chroma(data.slice(0, 3)).hsl(); + return new tree.Color(hsl, a, false); } }, @@ -462,7 +476,7 @@ carto.Parser = function Parser(env) { dimension: function() { var c = input.charCodeAt(i); if ((c > 57 || c < 45) || c === 47) return; - var value = $(/^(-?\d*\.?\d+)(\%|\w+)?/); + var value = $(/^(-?\d*\.?\d+(?:[eE][-+]?\d+)?)(\%|\w+)?/); if (value) { return new tree.Dimension(value[1], value[2], memo); } @@ -542,7 +556,7 @@ carto.Parser = function Parser(env) { conditions++; } else if (attachment) { throw makeError({ - message: 'Encountered second attachment name.', + message: 'Encountered second attachment name.\n', index: i - 1 }); } else { @@ -562,6 +576,8 @@ carto.Parser = function Parser(env) { save(); var key, op, val; if (! $('[')) return; + + /*eslint-disable no-cond-assign */ if (key = $(/^[a-zA-Z0-9\-_]+/) || $(this.entities.quoted) || $(this.entities.variable) || @@ -587,6 +603,8 @@ carto.Parser = function Parser(env) { return new tree.Filter(key, op, val, memo, env.filename); } } + + /*eslint-enable no-cond-assign */ }, zoom: function() { @@ -614,17 +632,25 @@ carto.Parser = function Parser(env) { // div, .class, body > p {...} ruleset: function() { - var selectors = [], s, f, l, rules, filters = []; + var selectors = [], s, rules; save(); - while (s = $(this.selector)) { + s = $(this.selector); + while (s) { selectors.push(s); - while ($(this.comment)) {} + while ($(this.comment)) { + // do nothing + } if (! $(',')) { break; } - while ($(this.comment)) {} + while ($(this.comment)) { + // do nothing + } + s = $(this.selector); } if (s) { - while ($(this.comment)) {} + while ($(this.comment)) { + // do nothing + } } if (selectors.length > 0 && (rules = $(this.block))) { @@ -648,6 +674,7 @@ carto.Parser = function Parser(env) { if (c === '.' || c === '#') { return; } + /*eslint-disable no-cond-assign */ if (name = $(this.variable) || $(this.property)) { value = $(this.value); @@ -658,21 +685,27 @@ carto.Parser = function Parser(env) { restore(); } } + + /*eslint-enable no-cond-assign */ }, font: function() { - var value = [], expression = [], weight, font, e; + var value = [], expression = [], e; - while (e = $(this.entity)) { + e = $(this.entity); + while (e) { expression.push(e); + e = $(this.entity); } value.push(new tree.Expression(expression)); if ($(',')) { - while (e = $(this.expression)) { + e = $(this.expression); + while (e) { value.push(e); if (! $(',')) { break; } + e = $(this.expression); } } return new tree.Value(value); @@ -684,9 +717,11 @@ carto.Parser = function Parser(env) { value: function() { var e, expressions = []; - while (e = $(this.expression)) { + e = $(this.expression); + while (e) { expressions.push(e); if (! $(',')) { break; } + e = $(this.expression); } if (expressions.length > 1) { @@ -709,20 +744,30 @@ carto.Parser = function Parser(env) { // and division. multiplication: function() { var m, a, op, operation; - if (m = $(this.operand)) { + m = $(this.operand); + if (m) { + + /*eslint-disable no-cond-assign */ while ((op = ($('/') || $('*') || $('%'))) && (a = $(this.operand))) { operation = new tree.Operation(op, [operation || m, a], memo); } + + /*eslint-enable no-cond-assign */ return operation || m; } }, addition: function() { var m, a, op, operation; - if (m = $(this.multiplication)) { + m = $(this.multiplication); + if (m) { + + /*eslint-disable no-cond-assign */ while ((op = $(/^[-+]\s+/) || (input.charAt(i - 1) != ' ' && ($('+') || $('-')))) && (a = $(this.multiplication))) { operation = new tree.Operation(op, [operation || m, a], memo); } + + /*eslint-enable no-cond-assign */ return operation || m; } }, @@ -736,10 +781,12 @@ carto.Parser = function Parser(env) { // Expressions either represent mathematical operations, // or white-space delimited Entities. @var * 2 expression: function() { - var e, delim, entities = [], d; + var e, entities = []; - while (e = $(this.addition) || $(this.entity)) { + e = $(this.addition); + while (e || $(this.entity)) { entities.push(e); + e = $(this.addition); } if (entities.length > 0) { diff --git a/lib/carto/renderer.js b/lib/carto/renderer.js index ce14af1..49c4cb8 100644 --- a/lib/carto/renderer.js +++ b/lib/carto/renderer.js @@ -1,29 +1,28 @@ -var _ = require('underscore'); +var _ = require('lodash'); var carto = require('./index'); carto.Renderer = function Renderer(env, options) { this.env = env || {}; this.options = options || {}; - this.options.mapnik_version = this.options.mapnik_version || 'latest'; + this.options.mapnik_version = this.options.mapnik_version || '3.0.0'; }; -// Prepare a MSS document (given as an string) into a -// XML Style fragment (mostly useful for debugging) -// -// - @param {String} str the mss contents as a string. -// - @param {Object} env renderer environment options. -carto.Renderer.prototype.renderMSS = function render(data, callback) { +/** + * Prepare a MSS document (given as an string) into a + * XML Style fragment (mostly useful for debugging) + * + * @param {String} data the mss contents as a string. + */ +carto.Renderer.prototype.renderMSS = function render(data) { // effects is a container for side-effects, which currently // are limited to FontSets. var env = _(this.env).defaults({ benchmark: false, validation_data: false, effects: [] - }); + }).value(); - if (!carto.tree.Reference.setVersion(this.options.mapnik_version)) { - return callback(new Error("Could not set mapnik version to " + this.options.mapnik_version), null); - } + carto.tree.Reference.setVersion(this.options.mapnik_version); var output = []; var styles = []; @@ -56,16 +55,17 @@ carto.Renderer.prototype.renderMSS = function render(data, callback) { if (env.benchmark) console.timeEnd(bench_name); } if (env.benchmark) console.timeEnd('Total Style generation'); - if (env.errors) return callback(env.errors); - return callback(null, output.join('\n')); + if (env.errors) throw env.errors; + return output.join('\n'); }; -// Prepare a MML document (given as an object) into a -// fully-localized XML file ready for Mapnik2 consumption -// -// - @param {String} str the JSON file as a string. -// - @param {Object} env renderer environment options. -carto.Renderer.prototype.render = function render(m, callback) { +/** + * Prepare a MML document (given as an object) into a + * fully-localized XML file ready for Mapnik consumption + * + * @param {String} m - the JSON file as a string. + */ +carto.Renderer.prototype.render = function render(m) { // effects is a container for side-effects, which currently // are limited to FontSets. var env = _(this.env).defaults({ @@ -73,33 +73,36 @@ carto.Renderer.prototype.render = function render(m, callback) { validation_data: false, effects: [], ppi: 90.714 - }); + }).value(); - if (!carto.tree.Reference.setVersion(this.options.mapnik_version)) { - return callback(new Error("Could not set mapnik version to " + this.options.mapnik_version), null); - } + carto.tree.Reference.setVersion(this.options.mapnik_version); var output = []; + var definitions = []; // Transform stylesheets into definitions. - var definitions = _(m.Stylesheet).chain() - .map(function(s) { - if (typeof s == 'string') { - callback(new Error("Stylesheet object is expected not a string: '" + s + "'")); - } - // Passing the environment from stylesheet to stylesheet, - // allows frames and effects to be maintained. - env = _(env).extend({filename:s.id}); - - // @TODO try/catch? - var time = +new Date(), - root = (carto.Parser(env)).parse(s.data); - if (env.benchmark) - console.warn('Parsing time: ' + (new Date() - time) + 'ms'); - return root.toList(env); - }) - .flatten() - .value(); + if (_.has(m, 'Stylesheet') && !_.isNil(m.Stylesheet)) { + m.Stylesheet = _.castArray(m.Stylesheet); + definitions = _(m.Stylesheet).chain() + .map(function(s) { + if (_.isString(s) || !_.has(s, 'id') || !_.has(s, 'data') || _.isNil(s.id) || _.isNil(s.data)) { + var e = new Error("Expecting a stylesheet object of the form { id: 'x', 'data': 'y' } for the Stylesheet property.\n"); + e.stack = null; // do not show stack trace + throw e; + } + // Passing the environment from stylesheet to stylesheet, + // allows frames and effects to be maintained. + env = _(env).extend({filename:s.id}).value(); + + var time = +new Date(), + root = (carto.Parser(env)).parse(s.data); + if (env.benchmark) + console.warn('Parsing time: ' + (new Date() - time) + 'ms'); + return root.toList(env); + }) + .flatten() + .value(); + } function appliesTo(name, classIndex) { return function(definition) { @@ -113,28 +116,31 @@ carto.Renderer.prototype.render = function render(m, callback) { for (var i = 0; i < m.Layer.length; i++) { l = m.Layer[i]; styles = []; - classIndex = {}; - if (env.benchmark) console.warn('processing layer: ' + l.id); - // Classes are given as space-separated alphanumeric strings. - var classes = (l['class'] || '').split(/\s+/g); - for (var j = 0; j < classes.length; j++) { - classIndex[classes[j]] = true; - } - matching = definitions.filter(appliesTo(l.name, classIndex)); - rules = inheritDefinitions(matching, env); - sorted = sortStyles(rules, env); + if (definitions.length > 0) { + classIndex = {}; - for (var k = 0, rule, style_name; k < sorted.length; k++) { - rule = sorted[k]; - style_name = l.name + (rule.attachment !== '__default__' ? '-' + rule.attachment : ''); + if (env.benchmark) console.warn('processing layer: ' + l.id); + // Classes are given as space-separated alphanumeric strings. + var classes = (l['class'] || '').split(/\s+/g); + for (var j = 0; j < classes.length; j++) { + classIndex[classes[j]] = true; + } + matching = definitions.filter(appliesTo(l.name, classIndex)); + rules = inheritDefinitions(matching, env); + sorted = sortStyles(rules, env); - // env.effects can be modified by this call - var styleXML = carto.tree.StyleXML(style_name, rule.attachment, rule, env); + for (var k = 0, rule, style_name; k < sorted.length; k++) { + rule = foldStyle(sorted[k]); + style_name = l.name + (rule.attachment !== '__default__' ? '-' + rule.attachment : ''); - if (styleXML) { - output.push(styleXML); - styles.push(style_name); + // env.effects can be modified by this call + var styleXML = carto.tree.StyleXML(style_name, rule.attachment, rule, env); + + if (styleXML) { + output.push(styleXML); + styles.push(style_name); + } } } @@ -145,16 +151,10 @@ carto.Renderer.prototype.render = function render(m, callback) { return e.toXML(env); }).join('\n')); - var map_properties; - try { - map_properties = getMapProperties(m, definitions, env); - } catch (err) { - env.error(err); - return callback(err); - } + var map_properties = getMapProperties(m, definitions, env); // Exit on errors. - if (env.errors) return callback(env.errors); + if (env.errors) throw env.errors; // Pass TileJSON and other custom parameters through to Mapnik XML. var parameters = _(m).reduce(function(memo, v, k) { @@ -211,9 +211,6 @@ carto.Renderer.prototype.render = function render(m, callback) { ); var properties = _(map_properties).map(function(v) { return ' ' + v; }).join(''); - if(!map_properties['maximum-extent']) { - properties += ' maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"'; - } output.unshift( '<?xml version="1.0" ' + @@ -221,17 +218,17 @@ carto.Renderer.prototype.render = function render(m, callback) { '<!DOCTYPE Map[]>\n' + '<Map' + properties +'>\n'); output.push('</Map>'); - return callback(null, output.join('\n')); + return output.join('\n'); }; -// This function currently modifies 'current' -// -// @param {Array} the current list of rules -// @param {Object} definition a Definition object to add to the rules -// @param {Object} byFilter an object/dictionary of existing filters. This is -// actually keyed `attachment->filter` -// @param {Object} env the current environment -function addRules(current, definition, byFilter, env) { +/** + * This function currently modifies 'current' + * @param {Array} current current list of rules + * @param {Object} definition a Definition object to add to the rules + * @param {Object} byFilter an object/dictionary of existing filters. This is + * actually keyed `attachment->filter` +*/ +function addRules(current, definition, byFilter, env) { // eslint-disable-line var newFilters = definition.filters, newRules = definition.rules, updatedFilters, clone, previous; @@ -283,16 +280,18 @@ function addRules(current, definition, byFilter, env) { return current; } -// Apply inherited styles from their ancestors to them. -// -// called either once per render (in the case of mss) or per layer -// (for mml) -// -// @param {Object} definitions: a list of definitions objects that contain .rules -// @param {Object} env the environment -// -// result: an array of arrays is returned, in which each array refers to a -// specific attachment +/** + * Apply inherited styles from their ancestors to them. + * + * called either once per render (in the case of mss) or per layer + * (for mml) + * + * @param {Object} definitions - a list of definitions objects + * that contain .rules + * @param {Object} env - the environment + * @return {Array<Array>} an array of arrays is returned, + * in which each array refers to a specific attachment + */ function inheritDefinitions(definitions, env) { var inheritTime = +new Date(); // definitions are ordered by specificity, @@ -300,7 +299,7 @@ function inheritDefinitions(definitions, env) { var byAttachment = {}, byFilter = {}; var result = []; - var current, previous, attachment; + var current, attachment; // Evaluate the filters specified by each definition with the given // environment to correctly resolve variable references @@ -344,7 +343,7 @@ function inheritDefinitions(definitions, env) { // This sorts a slice of the styles, so it returns a sorted // array but does not change the input. function sortStylesIndex(a, b) { return b.index - a.index; } -function sortStyles(styles, env) { +function sortStyles(styles, env) { // eslint-disable-line for (var i = 0; i < styles.length; i++) { var style = styles[i]; style.index = Infinity; @@ -364,16 +363,31 @@ function sortStyles(styles, env) { return result; } -// Find a rule like Map { background-color: #fff; }, -// if any, and return a list of properties to be inserted -// into the <Map element of the resulting XML. Translates -// properties of the mml object at `m` directly into XML -// properties. -// -// - @param {Object} m the mml object. -// - @param {Array} definitions the output of toList. -// - @param {Object} env. -// - @return {String} rendered properties. +// Removes dead style definitions that can never be reached +// when filter-mode="first". The style is modified in-place +// and returned. The style must be sorted. +function foldStyle(style) { + for (var i = 0; i < style.length; i++) { + for (var j = style.length - 1; j > i; j--) { + if (style[j].filters.cloneWith(style[i].filters) === null) + style.splice(j, 1); + } + } + return style; +} + +/** + * Find a rule like Map { background-color: #fff; }, + * if any, and return a list of properties to be inserted + * into the <Map element of the resulting XML. Translates + * properties of the mml object at `m` directly into XML + * properties. + * + * @param {Object} m the mml object. + * @param {Array} definitions the output of toList. + * @param {Object} env + * @return {String} rendered properties. + */ function getMapProperties(m, definitions, env) { var rules = {}; var symbolizers = carto.tree.Reference.data.symbolizers.map; diff --git a/lib/carto/tree.js b/lib/carto/tree.js index c725a4d..a8d6db9 100644 --- a/lib/carto/tree.js +++ b/lib/carto/tree.js @@ -3,7 +3,8 @@ */ module.exports.find = function (obj, fun) { for (var i = 0, r; i < obj.length; i++) { - if (r = fun.call(obj, obj[i])) { return r; } + r = fun.call(obj, obj[i]); + if (r) { return r; } } return null; }; diff --git a/lib/carto/tree/call.js b/lib/carto/tree/call.js index 6e9566b..253a882 100644 --- a/lib/carto/tree/call.js +++ b/lib/carto/tree/call.js @@ -1,5 +1,5 @@ (function(tree) { -var _ = require('underscore'); +var _ = require('lodash'); tree.Call = function Call(name, args, index) { this.name = name; this.args = args; @@ -57,7 +57,7 @@ tree.Call.prototype = { } else { var fn = tree.Reference.mapnikFunctions[this.name]; if (fn === undefined) { - var functions = _.pairs(tree.Reference.mapnikFunctions); + var functions = _.toPairs(tree.Reference.mapnikFunctions); // cheap closest, needs improvement. var name = this.name; var mean = functions.map(function(f) { @@ -78,6 +78,7 @@ tree.Call.prototype = { }; } if (fn !== args.length && + !(Array.isArray(fn) && _.includes(fn, args.length)) && // support variable-arg functions like `colorize-alpha` fn !== -1) { env.error({ @@ -99,7 +100,7 @@ tree.Call.prototype = { } }, - toString: function(env, format) { + toString: function(env, format) { // eslint-disable-line if (this.args.length) { return this.name + '(' + this.args.join(',') + ')'; } else { diff --git a/lib/carto/tree/color.js b/lib/carto/tree/color.js index fbdb41c..633c4fe 100644 --- a/lib/carto/tree/color.js +++ b/lib/carto/tree/color.js @@ -1,31 +1,34 @@ +var chroma = require('chroma-js'), + husl = require('husl'), + _ = require('lodash'); + (function(tree) { -// RGB Colors - #ff0014, #eee -// can be initialized with a 3 or 6 char string or a 3 or 4 element -// numerical array -tree.Color = function Color(rgb, a) { - // The end goal here, is to parse the arguments - // into an integer triplet, such as `128, 255, 0` - // - // This facilitates operations and conversions. - if (Array.isArray(rgb)) { - this.rgb = rgb.slice(0, 3); - } else if (rgb.length == 6) { - this.rgb = rgb.match(/.{2}/g).map(function(c) { - return parseInt(c, 16); - }); + +tree.Color = function Color(hsl, a, perceptual) { + if (Array.isArray(hsl)) { + this.hsl = hsl.slice(0, 3); + this.hsl[0] = Math.max(0, Math.min(this.hsl[0], 360)); + this.hsl[1] = Math.max(0, Math.min(this.hsl[1], 1)); + this.hsl[2] = Math.max(0, Math.min(this.hsl[2], 1)); } else { - this.rgb = rgb.split('').map(function(c) { - return parseInt(c + c, 16); - }); + this.hsl = null; } if (typeof(a) === 'number') { this.alpha = a; - } else if (rgb.length === 4) { - this.alpha = rgb[3]; } else { this.alpha = 1; } + if (typeof(a) === 'number') { + this.alpha = a; + } else { + this.alpha = 1; + } + if (typeof(perceptual) == 'boolean') { + this.perceptual = perceptual; + } else { + this.perceptual = false; + } }; tree.Color.prototype = { @@ -35,60 +38,117 @@ tree.Color.prototype = { // If we have some transparency, the only way to represent it // is via `rgba`. Otherwise, we use the hex representation, // which has better compatibility with older browsers. - // Values are capped between `0` and `255`, rounded and zero-padded. toString: function() { - if (this.alpha < 1.0) { - return 'rgba(' + this.rgb.map(function(c) { - return Math.round(c); - }).concat(this.alpha).join(', ') + ')'; - } else { - return '#' + this.rgb.map(function(i) { - i = Math.round(i); - i = (i > 255 ? 255 : (i < 0 ? 0 : i)).toString(16); - return i.length === 1 ? '0' + i : i; - }).join(''); + if (this.hsl !== null) { + if (this.alpha < 1.0) { + if (this.perceptual) { + return 'rgba(' + husl.toRGB(this.hsl[0], this.hsl[1] * 100, this.hsl[2] * 100).map(function(c) { + return Math.round(c * 255); + }).concat(this.round(this.alpha, 2)).join(', ') + ')'; + } + else { + return 'rgba(' + chroma.hsl(this.hsl[0], this.hsl[1], this.hsl[2]).rgb().map(function(c) { + return Math.round(c); + }).concat(this.round(this.alpha, 2)).join(', ') + ')'; + } + } else { + if (this.perceptual) { + return husl.toHex(this.hsl[0], this.hsl[1] * 100, this.hsl[2] * 100); + } + else { + return chroma.hsl(this.hsl[0], this.hsl[1], this.hsl[2]).hex(); + } + } + } + return ''; + }, + + isPerceptual: function() { + return this.perceptual; + }, + + toPerceptual: function() { + if (this.perceptual) { + return this; + } + else { + // transition via RGB, because HSL values cannot be directly + // transformed into HUSL values easily + var rgb = chroma.hsl(this.hsl[0], this.hsl[1], this.hsl[2]).rgb(); + var huslc = husl.fromRGB(rgb[0] / 255, rgb[1] / 255, rgb[2] / 255); + return new tree.Color([huslc[0], huslc[1] / 100, huslc[2] / 100], this.alpha, true); + } + }, + + toStandard: function() { + if (!this.perceptual) { + return this; + } + else { + // transition via RGB, because HUSL values cannot be directly + // transformed into HSL values easily + var rgb = husl.toRGB(this.hsl[0], this.hsl[1], this.hsl[2]).rgb(); + var hsl = chroma(rgb[0] * 255, rgb[1] * 255, rgb[2] * 255).hsl(); + return new tree.Color([hsl[0], hsl[1], hsl[2]], this.alpha, false); } }, - // Operations have to be done per-channel, if not, + // Operations have to be done in RGB per-channel, if not, // channels will spill onto each other. Once we have // our result, in the form of an integer triplet, // we create a new Color node to hold the result. operate: function(env, op, other) { - var result = []; + var result = [], + rgb2; - if (! (other instanceof tree.Color)) { - other = other.toColor(); + if (other instanceof tree.Color) { + rgb2 = chroma(other.toString()).rgb(); } + else if (_.isArray(other)) { + rgb2 = _.slice(other, 0, Math.max(other.length, 3)); + } + else if (_.isObject(other)) { + if (_.has(other, 'value')) { + rgb2 = [other.value, other.value, other.value]; + } + else { + return; + } + } + else { + rgb2 = [other, other, other]; + } + + var rgb1 = chroma(this.toString()).rgb(); for (var c = 0; c < 3; c++) { - result[c] = tree.operate(op, this.rgb[c], other.rgb[c]); + result[c] = tree.operate(op, rgb1[c] , rgb2[c]); } - return new tree.Color(result); - }, - - toHSL: function() { - var r = this.rgb[0] / 255, - g = this.rgb[1] / 255, - b = this.rgb[2] / 255, - a = this.alpha; - var max = Math.max(r, g, b), min = Math.min(r, g, b); - var h, s, l = (max + min) / 2, d = max - min; + if (this.perceptual) { + var normalize = function (x) { + return x / 255; + }; + result = husl.fromRGB.apply(this, _.map(result, normalize)); + result[1] = result[1] / 100; + result[2] = result[2] / 100; + } + else { + result = chroma(result).hsl(); + } - if (max === min) { - h = s = 0; - } else { - s = l > 0.5 ? d / (2 - max - min) : d / (max + min); + return new tree.Color(result, this.alpha, this.perceptual); + }, - switch (max) { - case r: h = (g - b) / d + (g < b ? 6 : 0); break; - case g: h = (b - r) / d + 2; break; - case b: h = (r - g) / d + 4; break; - } - h /= 6; + getComponents: function() { + if (this.hsl !== null) { + return { h: this.hsl[0] || 0, s: this.hsl[1], l: this.hsl[2], a: this.alpha, perceptual: this.perceptual } } - return { h: h * 360, s: s, l: l, a: a }; + return null; + }, + + round: function(value, decimals) { + return Number(Math.round(value+'e'+decimals)+'e-'+decimals); } }; diff --git a/lib/carto/tree/comment.js b/lib/carto/tree/comment.js index c12a799..3b2a70e 100644 --- a/lib/carto/tree/comment.js +++ b/lib/carto/tree/comment.js @@ -6,7 +6,7 @@ tree.Comment = function Comment(value, silent) { }; tree.Comment.prototype = { - toString: function(env) { + toString: function(env) { // eslint-disable-line return '<!--' + this.value + '-->'; }, 'ev': function() { return this; } diff --git a/lib/carto/tree/definition.js b/lib/carto/tree/definition.js index c475273..2283c18 100644 --- a/lib/carto/tree/definition.js +++ b/lib/carto/tree/definition.js @@ -1,6 +1,6 @@ (function(tree) { var assert = require('assert'), - _ = require('underscore'); + _ = require('lodash'); // A definition is the combination of a selector and rules, like // #foo { @@ -97,6 +97,7 @@ tree.Definition.prototype.symbolizersToXML = function(env, symbolizers, zoom) { } sym_order = symbolizerList(sym_order); + var sym_count = 0; for (var i = 0; i < sym_order.length; i++) { var attributes = symbolizers[sym_order[i]]; @@ -105,6 +106,7 @@ tree.Definition.prototype.symbolizersToXML = function(env, symbolizers, zoom) { // Skip the magical * symbolizer which is used for universal properties // which are bubbled up to Style elements intead of Symbolizer elements. if (symbolizer === '*') continue; + sym_count++; var fail = tree.Reference.requiredProperties(symbolizer, attributes); if (fail) { @@ -147,7 +149,7 @@ tree.Definition.prototype.symbolizersToXML = function(env, symbolizers, zoom) { } } } - if (!xml) return ''; + if (!sym_count || !xml) return ''; return ' <Rule>\n' + xml + ' </Rule>\n'; }; @@ -186,20 +188,25 @@ tree.Definition.prototype.toXML = function(env, existing) { var filter = this.filters.toString(); if (!(filter in existing)) existing[filter] = tree.Zoom.all; - var available = tree.Zoom.all, xml = '', zoom, symbolizers, + var available = tree.Zoom.all, xml = '', symbolizers, zooms = { available: tree.Zoom.all }; for (var i = 0; i < this.rules.length && available; i++) { zooms.rule = this.rules[i].zoom; if (!(existing[filter] & zooms.rule)) continue; - while (zooms.current = zooms.rule & available) { - if (symbolizers = this.collectSymbolizers(zooms, i)) { - if (!(existing[filter] & zooms.current)) continue; - xml += this.symbolizersToXML(env, symbolizers, - (new tree.Zoom()).setZoom(existing[filter] & zooms.current)); - existing[filter] &= ~zooms.current; + do { + zooms.current = zooms.rule & available; + if (zooms.current) { + symbolizers = this.collectSymbolizers(zooms, i); + if (symbolizers) { + if (!(existing[filter] & zooms.current)) continue; + xml += this.symbolizersToXML(env, symbolizers, + (new tree.Zoom()).setZoom(existing[filter] & zooms.current)); + existing[filter] &= ~zooms.current; + } } } + while (zooms.current); } return xml; diff --git a/lib/carto/tree/dimension.js b/lib/carto/tree/dimension.js index 07232f2..dad8ebb 100644 --- a/lib/carto/tree/dimension.js +++ b/lib/carto/tree/dimension.js @@ -1,5 +1,6 @@ (function(tree) { -var _ = require('underscore'); +var _ = require('lodash'), + chroma = require('chroma-js'); // // A number with a unit // @@ -22,7 +23,7 @@ tree.Dimension.prototype = { pc: 6 }, ev: function (env) { - if (this.unit && !_.contains(this.all_units, this.unit)) { + if (this.unit && !_.includes(this.all_units, this.unit)) { env.error({ message: "Invalid unit: '" + this.unit + "'", index: this.index @@ -31,7 +32,7 @@ tree.Dimension.prototype = { } // normalize units which are not px or % - if (this.unit && _.contains(this.physical_units, this.unit)) { + if (this.unit && _.includes(this.physical_units, this.unit)) { if (!env.ppi) { env.error({ message: "ppi is not set, so metric units can't be used", @@ -48,7 +49,7 @@ tree.Dimension.prototype = { return this; }, toColor: function() { - return new tree.Color([this.value, this.value, this.value]); + return new tree.Color(chroma([this.value, this.value, this.value]).hsl(), 1, false); }, round: function() { this.value = Math.round(this.value); diff --git a/lib/carto/tree/filterset.js b/lib/carto/tree/filterset.js index 4e3642b..cb79390 100644 --- a/lib/carto/tree/filterset.js +++ b/lib/carto/tree/filterset.js @@ -26,6 +26,18 @@ tree.Filterset.prototype.ev = function(env) { for (var i in this.filters) { this.filters[i].ev(env); } + // Rebuild the filters dict after var subst. + var result = new tree.Filterset(); + for (var i2 in this.filters) { + var err = result.add(this.filters[i2]); + if (err) { + var filename = this.filters[i2].filename; + if (filename) + err = filename + ': ' + err; + throw new Error(err); + } + } + this.filters = result.filters; return this; }; @@ -70,9 +82,13 @@ tree.Filterset.prototype.cloneWith = function(other) { } // Only add new filters that actually change the filter. - while (id = additions.shift()) { - clone.add(id); + do { + id = additions.shift(); + if (id) { + clone.add(id); + } } + while (id); return clone; }; @@ -84,7 +100,7 @@ tree.Filterset.prototype.addable = function(filter) { var key = filter.key.toString(), value = filter.val.toString(); - if (value.match(/^[0-9]+(\.[0-9]*)?$/)) value = parseFloat(value); + if (value.match(/^[+-]?[0-9]+(\.[0-9]*)?$/)) value = parseFloat(value); switch (filter.op) { case '=': @@ -178,9 +194,8 @@ tree.Filterset.prototype.conflict = function(filter) { }; // Only call this function for filters that have been cleared by .addable(). -tree.Filterset.prototype.add = function(filter, env) { +tree.Filterset.prototype.add = function(filter, env) { // eslint-disable-line var key = filter.key.toString(), - id, op = filter.op, conflict = this.conflict(filter), numval; @@ -197,14 +212,6 @@ tree.Filterset.prototype.add = function(filter, env) { } else if (op === '=~') { this.filters[key + '=~' + filter.val] = filter; } else if (op === '>') { - // If there are other filters that are also > - // but are less than this one, they don't matter, so - // remove them. - for (var j in this.filters) { - if (this.filters[j].key == key && this.filters[j].val <= filter.val) { - delete this.filters[j]; - } - } this.filters[key + '>'] = filter; } else if (op === '>=') { for (var k in this.filters) { diff --git a/lib/carto/tree/fontset.js b/lib/carto/tree/fontset.js index 80ed28b..d5a454e 100644 --- a/lib/carto/tree/fontset.js +++ b/lib/carto/tree/fontset.js @@ -18,7 +18,7 @@ tree.FontSet = function FontSet(env, fonts) { this.name = 'fontset-' + env.effects.length; }; -tree.FontSet.prototype.toXML = function(env) { +tree.FontSet.prototype.toXML = function(env) { // eslint-disable-line return '<FontSet name="' + this.name + '">\n' + diff --git a/lib/carto/tree/layer.js b/lib/carto/tree/layer.js index 24e61ce..3972051 100644 --- a/lib/carto/tree/layer.js +++ b/lib/carto/tree/layer.js @@ -1,3 +1,5 @@ +var semver = require('semver'); + (function(tree) { tree.LayerXML = function(obj, styles) { @@ -7,12 +9,26 @@ tree.LayerXML = function(obj, styles) { obj.Datasource[i] + ']]></Parameter>'); } + var apiVersion = tree.Reference.data['version']; + var prop_string = ''; for (var prop in obj.properties) { if (prop === 'minzoom') { - prop_string += ' maxzoom="' + tree.Zoom.ranges[obj.properties[prop]] + '"\n'; + if (semver.gte(apiVersion, '3.0.0')) { + prop_string += ' maximum-scale-denominator="' + } + else { + prop_string += ' maxzoom="' + } + prop_string += tree.Zoom.ranges[obj.properties[prop]] + '"\n'; } else if (prop === 'maxzoom') { - prop_string += ' minzoom="' + tree.Zoom.ranges[obj.properties[prop]+1] + '"\n'; + if (semver.gte(apiVersion, '3.0.0')) { + prop_string += ' minimum-scale-denominator="' + } + else { + prop_string += ' minzoom="' + } + prop_string += tree.Zoom.ranges[obj.properties[prop]+1] + '"\n'; } else { prop_string += ' ' + prop + '="' + obj.properties[prop] + '"\n'; } diff --git a/lib/carto/tree/quoted.js b/lib/carto/tree/quoted.js index ead48cf..0d3045e 100644 --- a/lib/carto/tree/quoted.js +++ b/lib/carto/tree/quoted.js @@ -8,13 +8,14 @@ tree.Quoted.prototype = { is: 'string', toString: function(quotes) { - var xmlvalue = this.value + var escapedValue = this.value .replace(/&/g, '&') - .replace(/\'/g, ''') + var xmlvalue = escapedValue + .replace(/\'/g, '\\\'') .replace(/\"/g, '"') .replace(/</g, '<') .replace(/\>/g, '>'); - return (quotes === true) ? "'" + xmlvalue + "'" : this.value; + return (quotes === true) ? "'" + xmlvalue + "'" : escapedValue; }, 'ev': function() { diff --git a/lib/carto/tree/reference.js b/lib/carto/tree/reference.js index e6ef872..0bfcacf 100644 --- a/lib/carto/tree/reference.js +++ b/lib/carto/tree/reference.js @@ -4,7 +4,7 @@ // combinations. (function(tree) { -var _ = require('underscore'), +var _ = require('lodash'), mapnik_reference = require('mapnik-reference'), ref = {}; @@ -12,15 +12,25 @@ ref.setData = function(data) { ref.data = data; ref.selector_cache = generateSelectorCache(data); ref.mapnikFunctions = generateMapnikFunctions(data); + + ref.mapnikFunctions.matrix = [6]; + ref.mapnikFunctions.translate = [1, 2]; + ref.mapnikFunctions.scale = [1, 2]; + ref.mapnikFunctions.rotate = [1, 3]; + ref.mapnikFunctions.skewX = [1]; + ref.mapnikFunctions.skewY = [1]; + ref.required_cache = generateRequiredProperties(data); }; ref.setVersion = function(version) { - if (mapnik_reference.version.hasOwnProperty(version)) { - ref.setData(mapnik_reference.version[version]); - return true; - } else { - return false; + try { + ref.setData(mapnik_reference.load(version)); + } + catch (err) { + var e = new Error('Mapnik version ' + version + ' is not supported'); + e.stack = null; // do not show stack trace + throw e; } }; @@ -148,7 +158,7 @@ function validateKeyword(value, selector) { } ref.validValue = function(env, selector, value) { - var i, j; + var i; // TODO: handle in reusable way if (!ref.selector(selector)) { return false; @@ -178,8 +188,6 @@ ref.validValue = function(env, selector, value) { // For backwards compatibility, you can specify a string for `functions`-compatible // values, though they will not be validated. return validateFunctions(value, selector); - } else if (ref.selector(selector).type === 'expression') { - return true; } else if (ref.selector(selector).type === 'unsigned') { if (value.value[0].is === 'float') { value.value[0].round(); @@ -187,15 +195,14 @@ ref.validValue = function(env, selector, value) { } else { return false; } + } else if ((ref.selector(selector).expression)) { + return true; } else { if (ref.selector(selector).validate) { var valid = false; for (i = 0; i < value.value.length; i++) { if (ref.selector(selector).type == value.value[i].is && - ref - ._validateValue - [ref.selector(selector).validate] - (env, value.value[i].value)) { + ref._validateValue[ref.selector(selector).validate](env, value.value[i].value)) { return true; } } @@ -206,8 +213,6 @@ ref.validValue = function(env, selector, value) { } }; -ref.setVersion('latest'); - tree.Reference = ref; })(require('../tree')); diff --git a/lib/carto/tree/rule.js b/lib/carto/tree/rule.js index 75b64b3..c72e05f 100644 --- a/lib/carto/tree/rule.js +++ b/lib/carto/tree/rule.js @@ -46,7 +46,7 @@ function getMean(name) { // rule without the usual attribute="content" wrapping. Right // now this is just for the TextSymbolizer, but applies to other // properties in reference.json which specify serialization=content -tree.Rule.prototype.toXML = function(env, content, sep, format) { +tree.Rule.prototype.toXML = function(env, content, sep, format) { // eslint-disable-line if (!tree.Reference.validSelector(this.name)) { var mean = getMean(this.name); var mean_message = ''; diff --git a/lib/carto/tree/ruleset.js b/lib/carto/tree/ruleset.js index cf48965..5851ca4 100644 --- a/lib/carto/tree/ruleset.js +++ b/lib/carto/tree/ruleset.js @@ -10,6 +10,7 @@ tree.Ruleset.prototype = { is: 'ruleset', 'ev': function(env) { var i, + rule, ruleset = new tree.Ruleset(this.selectors, this.rules.slice(0)); ruleset.root = this.root; @@ -17,7 +18,7 @@ tree.Ruleset.prototype = { env.frames.unshift(ruleset); // Evaluate everything else - for (i = 0, rule; i < ruleset.rules.length; i++) { + for (i = 0; i < ruleset.rules.length; i++) { rule = ruleset.rules[i]; ruleset.rules[i] = rule.ev ? rule.ev(env) : rule; } @@ -54,7 +55,7 @@ tree.Ruleset.prototype = { }, find: function(selector, self) { self = self || this; - var rules = [], rule, match, + var rules = [], match, key = selector.toString(); if (key in this._lookups) { return this._lookups[key]; } diff --git a/lib/carto/tree/style.js b/lib/carto/tree/style.js index f050e89..0d8e66e 100644 --- a/lib/carto/tree/style.js +++ b/lib/carto/tree/style.js @@ -1,17 +1,20 @@ (function(tree) { -var _ = require('underscore'); +var _ = require('lodash'); // Given a style's name, attachment, definitions, and an environment object, // return a stringified style for Mapnik tree.StyleXML = function(name, attachment, definitions, env) { var existing = {}; - var image_filters = [], direct_image_filters = [], comp_op = [], opacity = []; + var image_filters = [], image_filters_inflate = [], direct_image_filters = [], comp_op = [], opacity = []; for (var i = 0; i < definitions.length; i++) { for (var j = 0; j < definitions[i].rules.length; j++) { if (definitions[i].rules[j].name === 'image-filters') { image_filters.push(definitions[i].rules[j]); } + if (definitions[i].rules[j].name === 'image-filters-inflate') { + image_filters_inflate.push(definitions[i].rules[j]); + } if (definitions[i].rules[j].name === 'direct-image-filters') { direct_image_filters.push(definitions[i].rules[j]); } @@ -38,6 +41,10 @@ tree.StyleXML = function(name, attachment, definitions, env) { }).value().join(',') + '"'; } + if (image_filters_inflate.length) { + attrs_xml += ' image-filters-inflate="' + image_filters_inflate[0].value.ev(env).toString() + '"'; + } + if (direct_image_filters.length) { attrs_xml += ' direct-image-filters="' + _.chain(direct_image_filters) // prevent identical filters from being duplicated in the style @@ -46,11 +53,11 @@ tree.StyleXML = function(name, attachment, definitions, env) { }).value().join(',') + '"'; } - if (comp_op.length) { + if (comp_op.length && comp_op[0].value.ev(env).value != 'src-over') { attrs_xml += ' comp-op="' + comp_op[0].value.ev(env).toString() + '"'; } - if (opacity.length) { + if (opacity.length && opacity[0].value.ev(env).value != 1) { attrs_xml += ' opacity="' + opacity[0].value.ev(env).toString() + '"'; } var rule_string = rules.join(''); diff --git a/lib/carto/tree/variable.js b/lib/carto/tree/variable.js index 982da88..3e3cad0 100644 --- a/lib/carto/tree/variable.js +++ b/lib/carto/tree/variable.js @@ -12,10 +12,6 @@ tree.Variable.prototype = { return this.name; }, ev: function(env) { - var variable, - v, - name = this.name; - if (this._css) return this._css; var thisframe = env.frames.filter(function(f) { diff --git a/lib/carto/tree/zoom.js b/lib/carto/tree/zoom.js index 3dd0921..dcdc351 100644 --- a/lib/carto/tree/zoom.js +++ b/lib/carto/tree/zoom.js @@ -58,10 +58,10 @@ tree.Zoom.prototype.toString = function() { return this.zoom; }; -// Covers all zoomlevels from 0 to 22 -tree.Zoom.all = 0x7FFFFF; +tree.Zoom.maxZoom = 25; -tree.Zoom.maxZoom = 22; +// Covers all zoomlevels from 0 to maxZoom +tree.Zoom.all = parseInt(Array(tree.Zoom.maxZoom + 2).join('1'), 2) tree.Zoom.ranges = { 0: 1000000000, @@ -87,7 +87,10 @@ tree.Zoom.ranges = { 20: 750, 21: 500, 22: 250, - 23: 100 + 23: 100, + 24: 50, + 25: 25, + 26: 12.5 }; // Only works for single range zooms. `[XXX....XXXXX.........]` is invalid. @@ -103,7 +106,7 @@ tree.Zoom.prototype.toXML = function() { } if (start > 0) conditions.push(' <MaxScaleDenominator>' + tree.Zoom.ranges[start] + '</MaxScaleDenominator>\n'); - if (end < 22) conditions.push(' <MinScaleDenominator>' + + if (end < tree.Zoom.maxZoom) conditions.push(' <MinScaleDenominator>' + tree.Zoom.ranges[end + 1] + '</MinScaleDenominator>\n'); } return conditions; diff --git a/package.json b/package.json index 00f0a6d..efd793f 100644 --- a/package.json +++ b/package.json @@ -1,14 +1,14 @@ { "name": "carto", - "version": "0.9.5", + "version": "0.16.3", "description": "Mapnik Stylesheet Compiler", "url": "https://github.com/mapbox/carto", "repository": { - "type": "git", - "url": "http://github.com/mapbox/carto.git" + "type": "git", + "url": "http://github.com/mapbox/carto.git" }, "author": { - "name": "MapBox", + "name": "Mapbox", "url": "http://mapbox.com/", "email": "info@mapbox.com" }, @@ -23,12 +23,9 @@ "Konstantin Käfer", "Alexis Sellier <self@cloudhead.net>" ], - "licenses": [{ - "type": "Apache" - }], + "license": "Apache-2.0", "bin": { - "carto": "./bin/carto", - "mml2json.js": "./bin/mml2json.js" + "carto": "./bin/carto" }, "man": "./man/carto.1", "main": "./lib/carto/index", @@ -36,18 +33,24 @@ "node": ">=0.4.x" }, "dependencies": { - "underscore": "~1.4.3", - "mapnik-reference": "~5.0.7", - "xml2js": "~0.2.4", - "optimist": "~0.6.0" + "chroma-js": "~1.1.1", + "husl": "^6.0.1", + "js-yaml": "^3.4.6", + "lodash": "^4.5.1", + "mapnik-reference": "~8.5.3", + "semver": "^5.1.0", + "yargs": "^4.2.0" }, "devDependencies": { - "mocha": "1.12.x", - "jshint": "0.2.x", - "sax": "0.1.x" + "coveralls": "~2.11.8", + "istanbul": "~0.4.2", + "mocha": "~2.4.5", + "mocha-eslint": "^2.0.1", + "sax": "~1.1.5" }, "scripts": { "pretest": "npm install", - "test": "mocha -R spec" + "test": "mocha -R spec --timeout 50000", + "coverage": "istanbul cover ./node_modules/.bin/_mocha && coveralls < ./coverage/lcov.info" } } diff --git a/test/bincarto.test.js b/test/bincarto.test.js new file mode 100644 index 0000000..2fb23f2 --- /dev/null +++ b/test/bincarto.test.js @@ -0,0 +1,55 @@ +var assert = require('assert'); +var exec = require('child_process').exec; +var path = require('path'); +var util = require('util'); +var helper = require('./support/helper'); +var bin = path.resolve(path.join(__dirname, '..', 'bin', 'carto')); +var fs = require('fs'); + +describe('bin/carto', function() { + it('errors on no input', function(done) { + exec(util.format('node %s', bin), function(err, stdout, stderr) { + assert.equal(1, err.code); + assert.equal("carto: no input files ('carto -h or --help' for help)\n", stderr); + done(); + }); + }); + it('errors on unsupported api version', function(done) { + var file = path.join('test', 'rendering', 'identity.mml'); + var api = '1.0.0'; + exec(util.format('node %s -a %s %s', bin, api, file), function(err, stdout, stderr) { + assert.equal(1, err.code); + assert.equal("Mapnik version 1.0.0 is not supported\n", stderr); + done(); + }); + }); + it('errors on wrongly formatted api version', function(done) { + var file = path.join('test', 'rendering', 'identity.mml'); + var api = 'api'; + exec(util.format('node %s -a %s %s', bin, api, file), function(err, stdout, stderr) { + assert.equal(1, err.code); + assert.equal("carto: invalid Mapnik API version. A valid version is e.g. 3.0.10\n", stderr); + done(); + }); + }); + it('renders mml', function(done) { + var file = path.join('test', 'rendering', 'identity.mml'); + exec(util.format('node %s %s', bin, file), function(err, stdout) { + assert.ifError(err); + helper.compareToXMLFile(helper.resultFile(file), stdout, done, [ + helper.removeAbsoluteImages, + helper.removeAbsoluteDatasources + ]); + }); + }); + it('renders mss', function(done) { + var file = path.join('test', 'rendering-mss', 'empty_name.mss'); + exec(util.format('node %s %s', bin, file), function(err, stdout) { + assert.ifError(err); + var expected = file.replace(path.extname(file),'')+'.xml'; + var expected_data = fs.readFileSync(expected, 'utf8'); + assert.equal(stdout,expected_data + '\n'); + done(); + }); + }); +}); diff --git a/test/color.test.js b/test/color.test.js new file mode 100644 index 0000000..ac246fe --- /dev/null +++ b/test/color.test.js @@ -0,0 +1,25 @@ +var assert = require('assert'); +var tree = require('../lib/carto/tree.js'); +require('../lib/carto/functions'); +require('../lib/carto/tree/color'); +require('../lib/carto/tree/dimension'); + +describe('Color', function() { + describe('basic functionality', function() { + it('should be constructed', function() { + var f = new tree.Color([0, 0, 0], 1); + assert.deepEqual(f.getComponents(), {"h":0,"s":0,"l":0,"a":1,"perceptual":false}); + assert.ok(f); + }); + }); + describe('functions', function() { + it('should be constructed', function() { + assert.deepEqual(tree.functions.rgb(0, 0, 0), new tree.Color([0, 0, 0], 1)); + assert.deepEqual(tree.functions.hue(new tree.Color([0, 0, 0], 1)), new tree.Dimension(0)); + assert.deepEqual(tree.functions.saturation(new tree.Color([0, 0, 0], 1)), new tree.Dimension(0, '%')); + assert.deepEqual(tree.functions.lightness(new tree.Color([0, 0, 0], 1)), new tree.Dimension(0, '%')); + assert.deepEqual(tree.functions.alpha(new tree.Color([0, 0, 0], 1)), new tree.Dimension(1)); + assert.deepEqual(tree.functions.greyscale(new tree.Color([0, 0, 0], 1)), new tree.Color([0, 0, 0], 1)); + }); + }); +}); diff --git a/test/comment.test.js b/test/comment.test.js new file mode 100644 index 0000000..bc6b01e --- /dev/null +++ b/test/comment.test.js @@ -0,0 +1,14 @@ +var assert = require('assert'); +var tree = require('../lib/carto/tree.js'); +require('../lib/carto/tree/comment'); + +describe('Comment', function() { + describe('basic functionality', function() { + it('should be constructed', function() { + var f = new tree.Comment('hello world'); + assert.deepEqual(f.toString(), '<!--hello world-->'); + assert.deepEqual(f.ev(), f); + assert.ok(f); + }); + }); +}); diff --git a/test/eclint.test.js b/test/eclint.test.js new file mode 100644 index 0000000..c5cce9f --- /dev/null +++ b/test/eclint.test.js @@ -0,0 +1,13 @@ +var lint = require('mocha-eslint'); + +describe('JS linting', function() { + var paths = [ + 'bin', + 'lib', + 'test' + ]; + + var options = {}; + options.formatter = 'compact'; + lint(paths, options); +}); diff --git a/test/errorhandling.test.js b/test/errorhandling.test.js index 749f293..603c514 100644 --- a/test/errorhandling.test.js +++ b/test/errorhandling.test.js @@ -3,15 +3,12 @@ var path = require('path'), fs = require('fs'); var carto = require('../lib/carto'); -var tree = require('../lib/carto/tree'); var helper = require('./support/helper'); describe('Error handling mml+mss', function() { helper.files('errorhandling', 'mml', function(file) { var basename = path.basename(file); it('should handle errors in ' + basename, function(done) { - var completed = false; - var renderResult; var mml = helper.mml(file); try { new carto.Renderer({ @@ -19,29 +16,19 @@ helper.files('errorhandling', 'mml', function(file) { data_dir: path.join(__dirname, '../data'), local_data_dir: path.join(__dirname, 'rendering'), filename: file - }).render(mml, function (err) { - if (!err) { - throw new Error("*** invalid error handling test found: " + basename + ": all error handling tests should throw!"); - } - var result = helper.resultFile(file); - var output = err.message; - // @TODO for some reason, fs.readFile includes an additional \n - // at the end of read files. Determine why. - fs.readFile(helper.resultFile(file), 'utf8', function(err, data) { - if (!err) assert.deepEqual(output, data.substr(0, data.length - 1)); - done(); - }); - }); - } catch(err) { + }).render(mml); + // should not get here + assert.ok(false); + done(); + } catch (err) { if (err.message.indexOf('***') > -1) throw err; - var result = helper.resultFile(file); var output = err.message; // @TODO for some reason, fs.readFile includes an additional \n // at the end of read files. Determine why. - fs.readFile(helper.resultFile(file), 'utf8', function(err, data) { - if (!err) assert.deepEqual(output, data.substr(0, data.length - 1)); - done(); - }); + // fs.writeFileSync(helper.resultFile(file), output); + var data = fs.readFileSync(helper.resultFile(file), 'utf8'); + assert.deepEqual(output, data); + done(); } }); }); @@ -54,8 +41,6 @@ helper.files('errorhandling', 'mss', function(file) { return; } it('should handle errors in ' + basename, function(done) { - var completed = false; - var renderResult; var mss = helper.mss(file); try { new carto.Renderer({ @@ -65,29 +50,19 @@ helper.files('errorhandling', 'mss', function(file) { // note: we use the basename here so that the expected error result // will match if the style was loaded from mml filename: basename - }).renderMSS(mss, function (err) { - if (!err) { - throw new Error("*** invalid error handling test found: " + basename + ": all error handling tests should throw!"); - } - var result = helper.resultFile(file); - var output = err.message; - // @TODO for some reason, fs.readFile includes an additional \n - // at the end of read files. Determine why. - fs.readFile(helper.resultFile(file), 'utf8', function(err, data) { - if (!err) assert.deepEqual(output, data.substr(0, data.length - 1)); - done(); - }); - }); - } catch(err) { + }).renderMSS(mss); + // should not get here + assert.ok(false); + done(); + } catch (err) { if (err.message.indexOf('***') > -1) throw err; - var result = helper.resultFile(file); var output = err.message; // @TODO for some reason, fs.readFile includes an additional \n // at the end of read files. Determine why. - fs.readFile(helper.resultFile(file), 'utf8', function(err, data) { - if (!err) assert.deepEqual(output, data.substr(0, data.length - 1)); - done(); - }); + // fs.writeFileSync(helper.resultFile(file), output); + var data = fs.readFileSync(helper.resultFile(file), 'utf8'); + assert.deepEqual(output, data); + done(); } }); }); diff --git a/test/errorhandling/bad_filter.mml b/test/errorhandling/bad_filter.mml new file mode 100644 index 0000000..123c427 --- /dev/null +++ b/test/errorhandling/bad_filter.mml @@ -0,0 +1,10 @@ +{ + "Layer": [ + { + "name": "a" + } + ], + "Stylesheet": [ + "bad_filter.mss" + ] +} diff --git a/test/errorhandling/bad_filter.mss b/test/errorhandling/bad_filter.mss new file mode 100644 index 0000000..9aa3d27 --- /dev/null +++ b/test/errorhandling/bad_filter.mss @@ -0,0 +1,3 @@ +Map { } +@x: 'X'; +[CODE='X'][CODE!=@x] { } diff --git a/test/errorhandling/bad_filter.result b/test/errorhandling/bad_filter.result new file mode 100644 index 0000000..4d035c5 --- /dev/null +++ b/test/errorhandling/bad_filter.result @@ -0,0 +1 @@ +bad_filter.mss: [[CODE]!=@x] added to [CODE]=X produces an invalid filter
\ No newline at end of file diff --git a/test/errorhandling/bad_op.mml b/test/errorhandling/bad_op.mml new file mode 100644 index 0000000..c01f1a3 --- /dev/null +++ b/test/errorhandling/bad_op.mml @@ -0,0 +1,15 @@ +{ + "srs": "+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over", + "Stylesheet": [ + "bad_op.mss" + ], + "Layer": [{ + "id": "world", + "name": "world", + "srs": "+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over", + "Datasource": { + "file": "http://tilemill-data.s3.amazonaws.com/test_data/shape_demo.zip", + "type": "shape" + } + }] +} diff --git a/test/errorhandling/bad_op.mss b/test/errorhandling/bad_op.mss new file mode 100644 index 0000000..dac63df --- /dev/null +++ b/test/errorhandling/bad_op.mss @@ -0,0 +1,3 @@ +#world { + line-width: 20% + 2px; +} diff --git a/test/errorhandling/bad_op.result b/test/errorhandling/bad_op.result new file mode 100644 index 0000000..017498c --- /dev/null +++ b/test/errorhandling/bad_op.result @@ -0,0 +1 @@ +bad_op.mss:2:4 If two operands differ, the first must not be %
\ No newline at end of file diff --git a/test/errorhandling/bad_op_2.mml b/test/errorhandling/bad_op_2.mml new file mode 100644 index 0000000..3f8e503 --- /dev/null +++ b/test/errorhandling/bad_op_2.mml @@ -0,0 +1,15 @@ +{ + "srs": "+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over", + "Stylesheet": [ + "bad_op_2.mss" + ], + "Layer": [{ + "id": "world", + "name": "world", + "srs": "+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over", + "Datasource": { + "file": "http://tilemill-data.s3.amazonaws.com/test_data/shape_demo.zip", + "type": "shape" + } + }] +} diff --git a/test/errorhandling/bad_op_2.mss b/test/errorhandling/bad_op_2.mss new file mode 100644 index 0000000..a50ca10 --- /dev/null +++ b/test/errorhandling/bad_op_2.mss @@ -0,0 +1,3 @@ +#world { + line-width: 20px * 2%; +} diff --git a/test/errorhandling/bad_op_2.result b/test/errorhandling/bad_op_2.result new file mode 100644 index 0000000..452c4e0 --- /dev/null +++ b/test/errorhandling/bad_op_2.result @@ -0,0 +1 @@ +bad_op_2.mss:2:4 Percent values can only be added or subtracted from other values
\ No newline at end of file diff --git a/test/errorhandling/color_functions.result b/test/errorhandling/color_functions.result index c400c05..8d27065 100644 --- a/test/errorhandling/color_functions.result +++ b/test/errorhandling/color_functions.result @@ -1 +1 @@ -color_functions.mss:3:31 incorrect arguments given to hsl() +color_functions.mss:3:31 incorrect arguments given to hsl()
\ No newline at end of file diff --git a/test/errorhandling/contradiction.result b/test/errorhandling/contradiction.result index 63c7724..8af476b 100644 --- a/test/errorhandling/contradiction.result +++ b/test/errorhandling/contradiction.result @@ -1 +1 @@ -contradiction.mss:1:37 [[FeatureCla]=] added to [FeatureCla]!= produces an invalid filter +contradiction.mss:1:37 [[FeatureCla]=] added to [FeatureCla]!= produces an invalid filter
\ No newline at end of file diff --git a/test/errorhandling/contradiction_2.result b/test/errorhandling/contradiction_2.result index 99588ed..7269ced 100644 --- a/test/errorhandling/contradiction_2.result +++ b/test/errorhandling/contradiction_2.result @@ -1 +1 @@ -contradiction_2.mss:1:37 [[FeatureCla]!=] added to [FeatureCla]= produces an invalid filter +contradiction_2.mss:1:37 [[FeatureCla]!=] added to [FeatureCla]= produces an invalid filter
\ No newline at end of file diff --git a/test/errorhandling/function_args.result b/test/errorhandling/function_args.result index d58d33f..a189b88 100644 --- a/test/errorhandling/function_args.result +++ b/test/errorhandling/function_args.result @@ -1 +1 @@ -function_args.mss:3:38 unknown function agg-stack-blu(), did you mean agg-stack-blur(2) +function_args.mss:3:38 unknown function agg-stack-blu(), did you mean agg-stack-blur(2)
\ No newline at end of file diff --git a/test/errorhandling/invalid_attachment.mml b/test/errorhandling/invalid_attachment.mml new file mode 100644 index 0000000..05b0bfe --- /dev/null +++ b/test/errorhandling/invalid_attachment.mml @@ -0,0 +1,15 @@ +{ + "srs": "+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over", + "Stylesheet": [ + "invalid_attachment.mss" + ], + "Layer": [{ + "id": "world", + "name": "world", + "srs": "+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over", + "Datasource": { + "file": "http://tilemill-data.s3.amazonaws.com/test_data/shape_demo.zip", + "type": "shape" + } + }] +} diff --git a/test/errorhandling/invalid_attachment.mss b/test/errorhandling/invalid_attachment.mss new file mode 100644 index 0000000..35dc2da --- /dev/null +++ b/test/errorhandling/invalid_attachment.mss @@ -0,0 +1,3 @@ +#world::test::test2 { + polygon-fill: #f00; +} diff --git a/test/errorhandling/invalid_attachment.result b/test/errorhandling/invalid_attachment.result new file mode 100644 index 0000000..2d2bcbc --- /dev/null +++ b/test/errorhandling/invalid_attachment.result @@ -0,0 +1 @@ +invalid_attachment.mss:1:19 Encountered second attachment name. diff --git a/test/errorhandling/invalid_color_in_fn.result b/test/errorhandling/invalid_color_in_fn.result index 88370e8..8106354 100644 --- a/test/errorhandling/invalid_color_in_fn.result +++ b/test/errorhandling/invalid_color_in_fn.result @@ -1 +1 @@ -invalid_color_in_fn.mss:2:34 incorrect arguments given to spin() +invalid_color_in_fn.mss:2:34 incorrect arguments given to spin()
\ No newline at end of file diff --git a/test/errorhandling/invalid_property.result b/test/errorhandling/invalid_property.result index 6daf2ef..d384047 100644 --- a/test/errorhandling/invalid_property.result +++ b/test/errorhandling/invalid_property.result @@ -1 +1 @@ -invalid_property.mss:3:2 Unrecognized rule: polygonopacity. Did you mean polygon-opacity? +invalid_property.mss:3:2 Unrecognized rule: polygonopacity. Did you mean polygon-opacity?
\ No newline at end of file diff --git a/test/errorhandling/invalid_value.mss b/test/errorhandling/invalid_value.mss index 181174b..eb60b56 100644 --- a/test/errorhandling/invalid_value.mss +++ b/test/errorhandling/invalid_value.mss @@ -1,5 +1,4 @@ #world[zoom=5] { text-face-name: 2; - line-rasterizer: 'full'; text-name: 'foo'; } diff --git a/test/errorhandling/invalid_value.result b/test/errorhandling/invalid_value.result index 32dc5e9..e70d73e 100644 --- a/test/errorhandling/invalid_value.result +++ b/test/errorhandling/invalid_value.result @@ -1,2 +1 @@ -invalid_value.mss:2:2 Invalid value for text-face-name, the type font is expected. 2 (of type float) was given. -invalid_value.mss:3:2 Invalid value for line-rasterizer, the type keyword (options: full, fast) is expected. full (of type string) was given. +invalid_value.mss:2:2 Invalid value for text-face-name, the type font is expected. 2 (of type float) was given.
\ No newline at end of file diff --git a/test/errorhandling/invaliddimension.mml b/test/errorhandling/invaliddimension.mml new file mode 100644 index 0000000..9c62378 --- /dev/null +++ b/test/errorhandling/invaliddimension.mml @@ -0,0 +1,15 @@ +{ + "srs": "+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over", + "Stylesheet": [ + "invaliddimension.mss" + ], + "Layer": [{ + "id": "world", + "name": "world", + "srs": "+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over", + "Datasource": { + "file": "http://tilemill-data.s3.amazonaws.com/test_data/shape_demo.zip", + "type": "shape" + } + }] +} diff --git a/test/errorhandling/invaliddimension.mss b/test/errorhandling/invaliddimension.mss new file mode 100644 index 0000000..d753c13 --- /dev/null +++ b/test/errorhandling/invaliddimension.mss @@ -0,0 +1,3 @@ +#world { + line-width: 10wifflewaffles; +} diff --git a/test/errorhandling/invaliddimension.result b/test/errorhandling/invaliddimension.result new file mode 100644 index 0000000..dcf75c2 --- /dev/null +++ b/test/errorhandling/invaliddimension.result @@ -0,0 +1 @@ +invaliddimension.mss:2:4 Invalid unit: 'wifflewaffles'
\ No newline at end of file diff --git a/test/errorhandling/issue119.result b/test/errorhandling/issue119.result new file mode 100644 index 0000000..1204e91 --- /dev/null +++ b/test/errorhandling/issue119.result @@ -0,0 +1 @@ +issue119.mss:2:2 Map properties are not permitted in other rules
\ No newline at end of file diff --git a/test/errorhandling/issue123.result b/test/errorhandling/issue123.result index ed6f8ad..875e815 100644 --- a/test/errorhandling/issue123.result +++ b/test/errorhandling/issue123.result @@ -1 +1 @@ -issue123.mss:3:31 incorrect number of arguments for darken(). 2 expected. +issue123.mss:3:31 incorrect number of arguments for darken(). 2 expected.
\ No newline at end of file diff --git a/test/errorhandling/issue124.result b/test/errorhandling/issue124.result new file mode 100644 index 0000000..3fd8797 --- /dev/null +++ b/test/errorhandling/issue124.result @@ -0,0 +1 @@ +issue124.mss:6:0 missing closing `}`
\ No newline at end of file diff --git a/test/errorhandling/issue297.mss b/test/errorhandling/issue297.mss index a406488..04629a7 100644 --- a/test/errorhandling/issue297.mss +++ b/test/errorhandling/issue297.mss @@ -1,4 +1,4 @@ #t { - text-name: invalid; - text-face-name: "Dejagnu"; + text-name: valid; + text-face-name: 2; } diff --git a/test/errorhandling/issue297.result b/test/errorhandling/issue297.result index 422c58e..c2fe924 100644 --- a/test/errorhandling/issue297.result +++ b/test/errorhandling/issue297.result @@ -1 +1 @@ -issue297.mss:2:2 Invalid value for text-name, the type expression is expected. invalid (of type keyword) was given. +issue297.mss:3:2 Invalid value for text-face-name, the type font is expected. 2 (of type float) was given.
\ No newline at end of file diff --git a/test/errorhandling/issue_204_a.result b/test/errorhandling/issue_204_a.result new file mode 100644 index 0000000..ca4418e --- /dev/null +++ b/test/errorhandling/issue_204_a.result @@ -0,0 +1 @@ +issue_204_a.mss:3:1 missing opening `{`
\ No newline at end of file diff --git a/test/errorhandling/issue_204_b.result b/test/errorhandling/issue_204_b.result new file mode 100644 index 0000000..1ddd28f --- /dev/null +++ b/test/errorhandling/issue_204_b.result @@ -0,0 +1 @@ +issue_204_b.mss:3:3 missing opening `{`
\ No newline at end of file diff --git a/test/errorhandling/issue_204_c.result b/test/errorhandling/issue_204_c.result new file mode 100644 index 0000000..8588127 --- /dev/null +++ b/test/errorhandling/issue_204_c.result @@ -0,0 +1 @@ +issue_204_c.mss:4:0 missing opening `{`
\ No newline at end of file diff --git a/test/errorhandling/issue_218.result b/test/errorhandling/issue_218.result new file mode 100644 index 0000000..2acca5c --- /dev/null +++ b/test/errorhandling/issue_218.result @@ -0,0 +1 @@ +issue_218.mss:5:2 missing opening `{`
\ No newline at end of file diff --git a/test/errorhandling/mapnik_keyword.result b/test/errorhandling/mapnik_keyword.result index d44a1dc..598985b 100644 --- a/test/errorhandling/mapnik_keyword.result +++ b/test/errorhandling/mapnik_keyword.result @@ -1 +1 @@ -mapnik_keyword.mss:1:6 nul is not a valid keyword in a filter expression +mapnik_keyword.mss:1:6 nul is not a valid keyword in a filter expression
\ No newline at end of file diff --git a/test/errorhandling/missing_close.result b/test/errorhandling/missing_close.result index b178bb7..29e63fb 100644 --- a/test/errorhandling/missing_close.result +++ b/test/errorhandling/missing_close.result @@ -1 +1 @@ -missing_close.mss:1:5 Missing closing ] of filter. +missing_close.mss:1:5 Missing closing ] of filter.
\ No newline at end of file diff --git a/test/errorhandling/multi_stylesheets.result b/test/errorhandling/multi_stylesheets.result new file mode 100644 index 0000000..74ff117 --- /dev/null +++ b/test/errorhandling/multi_stylesheets.result @@ -0,0 +1 @@ +multi_stylesheets_b.mss:2:2 Unrecognized rule: polygonopacity. Did you mean polygon-opacity?
\ No newline at end of file diff --git a/test/errorhandling/multi_stylesheets_b.result b/test/errorhandling/multi_stylesheets_b.result new file mode 100644 index 0000000..74ff117 --- /dev/null +++ b/test/errorhandling/multi_stylesheets_b.result @@ -0,0 +1 @@ +multi_stylesheets_b.mss:2:2 Unrecognized rule: polygonopacity. Did you mean polygon-opacity?
\ No newline at end of file diff --git a/test/errorhandling/nopound.result b/test/errorhandling/nopound.result new file mode 100644 index 0000000..eebd7da --- /dev/null +++ b/test/errorhandling/nopound.result @@ -0,0 +1 @@ +nopound.mss:1:0 Invalid code: world { diff --git a/test/errorhandling/notenoughargs.result b/test/errorhandling/notenoughargs.result new file mode 100644 index 0000000..5ee5ba2 --- /dev/null +++ b/test/errorhandling/notenoughargs.result @@ -0,0 +1 @@ +notenoughargs.mss:3:31 incorrect number of arguments for darken(). 2 expected.
\ No newline at end of file diff --git a/test/errorhandling/stylesheet_no_data.mml b/test/errorhandling/stylesheet_no_data.mml new file mode 100644 index 0000000..bf8dea4 --- /dev/null +++ b/test/errorhandling/stylesheet_no_data.mml @@ -0,0 +1,10 @@ +{ + "Layer": [ + { + "name": "a" + } + ], + "Stylesheet": [{ + "id": "b" + }] +} diff --git a/test/errorhandling/stylesheet_no_data.result b/test/errorhandling/stylesheet_no_data.result new file mode 100644 index 0000000..1f4227d --- /dev/null +++ b/test/errorhandling/stylesheet_no_data.result @@ -0,0 +1 @@ +Expecting a stylesheet object of the form { id: 'x', 'data': 'y' } for the Stylesheet property. diff --git a/test/errorhandling/stylesheet_no_id.mml b/test/errorhandling/stylesheet_no_id.mml new file mode 100644 index 0000000..d7f28fc --- /dev/null +++ b/test/errorhandling/stylesheet_no_id.mml @@ -0,0 +1,10 @@ +{ + "Layer": [ + { + "name": "a" + } + ], + "Stylesheet": [{ + "data": "test" + }] +} diff --git a/test/errorhandling/stylesheet_no_id.result b/test/errorhandling/stylesheet_no_id.result new file mode 100644 index 0000000..1f4227d --- /dev/null +++ b/test/errorhandling/stylesheet_no_id.result @@ -0,0 +1 @@ +Expecting a stylesheet object of the form { id: 'x', 'data': 'y' } for the Stylesheet property. diff --git a/test/errorhandling/undefined_variable.result b/test/errorhandling/undefined_variable.result index ff2e384..2a6c6cc 100644 --- a/test/errorhandling/undefined_variable.result +++ b/test/errorhandling/undefined_variable.result @@ -1,3 +1,3 @@ undefined_variable.mss:2:16 variable @something is undefined undefined_variable.mss:3:14 variable @something is undefined -undefined_variable.mss:4:22 variable @something is undefined +undefined_variable.mss:4:22 variable @something is undefined
\ No newline at end of file diff --git a/test/errorhandling/zoom_as_var.result b/test/errorhandling/zoom_as_var.result index 3c5d9fc..b1849cd 100644 --- a/test/errorhandling/zoom_as_var.result +++ b/test/errorhandling/zoom_as_var.result @@ -1 +1 @@ -zoom_as_var.mss:2:2 Cannot do math with type keyword. +zoom_as_var.mss:2:2 Cannot do math with type keyword.
\ No newline at end of file diff --git a/test/errorhandling/zoommax.result b/test/errorhandling/zoommax.result index 23e7cbc..d9a2d2c 100644 --- a/test/errorhandling/zoommax.result +++ b/test/errorhandling/zoommax.result @@ -1 +1 @@ -zoommax.mss:1:6 Only zoom levels between 0 and 22 supported. +zoommax.mss:1:6 Only zoom levels between 0 and 25 supported.
\ No newline at end of file diff --git a/test/filterset.test.js b/test/filterset.test.js index 57500ae..9cb4df2 100644 --- a/test/filterset.test.js +++ b/test/filterset.test.js @@ -225,13 +225,13 @@ describe('Filtersets', function() { f = new tree.Filterset(); f.add({ key: 'TOTAL', op: '!=', val: '11' }); f.add({ key: 'TOTAL', op: '>', val: 11 }); - assert.deepEqual(f.filters, { 'TOTAL>': { key: 'TOTAL', op: '>', val: 11 }}); + assert.deepEqual(f.filters, {"TOTAL!=11":{"key":"TOTAL","op":"!=","val":"11"},"TOTAL>":{"key":"TOTAL","op":">","val":11}}); f = new tree.Filterset(); f.add({ key: 'TOTAL', op: '!=', val: '11' }); f.add({ key: 'TOTAL', op: '>', val: 90 }); - assert.deepEqual(f.filters, { 'TOTAL>': { key: 'TOTAL', op: '>', val: 90 }}); - + assert.deepEqual(f.filters, {"TOTAL!=11":{"key":"TOTAL","op":"!=","val":"11"},"TOTAL>":{"key":"TOTAL","op":">","val":90}}); + f = new tree.Filterset(); f.add({ key: 'TOTAL', op: '!=', val: '11' }); f.add({ key: 'TOTAL', op: '>=', val: 9 }); diff --git a/test/operation.test.js b/test/operation.test.js index 936d6b9..a0a52ab 100644 --- a/test/operation.test.js +++ b/test/operation.test.js @@ -18,27 +18,27 @@ describe('Operation', function() { it('should work with units', function() { var env = { ppi:72, error:function(err) { console.log(err.message); } }; - var o = new tree.Operation("+", [ new tree.Dimension(2.54, 'cm'), new tree.Dimension(0.0254, 'm') ]); - assert.equal(o.ev(env).value, 144); + var o1 = new tree.Operation("+", [ new tree.Dimension(2.54, 'cm'), new tree.Dimension(0.0254, 'm') ]); + assert.equal(o1.ev(env).value, 144); - var o = new tree.Operation("+", [ new tree.Dimension(25.4, 'mm'), new tree.Dimension(72, 'pt') ]); - assert.equal(o.ev(env).value, 144); + var o2 = new tree.Operation("+", [ new tree.Dimension(25.4, 'mm'), new tree.Dimension(72, 'pt') ]); + assert.equal(o2.ev(env).value, 144); - var o = new tree.Operation("+", [ new tree.Dimension(72, 'pt'), new tree.Dimension(6, 'pc') ]); - assert.equal(o.ev(env).value, 144); + var o3 = new tree.Operation("+", [ new tree.Dimension(72, 'pt'), new tree.Dimension(6, 'pc') ]); + assert.equal(o3.ev(env).value, 144); }); it('should work with different ppi', function() { var env = { ppi:300, error:function(err) { console.log(err.message); } }; - var o = new tree.Operation("+", [ new tree.Dimension(2.54, 'cm'), new tree.Dimension(0.0254, 'm') ]); - assert.equal(o.ev(env).value, 600); + var o1 = new tree.Operation("+", [ new tree.Dimension(2.54, 'cm'), new tree.Dimension(0.0254, 'm') ]); + assert.equal(o1.ev(env).value, 600); - var o = new tree.Operation("+", [ new tree.Dimension(25.4, 'mm'), new tree.Dimension(72, 'pt') ]); - assert.equal(o.ev(env).value, 600); + var o2 = new tree.Operation("+", [ new tree.Dimension(25.4, 'mm'), new tree.Dimension(72, 'pt') ]); + assert.equal(o2.ev(env).value, 600); - var o = new tree.Operation("+", [ new tree.Dimension(72, 'pt'), new tree.Dimension(6, 'pc') ]); - assert.equal(o.ev(env).value, 600); + var o3 = new tree.Operation("+", [ new tree.Dimension(72, 'pt'), new tree.Dimension(6, 'pc') ]); + assert.equal(o3.ev(env).value, 600); }); diff --git a/test/quoted.test.js b/test/quoted.test.js index 5ce8069..0ed8807 100644 --- a/test/quoted.test.js +++ b/test/quoted.test.js @@ -12,12 +12,12 @@ describe('Quoted', function() { it('should produce normal output', function() { var f = new tree.Quoted("Tom's & \"<quoted>\""); assert.ok(f); - assert.equal(f.toString(), "Tom's & \"<quoted>\""); + assert.equal(f.toString(), "Tom's & \"<quoted>\""); }); it('should produce xml-friendly output', function() { var f = new tree.Quoted("Tom's & \"<quoted>\""); assert.ok(f); - assert.equal(f.toString(true), "'Tom's & "<quoted>"'"); + assert.equal(f.toString(true), "'Tom\\'s & "<quoted>"'"); }); }); }); diff --git a/test/rendering-mss.test.js b/test/rendering-mss.test.js index 2d31a5d..74ded5e 100644 --- a/test/rendering-mss.test.js +++ b/test/rendering-mss.test.js @@ -4,42 +4,34 @@ var path = require('path'), var existsSync = require('fs').existsSync || require('path').existsSync; var carto = require('../lib/carto'); -var tree = require('../lib/carto/tree'); var helper = require('./support/helper'); describe('Rendering mss', function() { helper.files('rendering-mss', 'mss', function(file) { - it('should render mss ' + path.basename(file) + ' correctly', function(done) { - var completed = false; - var renderResult; + it('should render mss ' + path.basename(file) + ' correctly', function() { var mss = helper.mss(file); - new carto.Renderer({ - paths: [ path.dirname(file) ], - data_dir: path.join(__dirname, '../data'), - local_data_dir: path.join(__dirname, 'rendering'), - filename: file - }).renderMSS(mss, function (err, output) { - if (err) { - if (Array.isArray(err)){ - err.forEach(carto.writeError); - done(); - } else { - throw err; - done(); - } + try { + var output = new carto.Renderer({ + paths: [ path.dirname(file) ], + data_dir: path.join(__dirname, '../data'), + local_data_dir: path.join(__dirname, 'rendering'), + filename: file + }).renderMSS(mss); + } catch (err) { + if (Array.isArray(err)){ + err.forEach(carto.writeError); } else { - var expected = file.replace(path.extname(file),'')+'.xml'; - if (!existsSync(expected)) { - fs.writeFileSync(expected,output); - } - var expected_data = fs.readFileSync(expected).toString(); - assert.equal(output,expected_data); - done(); + throw err; } - }); + } + var expected = file.replace(path.extname(file),'')+'.xml'; + if (!existsSync(expected)) { + fs.writeFileSync(expected,output); + } + var expected_data = fs.readFileSync(expected).toString(); + assert.equal(output.trim(),expected_data.trim()); }); }); }); - diff --git a/test/rendering-mss/color_functions.mss b/test/rendering-mss/color_functions.mss new file mode 100644 index 0000000..4fc3908 --- /dev/null +++ b/test/rendering-mss/color_functions.mss @@ -0,0 +1,68 @@ +#world { + name/line-color: green; + + hex-3/line-color: #BED; + hex-6/line-color: #DEADBE; + + rgb/line-color: rgb(123, 45, 67); + rgba/line-color: rgba(123, 45, 67, 89%); + rgba-d/line-color: rgba(123, 45, 67, .89); + + hsl/line-color: hsl(123, 45%, 67%); + hsl-d/line-color: hsl(123, .45, .67); + hsla/line-color: hsla(123, 45%, 67%, 89%); + hsla-d/line-color: hsla(123, 45%, 67%, .89); + + husl/line-color: husl(123, 45%, 67%); + husl-d/line-color: husl(123, .45, .67); + husla/line-color: husla(123, 45%, 67%, 89%); + husla-d/line-color: husla(123, 45%, 67%, .89); + + hsl-darken/line-color: darken(hsl(209, 81%, 64%), 10%); + hsl-lighten/line-color: lighten(hsl(209, 81%, 64%), 10%); + hsl-saturate/line-color: saturate(hsl(209, 81%, 64%), 10%); + hsl-desaturate/line-color: desaturate(hsl(209, 81%, 64%), 10%); + hsl-spin/line-color: spin(hsl(209, 81%, 64%), 10); + hsl-fadein/line-color: fadein(hsla(209, 81%, 64%, 80%), 10%); + hsl-fadeout/line-color: fadeout(hsla(209, 81%, 64%, 80%), 10%); + hsl-greyscale/line-color: greyscale(hsl(209, 81%, 64%)); + + percept-darken/line-color: darken(husl(209, 81%, 64%), 10%); + percept-lighten/line-color: lighten(husl(209, 81%, 64%), 10%); + percept-saturate/line-color: saturate(husl(209, 81%, 64%), 10%); + percept-desaturate/line-color: desaturate(husl(209, 81%, 64%), 10%); + percept-spin/line-color: spin(husl(209, 81%, 64%), 10); + percept-fadein/line-color: fadein(husla(209, 81%, 64%, 80%), 10%); + percept-fadeout/line-color: fadeout(husla(209, 81%, 64%, 80%), 10%); + percept-greyscale/line-color: greyscale(husl(209, 81%, 64%)); + + force-percept-darken/line-color: darkenp(hsl(209, 81%, 64%), 10%); + force-percept-lighten/line-color: lightenp(hsl(209, 81%, 64%), 10%); + force-percept-saturate/line-color: saturatep(hsl(209, 81%, 64%), 10%); + force-percept-desaturate/line-color: desaturatep(hsl(209, 81%, 64%), 10%); + force-percept-spin/line-color: spinp(hsl(209, 81%, 64%), 10); + force-percept-fadein/line-color: fadeinp(hsla(209, 81%, 64%, 80%), 10%); + force-percept-fadeout/line-color: fadeoutp(hsla(209, 81%, 64%, 80%), 10%); + force-percept-greyscale/line-color: greyscalep(hsl(209, 81%, 64%)); + + mix/line-color: mix(hsl(209, 81%, 64%), hsl(109, 81%, 64%), 20%); + mix2/line-color: mix(#5ba2a2, #0080ff, 50%); + mix3/line-color: mix(#ff0000, #00ff00, 0%); + mix4/line-color: mix(#ff0000, #00ff00, 100%); + mix5/line-color: mix(rgba(255, 0, 0, 0.2), rgba(0, 255, 0, 0.8), 20%); + percept-mix/line-color: mix(hsl(109, 81%, 64%), husl(209, 81%, 64%), 20%); + percept-mix2/line-color: mix(husl(109, 81%, 64%), husl(209, 81%, 64%), 20%); + + multiply/line-color: #f8f4f0 * 0.8; + divide/line-color: #f8f4f0 / 1.2; + add/line-color: #f8f4f0 + 0.8; + subtract/line-color: #f8f4f0 - 0.8; + + multiply2/line-color: #252525 * #020202; + divide2/line-color: #f8f4f0 / #83b7eb; + add2/line-color: #f8f4f0 + #020202; + subtract2/line-color: #f8f4f0 - #83b7eb; + + components/line-color: hsl(hue(hsl(209, 81%, 64%)), saturation(hsl(209, 81%, 64%)), lightness(hsl(209, 81%, 64%))); + percept-components/line-color: husl(huep(hsl(209, 81%, 64%)), saturationp(hsl(209, 81%, 64%)), lightnessp(hsl(209, 81%, 64%))); +} diff --git a/test/rendering-mss/color_functions.xml b/test/rendering-mss/color_functions.xml new file mode 100644 index 0000000..034d791 --- /dev/null +++ b/test/rendering-mss/color_functions.xml @@ -0,0 +1,59 @@ +<Style name="style" filter-mode="first"> + <Rule> + <LineSymbolizer stroke="#008000" /> + <LineSymbolizer stroke="#bbeedd" /> + <LineSymbolizer stroke="#deadbe" /> + <LineSymbolizer stroke="#7b2d43" /> + <LineSymbolizer stroke="rgba(123, 45, 67, 0.89)" /> + <LineSymbolizer stroke="rgba(123, 45, 67, 0.89)" /> + <LineSymbolizer stroke="#85d189" /> + <LineSymbolizer stroke="#85d189" /> + <LineSymbolizer stroke="rgba(133, 209, 137, 0.89)" /> + <LineSymbolizer stroke="rgba(133, 209, 137, 0.89)" /> + <LineSymbolizer stroke="#80af77" /> + <LineSymbolizer stroke="#80af77" /> + <LineSymbolizer stroke="rgba(128, 175, 119, 0.89)" /> + <LineSymbolizer stroke="rgba(128, 175, 119, 0.89)" /> + <LineSymbolizer stroke="#2b8de9" /> + <LineSymbolizer stroke="#87bef2" /> + <LineSymbolizer stroke="#50a6f7" /> + <LineSymbolizer stroke="#62a5e4" /> + <LineSymbolizer stroke="#598dee" /> + <LineSymbolizer stroke="rgba(89, 166, 238, 0.9)" /> + <LineSymbolizer stroke="rgba(89, 166, 238, 0.7)" /> + <LineSymbolizer stroke="#a3a3a3" /> + <LineSymbolizer stroke="#3b8c99" /> + <LineSymbolizer stroke="#56c5d6" /> + <LineSymbolizer stroke="#32aaba" /> + <LineSymbolizer stroke="#59a6b4" /> + <LineSymbolizer stroke="#4aa7c0" /> + <LineSymbolizer stroke="rgba(73, 168, 183, 0.9)" /> + <LineSymbolizer stroke="rgba(73, 168, 183, 0.7)" /> + <LineSymbolizer stroke="#9b9b9b" /> + <LineSymbolizer stroke="#428bcc" /> + <LineSymbolizer stroke="#95bff3" /> + <LineSymbolizer stroke="#46a7f7" /> + <LineSymbolizer stroke="#67a5e5" /> + <LineSymbolizer stroke="#7e9fee" /> + <LineSymbolizer stroke="rgba(89, 166, 238, 0.9)" /> + <LineSymbolizer stroke="rgba(89, 166, 238, 0.7)" /> + <LineSymbolizer stroke="#a1a1a1" /> + <LineSymbolizer stroke="#6fe077" /> + <LineSymbolizer stroke="#2e91d1" /> + <LineSymbolizer stroke="#00ff00" /> + <LineSymbolizer stroke="#ff0000" /> + <LineSymbolizer stroke="rgba(15, 240, 0, 0.68)" /> + <LineSymbolizer stroke="#52b6a4" /> + <LineSymbolizer stroke="#54a8a0" /> + <LineSymbolizer stroke="#c6c3c0" /> + <LineSymbolizer stroke="#cfcbc8" /> + <LineSymbolizer stroke="#f9f5f1" /> + <LineSymbolizer stroke="#f7f3ef" /> + <LineSymbolizer stroke="#4a4a4a" /> + <LineSymbolizer stroke="#020101" /> + <LineSymbolizer stroke="#faf6f2" /> + <LineSymbolizer stroke="#753d05" /> + <LineSymbolizer stroke="#59a6ee" /> + <LineSymbolizer stroke="#57a6ee" /> + </Rule> +</Style> diff --git a/test/rendering-mss/image-filters.mss b/test/rendering-mss/image-filters.mss index 79e611c..a333aa4 100644 --- a/test/rendering-mss/image-filters.mss +++ b/test/rendering-mss/image-filters.mss @@ -1,4 +1,5 @@ #layer { - image-filters:invert(); - direct-image-filters:invert(); + image-filters:invert(); + image-filters-inflate:true; + direct-image-filters:invert(); }
\ No newline at end of file diff --git a/test/rendering-mss/image-filters.xml b/test/rendering-mss/image-filters.xml index 262f405..532cf81 100644 --- a/test/rendering-mss/image-filters.xml +++ b/test/rendering-mss/image-filters.xml @@ -1,2 +1,2 @@ -<Style name="style" filter-mode="first" image-filters="invert" direct-image-filters="invert"> +<Style name="style" filter-mode="first" image-filters="invert" image-filters-inflate="true" direct-image-filters="invert"> </Style>
\ No newline at end of file diff --git a/test/rendering-mss/issue_197.xml b/test/rendering-mss/issue_197.xml index 184c2bf..26fdf91 100644 --- a/test/rendering-mss/issue_197.xml +++ b/test/rendering-mss/issue_197.xml @@ -8,4 +8,4 @@ <MaxScaleDenominator>6500000</MaxScaleDenominator> <MarkersSymbolizer width="1" /> </Rule> -</Style>
\ No newline at end of file +</Style> diff --git a/test/rendering-mss/issue_303.mss b/test/rendering-mss/issue_303.mss new file mode 100644 index 0000000..a64adee --- /dev/null +++ b/test/rendering-mss/issue_303.mss @@ -0,0 +1,4 @@ +#layer["Hello&Goodbye"="yes"] { + text-name: [name]; + text-face-name: "El&Font Bubble Regular"; +}
\ No newline at end of file diff --git a/test/rendering-mss/issue_303.xml b/test/rendering-mss/issue_303.xml new file mode 100644 index 0000000..3eef433 --- /dev/null +++ b/test/rendering-mss/issue_303.xml @@ -0,0 +1,6 @@ +<Style name="style" filter-mode="first"> + <Rule> + <Filter>([Hello&Goodbye] = 'yes')</Filter> + <TextSymbolizer face-name="El&Font Bubble Regular" ><![CDATA[[name]]]></TextSymbolizer> + </Rule> +</Style>
\ No newline at end of file diff --git a/test/rendering-mss/issue_315.mss b/test/rendering-mss/issue_315.mss new file mode 100644 index 0000000..2593d5c --- /dev/null +++ b/test/rendering-mss/issue_315.mss @@ -0,0 +1,9 @@ +#somelayername { + [feature = 'highway_motorway'], + [feature = 'highway_motorway_link'] { + /* code for any motorway */ + [feature = 'highway_motorway_link'] { + /* code specific for links */ + } + } +}
\ No newline at end of file diff --git a/test/rendering-mss/issue_315.xml b/test/rendering-mss/issue_315.xml new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/test/rendering-mss/issue_315.xml diff --git a/test/rendering-mss/issue_339.mss b/test/rendering-mss/issue_339.mss new file mode 100644 index 0000000..6135740 --- /dev/null +++ b/test/rendering-mss/issue_339.mss @@ -0,0 +1 @@ +#poi_label[maki=''] { opacity:.5; }
\ No newline at end of file diff --git a/test/rendering-mss/issue_339.xml b/test/rendering-mss/issue_339.xml new file mode 100644 index 0000000..88ced86 --- /dev/null +++ b/test/rendering-mss/issue_339.xml @@ -0,0 +1,2 @@ +<Style name="style" filter-mode="first" opacity="0.5"> +</Style>
\ No newline at end of file diff --git a/test/rendering-mss/issue_339b.mss b/test/rendering-mss/issue_339b.mss new file mode 100644 index 0000000..7a59067 --- /dev/null +++ b/test/rendering-mss/issue_339b.mss @@ -0,0 +1,4 @@ +#poi_label[maki=''] { + opacity:1.0; + comp-op:src-over; +}
\ No newline at end of file diff --git a/test/rendering-mss/issue_339b.xml b/test/rendering-mss/issue_339b.xml new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/test/rendering-mss/issue_339b.xml diff --git a/test/rendering-mss/issue_370.mss b/test/rendering-mss/issue_370.mss new file mode 100644 index 0000000..6cd02b1 --- /dev/null +++ b/test/rendering-mss/issue_370.mss @@ -0,0 +1,3 @@ +[way_pixels < 192000][way_pixels > 3000] { + line-width: 1; +}
\ No newline at end of file diff --git a/test/rendering-mss/issue_370.xml b/test/rendering-mss/issue_370.xml new file mode 100644 index 0000000..ef7c573 --- /dev/null +++ b/test/rendering-mss/issue_370.xml @@ -0,0 +1,6 @@ +<Style name="style" filter-mode="first"> + <Rule> + <Filter>([way_pixels] < 192000) and ([way_pixels] > 3000)</Filter> + <LineSymbolizer stroke-width="1" /> + </Rule> +</Style>
\ No newline at end of file diff --git a/test/rendering-mss/issue_370_b.mss b/test/rendering-mss/issue_370_b.mss new file mode 100644 index 0000000..97acbdc --- /dev/null +++ b/test/rendering-mss/issue_370_b.mss @@ -0,0 +1,3 @@ +[way_pixels <= 192000][way_pixels >= 3000] { + line-width: 1; +}
\ No newline at end of file diff --git a/test/rendering-mss/issue_370_b.xml b/test/rendering-mss/issue_370_b.xml new file mode 100644 index 0000000..4c3a29d --- /dev/null +++ b/test/rendering-mss/issue_370_b.xml @@ -0,0 +1,6 @@ +<Style name="style" filter-mode="first"> + <Rule> + <Filter>([way_pixels] <= 192000) and ([way_pixels] >= 3000)</Filter> + <LineSymbolizer stroke-width="1" /> + </Rule> +</Style>
\ No newline at end of file diff --git a/test/rendering-mss/issue_443.mss b/test/rendering-mss/issue_443.mss new file mode 100644 index 0000000..0c52cb7 --- /dev/null +++ b/test/rendering-mss/issue_443.mss @@ -0,0 +1,5 @@ +@water: #a0c8f0; + +#water { + polygon-fill: @water - #111; +}
\ No newline at end of file diff --git a/test/rendering-mss/issue_443.xml b/test/rendering-mss/issue_443.xml new file mode 100644 index 0000000..8131285 --- /dev/null +++ b/test/rendering-mss/issue_443.xml @@ -0,0 +1,5 @@ +<Style name="style" filter-mode="first"> + <Rule> + <PolygonSymbolizer fill="#8fb7df" /> + </Rule> +</Style> diff --git a/test/rendering-mss/line-width-zoom.mss b/test/rendering-mss/line-width-zoom.mss new file mode 100644 index 0000000..e7d9741 --- /dev/null +++ b/test/rendering-mss/line-width-zoom.mss @@ -0,0 +1,3 @@ +#layer { + line-width:"@zoom"; +}
\ No newline at end of file diff --git a/test/rendering-mss/line-width-zoom.xml b/test/rendering-mss/line-width-zoom.xml new file mode 100644 index 0000000..2e6d083 --- /dev/null +++ b/test/rendering-mss/line-width-zoom.xml @@ -0,0 +1,5 @@ +<Style name="style" filter-mode="first"> + <Rule> + <LineSymbolizer stroke-width="@zoom" /> + </Rule> +</Style> diff --git a/test/rendering-mss/text-face-name-escaping.mss b/test/rendering-mss/text-face-name-escaping.mss new file mode 100644 index 0000000..ec02985 --- /dev/null +++ b/test/rendering-mss/text-face-name-escaping.mss @@ -0,0 +1,4 @@ +#layer { + text-name: [name]; + text-face-name: "El&Font Bubble Regular"; +} diff --git a/test/rendering-mss/text-face-name-escaping.xml b/test/rendering-mss/text-face-name-escaping.xml new file mode 100644 index 0000000..2c1089a --- /dev/null +++ b/test/rendering-mss/text-face-name-escaping.xml @@ -0,0 +1,5 @@ +<Style name="style" filter-mode="first"> + <Rule> + <TextSymbolizer face-name="El&Font Bubble Regular" ><![CDATA[[name]]]></TextSymbolizer> + </Rule> +</Style>
\ No newline at end of file diff --git a/test/rendering-mss/variable-quoting-of-enum.mss b/test/rendering-mss/variable-quoting-of-enum.mss new file mode 100644 index 0000000..e7655aa --- /dev/null +++ b/test/rendering-mss/variable-quoting-of-enum.mss @@ -0,0 +1,5 @@ +#world { + line-rasterizer: 'fast'; + // carto should collapse to one + line-rasterizer: fast; +} diff --git a/test/rendering-mss/variable-quoting-of-enum.xml b/test/rendering-mss/variable-quoting-of-enum.xml new file mode 100644 index 0000000..bc2b811 --- /dev/null +++ b/test/rendering-mss/variable-quoting-of-enum.xml @@ -0,0 +1,5 @@ +<Style name="style" filter-mode="first"> + <Rule> + <LineSymbolizer rasterizer="fast" /> + </Rule> +</Style> diff --git a/test/rendering-mss/zoom-like-field-name.xml b/test/rendering-mss/zoom-like-field-name.xml new file mode 100644 index 0000000..d47b079 --- /dev/null +++ b/test/rendering-mss/zoom-like-field-name.xml @@ -0,0 +1,6 @@ +<Style name="style" filter-mode="first"> + <Rule> + <Filter>([zoomy] > 2)</Filter> + <PolygonSymbolizer fill="#ff0000" /> + </Rule> +</Style>
\ No newline at end of file diff --git a/test/rendering.test.js b/test/rendering.test.js index 65bcea8..129b10e 100644 --- a/test/rendering.test.js +++ b/test/rendering.test.js @@ -1,63 +1,100 @@ var path = require('path'), + fs = require('fs'), assert = require('assert'), - fs = require('fs'); + semver = require('semver'); var carto = require('../lib/carto'); -var tree = require('../lib/carto/tree'); var helper = require('./support/helper'); describe('Rendering', function() { + + it('should support rendering without Stylesheet (for non-styling/vector tile usage)', function(done) { + + // note: this intentionally does not have a `"Stylesheet":[]` property + // so we should skip trying to validate it + var opts = {"name":"","description":"", + "attribution":"", + "center":[0,0,3], + "format":"pbf", + "minzoom":0, + "maxzoom":6, + "srs":"+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over", + "Layer":[], + "json":"{\"vector_layers\":[]}"}; + var renderer = new carto.Renderer(null).render(opts); + assert.ok(renderer); + done(); + }); + + helper.files('rendering', 'mml', function(file) { + var api = null, + filename = path.basename(file); + if (filename.indexOf('_api') !== -1) { + api = filename.substring(filename.indexOf('_api') + 4, filename.length - 4); + if (!semver.valid(api)) { + api = null; + } + } it('should render ' + path.basename(file) + ' correctly', function(done) { - var completed = false; - var renderResult; var mml = helper.mml(file); - new carto.Renderer({ - paths: [ path.dirname(file) ], - data_dir: path.join(__dirname, '../data'), - local_data_dir: path.join(__dirname, 'rendering'), - filename: file - }).render(mml, function (err, output) { + try { + var env = { + paths: [ path.dirname(file) ], + data_dir: path.join(__dirname, '../data'), + local_data_dir: path.join(__dirname, 'rendering'), + filename: file + }, + renderer = null; + + if (api) { + renderer = new carto.Renderer(env, { + mapnik_version: api + }); + } + else { + renderer = new carto.Renderer(env); + } + var output = renderer.render(mml); + } catch (err) { + if (Array.isArray(err)){ + err.forEach(carto.writeError); + return done(); + } else { + return done(err); + } + } + var result = helper.resultFile(file); + helper.compareToXMLFile(result, output, function(err,expected_json,actual_json) { + var actual = file.replace(path.extname(file),'') + '-actual.json'; + var expected = file.replace(path.extname(file),'') + '-expected.json'; if (err) { - if (Array.isArray(err)){ - err.forEach(carto.writeError); - } else { - throw err; - } + // disabled since it can break on large diffs + /* + console.warn( + helper.stylize("Failure", 'red') + ': ' + + helper.stylize(file, 'underline') + + ' differs from expected result.'); + helper.showDifferences(err); + throw ''; + */ + fs.writeFileSync(actual,JSON.stringify(actual_json,null,4)); + fs.writeFileSync(expected,JSON.stringify(expected_json,null,4)); + throw new Error('failed: xml ' + result + ' in json form does not match expected result:\n' + actual + ' (actual)\n' + expected + ' (expected)'); } else { - var result = helper.resultFile(file); - renderResult = output; - helper.compareToXMLFile(result, output, function(err,expected_json,actual_json) { - completed = true; - var actual = file.replace(path.extname(file),'') + '-actual.json'; - var expected = file.replace(path.extname(file),'') + '-expected.json'; - if (err) { - // disabled since it can break on large diffs - /* - console.warn( - helper.stylize("Failure", 'red') + ': ' + - helper.stylize(file, 'underline') + - ' differs from expected result.'); - helper.showDifferences(err); - throw ''; - */ - fs.writeFileSync(actual,JSON.stringify(actual_json,null,4)); - fs.writeFileSync(expected,JSON.stringify(expected_json,null,4)); - throw new Error('failed: xml ' + result + ' in json form does not match expected result:\n' + actual + ' (actual)\n' + expected + ' (expected)'); - } else { - // cleanup any actual renders that no longer fail - try { - fs.unlinkSync(actual); - fs.unlinkSync(expected); - } catch (err) {} - } - done(); - }, [ - helper.removeAbsoluteImages, - helper.removeAbsoluteDatasources - ]); + // cleanup any actual renders that no longer fail + try { + fs.unlinkSync(actual); + fs.unlinkSync(expected); + } catch (err) { + // do nothing + } } - }); + done(); + }, [ + helper.removeAbsoluteImages, + helper.removeAbsoluteDatasources + ]); // beforeExit(function() { // if (!completed && renderResult) { diff --git a/test/rendering/afghanistan_votes.result b/test/rendering/afghanistan_votes.result index 7570a42..e8959d8 100644 --- a/test/rendering/afghanistan_votes.result +++ b/test/rendering/afghanistan_votes.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="data" filter-mode="first" > diff --git a/test/rendering/background_attributes.result b/test/rendering/background_attributes.result index 971950b..fd5f0a4 100644 --- a/test/rendering/background_attributes.result +++ b/test/rendering/background_attributes.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" background-color="#ffffff" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" background-color="#ffffff" > </Map> diff --git a/test/rendering/buffersize.result b/test/rendering/buffersize.result index 501ac0d..32d30e6 100644 --- a/test/rendering/buffersize.result +++ b/test/rendering/buffersize.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" buffer-size="256" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" buffer-size="256"> <FontSet name="fontset-0"> <Font face-name="Georgia Regular"/> diff --git a/test/rendering/building_height.result b/test/rendering/building_height.result index 393778d..4e492ad 100644 --- a/test/rendering/building_height.result +++ b/test/rendering/building_height.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="world" filter-mode="first" > diff --git a/test/rendering/color_variable.mss b/test/rendering/color_variable.mss deleted file mode 100644 index 249df79..0000000 --- a/test/rendering/color_variable.mss +++ /dev/null @@ -1,4 +0,0 @@ -#world { - polygon-fill: green; - line-color: hsl(30, 40%, 90%); -} diff --git a/test/rendering/combined_class.result b/test/rendering/combined_class.result index 24dea77..889f07b 100644 --- a/test/rendering/combined_class.result +++ b/test/rendering/combined_class.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="just_land" filter-mode="first" > diff --git a/test/rendering/complex_cascades.result b/test/rendering/complex_cascades.result index cab5c7b..e65e25c 100644 --- a/test/rendering/complex_cascades.result +++ b/test/rendering/complex_cascades.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="world" filter-mode="first"> diff --git a/test/rendering/complexfontset.result b/test/rendering/complexfontset.result index e513532..68d1869 100644 --- a/test/rendering/complexfontset.result +++ b/test/rendering/complexfontset.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" > <FontSet name="fontset-0"> <Font face-name="Georgia Regular"/> diff --git a/test/rendering/cross_stylesheet_variable.result b/test/rendering/cross_stylesheet_variable.result index 30079df..4508336 100644 --- a/test/rendering/cross_stylesheet_variable.result +++ b/test/rendering/cross_stylesheet_variable.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" > <Style name="world" filter-mode="first"> diff --git a/test/rendering/data_only.result b/test/rendering/data_only.result index 06fc4fa..d7ae309 100644 --- a/test/rendering/data_only.result +++ b/test/rendering/data_only.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Layer name="world" diff --git a/test/rendering/empty_style.result b/test/rendering/empty_style.result index ed5ffe1..5a87aa0 100644 --- a/test/rendering/empty_style.result +++ b/test/rendering/empty_style.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="world-fill" filter-mode="first"> diff --git a/test/rendering/empty_url.result b/test/rendering/empty_url.result index 40a39eb..fac8060 100644 --- a/test/rendering/empty_url.result +++ b/test/rendering/empty_url.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="world" filter-mode="first" > diff --git a/test/rendering/external_image.result b/test/rendering/external_image.result index fe5fded..b4fbc05 100644 --- a/test/rendering/external_image.result +++ b/test/rendering/external_image.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" > <Style name="world" filter-mode="first"> diff --git a/test/rendering/fadeout.result b/test/rendering/fadeout.result index 53e9633..91ef42d 100644 --- a/test/rendering/fadeout.result +++ b/test/rendering/fadeout.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="world" filter-mode="first"> diff --git a/test/rendering/field.result b/test/rendering/field.result index 716e378..b4a56d9 100644 --- a/test/rendering/field.result +++ b/test/rendering/field.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <FontSet name="fontset-0"> <Font face-name="Georgia Regular"/> diff --git a/test/rendering/field_advanced.result b/test/rendering/field_advanced.result index cf47ac3..9673df2 100644 --- a/test/rendering/field_advanced.result +++ b/test/rendering/field_advanced.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <FontSet name="fontset-0"> <Font face-name="Georgia Regular"/> diff --git a/test/rendering/filter_comparing_fields.result b/test/rendering/filter_comparing_fields.result index adf44cd..93c8eb4 100644 --- a/test/rendering/filter_comparing_fields.result +++ b/test/rendering/filter_comparing_fields.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="world" filter-mode="first" > diff --git a/test/rendering/color_variable.mml b/test/rendering/filterexp.mml index d07083c..28c9176 100644 --- a/test/rendering/color_variable.mml +++ b/test/rendering/filterexp.mml @@ -1,7 +1,7 @@ { "srs": "+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over", "Stylesheet": [ - "color_variable.mss" + "filterexp.mss" ], "Layer": [{ "name": "world", @@ -12,3 +12,4 @@ } }] } + diff --git a/test/rendering/filterexp.mss b/test/rendering/filterexp.mss new file mode 100644 index 0000000..ca51149 --- /dev/null +++ b/test/rendering/filterexp.mss @@ -0,0 +1 @@ +#world [a = 1.2e3][b = 1.2e-3][c = 1.2e+3] { polygon-fill:#fff; } diff --git a/test/rendering/color_variable.result b/test/rendering/filterexp.result index 71357ee..ef6845a 100644 --- a/test/rendering/color_variable.result +++ b/test/rendering/filterexp.result @@ -1,16 +1,16 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" > <Style name="world" filter-mode="first"> <Rule> - <PolygonSymbolizer fill="#008000" /> - <LineSymbolizer stroke="#f0e6db" /> + <Filter>([a] = 1200) and ([b] = 0.0012) and ([c] = 1200)</Filter> + <PolygonSymbolizer fill="#ffffff" /> </Rule> </Style> <Layer name="world" - srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> + srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <StyleName>world</StyleName> <Datasource> <Parameter name="file"><![CDATA[[absolute path]]]></Parameter> diff --git a/test/rendering/filterquote.result b/test/rendering/filterquote.result index f43fc57..c8a4806 100644 --- a/test/rendering/filterquote.result +++ b/test/rendering/filterquote.result @@ -1,11 +1,11 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" > <Style name="world" filter-mode="first"> <Rule> - <Filter>([name2] = ' Sa'ad')</Filter> + <Filter>([name2] = ' Sa\'ad')</Filter> <PolygonSymbolizer fill="#ffffff" /> </Rule> </Style> diff --git a/test/rendering/filters.result b/test/rendering/filters.result index 54dd74e..a667499 100644 --- a/test/rendering/filters.result +++ b/test/rendering/filters.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" > <Style name="world" filter-mode="first"> diff --git a/test/rendering/filtervariable.result b/test/rendering/filtervariable.result index d381928..723c7fc 100644 --- a/test/rendering/filtervariable.result +++ b/test/rendering/filtervariable.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" > <Style name="world" filter-mode="first"> diff --git a/test/rendering/filtervariable2.mml b/test/rendering/filtervariable2.mml new file mode 100644 index 0000000..9ec739e --- /dev/null +++ b/test/rendering/filtervariable2.mml @@ -0,0 +1,10 @@ +{ + "Layer": [ + { + "name": "a" + } + ], + "Stylesheet": [ + "filtervariable2.mss" + ] +} diff --git a/test/rendering/filtervariable2.mss b/test/rendering/filtervariable2.mss new file mode 100644 index 0000000..ff98746 --- /dev/null +++ b/test/rendering/filtervariable2.mss @@ -0,0 +1,6 @@ +Map { } +@x: 'X'; +[CODE!=@x] { + line-color: red; + [zoom>=15] { line-color: green; } +} diff --git a/test/rendering/filtervariable2.result b/test/rendering/filtervariable2.result new file mode 100644 index 0000000..bb99398 --- /dev/null +++ b/test/rendering/filtervariable2.result @@ -0,0 +1,22 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE Map[]> +<Map> + + +<Style name="a" filter-mode="first"> + <Rule> + <MaxScaleDenominator>25000</MaxScaleDenominator> + <Filter>([CODE] != 'X')</Filter> + <LineSymbolizer stroke="#008000" /> + </Rule> + <Rule> + <MinScaleDenominator>25000</MinScaleDenominator> + <Filter>([CODE] != 'X')</Filter> + <LineSymbolizer stroke="#ff0000" /> + </Rule> +</Style> +<Layer name="a" +> + <StyleName>a</StyleName> </Layer> + +</Map> diff --git a/test/rendering/fontset-duplication.result b/test/rendering/fontset-duplication.result index 6697006..5428542 100644 --- a/test/rendering/fontset-duplication.result +++ b/test/rendering/fontset-duplication.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" > <FontSet name="fontset-0"> <Font face-name="Franklin Gothic FS Medium"/> diff --git a/test/rendering/gray_function.result b/test/rendering/gray_function.result index 9891f15..68f0e57 100644 --- a/test/rendering/gray_function.result +++ b/test/rendering/gray_function.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="world" filter-mode="first" > diff --git a/test/rendering/highzooms.result b/test/rendering/highzooms.result index f5734ef..5973517 100644 --- a/test/rendering/highzooms.result +++ b/test/rendering/highzooms.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" > <Style name="world" filter-mode="first"> @@ -31,10 +31,10 @@ </Rule> <Rule> <MaxScaleDenominator>250</MaxScaleDenominator> + <MinScaleDenominator>100</MinScaleDenominator> <PolygonSymbolizer fill="#f00000" /> </Rule> <Rule> - <MinScaleDenominator>5000</MinScaleDenominator> <PolygonSymbolizer fill="#000000" /> </Rule> </Style> diff --git a/test/rendering/identity.result b/test/rendering/identity.result index e89c585..1df3752 100644 --- a/test/rendering/identity.result +++ b/test/rendering/identity.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="world" filter-mode="first"> diff --git a/test/rendering/image_filters.result b/test/rendering/image_filters.result index bccba07..6a39666 100644 --- a/test/rendering/image_filters.result +++ b/test/rendering/image_filters.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="world" filter-mode="first" image-filters="blur,sharpen,agg-stack-blur(2,2)" comp-op="src-in"> diff --git a/test/rendering/imagefilter-duplication.result b/test/rendering/imagefilter-duplication.result index 76b5970..9e9832d 100644 --- a/test/rendering/imagefilter-duplication.result +++ b/test/rendering/imagefilter-duplication.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="world" filter-mode="first" image-filters="agg-stack-blur(3,3)"> diff --git a/test/rendering/instance_names.result b/test/rendering/instance_names.result index 087601d..482d6b1 100644 --- a/test/rendering/instance_names.result +++ b/test/rendering/instance_names.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="world" filter-mode="first" > diff --git a/test/rendering/issue294.result b/test/rendering/issue294.result index f396629..2cd0e7d 100644 --- a/test/rendering/issue294.result +++ b/test/rendering/issue294.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Layer name="world" diff --git a/test/rendering/issue32.result b/test/rendering/issue32.result index 8cb108b..43936e2 100644 --- a/test/rendering/issue32.result +++ b/test/rendering/issue32.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" background-color="#aaaaff" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" background-color="#aaaaff" > <Style name="world" filter-mode="first"> diff --git a/test/rendering/issue60.result b/test/rendering/issue60.result index b8edc97..bf7f8cb 100644 --- a/test/rendering/issue60.result +++ b/test/rendering/issue60.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" > <Style name="world" filter-mode="first"> diff --git a/test/rendering/issue_100_filters.result b/test/rendering/issue_100_filters.result index c9e3210..7707301 100644 --- a/test/rendering/issue_100_filters.result +++ b/test/rendering/issue_100_filters.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" > <Style name="world" filter-mode="first"> diff --git a/test/rendering/issue_239.result b/test/rendering/issue_239.result index 0833fbe..0d67704 100644 --- a/test/rendering/issue_239.result +++ b/test/rendering/issue_239.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Parameters> <Parameter name="bounds">-180,-85.05112877980659,180,85.05112877980659</Parameter> diff --git a/test/rendering/issue_394.mss b/test/rendering/issue_394.mss new file mode 100644 index 0000000..e1f1a55 --- /dev/null +++ b/test/rendering/issue_394.mss @@ -0,0 +1,4 @@ +#world { + line-width: 2; + line-color: #024; +} diff --git a/test/rendering/issue_394_api2.3.0.mml b/test/rendering/issue_394_api2.3.0.mml new file mode 100644 index 0000000..989349e --- /dev/null +++ b/test/rendering/issue_394_api2.3.0.mml @@ -0,0 +1,18 @@ +{ + "srs": "+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over", + "Stylesheet": [ + "issue_394.mss" + ], + "Layer": [{ + "name": "world", + "srs": "+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over", + "Datasource": { + "file": "http://tilemill-data.s3.amazonaws.com/test_data/shape_demo.zip", + "type": "shape" + }, + "properties": { + "minzoom": 7, + "maxzoom": 9 + } + }] +} diff --git a/test/rendering/issue_394_api2.3.0.result b/test/rendering/issue_394_api2.3.0.result new file mode 100644 index 0000000..cc6aaea --- /dev/null +++ b/test/rendering/issue_394_api2.3.0.result @@ -0,0 +1,22 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE Map[]> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" > + + +<Style name="world" filter-mode="first"> + <Rule> + <LineSymbolizer stroke="#002244" stroke-width="2" /> + </Rule> +</Style> +<Layer name="world" + minzoom="750000" + maxzoom="6500000" + srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> + <StyleName>world</StyleName> + <Datasource> + <Parameter name="file"><![CDATA[[absolute path]]]></Parameter> + <Parameter name="type"><![CDATA[shape]]></Parameter> + </Datasource> + </Layer> + +</Map> diff --git a/test/rendering/issue_394_api3.0.0.mml b/test/rendering/issue_394_api3.0.0.mml new file mode 100644 index 0000000..989349e --- /dev/null +++ b/test/rendering/issue_394_api3.0.0.mml @@ -0,0 +1,18 @@ +{ + "srs": "+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over", + "Stylesheet": [ + "issue_394.mss" + ], + "Layer": [{ + "name": "world", + "srs": "+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over", + "Datasource": { + "file": "http://tilemill-data.s3.amazonaws.com/test_data/shape_demo.zip", + "type": "shape" + }, + "properties": { + "minzoom": 7, + "maxzoom": 9 + } + }] +} diff --git a/test/rendering/issue_394_api3.0.0.result b/test/rendering/issue_394_api3.0.0.result new file mode 100644 index 0000000..1e89b00 --- /dev/null +++ b/test/rendering/issue_394_api3.0.0.result @@ -0,0 +1,22 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE Map[]> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" > + + +<Style name="world" filter-mode="first"> + <Rule> + <LineSymbolizer stroke="#002244" stroke-width="2" /> + </Rule> +</Style> +<Layer name="world" + minimum-scale-denominator="750000" + maximum-scale-denominator="6500000" + srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> + <StyleName>world</StyleName> + <Datasource> + <Parameter name="file"><![CDATA[[absolute path]]]></Parameter> + <Parameter name="type"><![CDATA[shape]]></Parameter> + </Datasource> + </Layer> + +</Map> diff --git a/test/rendering/layer_nodatasource.result b/test/rendering/layer_nodatasource.result index 3e78bad..2126449 100644 --- a/test/rendering/layer_nodatasource.result +++ b/test/rendering/layer_nodatasource.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" > <Style name="world" filter-mode="first"> diff --git a/test/rendering/layer_properties.result b/test/rendering/layer_properties.result index d6e604d..b318e55 100644 --- a/test/rendering/layer_properties.result +++ b/test/rendering/layer_properties.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" > <Style name="world" filter-mode="first"> diff --git a/test/rendering/mapnik_keyword.result b/test/rendering/mapnik_keyword.result index 8449c32..8ca39b9 100644 --- a/test/rendering/mapnik_keyword.result +++ b/test/rendering/mapnik_keyword.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="world" filter-mode="first" > diff --git a/test/rendering/modulus.result b/test/rendering/modulus.result index b0f7020..0576929 100644 --- a/test/rendering/modulus.result +++ b/test/rendering/modulus.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <FontSet name="fontset-0"> <Font face-name="Georgia Regular"/> diff --git a/test/rendering/multiple_symbolizers.result b/test/rendering/multiple_symbolizers.result index 11265d3..9839c97 100644 --- a/test/rendering/multiple_symbolizers.result +++ b/test/rendering/multiple_symbolizers.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" > <Style name="world" filter-mode="first"> diff --git a/test/rendering/nesting_class.result b/test/rendering/nesting_class.result index 1db146f..4a39e9b 100644 --- a/test/rendering/nesting_class.result +++ b/test/rendering/nesting_class.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="foo" filter-mode="first" > diff --git a/test/rendering/no_stylesheet.mml b/test/rendering/no_stylesheet.mml new file mode 100644 index 0000000..28bc61c --- /dev/null +++ b/test/rendering/no_stylesheet.mml @@ -0,0 +1,7 @@ +{ + "Layer": [ + { + "name": "a" + } + ] +} diff --git a/test/rendering/no_stylesheet.result b/test/rendering/no_stylesheet.result new file mode 100644 index 0000000..6b1862d --- /dev/null +++ b/test/rendering/no_stylesheet.result @@ -0,0 +1,10 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE Map[]> +<Map> + + +<Layer name="a" +> + </Layer> + +</Map> diff --git a/test/rendering/nominzoom.result b/test/rendering/nominzoom.result index 27755f9..50bb7c9 100644 --- a/test/rendering/nominzoom.result +++ b/test/rendering/nominzoom.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" > <Style name="world" filter-mode="first"> diff --git a/test/rendering/noquote_font.result b/test/rendering/noquote_font.result index a52023a..3535aa0 100644 --- a/test/rendering/noquote_font.result +++ b/test/rendering/noquote_font.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="world" filter-mode="first" > diff --git a/test/rendering/parameters.result b/test/rendering/parameters.result index bdcd737..e6476a5 100644 --- a/test/rendering/parameters.result +++ b/test/rendering/parameters.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" > <Parameters> <Parameter name="bounds">-180,-85,180,85</Parameter> <Parameter name="center">-78,40,8</Parameter> diff --git a/test/rendering/partial_overrides.result b/test/rendering/partial_overrides.result index f3ac99b..fc70ea6 100644 --- a/test/rendering/partial_overrides.result +++ b/test/rendering/partial_overrides.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="world" filter-mode="first" > diff --git a/test/rendering/raster-mesh-size.result b/test/rendering/raster-mesh-size.result index 0ec3811..a66c4be 100644 --- a/test/rendering/raster-mesh-size.result +++ b/test/rendering/raster-mesh-size.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" > <Style name="data" filter-mode="first"> diff --git a/test/rendering/raster.result b/test/rendering/raster.result index 197e25a..76114ec 100644 --- a/test/rendering/raster.result +++ b/test/rendering/raster.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" > <Style name="data" filter-mode="first"> diff --git a/test/rendering/raster_colorizer.result b/test/rendering/raster_colorizer.result index 2295daf..6d57641 100644 --- a/test/rendering/raster_colorizer.result +++ b/test/rendering/raster_colorizer.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="world" filter-mode="first"> diff --git a/test/rendering/raster_colorizer_comma.result b/test/rendering/raster_colorizer_comma.result index 1f24963..0b5625d 100644 --- a/test/rendering/raster_colorizer_comma.result +++ b/test/rendering/raster_colorizer_comma.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="world" filter-mode="first"> diff --git a/test/rendering/raster_colorizer_onestop.result b/test/rendering/raster_colorizer_onestop.result index 651c037..0a67a25 100644 --- a/test/rendering/raster_colorizer_onestop.result +++ b/test/rendering/raster_colorizer_onestop.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="world" filter-mode="first"> diff --git a/test/rendering/rastercolorizer.result b/test/rendering/rastercolorizer.result index 8aeeac5..dfe6679 100644 --- a/test/rendering/rastercolorizer.result +++ b/test/rendering/rastercolorizer.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="world" filter-mode="first"> diff --git a/test/rendering/regex.result b/test/rendering/regex.result index a9d8bab..ee90da3 100644 --- a/test/rendering/regex.result +++ b/test/rendering/regex.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="world" filter-mode="first"> diff --git a/test/rendering/regex_nest.result b/test/rendering/regex_nest.result index e6f372f..fdcb7bb 100644 --- a/test/rendering/regex_nest.result +++ b/test/rendering/regex_nest.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="railway" filter-mode="first" > diff --git a/test/rendering/selector_comment.result b/test/rendering/selector_comment.result index 4450471..fd025c5 100644 --- a/test/rendering/selector_comment.result +++ b/test/rendering/selector_comment.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="world" filter-mode="first"> diff --git a/test/rendering/sharedclass.result b/test/rendering/sharedclass.result index 1369149..8bfb123 100644 --- a/test/rendering/sharedclass.result +++ b/test/rendering/sharedclass.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" > <Style name="ab" filter-mode="first"> diff --git a/test/rendering/simplefontset.result b/test/rendering/simplefontset.result index 97e3900..8efc9af 100644 --- a/test/rendering/simplefontset.result +++ b/test/rendering/simplefontset.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" > <FontSet name="fontset-0"> <Font face-name="Georgia Regular"/> diff --git a/test/rendering/simplevariabletest.result b/test/rendering/simplevariabletest.result index b6fe411..3b14226 100644 --- a/test/rendering/simplevariabletest.result +++ b/test/rendering/simplevariabletest.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" > <Style name="world" filter-mode="first"> diff --git a/test/rendering/style_fold.mml b/test/rendering/style_fold.mml new file mode 100644 index 0000000..dfb09da --- /dev/null +++ b/test/rendering/style_fold.mml @@ -0,0 +1,11 @@ +{ + "Layer": [ + { + "name": "a", + "id": "a" + } + ], + "Stylesheet": [ + "style_fold.mss" + ] +} diff --git a/test/rendering/style_fold.mss b/test/rendering/style_fold.mss new file mode 100644 index 0000000..513e0ad --- /dev/null +++ b/test/rendering/style_fold.mss @@ -0,0 +1,14 @@ +Map { } +#a { + [x = 'X'] { + #a { + line-cap: round; + } + } + [y = 'Y'] { + line-width: 2; + #a { + line-cap: round; + } + } +} diff --git a/test/rendering/style_fold.result b/test/rendering/style_fold.result new file mode 100644 index 0000000..eb5b15e --- /dev/null +++ b/test/rendering/style_fold.result @@ -0,0 +1,20 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE Map[]> +<Map> + + +<Style name="a" filter-mode="first"> + <Rule> + <Filter>([y] = 'Y')</Filter> + <LineSymbolizer stroke-linecap="round" stroke-width="2" /> + </Rule> + <Rule> + <Filter>([x] = 'X')</Filter> + <LineSymbolizer stroke-linecap="round" /> + </Rule> +</Style> +<Layer name="a" +> + <StyleName>a</StyleName> </Layer> + +</Map> diff --git a/test/rendering/style_level_opacity.result b/test/rendering/style_level_opacity.result index f6132f9..fcd03c4 100644 --- a/test/rendering/style_level_opacity.result +++ b/test/rendering/style_level_opacity.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <FontSet name="fontset-0"> <Font face-name="Georgia Regular"/> diff --git a/test/rendering/support4504.result b/test/rendering/support4504.result index 4cb4947..36ebe26 100644 --- a/test/rendering/support4504.result +++ b/test/rendering/support4504.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="countries" filter-mode="first" > diff --git a/test/rendering/symbolizer_order.result b/test/rendering/symbolizer_order.result index 92e9a6a..8932a1e 100644 --- a/test/rendering/symbolizer_order.result +++ b/test/rendering/symbolizer_order.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" > <Style name="world" filter-mode="first"> diff --git a/test/rendering/text_property_overrides.result b/test/rendering/text_property_overrides.result index f16bd5a..2ea8bc6 100644 --- a/test/rendering/text_property_overrides.result +++ b/test/rendering/text_property_overrides.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" > <Style name="world" filter-mode="first"> diff --git a/test/rendering/transforms.mss b/test/rendering/transforms.mss index 297b652..ffa19d1 100644 --- a/test/rendering/transforms.mss +++ b/test/rendering/transforms.mss @@ -2,4 +2,6 @@ #world { point-file: url(foo.png); point-transform: translate( @trans * 2, @trans); + marker-width: 2; + marker-transform: scale(2); } diff --git a/test/rendering/transforms.result b/test/rendering/transforms.result index 6c8e094..4dca4d1 100644 --- a/test/rendering/transforms.result +++ b/test/rendering/transforms.result @@ -1,11 +1,12 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> -<Style name="world" filter-mode="first" > +<Style name="world" filter-mode="first"> <Rule> <PointSymbolizer file="[absolute path]" transform="translate(4,2)" /> + <MarkersSymbolizer width="2" transform="scale(2)" /> </Rule> </Style> <Layer name="world" diff --git a/test/rendering/transforms_backwards.result b/test/rendering/transforms_backwards.result index 7b5a0c3..434cdd5 100644 --- a/test/rendering/transforms_backwards.result +++ b/test/rendering/transforms_backwards.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="world" filter-mode="first" > diff --git a/test/rendering/transforms_field.result b/test/rendering/transforms_field.result index 36555d5..53529b2 100644 --- a/test/rendering/transforms_field.result +++ b/test/rendering/transforms_field.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="world" filter-mode="first" > diff --git a/test/rendering/transforms_single.result b/test/rendering/transforms_single.result index 0f8a790..b53c5ce 100644 --- a/test/rendering/transforms_single.result +++ b/test/rendering/transforms_single.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="world" filter-mode="first"> diff --git a/test/rendering/units.result b/test/rendering/units.result index 068ac7f..3dc1711 100644 --- a/test/rendering/units.result +++ b/test/rendering/units.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="world" filter-mode="first" > diff --git a/test/rendering/unsigned.result b/test/rendering/unsigned.result index aed4756..4a2819b 100644 --- a/test/rendering/unsigned.result +++ b/test/rendering/unsigned.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="world" filter-mode="first" > diff --git a/test/rendering/var_concat.result b/test/rendering/var_concat.result index cec6ddb..c6ed1f3 100644 --- a/test/rendering/var_concat.result +++ b/test/rendering/var_concat.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="world" filter-mode="first" > diff --git a/test/rendering/weird_comments.result b/test/rendering/weird_comments.result index e0e37ba..92b834d 100644 --- a/test/rendering/weird_comments.result +++ b/test/rendering/weird_comments.result @@ -1,5 +1,5 @@ <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" > <Style name="world" filter-mode="first"> diff --git a/test/rendering/weird_comments_2.result b/test/rendering/weird_comments_2.result index 904bc8a..8e73299 100644 --- a/test/rendering/weird_comments_2.result +++ b/test/rendering/weird_comments_2.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="world" filter-mode="first" > diff --git a/test/rendering/weird_simple_comments.result b/test/rendering/weird_simple_comments.result index 886a2fd..51b20a9 100644 --- a/test/rendering/weird_simple_comments.result +++ b/test/rendering/weird_simple_comments.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over"> <Style name="world" filter-mode="first" > diff --git a/test/rendering/zoomlevels.mss b/test/rendering/zoomlevels.mss index fd77577..3725b0e 100644 --- a/test/rendering/zoomlevels.mss +++ b/test/rendering/zoomlevels.mss @@ -10,6 +10,10 @@ polygon-fill: #FF0; } +#world[zoom > 9][zoom <= 11] { + polygon-fill: #DDD; +} + #countries { [zoom=1] { line-width:2; } [zoom=2] { line-width:1.5; } @@ -23,4 +27,4 @@ [zoom=11] { line-width:.4; } [zoom=12] { line-width:.3; } [zoom>12] { line-width:.25; } -}
\ No newline at end of file +} diff --git a/test/rendering/zoomlevels.result b/test/rendering/zoomlevels.result index 6563642..3aa1e24 100644 --- a/test/rendering/zoomlevels.result +++ b/test/rendering/zoomlevels.result @@ -1,10 +1,15 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" > <Style name="world" filter-mode="first"> <Rule> + <MaxScaleDenominator>750000</MaxScaleDenominator> + <MinScaleDenominator>200000</MinScaleDenominator> + <PolygonSymbolizer fill="#dddddd" /> + </Rule> + <Rule> <MinScaleDenominator>50000000</MinScaleDenominator> <PolygonSymbolizer fill="#ffff00" /> </Rule> diff --git a/test/rendering/zoomselector.result b/test/rendering/zoomselector.result index c627919..279493a 100644 --- a/test/rendering/zoomselector.result +++ b/test/rendering/zoomselector.result @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Map[]> -<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" maximum-extent="-20037508.34,-20037508.34,20037508.34,20037508.34"> +<Map srs="+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over" > <Style name="world" filter-mode="first"> diff --git a/test/specificity.test.js b/test/specificity.test.js index 529b89f..cecb80a 100644 --- a/test/specificity.test.js +++ b/test/specificity.test.js @@ -42,7 +42,9 @@ helper.files('specificity', 'mss', function(file) { try { fs.unlinkSync(actual); fs.unlinkSync(expected); - } catch (err) {} + } catch (err) { + // do nothing + } } catch (err) { fs.writeFileSync(actual,JSON.stringify(mss,null,4)); fs.writeFileSync(expected,JSON.stringify(json,null,4)); diff --git a/test/specificity/filters_and_ids.result b/test/specificity/filters_and_ids.result index e04ad1a..09b945e 100644 --- a/test/specificity/filters_and_ids.result +++ b/test/specificity/filters_and_ids.result @@ -1,8 +1,8 @@ [ {"elements":["#world","#countries"],"filters":["[NAME]=United States"],"specificity":[2,0,1,94]}, - {"elements":["#world"],"filters":["[NAME]=United States"],"zoom":"......XXXXXXXXXXXXXXXXX","specificity":[1,0,2,60]}, + {"elements":["#world"],"filters":["[NAME]=United States"],"zoom":"......XXXXXXXXXXXXXXXXXXXX","specificity":[1,0,2,60]}, {"elements":["#world"],"filters":["[NAME]=United States"],"specificity":[1,0,1,33]}, {"elements":["#world"],"filters":["[NAME]=Canada"],"specificity":[1,0,1,7]}, - {"elements":[],"zoom":"......XXXXXXXXXXXXXXXXX","specificity":[0,0,1,146]}, + {"elements":[],"zoom":"......XXXXXXXXXXXXXXXXXXXX","specificity":[0,0,1,146]}, {"elements":[],"filters":["[NAME]=United States"],"specificity":[0,0,1,120]} ] diff --git a/test/support/diff.js b/test/support/diff.js index 8f1f9b1..463fd8c 100644 --- a/test/support/diff.js +++ b/test/support/diff.js @@ -1,7 +1,7 @@ /** * Fragment used to represent a string fragment in the diff. */ -var Fragment = function (string) { +var Fragment = function Fragment(string) { this.content = string; this.equiv = false; }; @@ -38,7 +38,10 @@ var aggregate = function (a, i, k) { var join = function (what, t) { return what.map(function (a) { - if (a) return a.toString(t); + if (a) { + return a.toString(t); + } + return null; }).join(''); }; @@ -115,12 +118,12 @@ var WordDiff = { } // Fill up gaps. - for (var i = 0; i < result.del.length; i++) { - if (result.del[i].equiv && result.del[i].content.length < 3) { - var j = result.ins.indexOf(result.del[i]); - if (result.del[i-1] && result.del[i+1] && result.ins[j-1] && result.ins[j+1] && !result.del[i-1].equiv && !result.del[i+1].equiv && !result.ins[j-1].equiv && !result.ins[j+1].equiv){ - result.del[i].equiv = false; - result.ins[j] = clone(result.del[i]); + for (var i2 = 0; i2 < result.del.length; i2++) { + if (result.del[i2].equiv && result.del[i2].content.length < 3) { + var j2 = result.ins.indexOf(result.del[i2]); + if (result.del[i2-1] && result.del[i2+1] && result.ins[j2-1] && result.ins[j2+1] && !result.del[i2-1].equiv && !result.del[i2+1].equiv && !result.ins[j2-1].equiv && !result.ins[j2+1].equiv){ + result.del[i2].equiv = false; + result.ins[j2] = clone(result.del[i2]); } } } @@ -131,8 +134,8 @@ var WordDiff = { moveToEnd(result[type][i], i, result[type]); // Aggregate subsequent changes to minimize ins/del tags. - for (var i = 0; i < result[type].length; i++) - aggregate(result[type][i], i, result[type]); + for (var i2 = 0; i2 < result[type].length; i2++) + aggregate(result[type][i2], i2, result[type]); }); return result; @@ -159,10 +162,11 @@ var WordDiff = { render: function (args, result) { var join = function (what, type) { return what.map(function (a) { - if (!a) return; + if (!a) return null; if (a.equiv) return a.content; - if (type == 'del') return '\033[31;4m' + a.content + '\033[0m'; - if (type == 'ins') return '\033[32;4m' + a.content + '\033[0m'; + if (type == 'del') return '\x1B[31;4m' + a.content + '\x1B[0m'; + if (type == 'ins') return '\x1B[32;4m' + a.content + '\x1B[0m'; + return null; }).join(''); }; diff --git a/test/support/helper.js b/test/support/helper.js index 4519978..eeb80c5 100644 --- a/test/support/helper.js +++ b/test/support/helper.js @@ -1,10 +1,11 @@ var path = require('path'), - _ = require('underscore'), fs = require('fs'), assert = require('assert'), crypto = require('crypto'), sax = require('sax'), diff = require('./diff').diff, + yaml = require('js-yaml'), + _ = require('lodash'), constants = ((!process.ENOENT) >= 1) ? require('constants') : { ENOENT: process.ENOENT }; @@ -12,11 +13,11 @@ var path = require('path'), var helper = exports; exports.files = function(dir, extension, callback) { - var dir = path.join(__dirname, '..', dir); + dir = path.join(__dirname, '..', dir); extension = new RegExp('\\.' + extension + '$'); fs.readdirSync(dir).forEach(function(filename) { if (extension.test(filename)) { - callback(path.join(dir, filename)); + return callback(path.join(dir, filename)); } }); }; @@ -24,25 +25,32 @@ exports.files = function(dir, extension, callback) { exports.file = function(file, callback) { fs.readFile(file, 'utf-8', function(err, content) { if (err) throw err; - callback(content); + return callback(content); }); }; exports.json = function(file, callback) { fs.readFile(file, 'utf-8', function(err, content) { if (err) throw err; - callback(JSON.parse(content)); + return callback(JSON.parse(content)); }); }; exports.mml = function(file) { - var mml = JSON.parse(fs.readFileSync(file, 'utf-8')); - mml.Stylesheet = _(mml.Stylesheet).map(function(s) { - return { - id: s, - data: fs.readFileSync(path.join(path.dirname(file), s), 'utf-8') - }; - }); + var mml = yaml.safeLoad(fs.readFileSync(file, 'utf-8')); + if (!_.isNil(mml.Stylesheet)) { + mml.Stylesheet = mml.Stylesheet.map(function(s) { + if (path.extname(s) === '.mss') { + return { + id: s, + data: fs.readFileSync(path.join(path.dirname(file), s), 'utf-8') + }; + } + else { + return s; + } + }); + } return mml; }; @@ -84,7 +92,7 @@ exports.parseXML = function(xml, callback) { parser.onclosetag = function() { tree.shift(); - if (tree.length === 1) callback(tree[0]); + if (tree.length === 1) return callback(tree[0]); }; parser.ontext = parser.oncdata = function(text) { @@ -103,10 +111,10 @@ exports.compareToXMLFile = function(filename, second, callback, processors) { }); try { - assert.deepEqual(secondXML, firstXML); - callback(null); + assert.deepEqual(firstXML, secondXML); + return callback(null); } catch (err) { - callback(err,secondXML, firstXML); + return callback(err, firstXML, secondXML); } }); }); @@ -128,8 +136,8 @@ exports.stylize = function(str, style) { 'green' : [32, 39], 'red' : [31, 39] }; - return '\033[' + styles[style][0] + 'm' + str + - '\033[' + styles[style][1] + 'm'; + return '\x1B[' + styles[style][0] + 'm' + str + + '\x1B[' + styles[style][1] + 'm'; }; @@ -163,9 +171,11 @@ exports.rmrf = function rmrf(p) { exports.md5File = function(file, md5, context) { fs.readFile(file, 'binary', function(err, data) { - var hash = crypto.createHash('md5').update(data).digest('hex'); - assert.equal(hash, md5); - context.tests++; + if (!err) { + var hash = crypto.createHash('md5').update(data).digest('hex'); + assert.equal(hash, md5); + context.tests++; + } }); }; diff --git a/test/version.test.js b/test/version.test.js index 3684a44..3195d48 100644 --- a/test/version.test.js +++ b/test/version.test.js @@ -1,16 +1,16 @@ var carto = require('../lib/carto'); -var fs = require('fs'); var path = require('path'); var assert = require('assert'); describe('Version check', function() { it('test version matches package.json version and changelog', function() { - if (parseInt(process.version.split('.')[1]) > 4) { - var info = require('../package.json'); + var info; + if (parseInt(process.version.split('.')[1], 10) > 4) { + info = require('../package.json'); assert.deepEqual(info.version.split('.'), carto.version); } else { - var info = JSON.parse(require('fs').readFileSync(path.join(__dirname,'../package.json'))); + info = JSON.parse(require('fs').readFileSync(path.join(__dirname,'../package.json'))); assert.deepEqual(info.version.split('.'), carto.version); } }); |