rustface/
lib.rs

1// This file is part of the open-source port of SeetaFace engine, which originally includes three modules:
2//      SeetaFace Detection, SeetaFace Alignment, and SeetaFace Identification.
3//
4// This file is part of the SeetaFace Detection module, containing codes implementing the face detection method described in the following paper:
5//
6//      Funnel-structured cascade for multi-view face detection with alignment awareness,
7//      Shuzhe Wu, Meina Kan, Zhenliang He, Shiguang Shan, Xilin Chen.
8//      In Neurocomputing (under review)
9//
10// Copyright (C) 2016, Visual Information Processing and Learning (VIPL) group,
11// Institute of Computing Technology, Chinese Academy of Sciences, Beijing, China.
12//
13// As an open-source face recognition engine: you can redistribute SeetaFace source codes
14// and/or modify it under the terms of the BSD 2-Clause License.
15//
16// You should have received a copy of the BSD 2-Clause License along with the software.
17// If not, see < https://opensource.org/licenses/BSD-2-Clause>.
18
19mod classifier;
20mod common;
21mod detector;
22mod feat;
23pub mod math;
24pub mod model;
25
26pub use crate::common::FaceInfo;
27pub use crate::common::ImageData;
28pub use crate::common::Rectangle;
29pub use crate::model::{load_model, read_model, Model};
30
31use crate::detector::FuStDetector;
32use std::io;
33
34/// Create a face detector, based on a file with model description.
35pub fn create_detector(path_to_model: &str) -> Result<Box<dyn Detector>, io::Error> {
36    let model = load_model(path_to_model)?;
37    Ok(create_detector_with_model(model))
38}
39
40/// Create a face detector, based on the provided model.
41pub fn create_detector_with_model(model: Model) -> Box<dyn Detector> {
42    Box::new(FuStDetector::new(model))
43}
44
45pub trait Detector {
46    /// Detect faces on input image.
47    ///
48    /// (1) The input image should be gray-scale, i.e. `num_channels` set to 1.
49    /// (2) Currently this function does not give the Euler angles, which are
50    ///     left with invalid values.
51    ///
52    /// # Panics
53    ///
54    /// Panics if `image` is not a legal image, e.g. it
55    /// - is not gray-scale (`num_channels` is not equal to 1)
56    /// - has `width` or `height` equal to 0
57    fn detect(&mut self, image: &ImageData) -> Vec<FaceInfo>;
58
59    /// Set the size of the sliding window.
60    ///
61    /// The minimum size is constrained as no smaller than 20.
62    ///
63    /// # Panics
64    ///
65    /// Panics if `wnd_size` is less than 20.
66    fn set_window_size(&mut self, wnd_size: u32);
67
68    /// Set the sliding window step in horizontal and vertical directions.
69    ///
70    /// The steps should take positive values.
71    /// Usually a step of 4 is a reasonable choice.
72    ///
73    /// # Panics
74    ///
75    /// Panics if `step_x` or `step_y` is less than or equal to 0.
76    fn set_slide_window_step(&mut self, step_x: u32, step_y: u32);
77
78    /// Set the minimum size of faces to detect.
79    ///
80    /// The minimum size is constrained as no smaller than 20.
81    ///
82    /// # Panics
83    ///
84    /// Panics if `min_face_size` is less than 20.
85    fn set_min_face_size(&mut self, min_face_size: u32);
86
87    /// Set the maximum size of faces to detect.
88    ///
89    /// The maximum face size actually used is computed as the minimum among:
90    /// user specified size, image width, image height.
91    fn set_max_face_size(&mut self, max_face_size: u32);
92
93    /// Set the factor between adjacent scales of image pyramid.
94    ///
95    /// The value of the factor lies in (0.1, 0.99). For example, when it is set as 0.5,
96    /// an input image of size w x h will be resized to 0.5w x 0.5h, 0.25w x 0.25h,  0.125w x 0.125h, etc.
97    ///
98    /// # Panics
99    ///
100    /// Panics if `scale_factor` is less than 0.01 or greater than 0.99
101    fn set_pyramid_scale_factor(&mut self, scale_factor: f32);
102
103    /// Set the score threshold of detected faces.
104    ///
105    /// Detections with scores smaller than the threshold will not be returned.
106    /// Typical threshold values include 0.95, 2.8, 4.5. One can adjust the
107    /// threshold based on his or her own test set.
108    ///
109    /// Smaller values result in more detections (possibly increasing the number of false positives),
110    /// larger values result in fewer detections (possibly increasing the number of false negatives).
111    ///
112    /// # Panics
113    ///
114    /// Panics if `thresh` is less than or equal to 0.
115    fn set_score_thresh(&mut self, thresh: f64);
116}
rustface/lib.rs

rustface/
lib.rs
