add face detector support

docs/doc/en/sidebar.yaml

@@ -49,8 +49,10 @@ items:
         label: AI object classify
     -   file: vision/yolov5.md
         label: YOLOv5 object detect
+    -   file: vision/face_detection.md
+        label: Face detect and keypoints
     -   file: vision/face_recognition.md
-        label: Face detect
+        label: Face recognition
     -   file: vision/body_key_points.md
         label: Human critical point detection
     -   file: vision/self_learn_classifier.md

docs/doc/en/vision/face_detection.md

@@ -0,0 +1,47 @@
+---
+title: MaixPy Face Detection and Key Points Detection
+---
+
+## Introduction
+
+Face detection can be used in many places, such as providing the step of face detection for face recognition, or applications related to face tracking, and more.
+
+The face detection provided here can not only detect faces but also detect 5 key points, including two eyes, one nose, and the two corners of a mouth.
+
+![face detection](../../assets/face_detection.jpg)
+
+## Using Face Detection in MaixPy
+
+MaixPy officially provides two face detection models, sourced from the open projects [face detector 1MB with landmark](https://github.com/biubug6/Face-Detector-1MB-with-landmark) and [Retinaface](https://github.com/biubug6/Pytorch_Retinaface).
+
+To use them, first download a model, either one as there's not much difference between them:
+* [face detector 1MB with landmark](https://maixhub.com/model/zoo/377)
+* [Retinaface](https://maixhub.com/model/zoo/378)
+
+Then copy the model file to your device, see [Using MaixVision](../basic/maixvision.md) for how to copy.
+> The default image contains a file that can be used directly; if not available, you must download it yourself. The downloaded zip package contains multiple resolutions to choose from; the higher the resolution, the more precise but also more time-consuming.
+
+Next, run the code. The following line of commented code is for loading the `Retinaface` model, choose which line of code to use based on the model you downloaded.
+
+> To use this function, MaixPy must >= 4.1.4.
+
+```python
+from maix import camera, display, image, nn, app
+import math
+
+detector = nn.FaceDetector(model="/root/models/face_detector.mud")
+# detector = nn.Retinaface(model="/root/models/retinaface.mud")
+
+cam = camera.Camera(detector.input_width(), detector.input_height(), detector.input_format())
+dis = display.Display()
+
+while not app.need_exit():
+    img = cam.read()
+    objs = detector.detect(img, conf_th = 0.4, iou_th = 0.45)
+    for obj in objs:
+        img.draw_rect(obj.x, obj.y, obj.w, obj.h, color = image.COLOR_RED)
+        radius = math.ceil(obj.w / 10)
+        img.draw_keypoints(obj.points, image.COLOR_RED, size = radius if radius < 5 else 4)
+    dis.show(img)
+
+```

docs/doc/zh/sidebar.yaml

@@ -49,6 +49,8 @@ items:
         label: AI 物体分类
     -   file: vision/yolov5.md
         label: YOLOv5 物体检测
+    -   file: vision/face_detection.md
+        label: 人脸及关键点检测
     -   file: vision/face_recognition.md
         label: 人脸识别
     -   file: vision/body_key_points.md

docs/doc/zh/vision/face_detection.md

@@ -0,0 +1,54 @@
+---
+title: MaixPy 人脸检测和关键点检测
+---
+
+## 简介
+
+人脸检测在很多地方都能用到，比如是为人脸识别提供人脸检测这一步骤，或者是人脸跟踪相关的应用等等。
+
+这里提供的人脸检测不光可以检测到人脸，还能检测到 5 个关键点，包括两个眼睛，一个鼻子，一张嘴巴的两个嘴角。
+
+![face detection](../../assets/face_detection.jpg)
+
+
+## MaixPy 中使用人脸检测
+
+MaixPy 官方提供了两种人脸检测模型，分别来自开源项目 [face detector 1MB with landmark](https://github.com/biubug6/Face-Detector-1MB-with-landmark) 和 [Retinafate](https://github.com/biubug6/Pytorch_Retinaface)。
+
+要使用需要先下载模型，选择一个即可，两者区别不大：
+* [face detector 1MB with landmark](https://maixhub.com/model/zoo/377)
+* [Retinafate](https://maixhub.com/model/zoo/378)
+
+然后拷贝模型文件到设备，拷贝方法见 [MaixVision 使用](../basic/maixvision.md)。
+> 默认镜像里面有一个文件，可以直接使用，如果没有则需要你自己下载，而且下载的压缩包里面有多个分辨率可以选择，分辨率越高越精准但耗时更长
+
+然后执行代码，这里有一行被注释了代码是加载`Retinafae`模型，根据你下载的模型选择使用哪一行代码
+
+> 本功能需要 MaixPy >= 4.1.4 才能使用
+
+
+```python
+from maix import camera, display, image, nn, app
+import math
+
+
+detector = nn.FaceDetector(model="/root/models/face_detector.mud")
+# detector = nn.Retinaface(model="/root/models/retinaface.mud")
+
+cam = camera.Camera(detector.input_width(), detector.input_height(), detector.input_format())
+dis = display.Display()
+
+while not app.need_exit():
+    img = cam.read()
+    objs = detector.detect(img, conf_th = 0.4, iou_th = 0.45)
+    for obj in objs:
+        img.draw_rect(obj.x, obj.y, obj.w, obj.h, color = image.COLOR_RED)
+        radius = math.ceil(obj.w / 10)
+        img.draw_keypoints(obj.points, image.COLOR_RED, size = radius if radius < 5 else 4)
+    dis.show(img)
+
+```
+
+
+
+

examples/vision/ai_detect/nn_facedetector.py

@@ -0,0 +1,20 @@
+from maix import camera, display, image, nn, app
+import math
+
+# download model from:
+#                     https://maixhub.com/model/zoo/377 (face_detector https://github.com/biubug6/Face-Detector-1MB-with-landmark)
+#                     https://maixhub.com/model/zoo/378 (retinafate https://github.com/biubug6/Pytorch_Retinaface)
+detector = nn.FaceDetector(model="/root/models/face_detector.mud")
+# detector = nn.Retinaface(model="/root/models/retinaface.mud")
+
+cam = camera.Camera(detector.input_width(), detector.input_height(), detector.input_format())
+dis = display.Display()
+
+while not app.need_exit():
+    img = cam.read()
+    objs = detector.detect(img, conf_th = 0.4, iou_th = 0.45)
+    for obj in objs:
+        img.draw_rect(obj.x, obj.y, obj.w, obj.h, color = image.COLOR_RED)
+        radius = math.ceil(obj.w / 10)
+        img.draw_keypoints(obj.points, image.COLOR_RED, size = radius if radius < 5 else 4)
+    dis.show(img)

maix/version.py

@@ -3,6 +3,6 @@
 
 version_major = 4
 version_minor = 1
-version_patch = 3
+version_patch = 4
 
 __version__ = "{}.{}.{}".format(version_major, version_minor, version_patch)