ImageMagick Tutorial

This tutorial demonstrates using Cloud Functions, the Google Cloud Vision API, and ImageMagick to detect and blur offensive images that get uploaded to a Cloud Storage bucket.


  • Deploy a storage-triggered Background Cloud Function.
  • Use the Cloud Vision API to detect violent or adult content.
  • Use ImageMagick to blur offensive images.
  • Test the function by uploading an image of a flesh-eating zombie.


This tutorial uses billable components of Cloud Platform, including:

  • Google Cloud Functions
  • Google Cloud Storage
  • Google Cloud Vision API

Use the Pricing Calculator to generate a cost estimate based on your projected usage.

New Cloud Platform users might be eligible for a free trial.

Before you begin

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

  4. Enable the Cloud Functions, Cloud Build, Cloud Storage, and Cloud Vision APIs.

    Enable the APIs

  5. Install and initialize the Cloud SDK.
  6. If you already have the Cloud SDK installed, update it by running the following command:

    gcloud components update
  7. Prepare your development environment.

Visualizing the flow of data

The flow of data in the ImageMagick tutorial application involves several steps:

  1. An image is uploaded to a Cloud Storage bucket.
  2. The Cloud Function analyzes the image using the Cloud Vision API.
  3. If violent or adult content is detected, the Cloud Function uses ImageMagick to blur the image.
  4. The blurred image is uploaded to another Cloud Storage bucket for use.

Preparing the application

  1. Create a Cloud Storage bucket for uploading images, where YOUR_INPUT_BUCKET_NAME is a globally unique bucket name:

    gsutil mb gs://YOUR_INPUT_BUCKET_NAME
  2. Create a Cloud Storage bucket to receive blurred images, where YOUR_OUTPUT_BUCKET_NAME is a globally unique bucket name:

    gsutil mb gs://YOUR_OUTPUT_BUCKET_NAME
  3. Clone the sample app repository to your local machine:


    git clone

    Alternatively, you can download the sample as a zip file and extract it.


    git clone

    Alternatively, you can download the sample as a zip file and extract it.


    git clone

    Alternatively, you can download the sample as a zip file and extract it.


    git clone

    Alternatively, you can download the sample as a zip file and extract it.


    git clone

    Alternatively, you can download the sample as a zip file and extract it.

  4. Change to the directory that contains the Cloud Functions sample code:


    cd nodejs-docs-samples/functions/imagemagick/


    cd python-docs-samples/functions/imagemagick/


    cd golang-samples/functions/imagemagick/


    cd java-docs-samples/functions/imagemagick/


    cd dotnet-docs-samples/functions/imagemagick/

Understanding the code

Importing dependencies

The application must import several dependencies in order to interact with Google Cloud Platform services, ImageMagick, and the file system:


const gm = require('gm').subClass({imageMagick: true});
const fs = require('fs').promises;
const path = require('path');
const vision = require('@google-cloud/vision');

const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
const client = new vision.ImageAnnotatorClient();

const {BLURRED_BUCKET_NAME} = process.env;


import os
import tempfile

from import storage, vision
from wand.image import Image

storage_client = storage.Client()
vision_client = vision.ImageAnnotatorClient()


// Package imagemagick contains an example of using ImageMagick to process a
// file uploaded to Cloud Storage.
package imagemagick

import (

	vision ""
	visionpb ""

// Global API clients used across function invocations.
var (
	storageClient *storage.Client
	visionClient  *vision.ImageAnnotatorClient

func init() {
	// Declare a separate err variable to avoid shadowing the client variables.
	var err error

	storageClient, err = storage.NewClient(context.Background())
	if err != nil {
		log.Fatalf("storage.NewClient: %v", err)

	visionClient, err = vision.NewImageAnnotatorClient(context.Background())
	if err != nil {
		log.Fatalf("vision.NewAnnotatorClient: %v", err)


import functions.eventpojos.GcsEvent;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.List;
import java.util.logging.Level;
import java.util.logging.Logger;

public class ImageMagick implements BackgroundFunction<GcsEvent> {

  private static Storage storage = StorageOptions.getDefaultInstance().getService();
  private static final String BLURRED_BUCKET_NAME = System.getenv("BLURRED_BUCKET_NAME");
  private static final Logger logger = Logger.getLogger(ImageMagick.class.getName());


using CloudNative.CloudEvents;
using Google.Cloud.Functions.Framework;
using Google.Cloud.Functions.Hosting;
using Google.Cloud.Storage.V1;
using Google.Cloud.Vision.V1;
using Google.Events.Protobuf.Cloud.Storage.V1;
using Grpc.Core;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using System;
using System.Diagnostics;
using System.IO;
using System.Threading;
using System.Threading.Tasks;

namespace ImageMagick
    // Dependency injection configuration, executed during server startup.
    public class Startup : FunctionsStartup
        public override void ConfigureServices(WebHostBuilderContext context, IServiceCollection services) =>

    public class Function : ICloudEventFunction<StorageObjectData>
        /// <summary>
        /// The bucket to store blurred images in. An alternative to using environment variables here would be to
        /// fetch it from IConfiguration.
        /// </summary>
        private static readonly string s_blurredBucketName = Environment.GetEnvironmentVariable("BLURRED_BUCKET_NAME");

        private readonly ImageAnnotatorClient _visionClient;
        private readonly StorageClient _storageClient;
        private readonly ILogger _logger;

        public Function(ImageAnnotatorClient visionClient, StorageClient storageClient, ILogger<Function> logger) =>
            (_visionClient, _storageClient, _logger) = (visionClient, storageClient, logger);


Analyzing images

The following function is invoked when an image is uploaded to the Cloud Storage bucket you created for storing images. The function uses the Cloud Vision API to detect violent or adult content in uploaded images.


// Blurs uploaded images that are flagged as Adult or Violence.
exports.blurOffensiveImages = async event => {
  // This event represents the triggering Cloud Storage object.
  const object = event;

  const file = storage.bucket(object.bucket).file(;
  const filePath = `gs://${object.bucket}/${}`;

  console.log(`Analyzing ${}.`);

  try {
    const [result] = await client.safeSearchDetection(filePath);
    const detections = result.safeSearchAnnotation || {};

    if (
      // Levels are defined in === 'VERY_LIKELY' ||
      detections.violence === 'VERY_LIKELY'
    ) {
      console.log(`Detected ${} as inappropriate.`);
      return await blurImage(file, BLURRED_BUCKET_NAME);
    } else {
      console.log(`Detected ${} as OK.`);
  } catch (err) {
    console.error(`Failed to analyze ${}.`, err);
    throw err;


# Blurs uploaded images that are flagged as Adult or Violence.
def blur_offensive_images(data, context):
    file_data = data

    file_name = file_data["name"]
    bucket_name = file_data["bucket"]

    blob = storage_client.bucket(bucket_name).get_blob(file_name)
    blob_uri = f"gs://{bucket_name}/{file_name}"
    blob_source = vision.Image(source=vision.ImageSource(gcs_image_uri=blob_uri))

    # Ignore already-blurred files
    if file_name.startswith("blurred-"):
        print(f"The image {file_name} is already blurred.")

    print(f"Analyzing {file_name}.")

    result = vision_client.safe_search_detection(image=blob_source)
    detected = result.safe_search_annotation

    # Process image
    if == 5 or detected.violence == 5:
        print(f"The image {file_name} was detected as inappropriate.")
        return __blur_image(blob)
        print(f"The image {file_name} was detected as OK.")


// GCSEvent is the payload of a GCS event.
type GCSEvent struct {
	Bucket string `json:"bucket"`
	Name   string `json:"name"`

// BlurOffensiveImages blurs offensive images uploaded to GCS.
func BlurOffensiveImages(ctx context.Context, e GCSEvent) error {
	outputBucket := os.Getenv("BLURRED_BUCKET_NAME")
	if outputBucket == "" {
		return errors.New("BLURRED_BUCKET_NAME must be set")

	img := vision.NewImageFromURI(fmt.Sprintf("gs://%s/%s", e.Bucket, e.Name))

	resp, err := visionClient.DetectSafeSearch(ctx, img, nil)
	if err != nil {
		return fmt.Errorf("AnnotateImage: %v", err)

	if resp.GetAdult() == visionpb.Likelihood_VERY_LIKELY ||
		resp.GetViolence() == visionpb.Likelihood_VERY_LIKELY {
		return blur(ctx, e.Bucket, outputBucket, e.Name)
	log.Printf("The image %q was detected as OK.", e.Name)
	return nil


// Blurs uploaded images that are flagged as Adult or Violence.
public void accept(GcsEvent event, Context context) {
  // Validate parameters
  if (event.getBucket() == null || event.getName() == null) {
    logger.severe("Error: Malformed GCS event.");

  BlobInfo blobInfo = BlobInfo.newBuilder(event.getBucket(), event.getName()).build();

  // Construct URI to GCS bucket and file.
  String gcsPath = String.format("gs://%s/%s", event.getBucket(), event.getName());"Analyzing %s", event.getName()));

  // Construct request.
  ImageSource imgSource = ImageSource.newBuilder().setImageUri(gcsPath).build();
  Image img = Image.newBuilder().setSource(imgSource).build();
  Feature feature = Feature.newBuilder().setType(Type.SAFE_SEARCH_DETECTION).build();
  AnnotateImageRequest request =
  List<AnnotateImageRequest> requests = List.of(request);

  // Send request to the Vision API.
  try (ImageAnnotatorClient client = ImageAnnotatorClient.create()) {
    BatchAnnotateImagesResponse response = client.batchAnnotateImages(requests);
    List<AnnotateImageResponse> responses = response.getResponsesList();
    for (AnnotateImageResponse res : responses) {
      if (res.hasError()) {"Error: %s", res.getError().getMessage()));
      // Get Safe Search Annotations
      SafeSearchAnnotation annotation = res.getSafeSearchAnnotation();
      if (annotation.getAdultValue() == 5 || annotation.getViolenceValue() == 5) {"Detected %s as inappropriate.", event.getName()));
      } else {"Detected %s as OK.", event.getName()));
  } catch (IOException e) {
    logger.log(Level.SEVERE, "Error with Vision API: " + e.getMessage(), e);


public async Task HandleAsync(CloudEvent cloudEvent, StorageObjectData data, CancellationToken cancellationToken)
    // Validate parameters
    if (data.Bucket is null || data.Name is null)
        _logger.LogError("Malformed GCS event.");

    // Construct URI to GCS bucket and file.
    string gcsUri = $"gs://{data.Bucket}/{data.Name}";
    _logger.LogInformation("Analyzing {uri}", gcsUri);

    // Perform safe search detection using the Vision API.
    Image image = Image.FromUri(gcsUri);
    SafeSearchAnnotation annotation;
        annotation = await _visionClient.DetectSafeSearchAsync(image);
    // If the call to the Vision API fails, log the error but let the function complete normally.
    // If the exceptions weren't caught (and just propagated) the event would be retried.
    // See the "Best Practices" section in the documentation for more details about retry.
    catch (AnnotateImageException e)
        _logger.LogError(e, "Vision API reported an error while performing safe search detection");
    catch (RpcException e)
        _logger.LogError(e, "Error communicating with the Vision API");

    if (annotation.Adult == Likelihood.VeryLikely || annotation.Violence == Likelihood.VeryLikely)
        _logger.LogInformation("Detected {uri} as inappropriate.", gcsUri);
        await BlurImageAsync(data, cancellationToken);
        _logger.LogInformation("Detected {uri} as OK.", gcsUri);

Blurring images

The following function is called when violent or adult content is detected in an uploaded image. The function downloads the offensive image, uses ImageMagick to blur the image, and then uploads the blurred image over the original image.


// Blurs the given file using ImageMagick, and uploads it to another bucket.
const blurImage = async (file, blurredBucketName) => {
  const tempLocalPath = `/tmp/${path.parse(}`;

  // Download file from bucket.
  try {
    await{destination: tempLocalPath});

    console.log(`Downloaded ${} to ${tempLocalPath}.`);
  } catch (err) {
    throw new Error(`File download failed: ${err}`);

  await new Promise((resolve, reject) => {
      .blur(0, 16)
      .write(tempLocalPath, (err, stdout) => {
        if (err) {
          console.error('Failed to blur image.', err);
        } else {
          console.log(`Blurred image: ${}`);

  // Upload result to a different bucket, to avoid re-triggering this function.
  const blurredBucket = storage.bucket(blurredBucketName);

  // Upload the Blurred image back into the bucket.
  const gcsPath = `gs://${blurredBucketName}/${}`;
  try {
    await blurredBucket.upload(tempLocalPath, {destination:});
    console.log(`Uploaded blurred image to: ${gcsPath}`);
  } catch (err) {
    throw new Error(`Unable to upload blurred image to ${gcsPath}: ${err}`);

  // Delete the temporary file.
  return fs.unlink(tempLocalPath);


# Blurs the given file using ImageMagick.
def __blur_image(current_blob):
    file_name =
    _, temp_local_filename = tempfile.mkstemp()

    # Download file from bucket.
    print(f"Image {file_name} was downloaded to {temp_local_filename}.")

    # Blur the image using ImageMagick.
    with Image(filename=temp_local_filename) as image:
        image.resize(*image.size, blur=16, filter="hamming")

    print(f"Image {file_name} was blurred.")

    # Upload result to a second bucket, to avoid re-triggering the function.
    # You could instead re-upload it to the same bucket + tell your function
    # to ignore files marked as blurred (e.g. those with a "blurred" prefix)
    blur_bucket_name = os.getenv("BLURRED_BUCKET_NAME")
    blur_bucket = storage_client.bucket(blur_bucket_name)
    new_blob = blur_bucket.blob(file_name)
    print(f"Blurred image uploaded to: gs://{blur_bucket_name}/{file_name}")

    # Delete the temporary file.


// blur blurs the image stored at gs://inputBucket/name and stores the result in
// gs://outputBucket/name.
func blur(ctx context.Context, inputBucket, outputBucket, name string) error {
	inputBlob := storageClient.Bucket(inputBucket).Object(name)
	r, err := inputBlob.NewReader(ctx)
	if err != nil {
		return fmt.Errorf("NewReader: %v", err)

	outputBlob := storageClient.Bucket(outputBucket).Object(name)
	w := outputBlob.NewWriter(ctx)
	defer w.Close()

	// Use - as input and output to use stdin and stdout.
	cmd := exec.Command("convert", "-", "-blur", "0x8", "-")
	cmd.Stdin = r
	cmd.Stdout = w

	if err := cmd.Run(); err != nil {
		return fmt.Errorf("cmd.Run: %v", err)

	log.Printf("Blurred image uploaded to gs://%s/%s", outputBlob.BucketName(), outputBlob.ObjectName())

	return nil


// Blurs the file described by blobInfo using ImageMagick,
// and uploads it to the blurred bucket.
private static void blur(BlobInfo blobInfo) throws IOException {
  String bucketName = blobInfo.getBucket();
  String fileName = blobInfo.getName();

  // Download image
  Blob blob = storage.get(BlobId.of(bucketName, fileName));
  Path download = Paths.get("/tmp/", fileName);

  // Construct the command.
  Path upload = Paths.get("/tmp/", "blurred-" + fileName);
  List<String> args = List.of("convert", download.toString(), "-blur", "0x8", upload.toString());
  try {
    ProcessBuilder pb = new ProcessBuilder(args);
    Process process = pb.start();
  } catch (Exception e) {"Error: %s", e.getMessage()));

  // Upload image to blurred bucket.
  BlobId blurredBlobId = BlobId.of(BLURRED_BUCKET_NAME, fileName);
  BlobInfo blurredBlobInfo =

  byte[] blurredFile = Files.readAllBytes(upload);
  storage.create(blurredBlobInfo, blurredFile);
      String.format("Blurred image uploaded to: gs://%s/%s", BLURRED_BUCKET_NAME, fileName));

  // Remove images from fileSystem


/// <summary>
/// Downloads the Storage object specified by <paramref name="data"/>,
/// blurs it using ImageMagick, and uploads it to the "blurred" bucket.
/// </summary>
private async Task BlurImageAsync(StorageObjectData data, CancellationToken cancellationToken)
    // Download image
    string originalImageFile = Path.GetTempFileName();
    using (Stream output = File.Create(originalImageFile))
        await _storageClient.DownloadObjectAsync(data.Bucket, data.Name, output, cancellationToken: cancellationToken);

    // Construct the ImageMagick command
    string blurredImageFile = Path.GetTempFileName();
    // Command-line arguments for ImageMagick.
    // Paths are wrapped in quotes in case they contain spaces.
    string arguments = $"\"{originalImageFile}\" -blur 0x8, \"{blurredImageFile}\"";

    // Run the ImageMagick command line tool ("convert").
    Process process = Process.Start("convert", arguments);
    // Process doesn't expose a way of asynchronously waiting for completion.
    // See for examples of how
    // this can be achieved using events, but for the sake of brevity,
    // this sample just waits synchronously.

    // If ImageMagick failed, log the error but complete normally to avoid retrying.
    if (process.ExitCode != 0)
        _logger.LogError("ImageMagick exited with code {exitCode}", process.ExitCode);

    // Upload image to blurred bucket.
    using (Stream input = File.OpenRead(blurredImageFile))
        await _storageClient.UploadObjectAsync(
            s_blurredBucketName, data.Name, data.ContentType, input, cancellationToken: cancellationToken);

    string uri = $"gs://{s_blurredBucketName}/{data.Name}";
    _logger.LogInformation("Blurred image uploaded to: {uri}", uri);

    // Remove images from the file system.

Deploying the function

  1. To deploy your Cloud Function with a storage trigger, run the following command in the directory that contains the sample code (or in the case of Java, the pom.xml file):


    gcloud functions deploy blurOffensiveImages \
    --runtime nodejs10 \
    --trigger-bucket YOUR_INPUT_BUCKET_NAME \
    You can use the following values for the --runtime flag to specify your preferred Node.js version:
    • nodejs10
    • nodejs12
    • nodejs14 (public preview)


    gcloud functions deploy blur_offensive_images \
    --runtime python38 \
    --trigger-bucket YOUR_INPUT_BUCKET_NAME \
    You can use the following values for the --runtime flag to specify your preferred Python version:
    • python37
    • python38
    • python39 (public preview)


    gcloud functions deploy BlurOffensiveImages \
    --runtime go113 \
    --trigger-bucket YOUR_INPUT_BUCKET_NAME \
    You can use the following values for the --runtime flag to specify your preferred Go version:
    • go111 (Deprecated)
    • go113


    gcloud functions deploy java-blur-function \
    --entry-point functions.ImageMagick \
    --runtime java11 \
    --memory 512MB \
    --trigger-bucket YOUR_INPUT_BUCKET_NAME \


    gcloud functions deploy csharp-blur-function \
    --entry-point ImageMagick.Function \
    --runtime dotnet3 \
    --trigger-bucket YOUR_INPUT_BUCKET_NAME \

    where YOUR_INPUT_BUCKET_NAME is the name of the Cloud Storage bucket for uploading images, and YOUR_OUTPUT_BUCKET_NAME is the name of the bucket the blurred images should be saved to.

    The --allow-unauthenticated flag lets you reach the function without authentication. To require authentication, omit the flag.

Uploading an image

  1. Upload an offensive image, such as this image of a flesh-eating zombie:

    gsutil cp zombie.jpg gs://YOUR_INPUT_BUCKET_NAME

    where YOUR_INPUT_BUCKET_NAME is the Cloud Storage bucket you created earlier for uploading images.

  2. Watch the logs to be sure the executions have completed:

    gcloud functions logs read --limit 100
  3. You can view the blurred images in the YOUR_OUTPUT_BUCKET_NAME Cloud Storage bucket you created earlier.

Cleaning up

To avoid incurring charges to your Google Cloud account for the resources used in this tutorial, either delete the project that contains the resources, or keep the project and delete the individual resources.

Deleting the project

The easiest way to eliminate billing is to delete the project that you created for the tutorial.

To delete the project:

  1. In the Cloud Console, go to the Manage resources page.

    Go to Manage resources

  2. In the project list, select the project that you want to delete, and then click Delete.
  3. In the dialog, type the project ID, and then click Shut down to delete the project.

Deleting the Cloud Function

Deleting Cloud Functions does not remove any resources stored in Cloud Storage.

To delete the Cloud Function you deployed in this tutorial, run the following command:


gcloud functions delete blurOffensiveImages 


gcloud functions delete blur_offensive_images 


gcloud functions delete BlurOffensiveImages 


gcloud functions delete java-blur-function 


gcloud functions delete csharp-blur-function 

You can also delete Cloud Functions from the Google Cloud Console.