入门教程

此教程将帮助您熟悉使用 tpov 库，并了解如何使用它创建一个简单的公交POV视频。

目前此库仅支持类Unix命令（例如Linux，MacOS，*BSD操作系统）。

录制视频

记录您要录制的路线的GPS轨迹，并将其导出为GPX文件。

安装

一个用于管理本教程所需文件的项目文件夹将被创建。

推荐使用Python 3.10以获得最佳兼容性, 且是是唯一测试过的版本。

git clone https://github.com/CyrilSLi/tpov
cd tpov
pip install -r requirements.txt
mkdir .demo

命令行程序安装

  • osmfilter 和 osmconvert: Linux可安装osmctools，Homebrew可安装osmfilter。

  • exiftool: 收录于大多数包管理器中。

  • ffmpeg: 大多数系统中已经预装。

下载地图

从OpenStreetMap下载您要录制的区域的地图。Geofabrik是一个不错的选择。如需请解压地图文件。

用 tpov_convert.py 将地图文件转换为此库可用的格式。这将在当前目录中创建一个以 .out.o5m 结尾的文件。在本教程中，请将输出文件重命名为 map.out.o5m。

把path/to/mapfile替换为地图文件的路径。

python3.10 tpov_convert.py /path/to/mapfile tpov_filter.txt

过滤文件用于过滤地图中的不必要数据。tpov_filter.txt 应该适配大多数情况，但如需可修改。详情请见 osmfilter 维基（英文） 。

警告：处理大型地图文件需要很长时间和大量内存（处理500MB的过滤后的地图可占用30GB内存）。如果地图文件太大，您可以用 osmconvert -b=<x1>,<y1>,<x2>,<y2> 裁剪地图 （详情请见 osmconvert 维基（英文））或从 BBBike 截取并下载自定义的地图区域。

列表选择

在使用过程中，您将需要从列表中选择项目。列表将以以下格式显示：

#  Label  Label  ...
===============  ...
0  Item1  Item2  ...
1  Item3  Item4  ...
2  Item5  Item6  ...
...
Select item(s):

项目用一个类似自然语言的语法进行选择。索引（最左列）与操作符相结合以选择项目。每个项目之间用空格分隔。以下操作符可用：

  • - (减号) 排除选择中的项目或范围。

  • + (加号) 包含选择中的项目或范围。

  • to 配合两侧的索引成为一个包含范围。

一些特殊值用于选择全部或反转选择：

  • all 选择所有项目。将其视为一个索引（在其后使用操作符）。

  • revall 选择所有项目并反转选择。将其视为一个索引。

  • rev 反转选择。将其视为一个操作符（在其后使用索引）。

示例：

  • 0 选择第一个项目。

  • 0 to 2 + 4 选择 0 1 2 4。

  • rev 5 to 8 - 6 选择 8 7 5。

  • all - 3 选择除第四个项目外的所有项目。

提取站点数据

tpov_extract.py 用于提取公交路线的站点数据（名称、坐标、换乘信息等）。目前支持从GTFS、 OSM与百度地图提取数据。

选择以下数据源之一提取站点数据。数据将被保存到项目目录中的 stop_data.json。

GTFS

GTFS是许多公交公司提供数据的常见格式。您通常可以从公交公司的网站或第三方数据源下载GTFS数据。如需请解压。

第一次运行此脚本时，程序将花费一些时间对数据进行排序和索引。

python3.10 tpov_extract.py gtfs /path/to/gtfs .demo/stop_data.json

Enter the route short_name or long_name:

输入您录制的路线的编号（例如66）或名称（例如Canada Line）。

Enter the time the vehicle left the first stop in HH(:mm)(:ss) format:

用24小时制输入时间。允许输入模糊值，如 15（小时）或 15:30（小时与分钟）。

OpenStreetMap

站点数据可从OSM关系中提取。您可以在OpenStreetMap上搜索路线以获取关系ID。关系ID为URL末尾的数字。

python3.10 tpov_extract.py osm relation_id .demo/stop_data.json

使用此方法时请注意数据准确性。 特别是在选择要包含的站点时，请注意 'Role' 列。一些关系有重复的站点，它们分别使用 'stop' 和 'platform' 的 role。

百度地图

百度地图通常拥有最准确的中国公交路线数据。为取得最佳成果，您需要获取一个 SECKEY。您可以通过以下步骤获取 SECKEY：

  • 访问百度地图。

  • 右键选择“检查”或开发者工具。

  • 点击控制台标签页。

  • 在控制台中输入SECKEY并回车。

  • 复制返回的字符串。

python3.10 tpov_extract.py baidu [SECKEY] .demo/stop_data.json

匹配与截断GPS轨迹

请将GPX文件移到项目目录里并命名为 track.gpx。以下命令会将匹配的数据保存为 track.matched.gpx。

python3.10 tpov_match.py match_params_zh.json .demo/track.gpx --map map.out.o5m --stop .demo/stop_data.json

有关匹配参数的详细信息请参阅 匹配参数文档。

轨迹需要截断与扩展以匹配视频（将 /path/to/video 替换为您录制的视频文件的路径）：

python3.10 tpov_truncate.py .demo/track.matched.gpx -e /path/to/video

以上命令使用 exiftool 提取视频开头和结尾时间。在继续操作之前，请检查确保时间准确并如需手动更正。所有时间均为UTC和ISO 8601格式（请注意时区）。您可以用以下命令手动输入时间：

python3.10 tpov_truncate.py .demo/track.matched.gpx -t [开头时间] [结尾时间]

全部处理完的轨迹将被存为 track.matched.truncated.gpx。

创建视频

以下命令将使用 gopro-dashboard-overlay 与一个默认模板创建一个透明叠加视频，可在视频编辑器中与录制的视频合并。

默认模板因大陆限制而使用天地图瓦片，请把 KEY 替换为一个天地图服务器端API密钥。如需使用OSM瓦片，请将 tpov_layout_zh.xml 里的 frame 元素替换为 tpov_layout.xml 里的元素。

此模板适配 Noto Sans CJK 字体，但其他字体可以适用。请将 NotoSansCJK-VF 替换为您想使用的字体的文件路径。

gopro-dashboard.py --use-gpx-only --units-speed kph --units-altitude m --units-distance km --font NotoSansCJK-VF --profile overlay --overlay-size 1920x1080 --layout-xml tpov_layout_zh.xml .demo/overlay.mov --gpx .demo/track.matched.truncated.gpx --map-api-key KEY

如果您不想进一步编辑视频，可替代使用以下命令将叠加与视频合并（将 /path/to/video 替换为您录制的视频文件的路径）：

gopro-dashboard.py --use-gpx-only --units-speed kph --units-altitude m --units-distance km --font NotoSansCJK-VF --overlay-size 1920x1080 --layout-xml tpov_layout_zh.xml /path/to/video .demo/overlay.mp4 --gpx .demo/track.matched.truncated.gpx --map-api-key KEY

kph, m, 与 km 可被替换为其他单位。在 gopro-dashboard-overlay 文档（英文） 中列举了可选的单位。

尾声

您现在有一个显示路线地图、线路编号、速度、时间、海拔、距离、当前道路、上/下一站、换乘信息、路口信息于进度条的公交POV视频。您可以在视频编辑器中进一步编辑视频以添加音乐、过渡等。

此库仍在开发中，可能存在bug。请在 GitHub仓库 上汇报任何问题, 谢谢。