## О проекте
Главная ссылка: https://github.com/matiasdelellis/facerecognition 

# Распознавание лиц

![Статус PHPUnit](https://img.shields.io/github/workflow/status/matiasdelellis/facerecognition/PHPUnit)
[![Качество кода Scrutinizer](https://scrutinizer-ci.com/g/matiasdelellis/facerecognition/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/matiasdelellis/facerecognition/?branch=master)
[![Покрытие кода](https://scrutinizer-ci.com/g/matiasdelellis/facerecognition/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/matiasdelellis/facerecognition/?branch=master)
[![Значок Codacy](https://api.codacy.com/project/badge/Grade/4b035bd1283349009ad88235d37ddae1)](https://www.codacy.com/app/stalker314314/facerecognition?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=matiasdelellis/facerecognition&amp;utm_campaign=Badge_Grade)
![Загрузки](https://img.shields.io/github/downloads/matiasdelellis/facerecognition/total)
[![Лицензия](https://img.shields.io/badge/license-AGPLv3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0.en.html)

Приложение Nextcloud, реализующее базовую систему распознавания лиц.

FaceRecognition — это приложение Nextcloud, цель которого — распознавание, анализ и агрегация данных о лицах на изображениях пользователей, предоставление дополнительных функций на основе этой информации, все с встроенной конфиденциальностью Nextcloud. Представьте себе Google Photos, но только для лиц (без распознавания объектов...) и таким образом, что ваши изображения никогда не покидают ваш экземпляр Nextcloud. :smiley:

Приложение отслеживает создание новых файлов изображений и ставит их в очередь на последующий анализ. Запланированная задача (или администратор по требованию) берет эту очередь и анализирует изображения на предмет лиц и, если возможно, идентифицирует их, группируя по сходству.

![Скриншоты приложения](https://matiasdelellis.github.io/img/facerecognition/facerecognition-persons-view-small.jpeg "Скриншоты приложения")

## Как это использовать?

Администратор должен правильно настроить приложение, и как только оно заработает, пользователь должен согласиться на анализ своих изображений для поиска своих друзей.
Наконец, пользователь может использовать приложение тремя способами:

 1. В настройках пользователя есть панель "Распознавание лиц", где каждый пользователь должен в первую очередь включить анализ. После включения вы постепенно увидите открытие ваших друзей, и сможете присвоить им имена.
 2. В приложении для файлов пользователь может искать, вводя имя друга, и это покажет все фотографии.
 3. В боковой панели приложения для файлов добавлена вкладка "Люди", где вы можете видеть список ваших друзей на фото и переименовывать их. Также можно выбрать папки, которые вы хотите игнорировать для процесса.
 4. В боковой панели приложения "Фотографии" добавлена вкладка "Люди", где вы можете видеть список ваших друзей на фото и переименовывать их.

## Пожертвования

Если вы хотите поддержать создание и поддержку этого программного обеспечения, рассмотрите возможность пожертвования.

[![Пожертвовать через PayPal](https://img.shields.io/badge/Donate-PayPal-blue)](https://github.com/matiasdelellis/facerecognition/wiki/Donate)
[![Пожертвовать Bitcoin](https://img.shields.io/badge/Donate-Bitcoin-orange)](https://github.com/matiasdelellis/facerecognition/wiki/Donate)
[![Пожертвовать Ethereum](https://img.shields.io/badge/Donate-Ethereum-blueviolet)](https://github.com/matiasdelellis/facerecognition/wiki/Donate)

## Установка, настройка и использование

#### Требования

 * Nextcloud 22+
 * [Привязки Dlib PHP](https://github.com/goodspb/pdlib)
 * [PHP Bzip2](https://www.php.net/manual/en/book.bzip2.php)
 * 1 ГБ оперативной памяти

#### Установка

Идеально, если вы выполните требования, вы можете установить и активировать его из магазина приложений Nextcloud. Для подробной и дополнительной информации читайте документацию об [установке](https://github.com/matiasdelellis/facerecognition/wiki/Installation).

#### Настройка

Перед началом анализа изображений вы должны указать, сколько памяти вы хотите выделить для обработки изображений, а затем должны правильно установить и настроить предварительно обученные модели, используя команду `occ face:setup`. Для подробной и дополнительной информации читайте документацию о [моделях](https://github.com/matiasdelellis/facerecognition/wiki/Models#install-models).

Затем вы должны указать размер изображений, используемых во временных файлах из панели настроек Nextcloud. Эта настройка будет зависеть от вашей установки и иметь прямое влияние на потребление памяти. Для подробной и дополнительной информации читайте документацию о [временных файлах](https://github.com/matiasdelellis/facerecognition/wiki/Settings#temporary-files).

#### Тестирование приложения

Мы рекомендуем интенсивно тестировать приложение перед началом анализа реальных данных пользователей. Для этого вы можете создать нового пользователя в вашем экземпляре Nextcloud и загрузить несколько фотографий из интернета. Затем вы должны выполнить команду `occ face:background_job -u new_user -t 900` для этого пользователя и оценить результат. Для подробной и дополнительной информации читайте документацию к этой команде ниже.

#### Планирование фоновой задачи

Приложение предназначено для работы как запланированная задача. Это позволяет анализировать фотографии и постепенно показывать результаты пользователю. Вы можете узнать о некоторых способах настройки этого в нашей документации о [планировании фоновых задач](https://github.com/matiasdelellis/facerecognition/wiki/Schedule-Background-Task).

## Команды occ

Приложение добавляет команды в [интерфейс командной строки Nextcloud](https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/occ_command.html).

#### Начальная настройка

`occ face:setup [-M|--memory MEMORY] [-m|--model MODEL]`

Эта команда отвечает за выполнение необходимых настроек для использования приложения.

Если указан `MEMORY`, она установит максимальную память, используемую для обработки изображений. Это значение будет ограничено доступной памятью системы и конфигурацией PHP. Вы можете использовать числа в байтах (1073741824 для 1GB), или с суффиксом единиц (1024M или 1G), но обратите внимание, что это без пробела.

Если указан `MODEL_ID`, будет установлена предварительно обученная модель для распознавания лиц.

Вы должны выполнить обе настройки перед продолжением любой команды приложения. Если вы не укажете ни одну из этих опций, команда вернет текущую конфигурацию.

#### Анализ лиц

`occ face:background_job [-u|--user_id USER_ID] [-t|--timeout TIMEOUT] [--defer-clustering] [-M|--max_image_area MAX_IMAGE_AREA]`

Эта команда выполняет всю работу. Она отвечает за поиск изображений, их анализ и кластеризацию найденных на них лиц в группы похожих людей.

Будьте осторожны, эта команда может потреблять много CPU и памяти! Перед тем как поместить ее в cron job, рекомендуется попробовать вручную, чтобы убедиться, что у вас есть все необходимое и достаточно ресурсов на вашем компьютере.

Команда предназначена для непрерывной работы, поэтому вы захотите настроить ее на выполнение через cron время от времени, вместе с указанным таймаутом. Она может быть запущена каждые 15 минут с таймаутом `-t 900` (таким образом, она сама остановится через 15 минут, и cron запустит ее снова), или один раз в день с таймаутом 2 часа, как `-t 7200`.

Если указан `USER_ID`, она будет циклически обрабатывать файлы данного пользователя. Имейте в виду, что каждый пользователь должен индивидуально включить анализ, в противном случае эта команда проигнорирует пользователя.

Если указан `TIMEOUT`, она остановится после указанных секунд и продолжит в следующем исполнении. Используйте это значение в сочетании с временем запланированной задачи для распределения нагрузки на систему в течение дня.

Если указан `MAX_IMAGE_AREA`, это ограничит максимальную площадь (в пикселях^2) изображения, которое подается в нейронную сеть, эффективно снижая необходимую память. Используйте это, если распознавание лиц случайно завершается с ошибкой.

Если используется опция `--defer-clustering`, она изменит порядок выполнения процесса, откладывая кластеризацию лиц в конец анализа, чтобы получить лица в одном выполнении команды.

#### Создание альбомов в приложении Фотографии

`face:sync-albums [-u|--user_id USER_ID]`

Эта команда создает фотоальбомы в приложении Nexcloud Photos с фотографиями каждого найденного человека.

Обратите внимание, что эти альбомы можно редактировать в приложении Photos, и любые изменения будут игнорироваться и отменены при следующем выполнении этой команды.

Эта команда также предназначена для регулярного выполнения, чтобы синхронизировать любые изменения пользователя, так как эта команда является единственной, которая будет обновлять альбомы.

Если указан `USER_ID`, она просто синхронизирует альбомы для этого пользователя.

#### Сброс информации

`occ face:reset [--all] [--model] [--image-errors] [--clustering] [-u|--user_id USER_ID]`

Эта команда может полностью стереть все изображения, лица и кластеры лиц. Она идеальна, если вы хотите начать с чистого листа по какой-либо причине.

Вы должны указать, хотите ли вы полностью сбросить базу данных `[--all]` или только текущую модель `[--model]` и все изображения должны быть проанализированы снова, или вы можете сбросить только кластеризацию лиц `[--clustering]` и только кластеризация должна быть выполнена снова, или сбросить только изображения, которые имели ошибки `[--image-errors]`, чтобы попытаться проанализировать их снова.

Если указан `USER_ID`, она просто сбросит информацию конкретного пользователя.

#### Миграция моделей

`occ face:migrate [-m|--model_id MODEL_ID] [-u|--user_id USER_ID]`

Эта команда позволяет мигрировать лица, полученные в одной модели, в новую. Обратите внимание, что имена лиц не мигрируются, и пользователь должен переименовать их снова.
Всегда рекомендуется анализировать с нуля любую настроенную модель, но вы можете сэкономить много времени, мигрируя ее.

Вы должны указать, какую модель вы хотите мигрировать, используя опцию `MODEL_ID`.

Если указан `USER_ID`, просто мигрируйте лица для данного пользователя.

#### Статистика

`occ face:stats [-u|--user_id USER_ID] [-j|--json]`

Эта команда возвращает сводку количества изображений, лиц и найденных лиц.

Если указан `USER_ID`, возвращает статистику только для данного пользователя.

Если используется аргумент `--json`, она выводит статистику в формате json, более подходящем для анализа с другими инструментами.

#### Прогресс

`occ face:progress`

Эта команда просто возвращает прогресс анализа и оценочное время до завершения.

Если используется аргумент `--json`, она выводит статистику в формате json, более подходящем для анализа с другими инструментами.
