Update README.md to follow standard format
- Rewrite README with clear sections: Features, Installation, Usage, Structure - Add FAQ and contact information - Keep project information concise and actionable
This commit is contained in:
265
README.md
265
README.md
@@ -2,204 +2,119 @@
|
||||
|
||||
CheckShot 是一个面向 Android 的图片处理与检查工具，包含水印处理、拼图合成、以及丰富的设置能力，配合 AirTest 自动化测试用例，帮助实现端到端的图像工作流。
|
||||
|
||||
## 核心功能
|
||||
## 功能特点
|
||||
|
||||
- **相机模块**
|
||||
- 使用 CameraX 库实现拍照、自动/手动对焦、曝光调节
|
||||
- 拍摄后自动叠加水印（时间+地点）
|
||||
- **相机模块**：使用 CameraX 库实现拍照、自动/手动对焦、曝光调节，拍摄后自动叠加水印（时间+地点）
|
||||
- **水印处理**：支持时间水印（格式固定为 "yyyy年-MM月-dd日 HH:mm:ss"）和地点水印（优先联网解析，失败时显示经纬度），提供三种预设样式
|
||||
- **多图拼图（合成）模块**：支持 2x2 和 3x3 网格布局，图片自动缩放裁剪，支持图片替换、删除、添加和质量控制
|
||||
- **文字编辑模块**：在合成图片的顶部（标题）和底部（内容）添加带矩形背景的文字说明，支持智能换行
|
||||
- **图片管理**：本地存储、分类管理、预览、导出/分享，遵循分区存储规则通过 MediaStore 保存至系统相册
|
||||
- **设置与通用配置**：水印设置、合成设置、通用设置、关于等配置项均可通过设置界面调整
|
||||
- **测试与自动化**：集成 AirTest 测试用例，覆盖水印、相册、拼图、设置等场景，便于回归验证
|
||||
|
||||
- **水印处理**
|
||||
- **时间水印**：拍摄后在左下角叠加时间戳，格式固定为 "yyyy年-MM月-dd日 HH:mm:ss"
|
||||
- **地点水印**：优先通过 Geocoder 联网解析地址，失败时回落显示经纬度。可在设置中配置校准方式
|
||||
- **样式**：提供三种预设样式（默认/简约/醒目），并可在设置中预览和应用
|
||||
## 安装步骤
|
||||
|
||||
- **多图拼图（合成）模块**
|
||||
- **布局规则**：支持 2x2 和 3x3 两种网格布局，图片自动缩放裁剪以适配网格
|
||||
- **核心能力**：图片拼接、模板化布局编辑（替换/删除图片）、合成质量控制（分辨率/清晰度）
|
||||
- **交互**：支持替换网格中的图片、删除图片、添加新图片、设置合成质量
|
||||
|
||||
- **文字编辑模块**
|
||||
- 在合成图片的顶部（标题）和底部（内容）添加带矩形背景的文字说明
|
||||
- 支持智能换行，自动适应指定宽度
|
||||
- 提供预设文字样式选择
|
||||
|
||||
- **图片管理**
|
||||
- 本地存储、分类管理、预览、导出/分享
|
||||
- 遵循分区存储规则，通过 MediaStore 保存至系统相册
|
||||
- 文件命名规则：`巡检报告_{巡检主题}_{生成时间}.jpg`
|
||||
|
||||
- **设置与通用配置**
|
||||
- 水印设置、合成设置、通用设置、关于等配置项，均可通过设置界面调整
|
||||
|
||||
- **测试与自动化**
|
||||
- 集成 AirTest 测试用例，覆盖水印、相册、拼图、设置等场景，便于回归验证
|
||||
|
||||
---
|
||||
|
||||
## 通用拼图布局组件技术规格
|
||||
|
||||
### 1. 逻辑结构
|
||||
|
||||
采用“上-中-下”三段式布局：
|
||||
|
||||
```
|
||||
┌─────────────────────────┐
|
||||
│ 标题区 (Title) │ 高度自适应，支持 1 行文本
|
||||
├─────────────────────────┤
|
||||
│ │
|
||||
│ 图片网格区 │ 2x2 或 3x3 栅格布局
|
||||
│ (Grid Area) │
|
||||
│ │
|
||||
├─────────────────────────┤
|
||||
│ 底部文字区 (Text) │ 200dp 高度，包含标题+内容
|
||||
└─────────────────────────┘
|
||||
```
|
||||
|
||||
### 2. 核心布局参数化
|
||||
|
||||
| 参数 | 说明 | 当前值 |
|
||||
|------|------|--------|
|
||||
| Grid_Columns | 列数 | 2 或 3 |
|
||||
| Grid_Rows | 行数 | 2 或 3 |
|
||||
| S | 单元格间距 | 4dp |
|
||||
| P | 容器内边距 | 16dp |
|
||||
|
||||
布局模板自动匹配：根据图片数量自动选择最接近的栅格模板。
|
||||
|
||||
### 3. 内容渲染规则
|
||||
|
||||
- **标题区**：位于顶部，高度自适应，支持 1 行文本
|
||||
- **图片网格区**：位于栅格正下方，由图片组成
|
||||
- **内容区**：位于底部，由 Title（加粗）和 Content（常规）组成
|
||||
|
||||
---
|
||||
|
||||
### 4. 缩放算法规格
|
||||
|
||||
#### 等比缩放 (Proportional Scaling)
|
||||
|
||||
- 锁定原始宽高比，严禁 X 或 Y 轴独立拉伸
|
||||
- 计算缩放比例：`k = max(Wt / W_orig, Ht / H_orig)`
|
||||
|
||||
其中：
|
||||
- `Wt` = 目标单元格宽度（物理像素）
|
||||
- `Ht` = 目标单元格高度（物理像素）
|
||||
- `W_orig` = 原始图片宽度
|
||||
- `H_orig` = 原始图片高度
|
||||
|
||||
#### 填充模式
|
||||
|
||||
- **Aspect Fill**：图片须完全覆盖单元格区域，不允许出现留白（Gap-free）
|
||||
|
||||
#### 采样策略
|
||||
|
||||
- **下采样 (Downsampling)**：针对大图缩小，采用双线性（Bilinear）过滤，避免出现锯齿或摩尔纹
|
||||
|
||||
#### 对齐规则
|
||||
|
||||
- **Center Aligned**：初始加载时，图片几何中心与单元格几何中心重合
|
||||
|
||||
#### 分辨率限制
|
||||
|
||||
- **Max DPI 限制**：缩小后的图片逻辑像素密度不低于 320dpi，确保在高分屏下的视觉清晰度
|
||||
|
||||
---
|
||||
|
||||
### 5. 布局通用适配规则
|
||||
|
||||
1. 系统根据当前选定的布局模板（2x2 或 3x3），计算出单个单元格的目标物理像素 (Wt, Ht)
|
||||
2. 原始图片输入后，自动计算缩放比例 k = max(Wt/W_orig, Ht/H_orig)
|
||||
3. 图片按 k 倍数进行等比缩小
|
||||
4. 缩小后的图片根据单元格中心进行溢出裁切，确保视觉上的严丝合缝
|
||||
|
||||
---
|
||||
|
||||
## 架构与实现要点
|
||||
|
||||
- Watermark：时间文本来自系统时间，地点文本通过 LocationHelper/Geocoder 获取。
|
||||
- Puzzle：通过 Bitmap 拼接与 Canvas/Matrix 实现多种布局，支持图片替换、删除与质量控制。
|
||||
- Settings：使用 DataStore 保存用户偏好。
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 构建与运行
|
||||
|
||||
- **构建调试 APK**：`./gradlew assembleDebug`
|
||||
- **构建发布 APK**：`./gradlew assembleRelease`
|
||||
- **在设备/模拟器上安装**：`adb install -r app/build/outputs/apk/debug/app-debug.apk`
|
||||
|
||||
### 发布签名配置
|
||||
|
||||
本项目已配置自动签名，使用 `app/my-release.jks` 密钥库：
|
||||
|
||||
1. **生成签名密钥**（已配置）：
|
||||
1. **克隆项目**：
|
||||
```bash
|
||||
keytool -genkeypair -v -alias my-key -keyalg RSA -keysize 2048 -validity 10000 -keystore my-release.jks
|
||||
git clone http://124.223.26.33:3000/xiaji/anroid-CheckShot.git
|
||||
cd anroid-CheckShot
|
||||
```
|
||||
|
||||
2. **签名配置**：
|
||||
- 在 `app/build.gradle.kts` 中配置了 `signingConfigs`
|
||||
- 签名密码存储在 `gradle.properties` 中（不提交到版本控制）
|
||||
|
||||
3. **构建签名 APK**：
|
||||
2. **构建调试 APK**：
|
||||
```bash
|
||||
./gradlew assembleRelease
|
||||
./gradlew assembleDebug
|
||||
```
|
||||
构建产物：`app/build/outputs/apk/release/app-release.apk`
|
||||
|
||||
### AirTest 测试
|
||||
3. **安装到设备**：
|
||||
```bash
|
||||
adb install -r app/build/outputs/apk/debug/app-debug.apk
|
||||
```
|
||||
|
||||
- **安装依赖**：
|
||||
4. **安装 AirTest 依赖（用于测试）**：
|
||||
```bash
|
||||
pip install airtest pocoui
|
||||
```
|
||||
|
||||
- **运行测试用例**：
|
||||
```bash
|
||||
# 确保设备已连接（模拟器或真机）
|
||||
adb devices
|
||||
## 使用示例
|
||||
|
||||
# 运行拼图测试
|
||||
airtest run test/airtest/test_puzzle_merge.py --device Android:///
|
||||
```
|
||||
### 基本使用
|
||||
|
||||
- **手动测试脚本**：
|
||||
```bash
|
||||
python test_android.py # 基础功能测试
|
||||
python test_camera.py # 相机功能测试
|
||||
python test_gallery.py # 相册功能测试
|
||||
```
|
||||
1. **启动应用**：在 Android 设备/模拟器上安装并打开 CheckShot
|
||||
2. **拍照**：点击相机按钮拍照，自动添加水印
|
||||
3. **拼图**：选择多张图片进行拼图合成
|
||||
4. **查看相册**：浏览和管理拍摄的照片
|
||||
|
||||
## 项目结构与升级
|
||||
### 构建发布 APK
|
||||
|
||||
- 主要代码位于：
|
||||
- app/src/main/... 业务代码与 UI 组件
|
||||
- app/src/test/... 单元测试
|
||||
- test/airtest/... AirTest 的 UI 测试用例
|
||||
- README 作为版本演进的记录，后续变更请同步更新。
|
||||
```bash
|
||||
# 构建签名 APK（需配置好 keystore）
|
||||
./gradlew assembleRelease
|
||||
|
||||
## 设置选项说明
|
||||
# 构建产物位置
|
||||
app/build/outputs/apk/release/app-release.apk
|
||||
```
|
||||
|
||||
### 水印设置
|
||||
- **水印样式**：默认样式、简约样式、醒目样式
|
||||
- **地点校准方式**：
|
||||
- 联网查询校准（默认）
|
||||
- 经纬度+距离校准
|
||||
### 运行测试
|
||||
|
||||
### 合成与文字设置
|
||||
- **默认合成布局**：2x2 网格、3x3 网格
|
||||
- **合成图片质量**：高清（95%）、标准（85%）、流畅（70%）
|
||||
- **默认文字样式**：分别为标题和内容提供预设样式选择
|
||||
```bash
|
||||
# 确保设备已连接
|
||||
adb devices
|
||||
|
||||
### 通用设置
|
||||
- **默认巡检主题**：预设默认的巡检主题名称
|
||||
- **巡检员信息**：填写姓名或工号（扩展项）
|
||||
- **关于**：显示应用版本号、开发者信息
|
||||
# 运行 AirTest 拼图测试
|
||||
airtest run test/airtest/test_puzzle_merge.py --device Android:///
|
||||
|
||||
## 持续集成与发布
|
||||
# 运行手动测试脚本
|
||||
python test_android.py # 基础功能测试
|
||||
python test_camera.py # 相机功能测试
|
||||
python test_gallery.py # 相册功能测试
|
||||
```
|
||||
|
||||
- 建议在 CI 中执行：编译、单元测试、AirTest 测试并在通过后打包发行版。
|
||||
## 目录结构
|
||||
|
||||
## 联系与贡献
|
||||
```
|
||||
anroid-CheckShot/
|
||||
├── app/ # App 模块
|
||||
│ ├── src/main/ # 主代码
|
||||
│ │ ├── java/ # Kotlin/Java 代码
|
||||
│ │ └── res/ # 资源文件
|
||||
│ ├── build.gradle.kts # App 级构建配置
|
||||
│ └── my-release.jks # 签名密钥（本地）
|
||||
├── test/ # 测试代码
|
||||
│ └── airtest/ # AirTest UI 测试
|
||||
├── gradle.properties # Gradle 属性（含签名配置）
|
||||
├── build.gradle.kts # 项目级构建配置
|
||||
├── settings.gradle.kts # 项目设置
|
||||
└── README.md # 项目说明
|
||||
```
|
||||
|
||||
- 如需进一步定制文档结构，或需要将某些部分拆分为单独的开发指南，请告知偏好。
|
||||
## 贡献指南
|
||||
|
||||
1. Fork 项目仓库
|
||||
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
|
||||
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
|
||||
4. 推送到分支 (`git push origin feature/AmazingFeature`)
|
||||
5. 提交 Pull Request
|
||||
|
||||
## 常见问题 (FAQ)
|
||||
|
||||
**Q: 如何配置签名？**
|
||||
A: 项目已配置自动签名，签名密钥文件 `my-release.jks` 在 `app/` 目录下，密码在 `gradle.properties` 中配置。
|
||||
|
||||
**Q: 如何修改水印样式？**
|
||||
A: 在设置界面中选择水印样式（默认/简约/醒目），可实时预览效果。
|
||||
|
||||
**Q: AirTest 测试失败怎么办？**
|
||||
A: 确保设备已连接且已安装 AirTest 依赖，检查设备是否开启开发者选项和 USB 调试。
|
||||
|
||||
**Q: 拼图功能支持哪些布局？**
|
||||
A: 支持 2x2 和 3x3 网格布局，图片会自动缩放裁剪以适配网格。
|
||||
|
||||
## 联系方式/反馈渠道
|
||||
|
||||
- 项目仓库：http://124.223.26.33:3000/xiaji/anroid-CheckShot.git
|
||||
- 问题反馈：请在仓库中提交 Issue
|
||||
- 代码贡献：欢迎提交 Pull Request
|
||||
|
||||
---
|
||||
|
||||
**注意**：请妥善保管签名密钥文件 (`my-release.jks`) 和密码，这些文件已添加到 `.gitignore` 中，不会被提交到版本控制。
|
||||
Reference in New Issue
Block a user