From 1b9b12d41230755c58bc2c9d51d497d4e1d1efcd Mon Sep 17 00:00:00 2001 From: ioctl-user Date: Sun, 11 Dec 2022 14:17:28 +0300 Subject: [PATCH] Update documentation and release files. --- README.md | 126 +++++++++++++++++++++++++++++---------------------- README_ru.md | 119 +++++++++++++++++++++++++++--------------------- setup.py | 5 +- 3 files changed, 141 insertions(+), 109 deletions(-) diff --git a/README.md b/README.md index 4940789..38f08d3 100644 --- a/README.md +++ b/README.md @@ -4,97 +4,113 @@ +## Оглавление +**[Introduction](#introduction)** -## Introduction - -Sevimon is an open source program written in Python. It allows facial muscle tension to be monitored through a video camera, which can be used to eliminate stress, indirectly influence mood and, with long-term use, prevent the appearance of facial wrinkles. - -Sevimon works by first identifying a face on an image and then comparing it to each of eight emotions (anger, contempt, disgust, fear, joy, no emotion, sadness, surprise), and then giving each emotion some kind of similarity rating. - -The values obtained are stored in the logbook in text format for later analysis by the sevistat program. -In addition, for each emotion in the settings file, you can set the upper and lower limits of values, at the crossing of which a reminder is issued. +**[Running in Docker in Linux](#running-in-docker-in-Linux)** -At the first start-up the models are downloaded, after which the programme does not require an internet connection. +**[Running binary versions on Windows 10 and later](#running-binary-versions-on-Windows-10-and-later)** -## Direct program startup -## Linux/UNIX +**[Install and run universal interpreted versions of programs](#install-and-run-universal-interpreted-versions-of-programs)** -Install the following packages from the distribution: git, python, python-pip. -Download the project, install the dependencies that are missing in the system: -```shell -git clone https://github.com/ioctl-user/sevimon.git -cd sevimon -python3 -m pip install -r requirements.txt -``` +**[Project files license](#project-files-license)** -Use the command `sevimon.py` from the project folder to run it. -To display statistics, use the command `sevistat.py` from the project folder. Currently at least two ours of stat needed. +**[Acknowledgements](#acknowledgements)** -At first startup, models are downloaded, a configuration file ~/.config/sevimon/sevimon.cfg is created, which can be edited if necessary. -The emotion log is written to the ~/.cache/sevimon/log/ . - -### Windows +## Introduction -Install package [python with built-in pip](https://www.python.org/downloads/windows/). -Install [git package](https://git-scm.com/download/win). +Sevimon is a set of open source programs written in Python. It allows facial muscle tension to be monitored through a video camera, which can be used to eliminate overstretching, indirectly influence mood and, with long-term use, prevent the appearance of facial wrinkles. -Run Powershell by typing Win+X and select userland mode. +The basic Sevimon programme works like this: first a face is identified on an image, then each of the eight emotions (anger, contempt, disgust, fear, joy, no emotion, sadness, surprise) is given a sort of rating for the facial expression. -Enter the following commands to download the package and install the dependencies: -```shell -git clone https://github.com/ioctl-user/sevimon.git -cd sevimon -python3 -m pip install -r requirements.txt -``` +The values obtained are stored in the logbook in text format for later analysis by the `sevistat' program. +In addition, for each emotion in the settings file, the upper and lower limits of the values can be set and a reminder is given when these are crossed. +The settings file, whose name is displayed on start-up, can be changed in any text editor, or you can use the `sevicfg` graphical utility to configure it. The default setting is to give a warning when anger and surprise are detected, which corresponds to a frown on the eyebrows and a wrinkled forehead. -Use the command `python.exe -m sevimon.py` from the project folder to run it. -Use the command `python.exe -m sevistat.py` from the project folder to display the statistics. Currently at least two ours of stat needed. -The first run downloads the models, creates an editable configuration file sevimon.cfg and a folder for the emotion log. +The models are downloaded the first time you start, after which an internet connection is not required. -In case of lack of DLL modules, install [MS Visual C](https://learn.microsoft.com/cpp/windows/latest-supported-vc-redist). +## Running in Docker in Linux +Prepared a Docker image with the program, all its dependencies and models, which runs without access to the network. -## Run via Docker in Linux -The sevimon program is started as follows: +The sevimon program is run as follows: ```shell -xhost +localhost mkdir -p ~/.cache/sevimon/log/ mkdir -p ~/.config/sevimon/ echo > ~/.config/sevimon/sevimon.cfg +xhost +"local:docker@" docker run -it --rm --privileged \ --net=none \ - -w /sevimon/ \ -e DISPLAY=$DISPLAY \ -e LANG=$LANG \ -v /tmp/.X11-unix:/tmp/.X11-unix \ -v $HOME/.Xauthority:/root/.Xauthority \ -v $HOME/.config/sevimon/sevimon.cfg:/root/.config/sevimon/sevimon.cfg \ - -v $HOME/.cache/sevimon/log:/root/.cache/sevimon/log \ + -v $HOME/.cache/sevimon/log:/root/.local/state/sevimon/log \ -v /dev/video0:/dev/video0 \ - ioctl2/sevimon /sevimon/sevimon.py -xhost -localhost + ioctl2/sevimon:latest sevimon +xhost -"local:docker@" ``` -The sevistat program is started as follows: +The sevistat programme is started with a command: ```shell -xhost +localhost +xhost +"local:docker@" docker run -it --rm --privileged \ --net=none \ - -w /sevimon/ \ -e DISPLAY=$DISPLAY \ -e LANG=$LANG \ -v /tmp/.X11-unix:/tmp/.X11-unix \ -v $HOME/.Xauthority:/root/.Xauthority \ -v $HOME/.config/sevimon/sevimon.cfg:/root/.config/sevimon/sevimon.cfg \ - -v $HOME/.cache/sevimon/log:/root/.cache/sevimon/log \ - ioctl2/sevimon /sevimon/sevistat.py -xhost -localhost + -v $HOME/.cache/sevimon/log:/root/.local/state/sevimon/log \ + ioctl2/sevimon:latest sevistat +xhost -"local:docker@" +``` +The sevicfg programme is started as follows: +```shell +xhost +"local:docker@" +docker run -it --rm --privileged \ + --net=none \ + -e DISPLAY=$DISPLAY \ + -e LANG=$LANG \ + -v /tmp/.X11-unix:/tmp/.X11-unix \ + -v $HOME/.Xauthority:/root/.Xauthority \ + -v $HOME/.config/sevimon/sevimon.cfg:/root/.config/sevimon/sevimon.cfg \ + -v $HOME/.cache/sevimon/log:/root/.local/state/sevimon/log \ + ioctl2/sevimon:latest sevicfg +xhost -"local:docker@" ``` -## Project file licence +## Running binary versions on Windows 10 and later +Prepared [binary program builds](https://github.com/ioctl-user/sevimon/releases/download/v0.1/sevimon_win10_v0.1.zip) with all its dependencies for Windows (x86\_64). Models are automatically downloaded the first time you run it. -AGPL v3 or newer +## Install and run universal interpreted versions of programs +### Preparatory steps for Linux/UNIX +Install the python and python-pip packages from the distribution. -## Acknowledgements +### Preparatory steps for Windows +Install package [python along with built-in pip](https://www.python.org/downloads/windows/). -The [Centerface](https://github.com/Star-Clouds/CenterFace/blob/master/prj-python/) project is used to search for faces in images. -The project [HSEmotion](https://github.com/HSE-asavchenko/face-emotion-recognition) is used for emotion detection. +In case of lack of DLL at startup, install [MS Visual C](https://learn.microsoft.com/cpp/windows/latest-supported-vc-redist). + +Run Powershell by typing Win+X and selecting to run as a normal user. + +### Installation and startup + +Install the project with all dependencies: +```shell +python3 -m pip install sevimon +``` + +Warnings may appear during the process asking to add the executable path to the environment variables - this should be done. + +Use the ``sevimon'' command to start the main program. The first run downloads the models and creates a text configuration file. +You can run the program `sevicfg` to configure it. +Use the command `sevistat` to display statistics. It must have been accumulated for at least 2 hours beforehand. + +## Project files licence + +AGPL v3 or newer. + +## Acknowledgements +The [Centerface] project (https://github.com/Star-Clouds/CenterFace/blob/master/prj-python/) is used to search for faces in an image. +The [HSEmotion] project (https://github.com/HSE-asavchenko/face-emotion-recognition) is used for emotion detection. diff --git a/README_ru.md b/README_ru.md index 7792b14..db62c17 100644 --- a/README_ru.md +++ b/README_ru.md @@ -4,96 +4,113 @@ +## Оглавление +**[Введение](#Введение)** -## Введение +**[Запуск в докере в Linux](#запуск-в-докере-в-linux)** -Sevimon это программа с открытым исходным кодом написанная на питоне. Позволяет отслеживать напряжение лицевых мышц через видеокамеру, что может быть использовано для устранения перенапряжения, косвенного воздействия на настроение и, при длительном применении, предотвращения появляния мимических морщин. +**[Запуск бинарных версий в Windows 10 и более новых](#запуск-бинарных-версий-в-Windows-10-и-более-новых)** -Sevimon работает следующим образом: сначала на изображении определяется лицо, затем лицо сопоставляется с каждой из восьми эмоций (злость, презрение, отвращение, страх, радость, отсутствие эмоций, грусть, удивление), после чего для каждой эмоции даётся некая оценка похожести. +**[Установка и запуск универсальных интерпретирумых версий программ](#установка-и-запуск-универсальных-интерпретирумых-версий-программ)** -Полученные значения сохраняются в журнале в текстовом формате для последующего анализа программой sevistat. -Кроме того, для каждой эмоции в файле настроек можно задать верхние и нижние границы значений, при пересечении которых выдаётся напоминание. +**[Лицензия файлов проекта](#лицензия-файлов-проекта)** -При первом запуске скачиваются модели, после чего программа не требует подключения к интернету. +**[Благодарности](#благодарности)** -## Непосредственный запуск программы -### Linux/UNIX +## Введение -Поставьте следующие пакеты средствами дистрибутива: git, python, python-pip. -Скачайте проект, установите зависимости, которых не хватает в системе: -```shell -git clone https://github.com/ioctl-user/sevimon.git -cd sevimon -python3 -m pip install -r requirements.txt -``` +Sevimon это набор программ с открытым исходным кодом, написанных на питоне. Позволяет отслеживать напряжение лицевых мышц через видеокамеру, что может быть использовано для устранения перенапряжения, косвенного воздействия на настроение и, при длительном применении, предотвращения появляния мимических морщин. -Для запуска используйте команду `sevimon.py` из папки проекта. -Для отображения статистики используйте команду `sevistat.py` из папки проекта. Должно быть накоплено хотя бы 2 часа статистики для её показа. +Основная программа `sevimon` работает следующим образом: сначала на изображении определяется лицо, затем для выражения лица даётся некая оценка соответствия каждой из восьми эмоций (злость, презрение, отвращение, страх, радость, отсутствие эмоций, грусть, удивление). -При первом запуске скачиваются модели, создаются конфигурационный файл ~/.config/sevimon/sevimon.cfg, который можно редактировать при необходимости. -Журнал эмоций пишется в папку ~/.cache/sevimon/log/ . +Полученные значения сохраняются в журнале в текстовом формате для последующего анализа программой `sevistat`. +Кроме того, для каждой эмоции в файле настроек можно задать верхние и нижние границы значений, при пересечении которых тут же выдаётся напоминание. +Файл настроек, имя которого выводится при старте программы, можно менять в любом текстовом редакторе, или же можно воспользоваться графической утилитой `sevicfg` для настройки. По умолчанию настроена выдача предупреждения при определении злости и удивления, что соответствует нахмуренности бровей и сморщенному лбу. -### Windows +При первом запуске скачиваются модели, после чего подключение к интернету не требуется. -Установите пакет [python вместе со встроенным pip](https://www.python.org/downloads/windows/). -Установите пакет [git](https://git-scm.com/download/win). +## Запуск в докере в Linux +Подготовлен образ Docker с программой, всеми её зависимостями и моделями, который запускается без доступа к сети. -Запустите Powershell, набрав комбинацию клавиш Win+X и выбрав запуск от обычного пользователя. - -Введите следующие команды для скачивания пакета и установки зависимостей: -```shell -git clone https://github.com/ioctl-user/sevimon.git -cd sevimon -python3 -m pip install -r requirements.txt -``` - -Для запуска используйте команду `python.exe -m sevimon.py` из папки проекта. -Для отображения статистики используйте команду `python.exe -m sevistat.py` из папки проекта. Должно быть накоплено хотя бы 2 часа статистики для её показа. -При первом запуске скачиваются модели, создаются редактируемый конфигурационный файл sevimon.cfg и папка для журнала эмоций. - -В случе нехватки модулей DLL, установите [MS Visual C](https://learn.microsoft.com/cpp/windows/latest-supported-vc-redist). - -## Запуск через Docker в Linux Программа sevimon запускается следующим образом: ```shell -xhost +localhost mkdir -p ~/.cache/sevimon/log/ mkdir -p ~/.config/sevimon/ echo > ~/.config/sevimon/sevimon.cfg +xhost +"local:docker@" docker run -it --rm --privileged \ --net=none \ - -w /sevimon/ \ -e DISPLAY=$DISPLAY \ -e LANG=$LANG \ -v /tmp/.X11-unix:/tmp/.X11-unix \ -v $HOME/.Xauthority:/root/.Xauthority \ -v $HOME/.config/sevimon/sevimon.cfg:/root/.config/sevimon/sevimon.cfg \ - -v $HOME/.cache/sevimon/log:/root/.cache/sevimon/log \ + -v $HOME/.cache/sevimon/log:/root/.local/state/sevimon/log \ -v /dev/video0:/dev/video0 \ - ioctl2/sevimon /sevimon/sevimon.py -xhost -localhost + ioctl2/sevimon:latest sevimon +xhost -"local:docker@" +``` +Программа sevistat запускается командой: +```shell +xhost +"local:docker@" +docker run -it --rm --privileged \ + --net=none \ + -e DISPLAY=$DISPLAY \ + -e LANG=$LANG \ + -v /tmp/.X11-unix:/tmp/.X11-unix \ + -v $HOME/.Xauthority:/root/.Xauthority \ + -v $HOME/.config/sevimon/sevimon.cfg:/root/.config/sevimon/sevimon.cfg \ + -v $HOME/.cache/sevimon/log:/root/.local/state/sevimon/log \ + ioctl2/sevimon:latest sevistat +xhost -"local:docker@" ``` -Программа sevistat запускается следующим образом: +Программа sevicfg запускается так: ```shell -xhost +localhost +xhost +"local:docker@" docker run -it --rm --privileged \ --net=none \ - -w /sevimon/ \ -e DISPLAY=$DISPLAY \ -e LANG=$LANG \ -v /tmp/.X11-unix:/tmp/.X11-unix \ -v $HOME/.Xauthority:/root/.Xauthority \ -v $HOME/.config/sevimon/sevimon.cfg:/root/.config/sevimon/sevimon.cfg \ - -v $HOME/.cache/sevimon/log:/root/.cache/sevimon/log \ - ioctl2/sevimon /sevimon/sevistat.py -xhost -localhost + -v $HOME/.cache/sevimon/log:/root/.local/state/sevimon/log \ + ioctl2/sevimon:latest sevicfg +xhost -"local:docker@" ``` +## Запуск бинарных версий в Windows 10 и более новых +Подготовлены [бинарные сборки программы](https://github.com/ioctl-user/sevimon/releases/download/v0.1/sevimon_win10_v0.1.zip) со всеми её зависимостями для Windows (x86\_64). Модели автоматически скачиваются при первом запуске. + +## Установка и запуск универсальных интерпретирумых версий программ +### Подготовительные действия для Linux/UNIX +Поставьте пакеты python и python-pip средствами дистрибутива. + +### Подготовительные действия для Windows +Установите пакет [python вместе со встроенным pip](https://www.python.org/downloads/windows/). + +В случае нехватки DLL при запуске программы, установите [MS Visual C](https://learn.microsoft.com/cpp/windows/latest-supported-vc-redist). + +Запустите Powershell, набрав комбинацию клавиш Win+X и выбрав запуск от обычного пользователя. + +### Установка и запуск + +Установите проект со всеми зависимостями: +```shell +python3 -m pip install sevimon +``` + +В процессе могут выводиться предупреждения с просьбой добавить путь к исполняемым файлам в переменные среды -- это следует сделать. + +Для старта основной программы используйте команду `sevimon`. При первом запуске скачиваются модели, создаётся текстовый конфигурационный файл. +Для настройки можно запустить программу `sevicfg`. +Для отображения статистики используйте команду `sevistat`. Перед этим её должно быть накоплено хотя бы 2 часа. + ## Лицензия файлов проекта -AGPL v3 или более новая +AGPL v3 или более новая. ## Благодарности -Для поиска лиц на изображения используются наработки проекта [Centerface](https://github.com/Star-Clouds/CenterFace/blob/master/prj-python/). +Для поиска лиц на изображении используются наработки проекта [Centerface](https://github.com/Star-Clouds/CenterFace/blob/master/prj-python/). Для определения эмоций используется проект [HSEmotion](https://github.com/HSE-asavchenko/face-emotion-recognition). diff --git a/setup.py b/setup.py index 6f65f3e..7cd1e74 100644 --- a/setup.py +++ b/setup.py @@ -6,7 +6,7 @@ setup( name='sevimon', - version='0.1', + version='0.2', license='LICENSE.txt', packages=[ "sevimon", @@ -16,14 +16,13 @@ package_dir={'sevimon': '', 'sevimon.lib': 'lib', 'sevimon.lib.locale': 'lib/locale'}, entry_points = { 'console_scripts': [ - 'sevicfg=sevicfg.sevicfg:main', + 'sevicfg=sevimon.sevicfg:main', 'sevimon=sevimon.sevimon:main', 'sevistat=sevimon.sevistat:main', ], }, url='https://github.com/ioctl-user/sevimon', description='Self Video Monitoring tool for facial muscles.', - long_description=open('README.md').read(), keywords='sevimon face emotion tension stress muscles wrinkles', install_requires=requirements, )