人脸坐标系与左右命名规范

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

// ✅ 正确：统一使用一种坐标系
fun processFace() {
    // 方案 A：统一使用图像坐标系（推荐）
    val imageLeftEye = getImageLeftEye()
    val imageRightEye = getImageRightEye()
    val distance = calculateDistance(imageLeftEye, imageRightEye)
    
    // 方案 B：统一使用人脸坐标系（需转换）
    val userLeftEye = getUserLeftEye(isFrontCamera)
    val userRightEye = getUserRightEye(isFrontCamera)
    val distance = calculateDistance(userLeftEye, userRightEye)
}

// ✅ 正确：跨坐标系转换有明确函数
fun convertUserToImageCoordinates(
    userLandmarks: List<Point>,
    isFrontCamera: Boolean
): List<Point> {
    return userLandmarks.map { point ->
        if (isFrontCamera) {
            Point(1.0f - point.x, point.y)  // 前置镜像
        } else {
            point
        }
    }
}

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

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

## 3. 人脸关键点映射

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

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

// ❌ 错误：未标注坐标系
// 右眼外轮廓（画面左侧）
val rightEyeContour = landmarks.slice(52..57)

// ✅ 正确：明确标注坐标系
// [图像坐标系] 图像右侧的眼睛外轮廓（后置时对应被拍摄者右眼）
val imageRightEyeContour = landmarks.slice(52..57)

// ✅ 正确：语义标注（需说明转换关系）
// [人脸坐标系] 被拍摄者右眼（前置时位于图像右侧，后置时位于图像左侧）
val userRightEye = if (isFrontCamera) {
    landmarks[IMAGE_RIGHT_EYE_INDICES]  // 前置：图像右侧
} else {
    landmarks[IMAGE_LEFT_EYE_INDICES]   // 后置：图像左侧
}

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

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

// ❌ 错误：未标注坐标系，存在歧义
val leftEye = face.leftEye
val rightEye = face.rightEye

// ✅ 正确：图像坐标系（推荐，项目统一标准）
val imageLeftEye = face.getImageLeftEye()    // 图像左侧的眼睛
val imageRightEye = face.getImageRightEye()  // 图像右侧的眼睛

// ✅ 可接受：人脸坐标系（需明确标注，谨慎使用）
val userLeftEye = face.getUserLeftEye(isFrontCamera)    // 被拍摄者左眼
val userRightEye = face.getUserRightEye(isFrontCamera)  // 被拍摄者右眼

/**
 * 眼睛位置枚举（明确标注坐标系）
 */
enum class EyePosition {
    /** [图像坐标系] 图像左侧的眼睛（x 坐标较小） */
    IMAGE_LEFT,
    
    /** [图像坐标系] 图像右侧的眼睛（x 坐标较大） */
    IMAGE_RIGHT,
    
    /** [人脸坐标系] 被拍摄者左眼（前置时对应 IMAGE_RIGHT） */
    USER_LEFT,
    
    /** [人脸坐标系] 被拍摄者右眼（前置时对应 IMAGE_LEFT） */
    USER_RIGHT
}

// ❌ 错误：混用图像坐标系和人脸坐标系
class FaceProcessor {
    fun process() {
        val imageLeftEye = landmarks[IMAGE_LEFT_EYE]     // 图像坐标系
        val userRightEye = getUserRightEye()              // 人脸坐标系
        
        // ❌ 错误：两种坐标系混合计算
        val center = (imageLeftEye + userRightEye) / 2
    }
}

// ✅ 正确：统一使用图像坐标系
class FaceProcessor {
    fun process() {
        val imageLeftEye = landmarks[IMAGE_LEFT_EYE]
        val imageRightEye = landmarks[IMAGE_RIGHT_EYE]
        
        // ✅ 正确：同一种坐标系计算
        val center = (imageLeftEye + imageRightEye) / 2
    }
}

// ✅ 正确：如需转换，使用明确的转换函数
class FaceProcessor {
    fun process() {
        // 从人脸坐标系转换为图像坐标系
        val userLandmarks = getUserLandmarks()
        val imageLandmarks = convertUserToImageCoordinates(
            userLandmarks, 
            isFrontCamera
        )
        
        // 统一使用图像坐标系处理
        val imageLeftEye = imageLandmarks[IMAGE_LEFT_EYE]
        val imageRightEye = imageLandmarks[IMAGE_RIGHT_EYE]
        val center = (imageLeftEye + imageRightEye) / 2
    }
}

# 搜索模糊的左右描述
grep -r "左眼\|右眼\|左眉\|右眉" docs/ --include="*.md"
grep -r "leftEye\|rightEye" app/src/ --include="*.kt" | grep -v "imageLeft\|imageRight"

# 修改前
| 33 | 右眉眉头（画面左侧） | 43 |
| 38 | 左眉眉头（画面右侧） | 101 |

# 修改后
| 33 | 图像右侧眉毛的眉头（被拍摄者右眉） | 43 |
| 38 | 图像左侧眉毛的眉头（被拍摄者左眉） | 101 |

// 修改前
// 右眼外轮廓：统一 52-57（画面左侧）
val rightEyeContour = unifiedLandmarks.slice(52..57)

// 修改后
// 图像左侧的眼睛外轮廓（对应被拍摄者右眼）：统一索引 52-57
val imageLeftEyeContour = unifiedLandmarks.slice(52..57)

// Phase 1: 添加别名（向后兼容）
@Deprecated("使用 imageLeftEye 替代", ReplaceWith("imageLeftEye"))
val leftEye = imageLeftEye

// Phase 2: 逐步迁移调用方
// Phase 3: 移除旧命名

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

enum class EyePosition {
    IMAGE_LEFT,   // 图像左侧的眼睛
    IMAGE_RIGHT   // 图像右侧的眼睛
}

fun getEyeCenter(position: EyePosition): Point {
    return when (position) {
        EyePosition.IMAGE_LEFT -> landmarks[IMAGE_LEFT_EYE_INDEX]
        EyePosition.IMAGE_RIGHT -> landmarks[IMAGE_RIGHT_EYE_INDEX]
    }
}

// ❌ 不明确
fun getLeftEye(): Point

// ✅ 明确
fun getImageLeftEye(): Point
fun getFaceSpaceLeftEye(): Point  // 如果确实需要人脸坐标系

## 坐标系说明

本文档中所有坐标均基于**图像坐标系**：

// ❌ 错误：假设前置和后置的"左眼"相同
val leftEye = if (isFrontCamera) {
    face.leftEye  // 前置：这是图像右侧！
} else {
    face.leftEye  // 后置：这是图像左侧
}

// ✅ 正确：统一使用图像坐标系
val imageLeftEye = face.getImageLeftEye()  // 永远是图像左侧

// ❌ 错误：镜像后仍然叫 leftEye
val mirroredLeftEye = mirror(face.leftEye)  // 实际已变成图像右侧

// ✅ 正确：镜像后重新评估位置
val imageLeftEye = if (isMirrored) {
    face.originalRightEye  // 镜像后，原右眼变成图像左侧
} else {
    face.originalLeftEye
}

# 文档说：
"左眼使用索引 58-63"

# 代码却是：
val imageLeftEye = landmarks[58..63]  // 实际是图像左侧

# 问题：文档的"左眼"指什么？

#!/bin/bash
# scripts/check-coordinate-annotation.sh
# 检测代码中未标注坐标系的左右描述

echo "🔍 检查未标注坐标系的注释..."

# 搜索常见的模糊描述
FUZZY_PATTERNS=(
    "左眼"
    "右眼"
    "左眉"
    "右眉"
    "左侧脸"
    "右侧脸"
)

for pattern in "${FUZZY_PATTERNS[@]}"; do
    echo "\n搜索: $pattern"
    grep -rn "$pattern" app/src/ --include="*.kt" | grep -v "\[图像坐标系\]" | grep -v "\[人脸坐标系\]" | grep -v "imageLeft" | grep -v "imageRight" | grep -v "userLeft" | grep -v "userRight"
done

echo "\n✅ 检查完成"

#!/bin/bash
# scripts/check-doc-coordinate-annotation.sh
# 检测文档中未标注坐标系的左右描述

echo "🔍 检查文档中的坐标系标注..."

# 搜索 Markdown 文件中的模糊描述
grep -rn "左眼\|右眼\|左眉\|右眉" docs/ --include="*.md" | \
    grep -v "\[图像坐标系\]" | \
    grep -v "\[人脸坐标系\]" | \
    grep -v "图像左侧" | \
    grep -v "图像右侧" | \
    grep -v "被拍摄者"

echo "\n✅ 检查完成"

#!/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

# 查找潜在的歧义描述
find docs/ -name "*.md" -exec grep -l "左眼\|右眼\|左眉\|右眉" {} \;

# 检查代码注释
find app/src/ -name "*.kt" -exec grep -n "//.*左眼\|//.*右眼" {} +

## PicMe 开发规范

### 坐标系与命名
- 阅读 [人脸坐标系与左右命名规范](../02-ARCHITECTURE/ADR/ADR-003-coordinate-system-management.md)
- 理解图像坐标系 vs 人脸坐标系的区别
- 掌握前置/后置摄像头的镜像差异

// custom-lint-rules/AmbiguousNamingDetector.kt
class AmbiguousNamingDetector : Detector(), Detector.UastScanner {
    override fun getApplicableUastTypes() = listOf<UClass>(
        UVariableDeclaration::class.java
    )
    
    override fun createUastHandler(context: JavaContext) = object : UElementHandler() {
        override fun visitVariable(node: UVariableDeclaration) {
            val name = node.name
            if (name.matches(Regex("^(left|right)(Eye|Eyebrow|Cheek)$"))) {
                context.report(
                    issue = AMBIGUOUS_NAMING,
                    location = context.getLocation(node),
                    message = "变量名 '$name' 有歧义，请使用 'imageLeft' 或 'imageRight' 前缀"
                )
            }
        }
    }
}