diff --git a/README.md b/README.md index 2e40200725..2328521d37 100644 --- a/README.md +++ b/README.md @@ -92,9 +92,9 @@ alt="compreface-dashboard-page" width="390px" style="padding: 0px 0px 0px 10px;"

-compreface-verification-page -compreface-detection-page

@@ -185,14 +185,14 @@ The system can accurately identify people even when it has only “seen” their 2. Download the archive from our latest release: https://github.com/exadel-inc/CompreFace/releases 3. Unzip the archive 4. Run Docker -5. Open Command prompt (write `cmd` in windows search bar) -6. Open folder where you extracted zip archive (Write `cd path_of_the_folder`, press enter). +5. Open Command prompt (Type `cmd` in windows search bar) +6. Open folder where you extracted zip archive (Type `cd path_of_the_folder`, press enter). 7. Run command: `docker-compose up -d` 8. Open http://localhost:8000/login ### Getting started for contributors -Follow this [link](/dev) +Follow this [link](/dev). # CompreFace SDKs @@ -204,7 +204,7 @@ Follow this [link](/dev) # Documentation -More documentation is available [here](/docs) +More documentation is available [here](/docs). # Contributing @@ -220,6 +220,6 @@ We want to improve our open-source face recognition solution, so your contributi For more information, visit our [contributing](CONTRIBUTING.md) guide, or create a [discussion](https://github.com/exadel-inc/CompreFace/discussions). -# License info +# License info CompreFace is open-source real-time facial recognition software released under the [Apache 2.0 license](https://www.apache.org/licenses/LICENSE-2.0.html). diff --git a/dev/README.md b/dev/README.md index db45f63695..994ddb1a9c 100644 --- a/dev/README.md +++ b/dev/README.md @@ -9,7 +9,7 @@ #### Tips for Windows (use Git Bash terminal) -1. Turn of the git autocrlf with command: `git config --global core.autocrlf false` +1. Turn off the git autocrlf with command: `git config --global core.autocrlf false` 2. Make sure all your containers are down: `docker ps` 3. In case some containers are working, they should be stopped: `docker-compose down` 4. Clean all local datebases and images: `docker system prune --volumes` diff --git a/docs/Face-data-migration.md b/docs/Face-data-migration.md index a887f68160..44223451b2 100644 --- a/docs/Face-data-migration.md +++ b/docs/Face-data-migration.md @@ -35,9 +35,10 @@ enough, so please do a backup copy of the database and perform migration at your own risk. REST request to start migration: - +```shell curl -i -X POST \ 'http://localhost:8000/api/v1/migrate' +``` This rest endpoint is asynchronous; it starts the migration and returns a response immediately. Please look at logs for "Migration successfully diff --git a/docs/Face-services-and-plugins.md b/docs/Face-services-and-plugins.md index 0169b87773..82afe9da10 100644 --- a/docs/Face-services-and-plugins.md +++ b/docs/Face-services-and-plugins.md @@ -13,7 +13,7 @@ CompreFace supports these face services and plugins: # Services -To use face service you need to create it in an application on UI. +To use face service you need to create it in an application on the UI. The type of service depends on your application needs. Each service has its own REST API context and there is no possibility to change the service type after creation. Here is a short description of each of them: @@ -23,7 +23,7 @@ Here is a short description of each of them: Face detection service is used to detect all faces in the image. It doesn’t recognize faces, just finds them on the image. -**Cases of use** +**Use cases** The most useful cases include face plugins for face analysis: * gather statistics on how your store popular among different genders @@ -57,7 +57,7 @@ Face recognition service is used for face identification. This means that you fi then recognize unknown faces among them. When you upload an unknown face, the service returns the most similar faces to it. Also, face recognition service supports verify endpoint to check if this person from face collection is the correct one. -**Cases of use** +**Use cases** The possible cases include: * when you have photos of employees and want to recognize strangers in the office @@ -88,7 +88,7 @@ Example: Face verification service is used to check if this person is the correct one. The service compares two faces you send to the rest endpoint and returns their similarity. -**Cases of use** +**Use cases** The possible cases include: * when a customer provides you an ID or driving license and you need to verify if this is him diff --git a/docs/Gathering-anonymous-statistics.md b/docs/Gathering-anonymous-statistics.md index 46b1e0ecd3..b0c585c333 100644 --- a/docs/Gathering-anonymous-statistics.md +++ b/docs/Gathering-anonymous-statistics.md @@ -20,16 +20,16 @@ Privacy Policy and agree to send anonymous statistics to our servers. name, email password, etc.). - Event of application creation - we record only the fact of the creation of a new application. We do not gather any information - about the application(like name, which users have access to it, + about the application (like name, which users have access to it, etc.). - Event of service creation - we record only the creation of a new service and its type. We do not gather any information about the - service(like name, etc.). + service (like name, etc.). - The number of saved faces in Face Recognition service Collection. Every day we record how many faces are saved in Collection in ranges: 1-10, 11-50, 51-200, 201-500, 501-2000, 2001-10000, 10001-50000, 50001-200000, 200001-1000000, 1000001+. We do not - gather any information about the faces(like face name, embedding, + gather any information about the faces (like face name, embedding, etc.). #### What we do NOT collect: @@ -62,6 +62,7 @@ that this is the same installation as before. "2021-03-13 13:25:50.003","59638de4-5fca-11eb-848b-0242ac120002","39c1925d-a1a9-4d44-8eb3-6acf132b89f2","1-10" "2021-03-13 13:25:50.763","59638de4-5fca-11eb-848b-0242ac120002","794dd0ec-ac88-4552-90a8-f0bb0ddcee1e","201-500" ``` + #### How we use the data The data is used to understand the popularity of different services, how @@ -73,5 +74,4 @@ self-promotional goals, like "CompreFace has N active users" or than 1 million faces". If you have any questions about the privacy policy, what data we -collect, or how we use it, please [get in touch with -us](mailto:compreface.support@exadel.com) +collect, or how we use it, please [get in touch with us](mailto:compreface.support@exadel.com). diff --git a/docs/How-to-Use-CompreFace.md b/docs/How-to-Use-CompreFace.md index aa72d4e8a4..dff983dbd6 100644 --- a/docs/How-to-Use-CompreFace.md +++ b/docs/How-to-Use-CompreFace.md @@ -45,8 +45,7 @@ Each object has the following fields: 4. `x_min`, `x_max`, `y_min`, `y_max` are coordinates of the face in the image -``` - +```json { "result": [ { @@ -78,14 +77,14 @@ Each object has the following fields: This demo shows the most simple example of Face recognition service usage. To run a demo, open an HTML file in a browser. API key for this demo was created on **step 5** of [How to Use -CompreFace](#how-to-use-compreface) +CompreFace](#how-to-use-compreface). 2. [webcam_demo.html](./demos/webcam_demo.html) This demo shows the most simple webcam demo for Face recognition service. To run a demo, open an HTML file in a browser. API key for this demo was created on **step 5** of [How to Use -CompreFace](#how-to-use-compreface) +CompreFace](#how-to-use-compreface). ## Code Snippets diff --git a/docs/Installation-options.md b/docs/Installation-options.md index 5230c5d734..79adbce2ec 100644 --- a/docs/Installation-options.md +++ b/docs/Installation-options.md @@ -1,7 +1,7 @@ # Installation (Deployment) options -Exadel CompreFace consists of several services and a database. -Full architecture description and scaling tips you can find [here](Architecture-and-scalability.md). +Exadel CompreFace consists of several services and a database. +You can find the full architecture description and scaling tips [here](Architecture-and-scalability.md). Each service is put to docker image for simpler usage, and they can be run separately. However, for a better user experience, CompreFace provides three distribution options that help install CompreFace easier. By default, CompreFace is delivered as a docker-compose configuration. But there are more options to install and run CompreFace. @@ -16,11 +16,11 @@ Each of them has its benefits and disadvantages. ## Docker Compose Docker-compose configuration allows simply run, configure, stop and restart CompreFace. -To install CompreFace using docker-compose just follow instructions in [getting started](../README.md#getting-started-with-compreface) +To install CompreFace using docker-compose just follow instructions in [getting started](../README.md#getting-started-with-compreface). ### Maintaining tips -1. After you run CompreFace, wait at least 30 seconds until it starts. +1. After you run CompreFace, allow at least 30 seconds for it to start. Do not stop it during this time, as it may corrupt database data during data migration. 2. You can run `docker-compose ps` to see all CompreFace services. There should be 5 CompreFace services: compreface-core, compreface-api, compreface-admin, compreface-ui, compreface-postgres-db. @@ -29,16 +29,16 @@ To install CompreFace using docker-compose just follow instructions in [getting You also can run `docker-compose logs -f` to see the logs of all CompreFace services. 4. Docker-compose automatically restarts all services if they fail. It also automatically starts them after you restart your machine. 5. If you want to stop CompreFace, run `docker-compose stop`. - You can also stop each container one by one, e.g. `docker-compose stop compreface-core`. + You can also stop each container one by one, by running `docker-compose stop `, e.g. `docker-compose stop compreface-core`. 6. To start stopped Compreface, run `docker-compose start`. - You can also start each container one by one, e.g. `docker-compose start compreface-core`. + You can also start each container one by one, by running `docker-compose start `, e.g. `docker-compose start compreface-core`. 7. If you want to restart CompreFace, run `docker-compose restart`. - You can also restart each container one by one, e.g. `docker-compose restart compreface-core`. + You can also restart each container one by one, by running `docker-compose restart `, e.g. `docker-compose restart compreface-core`. 8. All the data is stored locally on your machine. It is stored in a named docker volume. This guarantees that if you stop or delete CompreFace docker containers, you won’t lose the data. To find the volume name, run `docker volume ls`, the name should be `_postgres-data`, e.g. `compreface_061_postgres-data`. 9. If you want to clear CompreFace installation, first stop it with `docker-compose stop`. - Then delete the volume, e.g. `docker volume rm compreface_061_postgres-data`. Then run CompreFace again `docker-compose up -d`. + Then delete the volume (see tip 8 for getting volume name), e.g. `docker volume rm compreface_061_postgres-data`. Then run CompreFace again `docker-compose up -d`. 10. To update the CompreFace version or change custom build, download new `docker-compose.yml` and `.env` files. Stop CompreFace with `docker-compose down`. Copy new files into the old CompreFace folder. Then run CompreFace with `docker-compose up -d`. @@ -50,7 +50,7 @@ To install CompreFace using docker-compose just follow instructions in [getting 2. Problem: `compreface-admin` doesn’t start and there are logs like `Waiting for changelog lock....` - Solution: clear CompreFace installation (see #Maintaining-tips) + Solution: clear CompreFace installation (see [Maintaining-tips](#maintaining-tips)) ## Kubernetes @@ -58,7 +58,7 @@ You can find all Kubernetes scripts in CompreFace [Kubernetes repository](https: ## Single docker container -Except for other distribution options, here all services and the database are placed in one docker image. +Unlike other distribution options, all services and the database here are placed in one docker image. The obvious advantage of this approach is that it is the simplest way to start CompreFace. However, it has some limitations in maintaining and troubleshooting. E.g. it’s very difficult to stop or restart services one by one. @@ -100,7 +100,7 @@ docker run -d --name=CompreFace -v compreface-db:/var/lib/postgresql/data --runt ### Maintaining tips 1. Start CompreFace in a single docker container takes at least 45 seconds. - So long start is because of manual timings that help to start services in the right order. + The long start is because of manual timings that help to start services in the right order. 2. There is a possibility that the database starts too slow, then service `compreface-admin` will fail. Supervisord will restart it automatically and CompreFace should start properly. 3. To check if the run is finished, you can check the logs `docker logs CompreFace -f`. @@ -110,14 +110,14 @@ docker run -d --name=CompreFace -v compreface-db:/var/lib/postgresql/data --runt 5. `compreface-db` in the run command is the name of the volume, all your data is stored locally in this volume. This guarantees that if you stop or delete CompreFace docker containers, you won’t lose the data. 6. You can use environment variables from `docker-compose` version, e.g. to set API server limit you can run: -```commandline -docker run -d -e "API_JAVA_OPTS=-Xmx8g" --name=CompreFace -v compreface-db:/var/lib/postgresql/data -p 8000:80 exadel/compreface` -``` + ```shell + docker run -d -e "API_JAVA_OPTS=-Xmx8g" --name=CompreFace -v compreface-db:/var/lib/postgresql/data -p 8000:80 exadel/compreface` + ``` 7. By default, docker won’t restart CompreFace if it fails or after your restart your machine. You can add this by adding `--restart=always` in run command: -```commandline -docker run -d --name=CompreFace -v compreface-db:/var/lib/postgresql/data -p 8000:80 --restart=always exadel/compreface -``` + ```shell + docker run -d --name=CompreFace -v compreface-db:/var/lib/postgresql/data -p 8000:80 --restart=always exadel/compreface + ``` 8. If you want to stop CompreFace, run `docker stop CompreFace`. 9. To start stopped Compreface, run `docker start CompreFace`. 10. If you want to restart CompreFace, run `docker restart CompreFace`. diff --git a/docs/Mask-detection-plugin.md b/docs/Mask-detection-plugin.md index 7c3f3476ab..87e59e375c 100644 --- a/docs/Mask-detection-plugin.md +++ b/docs/Mask-detection-plugin.md @@ -7,11 +7,12 @@ correctly automatically. There are three possible results: There was no suitable free and ready-to-use model for face mask detection at the moment of adding this plugin, so we created our model. - Disclaimer: - Software developers, not medical experts, created the plugin. - The plugin doesn't contain the recommendations of how to use and wear face mask correctly. - The accuracy of the model is not 100%. - Please use the plugin at your own risk. +> [!NOTE] +> Disclaimer: +> Software developers, not medical experts, created the plugin. +> The plugin doesn't contain the recommendations of how to use and wear face mask correctly. +> The accuracy of the model is not 100%. +> Please use the plugin at your own risk. # Face mask detection example @@ -42,5 +43,4 @@ augmentation (see augmentation.py) to achieve class balance. InceptionV3 was cut off on a mixed 7 layer to improve speed and was used as a backbone. The final model with 97.2 % accuracy is used by default -and can be found -[here](https://drive.google.com/file/d/1jm2Wd2JEZxhS8O1JjV-kfBOyOYUMxKHq/view?usp=sharing) +and can be found [here](https://drive.google.com/file/d/1jm2Wd2JEZxhS8O1JjV-kfBOyOYUMxKHq/view?usp=sharing). diff --git a/docs/User-Roles-System.md b/docs/User-Roles-System.md index c21fe50732..0ba16139f4 100644 --- a/docs/User-Roles-System.md +++ b/docs/User-Roles-System.md @@ -16,6 +16,8 @@ administrator) roles to technical support employees. Then there is no reason to add such users to applications as they still have all permissions within the application. +### Global owner role + In CompreFace, the first user automatically receives the global owner role and has rights for any operation within CompreFace - managing users and creating and managing applications. The only restriction for the @@ -23,12 +25,16 @@ global owner is that such a user can't delete themselves from the system, so the user has to assign the global owner role to somebody else and then remove themselves from the system. +### Global administrator role + Users with the global administrator role have the same permissions as users with the global owner role. The only difference is that such users can\'t manage the user with the global owner role. We recommend reducing users with such a role to the minimum number required to maintain the system. +### Global user role + All new users are automatically assigned the global user role. These users can't create applications, can access only the applications they were added to, and can't manage other users. These users use CompreFace @@ -47,6 +53,8 @@ become a member of an application team, users with a global user role need to be added to the application directly by the global owner, global administrator, or application owner. +### Application owner role + The user that creates an application automatically receives the application owner role and has rights for any operation within the application - managing the application and its users and creating and @@ -55,11 +63,15 @@ restriction for the application owner is that they can't delete themselves from the application, so they have to assign the application owner role to somebody else before deleting themselves. +### Application administrator role + Users with the application administrator role (global user role + application administrator role) can create and manage [Face Services](Face-services-and-plugins.md) but can't manage an application and its users. +### Application user role + Users with the application user role can't manage anything in the application. This is the least permissive role (global user role + application user role), but this provides enough information to diff --git a/load-tests/README.md b/load-tests/README.md index 714d077001..5fb1818aae 100644 --- a/load-tests/README.md +++ b/load-tests/README.md @@ -26,9 +26,9 @@ docker run \ ``` Any test from `tests` folder follows those steps: -1. Apply db_init.sql to database +1. Apply *db_init.sql* to database 2. Run recognition test according to `scenarios` defined in the script -3. Apply db_truncate.sql to database +3. Apply *db_truncate.sql* to database ### Run command details