This demo solution demonstrates how to train a custom model to detect a specific PPE requirement, High Visibility Safety Vest. It uses a combination of Amazon Rekognition Labels Detection and Amazon Rekognition Custom Labels to prepare and train a model to identify an individual who is wearing a vest or not.
It consists of two main workflows: Training and Analysis. The former helps you to prepare dataset, train and run a Custom Labels model; the latter provides an easy way to analyze images using the model. The solution also provides a simple web interface to guide you through both training and analysis processes.
__
The Training workflow provides an easy way to prepare dataset, create, and train your own Custom Labels model. The Custom Labels model uses Image-level Labels where we assign an image (a person in our case) to either a vest or novest label to indicate a person is wearing a Safety vest or not.
The web interface exposes two options to prepare and train your first Custom Label model.
__
This option allows you drag and drop images that have not been categorized/labeled; for instance, an image with a large crowd. This option first uses Amazon Rekognition Labels Detection to obtain bounding boxes of each person's coordinate and to crop the person within the image. Then it prepares the dataset (cropped images) for you to label. The animated GIF below demonstrates the steps to prepare the training dataset. Once the preparation is done, use Option 2 (described below) to upload and train a Custom Labels model.
__
If you have already prepared your training dataset (people already cropped and labeled), choose this option to upload your training dataset by drag and drop images where people wear vest to the vest area and people who don't wear vest to the novest area. Then, create and train a Custom Labels model. The animated GIF below demonstrates the steps.
__
Once the Custom Labels model is trained and is running, you can start analyzing image(s) by dropping images into the web portal. The analysis process is designed to run concurrently; thus, you can drop one image or a collection of images at once. See the animated GIF below:
__
A few examples of the detection results are shown below:
(Green box highlights individual who is wearing a high visibility vest with a confidence score)
(Red box highlights individual who is not wearing a high visibility vest)
(Shows detection result in a mixed group)
The solution is designed with serverless architecture. The architectural diagram below illustrates an overview of the solution.
User first signs in to the web portal using Amazon Cognito service. The web application is hosted on an Amazon Simple Storage Service (S3), a web bucket indicated in the diagram. The web bucket is protected by Amazon CloudFront distribution with Origin Access Identity (OAID) which restricts direct access to the bucket.
Upon sign-in, the user is authenticated and is given a temporary security credential to access limited AWS resources such as permission to call a specific Amazon API Gateway endpoint and permission to upload images to a specific Amazon Simple Storage Service (S3) bucket, the source bucket. The source S3 bucket is configured to take advantage of Amazon S3 Transfer Acceleration.
The training and analysis workflows can only be accessed through Amazon API Gateway endpoint where the incoming requests are authenticated with AWS_IAM, the temporary security credential. The API endpoint invokes a lambda function to process the api requests.
An Amazon S3 logs bucket is created to store access logs from Amazon S3 buckets and Amazon CloudFront distribution.
Learn more about the implementation of:
- RESTful API, training and analysis components
- Webapp component
- Custom resources component used by AWS CloudFormation stack included the configuration of Amazon S3 bucket CORS policy
The solution is deployed using an AWS CloudFormation template with AWS Lambda backed custom resources. To deploy this solution, use one of the following CloudFormation templates and follows the instructions.
| AWS Region | AWS CloudFormation Template URL |
|---|---|
| EU (Ireland) | Launch stack |
| US East (N. Virginia) | Launch stack |
| US East (Ohio) | Launch stack |
| US West (Oregon) | Launch stack |
- Under Create stack page, click Next to continue
- In Specify stack details page, provide Email and Price Class parameters as follows. Click Next to continue
- In Review stack page, scroll to the bottom and make sure I acknowledge that AWS CloudFormation might create IAM resources. under Capabilities is checked. Then, click on Create stack
The stack creation takes roughly 15 minutes to complete the stack as Amazon CloudFront distribution takes about 15 minutes to propagate to the edge locations.
__
After the stack is created (~15 minutes), you should receive an invitation email from no-reply@verificationmail.com. The email contains an Amazon CloudFront URL link to access the demo portal, your login username, and a temporary password.
The sample code is written in NodeJS v10.x. So, before you start, please make sure NodeJS has been installed. You would also need to create an Amazon Simple Storage Service (Amazon S3) bucket to store the build artifacts.
Make sure you install NodeJS 10.x or above onto your system.
For MAC user, download and install from nodejs.org. Alternatively, you can also use Homebrew.
For Linux or Amazon EC2 user, follow Tutorial: Setting Up Node.js on an Amazon EC2 Instance
For Windows 10 user, make sure to install Windows Subsystem for Linux before installing NodeJS. The build and deploy scripts are written in Bash script.
The deploy-s3-dist.sh shell script uploads the build artifacts to your S3 bucket; thus, it requires AWS CLI to be installed and configured.
# after AWS CLI is installed, run the command and follow the instruction to configure your profile
aws configure
Create a S3 bucket to store the build artifacts: AWS CloudFormation (CFN) templates and Amazon Lambda packages.
Note: make sure to choose the region you intend to run the workflow; for example, us-east-1 region.
__
- Clone the repository
git clone git@github.com:awslabs/amazon-rekognition-custom-ppe-detection-with-custom-labels.git
- Change directory to deployment and run build-s3-dist.sh
cd amazon-rekognition-custom-ppe-detection-with-custom-labels/deployment
bash build-s3-dist.sh --bucket your-bucket
- Deploy the package to your S3 bucket
bash deploy-s3-dist.sh --bucket your-bucket
# optionally you could specify different AWS CLI Profile,
# AWS CLI profile (default to 'default')
# and ACL settings (default to bucket-owner-full-control)
bash deploy-s3-dist.sh --bucket your-bucket \
--profile DevProfile \
--acl public-read
Now you should have all the code packages and CFN templates uploaded to your S3 bucket.
Log in to AWS S3 Console and navigate to the bucket you created.
Make sure you see the following files under /custom-ppe-detection/1.0.0/
| Name | Description |
|---|---|
| custom-ppe-detection.template | the main cloudformation templates |
| custom-ppe-detection-custom-resources-1.0.0.zip | a package of custom resource lambda code used by cloudformation template |
| custom-ppe-detection-api-1.0.0.zip | a package of a lambda code to process GET, POST, and OPTIONS requests from Amazon API Gateway |
| custom-ppe-detection-layer-image-utils-1.0.0.zip | a package of a lambda layer used by the api lambda function |
| custom-ppe-detection-webapp-1.0.0.zip | a package of the webapp code |
This section covers two different methods to deploy your customized solution: 1) using AWS CloudFormation Console and 2) using AWS CLI command.
- Log on to AWS CloudFormation Console
- Click on Create stack with new resources (standard)
- Follow the instruction described earlier. Make sure to specify the S3 location of your customized CloudFormation template under the Amazon S3 URL field.
- Create a JSON input file as follows and save it locally; ie., cfn-input.json
[
{
"ParameterKey": "Email",
"ParameterValue": "yourname@email.com"
},
{
"ParameterKey": "PriceClass",
"ParameterValue": "Use Only U.S., Canada and Europe [PriceClass_100]"
}
]
- Run the following AWS CLI command to create the stack
aws cloudformation create-stack \
--stack-name custom-ppe-detection \
--template-url https://your-bucket.s3.amazonaws.com/custom-ppe-detection/1.0.0/custom-ppe-detection.template \
--parameters file://cfn-input.json \
--capabilities "CAPABILITY_IAM"
To delete the demo solution, simply delete the CloudFormation stack that was deployed earlier.
Important note: deleteing the CloudFormation stack does NOT remove the following resources. Therefore, make sure you manually clean up these resources to avoid potential recurring cost.
- Amazon S3 bucket (web)
- Amazon S3 bucket (source)
- Amazon S3 bucket (logs)
- Amazon Rekognition Custom Labels Project
When you build systems on AWS infrastructure, security responsibilities are shared between you and AWS. This shared model can reduce your operational burden as AWS operates, manages, and controls the components from the host operating system and virtualization layer down to the physical security of the facilities in which the services operate. For more information about security on AWS, visit the AWS Security Center.
AWS highly recommends that customers encrypt sensitive data in transit and at rest. This demo solution automatically encrypts image files and metadata at rest with Amazon Simple Storage Service (Amazon S3) Server-Side Encryption (SSE).
This demo solution deploys a static website hosted in an Amazon S3 bucket. To help reduce latency and improve security, this solution includes an Amazon CloudFront distribution with an origin access identity, which is a special CloudFront user that helps restrict access to the solution’s website bucket contents. For more information, see Restricting Access to Amazon S3 Content by Using an Origin Access Identity.
The solution uses various AWS services. Please make sure to check the pricing for each of the services.
- Amazon Rekognition Custom Labels
- Amazon Rekognition Image - Labels Detection
- Amazon S3
- Intelligent - Tiering
- Transfer acceleration
- Amazon CloudFront - on-demand
- Amazon Lambda - request and duration
- 1024MB Memory for POST requests
- 256MB Memory for OPTIONS and GET requests
- Amazon Cognito
- Amazon API Gateway - REST API
- AWS CloudFormation
Let's assume that we are training a new Custom Labels model with 2,000 images (averaging 2MB per file) in total. When the model is trained, we start the model with 1 inference endpoint, analyze with 1,000 images averaging 10 people per image. Then, we step the model after 1 hours. Also assume that we are using US East (N. Virginia) region.
The cost of Amazon Cognito and AWS CloudFormation are not included in the estimation.
| Stage | Cost Type | Unit Cost | # of Requests | Cost Per Item | Comments |
|---|---|---|---|---|---|
| Training (prep) | Amazon S3 Transfer Acceleration | $0.04 per GB | 4GB (2000 * 2MB) | $0.16 | |
| Training (prep) | Amazon S3 Storage | $0.023 per GB / Month | 4GB | $0.092 | Per Month cost |
| Training (prep) | Amazon API Gateway API Request | $3.50 per million | 2000 | $0.007 | POST request to run DetectLabels |
| Training (prep) | Amazon Lambda Requests | $0.20 per 1M requests | 2000 | $0.0004 | lambda invocation requests |
| Training (prep) | Amazon Lambda Duration (1024MB Memory) | $0.0000016667 per 100ms | 2000 * 300ms | $0.0100002 | Average label detection runtime is 300ms |
| Training (prep) | Amazon Rekognition DetectLabels | $0.001 per image | 2000 | $2 | one time cost |
| Training (dataset) | Amazon S3 Transfer Acceleration | $0.04 per GB | 2MB (2000 * 1KB) | $0.00008 | Average size of cropped person, 1KB |
| Training (dataset) | Amazon S3 Storage | $0.023 per GB / Month | 2MB | $0.000046 | Per Month Cost |
| Training (create model) | Amazon API Gateway API Request | $3.50 per million | 1 | $0.0000035 | POST request to create a Custom Labels model (CreateProjectVersion) |
| Training (create model) | Amazon Rekognition Custom Labels Training Hours | $1/hr | 2 | $2 | Assuming the training takes 2 hours |
| Training Cost | $4.27 | ||||
| Stage | Cost Type | Unit Cost | # of Requests | Cost Per Item | Comments |
| Analysis | Amazon S3 Transfer Acceleration | $0.04 per GB | 2GB (1000 * 2MB) | $0.08 | |
| Analysis | Amazon S3 Storage | $0.023 per GB / Month | 4GB | $0.092 | Per Month cost |
| Analysis | Amazon API Gateway API Request | $3.50 per million | 1000 | $0.0035 | POST request to run analysis |
| Analysis | Amazon Lambda Requests | $0.20 per 1M requests | 1000 | $0.0002 | lambda invocation requests |
| Analysis | Amazon Lambda Duration (1024MB Memory) | $0.0000016667 per 100ms | 1000 * 5000ms | $0.0083335 | Average analysis runtime is 5000ms |
| Analysis | Amazon Rekognition DetectLabels | $0.001 per image | 1000 | $1 | |
| Analysis | Amazon Rekognition Custom Labels Inference Hours | $4 per hour per inference | 1 | $4 | |
| Analysis Cost | $5.18 | ||||
| Total Cost | $9.45 |
- Total cost to try out the demo solution is $9.45
- The cost of training a model may vary depending on your training dataset. It is also applied when you are training or re-training your model
- The cost of running a Custom Labels model (Amazon Rekognition Custom Labels Inference Hours) is $4 per hour. Therefore, it is important to stop the Custom Labels model when it is not in use
Amazon Rekognition Custom Labels is supported in the following regions:
- North Virginia (us-east-1)
- Ohio (us-east-2)
- Oregon (us-west-2)
- Ireland (eu-west-1)
Make sure to check AWS Region Table for any updated region support for the service.
The solution uses the following AWS resources:
- Amazon S3 Buckets (x3)
- a web bucket to host the web application
- a source bucket to store images for training data, images for analysis, and dataset manifests
- a log bucket to store access logs from other AWS resources used in the demo solution
- Amazon Lambda (x3)
- an API backend lambda function to handle POST request with 1024MB Memory
- a smaller instance with 256MB Memory of the same lambda function to handle GET and OPTIONS requests
- a Custom Resource lambda funciton with 256MB Memory to provision resources during the stack creation
- Amazon Cognito
- an User Pool and Identity Pool to provide sign-in, sign-up, and authentication
- Amazon API Gateway
- RESTful API endpoints to interact with web appplication
- Amazon CloudFront
- a CloudFront distribution to host web application
- Amazon Rekognition
- a Custom Labels Project is created during the stack creation. The Project is then used to train your own model and run inference endpoint
- Amazon Identity and Access Management
- IAM Roles for the custom resource and the Lambda function
- AWS CloudFormation
Images and videos used in this README and training and testing datasets are courtesy of pexels.com and unsplash.com.