Altair背景图像与坐标轴对齐问题：如何实现图像与轴刻度匹配？

问题描述 #

我希望在Altair中显示图像并在其上绘制标记，但图像与坐标轴无法良好对齐，导致标记位置错误。以下是我的代码：

import altair as alt
import pandas as pd
from PIL import Image
import numpy as np
from io import BytesIO
import base64


def toBase64(np_img):
    # convert numpy image to base64 string
    with BytesIO() as buffer:
        Image.fromarray(np_img).save(buffer, 'png')
        img_str = base64.encodebytes(buffer.getvalue()).decode('utf-8')
    return f"data:image/png;base64,{img_str}"


h,w = 250,410 
im0 = np.zeros((h,w,3), dtype=np.uint8)
tmp = pd.DataFrame([
    {"x": w//2, "y": h//2, "img": toBase64(im0)}
])
backgrd = alt.Chart(tmp).mark_image(
    width=w,
    height=h
).encode(x='x', y='y', url='img')
b0_df = pd.DataFrame({'x': [0,0,w,w], 'y': [0,h,0,h]})
b0 = alt.Chart(b0_df).mark_circle(size=30, color='red').encode(x='x', y='y').properties(width=w, height=h)
(backgrd+b0)

运行后标记位置正确，但图像存在拉伸和对齐问题，类似Plotly中可通过设置xref和yref让图像与轴刻度比例一致，请问在Altair中该如何实现？

解决方法 #

在Altair中实现图像与坐标轴精确对齐，需要从坐标系统、图像锚点和图表尺寸三个方面调整：

1. 固定统一的轴范围 #

为图像和标记图表设置完全一致的x、y轴定义域，确保两者共享同一坐标空间：

x_scale = alt.Scale(domain=[0, w])
y_scale = alt.Scale(domain=[0, h])

2. 调整图像的锚点与位置编码 #

默认图像锚点为中心，需将图像的位置改为左上角坐标，并设置对齐方式，让图像边缘贴合坐标轴原点：

# 图像数据使用左上角坐标(0,0)
tmp = pd.DataFrame([
    {"x": 0, "y": 0, "img": toBase64(im0)}
])

backgrd = alt.Chart(tmp).mark_image(
    width=w,
    height=h,
    align='left',  # 左对齐坐标轴
    baseline='top' # 顶部对齐坐标轴
).encode(
    x=alt.X('x:Q', scale=x_scale),
    y=alt.Y('y:Q', scale=y_scale),
    url='img'
)

3. 统一图表尺寸设置 #

确保图像和标记图表使用相同的width和height，避免尺寸差异导致的拉伸或偏移：

b0 = alt.Chart(b0_df).mark_circle(size=30, color='red').encode(
    x=alt.X('x:Q', scale=x_scale),
    y=alt.Y('y:Q', scale=y_scale)
).properties(width=w, height=h)

完整修正代码 #

import altair as alt
import pandas as pd
from PIL import Image
import numpy as np
from io import BytesIO
import base64


def toBase64(np_img):
    # convert numpy image to base64 string
    with BytesIO() as buffer:
        Image.fromarray(np_img).save(buffer, 'png')
        img_str = base64.encodebytes(buffer.getvalue()).decode('utf-8')
    return f"data:image/png;base64,{img_str}"


h,w = 250,410 
im0 = np.zeros((h,w,3), dtype=np.uint8)

# 设置统一的轴范围
x_scale = alt.Scale(domain=[0, w])
y_scale = alt.Scale(domain=[0, h])

# 图像使用左上角坐标并设置对齐方式
tmp = pd.DataFrame([
    {"x": 0, "y": 0, "img": toBase64(im0)}
])
backgrd = alt.Chart(tmp).mark_image(
    width=w,
    height=h,
    align='left',
    baseline='top'
).encode(
    x=alt.X('x:Q', scale=x_scale),
    y=alt.Y('y:Q', scale=y_scale),
    url='img'
).properties(width=w, height=h)

# 标记图表使用相同的轴范围和尺寸
b0_df = pd.DataFrame({'x': [0,0,w,w], 'y': [0,h,0,h]})
b0 = alt.Chart(b0_df).mark_circle(size=30, color='red').encode(
    x=alt.X('x:Q', scale=x_scale),
    y=alt.Y('y:Q', scale=y_scale)
).properties(width=w, height=h)

(backgrd+b0)

关键逻辑说明 #

• 固定轴定义域：确保图像和标记的坐标计算规则完全一致；
• 调整图像锚点：让图像的左上角与坐标轴原点重合，避免中心对齐带来的偏移；
• 统一尺寸：消除图表间的尺寸差异，防止图像被拉伸变形。

内容的提问来源于stack exchange，提问作者Tu Bui