Added README

README.md

@@ -0,0 +1,65 @@
+# Immich Selfie Timelapse Tool
+
+This tool helps create selfie timelapses from your Immich instance.  
+It uses the powerful machine learning features of Immich to gather all the photographs where a particular individual appears, retrieves the bounding box metadata, and automatically crops and aligns the photos.
+
+## Features
+
+- Automatically fetch images featuring a specified individual from your Immich instance.
+- Extract bounding box metadata and crop/align photos using machine learning.
+- Discard photos with low resolution (set by threshold).
+- Discard photos where the subject is viewed from the side.
+
+## Setup
+
+1. **Generate an API Key in Immich:**
+   - Log in to your Immich web UI.
+   - Navigate to the API settings (or your profile settings) and generate an API key.
+   - Copy the API key for use with the script.
+
+2. **Find the Person ID:**
+   - In the Immich web UI, view photos sorted by person.
+   - When you click on a specific person, check the URL in your browser.
+   - The person ID (usually a UUID) is part of the URL. Copy this ID for use in the script.
+
+3. **Download the Face Landmark Data:**
+   - Download the 68-point face landmark model from:
+     https://github.com/italojs/facial-landmarks-recognition/blob/master/shape_predictor_68_face_landmarks.dat
+   - Place the file in the same folder as the script, or update the predictor path in the script accordingly.
+
+4. **Install the required python modules from requirements.txt**
+   - Note that an old version of Numpy is required for compatibility with dlib.
+
+## Usage
+
+Run the script from the command line with the required arguments. For example:
+
+    python process_faces.py \
+      --api-key YOUR_API_KEY \
+      --base-url http://your.immich.server:2283/api \
+      --person-id YOUR_PERSON_ID \
+      --output-folder output
+
+### Command-line Arguments
+
+- **--api-key**: API key generated from Immich.
+- **--base-url**: Base URL of your Immich API (e.g., http://192.168.1.123:2283/api).
+- **--person-id**: The ID of the person (obtained from the Immich web UI).
+- **--output-folder**: Directory where the aligned face images will be saved (default: output).
+- **--padding-percent**: Padding added around the face as a percentage (default: 0.3).
+- **--resize-width** and **--resize-height**: Dimensions for the output image (default: 512 x 512).
+- **--min-face-width** and **--min-face-height**: Minimum acceptable face dimensions (default: 128 x 128).
+- **--pose-threshold**: Threshold for acceptable head pose.
+- **--desired-left-eye**: Desired left eye position as a fraction (x y) in the output image (default: 0.35 0.45).
+- **--max-workers**: Number of parallel processes to use (default: 4).
+
+## Additional Notes
+
+- Ensure that the `shape_predictor_68_face_landmarks.dat` file is accessible by the script. Update the path if necessary.
+- The tool may require some manual sorting of the output images to achieve the best video effect. In particular I remove images with poor lighting.
+- I find that a video framerate of 15 fps gives good results.
+- Contributions and improvements are welcome.
+
+## License
+
+This project is open source and available under the MIT License.

immich_selfie_timelapse.py

@@ -1,6 +1,12 @@
 #!/usr/bin/env python3
 """
-Script to process assets containing a specific person and align faces.
+This tool helps create selfie timelapses from your Immich instance.
+It uses the powerful machine learning features of Immich to gather all the photographs where a particular individual
+appears, retrieves the bounding box metadata, and automatically crops and aligns the photos.
+Some manual sorting is still required to achieve the best effect in the video.
+I personally found that a video frame rate of 15 fps looks pretty good.
+
+Script by Arnaud Cayrol
 """
 
 import os
@@ -214,7 +220,7 @@ def main():
     parser.add_argument("--resize-height", type=int, default=512, help="Output image height")
     parser.add_argument("--min-face-width", type=int, default=128, help="Minimum face width")
     parser.add_argument("--min-face-height", type=int, default=128, help="Minimum face height")
-    parser.add_argument("--pose-threshold", type=float, default=25, help="Threshold for acceptable head pose")
+    parser.add_argument("--pose-threshold", type=float, default=25, help="Threshold for acceptable head orientation towards camera")
     parser.add_argument("--desired-left-eye", type=float, nargs=2, default=[0.35, 0.45],
                         help="Desired left eye position as fraction (x y) in the output image")
     parser.add_argument("--max-workers", type=int, default=4, help="Maximum number of parallel workers")

main.py

@@ -1,16 +0,0 @@
-# This is a sample Python script.
-
-# Press Maj+F10 to execute it or replace it with your code.
-# Press Double Shift to search everywhere for classes, files, tool windows, actions, and settings.
-
-
-def print_hi(name):
-    # Use a breakpoint in the code line below to debug your script.
-    print(f'Hi, {name}')  # Press Ctrl+F8 to toggle the breakpoint.
-
-
-# Press the green button in the gutter to run the script.
-if __name__ == '__main__':
-    print_hi('PyCharm')
-
-# See PyCharm help at https://www.jetbrains.com/help/pycharm/