mirror of
https://github.com/wagtail/wagtail.git
synced 2024-11-30 11:10:43 +01:00
24ef0e62e6
Fix code block indentation in tutorial.rst Prevent it from being displayed as a quote. Fix indentation in pages.rst Fix indentation in indexing.rst Fix indentation in searching.rst Fix indentation in backends.rst Fix indentation in renditions.rst Fix indentation in custom_image_model.rst Fix indentation in feature_detection.rst Fix indentation in image_serve_view.rst Fix indentation in custom_document_model.rst Fix indentation in i18n.rst Fix indentation in privacy.rst Fix indentation in page_editing_interface.rst Fix indentation in rich_text_internals.rst Fix indentation in extending_hallo.rst Fix indentation in configuration.rst Fix indentation in usage.rst Fix indentation in theory.rst Fix indentation in model_reference.rst Fix indentation in queryset_reference.rst Configure editors to indent .rst files with 2 spaces In order for the documentation to be styled correctly, the generator depends on indentation. Too much indentation can result in the content being wrapped in a quote block, which looks bad. Fix indentation in sitemaps.rst Fix indentation in frontendcache.rst Fix indentation in routablepage.rst Fix indentation in table_block.rst Fix routablepage.rst autodocs disppearing Fix indentation in table_block.rst Fix indentation in redirects.rst Fix indentation in table_documentation-modes.rst Fix indentation in browser_issues.rst Fix indentation in release_process.rst Fix indentation of release notes One more indent fix in the release notes Fix indentation warnings Fix warning about undefined label in docs Error during `make html`: wagtail/docs/releases/1.7.rst:25: WARNING: undefined label: jpeg_image_quality
152 lines
5.2 KiB
ReStructuredText
152 lines
5.2 KiB
ReStructuredText
.. _image_feature_detection:
|
|
|
|
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 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
|
|
------------
|
|
|
|
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: 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.
|
|
|
|
There is more than one way to install these components, but in each case you will need to test that both OpenCV itself *and* the Python interface have been correctly installed.
|
|
|
|
|
|
Install ``opencv-python``
|
|
`````````````````````````
|
|
|
|
`opencv-python <https://pypi.org/project/opencv-python/>`_ is available on PyPI.
|
|
It includes a Python interface to OpenCV, as well as the statically-built OpenCV binaries themselves.
|
|
|
|
To install:
|
|
|
|
.. code-block:: console
|
|
|
|
$ pip install opencv-python
|
|
|
|
Depending on what else is installed on your system, this may be all that is required. On lighter-weight Linux systems, you may need to identify and install missing system libraries (for example, a slim version of Debian Stretch requires ``libsm6 libxrender1 libxext6`` to be installed with ``apt``).
|
|
|
|
|
|
Install a system-level package
|
|
``````````````````````````````
|
|
|
|
A system-level package can take care of all of the required components. Check what is available for your operating system. For example, `python-opencv <https://packages.debian.org/stretch/python-opencv>`_ is available for Debian; it installs OpenCV itself, and sets up Python bindings.
|
|
|
|
However, it may make incorrect assumptions about how you're using Python (for example, which version you're using) - test as described below.
|
|
|
|
|
|
Testing the installation
|
|
````````````````````````
|
|
|
|
Test the installation::
|
|
|
|
python3
|
|
>>> import cv2
|
|
|
|
An error such as::
|
|
|
|
ImportError: libSM.so.6: cannot open shared object file: No such file or directory
|
|
|
|
indicates that a required system library (in this case ``libsm6``) has not been installed.
|
|
|
|
On the other hand,
|
|
|
|
::
|
|
|
|
ModuleNotFoundError: No module named 'cv2'
|
|
|
|
means that the Python components have not been set up correctly in your Python environment.
|
|
|
|
If you don't get an import error, installation has probably been successful.
|
|
|
|
|
|
Rustface
|
|
^^^^^^^^
|
|
|
|
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
|
|
|
|
# settings.py
|
|
|
|
WAGTAILIMAGES_FEATURE_DETECTION_ENABLED = True
|
|
|
|
|
|
Manually running feature detection
|
|
----------------------------------
|
|
|
|
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.
|
|
|
|
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 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()
|
|
|
|
|