坐标系管理技术决策文档

// ❌ 历史代码：混用两种坐标系
fun calculateEyeDistance() {
    val imageLeftEye = getImageLeftEye()      // 图像坐标系
    val userRightEye = getUserRightEye()      // 人脸坐标系
    
    // Bug: 两种坐标系混合计算，结果错误
    val distance = sqrt((imageLeftEye.x - userRightEye.x)^2 + ...)
}

❌ 模糊描述：
- "左眼外眼角"
- "右眉眉头"

问题：
- 是图像左侧还是被拍摄者左侧？
- 前置和后置是否一致？

// ✅ 正确标注
val imageLeftEye = getImageLeftEye()      // [图像坐标系]
val userLeftEye = getUserLeftEye()        // [人脸坐标系]

// ❌ 错误：未标注
val leftEye = getLeftEye()                // 歧义！

/**
 * [图像坐标系] 获取图像左侧眼睛的中心点
 * 
 * @return 图像坐标系中的点（原点在左上角，x 向右增加，y 向下增加）
 * @see COORDINATE_SYSTEM_STANDARD.md 坐标系规范
 */
fun getImageLeftEyeCenter(): Point {
    // ...
}

/**
 * [人脸坐标系] 获取被拍摄者左眼的中心点
 * 
 * @param isFrontCamera 是否为前置摄像头（影响坐标映射）
 * @return 图像坐标系中的点（已根据前后置自动转换）
 * @note 前置时返回图像右侧的点，后置时返回图像左侧的点
 */
fun getUserLeftEyeCenter(isFrontCamera: Boolean): Point {
    // ...
}

// ❌ 错误：混用两种坐标系
fun processFace() {
    val imageLeftEye = getImageLeftEye()      // 图像坐标系
    val userRightEye = getUserRightEye()      // 人脸坐标系
    val distance = calculateDistance(imageLeftEye, userRightEye)  // ❌ 混用！
}

// ✅ 正确：统一使用一种坐标系
fun processFace() {
    val imageLeftEye = getImageLeftEye()
    val imageRightEye = getImageRightEye()
    val distance = calculateDistance(imageLeftEye, imageRightEye)  // ✅ 同一种
}

/**
 * [坐标转换] 将人脸坐标系转换为图像坐标系
 * 
 * @param userLandmarks 人脸坐标系的关键点列表
 * @param isFrontCamera 是否为前置摄像头
 * @return 图像坐标系的关键点列表
 */
fun convertUserToImageCoordinates(
    userLandmarks: List<Point>,
    isFrontCamera: Boolean
): List<Point> {
    return userLandmarks.map { point ->
        if (isFrontCamera) {
            // 前置摄像头：镜像翻转
            Point(1.0f - point.x, point.y)
        } else {
            // 后置摄像头：保持不变
            point
        }
    }
}

/**
 * [坐标转换] 将图像坐标系转换为人脸坐标系
 * 
 * @param imageLandmarks 图像坐标系的关键点列表
 * @param isFrontCamera 是否为前置摄像头
 * @return 人脸坐标系的关键点列表
 */
fun convertImageToUserCoordinates(
    imageLandmarks: List<Point>,
    isFrontCamera: Boolean
): List<Point> {
    // 逆转换：与上面相同（镜像是对称操作）
    return convertUserToImageCoordinates(imageLandmarks, isFrontCamera)
}

❌ 错误（未标注坐标系）：
- "左眼外眼角"
- "右眉眉头"

✅ 正确（明确标注）：
- "[图像坐标系] 图像左侧眼睛的外眼角"
- "[人脸坐标系] 被拍摄者右眉的眉头"
- "[图像坐标系] 图像右侧眉毛的眉头（后置时对应被拍摄者右眉）"

## 3. 人脸关键点映射

> **坐标系说明**：本节所有坐标均基于**图像坐标系**（观察者视角）。
> - 图像左侧 = x 坐标较小的一侧
> - 图像右侧 = x 坐标较大的一侧
> - 前置摄像头镜像后，图像左侧对应被拍摄者右脸

| 索引 | 部位 | 说明 |
|------|------|------|
| 52-57 | [图像坐标系] 图像右侧眼睛外轮廓 | 后置时对应被拍摄者右眼 |
| 58-63 | [图像坐标系] 图像左侧眼睛外轮廓 | 后置时对应被拍摄者左眼 |

# 检测代码
cd /Users/guoshuai/AndroidStudioProjects/PicMe
scripts/check-coordinate-annotation.sh

# 检测文档
scripts/check-doc-coordinate-annotation.sh

#!/bin/bash
# .git/hooks/pre-commit
# 提交前自动检查坐标系标注

echo "🔍 运行坐标系标注检查..."

# 检查暂存的文件
STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E "\.(kt|md)$")

if [ -z "$STAGED_FILES" ]; then
    exit 0
fi

ERRORS=0

for file in $STAGED_FILES; do
    # 检查 Kotlin 文件
    if [[ $file == *.kt ]]; then
        FUZZY_COMMENTS=$(grep -n "左眼\|右眼\|左眉\|右眉" "$file" | \
            grep -v "\[图像坐标系\]" | \
            grep -v "\[人脸坐标系\]" | \
            grep -v "imageLeft" | \
            grep -v "imageRight")
        
        if [ ! -z "$FUZZY_COMMENTS" ]; then
            echo "❌ $file 中存在未标注坐标系的注释:"
            echo "$FUZZY_COMMENTS"
            ERRORS=$((ERRORS + 1))
        fi
    fi
    
    # 检查 Markdown 文件
    if [[ $file == *.md ]]; then
        FUZZY_DOCS=$(grep -n "左眼\|右眼\|左眉\|右眉" "$file" | \
            grep -v "\[图像坐标系\]" | \
            grep -v "\[人脸坐标系\]" | \
            grep -v "图像左侧" | \
            grep -v "图像右侧")
        
        if [ ! -z "$FUZZY_DOCS" ]; then
            echo "❌ $file 中存在未标注坐标系的描述:"
            echo "$FUZZY_DOCS"
            ERRORS=$((ERRORS + 1))
        fi
    fi
done

if [ $ERRORS -gt 0 ]; then
    echo "\n❌ 发现 $ERRORS 个文件存在坐标系标注问题"
    echo "请参考 docs/07-STANDARDS/COORDINATE_SYSTEM.md 修复"
    exit 1
fi

echo "✅ 坐标系标注检查通过"
exit 0

chmod +x .git/hooks/pre-commit

class FaceProcessor {
    fun applyMakeup() {
        val leftEye = getLeftEye()          // 歧义！
        val rightEye = getRightEye()        // 歧义！
        
        // 可能混用了不同坐标系
        val center = (leftEye + rightEye) / 2
    }
}

class FaceProcessor {
    /**
     * [图像坐标系] 应用妆容效果
     */
    fun applyMakeup() {
        // 统一使用图像坐标系
        val imageLeftEye = getImageLeftEye()
        val imageRightEye = getImageRightEye()
        
        val center = (imageLeftEye + imageRightEye) / 2
        
        // 传递给 Shader
        shader.setUniform("u_eyeCenter", center.toNDC())
    }
}

class BeautyController {
    fun process(userLandmarks: List<Point>) {
        // 直接使用，没有明确转换
        renderer.render(userLandmarks)  // ❌ 坐标系不明确
    }
}

class BeautyController {
    fun process(
        userLandmarks: List<Point>,  // [人脸坐标系] 输入
        isFrontCamera: Boolean
    ) {
        // 明确转换到图像坐标系
        val imageLandmarks = convertUserToImageCoordinates(
            userLandmarks,
            isFrontCamera
        )
        
        // 渲染层使用图像坐标系
        renderer.render(imageLandmarks)  // ✅ 坐标系明确
    }
}

## 人脸关键点索引

| 索引 | 部位 |
|------|------|
| 52-57 | 右眼外轮廓 |
| 58-63 | 左眼外轮廓 |

## 人脸关键点索引

> **坐标系说明**：本节所有坐标均基于**图像坐标系**（观察者视角）。

| 索引 | 部位 | 说明 |
|------|------|------|
| 52-57 | [图像坐标系] 图像右侧眼睛外轮廓 | 后置时对应被拍摄者右眼 |
| 58-63 | [图像坐标系] 图像左侧眼睛外轮廓 | 后置时对应被拍摄者左眼 |

# 运行检测脚本，必须全部通过
scripts/check-coordinate-annotation.sh    # ✅ 通过
scripts/check-doc-coordinate-annotation.sh # ✅ 通过