(image_feature_detection)=

# 특징 감지

Wagtail은 이미지 안의 얼굴과 특징을 자동으로 감지하고, 그 특징에 맞춰 이미지를 자르는 기능이 있습니다.

특징 감지는 서드파티 도구를 사용하여 이미지가 업로드될 때 이미지의 얼굴/특징을 감지합니다. 감지된 특징은 `Image` 모델의 `focal_point_{x, y, width, height}` 필드에 초점 정보로 내부적으로 저장됩니다. 이 필드들은 템플릿에서 이미지가 렌더링될 때 `fill` 이미지 필터에 의해 이미지를 자르는 데 사용됩니다.

## 설치

Wagtail과 함께 작동하는 것으로 알려진 두 가지 서드파티 도구가 있습니다: 일반적인 특징 감지를 위한 [OpenCV](https://opencv.org/) 기반 도구와 얼굴 감지를 위한 [Rustface](https://github.com/torchbox/rustface-py/) 기반 도구입니다.

### Debian/Ubuntu에서 OpenCV 설치하기

특징 감지에는 [OpenCV](https://opencv.org/)가 필요하며, 현재 pip으로 설치할 수 없기 때문에 설치가 다소 까다로울 수 있습니다.

이러한 구성 요소를 설치하는 방법은 여러 가지가 있지만, 각각의 경우 OpenCV 자체와 파이썬 인터페이스가 모두 올바르게 설치되었는지 테스트해야 합니다.

#### `opencv-python` 설치하기

[opencv-python](https://pypi.org/project/opencv-python/)은 PyPI에서 사용할 수 있습니다.
여기에는 OpenCV에 대한 파이썬 인터페이스와 정적으로 빌드된 OpenCV 바이너리 자체가 포함되어 있습니다.

설치 방법:

```sh
pip install opencv-python
```

시스템에 설치된 다른 항목에 따라 이것만으로도 충분할 수 있습니다. 경량 리눅스 시스템에서는 누락된 시스템 라이브러리를 식별하고 설치해야 할 수도 있습니다 (예: Debian Stretch의 슬림 버전에서는 `apt` 로 `libsm6 libxrender1 libxext6` 를 설치해야 함).

#### 시스템 수준 패키지 설치하기

시스템 수준 패키지는 필요한 모든 구성 요소를 처리할 수 있습니다. 운영 체제에서 사용 가능한 것을 확인하십시오. 예를 들어, Debian에서는 [python-opencv](https://packages.debian.org/stretch/python-opencv)를 사용할 수 있으며, 이는 OpenCV 자체를 설치하고 파이썬 바인딩을 설정합니다.

그러나 파이썬 사용 방식(예: 사용 중인 버전)에 대해 잘못된 가정을 할 수 있으므로 아래 설명된 대로 테스트하십시오.

#### 설치 테스트하기

설치를 테스트합니다:

```python
python3
>>> import cv2
```

다음과 같은 오류는:

```python
ImportError: libSM.so.6: cannot open shared object file: No such file or directory
```

필요한 시스템 라이브러리(이 경우 `libsm6`)가 설치되지 않았음을 나타냅니다.

반면에,

```python
ModuleNotFoundError: No module named 'cv2'
```

는 파이썬 구성 요소가 파이썬 환경에 올바르게 설정되지 않았음을 의미합니다.

import 오류가 발생하지 않으면 설치가 성공적으로 완료된 것입니다.

### Rustface

[Rustface](https://github.com/torchbox/rustface-py/)는 리눅스 및 macOS용으로 사전 빌드된 wheel 파일이 제공되는 파이썬 라이브러리입니다. Rust로 구현되었지만 pip으로 설치할 수 있습니다:

```sh
pip install wheel
pip install rustface
```

#### Willow에 등록하기

Rustface는 [Willow](https://github.com/wagtail/Willow)에 등록해야 하는 플러그인을 제공합니다.

이 작업은 애플리케이션 시작 시 실행되는 곳에서 수행해야 합니다:

```python
from willow.registry import registry
import rustface.willow

registry.register_plugin(rustface.willow)
```

예를 들어, 앱의 [`AppConfig.ready`](django.apps.AppConfig.ready)에서 할 수 있습니다.

## 자르기

얼굴 감지 알고리즘은 머리 전체가 아닌 얼굴에 꼭 맞게 잘린 초점 영역을 생성합니다.

단일 얼굴이 있는 이미지의 경우, 어떤 경우에는 괜찮을 수 있지만(예: 썸네일), "얼굴 사진"에는 너무 빡빡할 수 있습니다.
이미지 렌디션은 크기 조정 규칙 끝에 있는 자르기 비율(`-c<percentage>`)을 0%까지 낮춤으로써 머리 부분을 더 많이 포함할 수 있습니다:

```html+django
{% image page.photo fill-200x200-c0 %}
```

## Wagtail에서 특징 감지 켜기

일단 설치되면, `WAGTAILIMAGES_FEATURE_DETECTION_ENABLED` 설정을 `True` 로 설정하여 Wagtail에 새 이미지가 업로드될 때마다 또는 초점이 없는 이미지가 저장될 때마다(이는 pre-save 시그널 핸들러를 통해 수행됨) 자동으로 얼굴/특징을 감지하도록 해야 합니다:

```python
# settings.py

WAGTAILIMAGES_FEATURE_DETECTION_ENABLED = True
```

## 수동으로 특징 감지 실행하기

Wagtail 사이트에 이미 이미지가 있고 이에 대해 특징 감지를 실행하고 싶거나, `WAGTAILIMAGES_FEATURE_DETECTION_ENABLED` 가 `False` 로 설정된 경우 선택적으로 특징 감지를 적용하고 싶다면, `Image` 모델의 `get_suggested_focal_point()` 메서드를 사용하여 수동으로 실행할 수 있습니다.

예를 들어, 파이썬 셸에서 다음 코드를 실행하여 모든 이미지에 대해 수동으로 특징 감지를 실행할 수 있습니다:

```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()
```