Upload folder using huggingface_hub

README.md

@@ -1,12 +1,83 @@
 ---
-title: Stack Overflow Users
-emoji: 🐠
-colorFrom: red
-colorTo: indigo
+title: stack_overflow_users
+app_file: stack_overflow_users.py
 sdk: gradio
-sdk_version: 4.28.3
-app_file: app.py
-pinned: false
+sdk_version: 4.28.2
 ---
+# Stack Overflow User Profiles and Face Detection
+The live application demo can be found [here](https://9ad3e3e6958cd392e8.gradio.live).
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+## About The Project
+This is a simple Gradio application that fetches the top 10 user profiles based on reputation from Stack Overflow API, downloads their profile images, attempts to detect faces within those images using `dlib`, and presents them in an intuitive user interface.
+
+
+### Features
+* Fetch user profiles from Stack Overflow.
+* Download profile images asynchronously.
+* Detect faces in the images using the `dlib` library.
+* Display the results in a user-friendly web interface using Gradio.
+
+
+## Installation
+
+### Prerequisites
+* Python 3.8 or higher
+* pip3 
+
+### Installing Dependencies
+1. Clone the repository:
+```sh
+git clone https://github.com/ardaatahan/technical-challenge.git
+cd technical-challenge
+```
+
+2. dlib requires cmake. If cmake is not installed:
+```sh
+brew install cmake
+```
+or you can follow [this](https://cgold.readthedocs.io/en/latest/first-step/installation.html) guide if you are using a different package manager/OS.
+
+3. Install the required packages:
+```sh
+pip3 install -r requirements.txt
+```
+
+### Usage 
+To run the project:
+
+1. Start the application:
+```sh
+python3 stack_overflow_users.py
+```
+
+2. Open your web browser and navigate to the link provided by Gradio.
+
+3. Press Generate button to fetch users and display results or Clear button to clear the results.
+
+### How It Works
+1. The application makes a call to the Stack Overflow API to fetch the top 10 user profiles.
+2. It then asynchronously downloads the profile images of these users.
+3. Each image is processed to detect faces using the `dlib` library.
+4. Results are displayed in a Gradio interface, showing the user details along with their profile image marked with detected faces.
+
+### Third Party Libraries Used
+`numpy`:
+* Use Case: Used extensively for handling arrays, which is crucial when manipulating image data received from profile images. numpy allows efficient operations on images, such as transformations and decoding, which are essential for the image processing steps prior to applying face detection algorithms.
+* Why Chosen: Chosen for its performance and wide support in the Python ecosystem, especially in data manipulation and numerical operations which are fundamental in image processing tasks.
+
+`gradio`:
+* Use Case: Facilitates the creation of a user-friendly interface that displays the Stack Overflow profiles and the results of the face detection process. Gradio makes it straightforward to create interactive blocks for displaying images and text, which are essential for the output of this project.
+* Why Chosen: Gradio is particularly effective for creating demo applications quickly and with minimal code. It supports a wide range of inputs and outputs, making it ideal for projects that require showcasing machine learning or image processing results in an intuitive way.
+
+`aiohttp`:
+* Use Case: Used to handle asynchronous HTTP requests to the Stack Overflow API. This is important for non-blocking data retrieval, allowing the application to perform other tasks, such as processing images, while waiting for HTTP responses.
+* Why Chosen: aiohttp is chosen for its ability to handle asynchronous web requests efficiently, which helps in maintaining responsiveness and scalability of the application when dealing with I/O-bound tasks like network requests.
+
+`opencv`:
+* Use Case: Provides a variety of image processing functionalities which are used to decode images from bytes, convert image formats, and prepare images for face detection. The headless version is used to reduce the overhead since GUI features of OpenCV are not needed.
+* Why Chosen: The headless version of OpenCV reduces the installation footprint and removes unnecessary dependencies on GUI libraries, which is beneficial for deployment in server environments or containers where graphical user interfaces are not utilized.
+
+`dlib`:
+* Use Case: Employs robust machine learning algorithms to detect faces in images. dlib offers one of the most effective and accurate face detection models available, making it suitable for projects that require reliable facial recognition.
+* Why Chosen: Despite its complex setup, dlib is selected for its superior performance in face detection compared to other libraries. Its face detector is based on a modification of the standard Histogram of Oriented Gradients (HOG) + Linear SVM method, which is well-suited for this application given its accuracy and efficiency in detecting human faces.

requirements.txt

@@ -0,0 +1,5 @@
+aiohttp==3.9.5
+dlib==19.24.4
+gradio==4.28.3
+numpy==1.26.4
+opencv_python==4.9.0.80

stack_overflow_users.py

@@ -0,0 +1,218 @@
+import numpy as np
+import gradio as gr
+
+import aiohttp
+import asyncio
+import cv2
+import dlib
+import base64
+import ssl
+
+
+ssl._create_default_https_context = ssl._create_unverified_context
+
+
+URL = "https://api.stackexchange.com/2.2/users?site=stackoverflow"
+MAX_USERS = 10
+
+
+def filter_profile_data(data):
+    """
+    Filter user profile data to get reputation, display name, profile link, and profile image
+    of first 10 users based on reputation.
+
+    :param data: array of dicts containing raw user profile information
+    :return: array of dicts filtered user profile information
+    """ 
+    data = data["items"]
+    data = data[: min(MAX_USERS, len(data))]
+    keys_to_keep = ["reputation", "location", "display_name", "link", "profile_image"]
+    filtered_data = []
+    for raw_user in data:
+        user = {}
+        for key in keys_to_keep:
+            user[key] = raw_user[key] if key in raw_user else None
+        filtered_data.append(user)
+    return filtered_data
+
+
+async def fetch_stack_overflow_profiles(url):
+    """
+    Fetch user profiles from Stack Overflow API.
+
+    :param url: URL of API to be called
+    :return: Raw user profile data if response is successful else error message
+    """ 
+    async with aiohttp.ClientSession() as session:
+        try:
+            async with session.get(url, timeout=10) as response:
+                if response.status == 200:
+                    data = await response.json()
+                    data = filter_profile_data(data)
+                    return data
+                else:
+                    return f"Failed to retrieve Stack Overflow user data: Status Code {response.status}"
+        except aiohttp.ClientError as e:
+            return str(e)
+        except asyncio.TimeoutError:
+            return "User data request timed out"
+
+
+async def download_profile_image(url):
+    """
+    Download profile image from given URL.
+
+    :param url: URL of profile image
+    :return: RGB decoded image if image can be downloaded else error message
+    """ 
+    async with aiohttp.ClientSession() as session:
+        try:
+            async with session.get(url, timeout=10) as response:
+                if response.status == 200:
+                    data = await response.read()
+                    array = np.asarray(bytearray(data), dtype=np.uint8)
+                    image = cv2.imdecode(array, 1)
+                    return image
+                else:
+                    return f"Failed to retrieve user profile image: Status Code {response.status}"
+        except aiohttp.ClientError as e:
+            return f"Profile image could not be downloaded: {str(e)}"
+        except asyncio.TimeoutError:
+            return "User profile image request timed out"
+
+
+def detect_face_in_image(image):
+    """
+    Detects whether a there is a face in the input image using dlib.
+
+    :param image: Image to check for face 
+    :return: Image with bounding box highlighting face if face exists else original image
+    :return: True if face exists in image else False
+    """ 
+    detector = dlib.get_frontal_face_detector()
+    faces, _, _ = detector.run(image, 1, -0.5)
+    for face in faces:
+        cv2.rectangle(
+            image,
+            (face.left(), face.top()),
+            (face.right(), face.bottom()),
+            (0, 255, 0),
+            4,
+        )
+    _, buffer = cv2.imencode(".jpg", image)
+    image = base64.b64encode(buffer)
+    return image, len(faces) > 0
+
+
+def fetch_and_process_users():
+    """
+    Higher level function to fetch users and analyze their profile images.
+
+    :return: HTML content displaying fetched user information and error messages as necessary
+    """ 
+    profiles = asyncio.run(fetch_stack_overflow_profiles(URL))
+    if type(profiles) is str:
+        return get_error_html(profiles)
+    
+    user_content = []
+
+    for profile in profiles:
+        image_url = profile["profile_image"]
+        image = asyncio.run(download_profile_image(image_url)) if image_url else None
+
+        if image is None:
+            user_html = get_user_html(None, profile, "", "Image for this user could not be fetched!")
+            user_content.append(user_html)
+            continue
+
+        if type(image) is str:
+            user_html = get_user_html(None, profile, "", image)
+            user_content.append(user_html)
+            continue
+
+        image, face_exists = detect_face_in_image(image)
+        face_message = (
+            "Face detected and highlighted in the user profile image!"
+            if face_exists
+            else "No face detected in the user profile image!"
+        )
+        image = image.decode("utf-8")
+        
+        user_html = get_user_html(image, profile, face_message, None)
+        user_content.append(user_html)
+        
+    return "".join(user_content)
+
+
+def get_error_html(error_message):
+    """
+    Constructs an HTML template to display error message.
+
+    :param error_message: Message to be displayed 
+    :return: HTML code with the error message
+    """ 
+    return f"""
+        <div style='display: flex; flex-direction: column; align-items: center; margin-bottom: 5rem;'>
+            <div style='text-align: center; font-size: 16px;'> 
+                <strong style='font-size: 18px;'></strong> {error_message} Try generating again.
+                <br>
+            </div>
+        </div>
+        """
+
+
+def get_user_html(image, profile, face_message, error_message):
+    """
+    Constructs an HTML template to display user information and error message.
+
+    :param image: Base64 image to be displayed on the page
+    :param profile: Profile information to be displayed 
+    :param face_message: Message that indicates whether face exists or not in the picture
+    :param error_message: Error message to display in case image cannot be fetched
+    :return: HTML code with the user information with a potential error message
+    """ 
+    return f"""
+        <div style='display: flex; flex-direction: column; align-items: center; margin-bottom: 5rem;'>
+           {f"""<div style='margin-bottom: 1rem;'>
+                <img src="data:image/jpeg;base64,{image}" alt="Profile image" style='width: 100%; height: 100%; object-fit: cover;'>
+            </div>""" if error_message is None else f"""<div style='text-align: center; font-size: 16px; margin-bottom: 1rem;'> 
+                <strong style='font-size: 18px;'></strong> {error_message} Try generating again.
+                <br>
+            </div>"""}
+            <div style='text-align: center; font-size: 16px;'> 
+                <strong style='font-size: 18px;'>Name:</strong> {profile.get("display_name", "Not available")}
+                <br>
+                <strong style='font-size: 18px;'>Reputation:</strong> {profile.get("reputation", "Not available")}
+                <br>
+                <strong style='font-size: 18px;'>Location:</strong> {profile.get("location", "Not available")}
+                <br>
+                <a href="{profile.get("link", "")}" target="_blank" style='font-size: 16px; color: blue; text-decoration: none;'>View Profile</a>
+                {f"""<br>
+                <span style='font-size: 16px; color: grey;'>{face_message}</span>""" if error_message is None else """"""}
+            </div>
+        </div>
+        """
+
+
+def get_html_content():
+    """
+    Constructs the whole HTML template to be displayed to the user. 
+
+    :return: HTML code to display each user's information and error messages
+    """
+    html_content = fetch_and_process_users()
+    return html_content
+
+
+demo = gr.Interface(
+    fn=get_html_content,
+    inputs=[],
+    outputs=gr.components.HTML(label="Stack Overflow User Profiles"),
+    title="Stack Overflow User Profiles and Face Detection",
+    css="footer{display:none !important}",
+    allow_flagging="never",
+)
+
+
+if __name__ == "__main__":
+    demo.launch()