# Face Recognition - 얼굴 인식 라이브러리

**Built by KCEE Tech**

**번역자 주:**

본 프로젝트 face_recognition은 강력하고 간단하며 사용하기 쉬운 얼굴 인식 오픈소스 프로젝트입니다. 완전한 개발 문서와 응용 사례를 갖추고 있으며, 특히 Raspberry Pi 시스템과 호환됩니다.

한국 개발자들이 얼굴 인식 연구 학습과 코드 기여를 용이하게 하기 위해 본 프로젝트의 README 파일을 한국어로 번역했습니다.

본 프로젝트의 모든 기여자들에게 경의를 표합니다.

**번역자: KCEE Tech 한국어 팀**
**문의사항: https://Kceetech.com**

본 라이브러리는 세계에서 가장 간단한 얼굴 인식 라이브러리로, Python 또는 명령 줄(CLI)에서 얼굴을 인식하고 조작해 볼 수 있습니다.

본 라이브러리는 딥러닝 기반으로 제작된 dlib의 최첨단 얼굴 인식 기능을 사용하여 구축되었습니다. 이 모델은 Labeled Faces in the Wild 기준으로 99.38%의 정확도를 가집니다.

또한, 명령 줄(CLI)에서 이미지 폴더 안에 있는 얼굴 인식 기능을 위한 간단한 `face_recognition` 도구를 제공합니다!

## 특징

#### 사진에서 얼굴 찾기

![얼굴 찾기](https://cloud.githubusercontent.com/assets/896692/23625227/42c65360-025d-11e7-94ea-b12f28cb34b4.png)

```python
import face_recognition
image = face_recognition.load_image_file("your_file.jpg")
face_locations = face_recognition.face_locations(image)
```

#### 사진에 있는 얼굴의 특징을 찾기&조작하기

![얼굴 특징](https://cloud.githubusercontent.com/assets/896692/23625282/7f2d79dc-025d-11e7-8728-d8924596f8fa.png)

```python
import face_recognition
image = face_recognition.load_image_file("your_file.jpg")
face_landmarks_list = face_recognition.face_landmarks(image)
```

얼굴의 특징을 찾는 기능은 여러 중요한 일들에 유용하게 쓰입니다. 예를 들어 디지털 메이크업 (Meitu 같은 것)을 적용하는 것과 같은 정말 멍청한 것들에도 쓰일 수 있습니다:

![디지털 메이크업](https://cloud.githubusercontent.com/assets/896692/23625283/80638760-025d-11e7-80a2-1d2779f7ccab.png)

#### 사진 속 얼굴의 신원 확인하기 

![얼굴 인식](https://cloud.githubusercontent.com/assets/896692/23625229/45e049b6-025d-11e7-89cc-8a71cf89e713.png)

```python
import face_recognition
known_image = face_recognition.load_image_file("biden.jpg")
unknown_image = face_recognition.load_image_file("unknown.jpg")

biden_encoding = face_recognition.face_encodings(known_image)[0]
unknown_encoding = face_recognition.face_encodings(unknown_image)[0]

results = face_recognition.compare_faces([biden_encoding], unknown_encoding)
```

이 라이브러리를 다른 Python 라이브러리와 함께 사용한다면 실시간 얼굴 인식도 가능합니다:

![실시간 얼굴 인식](https://cloud.githubusercontent.com/assets/896692/24430398/36f0e3f0-13cb-11e7-8258-4d0c9ce1e419.gif)

## 설치

### 요구 사항

* Python 3.3+ 또는 Python 2.7
* macOS 또는 Linux (Windows는 공식적으로 지원하지 않으나, 작동할 수도 있음)

### 설치 옵션들:

#### Mac 또는 Linux에서의 설치

우선, Python 바인딩을 통해 dlib이 이미 설치가 되어있는지를 확인해야 합니다.

다음으로, `pip3` (또는 Python2의 경우 `pip2`)을 사용하여 pypi에서의 모듈을 설치하십시오:

```bash
pip3 install face_recognition
```

또는, Docker로 이 라이브러리를 시도해보십시오.

#### Raspberry Pi 2+에서의 설치

Raspberry Pi 2+ 설치 설명서를 참조하십시오.

#### Windows에서 설치하기

Windows는 공식적으로 지원하지는 않지만, 친절한 유저들이 이 라이브러리를 어떻게 설치하는지 설명서를 작성했습니다.

## 사용법

### 명령 줄 인터페이스

`face_recognition`을 설치하면, 두 가지 간단한 명령 줄(CLI) 프로그램을 얻습니다:

* `face_recognition` - 사진 혹은 사진이 들어있는 폴더에서, 얼굴을 인식합니다.
* `face_detection` - 사진 혹은 사진이 들어있는 폴더에서, 얼굴을 찾습니다.

#### `face_recognition` 명령 줄 도구

`face_recognition` 명령을 사용하면 사진 혹은 사진이 들어있는 폴더에서, 얼굴을 인식할 수 있습니다.

그러기 위해서는 먼저, 이미 알고 있는(인식하고자 하는) 각 사람의 사진 한 장이 폴더에 있어야 합니다. 그리고 사진 속 그 사람의 이름을 딴 이미지 파일이 각각 하나씩 있어야 합니다:

![알려진 사람들](https://cloud.githubusercontent.com/assets/896692/23582466/8324810e-00df-11e7-82cf-41515eba704d.png)

다음으로, 식별하고 싶은 파일들이 있는 두 번째 폴더가 필요합니다:

![알려지지 않은 사람들](https://cloud.githubusercontent.com/assets/896692/23582465/81f422f8-00df-11e7-8b0d-75364f641f58.png)

그런 다음, 알고 있는 사람의 폴더와 모르는 사람의 폴더(또는 단일 이미지)를 전달하는 `face_recognition` 명령을 실행하면, 각 이미지에 있는 사람이 누군지 알 수 있습니다:

```bash
$ face_recognition ./pictures_of_people_i_know/ ./unknown_pictures/

/unknown_pictures/unknown.jpg,Barack Obama
/face_recognition_test/unknown_pictures/unknown.jpg,unknown_person
```

각각의 얼굴의 결과는 한 줄로 나타납니다. 각 줄은 파일 이름과 식별된 결과인 사람 이름이 쉼표로 구분되어 나타납니다.

`unknown_person`은 이미지 속에 알고 있는 사람의 폴더에 있는 그 누구와도 일치하지 않는 얼굴임을 의미합니다.

#### `face_detection` 명령 줄 도구

`face_detection` 명령을 사용하면 이미지에서 얼굴의 위치 (픽셀 좌표)를 찾을 수 있습니다.

`face_detection` 명령을 실행하여 검사 할 이미지 폴더 (또는 단일 이미지)를 전달하십시오:

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

감지된 각 얼굴에 대해 한 줄씩 인쇄합니다. 결과값의 좌표는 각각 얼굴의 위쪽, 오른쪽, 아래쪽 및 왼쪽 좌표 (픽셀 단위)입니다.

##### 오차 조절 / 민감도

같은 사람에 대해 여러 개의 항목을 얻었다면, 사진에 있는 사람들이 매우 유사하게 보이기 때문이며 더욱 엄격한 얼굴 비교를 위해 낮은 허용치(tolerance value)가 필요합니다.

`--tolerance` 변수를 이용하여 이를 수행할 수 있습니다. 기본 허용치 값은 0.6이며 숫자가 낮으면 더욱 엄격한 얼굴 비교가 가능합니다:

```bash
$ face_recognition --tolerance 0.54 ./pictures_of_people_i_know/ ./unknown_pictures/

/unknown_pictures/unknown.jpg,Barack Obama
/face_recognition_test/unknown_pictures/unknown.jpg,unknown_person
```

허용치 설정을 조정하기 위해, 각 식별에서의 얼굴 거리를 알고 싶다면 `--show-distance true`를 통해 볼 수 있습니다:

```bash
$ face_recognition --show-distance true ./pictures_of_people_i_know/ ./unknown_pictures/

/unknown_pictures/unknown.jpg,Barack Obama,0.378542298956785
/face_recognition_test/unknown_pictures/unknown.jpg,unknown_person,None
```

##### 더 많은 예제들

파일 이름은 신경 쓰지 않고 각 사진에 있는 사람들의 이름만을 알고 싶다면 다음과 같이 할 수 있습니다:

```bash
$ face_recognition ./pictures_of_people_i_know/ ./unknown_pictures/ | cut -d ',' -f2

Barack Obama
unknown_person
```

##### 얼굴 인식 속도 향상

여러 개의 CPU 코어가 있는 컴퓨터를 사용한다면, 얼굴 인식을 동시에 수행할 수 있습니다. 예를 들면, 4개의 CPU 코어가 있는 환경에서는, 모든 CPU 코어를 병렬로 사용하여 같은 시간 동안 약 4배의 이미지들을 처리할 수 있습니다.

Python 3.4 이상을 사용하는 경우 `--cpus <number_of_cpu_cores_to_use>` 에 매개 변수(parameter)를 전달하십시오:

```bash
$ face_recognition --cpus 4 ./pictures_of_people_i_know/ ./unknown_pictures/
```

또한 `--cpus -1`을 전달하여 시스템의 모든 CPU 코어를 사용할 수도 있습니다.

#### Python 모듈

`face_recognition` 모듈을 불러와(import) 단 몇 줄의 코드만으로 얼굴 조작을 쉽게 할 수 있습니다. 이는 매우 간단합니다!

##### 이미지의 모든 얼굴을 자동으로 찾기

```python
import face_recognition

image = face_recognition.load_image_file("my_picture.jpg")
face_locations = face_recognition.face_locations(image)

# face_locations is now an array listing the co-ordinates of each face!
```

좀 더 정확한 딥 러닝 기반의 얼굴 탐지 모델을 채택할 수도 있습니다.

참고: 이 모델의 성능을 높이려면 (NVidia의 CUDA 라이브러리를 통한) GPU 가속이 필요합니다. 또한 `dlib`을 컴파일링할 때 CUDA 지원(support)을 활성화 할 수 있습니다.

```python
import face_recognition

image = face_recognition.load_image_file("my_picture.jpg")
face_locations = face_recognition.face_locations(image, model="cnn")

# face_locations is now an array listing the co-ordinates of each face!
```

##### 이미지에서 자동으로 사람의 얼굴 특징 찾기

```python
import face_recognition

image = face_recognition.load_image_file("my_picture.jpg")
face_landmarks_list = face_recognition.face_landmarks(image)

# face_landmarks_list is now an array with the locations of each facial feature in each face.
# face_landmarks_list[0]['left_eye'] would be the location and outline of the first person's left eye.
```

##### 이미지에서 얼굴을 인식하고 누구인지 식별하기

```python
import face_recognition

picture_of_me = face_recognition.load_image_file("me.jpg")
my_face_encoding = face_recognition.face_encodings(picture_of_me)[0]

# my_face_encoding은 이제 어느 얼굴과도 비교할 수 있는 내가 가진 얼굴 특징의 보편적인 인코딩을 포함하게 되었습니다. 

unknown_picture = face_recognition.load_image_file("unknown.jpg")
unknown_face_encoding = face_recognition.face_encodings(unknown_picture)[0]

# 이제 `compare_faces`를 통해 두 얼굴이 같은 얼굴인지 비교할 수 있습니다!

results = face_recognition.compare_faces([my_face_encoding], unknown_face_encoding)

if results[0] == True:
    print("It's a picture of me!")
else:
    print("It's not a picture of me!")
```

## Python 코드 예제

모든 예제는 examples 폴더에 있습니다.

#### 얼굴 탐지

* 사진에서 얼굴 찾기
* 사진에서 얼굴 찾기(딥 러닝 사용)
* 이미지 모음에서 얼굴 찾기 w/ GPU (딥 러닝 사용)
* 웹캠을 사용하여 라이브 비디오의 모든 얼굴을 흐리게 처리하기 (OpenCV가 설치되어 있어야 함)

#### 얼굴의 특징

* 사진의 특정 얼굴 특징 확인하기
* 디지털 메이크업 적용하기

#### 얼굴 인식

* 알고있는 사람들의 사진을 기반으로 사진에서 알 수 없는 얼굴을 찾고 인식하기
* 사진 안의 각 사람들을 식별하고 주의에 상자를 그리기
* 얼굴 구분을 참/거짓 구분 대신 숫자로 비교하기
* 웹캠을 사용하여 라이브 비디오의 얼굴 인식하기 - 간단함 / 느린 버전 (OpenCV가 설치되어 있어야 함)
* 웹캠을 사용하여 라이브 비디오의 얼굴 인식하기 - 빠른 버전 (OpenCV가 설치되어 있어야 함)
* 비디오 파일에서 얼굴을 인식하고 새 비디오 파일을 작성하기 (OpenCV가 설치되어 있어야 함)
* Raspberry Pi w/ camera에서의 얼굴 인식하기
* HTTP를 통해 얼굴을 인식하는 웹 서비스 실행하기 (Flask가 설치되어 있어야 함)
* K-nearest neighbors classifier를 통한 얼굴 인식하기

## 독립적인 실행 파일 만들기

`Python`이나 `face_recognition`을 설치할 필요 없이 실행할 수 있는 독립적인 실행형 실행 파일을 만들려면 PyInstaller를 사용하면 됩니다. 그러나, 이 라이브러리로 작업하려면 어느 정도의 설정 커스텀이 필요합니다.

## `face_recognition`을 다루는 글 및 가이드

- 얼굴 인식이 어떻게 작동하는지에 관한 글: 딥 러닝을 통한 현대적 얼굴 인식
  - 알고리즘과 알고리즘이 일반적으로 어떻게 작동하는지
- Adrian Rosebrock의 OpenCV, Python 및 딥 러닝을 통한 얼굴 인식
  - 실제로 얼굴 인식을 사용하는 법
- Adrian Rosebrock의 Raspberry Pi 얼굴 인식
  - Raspberry Pi에서 어떻게 사용하는지
- Adrian Rosebrock의 Python 얼굴 클러스터링
  - 비지도 학습을 사용하여 각 사진에 나타나는 사람을 기반으로 사진을 자동 클러스터하는 방법

## 얼굴 인식이 작동하는지

black box 라이브러리에 의존하는 대신 얼굴 위치와 인식이 어떻게 작동하는지 알고 싶으시다면 관련 글을 읽으십시오.

## 주의 사항

* 얼굴 인식의 모델은 성인에 대한 데이터를 통해 훈련이 되었으며 따라서 어린이의 경우에는 잘 적용이 되지 않습니다. 0.6의 기본 임계 값을 사용한다면 어린이들의 얼굴을 구분하지 못하는 경향이 있습니다.
* 소수 민족마다 정확성이 다를 수 있습니다.

## 클라우드 호스트에 배포 (Heroku, AWS, 기타 등)

`face_recognition`은 C++로 작성된 `dlib`에 의존하기 때문에, Heroku 또는 AWS와 같은 클라우드 호스팅 제공 업체에 이를 사용하는 앱을 배포하는 것은 까다로울 수 있습니다.

더 쉬운 작업을 위해, Docker container에서 `face_recognition`으로 빌드 된 앱을 실행하는 방법을 보여주는 Dockerfile 예제가 있습니다. 이를 통해 Docker 이미지를 지원하는 모든 서비스에 배포할 수 있어야합니다.

다음을 실행하여 Docker 이미지를 로컬로 시도 할 수 있습니다: `docker-compose up --build`

GPU (드라이버 >= 384.81) 및 Nvidia-Docker가 설치된 Linux 사용자는 GPU에서 예제를 실행할 수 있습니다.

## 문제가 있으십니까?

문제가 발생하면 일반적인 오류 섹션을 읽어보십시오.

## 감사의 말

* `dlib`를 만들고 이 라이브러리에 사용된 얼굴 인식 기능과 얼굴 인코딩 모델을 제공한 Davis King에게 많은 감사를 드립니다. 얼굴 인코딩을 지원하는 ResNet에 대한 자세한 내용은 블로그 게시물을 확인하십시오.
* numpy, scipy, scikit-image, pillow 등의 모든 멋진 파이썬 데이터 과학 라이브러리에서 일하는 모든 사람들에게 감사합니다. 이런 종류의 것들을 파이썬에서 쉽고 재미있게 만듭니다.
* Cookiecutter와 audreyr/cookiecutter-pypackage 프로젝트 템플릿 덕분에 파이썬 프로젝트 패키징 방식이 더 괜찮아 졌습니다.

## 지원 및 문의사항

이 프로젝트는 KCEE Tech에 의해 구축되고 유지됩니다.

**기술 지원 및 문의사항:**
- 웹사이트: https://Kceetech.com
- 한국어 번역 관련 문의사항도 언제든지 환영합니다

**Built by KCEE Tech - 모든 권리 보유**