#pragma once

#include <QImage>
#include <QRect>
#include <QString>
#include <QSize>

#include <QtGlobal>

namespace core {
namespace image_file {

/// 仅读元数据（宽高），不解码像素；优先 libvips，否则 Qt QImageReader::size。
[[nodiscard]] bool probeImagePixelSize(const QString& absolutePath, QSize* outSize);

/// 统一大图解码管线：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,
                                      int maxOutputHeight, QImage* out);

/// 仅解码源图中矩形区域（逻辑像素坐标），并保证输出为 1:1 像素（不缩放）。
/// 用于抠图/像素对齐等需要严格坐标一致的场景。
[[nodiscard]] bool loadRegionToQImageExact(const QString& absolutePath, const QRect& rectLogical, QImage* out);

}  // namespace image_file
}  // namespace core