ibm-cloud / serverless-image-processor

Use Cloud Functions to automatically analyze images in Cloud Object Storage

Use Cloud Functions to automatically analyze images in Cloud Object Storage

Cloud Functions can be extended by integrating with Cloud Object Storage (COS). The COS trigger type lets you run custom code logic when a new object is stored, updated, or deleted from a designated bucket in COS.

This project shows a very common use for this type of trigger. Whenever an image file is uploaded to a Cloud Object Storage bucket, a sequence of actions will generate a thumbnail for the image (a smaller version) and will use IBM Cloud Visual Recognition to identify objects, places, faces from the original image.

1. The user uploads an image to the Cloud Object Storage bucket.
2. Cloud Object Storage sends an event to Cloud Functions.
3. This event triggers a sequence of actions:
   1. A thumbnail is generated and stored under the thumbnails/ prefix in the bucket.
   2. Visual Recognition is called on the image and the results stored under the metadata/ prefix in the bucket.

1. The user deletes an image.
2. Cloud Object Storage sends an event to Cloud Functions.
3. The event triggers the delete action to remove the generated thumbnail and visual recognition metadata.

The two triggers shown in the diagrams above are:

Name	Trigger Type	Description
on-create	Cloud Object Storage	Called when files are added to the bucket
on-delete	Cloud Object Storage	Called when files are deleted from the bucket

The triggers trigger the following actions:

Name	Runtime	Description
on-create	Sequence	Called via the on-create trigger when files are written to Cloud Object Storage.
filter	Node.js	Ignores non-image files and events generated by the thumbnails or visual recognition files.
thumbnail	Node.js	Uses gm to generate thumbnails from images stored in Cloud Object Storage.
visualrecognition	Node.js	Analyzes images with Visual Recognition and stores the results in the bucket.
on-delete	Sequence	Called via the on-delete trigger when files are deleted from Cloud Object Storage.
delete	Node.js	Removes thumbnails and visual recognition files.

Deploy the project

The scripts do not check permissions. You must ensure you have the right permissions:

• to create service instances,
• to create Cloud Functions namespaces (you need to be an Administrator on the Functions service)

1. To run the following scripts, make sure to install:

   • IBM Cloud CLI
   • Cloud Object Storage plugin. Install it with ibmcloud plugin install cloud-object-storage.
   • Cloud Functions plugin. Install it with ibmcloud plugin install cloud-functions.
   • jq command line utility

2. Copy the configuration file and set the values to match your environment. At a minimum, set or review the values for PREFIX, RESOURCE_GROUP_NAME and REGION.

   cp template.local.env local.env

3. Load the values into the current shell.

   source local.env

4. Ensure you have the prerequisites to run the scripts.

   ./000-prereqs.sh

5. Create Cloud Object Storage and Visual Recognition services.

   ./010-create-services.sh

   If they do not already exist, the script creates:

   • a Cloud Object Storage service instance and a service key,
   • a storage bucket
   • a Visual Recognition service instance and a service key.

   The previously defined PREFIX variable is used to define the names of these resources.

6. Create the actions and the triggers.

   ./020-create-functions.sh

7. From that point you can go into the Cloud Object Storage service instance and upload files from the IBM Cloud console. Or you can run this simple test which uses an image from Unsplash.

   ./030-test.sh

Cleanup

To delete the services and Cloud Functions artifacts, run:

./040-cleanup.sh