Adding face cropping parameters to image transformation (#23592)

* Adding face cropping parameters to image transformation

* Fixing face cropping documentation

* Merge updates from upstream

* Adding responsible AI to face cropping

* Update src/content/partials/images/gravity.mdx

* Update src/content/docs/images/transform-images/transform-via-workers.mdx

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

---------

Co-authored-by: ToriLindsay <[email protected]>
Co-authored-by: Doug <[email protected]>

Author: 3 people

src/content/docs/images/transform-images/transform-via-url.mdx

@@ -135,6 +135,10 @@ You must specify at least one option. Options are comma-separated (spaces are no
 
 <Render file="width" />
 
+### `zoom`
+
+<Render file="zoom" />
+
 ## Recommended image sizes
 
 Ideally, image sizes should match exactly the size they are displayed on the page. If the page contains thumbnails with markup such as `<img width="200" …>`, then images should be resized to `width=200`. If the exact size is not known ahead of time, use the [responsive images technique](/images/manage-images/create-variants/).

src/content/docs/images/transform-images/transform-via-workers.mdx

@@ -118,6 +118,10 @@ The `fetch()` function accepts parameters in the second argument inside the `{cf
 
 <Render file="width" />
 
+### `zoom`
+
+<Render file="zoom" />
+
 In your worker, where you would fetch the image using `fetch(request)`, add options like in the following example:
 
 ```js
@@ -281,4 +285,4 @@ When testing image resizing, please deploy the script first. Resizing will not b
 
 Resized images are always cached. They are cached as additional variants under a cache entry for the URL of the full-size source image in the `fetch` subrequest. Do not worry about using many different Workers or many external URLs — they do not influence caching of resized images, and you do not need to do anything for resized images to be cached correctly.
 
-If you use the `cacheKey` fetch option to unify caches of multiple different source URLs, you must not add any resizing options to the `cacheKey`, as this will fragment the cache and hurt caching performance. The `cacheKey` option is meant for the full-size source image URL only, not for its resized variants.
+If you use the `cacheKey` fetch option to unify the caches of multiple source URLs, do not include any resizing options in the `cacheKey`. Doing so will fragment the cache and hurt caching performance. The `cacheKey` should reference only the full-size source image URL, not any of its resized versions.

src/content/partials/images/gravity.mdx

@@ -4,7 +4,8 @@
 
 import { Tabs, TabItem } from "~/components";
 
-When cropping with `fit: "cover"` and `fit: "crop"`, this parameter defines the side or point that should not be cropped. Available options are:
+Specifies how an image should be cropped when used with `fit=cover` and `fit=crop`.
+Available options are `auto`, `face`, a side (`left`, `right`, `top`, `bottom`), and relative coordinates (`XxY` with a valid range of `0.0` to `1.0`):
 
 - `auto`\
   Selects focal point based on saliency detection (using maximum symmetric surround algorithm).
@@ -17,6 +18,13 @@ When cropping with `fit: "cover"` and `fit: "crop"`, this parameter defines the
 You must subtract the height of the image before you calculate the focal point.
 :::
 
+- `face`\
+	Automatically sets the focal point based on detected faces in an image. This can be combined with the `zoom` parameter to specify how closely the image should be cropped towards the faces.
+
+	The new focal point is determined by a minimum bounding box that surrounds all detected faces. If no faces are found, then the focal point will fall back to the center of the image.
+
+	This feature uses an open-source model called RetinaFace through WorkersAI. Our model pipeline is limited only to facial detection, or identifying the pixels that represent a human face. We do not support facial identification or recognition. Read more about Cloudflare's [approach to responsible AI](https://www.cloudflare.com/trust-hub/responsible-ai/).
+
 <Tabs>
   <TabItem label="URL format">
     ```js
@@ -29,6 +37,10 @@ You must subtract the height of the image before you calculate the focal point.
     OR
 
     gravity=0x1
+
+    OR
+
+    gravity=face
     ```
 
   </TabItem>
@@ -43,6 +55,10 @@ You must subtract the height of the image before you calculate the focal point.
     OR
 
     g=0x1
+
+    OR
+
+    g=face
     ```
 
   </TabItem>
@@ -58,7 +74,10 @@ OR
 
 cf: {image: {gravity: {x:0.5, y:0.2}}}
 
+OR
+
+cf: {image: {gravity: "face"}}
 ```
 </TabItem>
 </Tabs>
-```
+```

src/content/partials/images/zoom.mdx

@@ -0,0 +1,30 @@
+---
+{}
+---
+import { Tabs, TabItem } from "~/components"
+
+Specifies how closely the image is cropped toward the face when combined with the `gravity=face` option.
+Valid range is from `0` (includes as much of the background as possible) to `1` (crops the image as closely to the face as possible), decimals allowed. The default is `0`.
+
+This controls the threshold for how much of the surrounding pixels around the face will be included in the image and takes effect only if face(s) are detected in the image.
+
+<Tabs>
+  <TabItem label="URL format">
+    ```js
+    zoom=0.1
+    ```
+  </TabItem>
+  <TabItem label="URL format alias">
+    ```js
+    zoom=0.2
+    OR
+
+    face-zoom=0.2
+    ```
+  </TabItem>
+  <TabItem label="Workers">
+  ```js
+  cf: {image: {zoom: 0.5}}
+  ```
+  </TabItem>
+</Tabs>