Merge pull request #20 from humanmade/update/recog-docs-improvements

Better docs & recognition improvements

composer.json

@@ -14,7 +14,7 @@
 		"humanmade/tachyon-plugin": "0.10.1",
 		"humanmade/smart-media": "0.1.13",
 		"humanmade/gaussholder": "1.1.3",
-		"humanmade/aws-rekognition": "0.1.4"
+		"humanmade/aws-rekognition": "0.1.5"
 	},
 	"autoload" : {
 		"files": [

docs/image-recognition.md

@@ -5,3 +5,125 @@ The Media module includes support for automatic image recognition of all images
 This is implementation using the [AWS Rekognition](https://github.com/humanmade/aws-rekognition) plugin and service.
 
 By default automatic image recognition is enabled, but can be specifically disabled by setting the `modules.media.rekognition` setting to `false`.
+
+## Recognition features
+
+### Labels
+
+Standard image label detection is enabled by default and provides basic information similar to tags on a piece of content, for example "nature", "aircraft" or "person" and can be searched against.
+
+This data can be accessed via the post meta key `hm_aws_rekognition_labels`.
+
+### Moderation labels
+
+Moderation labels provide information on potential adult content in uploaded images.
+
+This data can be accessed via the post meta key `hm_aws_rekognition_moderation`.
+
+### Faces
+
+Face detection provides the location and size of any faces in an image, as well as an ID if associated with a collection. You can [learn more about creating a face collection using the AWS SDK here](https://docs.aws.amazon.com/rekognition/latest/dg/collections.html).
+
+This data can be accessed via the post meta key `hm_aws_rekognition_faces`.
+
+### Celebrities
+
+This feature returns data on celebrities recognised in an image. Any successful matches will be used to populate the default image alt text if not already set. The alt text can be updated after it has been set dynamically as well.
+
+This data can be accessed via the post meta key `hm_aws_rekognition_celebrities`.
+
+### Text
+
+Text content can be extracted from uploaded images using this feature. By default it is used to enhance relevancy when searching in the media library.
+
+This data can be accessed via the post meta key `hm_aws_rekognition_text`.
+
+## Configuration
+
+The features described above can be toggled in your project's `composer.json` under the `extra.altis.modules.rekognition` property. The default configuration is shown below:
+
+```json
+{
+	"extra": {
+		"altis": {
+			"modules": {
+				"media": {
+					"rekognition": {
+						"labels": true,
+						"moderation": false,
+						"faces": false,
+						"celebrities": false,
+						"text": false
+					}
+				}
+			}
+		}
+	}
+}
+```
+
+## Hooks and filters
+
+You can build new features on top of the basic image recognition features either using the data collected by default or by hooking in.
+
+### `hm.aws.rekognition.process`
+
+Runs when an image is being processed and recieves the AWS Rekognition client object, the attachment ID and the data to pass for the `Image` parameter. You can use this to do any custom processing such as searching for faces in an existing collection.
+
+```php
+add_action( 'hm.aws.rekognition.process', function ( Aws\Rekognition\RekognitionClient $client, int $id, array $image_args ) {
+	$known_faces = $client->searchFacesByImage( [
+		'CollectionId' => 'ABCDEF123456',
+		'FaceMatchThreshold' => 0.9,
+		'Image' => $image_args,
+	] );
+
+	if ( ! empty( $known_faces['FaceMatches'] ) ) {
+		update_post_meta( $id, 'recognised_faces', $known_faces['FaceMatches'] );
+	}
+}, 10, 2 );
+```
+
+You can find the [full documentation for the `RekognitionClient` object here](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-rekognition-2016-06-27.html).
+
+### `hm.aws.rekognition.keywords`
+
+Filters the keywords stored and used to enhance media library search results. Recieves the current keyword list, the data returned from built in image processing according to what features are enabled eg. labels, faces etc... and the attachment ID.
+
+This is useful for doing any post processing of the recognition results such as translation.
+
+```php
+add_filter( 'hm.aws.rekognition.keywords', function ( array $keywords, array $data, int $id ) {
+	$translated_keywords = [];
+
+	// This could be Google translate for example.
+	$translation_service = new TranslationService();
+
+	foreach ( $keywords as $keyword ) {
+		$translated_keywords[] = $translation_service->translate( $keyword, 'fr' );
+	}
+
+	return $translated_keywords;
+}, 10, 3 );
+```
+
+### `hm.aws.rekognition.alt_text`
+
+Similar to the `hm.aws.rekognition.keywords` filter but allows you modify the generated alt text when none has been set yet.
+
+This can be good for enhancing the default alt text such as in the example below which lists detected celebrities as they appear from left to right in the image.
+
+```php
+add_filter( 'hm.aws.rekognition.alt_text', function ( string $new_alt_text, array $data, int $id ) {
+	if ( ! empty( $data['celebrities'] ) ) {
+		$celebrities = $data['celebrities'];
+		uasort( $celebrities, function ( $a, $b ) {
+			return $a['Face']['BoundingBox']['Left'] <=> $b['Face']['BoundingBox']['Left'];
+		} );
+		$names = wp_list_pluck( $celebrities, 'Name' );
+		return sprintf( 'From left to right: %s', implode( ', ', $names ) );
+	}
+
+	return $new_alt_text;
+}, 10, 3 );
+```

docs/lazy-loading.md

@@ -13,13 +13,15 @@ Lazy loading of images in post content is enabled by default. This behavior can
 Lazy loading is enabled on a per image size basis, so you must configure the specific image sizes. This is done via the `image-sizes` key in the configuration:
 
 ```json
-"extra": {
-	"altis": {
-		"modules": {
-			"media": {
-				"gaussholder": {
-					"image-sizes": {
-						"large": 32
+{
+	"extra": {
+		"altis": {
+			"modules": {
+				"media": {
+					"gaussholder": {
+						"image-sizes": {
+							"large": 32
+						}
 					}
 				}
 			}

docs/readme.md

@@ -1,3 +1,3 @@
 # Media
 
-The Media module includes features and enhanced related to media types.
+The Media module includes features and enhancements related to uploaded media. This includes [lazy loading](./lazy-loading.md), [AI powered image classification](./image-recognition.md) plus [dynamic image manipulation](./dynamic-images.md) and cropping tools.

inc/namespace.php

@@ -53,10 +53,33 @@ function load_plugins() {
 		add_filter( 'hm.aws.rekognition.client', __NAMESPACE__ . '\\override_aws_rekognition_aws_client', 10, 2 );
 		add_filter( 'ep_post_sync_args_post_prepare_meta', __NAMESPACE__ . '\\add_rekognition_keywords_to_search_index', 10, 2 );
 		add_filter( 'ep_search_fields', __NAMESPACE__ . '\\add_rekognition_keywords_to_search_fields' );
+
+		/**
+		 * Configure Rekognition features.
+		 */
+		if ( is_array( $config['rekognition'] ) ) {
+			$rekognition = $config['rekognition'];
+			add_filter( 'hm.aws.rekognition.labels', get_bool_callback( $rekognition['labels'] ?? true ) );
+			add_filter( 'hm.aws.rekognition.moderation', get_bool_callback( $rekognition['moderation'] ?? false ) );
+			add_filter( 'hm.aws.rekognition.faces', get_bool_callback( $rekognition['faces'] ?? false ) );
+			add_filter( 'hm.aws.rekognition.celebrities', get_bool_callback( $rekognition['celebrities'] ?? false ) );
+			add_filter( 'hm.aws.rekognition.text', get_bool_callback( $rekognition['text'] ?? false ) );
+		}
+
 		require_once $vendor_dir . '/humanmade/aws-rekognition/plugin.php';
 	}
 }
 
+/**
+ * Returns a callable that return true or false.
+ *
+ * @param boolean $value The value to check.
+ * @return callable A callback that returns $value.
+ */
+function get_bool_callback( bool $value ) : callable {
+	return $value ? '__return_true' : '__return_false';
+}
+
 /**
  * Set the image sizes that Gaussholder is applied to.
  *

load.php

@@ -13,11 +13,17 @@
 
 add_action( 'altis.modules.init', function () {
 	$default_settings = [
-		'enabled'     => true,
-		'tachyon'     => true,
+		'enabled' => true,
+		'tachyon' => true,
 		'smart-media' => true,
 		'gaussholder' => true,
-		'rekognition' => true,
+		'rekognition' => [
+			'labels' => true,
+			'moderation' => false,
+			'faces' => false,
+			'celebrities' => false,
+			'text' => false,
+		],
 	];
 	register_module( 'media', __DIR__, 'Media', $default_settings, __NAMESPACE__ . '\\bootstrap' );
 } );