From 8fb3af55182bbbe1f43201921a6845d30d30d8b5 Mon Sep 17 00:00:00 2001 From: xiaji Date: Sun, 15 Mar 2026 23:32:46 +0800 Subject: [PATCH] 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 --- README.md | 273 +++++++++++++++++++----------------------------------- 1 file changed, 94 insertions(+), 179 deletions(-) diff --git a/README.md b/README.md index a477e3a..f08e1b2 100644 --- a/README.md +++ b/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 + ``` -- **安装依赖**： - ```bash - pip install airtest pocoui - ``` +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. **查看相册**：浏览和管理拍摄的照片 -- 主要代码位于： - - app/src/main/... 业务代码与 UI 组件 - - app/src/test/... 单元测试 - - test/airtest/... AirTest 的 UI 测试用例 -- README 作为版本演进的记录，后续变更请同步更新。 +### 构建发布 APK -## 设置选项说明 +```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:/// -- 建议在 CI 中执行：编译、单元测试、AirTest 测试并在通过后打包发行版。 +# 运行手动测试脚本 +python test_android.py # 基础功能测试 +python test_camera.py # 相机功能测试 +python test_gallery.py # 相册功能测试 +``` -## 联系与贡献 +## 目录结构 -- 如需进一步定制文档结构，或需要将某些部分拆分为单独的开发指南，请告知偏好。 +``` +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` 中，不会被提交到版本控制。 \ No newline at end of file