Star Identifier plugin (#72)

Co-authored-by: DogmaDragon <[email protected]>

Author: axxeman23

plugins/starIdentifier/README.md

@@ -0,0 +1,92 @@
+# Star Identifier
+
+https://github.com/axxeman23/star_identifier
+
+## Intro
+
+Star Identifier uses [facial recognition](https://github.com/ageitgey/face_recognition) to automatically identify who is in images or scene screenshots from the performers already in your [Stash](https://github.com/stashapp/stash) library.
+
+## Requirements
+
+### Python3
+__version: 3.10.x +__
+
+#### Installing Python
+
+1. Download Python [here](https://www.python.org/downloads/)
+2. Install & add to your PATH
+3. Configure Stash to use Python (if necessary. This can be set in the `System` tab of your `Settings` page)
+
+### Libs & Dependencies
+
+#### CMake
+
+For Windows:
+
+- You'll also need to install Microsoft Visual Studio 2015 (or newer) with C/C++ Compiler installed. [Link here](https://visualstudio.microsoft.com/downloads/)
+- Install and add CMake to your PATH. [Link](https://cmake.org/download/)
+- For more details, see [this issue](https://github.com/ageitgey/face_recognition/issues/175)
+
+For Mac & Linux:
+`brew install cmake`
+
+#### Python Libraries
+
+1. numpy
+2. dlib
+3. face_recognition
+
+`pip install numpy dlib face_recognition`
+
+For more details, see the [Face Recognition installation instructions](https://github.com/ageitgey/face_recognition#installation).
+
+### Plugin Files
+
+You'll need the following in your `plugins` folder from this repo. Copy `star_identifier.yml` to the `plugins` folder, and the rest of the files to a folder called `py_plugins` inside the `plugins` folder. If you already have `log.py` in `py_plugins`, skip copying that one (it should be the same)
+
+```
+star_identifier.yml
+py_plugins:
+  | log.py
+  | star_identifier_config.py
+  | star_identifier_interface.py
+  | star_identifier.py
+```
+
+## Config
+
+### Paths
+
+Running the plugin will create a folder. By default, this will be created in your `plugins` folder, but you can change that in the config.
+
+Face encodings will be saved to that new folder. The encodings file will be roughly 1MB per 1,000 performers.
+
+### Stash Settings
+
+Star Identifier uses a tag to find images or scenes you would like identified. By default, that tag is `star identifier`.
+
+Since the recognition is based on a single performer image, that image needs to have a pretty clear front-facing view of the performer's face. If face_recognition fails to find a performer's face, Star Identifier will tag that performer with `star identifier performer error` by default.
+
+### Star Identifier Settings
+
+You can adjust the tolerance for identification here. `0.6` is default and typical, but I've found `0.5` to work well. Lower is more strict.
+
+## Running
+
+### Export Performers
+
+This is the first step. Star Identifier loads each performer's image, encodes their facial features into a numpy array, and saves those arrays. The clearer the face of the performer, the better identification results will be. Performers whose faces are not recognized by face_recognition will be tagged for you to update as desired.
+
+This only needs to be run once, or after new performers are added or have updated images.
+
+### Identify Images
+
+This loads all images in the stash database tagged with `star identifier` (by default), compares the recognized faces to the exported face database, and then adds all potential matches to those images as performers.
+
+### Identify Scene Screenshots
+
+This loads the screenshot for every scene in the stash database tagged with `star identifier` (by default), compares the recognized faces to the exported face database, and then adds all potential matches to those scenes as performers.
+
+## Upcoming roadmap
+
+See [issues](https://github.com/axxeman23/star_identifier/issues)

plugins/starIdentifier/log.py

@@ -0,0 +1,52 @@
+import sys
+
+
+# Log messages sent from a plugin instance are transmitted via stderr and are
+# encoded with a prefix consisting of special character SOH, then the log
+# level (one of t, d, i, w, e, or p - corresponding to trace, debug, info,
+# warning, error and progress levels respectively), then special character
+# STX.
+#
+# The LogTrace, LogDebug, LogInfo, LogWarning, and LogError methods, and their equivalent
+# formatted methods are intended for use by plugin instances to transmit log
+# messages. The LogProgress method is also intended for sending progress data.
+#
+
+def __prefix(level_char):
+	start_level_char = b'\x01'
+	end_level_char = b'\x02'
+
+	ret = start_level_char + level_char + end_level_char
+	return ret.decode()
+
+
+def __log(level_char, s):
+	if level_char == "":
+		return
+
+	print(__prefix(level_char) + s + "\n", file=sys.stderr, flush=True)
+
+
+def LogTrace(s):
+	__log(b't', s)
+
+
+def LogDebug(s):
+	__log(b'd', s)
+
+
+def LogInfo(s):
+	__log(b'i', s)
+
+
+def LogWarning(s):
+	__log(b'w', s)
+
+
+def LogError(s):
+	__log(b'e', s)
+
+
+def LogProgress(p):
+	progress = min(max(0, p), 1)
+	__log(b'p', str(progress))

plugins/starIdentifier/requirements.txt

@@ -0,0 +1,3 @@
+face_recognition
+numpy
+requests