# Face Tracking Demo
Demonstrates the following technologies:
- Face Detection in a video stream. Yolo models from DeGirum zoo are used.
- Creating face embeddings by [DeepFace](https://github.com/serengil/deepface)
- Saving face metadata, including embeddings, in a vector database ([LanceDB](https://lancedb.com/))
- Recognition of detected faces, using saved faces metadata.
Used as a mock-up for development of hybrid deployment of a vector db.
## 1.Installation
Create a new conda environment:
```
conda env create -f environment.yml
```
Activate it:
```
conda activate dg_face_tracking
```
Create a database folder:
```
mkdir db
```
Open env.ini file and fill the DEGIRUM_CLOUD_TOKEN field with a valid DeGirum cloud platform API access token.
## 2. Running
A laptop with an enabled camera must be used.
Start the face tracking app:
```
python track.py -d <deployment> -c <config>
```
Options:
- deployment: cloud, local or docker
- config: config path, relative to Configs subfolder
Press OK button to finalize keying.
Ctrl+C stops the app.
## 3. Creating a dataset.
1. Edit the `face_tracker_camera.cfg` config file by adding
```commandline
[${data_source.id}, ${dataset_writer}]
```
line in `data_connections` section.
2. In `dataset` section of `LocalDBWriter.cfg` config file:
- Set the valid paths for catalogue (`catalogue_path`) and the datasets path (`datasets_path`);
- Set dataset name `dataset_name`
- If you want to overwrite the existing dataset, set `write_mode` as "overwrite"
Run the application.
To stop data collection, press Ctrl+C
## 4. Running on a dataset
```
python DataFace.py face_tracker_dataset
```
`dataset` section of `FaceTrackerDataset.cfg` must contain the valid parameters of the dataset to be used:
- Set the valid paths for catalogue (`catalogue_path`) and the datasets path (`datasets_path`);
- Set the dataset name (`dataset_name`)
Run the application.
To stop running, press Ctrl+C
## 5. Face to ID functionality
To label a cropped face image: import `face2id` function
```
from dg_face_tracking.Face2ID.face2id import face2id
```
Interface:
```
def face2id(img: Union[str, np.ndarray],
deployment: str = "docker",
async_support: bool = False,
verbose: bool = False) -> str:
```
Parameters:
```
img : str or ndarray: face image as base64 encoded png or numpy array
deployment: ["cloud", "local", "docker"]
async_support: bool: do we need to enable async support
verbose: bool: for testing purpose only
```
Return value: json string
```
{"label": "<some label or empty string>", "error": "<error message or empty string>"}
```
Label can be a name of a person, `unknown` or empty (in case of internal error)
Error is empty string on success or contains some error message
## 6. CI/CD
To make new release perform the following steps:
1. Assign new git tag by running the following command:
```
./rel-tag.sh x.y.z
```
where `x.y.z` is semantic version of new release.
2. Open [Github Release action page](https://github.com/DeGirum/dg_face_tracking/actions/workflows/release.yml) and configure release action
by clicking **Run workflow** combo box, selecting **Tags** tab in **Branch** combo box, and specifying the tag, which corresponds to the released version:
3. Start release action by pressing green **Run workflow** button.
4. Make sure Release action finishes successfully (green checkmark new recent Release action run status)
5. Open [Github Upload action page](https://github.com/DeGirum/dg_face_tracking/actions/workflows/upload.yml) and configure upload action
by clicking **Run workflow** combo box and specifying the release version tag in **Release tag containing wheels to upload** edit box:
6. Start upload action by pressing green **Run workflow** button.
7. Make sure Upload action finishes successfully (green checkmark new recent Upload action run status)
8. Verify, that release is avaiable for installation by running the following command:
```
pip uninstall -y dg_face_tracking && pip install -U dg_face_tracking
```
You should see the following prompt:
```
Successfully installed dg_face_tracking-x.y.z
```
## 6. Orin Local Demo Installation
#### 6.1 Prerequisites
- Install the NVIDIA Container Toolkit and Configure Docker
https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html
- Start AIServer in Docker with nvidia runtime:
```commandline
docker run -d -p 8778:8778 -v /my/model/zoo/dir:/zoo --runtime nvidia --privileged degirum/aiservertrt:latest
```
- Download models from DeGirum cloud zoo
https://docs.degirum.com/documentation/PySDK-0.11.0/user-guide/cli/
#### 6.2. Create conda environment and install dg_face_tracking package
```commandline
conda create --name face_tracking python=3.9
conda activate face_tracking
pip install dg_face_tracking
```
#### 6.3 Run the Demo
```commandline
dr_face_tracking
```
To stop the demo: hit "x".
Raw data
{
"_id": null,
"home_page": "https://github.com/degirum",
"name": "dg-face-tracking",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "DeGirum Corp.",
"author_email": "support@degirum.com",
"download_url": null,
"platform": null,
"description": "# Face Tracking Demo\n\nDemonstrates the following technologies:\n- Face Detection in a video stream. Yolo models from DeGirum zoo are used.\n- Creating face embeddings by [DeepFace](https://github.com/serengil/deepface)\n- Saving face metadata, including embeddings, in a vector database ([LanceDB](https://lancedb.com/)) \n- Recognition of detected faces, using saved faces metadata.\n\nUsed as a mock-up for development of hybrid deployment of a vector db.\n\n## 1.Installation\n\n\nCreate a new conda environment:\n```\nconda env create -f environment.yml\n```\n\nActivate it:\n```\nconda activate dg_face_tracking\n```\n\nCreate a database folder:\n```\nmkdir db\n```\n\nOpen env.ini file and fill the DEGIRUM_CLOUD_TOKEN field with a valid DeGirum cloud platform API access token. \n\n## 2. Running\n\nA laptop with an enabled camera must be used. \n\n\nStart the face tracking app:\n```\npython track.py -d <deployment> -c <config>\n``` \nOptions:\n\n- deployment: cloud, local or docker\n- config: config path, relative to Configs subfolder \n\n\nPress OK button to finalize keying. \n\nCtrl+C stops the app.\n\n## 3. Creating a dataset.\n1. Edit the `face_tracker_camera.cfg` config file by adding\n```commandline\n [${data_source.id}, ${dataset_writer}]\n```\nline in `data_connections` section.\n\n\n2. In `dataset` section of `LocalDBWriter.cfg` config file:\n- Set the valid paths for catalogue (`catalogue_path`) and the datasets path (`datasets_path`);\n- Set dataset name `dataset_name`\n- If you want to overwrite the existing dataset, set `write_mode` as \"overwrite\"\n\nRun the application.\n\nTo stop data collection, press Ctrl+C\n\n## 4. Running on a dataset\n```\npython DataFace.py face_tracker_dataset\n``` \n`dataset` section of `FaceTrackerDataset.cfg` must contain the valid parameters of the dataset to be used:\n\n- Set the valid paths for catalogue (`catalogue_path`) and the datasets path (`datasets_path`);\n- Set the dataset name (`dataset_name`)\n\nRun the application.\n\nTo stop running, press Ctrl+C\n\n## 5. Face to ID functionality\n\nTo label a cropped face image: import `face2id` function\n ```\n from dg_face_tracking.Face2ID.face2id import face2id\n ```\nInterface:\n ```\n def face2id(img: Union[str, np.ndarray],\n deployment: str = \"docker\",\n async_support: bool = False,\n verbose: bool = False) -> str:\n ```\nParameters:\n ```\n img : str or ndarray: face image as base64 encoded png or numpy array\n deployment: [\"cloud\", \"local\", \"docker\"]\n async_support: bool: do we need to enable async support\n verbose: bool: for testing purpose only\n ```\nReturn value: json string\n ```\n {\"label\": \"<some label or empty string>\", \"error\": \"<error message or empty string>\"}\n ```\nLabel can be a name of a person, `unknown` or empty (in case of internal error)\nError is empty string on success or contains some error message\n\n## 6. CI/CD\n\nTo make new release perform the following steps:\n\n1. Assign new git tag by running the following command:\n\n ```\n ./rel-tag.sh x.y.z\n ```\n\n where `x.y.z` is semantic version of new release.\n\n2. Open [Github Release action page](https://github.com/DeGirum/dg_face_tracking/actions/workflows/release.yml) and configure release action\nby clicking **Run workflow** combo box, selecting **Tags** tab in **Branch** combo box, and specifying the tag, which corresponds to the released version:\n\n \n\n3. Start release action by pressing green **Run workflow** button.\n4. Make sure Release action finishes successfully (green checkmark new recent Release action run status)\n5. Open [Github Upload action page](https://github.com/DeGirum/dg_face_tracking/actions/workflows/upload.yml) and configure upload action\nby clicking **Run workflow** combo box and specifying the release version tag in **Release tag containing wheels to upload** edit box:\n\n \n\n6. Start upload action by pressing green **Run workflow** button.\n7. Make sure Upload action finishes successfully (green checkmark new recent Upload action run status)\n8. Verify, that release is avaiable for installation by running the following command:\n ```\n pip uninstall -y dg_face_tracking && pip install -U dg_face_tracking\n ```\n\n You should see the following prompt:\n\n ```\n Successfully installed dg_face_tracking-x.y.z\n ```\n \n## 6. Orin Local Demo Installation\n\n#### 6.1 Prerequisites\n- Install the NVIDIA Container Toolkit and Configure Docker\n\nhttps://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html\n\n- Start AIServer in Docker with nvidia runtime:\n ```commandline\n docker run -d -p 8778:8778 -v /my/model/zoo/dir:/zoo --runtime nvidia --privileged degirum/aiservertrt:latest\n ```\n- Download models from DeGirum cloud zoo \nhttps://docs.degirum.com/documentation/PySDK-0.11.0/user-guide/cli/\n\n\n#### 6.2. Create conda environment and install dg_face_tracking package\n\n ```commandline\n conda create --name face_tracking python=3.9\n conda activate face_tracking\n pip install dg_face_tracking\n ```\n\n#### 6.3 Run the Demo\n ```commandline\n dr_face_tracking \n ```\nTo stop the demo: hit \"x\".\n\n\n\n \n\n\n\n\n\n\n\n\n\n\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "DeGirum Face Tracking Application Package",
"version": "0.1.15",
"project_urls": {
"Homepage": "https://github.com/degirum"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6aca6bcd9a29ee6758146a03290188e050ccf27a9deb49fc210bee9b8ef5c0b4",
"md5": "484048d6a33d5a2d8ff31601671248ab",
"sha256": "1656079d9b1dfbcf0b6f707d48a57691585445c34e9dc0901fdb107ec5c725a5"
},
"downloads": -1,
"filename": "dg_face_tracking-0.1.15-py3-none-any.whl",
"has_sig": false,
"md5_digest": "484048d6a33d5a2d8ff31601671248ab",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 131834,
"upload_time": "2024-05-10T02:01:42",
"upload_time_iso_8601": "2024-05-10T02:01:42.498515Z",
"url": "https://files.pythonhosted.org/packages/6a/ca/6bcd9a29ee6758146a03290188e050ccf27a9deb49fc210bee9b8ef5c0b4/dg_face_tracking-0.1.15-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-10 02:01:42",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "dg-face-tracking"
}
JSON