Add Rustface to the feature detection docs (images)

CHANGELOG.txt

@@ -25,6 +25,7 @@ Changelog
  * Add ``purge_revisions`` management command to purge old page revisions (Jacob Topp-Mugglestone, Tom Dyson)
  * Render the Wagtail User Bar on non ``Page`` views (Caitlin White, Coen van der Kamp)
  * Add ability to define ``form_classname`` on ``ListBlock`` & ``StreamBlock`` (LB (Ben Johnston))
+ * Add documentation about how to use `Rustface` for image feature detection (Neal Todd)
  * Fix: Support IPv6 domain (Alex Gleason, Coen van der Kamp)
  * Fix: Ensure link to add a new user works when no users are visible in the users list (LB (Ben Johnston))
  * Fix: `AbstractEmailForm` saved submission fields are now aligned with the email content fields, `form.cleaned_data` will be used instead of `form.fields` (Haydn Greatnews)

docs/advanced_topics/images/feature_detection.rst

@@ -5,18 +5,22 @@ Feature Detection
 
 Wagtail has the ability to automatically detect faces and features inside your images and crop the images to those features.
 
-Feature detection uses `OpenCV <https://opencv.org>`_, the Open Source Computer Vision Library, to detect faces/features in an image when the image is uploaded. The detected features are stored internally as a focal point in the ``focal_point_{x, y, width, height}`` fields on the ``Image`` model. These fields are used by the ``fill`` image filter when an image is rendered in a template to crop the image.
+Feature detection uses third-party tools to detect faces/features in an image when the image is uploaded. The detected features are stored internally as a focal point in the ``focal_point_{x, y, width, height}`` fields on the ``Image`` model. These fields are used by the ``fill`` image filter when an image is rendered in a template to crop the image.
 
 
 Installation
 ------------
 
-Three components are required to get this working with Wagtail:
+Two third-party tools are known to work with Wagtail: One based on OpenCV_ for general feature detection and one based on Rustface_ for face detection.
 
-* OpenCV itself
-* various system-level components that OpenCV relies on
-* a Python interface to OpenCV, exposed as ``cv2``
+.. _OpenCV: https://opencv.org/
 
+.. _Rustface: https://github.com/torchbox/rustface-py/
+
+OpenCV on Debian/Ubuntu
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Feature detection requires OpenCV_ which can be a bit tricky to install as it's not currently pip-installable.
 
 Installation options
 ~~~~~~~~~~~~~~~~~~~~
@@ -72,10 +76,55 @@ means that the Python components have not been set up correctly in your Python e
 If you don't get an import error, installation has probably been successful.
 
 
-Switching on feature detection in Wagtail
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Rustface
+~~~~~~~~
 
-Once OpenCV is installed, you need to set the ``WAGTAILIMAGES_FEATURE_DETECTION_ENABLED`` setting to ``True``:
+Rustface_ is Python library with prebuilt wheel files provided for Linux and macOS. Although implemented in Rust it is pip-installable:
+
+ .. code-block:: console
+
+    $ pip install wheel
+    $ pip install rustface
+
+
+Registering with Willow
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Rustface provides a plug-in that needs to be registered with Willow_.
+
+This should be done somewhere that gets run on application startup:
+
+ .. code-block:: python
+
+    from willow.registry import registry
+    import rustface.willow
+
+    registry.register_plugin(rustface.willow)
+
+For example, in an app's AppConfig.ready_.
+
+.. _Willow: https://github.com/wagtail/Willow
+
+.. _AppConfig.ready: https://docs.djangoproject.com/en/2.2/ref/applications/#django.apps.AppConfig.ready
+
+
+Cropping
+^^^^^^^^
+
+The face detection algorithm produces a focal area that is tightly cropped to the face rather than the whole head.
+
+For images with a single face this can be okay in some cases, e.g. thumbnails, it might be overly tight for "headshots".
+Image renditions can encompass more of the head by reducing the crop percentage (``-c<percentage>``), at the end of the resize-rule, down to as low as 0%:
+
+.. code-block:: html+django
+
+    {% image page.photo fill-200x200-c0 %}
+
+
+Switching on feature detection in Wagtail
+-----------------------------------------
+
+Once installed, you need to set the ``WAGTAILIMAGES_FEATURE_DETECTION_ENABLED`` setting to ``True`` to automatically detect faces/features whenever a new image is uploaded in to Wagtail or when an image without a focal point is saved (this is done via a pre-save signal handler):
 
  .. code-block:: python
 
@@ -85,17 +134,21 @@ Once OpenCV is installed, you need to set the ``WAGTAILIMAGES_FEATURE_DETECTION_
 
 
 Manually running feature detection
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------
 
-Feature detection runs when new images are uploaded in to Wagtail. If you already have images in your Wagtail site and would like to run feature detection on them, you will have to run it manually.
+If you already have images in your Wagtail site and would like to run feature detection on them, or you want to apply feature detection selectively when the ``WAGTAILIMAGES_FEATURE_DETECTION_ENABLED`` is set to ``False`` you can run it manually using the `get_suggested_focal_point()` method on the ``Image`` model.
 
-You can manually run feature detection on all images by running the following code in the Python shell:
+For example, you can manually run feature detection on all images by running the following code in the python shell:
 
  .. code-block:: python
 
-    from wagtail.images.models import Image
+    from wagtail.images import get_image_model
+
+    Image = get_image_model()
 
     for image in Image.objects.all():
         if not image.has_focal_point():
             image.set_focal_point(image.get_suggested_focal_point())
             image.save()
+            
+        

docs/releases/2.10.rst

@@ -34,6 +34,7 @@ Other features
  * Add `purge_revisions` management command to purge old page revisions (Jacob Topp-Mugglestone, Tom Dyson)
  * Render the Wagtail User Bar on non `Page` views (Caitlin White, Coen van der Kamp)
  * Add ability to define `form_classname` on `ListBlock` & `StreamBlock` (LB (Ben Johnston))
+ * Add documentation about how to use ``Rustface`` for image feature detection (Neal Todd)
 
 
 Bug fixes