158 lines
4.8 KiB
Markdown
158 lines
4.8 KiB
Markdown
|
# Android 标尺测量应用 - 设计文档
|
|||
|
|
|
|||
|
|
## 概述
|
|||
|
|
|
|||
|
|
一款利用手机屏幕作为物理标尺的测量工具应用。支持屏幕标尺测量和拍照标注两种模式，通过屏幕 DPI + 手动校准保证测量精度。
|
|||
|
|
|
|||
|
|
**技术栈**：Kotlin + Jetpack Compose + Material 3
|
|||
|
|
**最低 API**：24 (Android 7.0)
|
|||
|
|
**主要依赖**：CameraX、DataStore Preferences
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 架构
|
|||
|
|
|
|||
|
|
### 顶层导航
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
┌──────────────────────────────────────────┐
|
|||
|
|
│ 🔧 设置（AppBar 右上角图标） │
|
|||
|
|
├──────────────────────────────────────────┤
|
|||
|
|
│ │
|
|||
|
|
│ 标尺测量模式 / 拍照标注模式 │
|
|||
|
|
│ │
|
|||
|
|
├──────────────────────────────────────────┤
|
|||
|
|
│ 📏 标尺 | 📷 拍照（底部导航栏） │
|
|||
|
|
└──────────────────────────────────────────┘
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
底部导航栏切换两种模式。右上角齿轮图标进入设置页面。设置页面使用独立 Screen 展示。
|
|||
|
|
|
|||
|
|
### 模式一：标尺测量
|
|||
|
|
|
|||
|
|
屏幕显示物理标尺。竖屏时纵向绘制，横屏时横向绘制。支持滚动查看完整量程。
|
|||
|
|
|
|||
|
|
**绘制规则**：
|
|||
|
|
- 三级刻度：cm 线（最长，标注数字）、0.5cm 线（中等）、mm 线（最短）
|
|||
|
|
- 测量标记：用户点击放置起点（绿色）、终点（红色），可拖拽微调
|
|||
|
|
- 结果展示：两点间距精确到 0.5mm
|
|||
|
|
|
|||
|
|
**关键计算**：
|
|||
|
|
```
|
|||
|
|
pixelPerCm = (dpi / 2.54) × cmCorrectionFactor
|
|||
|
|
totalCm = screenSide / pixelPerCm
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 模式二：拍照标注
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
拍照 → 预览确认 → 编辑标注 → 合成保存
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- **拍照**：CameraX 实现相机预览和拍照
|
|||
|
|
- **标注编辑**：在照片上叠加一个虚拟小标尺图
|
|||
|
|
- 小标尺是主标尺的缩略版（指定长度如 2/3/5/10cm），样式一致
|
|||
|
|
- 手势：单指拖拽移动、双指旋转 + 缩放
|
|||
|
|
- 底部切换标尺长度
|
|||
|
|
|
|||
|
|
- **合成保存**：照片 Bitmap + 标尺 Canvas 绘制合并为一张图，通过 MediaStore 保存到相册
|
|||
|
|
|
|||
|
|
### 设置页面
|
|||
|
|
|
|||
|
|
| 设置项 | 类型 | 说明 |
|
|||
|
|
|--------|------|------|
|
|||
|
|
| 标尺校准 | 交互页面 | 拖拽滑块对齐真实尺子的 10cm，保存修正系数 |
|
|||
|
|
| 默认方向 | 选择 | 竖屏 / 横屏 / 自适应 |
|
|||
|
|
| 拍照标尺默认长度 | 选择 | 2cm / 5cm / 10cm |
|
|||
|
|
| 关于 | 信息 | 版本号等 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 状态管理
|
|||
|
|
|
|||
|
|
### 单一 ViewModel
|
|||
|
|
|
|||
|
|
```kotlin
|
|||
|
|
data class RulerUiState(
|
|||
|
|
val orientation: Orientation,
|
|||
|
|
val pixelPerCm: Float,
|
|||
|
|
val scrollOffset: Float,
|
|||
|
|
val markStartCm: Float?,
|
|||
|
|
val markEndCm: Float?,
|
|||
|
|
val currentMode: Mode, // RULER / PHOTO
|
|||
|
|
val photoBitmap: Bitmap?,
|
|||
|
|
val overlayRulerLength: Float,
|
|||
|
|
val overlayPosition: Offset,
|
|||
|
|
val overlayScale: Float,
|
|||
|
|
val overlayRotation: Float,
|
|||
|
|
val showSettings: Boolean,
|
|||
|
|
val cmCorrectionFactor: Float,
|
|||
|
|
)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### DataStore 持久化
|
|||
|
|
|
|||
|
|
| Key | 类型 | 默认值 |
|
|||
|
|
|-----|------|--------|
|
|||
|
|
| `cm_correction_factor` | Float | 1.0 |
|
|||
|
|
| `is_calibrated` | Boolean | false |
|
|||
|
|
| `default_orientation` | String | "auto" |
|
|||
|
|
| `default_ruler_length` | Float | 3.0 |
|
|||
|
|
|
|||
|
|
统一封装为 `SettingsRepository`。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 项目结构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
app/src/main/java/com/example/androidruler/
|
|||
|
|
├── MainActivity.kt
|
|||
|
|
├── RulerApplication.kt
|
|||
|
|
├── ui/
|
|||
|
|
│ ├── RulerScreen.kt
|
|||
|
|
│ ├── RulerCanvas.kt
|
|||
|
|
│ ├── Markers.kt
|
|||
|
|
│ ├── ControlBar.kt
|
|||
|
|
│ ├── photo/
|
|||
|
|
│ │ ├── PhotoMarkScreen.kt
|
|||
|
|
│ │ ├── CameraCapture.kt
|
|||
|
|
│ │ ├── PhotoEditor.kt
|
|||
|
|
│ │ └── RulerOverlay.kt
|
|||
|
|
│ ├── settings/
|
|||
|
|
│ │ ├── SettingsScreen.kt
|
|||
|
|
│ │ └── CalibrationScreen.kt
|
|||
|
|
│ └── util/
|
|||
|
|
│ └── ImageSaver.kt
|
|||
|
|
├── viewmodel/
|
|||
|
|
│ └── RulerViewModel.kt
|
|||
|
|
├── data/
|
|||
|
|
│ └── SettingsRepository.kt
|
|||
|
|
└── theme/
|
|||
|
|
└── Theme.kt
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## AndroidManifest 权限
|
|||
|
|
|
|||
|
|
```xml
|
|||
|
|
<uses-permission android:name="android.permission.CAMERA" />
|
|||
|
|
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"
|
|||
|
|
android:maxSdkVersion="28" />
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 边界情况
|
|||
|
|
|
|||
|
|
| 场景 | 处理 |
|
|||
|
|
|------|------|
|
|||
|
|
| DPI 返回异常（如 160） | 弹窗提示手动校准 |
|
|||
|
|
| 首次启动无校准数据 | 用自动 DPI 先行绘制，顶部显示校准提示条 |
|
|||
|
|
| 屏幕旋转 | 标记点位置按比例换算保留 |
|
|||
|
|
| 标记点极短距离（<1mm） | 显示 "< 1mm" |
|
|||
|
|
| 拍照权限拒绝 | 提示引导去设置页开启 |
|
|||
|
|
| 相机不可用 | 模拟器/无相机设备降级为纯标尺模式 |
|
|||
|
|
| 图片保存失败 | Toast 提示重试 |
|