Getting Started with Amazon Rekognition Image and Video AI: A Step-by-Step Guide

Amazon Rekognition is a powerful service that lets you extract meaningful insights from images and videos. Here’s a step-by-step guide to help you get started:

1. Set Up Your AWS Account:

• If you don’t have an AWS account yet, head to https://aws.amazon.com/ and sign up for a free tier account. This gives you access to explore various AWS services, including Rekognition, with limited usage.

2. Creating an IAM Role for Amazon Rekognition

While you can initially use your AWS credentials for experimentation, creating an IAM role with specific permissions for Rekognition in a production environment is highly recommended. This approach enhances security by granting least-privilege access and helps you manage credentials more effectively.

Here’s a detailed breakdown of creating an IAM role for Rekognition:

1. Access the IAM Console:

• Log in to the AWS Management Console (https://console.aws.amazon.com/) and navigate to the IAM service. You can search for “IAM” in the search bar or find it under the “Security, Identity & Compliance” section.

2. Create a New Role:

• Click on “Roles” in the IAM service sidebar.
• Click “Create role”.

3. Choose the Use Case:

• Select the appropriate service for which you’re creating the role. In this case, choose “AWS service”. This option allows the role to be used by an AWS service, which will be your Rekognition client application.

4. Select Permissions:

• On the “Attach permissions policy” page, you have two options:
  • a) Use a Policy Template: AWS provides pre-defined policy templates with specific permissions for different services. Choose "AmazonRekognitionFullAccess" if you need access to all Rekognition functionalities. Otherwise, explore other available Rekognition-related templates based on your specific needs.
  • b) Create Custom Policy: For granular control, you can create a custom policy with the exact permissions required for Rekognition operations your application uses. - Use the search bar to find relevant Rekognition actions (e.g., `rekognition:DetectLabels`, `rekognition:RecognizeCelebrities`). - Add the necessary actions along with any required resource restrictions (e.g., specific S3 buckets for image access).

5. Review and Create:

• Review the policy permissions to ensure they align with your intended use case.
• Give your role a descriptive name for easy identification.
• Click “Create role” to finalize the role creation.

6. Attach the Role to Your EC2 Instance (if applicable):

• If running your Rekognition client application on an EC2 instance, attach the newly created role to the instance.
• Go to the EC2 service in the AWS Management Console and select the instance.
• Under the “Instance Settings” section, navigate to “Security” and then “IAM role”.
• Choose the role you created for Rekognition from the dropdown menu and click “Save”.

7. Use the Role ARN in Your Code:

• Once the role is created, you can use its ARN (Amazon Resource Name) in your application code when configuring the AWS SDK. The Rekognition client can then automatically retrieve temporary credentials associated with the role, eliminating the need to embed your main AWS credentials directly in your code. This increases security and best practices.

By creating an IAM role and attaching it to your EC2 instance (if applicable), you’ve established a more secure and controlled mechanism for Rekognition access in your application. Remember to choose the appropriate permissions level based on your specific needs.

3. Install the AWS SDK:

• Choose your preferred programming language (Python, Java, PHP, etc.) and install the AWS SDK for that language. You can find installation instructions and download links in the AWS documentation: https://docs.aws.amazon.com/sdk-for-php/

Here’s an elaboration on step 3 of the Rekognition tutorial, focusing on installing the AWS SDK for PHP:

Installing the AWS SDK for PHP:

There are two main ways to install the AWS SDK for PHP:

Method 1: Using Composer (Recommended):

1. Composer Setup: If you don’t have Composer installed yet, follow the instructions from the official website: https://getcomposer.org/doc/faqs/how-to-install-composer-programmatically.md.
2. Project Initialization: Create a new directory for your project and initialize a Composer project by running composer init in the terminal within that directory. This will create a composer.json file that manages your project’s dependencies.
3. Add AWS SDK Dependency: Edit the composer.json file and add the AWS SDK for PHP as a dependency. The following example specifies version 3 of the SDK:

{  
     "require": {
         "aws/aws-sdk-php": "^3.x"  
     }
}

4. Install Dependencies: Run composer install in your terminal to download and install the AWS SDK and any other dependencies listed in your composer.json file.

Method 2: Manual Download:

1. Download the SDK: Visit the AWS SDK for PHP download page: https://aws.amazon.com/sdk-for-php/. Choose the appropriate version for your PHP environment (e.g., compatible with your PHP version).
2. Extract the Package: Download the archive file and extract its contents into a directory within your project. You can then include the relevant files (e.g., vendor/autoload.php) in your PHP code.

Using the Installed SDK:

Once you have installed the AWS SDK using either method, you can include the vendor/autoload.php file (if using Composer) at the beginning of your PHP script to load the necessary classes and functions:

<?php

require 'vendor/autoload.php';

This allows you to use the AWS SDK classes and functions in your code to interact with Amazon Rekognition and other AWS services.

Additional Tips:

• Consider using a version control system (e.g., Git) to manage your project code and dependencies.
• Refer to the AWS SDK for PHP documentation for detailed instructions and code examples: https://docs.aws.amazon.com/sdk-for-php/

4. Configure Your Credentials:

Configuring Credentials with aws configure for Rekognition

While aws configure can be used to set up basic AWS credentials, it’s not the most secure approach for production environments, especially for services like Rekognition. However, it can be helpful for initial testing or local development. Here’s how to use it with Rekognition:

1. Open a Terminal Window:

• Launch your terminal or command prompt on your local development machine.

2. Run aws configure:

• Type the following command and press Enter:

aws configure

3. Enter Credentials:

• The command will prompt you for your AWS credentials:
  • Access key ID: Enter your AWS access key ID.
  • Secret access key: Enter your AWS secret access key.
  • Default region name: You can optionally specify a default region for Rekognition here (e.g., us-east-1). Leaving it blank allows you to set the region explicitly when using the Rekognition API in your code.
  • Default output format: This can be left as the default (json).

Important Security Considerations:

• Do not share your AWS credentials publicly! These credentials grant access to your AWS resources and should be kept confidential. Consider using more secure methods like environment variables or AWS Secrets Manager for credential management in production environments.
• Using aws configure stores your credentials in a plain text file (~/.aws/credentials). This is not ideal for production as it poses a security risk if someone gains access to your development machine.

Alternatives for Secure Credential Management:

• Environment Variables: Set environment variables like AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY with your actual credentials. This allows you to access them securely within your code without storing them directly in your codebase.
• AWS Secrets Manager: Create a secret in AWS Secrets Manager and store your credentials securely within it. Your code can then retrieve the credentials from Secrets Manager using the AWS SDK.

Using Credentials with the AWS SDK:

• Once you’ve configured your credentials using aws configure (or through a more secure method), you can use the AWS SDK for your chosen programming language to access Rekognition.
• The SDK will automatically retrieve the configured credentials and use them to make API calls.

Remember, aws configure is a basic approach for local development. For production environments, prioritize secure credential management methods like environment variables or AWS Secrets Manager.

5. Access Rekognition with the SDK:

For image processing:

• Use the AWS SDK to create a Rekognition client object. The specific code will vary depending on your chosen language, but generally involves specifying your region and credentials.
• Refer to the AWS Rekognition documentation for your chosen language for detailed examples and API references: https://docs.aws.amazon.com/rekognition/latest/dg/API_Reference.html
• Sample code in PHP below

<?php
//Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
//PDX-License-Identifier: MIT-0 (For details, see https://github.com/awsdocs/amazon-rekognition-developer-guide/blob/master/LICENSE-SAMPLECODE.)

    require 'vendor/autoload.php';

    use Aws\Rekognition\RekognitionClient;

    $options = [
       'region'            => 'us-west-2',
        'version'           => 'latest'
    ];

    $rekognition = new RekognitionClient($options);
	
    // Get local image
    $photo = 'input.jpg';
    $fp_image = fopen($photo, 'r');
    $image = fread($fp_image, filesize($photo));
    fclose($fp_image);


    // Call DetectFaces
    $result = $rekognition->DetectFaces(array(
       'Image' => array(
          'Bytes' => $image,
       ),
       'Attributes' => array('ALL')
       )
    );

    // Display info for each detected person
    print 'People: Image position and estimated age' . PHP_EOL;
    for ($n=0;$n<sizeof($result['FaceDetails']); $n++){

      print 'Position: ' . $result['FaceDetails'][$n]['BoundingBox']['Left'] . " "
      . $result['FaceDetails'][$n]['BoundingBox']['Top']
      . PHP_EOL
      . 'Age (low): '.$result['FaceDetails'][$n]['AgeRange']['Low']
      .  PHP_EOL
      . 'Age (high): ' . $result['FaceDetails'][$n]['AgeRange']['High']
      .  PHP_EOL . PHP_EOL;
    }
?>

Output:

People: Image position and estimated age
Position: 0.36749196052551 0.1610498726368
Age (low): 23
Age (high): 31

Calling the DetectFaces API

The provided code snippet focuses on step 5 of the Rekognition tutorial, which involves calling the DetectFaces API. Here’s a breakdown of what happens:

1. Define API Call Parameters:

• The code creates an associative array named $options containing two key-value pairs:
  • region: This specifies the AWS region where you want to use Rekognition (set to us-west-2 in this example). Choose the region closest to where your image is stored or where you expect most users to be located for optimal performance.
  • version: This sets the API version to latest to ensure you’re using the most recent functionalities.

2. Create a Rekognition Client:

• The code creates a RekognitionClient object using the Aws\Rekognition namespace and the $options array. This object acts as a client to interact with the Rekognition API.

3. Prepare Image Data:

• The code defines a variable $photo containing the path to your local image file (input.jpg).
• It opens the image file for reading (fopen).
• It reads the entire content of the image file into a variable $image using fread and filesize.
• The code closes the image file (fclose).

4. Call DetectFaces API:

• The core of step 5 is the line:PHP$result = $rekognition->DetectFaces(array( 'Image' => array( 'Bytes' => $image, ), 'Attributes' => array('ALL') ) );
  • This calls the DetectFaces method on the rekognition client object.
  • It provides an array of arguments representing the API call parameters:
    • Image: A sub-array containing details about the image you want to analyze.
      • Bytes: This key holds the actual image data read from the file ($image).
    • Attributes: Another sub-array specifying the type of attributes to be returned for each detected face. Here, 'ALL' is used to retrieve all available attributes, which includes AgeRange.

5. Processing Results:

• The code stores the API response in the $result variable. This response contains details about the detected faces, including bounding boxes and estimated age ranges.
• The code iterates through the FaceDetails array within the $result. For each detected face, it extracts:
  • Bounding box coordinates (Left, Top) using keys within the BoundingBox sub-array.
  • Estimated age range (Low, High) using keys within the AgeRange sub-array of each face detail.
• Finally, it prints the extracted information for each detected face.

For Video Processing:

<?php
require 'vendor/autoload.php';

use Aws\S3\S3Client;
use Aws\Rekognition\RekognitionClient;


$options = [
    'region'  => 'us-west-2',
    'version' => 'latest'
];

$s3 = new S3Client($options);
$rekognition = new RekognitionClient($options);

// Path to video file
$videoPath = 'videofile.mp4';

// S3 bucket and object key for the video
$bucket = '<bucketname>';
$key = 'videos/' . basename($videoPath);

// Upload the video to S3
$result = $s3->putObject([
    'Bucket' => $bucket,
    'Key'    => $key,
    'Body'   => fopen($videoPath, 'r')
]);

$s3options = [
    'Video' => [
        'S3Object' => [
            'Bucket' => $bucket,
            'Name'   => $key,
        ],
    ],
];

// Start label detection
$startResult = $rekognition->startLabelDetection($s3options);

// Get job ID for label detection
$labelJobId = $startResult['JobId'];

// Wait for label detection to complete
do {
    $result = $rekognition->getLabelDetection([
        'JobId' => $labelJobId,
    ]);

    // Check if label detection job is complete
    $status = $result['JobStatus'];
    if ($status === 'SUCCEEDED') {
        break;
    }

    // If the job is still in progress, wait for a while
    sleep(5);
} while ($status === 'IN_PROGRESS');

// Get label detection results
$labels = $result['Labels'];

// Output detected labels
foreach ($labels as $label) {
    //echo 'Label: ' . $label['Label']['Name'] . ' - Confidence: ' . $label['Label']['Confidence'] . '%' . PHP_EOL;
}

This PHP code utilizes Amazon Web Services (AWS) to detect labels in a video file. Here’s a breakdown of its functionality and a sample output:

Functionality:

1. Load Libraries:
   • It starts by requiring the AWS SDK for PHP (vendor/autoload.php).
   • This code assumes you have already configured the AWS SDK and set up credentials.
2. Create AWS Clients:
   • It creates instances of S3Client and RekognitionClient to interact with S3 storage and Rekognition service respectively.
   • Both clients are configured with the specified region and the latest available version.
3. Define Video Details:
   • It sets the path to the video file (videofile.mp4) you want to analyze.
   • It defines the S3 bucket name (<bucketname>) where the video will be uploaded and constructs the object key (videos/<filename>) within the bucket.
4. Upload Video to S3:
   • It uploads the video file (videofile.mp4) to the specified S3 bucket and object key using the S3Client.
5. Start Label Detection:
   • It defines an options array containing information about the video stored in S3.
   • This information includes the bucket name and object key where the uploaded video resides.
   • It calls the startLabelDetection function from the RekognitionClient with the options array.
   • This triggers the label detection process on the uploaded video.
6. Wait for Completion:
   • It retrieves the job ID for the label detection process from the start result.
   • It enters a loop that continuously checks the job status using the getLabelDetection function.
   • The loop waits for a set time (5 seconds) between checks.
   • The loop breaks when the job status becomes 'SUCCEEDED', indicating successful completion.
7. Get Label Detection Results:
   • Once the job finishes, it retrieves the labels detected in the video using the getLabelDetection function with the job ID.
   • The retrieved results are stored in the $labels array.
8. Sample Output:

Label: Car - Confidence: 85%
Label: Person - Confidence: 92%
Label: Road - Confidence: 78%

The provided PHP code utilizes an existing S3 bucket but doesn’t create one itself. Here’s a guide on creating an S3 bucket for your project:

Creating an S3 Bucket through the AWS Management Console:

1. Login to the AWS Management Console (https://aws.amazon.com/marketplace/management/signin).
2. Search for “S3” in the search bar and select “S3”.
3. Click on the orange “Create bucket” button.
4. Choose a unique bucket name that adheres to AWS naming conventions (lowercase letters, numbers, hyphens, and underscores). This name will be used in your code ($bucket).
5. Select a region where you want your bucket located. Consider factors like latency and data residency requirements. The provided code uses an example region, but you can choose a different one if needed.
6. You can leave the access control settings at the default for now. You’ll modify these later based on your specific security needs.
7. Review your selections and click “Create”.

Additional Considerations:

• Bucket Naming: Remember, bucket names must be unique across all AWS accounts and regions.
• Permissions: By default, newly created buckets are private. You’ll need to adjust permissions later if your code requires uploading or accessing objects from the bucket.

Once you’ve created the bucket, update the $bucket variable in your PHP code with the actual bucket name.

Alternative Methods for Creating Buckets:

• AWS CLI: You can use the AWS CLI (Command Line Interface) to create buckets programmatically. Refer to the AWS documentation for specific commands: https://docs.aws.amazon.com/cli/latest/reference/s3api/create-bucket.html
• AWS SDKs: AWS provides SDKs for various programming languages, including PHP. These SDKs allow you to create buckets through code. Refer to the AWS SDK for PHP documentation for details: https://aws.amazon.com/sdk-for-php/

Additional Notes:

• This code demonstrates analyzing a local image file. For production use, you might want to consider storing images in S3 buckets (Amazon’s storage service) and using S3 object references within the Image parameter.
• The Attributes parameter can be customized to specify specific face attributes you’re interested in, such as Smile, Emotions, or Eyeglasses. Refer to the AWS Rekognition documentation for a complete list: https://aws.amazon.com/rekognition/

By understanding these steps, you can effectively call the DetectFaces API and extract valuable face detection and estimation information from your images.

6. Choose an Operation:

• Rekognition offers various functionalities, including:
  • Detect Labels: Identify objects and scenes within images.
  • Detect Moderation Labels: Detect potentially inappropriate content.
  • Recognize Celebrities: Identify celebrities in images.
  • Detect Text: Extract text from images.
  • Compare Faces: Compare faces across different images.
• Choose the operation that suits your needs based on the type of information you want to extract from your images or videos.

7. Prepare Your Images:

• Rekognition can analyze images stored in S3 buckets or provided directly as binary data. Ensure your images are in a supported format (e.g., JPEG, PNG, etc.).
• For S3 buckets, make sure your IAM role or credentials have appropriate permissions to access the bucket and the specific image object.

8. Call the Rekognition API:

• Use the chosen operation in the Rekognition client object to analyze your image. The specific parameters you pass depend on the operation.
• For example, detectLabels might require the image location (S3 path or binary data), while compareFaces might need two image locations for comparison.

9. Process the Results:

• The Rekognition API returns a response object containing the results of the analysis. This might include:
  • Detected labels with confidence scores for detectLabels.
  • Moderation labels and their classifications for detectModerationLabels.
  • Details about recognized celebrities for recognizeCelebrities.
  • Extracted text content for detectText.
  • Similarity scores for face comparisons in compareFaces.
• Parse the response object and use the extracted information in your application as needed.

10. Explore Further:

• Rekognition offers various other functionalities beyond the examples mentioned above. Explore the AWS documentation to discover how it can enhance your image and video analysis needs: https://docs.aws.amazon.com/rekognition/

Additional Tips:

• Start with the free tier to experiment with Rekognition’s capabilities without initial costs.
• Consider using AWS Cost Explorer to monitor your Rekognition usage and optimize your costs.
• Explore the AWS Rekognition resources like tutorials, code samples, and best practices to get the most out of the service: https://docs.aws.amazon.com/rekognition/

By following these steps and exploring the resources provided, you’ll be well on your way to utilizing Amazon Rekognition’s powerful image and video analysis features in your applications.