Add face_detection CLI tool

Author: ageitgey

README.md

@@ -109,11 +109,19 @@ While Windows isn't officially supported, helpful users have posted instructions
 
 ## Usage
 
-#### Command-Line Interface
+### Command-Line Interface
 
-When you install `face_recognition`, you get a simple command-line program
-called `face_recognition` that you can use to recognize faces in a
-photograph or folder full for photographs.
+When you install `face_recognition`, you get a two simple command-line 
+programs:
+
+* `face_recognition` - Recognize faces in a photograph or folder full for 
+   photographs.
+* `face_detection` - Find faces in a photograph or folder full for photographs.
+
+#### `face_recognition` command line tool
+
+The `face_recognition` command lets you recognize faces in a photograph or 
+folder full  for photographs.
 
 First, you need to provide a folder with one picture of each person you
 already know. There should be one image file for each person with the
@@ -142,6 +150,25 @@ with the filename and the name of the person found.
 An `unknown_person` is a face in the image that didn't match anyone in
 your folder of known people.
 
+#### `face_detection` command line tool
+
+The `face_detection` lets you find the location (pixel coordinatates) 
+of any faces in an image.
+
+Just run the command `face_detection`, passing in a folder of images 
+to check (or a single image):
+
+```bash
+$ face_detection  ./folder_with_pictures/
+
+examples/image1.jpg,65,215,169,112
+examples/image2.jpg,62,394,211,244
+examples/image2.jpg,95,941,244,792
+```
+
+It prints one line for each face that was detected. The coordinates
+reported are the top, right, bottom and left coordinates of the face (in pixels).
+ 
 ##### Adjusting Tolerance / Sensitivity
 
 If you are getting multiple matches for the same person, it might be that

examples/face_recognition_knn.py

@@ -38,7 +38,7 @@
 import pickle
 from PIL import Image, ImageDraw
 import face_recognition
-from face_recognition.cli import image_files_in_folder
+from face_recognition.face_recognition_cli import image_files_in_folder
 
 ALLOWED_EXTENSIONS = {'png', 'jpg', 'jpeg'}
 

face_recognition/face_detection_cli.py

@@ -0,0 +1,73 @@
+# -*- coding: utf-8 -*-
+from __future__ import print_function
+import click
+import os
+import re
+import face_recognition.api as face_recognition
+import multiprocessing
+import sys
+import PIL.Image
+import itertools
+import numpy as np
+
+
+def print_result(filename, location):
+    top, right, bottom, left = location
+    print("{},{},{},{},{}".format(filename, top, right, bottom, left))
+
+
+def test_image(image_to_check, model):
+    unknown_image = face_recognition.load_image_file(image_to_check)
+    face_locations = face_recognition.face_locations(unknown_image, number_of_times_to_upsample=0, model=model)
+
+    for face_location in face_locations:
+        print_result(image_to_check, face_location)
+
+
+def image_files_in_folder(folder):
+    return [os.path.join(folder, f) for f in os.listdir(folder) if re.match(r'.*\.(jpg|jpeg|png)', f, flags=re.I)]
+
+
+def process_images_in_process_pool(images_to_check, number_of_cpus, model):
+    if number_of_cpus == -1:
+        processes = None
+    else:
+        processes = number_of_cpus
+
+    # macOS will crash due to a bug in libdispatch if you don't use 'forkserver'
+    context = multiprocessing
+    if "forkserver" in multiprocessing.get_all_start_methods():
+        context = multiprocessing.get_context("forkserver")
+
+    pool = context.Pool(processes=processes)
+
+    function_parameters = zip(
+        images_to_check,
+        itertools.repeat(model),
+    )
+
+    pool.starmap(test_image, function_parameters)
+
+
+@click.command()
+@click.argument('image_to_check')
+@click.option('--cpus', default=1, help='number of CPU cores to use in parallel. -1 means "use all in system"')
+@click.option('--model', default="hog", help='Which face detection model to use. Options are "hog" or "cnn".')
+
+def main(image_to_check, cpus, model):
+    # Multi-core processing only supported on Python 3.4 or greater
+    if (sys.version_info < (3, 4)) and cpus != 1:
+        click.echo("WARNING: Multi-processing support requires Python 3.4 or greater. Falling back to single-threaded processing!")
+        cpus = 1
+
+    if os.path.isdir(image_to_check):
+        if cpus == 1:
+            [test_image(image_file, model) for image_file in image_files_in_folder(image_to_check)]
+        else:
+            process_images_in_process_pool(image_files_in_folder(image_to_check), cpus, model)
+    else:
+        test_image(image_to_check, model)
+
+
+if __name__ == "__main__":
+    main()

face_recognition/cli.py face_recognition/face_recognition_cli.py

@@ -39,7 +39,8 @@
     },
     entry_points={
         'console_scripts': [
-            'face_recognition=face_recognition.cli:main'
+            'face_recognition=face_recognition.face_recognition_cli:main',
+            'face_detection=face_recognition.face_detection_cli:main'
         ]
     },
     install_requires=requirements,

setup.py

@@ -15,7 +15,8 @@
 from click.testing import CliRunner
 
 from face_recognition import api
-from face_recognition import cli
+from face_recognition import face_recognition_cli
+from face_recognition import face_detection_cli
 
 
 class Test_face_recognition(unittest.TestCase):
@@ -231,7 +232,7 @@ def test_compare_faces_empty_lists(self):
     def test_command_line_interface_options(self):
         target_string = 'Show this message and exit.'
         runner = CliRunner()
-        help_result = runner.invoke(cli.main, ['--help'])
+        help_result = runner.invoke(face_recognition_cli.main, ['--help'])
         self.assertEqual(help_result.exit_code, 0)
         self.assertTrue(target_string in help_result.output)
 
@@ -241,7 +242,7 @@ def test_command_line_interface(self):
         image_folder = os.path.join(os.path.dirname(__file__), 'test_images')
         image_file = os.path.join(os.path.dirname(__file__), 'test_images', 'obama.jpg')
 
-        result = runner.invoke(cli.main, args=[image_folder, image_file])
+        result = runner.invoke(face_recognition_cli.main, args=[image_folder, image_file])
 
         self.assertEqual(result.exit_code, 0)
         self.assertTrue(target_string in result.output)
@@ -252,7 +253,7 @@ def test_command_line_interface_big_image(self):
         image_folder = os.path.join(os.path.dirname(__file__), 'test_images')
         image_file = os.path.join(os.path.dirname(__file__), 'test_images', 'obama3.jpg')
 
-        result = runner.invoke(cli.main, args=[image_folder, image_file])
+        result = runner.invoke(face_recognition_cli.main, args=[image_folder, image_file])
 
         self.assertEqual(result.exit_code, 0)
         self.assertTrue(target_string in result.output)
@@ -263,7 +264,7 @@ def test_command_line_interface_tolerance(self):
         image_folder = os.path.join(os.path.dirname(__file__), 'test_images')
         image_file = os.path.join(os.path.dirname(__file__), 'test_images', 'obama.jpg')
 
-        result = runner.invoke(cli.main, args=[image_folder, image_file, "--tolerance", "0.55"])
+        result = runner.invoke(face_recognition_cli.main, args=[image_folder, image_file, "--tolerance", "0.55"])
 
         self.assertEqual(result.exit_code, 0)
         self.assertTrue(target_string in result.output)
@@ -274,7 +275,54 @@ def test_command_line_interface_show_distance(self):
         image_folder = os.path.join(os.path.dirname(__file__), 'test_images')
         image_file = os.path.join(os.path.dirname(__file__), 'test_images', 'obama.jpg')
 
-        result = runner.invoke(cli.main, args=[image_folder, image_file, "--show-distance", "1"])
+        result = runner.invoke(face_recognition_cli.main, args=[image_folder, image_file, "--show-distance", "1"])
 
         self.assertEqual(result.exit_code, 0)
         self.assertTrue(target_string in result.output)
+
+    def test_fd_command_line_interface_options(self):
+        target_string = 'Show this message and exit.'
+        runner = CliRunner()
+        help_result = runner.invoke(face_detection_cli.main, ['--help'])
+        self.assertEqual(help_result.exit_code, 0)
+        self.assertTrue(target_string in help_result.output)
+
+    def test_fd_command_line_interface(self):
+        runner = CliRunner()
+        image_file = os.path.join(os.path.dirname(__file__), 'test_images', 'obama.jpg')
+
+        result = runner.invoke(face_detection_cli.main, args=[image_file])
+        self.assertEqual(result.exit_code, 0)
+        parts = result.output.split(",")
+        self.assertTrue("obama.jpg" in parts[0])
+        self.assertEqual(len(parts), 5)
+
+    def test_fd_command_line_interface_folder(self):
+        runner = CliRunner()
+        image_file = os.path.join(os.path.dirname(__file__), 'test_images')
+
+        result = runner.invoke(face_detection_cli.main, args=[image_file])
+        self.assertEqual(result.exit_code, 0)
+        self.assertTrue("obama_partial_face2.jpg" in result.output)
+        self.assertTrue("obama.jpg" in result.output)
+        self.assertTrue("obama2.jpg" in result.output)
+        self.assertTrue("obama3.jpg" in result.output)
+        self.assertTrue("biden.jpg" in result.output)
+
+    def test_fd_command_line_interface_hog_model(self):
+        target_string = 'obama.jpg'
+        runner = CliRunner()
+        image_file = os.path.join(os.path.dirname(__file__), 'test_images', 'obama.jpg')
+
+        result = runner.invoke(face_detection_cli.main, args=[image_file, "--model", "hog"])
+        self.assertEqual(result.exit_code, 0)
+        self.assertTrue(target_string in result.output)
+
+    def test_fd_command_line_interface_cnn_model(self):
+        target_string = 'obama.jpg'
+        runner = CliRunner()
+        image_file = os.path.join(os.path.dirname(__file__), 'test_images', 'obama.jpg')
+
+        result = runner.invoke(face_detection_cli.main, args=[image_file, "--model", "cnn"])
+        self.assertEqual(result.exit_code, 0)
+        self.assertTrue(target_string in result.output)