Terrocotta :A lightweight tile server

Introduction

最近一直想找一个轻量的影像瓦片的服务端，上周一直在看@Vincent Sarago 基于其自己一套工具 rio-tiler , lambda-proxy 的的瓦片服务的provider，前前后后看了衍生的几个项目，包括lambda-tiler，landsat-tiler，rio-viz等等，经过简单的测试，感觉前两个工具均需要借助lambda才能发挥正常的性能，第三个应用框架用的tornado，考虑了并发问题，但是个单机应用，“移植”起来工程量挺大的，自己试了试放弃了。在单节点的情况下，请求阻塞问题非常严重，自己试着换了几个应用和服务端的组合，都没太大的改善。另外在单节点情况下，这种每个请求都要重新访问一次数据的方式并不经济。

简单的应用不行，在COG详情页看到了，Geotrellis项目，框架用scala实现的，在projects里发现了一个和需求很相近的实验项目，clone下来运行，并不能成功，好像是应用入口有变化，失败了，自己懒的上手改（不知道怎么改），就想着去quick start 里找个小例子，跑个tiles服务应该挺容易的（呸），scala在国内的新手使用体验是真的难，甚至比golang还难，构建工具sbt从maven中心仓库拉文件，乌龟似的启动速度，自己找了那寥寥无几的几篇更换国内源的方法，中间一度想吐🤮，最后换了华为云的源终于能接受了，sbt.build的诡异语法，硬着头皮坚持到io影像，最新版本的api根本跟docs大不一样了，自己照着api东改西改，又被魔鬼般的implict参数坑了十几分钟后：

1$ rm -rf repos/geotrellis-test ~/.sbt
2$ brew rmtree sbt

溜了溜了。

Terracotta

Github的feed真是个好东西，替我推荐了好多有用的玩意，Terracotta也是（太难打了，就叫他陶罐吧）。官方描述如下：

Terracotta is a pure Python tile server that runs as a WSGI app on a dedicated webserver or as a serverless app on AWS Lambda. It is built on a modern Python 3.6 stack, powered by awesome open-source software such as Flask, Zappa, and Rasterio.

提供传统部署和Lambda两种方式，轻量，pure python，都挺符合我的口味，“技术栈”也相对新。

陶罐与同样基于函数计算的lambda-tiler相比，不管是从结构来讲，或是理解起来，都是后者更简单。后者的整个流程非常直接，基于COG的portion请求特性和GDAL的VFS(Virtual File Systems)，不管你的数据在哪，多大，只要告诉我它数据的本地地址或者HTTP地址，它就可以实时的拉取切片。在lambda的环境下，这种方式在性能上不会有太大问题。但对于在国内使用、部署有两个问题。

AWS在国内严重水土不服，给国内使用Lambda造成障碍，Aliyun等国内厂商也有函数计算的服务，但还不太成熟，移植proxy等成本也很高。
一些open access 的数据比如Landsat 8 ，Sentinel-2都托管在S3对象存储上，使用Lambda切片很大程度依赖在AWS各部件上快速访问，但如果在国内提供服务在访问速度上会受很大的影响。

当然，陶罐也是推荐部署在Lambda函数上的，的确，这种方式非常适合动态切片服务，但比Lambda-tiler，它加了一个易用、可靠的头文件的“缓存机制”。

在使用rio-tiler想实现一个可以快速部署在单机上、支持少用户，低请求的动态切片服务时，就曾经想在内存中对同源的数据的头文件缓存下来，因为每一张瓦片都要请求一次源数据获取头文件，在单机环境来看是很浪费的，当时自己的想法有建一个dict，根据数据源地址存储头文件或者建一个sqlite数据库来存储，试了建个dict的方式，但效果并不明显。

而陶罐在业务流程设计上就强制加入了这一点，这使得他在新增数据时会有一个预处理的过程，这比起直接处理有一个延后，但正所谓磨刀不误砍柴工，不得不说，这比起传统的预切片可要快出不少。

除此之外，对数据cog化，头文件注入等流程，陶罐都有很好的api支持。

Quick Start

试用非常简单，先切换到使用的环境，然后

1$ pip install -U pip
2$ pip install terracotta

查看一下版本

1$ terracotta --version
2$ terracotta, version 0.5.3.dev20+gd3e3da1

进入存放tif的目标文件夹，以cog格式对影像进行优化。

1$ terracotta optimize-rasters *.tif -o optimized/

然后将希望serve的影像根据模式匹配存进sqlite数据库文件。

这里想吐槽一下这个功能，开始的时候我以为是一般的正则匹配，搞半天发现是{}的简单匹配，还不能不使用匹配，醉醉哒。

1$ terracotta ingest optimized/LB8_{date}_{band}.tif -o test.sqlite

注入数据库完成后，启动服务

1$ terracotta serve -d test.sqlite

服务默认在:5000启动，还提供了Web UI，需要另行启动，开另一个session：

1$ terracotta connect localhost:5000

这样Web UI也就启动了。这样可以在提示的地址中访问到了。

Deployment

没看lambda的部署方式，因为大致和lambda-tiler方式差不多，因为国内aws访问半身不遂，移植到阿里云，腾讯云的serverless的成本又太高了，所以才放弃了这种方式。

传统的部署方式如下：

我是在centos的云主机上部署的，和docs里的大同小异。

首先新建环境，安装软件和依赖。

1$ conda create --name gunicorn
2$ source activate gunicorn
3$ pip install cython
4$ git clone https://github.com/DHI-GRAS/terracotta.git
5$ cd /path/to/terracotta
6$ pip install -e .
7$ pip install gunicorn

准备数据，例子假设影像文件存放在/mnt/data/rasters/

1$ terracotta optimize-rasters /mnt/data/rasters/*.tif -o /mnt/data/optimized-rasters
2$ terracotta ingest /mnt/data/optimized-rasters/{name}.tif -o /mnt/data/terracotta.sqlite

新建服务，这里自己踩了两个坑，官方例子使用的是nginx反向代理到sock的方式，自己试了多个方法，没成功，也不想深入了解了。

1server {
2    listen 80;
3    server_name VM_IP;
4
5    location / {
6        include proxy_params;
7        proxy_pass http://unix:/mnt/data/terracotta.sock;
8    }
9}

另一个是，应用入口里的入口版本更新过，service里的和上下文的不一样，修改之后如下

 1[Unit]
 2Description=Gunicorn instance to serve Terracotta
 3After=network.target
 4
 5[Service]
 6User=root
 7WorkingDirectory=/mnt/data
 8Environment="PATH=/root/.conda/envs/gunicorn/bin"
 9Environment="TC_DRIVER_PATH=/mnt/data/terracotta.sqlite"
10ExecStart=/root/.conda/envs/gunicorn/bin/gunicorn \
11            --workers 3 --bind 0.0.0.0:5000  -m 007 terracotta.server.app:app
12
13[Install]
14WantedBy=multi-user.target

另外一个地方，使用"0.0.0.0"，使外网可以访问。

官方解释如下：

Absolute path to Gunicorn executable

Number of workers to spawn (2 * cores + 1 is recommended)

Binding to a unix socket file terracotta.sock in the working directory

Dotted path to the WSGI entry point, which consists of the path to the python module containing the main Flask app and the app object: terracotta.server.app:app

服务里需要指定Gunicorn的执行路径，设置workers数量，绑定socket file，指定应用入口。

设置开机启动，启动服务。

1$ sudo systemctl start terracotta
2$ sudo systemctl enable terracotta
3$ sudo systemctl restart terracotta

这样就能看到服务的表述了。

1$ curl localhost:5000/swagger.json

当然，也可以用terracotta自带的client来看一下效果：

1$ terracotta connect localhost:5000

Workflow

对与头文件存储方式的选择，sqlite自然是更方便，但mysql的灵活性和稳定性更高了，在线数据可以实现远程注入。

这里碰到点问题，driver的create方法新建失败，自己没看出问题在哪，就从driver里找出表定义，手动新建所需表。

 1from typing import Tuple
 2
 3import terracotta as tc
 4import pymysql
 5
 6
 7# driver = tc.get_driver("mysql://root:password@ip-address:3306/tilesbox'")
 8key_names = ('type', 'date', 'band')
 9keys_desc = {'type': 'type', 'date': 'data\'s date', 'band': 'raster band'}
10
11_MAX_PRIMARY_KEY_LENGTH = 767 // 4  # Max key length for MySQL is at least 767B
12_METADATA_COLUMNS: Tuple[Tuple[str, ...], ...] = (
13    ('bounds_north', 'REAL'),
14    ('bounds_east', 'REAL'),
15    ('bounds_south', 'REAL'),
16    ('bounds_west', 'REAL'),
17    ('convex_hull', 'LONGTEXT'),
18    ('valid_percentage', 'REAL'),
19    ('min', 'REAL'),
20    ('max', 'REAL'),
21    ('mean', 'REAL'),
22    ('stdev', 'REAL'),
23    ('percentiles', 'BLOB'),
24    ('metadata', 'LONGTEXT')
25)
26_CHARSET: str = 'utf8mb4'
27key_size = _MAX_PRIMARY_KEY_LENGTH // len(key_names)
28key_type = f'VARCHAR({key_size})'
29
30with pymysql.connect(host='ip-address', user='root',
31                     password='password', port=3306,
32                     binary_prefix=True, charset='utf8mb4', db='tilesbox') as cursor:
33    cursor.execute(f'CREATE TABLE terracotta (version VARCHAR(255)) '
34                   f'CHARACTER SET {_CHARSET}')
35
36    cursor.execute('INSERT INTO terracotta VALUES (%s)', [str('0.5.2')])
37
38    cursor.execute(f'CREATE TABLE key_names (key_name {key_type}, '
39                   f'description VARCHAR(8000)) CHARACTER SET {_CHARSET}')
40    key_rows = [(key, keys_desc[key]) for key in key_names]
41    cursor.executemany('INSERT INTO key_names VALUES (%s, %s)', key_rows)
42
43    key_string = ', '.join([f'{key} {key_type}' for key in key_names])
44    cursor.execute(f'CREATE TABLE datasets ({key_string}, filepath VARCHAR(8000), '
45                   f'PRIMARY KEY({", ".join(key_names)})) CHARACTER SET {_CHARSET}')
46
47    column_string = ', '.join(f'{col} {col_type}' for col, col_type
48                              in _METADATA_COLUMNS)
49    cursor.execute(f'CREATE TABLE metadata ({key_string}, {column_string}, '
50                   f'PRIMARY KEY ({", ".join(key_names)})) CHARACTER SET {_CHARSET}')

瓦罐的头文件存储共需要四个表。

Table	Describe
terracotta	存储瓦罐版本信息
metadata	存储数据头文件
Key_names	key类型及描述
Datasets	数据地址及（key）属性信息

服务启动修改如下：

 1[Unit]
 2Description=Gunicorn instance to serve Terracotta
 3After=network.target
 4
 5[Service]
 6User=root
 7WorkingDirectory=/mnt/data
 8Environment="PATH=/root/.conda/envs/gunicorn/bin"
 9Environment="TC_DRIVER_PATH=root:password@ip-address:3306/tilesbox"
10Environment="TC_DRIVER_PROVIDER=mysql"
11
12ExecStart=/root/.conda/envs/gunicorn/bin/gunicorn \
13            --workers 3 --bind 0.0.0.0:5000  -m 007 terracotta.server.app:app
14
15[Install]
16WantedBy=multi-user.target

对于注入本地文件，可参照如下方法：

 1import os
 2import terracotta as tc
 3from terracotta.scripts import optimize_rasters, click_types
 4import pathlib
 5
 6driver = tc.get_driver("/path/to/data/google/tc.sqlite")
 7print(driver.get_datasets())
 8
 9local = "/path/to/data/google/Origin.tiff"
10outdir = "/path/to/data/google/cog"
11filename = os.path.basename(os.path.splitext(local)[0])
12seq = [[pathlib.Path(local)]]
13path = pathlib.Path(outdir)
14# 调用click方法
15optimize_rasters.optimize_rasters.callback(raster_files=seq, output_folder=path, overwrite=True)
16
17outfile = outdir + os.sep + filename + ".tif"
18
19driver.insert(filepath=outfile, keys={'nomask': 'yes'})
20
21print(driver.get_datasets())
22

运行如下

 1Optimizing rasters:   0%|          | [00:00<?, file=Origin.tiff]
 2
 3Reading:   0%|          | 0/992
 4Reading:  12%|█▎        | 124/992
 5Reading:  21%|██▏       | 211/992
 6Reading:  29%|██▉       | 292/992
 7Reading:  37%|███▋      | 370/992
 8Reading:  46%|████▌     | 452/992
 9Reading:  54%|█████▍    | 534/992
10Reading:  62%|██████▏   | 612/992
11Reading:  70%|██████▉   | 693/992
12Reading:  78%|███████▊  | 771/992
13Reading:  87%|████████▋ | 867/992
14                                 
15Creating overviews:   0%|          | 0/1
16                                        
17Compressing:   0%|          | 0/1
18Optimizing rasters: 100%|██████████| [00:06<00:00, file=Origin.tiff]
19{('nomask',): '/path/to/data/google/nomask.tif', ('yes',): '/path/to/data/google/cog/Origin.tif'}
20
21Process finished with exit code 0
22

稍加修改就可以传入input 文件名和 output的文件夹名，就能实现影像优化、注入的工作流。