# daShangDao_utils

**版本: v1.0.0** | 图片处理工具库

提供统一的图片加载接口（支持文件路径/网络 URL/Base64 三种输入方式），包含纯白检测、缩放、裁切、去白边、二维码/条形码生成识别、中文水印等完整图片处理能力。

---

## 安装

```bash
go get git.buzhiyushu.cn/DaShangDao/daShangDao_utils/imglib
```

导入：

```go
import "git.buzhiyushu.cn/DaShangDao/daShangDao_utils/imglib"
```

---

## 核心类型

### ImageInput（统一图片输入源）

`ImageInput` 是本库的核心输入类型，支持 **三种图片加载方式**，任意设置一个即可：

```go
// 方式一：从磁盘文件加载
input := imglib.NewImageInputFromFile("/path/to/image.jpg")

// 方式二：从网络 URL 加载
input := imglib.NewImageInputFromURL("https://example.com/image.png")

// 方式三：从 Base64 字符串加载（自动处理 data:image/ 前缀）
input := imglib.NewImageInputFromBase64("iVBORw0KGgo...")

// 统一加载方法
img, format, err := input.Load()
```

---

## API 文档

### 纯白占比检测

```go
pct, err := imglib.CalculateWhitePercentage(input)
// pct: 0.0 ~ 1.0 之间的纯白像素占比
```

### 白底居中合成

```go
rgba, err := imglib.CreateWhiteBottomCenteredImage(input, width, height)
// 在 width×height 的白色背景上居中放置原图
```

### 等比高度缩放

```go
img, err := imglib.ResizeToHeight(input, targetHeight)
// 按目标高度等比例缩放，Lanczos3 插值
```

### 自适应尺寸缩放

```go
rgba, err := imglib.ResizeToDimensions(input, dstWidth, dstHeight)
// 按目标宽高等比例缩放，自实现 Lanczos3 算法
```

### 去白边

```go
img, err := imglib.RemoveWhiteBorder(input)
// 自动检测白色边框并裁剪，默认阈值 240

img, err := imglib.RemoveWhiteBorderWithConfig(input, threshold, margin)
// threshold: 检测阈值(0-255)，margin: 保留边距(像素)
```

### 图片裁切

```go
rgba, err := imglib.Crop(input, x, y, width, height)
// 按指定矩形区域裁切
```

### 二维码识别

```go
text, err := imglib.ScanQRCode(input)
// 返回二维码中的文本内容

text, qrImg, err := imglib.ScanQRCodeWithBounds(input)
// 返回文本内容 + 裁剪后的二维码区域图片
```

### 二维码生成

```go
img, err := imglib.GenerateQRCode(content, width, height)
// content: 二维码内容, width/height: 图片尺寸
```

### 条形码生成

```go
// 支持三种编码类型:
img, err := imglib.GenerateBarcode(imglib.Code128, "1234567890")
img, err := imglib.GenerateBarcode(imglib.EAN13, "1234567890123")
img, err := imglib.GenerateBarcode(imglib.Code39, "ABC-123")
```

### 中文文字图片

```go
img, err := imglib.CreateChineseTextImage(text, width, height, fontSize)
// 将中英文文本渲染为图片，超长自动换行并显示省略号
```

### 书籍信息水印

```go
// 先在现有 RGBA 图片上绘制书名/作者/出版社
err := imglib.DrawChineseInfo(rgba, "书名", "作者", "出版社")
```

### 通用水印

```go
result, err := imglib.ApplyWatermark(imglib.WatermarkConfig{
    SourceImage:  imglib.NewImageInputFromFile("source.jpg"),
    WatermarkImg: imglib.NewImageInputFromBase64(b64data),
    Opacity:      0.5,                              // 不透明度
    Position:     "bottom-right",                    // center/top-left/top-right/bottom-left/bottom-right/tile
    Scale:        0.3,                               // 水印缩放比例
    XOffset:      10,
    YOffset:      10,
})
```

**`Position` 可选值**:

| 值 | 说明 |
|------|------|
| `center` | 居中 |
| `top-left` | 左上角 |
| `top-right` | 右上角 |
| `bottom-left` | 左下角 |
| `bottom-right` | 右下角 |
| `tile` | 平铺 |

### 输出辅助

```go
// 编码为字节数组
bytes, err := imglib.EncodeToBytes(img, "jpeg", 95)

// 编码为 Base64 字符串（带 data:image/ 前缀）
b64, err := imglib.EncodeToBase64(img, "png", 95)

// 保存到文件（自动根据扩展名选择格式）
err := imglib.SaveToFile(img, "output.png")

// 保存为 JPEG
err := imglib.SaveJPEG(img, "out.jpg", 95)

// 保存为 PNG
err := imglib.SavePNG(img, "out.png")
```

---

## 完整示例

```go
package main

import (
    "fmt"
    "git.buzhiyushu.cn/DaShangDao/daShangDao_utils/imglib"
)

func main() {
    // 1. 从 URL 裁切图片
    cropped, err := imglib.Crop(
        imglib.NewImageInputFromURL("https://example.com/photo.jpg"),
        100, 50, 400, 300,
    )
    if err != nil {
        panic(err)
    }
    imglib.SaveJPEG(cropped, "cropped.jpg", 95)

    // 2. 从 Base64 识别二维码
    text, err := imglib.ScanQRCode(
        imglib.NewImageInputFromBase64("iVBORw0KGgoAAAANSUhEUg..."),
    )
    fmt.Println("二维码内容:", text)

    // 3. 从本地文件去白边
    cleaned, err := imglib.RemoveWhiteBorder(
        imglib.NewImageInputFromFile("scan.png"),
    )
    imglib.SavePNG(cleaned, "cleaned.png")

    // 4. 从 URL 添加 Base64 水印
    result, err := imglib.ApplyWatermark(imglib.WatermarkConfig{
        SourceImage:  imglib.NewImageInputFromURL("https://example.com/book.jpg"),
        WatermarkImg: imglib.NewImageInputFromBase64("iVBORw0KGgo..."),
        Opacity:      0.8,
        Position:     "center",
    })
    b64, _ := imglib.EncodeToBase64(result, "jpeg", 95)
    fmt.Println("水印结果:", b64[:50]+"...")

    // 5. 生成二维码并保存
    qr, _ := imglib.GenerateQRCode("https://example.com", 300, 300)
    imglib.SavePNG(qr, "qrcode.png")
}
```

---

## 版本历史

| 版本 | 日期 | 说明 |
|------|------|------|
| v1.0.0 | 2026-06-30 | 初始版本，支持三种图片输入方式，完整图片处理功能 |

---

## 许可证

MIT License