add optional module on image processing workflow using AWS Step Functions (#18)

* add optional module on image processing workflow using AWS Step Functions

Author: angelarw

ImageProcessing/README.md

@@ -0,0 +1,116 @@
+CC0 1.0 Universal
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator and
+subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for the
+purpose of contributing to a commons of creative, cultural and scientific
+works ("Commons") that the public can reliably and without fear of later
+claims of infringement build upon, modify, incorporate in other works, reuse
+and redistribute as freely as possible in any form whatsoever and for any
+purposes, including without limitation commercial purposes. These owners may
+contribute to the Commons to promote the ideal of a free culture and the
+further production of creative, cultural and scientific works, or to gain
+reputation or greater distribution for their Work in part through the use and
+efforts of others.
+
+For these and/or other purposes and motivations, and without any expectation
+of additional consideration or compensation, the person associating CC0 with a
+Work (the "Affirmer"), to the extent that he or she is an owner of Copyright
+and Related Rights in the Work, voluntarily elects to apply CC0 to the Work
+and publicly distribute the Work under its terms, with knowledge of his or her
+Copyright and Related Rights in the Work and the meaning and intended legal
+effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not limited
+to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display, communicate,
+  and translate a Work;
+
+  ii. moral rights retained by the original author(s) and/or performer(s);
+
+  iii. publicity and privacy rights pertaining to a person's image or likeness
+  depicted in a Work;
+
+  iv. rights protecting against unfair competition in regards to a Work,
+  subject to the limitations in paragraph 4(a), below;
+
+  v. rights protecting the extraction, dissemination, use and reuse of data in
+  a Work;
+
+  vi. database rights (such as those arising under Directive 96/9/EC of the
+  European Parliament and of the Council of 11 March 1996 on the legal
+  protection of databases, and under any national implementation thereof,
+  including any amended or successor version of such directive); and
+
+  vii. other similar, equivalent or corresponding rights throughout the world
+  based on applicable law or treaty, and any national implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention of,
+applicable law, Affirmer hereby overtly, fully, permanently, irrevocably and
+unconditionally waives, abandons, and surrenders all of Affirmer's Copyright
+and Related Rights and associated claims and causes of action, whether now
+known or unknown (including existing as well as future claims and causes of
+action), in the Work (i) in all territories worldwide, (ii) for the maximum
+duration provided by applicable law or treaty (including future time
+extensions), (iii) in any current or future medium and for any number of
+copies, and (iv) for any purpose whatsoever, including without limitation
+commercial, advertising or promotional purposes (the "Waiver"). Affirmer makes
+the Waiver for the benefit of each member of the public at large and to the
+detriment of Affirmer's heirs and successors, fully intending that such Waiver
+shall not be subject to revocation, rescission, cancellation, termination, or
+any other legal or equitable action to disrupt the quiet enjoyment of the Work
+by the public as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason be
+judged legally invalid or ineffective under applicable law, then the Waiver
+shall be preserved to the maximum extent permitted taking into account
+Affirmer's express Statement of Purpose. In addition, to the extent the Waiver
+is so judged Affirmer hereby grants to each affected person a royalty-free,
+non transferable, non sublicensable, non exclusive, irrevocable and
+unconditional license to exercise Affirmer's Copyright and Related Rights in
+the Work (i) in all territories worldwide, (ii) for the maximum duration
+provided by applicable law or treaty (including future time extensions), (iii)
+in any current or future medium and for any number of copies, and (iv) for any
+purpose whatsoever, including without limitation commercial, advertising or
+promotional purposes (the "License"). The License shall be deemed effective as
+of the date CC0 was applied by Affirmer to the Work. Should any part of the
+License for any reason be judged legally invalid or ineffective under
+applicable law, such partial invalidity or ineffectiveness shall not
+invalidate the remainder of the License, and in such case Affirmer hereby
+affirms that he or she will not (i) exercise any of his or her remaining
+Copyright and Related Rights in the Work or (ii) assert any associated claims
+and causes of action with respect to the Work, in either case contrary to
+Affirmer's express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+  a. No trademark or patent rights held by Affirmer are waived, abandoned,
+  surrendered, licensed or otherwise affected by this document.
+
+  b. Affirmer offers the Work as-is and makes no representations or warranties
+  of any kind concerning the Work, express, implied, statutory or otherwise,
+  including without limitation warranties of title, merchantability, fitness
+  for a particular purpose, non infringement, or the absence of latent or
+  other defects, accuracy, or the present or absence of errors, whether or not
+  discoverable, all to the greatest extent permissible under applicable law.
+
+  c. Affirmer disclaims responsibility for clearing rights of other persons
+  that may apply to the Work or any use thereof, including without limitation
+  any person's Copyright and Related Rights in the Work. Further, Affirmer
+  disclaims responsibility for obtaining any necessary consents, permissions
+  or other rights required for any use of the Work.
+
+  d. Affirmer understands and acknowledges that Creative Commons is not a
+  party to this document and has no duty or obligation with respect to this
+  CC0 or use of the Work.
+
+For more information, please see
+<http://creativecommons.org/publicdomain/zero/1.0/>

ImageProcessing/images/1st-state-machine-graph.png

@@ -0,0 +1,3 @@
+## Attribution
+
+This photo is from [https://www.pexels.com/photo/red-hand-iphone-smartphone-80673/](https://www.pexels.com/photo/red-hand-iphone-smartphone-80673/) and is under the CC0 license. 

ImageProcessing/images/1st_execution_result.png

@@ -0,0 +1,53 @@
+import os
+import json
+import cfnresponse
+
+import boto3
+from botocore.exceptions import ClientError
+
+client = boto3.client('s3')
+
+import logging
+
+logger = logging.getLogger()
+logger.setLevel(logging.INFO)
+
+
+def handler(event, context):
+    logger.info("Received event: %s" % json.dumps(event))
+    source_bucket = event['ResourceProperties']['SourceBucket']
+    source_prefix = event['ResourceProperties'].get('SourcePrefix') or ''
+    bucket = event['ResourceProperties']['Bucket']
+    prefix = event['ResourceProperties'].get('Prefix') or ''
+
+    result = cfnresponse.SUCCESS
+
+    try:
+        if event['RequestType'] == 'Create' or event['RequestType'] == 'Update':
+            result = copy_objects(source_bucket, source_prefix, bucket, prefix)
+        elif event['RequestType'] == 'Delete':
+            result = delete_objects(bucket, prefix)
+    except ClientError as e:
+        logger.error('Error: %s', e)
+        result = cfnresponse.FAILED
+
+    cfnresponse.send(event, context, result, {})
+
+
+def copy_objects(source_bucket, source_prefix, bucket, prefix):
+    paginator = client.get_paginator('list_objects_v2')
+    page_iterator = paginator.paginate(Bucket=source_bucket, Prefix=source_prefix)
+    for key in {x['Key'] for page in page_iterator for x in page['Contents']}:
+        source_key = key
+        dest_key = os.path.join(prefix, os.path.relpath(key, source_prefix))
+        print 'copy {} to {}'.format(key, dest_key)
+        client.copy_object(CopySource={'Bucket': source_bucket, 'Key': key}, Bucket=bucket, Key=dest_key)
+    return cfnresponse.SUCCESS
+
+
+def delete_objects(bucket, prefix):
+    paginator = client.get_paginator('list_objects_v2')
+    page_iterator = paginator.paginate(Bucket=bucket, Prefix=prefix)
+    objects = [{'Key': x['Key']} for page in page_iterator for x in page['Contents']]
+    client.delete_objects(Bucket=bucket, Delete={'Objects': objects})
+    return cfnresponse.SUCCESS

ImageProcessing/images/2nd-state-machine-graph.png

@@ -0,0 +1,5 @@
+appdirs==1.4.3
+cfn-response==0.0.4
+packaging==16.8
+pyparsing==2.2.0
+six==1.10.0

ImageProcessing/images/3rd-state-machine-graph.png

@@ -0,0 +1,54 @@
+const util = require('util');
+const AWS = require('aws-sdk');
+const rekognition = new AWS.Rekognition();
+
+exports.handler = (event, context, callback) =>
+{
+    console.log("Reading input from event:\n", util.inspect(event, {depth: 5}));
+
+    const srcBucket = event.s3Bucket;
+    // Object key may have spaces or unicode non-ASCII characters.
+    const srcKey = decodeURIComponent(event.s3Key.replace(/\+/g, " "));
+
+    var params = {
+        Image: {
+            S3Object: {
+                Bucket: srcBucket,
+                Name: srcKey
+            }
+        },
+        Attributes: ['ALL']
+    };
+
+    rekognition.detectFaces(params).promise().then((data)=> {
+        console.log("Detection result from rekognition:\n", util.inspect(data, {depth: 5}));
+        if (data.FaceDetails.length != 1) {
+            callback(new PhotoDoesNotMeetRequirementError("Detected " + data.FaceDetails.length + " faces in the photo."));
+        }
+        if (data.FaceDetails[0].Sunglasses.Value === true){
+            callback(new PhotoDoesNotMeetRequirementError("Face is wearing sunglasses"));
+        }
+        var detectedFaceDetails = data.FaceDetails[0];
+
+        // remove some fields not used in further processing to de-clutter the output.
+        delete detectedFaceDetails['Landmarks'];
+
+        callback(null, detectedFaceDetails);
+    }).catch( err=> {
+        console.log(err);
+        if (err.code === "ImageTooLargeException"){
+            callback(new PhotoDoesNotMeetRequirementError(err.message));
+        }
+        if (err.code === "InvalidImageFormatException"){
+            callback(new PhotoDoesNotMeetRequirementError("Unsupported image file format. Only JPEG or PNG is supported"));
+        }
+        callback(err);
+    });
+};
+
+
+function PhotoDoesNotMeetRequirementError(message) {
+    this.name = "PhotoDoesNotMeetRequirementError";
+    this.message = message;
+}
+PhotoDoesNotMeetRequirementError.prototype = new Error();

ImageProcessing/images/4th-state-machine-graph.png

@@ -0,0 +1,38 @@
+const util = require('util');
+const AWS = require('aws-sdk');
+const rekognition = new AWS.Rekognition();
+
+exports.handler = (event, context, callback) => {
+    console.log("Reading input from event:\n", util.inspect(event, {depth: 5}));
+
+    const srcBucket = event.s3Bucket;
+    // Object key may have spaces or unicode non-ASCII characters.
+    const srcKey = decodeURIComponent(event.s3Key.replace(/\+/g, " "));
+
+    var params = {
+        CollectionId: process.env.REKOGNITION_COLLECTION_ID,
+        Image: {
+            S3Object: {
+                Bucket: srcBucket,
+                Name: srcKey
+            }
+        },
+        FaceMatchThreshold: 70.0,
+        MaxFaces: 3
+    };
+    rekognition.searchFacesByImage(params).promise().then(data => {
+        if (data.FaceMatches.length > 0) {
+            callback(new FaceAlreadyExistsError());
+        } else {
+            callback(null, null);
+        }
+    }).catch(err => {
+        callback(err);
+    });
+};
+
+function FaceAlreadyExistsError() {
+    this.name = "FaceAlreadyExistsError";
+    this.message = "Face in the picture is already in the system. ";
+}
+FaceAlreadyExistsError.prototype = new Error();

ImageProcessing/images/already-indexed-face.png

@@ -0,0 +1,5 @@
+{
+  "userId": "johndoe",
+  "s3Bucket": "wildrydes-riderphotos-johndoe",
+  "s3Key": "1_happy_face.jpg"
+}

ImageProcessing/images/bucket-icon.png

@@ -0,0 +1,26 @@
+const util = require('util');
+const AWS = require('aws-sdk');
+const rekognition = new AWS.Rekognition();
+
+exports.handler = (event, context, callback) => {
+    const srcBucket = event.s3Bucket;
+    // Object key may have spaces or unicode non-ASCII characters.
+    const srcKey = decodeURIComponent(event.s3Key.replace(/\+/g, " "));
+
+    var params = {
+        CollectionId: process.env.REKOGNITION_COLLECTION_ID,
+        DetectionAttributes: [],
+        ExternalImageId: event.userId,
+        Image: {
+            S3Object: {
+                Bucket: srcBucket,
+                Name: srcKey
+            }
+        }
+    };
+    rekognition.indexFaces(params).promise().then(data => {
+        callback(null, data['FaceRecords'][0]['Face']);
+    }).catch(err => {
+        callback(err);
+    });
+}

ImageProcessing/images/cloudformation-delete.png

@@ -0,0 +1,20 @@
+'use strict';
+
+const util = require('util');
+
+exports.handler = (event, context, callback) => {
+
+    console.log("Reading input from event:\n", util.inspect(event, {depth: 5}));
+
+    var title = "";
+    var message = "";
+
+    if (event["errorInfo"]) {
+        title = event["errorInfo"]["Error"];
+        var errorCause = JSON.parse(event["errorInfo"]["Cause"]);
+        message = errorCause["errorMessage"];
+    }
+
+    callback(null, {"messageToSend": {"title": title, "message": message}})
+
+};

ImageProcessing/images/create-initial-state-machine-2.png

@@ -0,0 +1,9 @@
+{
+  "userId": "johndoe",
+  "s3Bucket": "wildrydes-riderphotos-johndoe",
+  "s3Key": "2_sunglass_face.jpg",
+  "errorInfo": {
+    "Error": "PhotoDoesNotMeetRequirementError",
+    "Cause": "{\"errorMessage\":\"Face is wearing sunglasses\",\"errorType\":\"PhotoDoesNotMeetRequirementError\",\"stackTrace\":[\"Object.<anonymous> (/var/task/index.js:54:46)\",\"Module._compile (module.js:409:26)\",\"Object.Module._extensions..js (module.js:416:10)\",\"Module.load (module.js:343:32)\",\"Function.Module._load (module.js:300:12)\",\"Module.require (module.js:353:17)\",\"require (internal/module.js:12:17)\"]}"
+  }
+}

ImageProcessing/images/create-machine-with-dedup.png

@@ -0,0 +1,35 @@
+// dependencies
+const AWS = require('aws-sdk');
+const util = require('util');
+
+const tableName = process.env.RIDER_PHOTOS_DDB_TABLE;
+
+const docClient = new AWS.DynamoDB.DocumentClient({
+    region: process.env.AWS_REGION
+});
+
+exports.handler = (event, context, callback) => {
+    console.log("Reading input from event:\n", util.inspect(event, {depth: 5}));
+
+    const dynamoItem = {
+        Username: event.userId,
+        s3key: event.s3Key,
+        s3bucket: event.s3Bucket
+    };
+
+    var indexDetails = event['parallelResult'][0];
+    var thumbnailDetails = event['parallelResult'][1];
+    dynamoItem['faceId'] = indexDetails['FaceId'];
+    dynamoItem['thumbnail'] = thumbnailDetails['thumbnail'];
+    docClient.put({
+        TableName: tableName,
+        Item: dynamoItem
+        // uncomment below if you want to disallow overwriting if the user is already in the table
+        //   ,ConditionExpression: 'attribute_not_exists (Username)'
+    }).promise().then(data => {
+        callback(null, data);
+    }).catch(err => {
+        callback(err);
+    })
+
+}