自定义地图配置

对齐、比例尺和背景图像可以为设备上的每个保存地图单独配置。

这些设置可以通过可视化编辑器中从地图列表中选择地图，或在 YAML 配置中使用 map_config 属性来配置。

地图配置选项

map_config内的设置是通过诸如 map_1、map_2 等键在每个地图索引中应用的。以下任何选项都可以在特定地图下定义：

警告

地图索引根据创建顺序分配，最早的地图从 1 开始获得最低索引。然而，如果在拥有多个地图及其配置的设备上禁用多层地图功能，当前活跃的地图会自动重新分配到 索引 1。这意味着之前在不同索引下配置的地图将突然采用 map_1.

• rotation：覆盖地图数据中配置的旋转，以在此卡片上以自定义旋转绘制地图，接受 0、90、180 或 270 的值。
• scale：覆盖基于地图原始大小与卡片大小差异的自动缩放计算，接受 0.1 到 20 之间的值。
• object_scale：覆盖地图对象（如房间和障碍物图标）的自动计算大小，使其显示得更大或更小。
• opacity：绘制地图的全局透明度。初始值为 1，可接受的最小值为 0。
• object_opacity：地图上绘制对象（如房间或障碍物图标）的透明度。初始值为 1，可接受的最小值为 0。
• font_size：显示在 激活对象 上方的文本气泡的字体大小。接受 0 到 12 之间的值。
• hidden_objects：覆盖此特定地图中全局 高级配置 定义的隐藏地图对象。

居中与缩放

下面的参数用于覆盖卡片自动计算以绘制地图的大小和中心坐标。

警告

这些参数提供的值是相对于地图的原始、未缩放尺寸的，而不是屏幕上的绝对像素。由于手动计算这些相对坐标非常复杂，因此所需的确切值可以通过可视化编辑器的实时地图信息部分提取。

• left：覆盖地图自动计算的水平中心。例如，将此值设置为0会将地图的0坐标在X轴上正好放置在卡片的水平中心。这个点通常位于码头正前方。
• top：覆盖地图自动计算的垂直中心。例如，将此值设置为0会将地图的0坐标在Y轴上正好放置在卡片的垂直中心。这个点通常位于码头正前方。
• width: 覆盖用于适应计算的地图实际宽度。由于卡片根据最大适应尺寸缩放地图，输入大于地图实际宽度的值会在卡片内缩小地图，而较小的值会放大地图。
• height：覆盖用于适应计算的地图实际高度。与 width 属性类似，输入大于地图实际高度的值会在卡片内缩小地图，而较小的值会放大它。

YAML 示例

type: custom:dreame-vacuum-card
entity: vacuum.l10s_gen2
map_config:
  map_1:
    rotation: 90
    scale: 1.2
    object_scale: 1.5
    left: 10
    top: -20
    hidden_objects:
      - name
      - virtual_wall
  map_2:
    rotation: 180
    opacity: 0.8

背景和叠加图像

卡片支持在地图后渲染自定义背景图像，这对于创建沉浸式 3D 楼层平面图仪表板特别有用。此行为可通过 background_image 属性进行配置。

为了进一步增强3D效果，也可以提供一个可选的overlay_image。覆盖图像直接绘制在机器人清洁路径之上，其主要目的是在平面图中视觉上遮挡穿过实体墙或家具的路径。强烈建议同时使用背景图像和覆盖图像，以在3D仪表板中实现逼真的深度感。

设计3D平面图

在为3D平面图创建自定义图形时，设计必须导出为两个具有透明背景的独立图像：一个包含地板和低矮家具的底层，以及一个仅包含上部墙壁的顶层。

下面的示例图片显示在棋盘格图案上，以突出它们的透明区域，这些图片是使用免费的室内设计应用程序 Sweet Home 3D 生成的，随后在标准图像编辑软件中处理，以去除地板区域并创建所需的透明部分。

背景图片

叠加图片

background_image 和 overlay_image 支持以下属性以对齐平面图：

• url: 图像路径，例如 /local/first_floor_bg.
• opacity：图像透明度。初始值为 1，并接受最低值为 0。

图像居中与缩放

图像的 left、top、width 和 height 属性使用与地图自身 居中与缩放 配置完全相同的相对坐标逻辑。这些属性是完全可选的。

即使自定义图像完全匹配地图大小，也强烈建议至少提供 top 和 left 值。这确保了如果地图的总大小在未来发生变化，自定义图像仍然能固定在相同的相对位置。

默认值

当未提供这些值时，卡片会自动将自定义图像的大小和中心与地图数据对齐。这些属性是完全可选的，仅用于覆盖此行为，以防止在地图随着时间扩展或收缩时，自定义图像发生偏移或缩放变化。

• left：定义图像相对于地图中心的水平中心。例如，将此值设置为 0 可以使地图的 0 坐标在 X 轴上恰好位于图像的水平中心。这个点通常位于码头正前方。
• top：定义图像相对于地图中心的垂直中心。例如，将此值设置为 0 可以使地图的 0 坐标在 Y 轴上恰好位于图像的垂直中心。这个点通常位于码头正前方。
• width: 定义图像相对于地图原始未缩放坐标系统的宽度，而不是绝对屏幕像素。例如，将此值设置为与地图的原始宽度匹配，可以确保图像按比例缩放，以覆盖与地图数据完全相同的水平区域。
• height: 定义图像相对于地图原始未缩放坐标系统的高度。例如，将此值设置为与地图的原始高度匹配，可以确保图像按比例缩放，以覆盖与地图数据完全相同的垂直区域。

原生旋转

自定义图像没有独立的旋转属性；它们的旋转本质上与地图的旋转绑定。为了确保所有视图的一致性，设计图像的基本方向必须完全匹配地图在设为0度时的初始方向。

设备像素比 (DPR)

该卡片根据设备的屏幕像素比渲染地图。为了防止背景和覆盖图像在高分辨率显示器（如手机）上出现模糊，强烈建议在桌面仪表板上提供这些图像的尺寸至少为所需尺寸的两倍。

确定图像尺寸

地图数据包含一个 grid_size 属性，该属性指示单个像素在现实世界中代表多少毫米。该值可以在 实时地图信息 部分找到。例如，grid_size 为 50 意味着每个像素对应 50 毫米，即 5 厘米。通过将房屋的实际尺寸除以该 grid_size，可以准确计算配置中要输入的 width 和 height 值，从而确保 1:1 的平面图像与房屋的实际尺寸完美匹配。

YAML 示例

type: custom:dreame-vacuum-card
entity: vacuum.l10s_gen2

map_config:
  map_1:
    object_scale: 7
    width: 250
    height: 183
    opacity: 0.45
    hidden_objects:
      - customized_cleaning
      - floor
      - name
      - name_background
      - no_go
      - no_mop
      - order
      - walls
    background_image:
      url: /local/home.png
      left: 77
      top: 10.3
      width: 250
      height: 183
      opacity: 0.75
    overlay_image:
      url: /local/home_overlay.png
      opacity: 0.9
  map_2:
    left: 41
    top: -12
    width: 269
    height: 171
    background_image:
      url: /local/second_floor_bg.png