updated readme

README.md

@@ -76,7 +76,7 @@ docker exec -it immich-auto-stack /script/immich_auto_stack.py
 
 ## Customizing the criteria
 
-### the defaults
+### The defaults
 
 Configurable stacking criteria allows for the customization of how files are grouped
 The default in pretty json is:
@@ -152,6 +152,8 @@ By default, `jpg`, `jpeg`, and `png` files are prioritized to be the parent. The
 
 The defaults are `jpg`, `jpeg`, and `png` because they often contain the finished image. That is especially true for systems that add filters/recipes/in-camera edits or simple profile corrections, on top of the final image.
 
+![](images/image.png)
+
 Keywords can be provided to provide additional weight to files when sorting. Maybe you performed an edit that should show first or there is an HDR version of the image. For example:
 
 ```shell
@@ -167,9 +169,96 @@ IMG_1234.jpg            # score -100
 IMG_1234_edit_crop.raw  # score -2
 IMG_1234.raw            # score 0
 ```
+## Examples
 
-## Running tests
+### Stack criteria based on filename only: 
+Maybe your desired stack items were scattered through time. Beware with images from digital cameras - the count rolls over at 9999 and you end up with duplicate filenames in the long run.
+```json
+[
+  {
+    "key": "originalFileName",
+    "split": {
+      "key": ".",
+      "index": 0 // this is the default
+    }
+  }
+}
+```
+### Stack criteria based on date & time only:
+Won't work for bursts.
+```json
+[
+  {
+    "key": "localDateTime"
+  }
+}
+```
+### Stack criteria based on date only:
+This won't work very well on its own. In combination with `"originalFileName"` it can stack a sequence that for some reason does not have the same timecode.
+```json
+[
+  {
+    "key": "localDateTime",
+    "split": {
+      "key": "T",
+      "index": 0
+    }
+  }
+}
+```
+### Stack criteria for filenames that may contain other keywords:
+Like RAW, ORIGINAL, EDIT. It picks out only the initial image sequence. More can be read in issue #1.
+```json
+[
+  {
+    "key": "originalFileName",
+    "regex": {
+      "key": "([A-Z]+[-_]?[0-9]{4}([-_][0-9]{4})?)([\\._-].*)?\\.[\\w]{3,4}$",
+      "index": 1
+    }
+  }
+}
+```
+### Multiple stack criterias:
+Like the above but now the secondary criteria limites the stack to a specific date (not datetime, note that the timecode is also split).
 
+⚠️ The order of the criteria matters! in this example, primary criteria is filename, secondary is date.
+```json
+[
+  {
+    "key": "originalFileName",
+    "regex": {
+      "key": "([A-Z]+[-_]?[0-9]{4}([-_][0-9]{4})?)([\\._-].*)?\\.[\\w]{3,4}$",
+      "index": 1
+    }
+  },
+  {
+    "key": "localDateTime",
+    "split": {
+      "key": "T",
+      "index": 0
+    }
+  }
+}
+```
+### Stacking by other keys:
+There aren't that many other keys that can be used as a stacking criteria because they are either unique or not as consistent as `originalFileName` and `localDateTime`. Regardless, here are some of them - `thumbhash`, `fileCreatedAt`, `fileModifiedAt`.
+
+ - `thumbhash` is mostly consistent when you want to stack dublicates instead of deleting them. It's mostly consistent when stacking RAW+JPG but not always.
+- `fileCreatedAt`, `fileModifiedAt` can be unique for each file, preventing reliable stacking.
+
+You can see all available keys for an asset by editing the URL to get to the API enty for it:
+
+```
+https://your-immich.tld/photos/00000000-0000-0000-0000-000000000000
+
+https://your-immich.tld/api/assets/00000000-0000-0000-0000-000000000000
+```
+### Stacking by EXIF data:
+Initallly this scrip relied entirely on the EXIF portion of the asset data.
+Unfortunately, not all assets have EXIF data available and even if they did, most of it isn't appropriate for stacking. Thus stacking by EXIF data was replaced by more widely available properties.
+
+## Running tests
 ```sh
 docker build -f Dockerfile.test -t immich-auto-stack-pytest .
 docker run immich-auto-stack-pytest