Cai1Cai1
721b867794
- go.mod 模块路径移除 .git 后缀 - README 添加私有 HTTP 仓库拉取配置说明 - 更新示例导入路径 - .gitignore 添加水印测试输出文件
261 lines
6.2 KiB
Markdown
261 lines
6.2 KiB
Markdown
# daShangDao_utils
|
||
|
||
**版本: v1.0.0** | 图片处理工具库
|
||
|
||
提供统一的图片加载接口（支持文件路径/网络 URL/Base64 三种输入方式），包含纯白检测、缩放、裁切、去白边、二维码/条形码生成识别、中文水印等完整图片处理能力。
|
||
|
||
---
|
||
|
||
## 安装
|
||
|
||
由于仓库使用 HTTP 协议（非 HTTPS），需要先配置环境变量：
|
||
|
||
```bash
|
||
# Windows PowerShell
|
||
$env:GOINSECURE="git.buzhiyushu.cn"
|
||
$env:GONOSUMDB="git.buzhiyushu.cn"
|
||
$env:GONOSUMCHECK="*"
|
||
$env:GOPRIVATE="git.buzhiyushu.cn"
|
||
|
||
# 然后拉取
|
||
go get git.buzhiyushu.cn/DaShangDao/daShangDao_utils/imglib
|
||
```
|
||
|
||
```bash
|
||
# Linux / macOS
|
||
export GOINSECURE="git.buzhiyushu.cn"
|
||
export GONOSUMDB="git.buzhiyushu.cn"
|
||
export GONOSUMCHECK="*"
|
||
export GOPRIVATE="git.buzhiyushu.cn"
|
||
|
||
go get git.buzhiyushu.cn/DaShangDao/daShangDao_utils/imglib
|
||
```
|
||
|
||
建议将上述环境变量写入 `~/.gitconfig` 或 CI 配置中，避免每次重复设置。
|
||
|
||
导入：
|
||
|
||
```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
|