From c89fde2300cf06a29b82ad70962b20b9814f8894 Mon Sep 17 00:00:00 2001 From: Arnaud_Cayrol Date: Sat, 29 Mar 2025 09:08:41 +0100 Subject: [PATCH] Added README --- README.md | 65 ++++++++++++++++++++++++++++++++++++++ immich_selfie_timelapse.py | 10 ++++-- main.py | 16 ---------- 3 files changed, 73 insertions(+), 18 deletions(-) create mode 100644 README.md delete mode 100644 main.py diff --git a/README.md b/README.md new file mode 100644 index 0000000..c56ecab --- /dev/null +++ b/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. \ No newline at end of file diff --git a/immich_selfie_timelapse.py b/immich_selfie_timelapse.py index 3000b48..aab4e0b 100644 --- a/immich_selfie_timelapse.py +++ b/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") diff --git a/main.py b/main.py deleted file mode 100644 index 20a033a..0000000 --- a/main.py +++ /dev/null @@ -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/