From e529904b6fdec34c69e471a99e47d4ce21cbe380 Mon Sep 17 00:00:00 2001 From: lukas91 Date: Tue, 3 Sep 2024 09:13:35 +0500 Subject: [PATCH] =?UTF-8?q?=D0=94=D0=BE=D0=B1=D0=B0=D0=B2=D0=B8=D1=82?= =?UTF-8?q?=D1=8C=20README.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 149 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..1af903b --- /dev/null +++ b/README.md @@ -0,0 +1,149 @@ +## О проекте +Главная ссылка: 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&utm_medium=referral&utm_content=matiasdelellis/facerecognition&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, более подходящем для анализа с другими инструментами.