Skip to main content

Create a social network graph based on coappearance in images

Project description

face-network

Documentation Status PyPI version

Create a social network graph based on coappearance in images. Given a large volume of images of people this tool:

  1. Extracts faces
  2. Clusters faces based on similarity
  3. Creates a social network graph based on co-appearance in images

The three steps above correspond to the black arrows on the left of the diagram below:

project structure

1. Extracting faces

face_network.extract_faces(source_dir, age_gender=False)

This function extracts all faces from a directory of images using Dlib’s face detector, and must be run prior to further analysis.

Outputs:

This function creates a new folder called “Face Network” in your image directory. When a face is identified, it is cropped and stored in a new folder “source_dir/Face Network/Faces/”. Given “Image.jpg” containing two faces, this function will save two cropped faces: “face1_Image.jpg” and “face2_Image.jpg”. Facial encodings (128-dimensional vectors used for clustering and matching similar faces) are stored in a file called “FaceDatabase.h5”.

2. Clustering Faces

face_network.cluster(source_dir, algorithm='DBSCAN', iterations=1, initial_eps=0.45, max_distance=45)

Once faces are extracted, similar faces are clustered together. This function uses a density-based clustering algorithm (DBSCAN) to identify clusters of similar faces in the list of facial encodings. Starting with loose clustering parameters, the function iteratively decreases the neighborhood distance parameter. In each iteration, facial similarity within clusters is evaluated. Dense clusters are extracted, and sparse clusters are assigned to be re-evaluated in the next iteration. When an iteration returns no new clusters, the function returns a dataframe containing facial encodings grouped into clusters based on similarity.

Outputs:

Rows in the FaceDatabase.h5 file now contain a unique numeric identifier, grouping similar faces into clusters. If the “mosaic” option is enabled, an image composed of all of the face tiles in a given cluster is created:

project structure

3. Generating a Network

face_network.network(photo_dir, scale=10)

Having identified individuals across multiple pictures, this function generates a force directed graph based on co-appearance in images. Each individual is a node, and each co-appearance is an edge.

Output:

A file called “Image_Network.html” is created in "photo_directory/Face Network/Data/".

project structure

The graph can be opened in a web browser and is fully interactive. Hovering over a node will display a tooltip showing the cluster’s unique identifier. This corresponds to the filenames of the mosaics generated in the previous step:

project structure

Example Project

Given a folder called “photo_dir” with five images, the following process extracts faces, clusters similar faces, and creates a co-appearance network:

import face_network
photo_dir="Users/oballinger/Downloads/photo_dir"

face_network.extract(photo_dir, age_gender=True)

face_network.cluster(photo_dir, algorithm='DBSCAN', iterations=10, initial_eps=0.44, max_distance=40)

face_network.network(photo_dir, size=20)

The diagram below shows the file structure of the resulting outputs:

outputs

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

face-network-1.0.2.tar.gz (10.0 kB view hashes)

Uploaded Source

Built Distribution

face_network-1.0.2-py2-none-any.whl (11.0 kB view hashes)

Uploaded Python 2

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page