Custom Map Configuration

The alignment, scale and background image can be configured independently for each saved map on the device.

These settings can be configured in the visual editor by selecting a map from the map list, or by using the map_config property in the YAML configuration.

Map Configuration Options

The settings inside map_config are applied per map index using keys like map_1, map_2, etc. Any of the following options can be defined under a specific map:

WARNING

Map indexes are assigned based on their creation order, with the oldest map receiving the lowest index, starting from 1. However, if the multi-floor map feature is disabled on a device that has multiple maps and their configurations, the currently active map is automatically reassigned to index 1. This means a map previously configured under a different index will suddenly adopt the configuration of map_1.

• rotation: Overrides the rotation configured within the map data to draw the map in a custom rotation specific to this card, accepting values of 0, 90, 180, or 270.
• scale: Overrides the automatic scale calculation based on the difference between the map's original size and the card's size, accepting values between 0.1 and 20.
• object_scale: Overrides the automatically calculated size of map objects, such as room and obstacle icons, allowing them to appear larger or smaller.
• opacity: Global transparency of the drawn map. The initial value is 1 and it accepts values down to 0.
• object_opacity: Transparency of the objects drawn on the map, such as room or obstacle icons. The initial value is 1 and it accepts values down to 0.
• hidden_objects: Overrides the hidden map objects defined in the global Advanced Configuration for this specific map.

Centering and Scaling

The parameters below are used to override the size and center coordinates that the card automatically calculates to draw the map.

WARNING

The values provided for these parameters are relative to the map's raw, unscaled dimensions, not the absolute pixels on the screen. Because calculating these relative coordinates manually is highly complex, the exact values needed can be extracted using the Live Map Information section of the visual editor.

• left: Overrides the automatically calculated horizontal center of the map. For example, setting this value to 0 places the map's 0 coordinate on the X-axis exactly in the horizontal center of the card. This point is typically located right in front of the dock.
• top: Overrides the automatically calculated vertical center of the map. For example, setting this value to 0 places the map's 0 coordinate on the Y-axis exactly in the vertical center of the card. This point is typically located right in front of the dock.
• width: Overrides the map's actual width used for the fit calculation. Because the card scales the map based on the largest fitting dimension, entering a value larger than the map's actual width will shrink the map inside the card, while a smaller value will enlarge it.
• height: Overrides the map's actual height used for the fit calculation. Similar to the width property, entering a value larger than the map's actual height will shrink the map inside the card, while a smaller value will enlarge it.

YAML Example

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

Background and Overlay Images

The card supports rendering a custom background image behind the map, which is particularly useful for creating immersive 3D floorplan dashboards. This behavior is configured using the background_image property.

To further enhance the 3D effect, an optional overlay_image can also be provided. The overlay image is drawn directly on top of the robot's cleaning path and its primary purpose is to visually obscure paths that travel behind physical walls or furniture in the floorplan. Combining both a background and an overlay image is highly recommended for achieving a realistic sense of depth in 3D dashboards.

Designing a 3D Floorplan

When creating custom graphics for a 3D floorplan, the design must be exported as two separate images with transparent backgrounds: a base layer containing the floors and low furniture and a top layer containing only the upper walls.

The example images below, shown over a checkerboard pattern to highlight their transparent areas, were generated using the free interior design application Sweet Home 3D and subsequently processed in standard image editing software to remove the floor areas and create the required transparent parts.

Background Image

Overlay Image

The background_image and overlay_image support the following properties to align the floorplan:

• url: Path of the image, such as /local/first_floor_bg.
• opacity: Transparency of the image. The initial value is 1 and it accepts values down to 0.

Centering and Scaling Images

The left, top, width and height properties for images operate using the exact same relative coordinate logic as the map's own Centering and Scaling configuration. These properties are entirely optional.

Even if the custom image perfectly matches the map size, it is highly recommended to provide at least top and left values. This ensures that if the map's total size changes in the future, the custom image remains securely pinned to the same relative location.

Default Values

When these values are not provided, the card automatically equalizes the size and center of the custom image with the map data. These properties are entirely optional and exist solely to override this behavior, preventing the custom image from shifting or its scale from changing in the event that the map expands or shrinks over time.

• left: Defines the horizontal center of the image relative to the map's center. For example, setting this value to 0 places the map's 0 coordinate on the X-axis exactly in the horizontal center of the image. This point is typically located right in front of the dock.
• top: Defines the vertical center of the image relative to the map's center. For example, setting this value to 0 places the map's 0 coordinate on the Y-axis exactly in the vertical center of the image. This point is typically located right in front of the dock.
• width: Defines the width of the image relative to the map's original, unscaled coordinate system, rather than absolute screen pixels. For example, setting this value to match the map's raw width ensures the image is scaled proportionately to cover the exact same horizontal area as the map data.
• height: Defines the height of the image relative to the map's original, unscaled coordinate system. For example, setting this value to match the map's raw height ensures the image is scaled proportionately to cover the exact same vertical area as the map data.

Native Rotation

Custom images do not have their own independent rotation property; their rotation is inherently tied to the map's rotation. To ensure alignment across all views, the base orientation of the designed image must exactly match the map's initial orientation when set to 0 degrees.

Device Pixel Ratio (DPR)

The card renders the map according to the device's screen pixel ratio. To prevent the background and overlay images from appearing blurry on high-resolution displays such as mobile phones, it is highly recommended to provide these images at minimum double the required size on desktop dashboard.

Determining Image Size

The map data includes a grid_size property that indicates how many millimeters a single pixel represents in the real world. This value can be found in the Live Map Information section. For example, a grid_size of 50 means each pixel corresponds to 50mm, or 5cm. By dividing the real-world dimensions of the home by this grid_size, the exact width and height values to enter in the configuration can be accurately calculated, ensuring a 1:1 floor plan image scales perfectly with the real-world size of the home.

YAML Example

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