update

client/core/image/ImageFileLoader.cpp

@@ -38,6 +38,23 @@ QImage loadImageLimited(const QString& absolutePath, qint64 maxPixelBudget) {
     return reader.read();
 }
 
+QImage loadDepthMapAlignedToBackground(const QString& depthAbsolutePath, const QString& backgroundAbsolutePath) {
+    if (depthAbsolutePath.isEmpty()) {
+        return {};
+    }
+    QImage g8 = loadImageLimited(depthAbsolutePath, core::image_decode::kWorkspaceMaxPixels);
+    if (g8.isNull()) {
+        return {};
+    }
+    g8 = g8.convertToFormat(QImage::Format_Grayscale8);
+    QSize logical;
+    if (!backgroundAbsolutePath.isEmpty() && probeImagePixelSize(backgroundAbsolutePath, &logical) &&
+        logical.isValid() && logical.width() > 0 && logical.height() > 0 && g8.size() != logical) {
+        g8 = g8.scaled(logical, Qt::IgnoreAspectRatio, Qt::SmoothTransformation);
+    }
+    return g8;
+}
+
 bool loadRegionToQImage(const QString& absolutePath, const QRect& rectLogical, int maxOutputWidth, int maxOutputHeight,
                         QImage* out) {
     if (!out || absolutePath.isEmpty() || maxOutputWidth < 32 || maxOutputHeight < 32) {

client/core/image/ImageFileLoader.h

@@ -16,6 +16,11 @@ namespace image_file {
 /// 统一大图解码管线：libvips（可用）按像素预算缩小后再解码为 QImage，否则 Qt。
 [[nodiscard]] QImage loadImageLimited(const QString& absolutePath, qint64 maxPixelBudget);
 
+/// 加载深度图并按背景图的逻辑像素尺寸对齐（与 probeImagePixelSize 一致）。
+/// 解决「背景走 vips 元数据为全尺寸、深度仍按像素预算降采样」时世界坐标采样错位。
+[[nodiscard]] QImage loadDepthMapAlignedToBackground(const QString& depthAbsolutePath,
+                                                     const QString& backgroundAbsolutePath);
+
 /// 仅解码源图中矩形区域（逻辑像素坐标）；超过 maxOutput* 则缩放该区域。
 /// libvips 可用时走随机访问裁剪；否则整图降采样回退后再拷贝矩形。
 [[nodiscard]] bool loadRegionToQImage(const QString& absolutePath, const QRect& rectLogical, int maxOutputWidth,