mapillary_tools是一个命令行工具，可以将标记地理信息的图像和视频上传到Mapillary。

# Install mapillary_tools
pip install mapillary_tools

# Process and upload images and videos in the directory
mapillary_tools process_and_upload MY_CAPTURE_DIR

# List all commands
mapillary_tools --help

• 支持的文件格式
• 安装
• 使用
  • 处理和上传
  • 处理
  • 上传
• 高级使用
  • 本地视频处理
  • 使用GPX进行地理标记
  • 认证
  • 图像描述
  • 压缩图像
• 开发

支持的文件格式

mapillary_tools可以上传图像和视频。

图像格式

mapillary_tools支持JPG/JEPG图像 (.jpg, .jpeg)，以下EXIF标记至少需要

• GPS经度
• GPS纬度
• 原始日期/时间或GPS日期/时间

视频格式

mapillary_tools支持包含以下遥测结构的视频 (.mp4, .360)

• GPMF：主要适用于GoPro视频
  • GoPro HERO系列（从5到11代）
  • GoPro MAX
• CAMM：由多款相机支持的开放标准遥测规范
  • Insta360 Pro2
  • Insta360 Titan
  • Ricoh Theta X
  • Labpano
  • 等等...
• BlackVue视频
  • DR900S-1CH
  • DR900X Plus

安装

独立可执行文件

1. 从发布中下载您平台上的最新可执行文件。
2. 将可执行文件移动到您的系统$PATH

注意：如果在macOS上看到错误“mapillary_tools已损坏，无法打开”，请尝试清除扩展属性

xattr -c mapillary_tools

通过pip安装

要安装或升级到最新稳定版本

pip install --upgrade mapillary_tools

如果您迫不及待想要安装开发中的最新功能，请从GitHub安装

pip install --upgrade git+https://github.com/mapillary/mapillary_tools

注意：如果您看到“权限被拒绝”错误，请尝试使用sudo运行上述命令，或在您的本地虚拟环境中安装它（推荐）。

Android设备安装

需要命令行程序，如Termux。无需root权限即可安装。以下命令将在Termux上安装Python 3、pip3、git以及mapillary_tools所需的所有库：

pkg install python git build-essential libgeos openssl libjpeg-turbo libexpat libexpat-static
pip install --upgrade pip wheel
pip install --upgrade mapillary_tools

Termux必须访问设备内部存储以处理和上传图像。为此，请使用以下命令：

termux-setup-storage

最后，在运行Android 11的设备上，如果处理图像时它们位于共享内部存储中，则使用命令行程序处理mapillary_tools时图像处理速度会非常慢。建议在运行mapillary_tools之前先将图像移动到命令行程序的原生目录。例如，使用Termux，如果图像存储在文件夹内部存储/DCIM/mapillaryimages中，则以下命令将把该文件夹从共享存储移动到Termux：

mv -v storage/dcim/mapillaryimages mapillaryimages

使用

处理和上传

对于大多数用户，process_and_upload是必用的命令。

# Process and upload all images and videos in MY_CAPTURE_DIR and its subfolders, and all videos under MY_VIDEO_DIR
mapillary_tools process_and_upload MY_CAPTURE_DIR MY_VIDEO_DIR/*.mp4

如果发生任何处理错误，例如图像中找不到GPS，mapillary_tools将以非零状态码退出。要忽略这些错误并继续上传剩余内容：

# Skip process errors and upload to the specified user and organization
mapillary_tools process_and_upload MY_CAPTURE_DIR MY_VIDEO_DIR/*.mp4 \
    --skip_process_errors \
    --user_name "my_username" \
    --organization_key "my_organization_id"

process_and_upload命令将连续运行process和upload命令，同时合并必需和可选参数。上述命令相当于：

mapillary_tools process MY_CAPTURE_DIR MY_VIDEO_DIR/*.mp4 \
    --skip_process_errors \
    --desc_path /tmp/mapillary_description_file.json

mapillary_tools upload MY_CAPTURE_DIR MY_VIDEO_DIR/*.mp4 \
    --desc_path /tmp/mapillary_description_file.json \
    --user_name "my_username" \
    --organization_key "my_organization_id"

处理

process命令是一个中间步骤，它从图像和视频中提取元数据，并将它们写入图像描述文件。用户应将其传递给upload命令。

mapillary_tools process MY_CAPTURE_DIR MY_VIDEO_DIR/*.mp4

使用自定义距离和角度进行重复检查

# Mark images that are 3 meters closer to its previous one as duplicates.
# Duplicates won't be uploaded
mapillary_tools process MY_CAPTURE_DIR \
    --duplicate_distance 3 \
    --duplicate_angle 360  # Set 360 to disable angle check

使用自定义截止距离或自定义捕获时间间隔拆分序列

# If two successive images are 100 meters apart,
# OR their capture times are 120 seconds apart,
# then split the sequence from there
mapillary_tools process MY_CAPTURE_DIR \
    --offset_angle 90 \
    --cutoff_distance 100 \
    --cutoff_time 120 \

上传

处理后，您应该得到图像描述文件。将其传递给upload命令以上传它们。

# Upload processed images and videos to the specified user account and organization
mapillary_tools upload  MY_CAPTURE_DIR \
    --desc_path /tmp/mapillary_image_description.json \
    --user_name "my_username" \
    --organization_key "my_organization_id"

高级使用

本地视频处理

本地视频处理将视频采样成一系列样本图像，并确保图像带有地理标签并准备好上传。它使用户能够更多地控制采样过程，例如，可以指定采样距离来控制密度。此外，样本图像的文件大小比视频小，因此可以节省带宽。

安装FFmpeg

本地视频处理需要FFmpeg。您可以从此处下载ffmpeg和ffprobe，或者使用您喜欢的包管理器进行安装。

视频处理

mapillary_tools首先从视频的遥测结构中提取GPS轨迹，然后沿着GPS轨迹定位视频帧。当所有帧都定位后，它默认每3米提取一个帧（图像）。

# Sample videos in MY_VIDEO_DIR and write the sample images in MY_SAMPLES with a custom sampling distance
mapillary_tools video_process MY_VIDEO_DIR MY_SAMPLES --video_sample_distance 5
# The command above is equivalent to
mapillary_tools sample_video MY_VIDEO_DIR MY_SAMPLES --video_sample_distance 5
mapillary_tools process MY_SAMPLES

要连续处理和上传样本图像，请运行：

mapillary_tools video_process_and_upload MY_VIDEO_DIR MY_SAMPLES --video_sample_distance 5
# The command above is equivalent to
mapillary_tools video_process MY_VIDEO_DIR MY_SAMPLES --video_sample_distance 5 --desc_path=/tmp/mapillary_description.json
mapillary_tools upload MY_SAMPLES --desc_path=/tmp/mapillary_description.json

使用GPX进行地理标记

如果您使用外部GPS设备进行绘图，则需要使用外部GPS轨迹为捕获进行地理标签。

要使用GPX文件为图像添加地理标签，捕获时间（从EXIF标签“原始日期/时间”或“GPS日期/时间”中提取）至少是必需的。它用于在GPS轨迹上定位图像。

mapillary_tools process MY_IMAGE_DIR --geotag_source "gpx" --geotag_source_path MY_EXTERNAL_GPS.gpx

要使用GPX文件为视频添加地理标签，需要视频开始时间（视频创建时间减去视频持续时间）以在GPS轨迹上定位样本图像。

# Geotagging with GPX works with interval-based sampling only,
# the two options --video_sample_distance -1 --video_sample_interval 2 are therefore required
# to switch from the default distance-based sampling to the legacy interval-based sampling
mapillary_tools video_process MY_VIDEO_DIR \
    --geotag_source "gpx" \
    --geotag_source_path MY_EXTERNAL_GPS.gpx \
    --video_sample_distance -1 --video_sample_interval 2

理想情况下，GPS设备和捕获设备应使用相同的时钟以同步时间戳。如果不一致，通常情况下，图像位置将会偏移。为此，mapillary_tools提供了一个选项--interpolation_offset_time N，它将N秒添加到图像捕获时间，以同步时间戳。

# The capture device's clock is 8 hours (i.e. -8 * 3600 = -28800 seconds) ahead of the GPS device's clock
mapillary_tools process MY_IMAGE_DIR \
    --geotag_source "gpx" \
    --geotag_source_path MY_EXTERNAL_GPS.gpx \
    --interpolation_offset_time -28800

另一个选项--interpolation_use_gpx_start_time将您的图像移动到与GPS轨迹开始处对齐。当您可以确认您在同时开始GPS录制和捕获，或者有一个已知的延迟时，这很有用。

# Start capturing 2.5 seconds after start GPS recording
mapillary_tools video_process MY_VIDEO_DIR \
    --geotag_source "gpx" \
    --geotag_source_path MY_EXTERNAL_GPS.gpx \
    --interpolation_use_gpx_start_time \
    --interpolation_offset_time 2.5 \
    --video_sample_distance -1 --video_sample_interval 2

新的视频地理标签功能（实验性）

作为实验性功能，mapillary_tools现在可以

• 从GPX和NMEA文件中记录的轨迹中标记视频的地理标签
• 如果系统上可用，则内部调用exiftool。exiftool可以从广泛的视频格式中提取地理定位数据，使我们能够以更少的麻烦支持更多相机。
• 依次尝试多个地理标记源，直到找到正确数据。

这些功能适用于process命令，该命令分析视频以直接上传，而不是将其采样到图像中。它们是实验性的，未来的版本中将可能发生变化。

使用

使用--video_geotag_source SOURCE选项触发新的视频处理。它可以指定多次：在这种情况下，将依次尝试每个源，直到其中一个返回高质量数据。

SOURCE可以是

1. 源 plain 名称 - video, camm, gopro, blackvue, gpx, nmea, exiftool_xml, exiftool_runtime之一
2. 包含可选参数的 JSON 对象

{
  "source": "SOURCE",
  "pattern": "FILENAME_PATTERN" // optional
}

PATTERN指定数据源文件的命名方式，从视频文件名开始

• %f: 完整视频文件名
• %g: 不带扩展名的视频文件名
• %e: 视频文件扩展名

支持源及其默认模式

• video：按顺序将视频解析为camm, gopro, blackvue。模式：%f
• camm：解析视频以查找CAMM轨迹。模式：%f
• gopro：解析视频以查找GoPro格式的地理定位。模式：%f
• blackvue：解析视频以查找BlackVue格式的地理定位。模式：%f
• gpx：外部GPX文件。模式：%g.gpx
• nmea：外部NMEA文件。模式：%g.nmea
• exiftool_xml：由exiftool生成的外部XML文件。模式：%g.xml
• exiftool_runtime：在视频文件上执行exiftool。模式：%f

注意

• exiftool_runtime仅在系统上安装了exiftool时才有效。您可以在https://exiftool.org/或通过软件管理器找到它。如果已安装exiftool，但它不在默认执行路径中，可以通过设置环境变量MAPILLARY_TOOLS_EXIFTOOL_PATH来指定其位置。
• 模式对大小写敏感或不同，具体取决于文件系统 - 在Windows中，%g.gpx将匹配basename.gpx和basename.GPX，在MacOs、Linux或其他Unix系统中则不会。
• 如果同时指定了--video_geotag_source和--geotag_source，则--video_geotag_source将应用于视频文件，而--geotag_source将应用于图像文件。

示例

支持的通用视频

处理目录中的所有视频，尝试将其解析为CAMM、GoPro或BlackVue

mapillary_tools process --video_geotag_source video VIDEO_DIR/

外部GPX

处理目录中的所有视频，从GPX文件中获取地理定位数据。名为foo.mp4的视频将与名为foo.gpx的GPX文件关联。

mapillary_tools process --video_geotag_source gpx VIDEO_DIR/

Insta360拼接视频

要处理的视频已由Insta360 Studio拼接；地理定位数据位于父目录中的原始视频中，并且可能还有与拼接视频一起的GPX文件。首先查找GPX，然后回退到对原始视频运行exiftool。

mapillary_tools process \
--video_geotag_source gpx \
--video_geotag_source '{"source": "exiftool_runtime", "pattern": "../%g.insv"}' \
VIDEO_DIR/

--video_geotag_source的限制

外部地理定位源将与视频的开始对齐，目前尚无方法应用偏移或缩放时间。这意味着，例如，GPX轨迹必须精确地开始于视频的瞬间，并且仅支持camm, gopro, blackvue源的时间流逝视频。

认证

authenticate命令将更新存储在配置文件中的用户凭据。

示例

认证新用户

mapillary_tools authenticate

为用户 my_username 进行认证。如果用户已经认证，则会更新配置中的凭据。

mapillary_tools authenticate --user_name "my_username"

图像描述

process 命令的输出是一个描述每个图像或视频元数据的 JSON 对象数组。元数据通过 图像描述架构 进行验证。以下是一个最小示例。

[
  {
    "MAPLatitude": 58.5927694,
    "MAPLongitude": 16.1840944,
    "MAPCaptureTime": "2021_02_13_13_24_41_140",
    "filename": "/MY_IMAGE_DIR/IMG_0291.jpg"
  },
  {
    "error": {
      "type": "MapillaryGeoTaggingError",
      "message": "Unable to extract GPS Longitude or GPS Latitude from the image"
    },
    "filename": "/MY_IMAGE_DIR/IMG_0292.jpg"
  }
]

用户可以在将文件传递给 upload 命令之前创建或操作图像描述文件。以下是一些示例。

# Remove images outside the bounding box and map matching the rest images on the road network
mapillary_tools process MY_IMAGE_DIR | \
    ./filter_by_bbox.py 5.9559,45.818,10.4921,47.8084  | \
    ./map_match.py > /tmp/mapillary_image_description.json

# Upload the processed images
mapillary_tools upload  MY_IMAGE_DIR --desc_path /tmp/mapillary_image_description.json

# Converts captures.csv to an image description file
./custom_csv_to_description.sh captures.csv | mapillary_tools upload MY_IMAGE_DIR --desc_path -

压缩图像

上传图像目录时，内部 upload 命令会将临时目录（TMPDIR）中的序列打包，然后上传这些 zip 文件。

mapillary_tools 提供了一个 zip 命令，允许用户指定存储 zip 文件的位置，通常是在 I/O 更快或空间更大的位置。

# Zip processed images in MY_IMAGE_DIR and write zip files in MY_ZIPFILES
mapillary_tools zip MY_IMAGE_DIR MY_ZIPFILES

# Upload all the zip files (*.zip) in MY_ZIPFILES:
mapillary_tools upload --file_types zip MY_ZIPFILES

开发

设置

克隆仓库

git clone git@github.com:mapillary/mapillary_tools.git
cd mapillary_tools

设置虚拟环境。这是可选的，但推荐这样做

pip install pipenv

安装依赖项

pipenv install -r requirements.txt
pipenv install -r requirements-dev.txt

进入虚拟环境 shell

pipenv shell

运行仓库中的代码

python3 -m mapillary_tools.commands --version

测试

运行测试

# test all cases
python3 -m pytest -s -vv tests
# or test a single case specifically
python3 -m pytest -s -vv tests/unit/test_camm_parser.py::test_build_and_parse

运行代码风格检查

# format code
black mapillary_tools tests
# sort imports
usort format mapillary_tools tests

发布和构建

# Assume you are releasing v0.9.1a2 (alpha2)

# Tag your local branch
# Use -f here to replace the existing one
git tag -f v0.9.1a2

# Push the tagged commit first if it is not there yet
git push origin

# Push ALL local tags (TODO: How to push a specific tag?)
# Use -f here to replace the existing tags in the remote repo
git push origin --tags -f

# The last step will trigger CI to publish a draft release with binaries built
# in https://github.com/mapillary/mapillary_tools/releases