Merge branch 'dev'

Author: ashleykleynhans

.coveragerc

@@ -0,0 +1,29 @@
+[run]
+source = .
+omit =
+    */venv/*
+    */tests/*
+    */examples/*
+    */unit_tests/*
+    */CodeFormer/*
+    */__pycache__/*
+    */site-packages/*
+    config*.py
+
+[report]
+exclude_lines =
+    pragma: no cover
+    def __repr__
+    raise AssertionError
+    raise NotImplementedError
+    if __name__ == .__main__.:
+    if TYPE_CHECKING:
+    @abstractmethod
+    except Exception as error:
+        raise
+    def __repr__
+    raise AssertionError
+    raise NotImplementedError
+    if __name__ == .__main__.:
+    if TYPE_CHECKING:
+    @abstractmethod

docs/api/filter-small-faces-with-min-face-size.md

@@ -0,0 +1,73 @@
+# Filter small faces using min_face_size parameter
+
+## Overview
+
+The `min_face_size` parameter allows you to filter out faces smaller than a specified percentage of the image's minimum dimension (width or height). This is useful when you want to target only prominent faces in the image and ignore smaller background faces.
+
+## How it works
+
+- `min_face_size` is specified as a percentage (0-100)
+- The filter compares each detected face's bounding box dimensions against the threshold
+- Faces with width OR height smaller than the threshold are excluded
+- The threshold is calculated as: `min_dimension * (min_face_size / 100)`
+- Where `min_dimension` is the smaller of the image's width or height
+
+## Example Use Case
+
+In an image with Harry Potter in the foreground (large face) and background characters with smaller faces, setting `min_face_size: 30` will filter out the smaller background faces, allowing you to target only Harry Potter's face.
+
+## Request
+
+In this example, setting `min_face_size` to `30` means faces must be at least 30% of the image's minimum dimension. This filters out small background faces and only processes the main face in the image.
+
+```json
+{
+  "input": {
+    "source_image": "base64 encoded source image content",
+    "target_image": "base64 encoded target image content",
+    "source_indexes": "-1",
+    "target_indexes": "-1",
+    "background_enhance": true,
+    "face_restore": true,
+    "face_upsample": true,
+    "upscale": 1,
+    "codeformer_fidelity": 0.5,
+    "output_format": "JPEG",
+    "min_face_size": 30
+  }
+}
+```
+
+## Common Values
+
+- `0` (default): No filtering, all detected faces are processed
+- `10-20`: Filter very small faces (distant background faces)
+- `20-30`: Filter small to medium faces (background characters)
+- `30-50`: Only process large, prominent faces (main subjects)
+- `50+`: Only process very large faces (close-up portraits)
+
+## Response
+
+### RUN
+
+```json
+{
+  "id": "83bbc301-5dcd-4236-9293-a65cdd681858",
+  "status": "IN_QUEUE"
+}
+```
+
+### RUNSYNC
+
+```json
+{
+  "delayTime": 20275,
+  "executionTime": 43997,
+  "id": "sync-a3b54383-e671-4e24-a7bd-c5fec16fda3b",
+  "output": {
+    "status": "ok",
+    "image": "base64 encoded output image"
+  },
+  "status": "COMPLETED"
+}
+```

docs/testing/local.md

@@ -28,13 +28,13 @@ python3 -u handler.py --rp_serve_api
 ```
 
 **NOTE:** You need to keep the RunPod Handler API running in order to
-run the tests, so open a new terminal window to run the tests. 
+run the examples, so open a new terminal window to run the examples. 
 
 ## Set your test data files
 
 You can either overwrite the images in the `data` directory with your
 own source and target files, or alternatively, you can edit the
-scripts in the `tests` directory to reference the source and target
+scripts in the `examples` directory to reference the source and target
 images somewhere else on your system.
 
 ## Remove credentials from .env
@@ -44,23 +44,24 @@ If you have added your `RUNPOD_API_KEY` and
 this directory, you should first comment them
 out before attempting to test locally.  If
 the .env file exists and the values are provided,
-the tests will attempt to send the requests to
+the examples will attempt to send the requests to
 your RunPod endpoint instead of running locally.
 
-### Run test scripts
+### Run example scripts
 
 1. Ensure that the RunPod Handler API is still running.
-2. Change directory to the `tests` directory and run
+2. Change directory to the `examples` directory and run
    one of the scripts, for example:
 ```bash
-cd tests
+cd examples
 python3 all_1_source_into_all_1_target.py
 ```
 3. This will display the HTTP status code and the filename
    of the output image, for example:
 ```
 Status code: 200
 Saving image: 792a7e9f-9c36-4d35-b408-0d45d8e2bbcb.jpg
+Total time taken for RunPod Serverless API call 14.0 seconds
 ```
 
 You can then open the output image (in this case

docs/testing/runpod.md

@@ -15,21 +15,21 @@ pip install -r requirements.txt
 
 ## Add Runpod credentials to .env
 
-Copy the `.env.example` file to '.env' in the `tests`
+Copy the `.env.example` file to '.env' in the `examples`
 directory as follows:
 
 ```bash
-cd tests
+cd examples
 cp .env.example .env
 ```
 
 Edit the .env file and add your RunPod API key to
 `RUNPOD_API_KEY` and your endpoint ID to
 `RUNPOD_ENDPOINT_ID`.  Without these credentials,
-the tests will attempt to run locally instead of
+the examples will attempt to run locally instead of
 on RunPod.
 
-## Run test scripts
+## Run example scripts
 
 Once the venv is created and activated, the requirements
 installed, and the credentials added to the .env
@@ -44,6 +44,7 @@ of the output image, for example:
 ```
 Status code: 200
 Saving image: 792a7e9f-9c36-4d35-b408-0d45d8e2bbcb.jpg
+Total time taken for RunPod Serverless API call 14.0 seconds
 ```
 
 You can then open the output image (in this case

tests/.env.example renamed to examples/.env.example

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+# Replace the single source face into the first face in the target image
+from util import post_request, encode_image_to_base64
+
+SOURCE_IMAGE = '../data/src.jpg'
+TARGET_IMAGE = '../data/hp-3faces.jpeg'
+SOURCE_INDEXES = '-1'
+TARGET_INDEXES = '-1'
+BACKGROUND_ENHANCE = True
+FACE_RESTORE = True
+FACE_UPSAMPLE = True
+UPSCALE = 1
+CODEFORMER_FIDELITY = 0.5
+OUTPUT_FORMAT = 'JPEG'
+
+
+if __name__ == '__main__':
+    # Create the payload dictionary
+    payload = {
+        "input": {
+            "source_image": encode_image_to_base64(SOURCE_IMAGE),
+            "target_image": encode_image_to_base64(TARGET_IMAGE),
+            "source_indexes": SOURCE_INDEXES,
+            "target_indexes": TARGET_INDEXES,
+            "background_enhance": BACKGROUND_ENHANCE,
+            "face_restore": FACE_RESTORE,
+            "face_upsample": FACE_UPSAMPLE,
+            "upscale": UPSCALE,
+            "codeformer_fidelity": CODEFORMER_FIDELITY,
+            "output_format": OUTPUT_FORMAT,
+            "min_face_size": 30
+        }
+    }
+
+    post_request(payload)