# VTM 引擎使用指南

[VTM](https://github.com/mapsforge/vtm)(Vector Tile Map)地图引擎是一个由OpenScienceMap组织开发的(目前已移交给mapsforge组织管理维护)，Java编写的地图引擎，它是一个支持Android、IOS、桌面端以及Web端的跨平台渲染引擎，同时显示效率也极为优秀。

## 地图特性

- Java地图库
- OpenGL矢量瓦片渲染
- 可设置主题的矢量瓦片图层（渲染主题）
- 支持多个瓦片数据源：
  - OpenScienceMap矢量瓦片
  - 地图矢量地图
  - MBTiles矢量瓦片&栅格瓦片
  - Mapbox矢量瓦片（例如Mapilion、Mapzen、Nextzen、OpenMapTiles）
  - GeoJSON矢量瓦片（例如Mapzen、Nextzen）
  - 栅格瓦片：以四叉树方式存储的栅格图片

## [地图样式详解](https://github.com/mapsforge/vtm/blob/master/docs/Rendertheme.md)
<!-- tabs:start -->
#### **中文**

本文介绍了如何使用基于XML的渲染主题来设置矢量瓦片图层数据样式的映射。

#### **英文**

This article describes how to use XML-based render-themes to style maps.
<!-- tabs:end -->
### 样式介绍
<!-- tabs:start -->
#### **中文**

渲染主题是一个包含了规则和渲染指令的XML文件。这样的文件可以用于自定义渲染地图的可视化样式。vtm地图库带有类似于Osmarender风格的内置渲染主题。也支持加载外部渲染主题文件，可以在运行时通过map.setTheme（ThemeLoader.load（File））方法激活对应的渲染文件。

渲染主题文件的语法和语义与Osmarender规则相似但不完全相同。格式化的渲染主题的描述规则以XML模式文档的形式存在，可以在[仓库这里](https://github.com/mapsforge/vtm/blob/master/resources/rendertheme.xsd)中找到。

我们始终建议您通过研究默认的[内置渲染主题](https://github.com/mapsforge/vtm/blob/master/vtm-themes/resources/assets/vtm/default.xml)来学习如何定义渲染样式。

#### **英文**

A render-theme is an XML file which contains rules and rendering instructions. Such files can be used to customize the visual style of the rendered map. The vtm map library comes with built-in render-themes similar to the Osmarender style. External render-theme files are also supported and can be activated via the map.setTheme(ThemeLoader.load(File)) method at runtime.

Syntax and semantics of render-theme files are similar but not identical to Osmarender rules. A formal render-theme description exists as an XML schema document, it can be found in the repository.

It is always recommended to study the default built-in render theme.
<!-- tabs:end -->

### 规则描述
---
规则元素＜m/＞（match）是主题文件匹配数据的最基础标签，它具有多个属性，用于指定规则如何匹配属性元素，他们都是可选的，没有一个是必需的。

|    属性   |    可选值    |          描述           |    默认值    |
|:---------:|:-----------:|:-----------------------:|:-----------:|
| e         | node</br> way </br> any|定义匹配到的地图要素类型|  any  |
| k         | string       | tile数据源中tag的key.</br>可以通过在多个string中添加"\|"方式定义多个key  |any key|
|v          |string       |tile数据源中tag的value.</br> 可以通过在多个string中添加"\|"方式定义多个value.</br> 可以在“\|”前添加“-”,表示非指定要素可以匹配，例如“-\|A\|B”意味着匹配非A或B的value，注意：“\|”不会单独使用.</br> 如果数据中的tag标签不存在指定的key，可以使用“~”匹配任意value.| any value|
|closed |yes</br>no</br>any|当way要素被匹配时，如果首尾坐标相同，则被认为closed为true| any|
|select   | first</br>when-matched</br>any|当前规则的子规则下的仅第一个匹配规则生效(其他规则忽略)</br>当前闭合规则下所有的匹配项均被选择</br>选择所有(无论是否匹配)|any|
|zoom-min | unsigned byte | 规则匹配的最小zoom | 0 |
|zoom-max | unsigned byte | 规则匹配的最大zoom | 127|

规则定义可以是无限深度来定义渲染指令，并且指令取决于多个规则。这样可以用来定义复杂的渲染规则以避免冗余。
请看下面的示例：
```xml
<m e="way" closed="no">
    <m k="highway" v="motorway">
        <m k="tunnel" v="true|yes">
            …
        </m>
        <m k="tunnel" v="~|no|false">
            …
        </m>
    </m>
</m>
```
下面有一个select标签的使用示例，在下面这段规则中，symbol会显示，而加粗的coption不会被显示，因为只有第一个匹配的子规则会被选择。斜体的caption也会被显示，因为它也是第一个被选中的子规则。
```xml
<m k="railway" v="halt|tram_stop" zoom-min="15" select="first">
    <m v="tram_stop">
        <symbol src="assets:symbols/transport/tram_stop.svg" />
    </m>
    <m v="tram_stop">
        <caption style="bold" dy="20" fill="#af3a3a" k="name" size="12"/>
    </m>
    <m select="when-matched">
        <caption style="italic" dy="-20" fill="#222222" k="name" size="12"/>
    </m>
</m>
```

### 渲染介绍
---
渲染指令指定地图元素的绘制方式。**每个规则元素可以包括任意数量的渲染指令**。除了标签(label)和符号(symbol)之外，所有渲染指令都按照定义的顺序绘制在地图上。
当前版本下支持的渲染样式有如下几类：  
- area
- caption
- circle
- line
- outline
- lineSymbol
- text
- extrusion
- symbol  
每一个渲染要素支持的渲染属性，可以参考对应的[渲染规则xml文件](https://github.com/mapsforge/vtm/blob/master/resources/rendertheme.xsd)。

### 标题元素
---
在顶级标签rendertheme下可以添加下面几个属性描述，用于定义theme中的整体样式。

- map-background: 地图背景颜色(空白区域的颜色描述),这个颜色值应该区别于陆地要素和海洋要素，默认的背景颜色是白色#FFFFFF
- base-stroke-width: 基础线宽，默认值为1
- base-text-scale: 基础文本缩放比例，默认为1
  
```xml
<?xml version="1.0" encoding="UTF-8"?>
<rendertheme xmlns="http://opensciencemap.org/rendertheme" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://opensciencemap.org/rendertheme https://raw.githubusercontent.com/mapsforge/vtm/master/resources/rendertheme.xsd" version="1" map-background="#FFFCFA">
    …
</rendertheme>
```

### Text和Caption标签
---
最常用的显示文本的标签：
|属性|可选值|描述|默认值|
|:---------:|:-----------:|:-----------------------:|:-----------:|
|font-family| default, default_bold, monospace, sans_serif, serif, thin, light, medium, black, condensed| 设置字体| default|
|style| bold, bold_italic, italic, normal| 设置文字样式| normal|
|size| non negative float| 设置文字大小| 0|
|fill| color| 设置文字填充颜色| #000000|
|stroke| color| 设置文字外边框颜色| #000000|
|stroke-width| non negative float| 设置文字外边框宽度| 0|
|dy| float| 设置文字在纵轴上的偏移量| 0|

### 样式(Styles)

---
尽可能以简化地图渲染以及切换地图样式。

#### 样式模板Style patterns

假如你要在不同匹配规则下多次使用对应的样式（文字text、线line、面area或者符号symbol），不用每次都定义一次新的样式，你可以通过定义一个渲染样式后，为它命名一个id，然后在需要使用它是使用use标签来引用它。

```xml
<style-area fade="11" fill="#e8e7e3" id="residential" />

<m closed="yes" e="way" k="highway|building" v="~">
    <m v="residential|commercial|retail|farmyard">
        <area use="residential" />
    </m>
</m>
```

### 样式菜单（略）

### 优先级Priorities

label和symbol是按照优先级绘制在地图上的，默认（最高）的优先级是0，因此，只有当空间尚未被占用或优先级值低于其冲突元素时，才会绘制优先级高于0的内容。

```xml
<m e="node" k="place" v="town" zoom-min="8">
    <caption priority="2" k="name" style="bold" size="14" fill="#333380" stroke="#FFFFFF" stroke-width="2.0"/>
</m>
<m e="node" k="place" v="city" zoom-min="6" zoom-max="6">
    <caption priority="0" k="name" style="bold" size="11" fill="#333380" stroke="#FFFFFF" stroke-width="2.0"/>
</m>
```

### 图标Symbol

Symbol可以使用png图片或是svg矢量图标，VTM在Android和Java环境下支持[Tiny SVG](http://www.w3.org/TR/SVGTiny12/index.html)标准的大部分子集内容。

#### SVG缩放

SVG资源会被自动缩放以适应不同设备的分辨率，但是你也可以通过下面的选项来优化SVG图标的显示大小：

- 如果没有给出大小，svg将呈现为20x20像素乘以设备比例因子和用户设备的缩放调整。
- Symbol-percent: SVG以其默认大小的百分比大小呈现。这是使某些svg比其他svg更小或更大的最佳方法。

- symbol-width/symbol-height：其他参数提供符号的绝对像素大小，同样由比例因子调整。如果只设置了一个尺寸，则根据纵横比计算另一个尺寸。

#### SVG资源

如果你想知道如何设计自己的svg图标，你可以看看[Google's Material Design](https://material.io/design/iconography/system-icons.html)惯例。为了降低SVG的大小，建议使用SVG文件中的重用工具，并删除任何不必要的注释和元数据。