{"id":28459639,"url":"https://github.com/farrandtom/social-distancing","last_synced_at":"2025-07-25T10:30:54.937Z","repository":{"id":97487427,"uuid":"265226084","full_name":"FarrandTom/social-distancing","owner":"FarrandTom","description":":star: An easy end-to-end social distancing implementation created using OpenCV! :camera:","archived":false,"fork":false,"pushed_at":"2020-05-20T14:15:15.000Z","size":10527,"stargazers_count":15,"open_issues_count":1,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-07-02T12:48:15.465Z","etag":null,"topics":["computer-vision","deep-learning","opencv","opencv-python","python","social-distancing"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FarrandTom.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-05-19T11:17:33.000Z","updated_at":"2025-04-03T14:29:38.000Z","dependencies_parsed_at":null,"dependency_job_id":"b7cb1874-618c-48a8-907a-31a6a5a5e02d","html_url":"https://github.com/FarrandTom/social-distancing","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/FarrandTom/social-distancing","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FarrandTom%2Fsocial-distancing","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FarrandTom%2Fsocial-distancing/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FarrandTom%2Fsocial-distancing/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FarrandTom%2Fsocial-distancing/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FarrandTom","download_url":"https://codeload.github.com/FarrandTom/social-distancing/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FarrandTom%2Fsocial-distancing/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266990860,"owners_count":24017730,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-25T02:00:09.625Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["computer-vision","deep-learning","opencv","opencv-python","python","social-distancing"],"created_at":"2025-06-07T00:44:12.082Z","updated_at":"2025-07-25T10:30:54.814Z","avatar_url":"https://github.com/FarrandTom.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Introduction :v:\nYes, this is another social distancing implementation. \n\n**How is it different?**  \n:point_right: Easy to follow end-to-end workflow.  \n:point_right: Super simple calibration.  \n:point_right: Run locally using a [local detections file](https://github.com/FarrandTom/social-distancing/blob/master/data/labels/oxford_snipped_labels.json), or call an external inference service.  \n:point_right: Already integrated into [IBM Visual Insights](https://www.ibm.com/products/ibm-visual-insights) for inference calls, and easy to rip and replace with another inference engine.\n\nIt is inspired by the fantastic work done by researchers at IIT-Pavis which you can find [here](https://github.com/IIT-PAVIS/Social-Distancing). Special thanks to [Bob Cheesebrough](https://github.com/zmadscientist) for his pointers while building this out!\n\n**Example output:**\n\n![](./readme_images/sample.gif)\n\n# Get Up and Running! :running::dash:\n\n1. Clone this repository  \n`git clone https://github.com/FarrandTom/social-distancing.git`\n2. Install the necessary packages in your virtual environment!  \n`conda install --file requirements.txt` or `pip install -r requirements.txt`\n3. Run `python main.py` to create an output video in `./data/results/output.mp4` based on a sample snippet of Oxford town centre saved at `./data/videos/oxford_snipped.mp4`\n\n# Usage :bulb:\n\n## Adding New Video :film_strip:\nTo add new videos you need to do the following:\n\n## 1. Update the settings :toolbox:\n\nThe main configuration file is [`settings.json`](https://github.com/FarrandTom/social-distancing/blob/master/settings.json). This is where the bulk of user driven settings can be tweaked and changed. This repository comes pre-populated with settings which allow you to run the tool out of the box:\n```\n{\n    \"VIDEO_INPUT_PATH\": \"./data/videos/oxford_snipped.mp4\",\n    \"VIDEO_OUTPUT_PATH\": \"./data/results/output.mp4\",\n    \"CALIBRATION_COORDS_PATH\": \"./calibration_coords.json\",\n    \"LOCAL_RUN\": \"True\",\n    \"VISUAL_INSIGHTS_CREDS_PATH\": \"./placeholder_creds.json\",\n    \"DETECTIONS_FILE\": \"./data/labels/oxford_snipped_labels.json\",\n    \"PHYSICAL_DISTANCE\": 100,\n    \"REFERENCE_HEIGHT\": 22.5,\n    \"DPI\": 300\n}\n```\nThe table below contains a description of each of the settings in more detail. \n\n| Name  | Description | Required? |\n| ------------- | ------------- | ------------- |\n| `VIDEO_INPUT_PATH`  | Path to the input video which will be processed.  | :ballot_box_with_check: |\n| `VIDEO_OUTPUT_PATH`  | Path to where the output video will be saved.  | :ballot_box_with_check: |\n| `CALIBRATION_COORDS_PATH`  | Path to the four calibration coordinates for the input video. If there is no existing calibration file then this path represents where the new file will be saved once the user has completed calibration.  | :ballot_box_with_check: |\n| `LOCAL_RUN`  | Boolean flag (\"True\" or \"False\") indicating whether to use a local detections file (True), or upload the video file to a 3rd party inference service (False). Out of the box remote inference is supported by IBM Visual Insights. | :ballot_box_with_check: |\n| `VISUAL_INSIGHTS_CREDS_PATH`  | If `LOCAL_RUN` is False, then this will be a path to a credentials file which supplies authentication to a 3rd party inference service.  | Only if `LOCAL_RUN` is False |\n| `DETECTIONS_FILE`  | If `LOCAL_RUN` is True, then this will be a path to a .json file which supplies detected object coordinates and frame numbers. For an example [click here](https://github.com/FarrandTom/social-distancing/blob/master/data/labels/oxford_snipped_labels.json).  | Only if `LOCAL_RUN` is True|\n| `PHYSICAL_DISTANCE` | The distance in cm required to maintain social distancing  | :ballot_box_with_check: |\n| `REFERENCE_HEIGHT`  | The estimated real world height of detected objects in cm. In this case we are using head detections, and therefore estimate that the average head height is 22.5 cm. | :ballot_box_with_check: |\n| `DPI`  | The quality of the output video in Dots Per Inch (DPI)   | :ballot_box_with_check: |\n\nTo allow the tool to infer on new videos you will have to change:\n - The `VIDEO_INPUT_PATH` to point to where the new video is saved. \n - To make sure that new results do not overwrite old ones it may be wise to update the `VIDEO_OUTPUT_PATH`\n - Set a fresh `CALIBRATION_COORDS_PATH` (even if you have not yet set the calibration coordinates) which is different from any previous calibration files. This new path will be where the calibration coordinates are then saved and re-used in the future. Move on all this in step 2 below.\n - If you are running in local mode (`LOCAL_RUN: \"True\"`) then you will have to supply a new `DETECTIONS_FILE` for the new video. You can see an example of these detections [here](https://github.com/FarrandTom/social-distancing/blob/master/data/labels/oxford_snipped_labels.json).\n - If you are using a remote inference service (`LOCAL_RUN: \"False\"`) then nothing should have to change, unless you wish to update the back end detection model.\n - `PHYSICAL_DISTANCE`, `REFERENCE_HEIGHT`, and `DPI` are only going to be impacted by the change in input video if there is a change in the objects being detected (e.g. full body instead of only the head), or the business problem being solved (e.g. the physcial distance needs to be 200cm instead of 100cm). \n\n## 2. Calibrate :world_map:\n\nThe next thing required is to populate a calibration coordinates .json file. An example found [here](https://github.com/FarrandTom/social-distancing/blob/master/calibration_coords.json) is:  \n`[[1129, 221], [1534, 267], [880, 953], [273, 755]]`\n\nThe calibration coordinates are simply the four corner points of a rectangle. This rectangle is used to generate the bird's-eye view perspective you can see in the GIF above. \n\nWhen using a new video you will need to generate new calibration coordinates- these will be written to, and subsequently read from, `CALIBRATION_COORDS_PATH`. \n\nTo kick off calibration simply run `python main.py`, in your virtual environment, using a `CALIBRATION_COORDS_PATH` which currently does not exist.  Your terminal will then display:\n\n```\n-------------------------------------------\nNo existing calibration file found. \nYou will now be prompted to calibrate the system. \nThe system expects four points in the shape of a rectangle which it uses as reference coordinates to calculate the bird's-eye perspective. \nThe rectangle should lie in line with the geometry of the video e.g. if there is a road running through the centre of your video, the rectangle should mirror the road's orientation. \n--------------------------------------------------------- \nThere are two main assumptions to bear in mind with this implementation: \n1) The ground is a flat plane. \n2) The camera viewpoint is in a fixed position. \n--------------------------------------------------------- \nThe first frame of the input video will now be displayed. \nSimply click where you wish the four corners of the calibration rectangle to be- a green dot will be placed wherever you click. \nYour calibration coordinates will be saved at ./test.json \n---------------------------------------------------------\n```\n\nAs you then click on the first frame of your video, each of the coordinates that you select will also be printed to the terminal:\n```\n280 749\n902 916\n1518 287\n1121 226\n```\n\nAs soon as you have selected four points, the script will move on to the inference and drawing steps! :art:\n\n*Note: If you make a mistake simply quit the script (cmd/ctrl + C), delete any .json file that has been created, and start again.*\n\n## 3. Infer :hourglass_flowing_sand:\n\nIf you are using detections from a local file then you will simply need to point the `DETECTIONS_FILE` variable towards that local file. Depending on the format of that local file you may need to tweak the `sort_detections` function found [here](https://github.com/FarrandTom/social-distancing/blob/master/inference/detect.py#L159). \n\nIf you have access to an [IBM Visual Insights](https://www.ibm.com/products/ibm-visual-insights) instance then the [`placeholder_creds.json`](https://github.com/FarrandTom/social-distancing/blob/master/placeholder_creds.json) file can be easily tweaked to support your credentials: \n```\n{\n    \"credentials\": {\n        \"hostname\" : \"\u003cYour hostname here\u003e\",\n        \"Auth\"    : [ \"\u003cYour username here\u003e\", \"\u003cYour password here\u003e\" ],\n        \"logLevel\": 40\n},\n    \"model_id\": \"\u003cYour model ID here\u003e\"\n}\n```\n\nYour `model_id` can be found via the [Visual Insights API](http://public.dhe.ibm.com/systems/power/docs/powerai/api120.html) or when selecting a deployed model in the GUI it will be displayed in the deployed model API endpoint e.g. `https://9.196.150.153/visual-insights/api/dlapis/a17d62c5-3087-4b34-9899-6f58da4da99d` --\u003e `\"model_id\": a17d62c5-3087-4b34-9899-6f58da4da99d`.\n\nIf you wish to perform inference against a different service then the API calls within [`detect.py`](https://github.com/FarrandTom/social-distancing/blob/master/inference/detect.py) will have to be adapted to support the new API. I'll leave that up to you :)\n\nThat's it, you're ready to go. :boom:\n\n# References :book:\n1. https://github.com/IIT-PAVIS/Social-Distancing\n2. https://www.pyimagesearch.com/2014/08/25/4-point-opencv-getperspective-transform-example/\n3. http://www.robots.ox.ac.uk/ActiveVision/Research/Projects/2009bbenfold_headpose/project.html\n4. https://www.pyimagesearch.com/2016/03/21/ordering-coordinates-clockwise-with-python-and-opencv/\n\n![](./readme_images/social_distancing.jpg)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffarrandtom%2Fsocial-distancing","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffarrandtom%2Fsocial-distancing","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffarrandtom%2Fsocial-distancing/lists"}