frog-engine · jarry · Jan 11, 2025 · Jan 17, 2025 · Jan 25, 2025 · Jan 25, 2025
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,30 @@
+*node_modules/
+.DS_Store
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+test/unit/coverage
+test/e2e/reports
+selenium-debug.log
+package-lock.json
+lerna-debug
+
+#generated theme
+theme/lib/
+
+# ignore dist
+dist/*.js
+dist/*.css
+tmp/
+
+# Editor directories and files
+.idea
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+.vscode
+
+# 打包文件
+*.tgz
+*.zip
diff --git a/Ability.md b/Ability.md
@@ -0,0 +1,82 @@
+# SDK 能力需求
+
+## 1. 图片生产能力
+- **描述**：提供统一的图片转码功能，包括格式转换、压缩和从视频或动图中抽帧。支持常见格式（JPEG、PNG、HEIC、WebP 等）。支持单个或批量图片操作。  
+- **备注**：提供灵活的图片格式处理和抽帧能力，满足多种生产场景。
+
+## 2. 图片制作能力
+- **描述**：提供统一的图片裁剪、旋转、缩放及拼接功能，API 支持多个功能组合调用，便于一次性完成多个操作，支持传递多张图片。  
+- **备注**：满足业务层图片加工需求，简化复杂操作的组合。
+
+## 3. 同步与异步支持
+- **描述**：支持同步和异步两种调用模式，可配置默认超时时间及最大等待时间。  
+- **备注**：适配不同场景，灵活性高，满足高性能需求。
+
+## 4. 调用性能
+- **描述**：同步调用需在 200ms 内完成返回，异步调用需在 500ms 内完成任务。  
+- **备注**：高效处理，满足实时性要求，需基于常规任务测试优化性能。
+
+## 5. 批量调用
+- **描述**：支持多任务同时调用，允许业务层以统一接口形式获取结果，支持任务队列管理和结果合并。  
+- **备注**：提高任务并发能力，简化业务开发复杂度。
+
+## 6. 任务叠加
+- **描述**：支持多个任务作用于同一对象，结果自动传递，自动管理任务依赖关系，避免冲突。  
+- **备注**：提供灵活任务组合，支持链式调用，简化复杂任务处理逻辑。
+
+## 7. 图片 AI 增强（可选）
+- **描述**：提供清晰度提升、高亮优化、滤镜等传统 AI 模型能力接口，生成式大模型功能有专门接口调用。  
+- **备注**：提升图片质量，支持多种 AI 模型应用场景。
+
+## 8. 上下文保持（可选）
+- **描述**：支持任务上下文环境保持，后续任务可复用前一个任务的结果作为输入，提供状态保存与还原功能（会话保存时间为 5 分钟）。  
+- **备注**：提高连续任务处理效率，支持任务结果的高效复用。
+
+## 9. 异构转码能力（可选）
+- **描述**：支持 GPU 等异构硬件加速，能够根据任务需求动态选择合适的加速方式，优化 CUDA、OpenCL、FPGA 等特定硬件的性能。  
+- **备注**：提高转码效率，充分利用硬件资源。
+
+## 10. 扩展能力（可选）
+- **描述**：按模块化结构设计，支持扩展功能（如新增 AI 增强模型、特定格式支持）。  
+- **备注**：灵活可扩展，适应未来需求变化。
+
+## 11. 报错日志与监控
+- **描述**：提供详细日志和报错信息，支持任务调用的日志记录和监控，便于追踪和调试。  
+- **备注**：提高系统可靠性和可维护性，方便定位问题。
+
+## 12. 友好 API 和指南
+- **描述**：提供简单易用的 API 和开发文档，包含使用场景代码示例，支持多语言 SDK（如 Go、Python、Java、C、NodeJS等）。  
+- **备注**：简化开发过程，提高开发者使用体验，覆盖更多语言生态。
+
+---
+
+# 图片生产能力
+
+## 能力与描述
+
+| **能力**   | **描述**                                                                 | **备注**                                              |
+|------------|--------------------------------------------------------------------------|-------------------------------------------------------|
+| 格式转换   | 将图像从一种格式转换为另一种格式。                                         | 支持 JPEG 转 PNG、GIF 转 WebP 等常见图像格式转换。    |
+| 压缩与缩放 | 减小图像文件大小，优化文件体积。                                           | 包括有损压缩和无损压缩，支持 JPEG、PNG、WebP 等格式。 |
+| 分辨率调整 | 调整图像分辨率，适配不同屏幕尺寸。                                         | 支持缩放图像分辨率，适用于不同设备或平台的需求。      |
+| 抽帧       | 从视频中提取特定帧并保存为图像格式。                                       | 支持提取关键帧或任意帧，转换为 JPEG、PNG 等格式。    |
+| 编码优化   | 优化图像编码，提高压缩率和解码效率。                                       | 支持 WebP、JPEG 2000、H.264、H.265、AV1 等编码格式。  |
+
+---
+
+# 图片制作能力
+
+## 能力与描述
+
+| **能力**               | **描述**                                                     | **备注**                                                   |
+|------------------------|--------------------------------------------------------------|------------------------------------------------------------|
+| 裁剪与缩放             | 去除图像不需要的部分，保留关键区域，按比例缩放尺寸。             | 支持自定义裁剪或按比例裁剪。                               |
+| 旋转与翻转             | 旋转图像至指定角度或沿水平/垂直轴进行翻转。                     | 支持任意角度旋转、90°、180°、水平/垂直翻转。               |
+| 拼接与合成             | 将多张图像合并为一张，支持横向、纵向拼接，或图层合成。           | 适用于广告、全景图、社交媒体等复杂图层操作。               |
+| 图像叠加与透明背景     | 叠加多张图像或设置透明背景。                                   | 用于 商标、文案条 合成、去背景等应用。                             |
+| 文字与标注             | 在图像上添加文字、水印或注释。                                 | 支持文字样式、颜色、大小等调整，适用于广告或社交内容。     |
+| 滤镜与效果             | 应用滤镜和特效（黑白、复古、模糊、锐化等）。                   | 支持多种艺术效果，改善或美化图像。                         |
+| 颜色调整               | 调整亮度、对比度、饱和度、色调。                               | 用于修正颜色偏差、增强色彩效果。                           |
+| 美颜与修饰             | 优化人像面部特征，去除瑕疵。                                   | 适用于人像修饰、美颜、去痘、磨皮等。                       |
+| 图层操作与蒙版         | 多层次编辑和效果叠加。                                         | 适用于复杂图像设计和创作。                                 |
+| 图像特效               | 添加光晕、阴影、反射等效果。                                   | 增强图像视觉吸引力，提升艺术效果。                         |
diff --git a/README.md b/README.md
@@ -1,2 +1,97 @@
-# frog-sdk
-Frog-SDK is an image transcoding SDK that encapsulates tools such as FFmpeg, ImageMagick, and Webpmux, providing an interface for upper-layer calls. It supports synchronous/asynchronous operations and multi-task processing.
+# frog-sdk 介绍
+Image Transcoder SDK 是一个用于图片和视频处理的Go语言SDK，支持多种开源工具的调用，提供丰富的API接口，满足多种业务需求。
+
+## 服务分层
+```bash
+业务层（即时转码/异步转码） ->  服务层(同步/异步) -> 图片转码SDK -> 开源转码工具
+```
+
+## 主要功能
+1. 为上层提供通过SDK接口，封装工具命令
+2. 调用转码工具ffpg/ImageMagick/Webpmux等进行转码
+3. 提供开发上下文环境，提供任务回调，并能对一个对象连续操作
+
+## 具体功能
+- 获取图片和视频的基本信息及元数据
+- 图片间的相似性比较
+- 图片格式转换
+- 图片压缩（有损/无损）
+- 图片裁剪、缩放、旋转等设置与调整
+- 从动图或视频中抽取静态帧
+- 添加文字和水印
+- 应用滤镜和特效
+- AI增强功能
+- 任务管理（上下文管理、任务串行与并行执行）
+
+### 安装
+1. 克隆项目
+```bash
+$ git clone https://github.com/frog-engine/frog-sdk.git
+```
+2. 进入项目目录
+```bash
+$ cd frog-sdk
+```
+
+3. 安装依赖
+```bash
+$ go mod download
+$ go mod tidy
+$ go mod vendor
+$ go mod verify
+```
+
+4. 启动服务
+```bash
+# SDK包供上层引用，此处启动仅是验证
+$ go run cmd/frog-sdk/main.go
+# 看见启动信息
+# frog-sdk run successfully
+```
+
+## 使用示例
+```go
+
+func main() {
+
+  // 创建一个新的 SDKApi 实例
+  sdkApi := frogsdk.Init(&config.Config{ToolsRoot: "/usr/bin/"}, "production")
+  // sdkApi := api.NewImageApi()
+  logger.Printf("api %v", sdkApi)
+
+  var image1 = filepath.Join(utils.GetHomeDir(), "Downloads/tmp", "image1.jpg")
+  // 获取图片基本信息示例
+  resp, err := sdkApi.GetImageInfo(&models.ImageInfoRequest{FilePaths: []string{image1}})
+  if err != nil {
+    logger.Fatalf("Error getting image info: %v", err)
+  }
+
+  // 打印获取的图片信息
+  for _, info := range resp {
+    fmt.Printf("Image: %s, Format: %s, Size: %dx%d\n", info.FilePath, info.Format, info.Width, info.Height)
+  }
+
+  // 示例：转换图片格式
+  convertResp, err := sdkApi.ImageConvert(&models.ConvertRequest{
+    SourcePath:   image1,
+    TargetFormat: "png",
+  })
+
+  if err != nil {
+    logger.Fatalf("Error converting image: %v", err)
+  }
+
+  fmt.Printf("Converted image saved at: %s\n", convertResp.OutputPath)
+
+  // 获取任务信息示例
+  taskID := "task123"
+  taskResp, err := sdkApi.GetTaskInfo(taskID)
+  if err != nil {
+    logger.Fatalf("Error getting task info: %v", err)
+  }
+
+  if taskResp != nil {
+    fmt.Printf("Task ID: %s, Status: %s\n", taskResp.ID, taskResp.Status)
+  }
+}
+```
diff --git a/Requirement.md b/Requirement.md
@@ -0,0 +1,101 @@
+# API需求分类
+
+## 功能分类
+
+| 序号 | API分类       | 功能描述                                                                 | 工具                                |
+|------|---------------|--------------------------------------------------------------------------|------------------------------------|
+| 1    | 获取信息       | 提取图片及视频的基本信息（格式、尺寸、分辨率、色彩模式等）及元数据（EXIF、IPTC） | `ffprobe`, `mediainfo`, `ImageMagick` |
+| 2    | 文件比较       | 分析图片间的相似性，计算SSIM或PSNR                                       | `ffprobe`, `ImageMagick`           |
+| 3    | 转换           | 转码为不同格式（HEIC、AVIF、WebP、GIF等）                                 | `ffmpeg`, `ImageMagick`, `gif2webp` |
+| 4    | 压缩           | 图片有损/无损压缩，减少文件大小                                           | `ffmpeg`, `ImageMagick`, `gifsicle`, `oxipng` |
+| 5    | 设置与调整     | 裁剪、缩放、旋转、翻转、拼接、色彩优化等                                  | `ffmpeg`, `ImageMagick`, `jpgiccplus` |
+| 6    | 抽帧           | 从动图或视频中抽取静态帧                                                | `ffmpeg`, `ImageMagick`           |
+| 7    | 文本与水印     | 添加文字/水印，支持样式与位置设置；删除水印                               | `ImageMagick`, `delogo`           |
+| 8    | 滤镜与特效     | 应用滤镜效果（如晕影、模糊、油画等）                                      | `ImageMagick`                     |
+| 9    | AI增强         | 使用AI技术增强图片清晰度、亮度，对人像智能修饰                            | `ZoomAI`                          |
+| 10   | 高级功能       | 任务管理（上下文管理、任务串行与并行执行、日志记录）                      | -                                 |
+
+---
+
+# API需求列表
+
+## 通用要求
+- 支持单个/多个文件处理  
+- 支持同步/异步调用  
+- 支持多任务并行处理  
+- 支持前后任务叠加操作  
+
+## API接口设计
+
+### 1. 获取信息
+
+| API名称                   | 说明                               | 参数                            | 作用场景                           |
+|--------------------------|------------------------------------|--------------------------------|-----------------------------------|
+| `getBasicInfo(path, params)` | 获取图片基本信息                     | `path`: 图片路径；`params`: 属性 | 转码前获取准确信息                   |
+| `getMetadata(path)`         | 获取元数据（EXIF、XMP、IPTC）       | `path`: 图片路径                | 提取元数据用于分类管理               |
+| `isAnimated(path)`         | 判断是否为动图                      | `path`: 图片路径                | 判断是否抽帧或转码                   |
+| `getFrames(path)`          | 获取动图帧数                        | `path`: 图片路径                | 判断动图帧数                        |
+| `getResolution(path)`      | 获取分辨率（宽x高，DPI）            | `path`: 图片路径                | 压缩方式选择，转码时间预估           |
+
+### 2. 文件比较
+
+| API名称                     | 说明                            | 参数                           | 作用场景                        |
+|----------------------------|---------------------------------|--------------------------------|--------------------------------|
+| `compareImages(img1, img2)` | 比较两张图片的SSIM或PSNR         | `img1`: 图片1路径；`img2`: 图片2路径 | 转码效果对比                     |
+| `rotateImageToOrientation(path, orientation)` | 逐像素比较两张图片             | `path`: 图片路径；`orientation`: 方向 | 精准分析内容差异                 |
+
+### 3. 转换
+
+| API名称                       | 说明                       | 参数                                | 作用场景                    |
+|------------------------------|----------------------------|------------------------------------|---------------------------|
+| `convertTo(source, target, params)` | 转换图片格式               | `source`: 来源路径；`target`: 目标格式；`params`: 附加参数 | 通用格式转换               |
+| `convertToWebP(source, target, params)` | 转WebP格式            | 同上                               | 快捷格式转换               |
+| `convertToGIF(source, target, params)` | 转GIF格式             | 同上                               | 快捷格式转换               |
+
+### 4. 压缩
+
+| API名称                       | 说明                        | 参数                                | 作用场景                    |
+|------------------------------|-----------------------------|------------------------------------|---------------------------|
+| `compressImage(source, target, params)` | 压缩图片（有损/无损）    | `source`: 来源路径；`target`: 压缩路径；`params`: 参数 | 文件大小优化               |
+| `losslessCompress(path)`        | 无损压缩                   | `path`: 图片路径                   | 保留原质量压缩             |
+
+### 5. 设置与调整
+
+| API名称                   | 说明                            | 参数                              | 作用场景                  |
+|--------------------------|---------------------------------|----------------------------------|-------------------------|
+| `cropImage(source, target, params)` | 裁剪图片                  | `source`: 来源路径；`params`: 区域参数 | 定位裁剪                |
+| `resizeImage(source, target, params)` | 缩放图片                 | `source`: 来源路径；`params`: 尺寸 | 按需调整大小             |
+
+### 6. 抽帧
+
+| API名称                      | 说明                          | 参数                            | 作用场景                |
+|-----------------------------|-------------------------------|--------------------------------|-----------------------|
+| `extractFrame(path, param)`   | 抽取视频/动图帧              | `path`: 文件路径；`param`: 帧号 | 内容分析、帧优化        |
+
+### 7. 文本与水印
+
+| API名称                        | 说明                        | 参数                           | 作用场景               |
+|--------------------------------|-----------------------------|--------------------------------|----------------------|
+| `addText(source, target, text, params)` | 添加文字               | `text`: 内容；`params`: 样式 | 图片标注或水印        |
+| `addWatermark(path, watermarkPath, position)` | 添加水印           | `watermarkPath`: 水印路径；`position`: 位置 | 防盗用                |
+
+### 8. 滤镜与特效
+
+| API名称                         | 说明                        | 参数                               | 作用场景                |
+|--------------------------------|-----------------------------|-----------------------------------|-----------------------|
+| `applyFilter(source, target, filterType)` | 应用滤镜            | `filterType`: 滤镜类型             | 图像增强               |
+| `applyEffect(source, target, effectType)` | 添加特效            | `effectType`: 特效类型             | 特效增强               |
+
+### 9. AI增强与擦除
+
+| API名称                   | 说明                          | 参数                            | 作用场景                |
+|--------------------------|-------------------------------|--------------------------------|-----------------------|
+| `aiEnhance(source, target, model)` | AI增强                 | `model`: 增强模型               | 清晰度、亮度提升        |
+| `eraseArea(path, x, y, width, height)` | 擦除区域             | `x, y, width, height`: 区域坐标 | 去除水印、修图          |
+
+### 10. 高级功能
+
+| API名称                | 说明                          | 参数                      | 作用场景                  |
+|-----------------------|-------------------------------|--------------------------|-------------------------|
+| `startTask(taskList)`   | 启动任务链，支持并行/串行    | `taskList`: 任务列表      | 任务批处理               |
+| `getTaskStatus(taskId)` | 查询任务状态                 | `taskId`: 任务ID         | 任务监控                |