django-tilebundler 0.1-beta3

TileBundler
==========
TileBundler是一个服务，它缓存指定“边界”内提供的层在[mbtiles][6]文件中的所有瓦片，并提供下载的“瓦片集”。更具体地说，TileBundler是一个[Django][1]应用程序，它使用[MapProxy][2]从本地和远程层生成瓦片集。该应用程序的目的是简化瓦片集的创建和分发，尤其是针对需要在断开连接的环境中运行的应用程序。

这是一个开源应用程序，它是在[ROGUE][4]项目下开发的，是[GeoSHAPE][3]生态系统的一部分。您可以将TileBundler集成到其他应用程序中，并创建

注释
=============
- 瓦片集的`geom`可以指定为
- 矩形框：`[-77.47, 38.72, -76.72, 39.08]`
- geojson：`{...}`
- WKT多边形或复合多边形：`POLYGON((-4.5703125 84.0228901101526,165.5859375 84.0228901101526,165.5859375 6.031310707125822,-4.5703125 6.031310707125822,-4.5703125 84.0228901101526))`

- 您可以从本地地理服务器上的图层创建瓦片集。请确保在图层名称前加上`<workspace>:`前缀，例如：`geonode:ne_50m_admin_0_countries`。如果本地服务器已启用ssl但未提供有效证书，则可以提供http url而不是https。

- 如果您的瓦片集服务类型是“瓦片”，它可以是XYZ层或TMS层。这些类型的层在处理边界时有所不同，需要特别注意。这可能意味着在此层上缓存边界可能需要不同的原点，特别是与赤道镜像的原点。这是通过反转几何的y值来实现的。以下是一个示例。在生成瓦片集之前执行此操作。如果您的瓦片集位于世界的错误一侧，并且/或者所有瓦片都颠倒，则在反转后重新生成瓦片集。有关此概念的更多文档可以在此处找到[8]。

- 如果您计划从OpenStreetMap或HIU TMS服务器缓存
- OpenStreetMap - 按以下信息操作。从外部来源（或OpenStreetMap.org的导出功能）获取边界时，请确保边界与赤道镜像。
- HIU TMS - 确保使用翻转URL（例如：洪都拉斯，特古西加尔巴 = http://hiu-maps.net/hot/1.0.0/tegu-15feb2010-flipped/%(z)s/%(x)s/%(y)s.png），并且边界也需与赤道镜像。
- 关于如何镜像赤道的示例将在此处[9]。
- OSM + TMS缓存的示例输出将在此处[10]。

- 目前不支持从GeoServer上的WMS层创建MBTiles。

示例 - 镜像赤道
--------
边界的排序是
[左，下，右，上]

正常OpenStreetMap的弗吉尼亚州费尔法克斯边界
[-77.21917, 38.85804, -77.21295, 38.86337]

下 = -上
38.85804 = -38.86337

上 = -下
38.86337 = -38.85804

镜像OpenStreetMap的弗吉尼亚州费尔法克斯边界
[-77.21917, -38.86337, -77.21295, -38.85804]

&nbsp;&nbsp;&nbsp;

示例输出 - OSM和TMS
--------
*OpenStreetMap: 弗吉尼亚州费尔法克斯*
```
{
"created_at": "2015-08-19T13:58:54.002882",
"created_by"
{
"first_name": "",
"last_name": "",
"resource_uri": "",
"username": "admin"
},
"file_size": 820224,
"file_updated": "2015-08-19T14:26:08.959459",
"geom": "[-77.21917, -38.86337, -77.21295, -38.85804]",
"id": 15,
"layer_name": "osm",
"layer_zoom_start": 0,
"layer_zoom_stop": 18,
"name": "OpenStreetMapdotOrg",
"resource_uri": "/api/tileset/15/",
"server_service_type": "tile",
"server_url": "http://b.tile.openstreetmap.org/%(z)s/%(x)s/%(y)s.png",
"server_username": ""
}
```

*OpenStreetMap Local GeoServer VM: 弗吉尼亚州费尔法克斯*
```
{
"created_at": "2015-08-04T14:14:52.977549",
"created_by"
{
"first_name": "",
"last_name": "",
"resource_uri": "",
"username": "admin"
},
"file_size": 820224,
"file_updated": "2015-08-19T10:41:33.265202",
"geom": "[-77.21917, -38.86337, -77.21295, -38.85804]\r\n",
"id": 4,
"layer_name": "osm",
"layer_zoom_start": 0,
"layer_zoom_stop": 18,
"name": "OSMLocal",
"resource_uri": "/api/tileset/4/",
"server_service_type": "tile",
"server_url": "http://(Location_Of_Your_OSM_VM)/osm_tiles/%(z)s/%(x)s/%(y)s.png",
"server_username": ""
}
```

*TMS - 洪都拉斯，特古西加尔巴：*
```
{
"created_at": "2015-08-04T15:19:49.048624",
"created_by"
{
"first_name": "",
"last_name": "",
"resource_uri": "",
"username": "admin"
},
"file_size": 118784,
"file_updated": "2015-08-19T10:41:33.265202",
"geom": "[-87.20499, 14.09714, -87.20273, 14.09966]",
"id": 7,
"layer_name": "tegu_layer",
"layer_zoom_start": 0,
"layer_zoom_stop": 18,
"name": "HiuTegu_TMS",
"resource_uri": "/api/tileset/7/",
"server_service_type": "tile",
"server_url": "http://hiu-maps.net/hot/1.0.0/tegu-15feb2010-flipped/%(z)s/%(x)s/%(y)s.png",
"server_username": ""
}
```

&nbsp;&nbsp;&nbsp;

API 快速指南
=============
要创建瓦片集对象，请使用django admin API。我们希望在[MapLoom][6]中嵌入瓦片集对象的创建，用户可以在地图中添加所有感兴趣的层，绘制几何形状，并指定瓦片集的缩放范围。他们还可以在[MapLoom][6]内触发生成、查看进度和管理服务器上的瓦片集。

`/api/tileset`
---------------------------
获取所有瓦片集对象的JSON列表

**样本响应**
```
{
"meta": {
"limit": 20,
"next": null,
"offset": 0,
"previous": null,
"total_count": 3
},
"objects": [
{
"created_at": "2015-07-15T12:45:39",
"created_by": {
"first_name": "",
"last_name": "",
"resource_uri": "",
"username": "admin"
},
"filesize": "3145728",
"geom": "POLYGON((-4.5703125 84.0228901101526,165.5859375 84.0228901101526,165.5859375 6.031310707125822,-4.5703125 6.031310707125822,-4.5703125 84.0228901101526))",
"id": 1,
"layer_name": "geonode:ne_50m_admin_0_countries",
"layer_zoom_start": 0,
"layer_zoom_stop": 5,
"name": "country_boundaries",
"resource_uri": "/api/tileset/1/",
"server_service_type": "wms",
"server_url": "http://192.168.99.100/geoserver/wms",
"服务器用户名": "admin"
},
{
"创建时间": "2015-07-15T12:16:07",
"created_by": {
"first_name": "",
"last_name": "",
"resource_uri": "",
"username": "admin"
},
"文件大小": "1368064",
"地理范围": "[-77.6843, 38.4299, -76.3152, 39.2982]",
"ID": 2,
"layer_name": "osm",
"layer_zoom_start": 0,
"图层缩放停止": 12,
"名称": "osm_wms_dc",
"资源URI": "/api/tileset/2/",
"server_service_type": "wms",
"服务器URL": "http://osm.omniscale.net/proxy/service",
"server_username": ""
},
{
"创建时间": "2015-07-15T12:43:56",
"created_by": {
"first_name": "",
"last_name": "",
"resource_uri": "",
"username": "admin"
},
"文件大小": "4706304",
"地理范围": "",
"ID": 3,
"图层名称": "syrus",
"layer_zoom_start": 0,
"layer_zoom_stop": 5,
"名称": "openstreetmap",
"资源URI": "/api/tileset/3/",
"server_service_type": "tile",
"服务器URL": "http://a.tile.openstreetmap.org/%(z)s/%(x)s/%(y)s.png",
"server_username": ""
}
]
}
```


`/api/tileset/1`
---------------------------
以JSON格式获取ID为1的瓦片集对象

**示例响应**
```
{
"创建时间": "2015-07-15T04:33:07",
"created_by": {
"first_name": "",
"last_name": "",
"resource_uri": "",
"username": "admin"
},
"文件大小": "8192000",
"地理范围": "[-83.507, 25.160, -78.030, 29.128]",
"id": 1,
"layer_name": "osm",
"layer_zoom_start": 0,
"图层缩放停止": 12,
"名称": "osm_fl",
"resource_uri": "/api/tileset/1/",
"server_service_type": "wms",
"服务器URL": "http://osm.omniscale.net/proxy/service",
"server_username": ""
}
```

`/api/tileset/1/generate`
-------------------------------------
触发ID为1的瓦片集文件的创建

**预期状态**
- `started`: mbtiles的生成刚刚开始
- `already started`: mbtiles的生成未开始，因为它已经启动并正在运行

**示例响应**
`{"status": "started"}`

`/api/tileset/1/stop`
-------------------------------
停止ID为1的瓦片集的生成

**预期状态**
- `not in progress`: 瓦片集的生成未在进度中
- `stopped`: mbtiles的生成已停止

`/api/tileset/1/status`
---------------------------------
将检索ID为1的瓦片集的状态，并将指示当前瓦片集的状态以及当瓦片集正在生成时的`pending`状态。请注意，当瓦片集生成时，它被保存为.generating文件，而不是.mbtiles，并且它只在生成完成后才替换mbtiles文件。为了保险起见，之前的mbtiles会备份，因为错误的生成触发可能会丢弃可能需要花费很长时间来生成的瓦片集。请注意，如果已经存在mbtiles文件并且瓦片集再次生成，在生成过程中，之前的瓦片集仍然可以用于下载。同样，如果当前的生成被停止，主瓦片集仍然有效和可使用。

**预期状态**
- `not generated`: 对应此瓦片集对象的mbtiles不存在。
- `ready`: 可以下载mbtiles文件。请注意，当瓦片集生成时，它不会替换任何现有的瓦片集，直到它完全生成。如果瓦片集已生成，然后以下`generate`被停止，将使用最后完成的瓦片集。
- `stopped`: mbtiles的生成在完成前已停止。请注意，通常除非瓦片集生成完成，mbtile文件不会替换以前的瓦片集。
- `in progress`: mbtiles的生成目前正在进行中
- `in progress, but log not found`: mbtiles已找到，但未找到相应的日志文件。

**示例响应**
```
{
"current": {
"文件大小": 1155072,
"状态": "ready",
"更新时间": "2015-07-23T04:05:07"
},
"pending": {
"当前缩放级别": "4",
"预计完成时间": "2015-07-23T04:38:40",
"文件大小": 237568,
"进度": "37.50",
"状态": "in progress",
"更新时间": "2015-07-23T04:35:41"
}
}
```

`/api/tileset/1/download`
------------------------------------
下载从ID为1的瓦片集生成的mbtiles文件

**预期状态**
- `not generated`: 找不到对应此瓦片集对象的mbtiles。

------
&nbsp;&nbsp;&nbsp;

已知问题
=============
- 无效的URL将锁定瓦片集的生成。进度不会超过0%，进度日志将反映这一点。
- `注意：如果在虚拟机上，生成的.lck将具有PID，并且rogue_geonode日志文件将打印出存在ServerError。`
- 无效的用户名/密码将锁定瓦片集的生成，并产生与无效URL类似的结果。
- 将生成无效的几何形状，但无法在地图上显示。

[1]: https://django.ac.cn "Django"
[2]: http://mapproxy.org "MapProxy"
[3]: http://geoshape.org "GeoSHAPE"
[4]: http://github.com/rogue-jctd/ "ROGUE"
[5]: http://github.com/ROGUE-JCTD/Arbiter-Android "Arbiter"
[6]: http://github.com/mapbox/mbtiles-spec "mbtiles"
[7]: http://github.com/ROGUE-JCTD/MapLoom "MapLoom"
[8]: https://alastaira.wordpress.com/2011/07/06/converting-tms-tile-coordinates-to-googlebingosm-tile-coordinates/
[9]: https://github.com/ROGUE-JCTD/django-tilebundler#example---mirroring-the-equator
[10]: https://github.com/ROGUE-JCTD/django-tilebundler#example-output---osm-and-tms