{"id":31962151,"url":"https://github.com/core2002/stellareyes","last_synced_at":"2025-10-14T16:35:47.843Z","repository":{"id":317797168,"uuid":"1003598119","full_name":"Core2002/StellarEyes","owner":"Core2002","description":" This Android app uses on-device machine learning to enable real-time face detection and recognition via the camera. It captures images, detects faces, extracts facial features (embeddings), and matches them against a stored database for identification. Users can also manage the stored facial data.","archived":false,"fork":false,"pushed_at":"2025-10-03T03:55:52.000Z","size":82747,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-03T05:43:19.783Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Core2002.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-17T11:41:41.000Z","updated_at":"2025-10-03T03:55:58.000Z","dependencies_parsed_at":"2025-10-03T05:54:19.231Z","dependency_job_id":null,"html_url":"https://github.com/Core2002/StellarEyes","commit_stats":null,"previous_names":["core2002/stellareyes"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Core2002/StellarEyes","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Core2002%2FStellarEyes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Core2002%2FStellarEyes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Core2002%2FStellarEyes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Core2002%2FStellarEyes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Core2002","download_url":"https://codeload.github.com/Core2002/StellarEyes/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Core2002%2FStellarEyes/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279019575,"owners_count":26086753,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-14T16:35:44.733Z","updated_at":"2025-10-14T16:35:47.835Z","avatar_url":"https://github.com/Core2002.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# StellarEyes\n\n## 简介\n\nStellarEyes 是一个 Android 应用程序，利用设备端机器学习 (ML) 技术，通过设备的摄像头实时进行人脸检测和人脸识别。它能够从摄像头捕捉图像，检测图像中的人脸，提取人脸特征（embeddings），并将这些特征与已存储的人脸数据库进行比对，以识别个体。用户还可以管理已存储的人脸数据。\n\n## 核心功能\n\n* **实时人脸检测**: 使用 Google ML Kit 从摄像头预览中实时检测人脸。\n* **人脸特征提取**: 使用 TensorFlow Lite (FaceNet 模型) 从检测到的人脸图像中提取高维特征向量 (embeddings)。\n* **人脸识别与匹配**:\n  * 使用 NCNN 进行高效的余弦相似度计算，比对新提取的人脸特征与数据库中已存储的特征。\n  * 识别已知人脸或提示为新用户。\n* **人脸数据管理**:\n  * 存储和管理人脸特征、关联的图像及名称。\n  * 提供查看、重命名和删除已存储人脸的功能。\n  * 数据通过 `VectorSearchEngine` 存储在本地 JSON 文件 (`vectors.json`) 中。\n* **可配置的识别行为**:\n  * **持续推理**: 可选择是否持续分析摄像头画面中的人脸。\n  * **处理所有/最大人脸**: 可选择处理检测到的所有人脸，或仅处理画面中最大的人脸。\n  * **自动录入**: 可选择是否自动将符合条件的新人脸添加到数据库。\n* **摄像头控制**: 支持前后摄像头切换。\n* **UI**: 基于 Jetpack Compose 构建的现代化用户界面，支持深色主题。\n\n## 主要技术栈\n\n* **Kotlin**: 作为主要开发语言，充分利用了协程 (Coroutines) 进行异步处理。\n* **Jetpack Compose**: 用于构建声明式用户界面。\n* **CameraX**: 用于简化摄像头访问和预览。\n* **Google ML Kit**:\n  * **Face Detection**: 用于在图像中快速准确地检测人脸。\n* **TensorFlow Lite (TFLite)**:\n  * 使用预训练的 `facenet_512.tflite` 模型生成 512 维的人脸特征向量。\n  * 支持 GPU 代理以加速推理。\n* **NCNN**: 腾讯开源的高性能神经网络推理框架。\n  * 通过 JNI 调用 C++ 实现，用于初始化 NCNN 环境、运行模型（可能指除了FaceNet之外的模型，或NCNN实现的算子）以及计算特征向量间的余弦相似度。\n* **Android NDK (C++)**: `main.cpp` 和 `stellar_eyes_native` 库表明了原生代码的集成，主要用于 NCNN 的相关操作。\n* **DataStore**: 用于持久化存储应用设置 (如持续推理开关、深色主题等)。\n* **Kotlinx Serialization**: 用于将 `VectorSearchEngine` 中的人脸数据序列化为 JSON 格式进行存储和加载。\n* **Material Design 3**: 应用的视觉风格和组件库。\n* **ViewModel**: 用于管理 UI 相关数据并处理业务逻辑。\n* **Navigation Compose**: 用于在不同的 Composable 屏幕间导航。\n\n## 工作流程简述\n\n1. **权限请求**: 应用启动时检查并请求摄像头权限。\n2. **摄像头预览**: 使用 CameraX 显示实时摄像头画面。\n3. **NCNN 初始化**: 在后台协程中初始化 NCNN 环境。\n4. **FaceNet 初始化**: 在专用协程（`TFLiteThread`）中初始化 FaceNet TFLite 模型，可选择启用 GPU 代理。\n5. **人脸检测 (ML Kit)**: `CameraPreview` 对每一帧图像进行分析，使用 ML Kit FaceDetector 检测人脸。\n6. **绘制边界框**: `FaceBoundingBoxOverlay` 在检测到的人脸周围绘制红色矩形框。\n7. **图像捕捉与处理**:\n    * 根据用户设置（持续推理或手动触发），捕捉当前帧或特定图像。\n    * 从捕捉到的图像中裁剪出人脸区域 (支持处理单个最大人脸或所有人脸)。\n    * 裁剪后的人脸图像被缩放到 FaceNet 模型所需的输入尺寸 (160x160)。\n8. **特征提取 (FaceNet)**:\n    * 预处理后的人脸图像输入到 FaceNet 模型中，生成 512 维的特征向量。\n9. **人脸识别/录入 (VectorSearchEngine \u0026 NCNN)**:\n    * `FaceRecognitionViewModel` 调用 `VectorSearchEngine`。\n    * `VectorSearchEngine` 使用 NCNN 提供的余弦相似度计算，将新提取的特征向量与数据库中存储的所有向量进行比较。\n    * 如果找到足够相似的匹配项 (相似度 \u003e 0.84f)，则识别为已知用户。\n    * 如果没有匹配项且启用了自动录入，并且满足特定条件（如连续帧检测到同一未知人脸），则将新的人脸特征、图像（Base64编码）和自动生成的名称存入数据库。\n10. **结果展示**: 在 UI 上显示识别结果（匹配到的用户、相似度）或新用户已添加的提示。\n11. **数据管理**: 用户可以通过 \"管理数据\" 界面查看、重命名或删除已存储的人脸条目。所有更改都会保存到 `vectors.json`。\n\n## 项目模块\n\n* **StellarEyes.app**: 核心 Android 应用模块。\n  * `MainActivity.kt`: 应用主入口，处理权限和导航。\n  * `NcnnController.kt`: NCNN JNI 接口。\n  * `FaceNet.kt`: FaceNet TFLite 模型加载与推理。\n  * `VectorSearchEngine.kt`: 人脸特征向量数据库及搜索逻辑。\n  * `ui/camera/`: 包含摄像头预览、人脸检测、识别相关的 UI 和 ViewModel。\n  * `ui/managefaces/`: 包含管理人脸数据的 UI 和 ViewModel。\n  * `ui/settings/`: 包含设置和关于页面的 UI 和 ViewModel。\n  * `data/`: 数据模型和存储相关。\n* (其他标准模块如 .androidTest, .unitTest, buildSrc 等)\n\n## 如何编译和运行\n\n1. **克隆项目**:\n\n    ```bash\n    git clone [项目GIT仓库地址]\n    cd StellarEyes\n    ```\n\n2. **Android Studio**:\n    * 使用 Android Studio (建议最新稳定版) 打开项目。\n    * 等待 Gradle 同步完成。\n    * 确保已安装 Android NDK 以编译 C++ 代码 (NCNN JNI 部分)。\n3. **模型文件**:\n    * 确保 `facenet_512.tflite` 模型文件位于 `app/src/main/assets/` 目录下。\n    * NCNN 模型文件（如果 NCNN JNI `initNcnn` 方法需要）也应放置在 `assets` 中并由 C++ 代码正确加载。\n4. **构建和运行**:\n    * 连接 Android 设备或启动模拟器 (API 级别适配见 `build.gradle.kts`)。\n    * 点击 \"Run\" 按钮。\n\n## 待办事项 / 未来改进 (可选)\n\n* [可以添加一些未来可能实现的功能]\n* 优化模型加载和初次运行的性能。\n* 提供更详细的错误处理和用户反馈。\n\n## 许可证\n\n[请在此处填写项目的许可证信息，例如 MIT, Apache 2.0 等]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcore2002%2Fstellareyes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcore2002%2Fstellareyes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcore2002%2Fstellareyes/lists"}