自訂地圖配置

對齊、比例和背景圖像可以針對設備上每個已儲存的地圖獨立配置。

這些設置可以在視覺編輯器中通過從地圖列表中選擇地圖來配置，或者使用 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