精灵图 - Martin Tile Server Documentation

精灵图源

给定一个包含 SVG 图像的目录，Martin 将生成一个精灵图——一个 JSON 索引和一个 PNG 图像，用于低分辨率和高分辨率显示。不带扩展名的 SVG 文件名将用作精灵图的图像 ID（请记住，一个精灵图，即 sprite_id 包含多个图像）。在给定目录中递归搜索图像，因此子目录名称将用作图像 ID 的前缀。例如，icons/bicycle.svg 将作为 icons/bicycle 精灵图图像可用。

精灵图表生成会被缓存，此缓存的大小可以通过配置文件中的 sprites.cache_size_mb 进行配置。

API

Martin 使用 MapLibre 精灵图 API 规范通过多个端点提供精灵图。精灵图图像和索引是即时生成的，因此如果更新了精灵图目录，更改将立即反映。

您可以使用 /catalog api 查看所有 <sprite_id> 及其包含的精灵图。

精灵图 PNG

sprite

GET /sprite/<sprite_id>.png 端点包含一个组合所有源图像的单个 PNG 精灵图图像。此外，在 GET /sprite/<sprite_id>@2x.png 有一个高 DPI 版本可用。

精灵图索引

/sprite/<sprite_id>.json 元数据索引描述精灵图内每个图像的位置和大小。就像 PNG 一样，在 /sprite/<sprite_id>@2x.json 有一个高 DPI 版本可用。

{
  "bicycle": {
    "height": 15,
    "pixelRatio": 1,
    "width": 15,
    "x": 20,
    "y": 16
  },
  ...
}

通过有符号距离场 (SDF) 在运行时着色

如果您想在运行时设置精灵图的颜色，您需要使用有符号距离场 (SDF) 端点。例如，如果使用 SDF，maplibre 确实支持通过 icon-color 和 icon-halo-color 属性修改图像。

SDF 有一个显著的缺点，即只允许一种颜色。如果您想要多种颜色，则需要将图标分层。

以下 API 可用：

/sdf_sprite/<sprite_id>.json 用于获取 SDF 精灵图索引
/sdf_sprite/<sprite_id>.png 用于获取 SDF 精灵图 PNG

组合多个精灵图

可以使用与瓦片连接相同的模式将多个 sprite_id 值组合到一个精灵图中：/sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>。不进行 ID 重命名，因此相同的精灵图名称将相互覆盖。

从 CLI 配置

可以使用 --sprite 标志从 CLI 配置精灵图目录。该标志可以多次使用以配置多个精灵图目录。精灵图的 sprite_id 将是目录的名称——在下面的示例中，精灵图将在 /sprite/sprite_a 和 /sprite/sprite_b 可用。使用 --save-config 将配置保存到配置文件。

martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b

使用配置文件配置

可以使用 sprite 键从配置文件配置精灵图目录，类似于 MBTiles 和 PMTiles 的配置方式。

# 精灵图配置
sprites:
  paths:
    # 此目录中的所有 SVG 文件将在 sprite_id "my_images" 下发布
    - /path/to/my_images
  sources:
    # 此目录中的 SVG 图像将在 sprite_id "my_sprites" 下发布
    my_sprites: /path/to/some_dir

精灵图现在在 /sprite/my_images,some_dir.png/ … 可用

Keyboard shortcuts

Martin Tile Server Documentation