Detecting Image Properties

The Image Properties feature detects general attributes of the image, such as dominant color.

Detecting Image Properties in a Local Image

Protocol

Refer to the images:annotate API endpoint for complete details.

To perform Image Properties detection, make a POST request and provide the appropriate request body:

POST https://vision.googleapis.com/v1/images:annotate?key=YOUR_API_KEY
{
  "requests": [
    {
      "images": {
        "content": "/9j/7QBEUGhvdG9zaG9...base64-encoded-image-content...fXNWzvDEeYxxxzj/Coa6Bax//Z"
      },
      "features": [
        {
          "type": "IMAGE_PROPERTIES"
        }
      ]
    }
  ]
}

See the AnnotateImageRequest reference documentation for more information on configuring the request body.

If the request is successful, the server returns a 200 OK HTTP status code and the response in JSON format:

{
  "responses": [
    {
      "imagePropertiesAnnotation": {
        "dominantColors": {
          "colors": [
            {
              "color": {
                "red": 69,
                "green": 42,
                "blue": 27
              },
              "score": 0.15197733,
              "pixelFraction": 0.14140345
            },
            {
              "color": {
                "red": 159,
                "green": 193,
                "blue": 252
              },
              "score": 0.12624279,
              "pixelFraction": 0.046971671
            },
            {
              "color": {
                "red": 25,
                "green": 18,
                "blue": 13
              },
              "score": 0.12161674,
              "pixelFraction": 0.15410289
            },
            {
              "color": {
                "red": 120,
                "green": 168,
                "blue": 250
              },
              "score": 0.06179978,
              "pixelFraction": 0.018316509
            },
            {
              "color": {
                "red": 61,
                "green": 46,
                "blue": 28
              },
              "score": 0.068530552,
              "pixelFraction": 0.052263107
            },
            {
              "color": {
                "red": 181,
                "green": 202,
                "blue": 239
              },
              "score": 0.061842542,
              "pixelFraction": 0.030364702
            },
            {
              "color": {
                "red": 131,
                "green": 168,
                "blue": 234
              },
              "score": 0.054366827,
              "pixelFraction": 0.018153695
            },
            {
              "color": {
                "red": 122,
                "green": 162,
                "blue": 249
              },
              "score": 0.039461233,
              "pixelFraction": 0.010827092
            },
            {
              "color": {
                "red": 39,
                "green": 27,
                "blue": 12
              },
              "score": 0.034653772,
              "pixelFraction": 0.02596874
            },
            {
              "color": {
                "red": 51,
                "green": 24,
                "blue": 12
              },
              "score": 0.033614498,
              "pixelFraction": 0.024991859
            }
          ]
        }
      }
    }
  ]
}

C#

For more on installing and creating a Cloud Vision API client, refer to Cloud Vision API Client Libraries.

// Load an image from a local file.
var image = Image.FromFile(filePath);
var client = ImageAnnotatorClient.Create();
var response = client.DetectImageProperties(image);
string header = "Red\tGreen\tBlue\tAlpha\n";
foreach (var color in response.DominantColors.Colors)
{
    Console.Write(header);
    header = "";
    Console.WriteLine("{0}\t{0}\t{0}\t{0}",
        color.Color.Red, color.Color.Green, color.Color.Blue,
        color.Color.Alpha);
}

Go

For more on installing and creating a Cloud Vision API client, refer to Cloud Vision API Client Libraries.

// detectProperties gets image properties from the Vision API for an image at the given file path.
func detectProperties(w io.Writer, file string) error {
	ctx := context.Background()

	client, err := vision.NewClient(ctx)
	if err != nil {
		return err
	}

	f, err := os.Open(file)
	if err != nil {
		return err
	}
	defer f.Close()

	image, err := vision.NewImageFromReader(f)
	if err != nil {
		return err
	}
	props, err := client.DetectImageProps(ctx, image)
	if err != nil {
		return err
	}

	fmt.Fprintln(w, "Dominant colors:")
	for _, quantized := range props.DominantColors {
		color := quantized.Color
		fmt.Fprintf(w, "%2.1f%% - #%02x%02x%02x\n", quantized.PixelFraction*100, color.R&0xff, color.G&0xff, color.B&0xff)
	}

	return nil
}

Java

For more on installing and creating a Cloud Vision API client, refer to Cloud Vision API Client Libraries.

public static void detectProperties(String filePath, PrintStream out) throws IOException {
  List<AnnotateImageRequest> requests = new ArrayList<>();

  ByteString imgBytes = ByteString.readFrom(new FileInputStream(filePath));

  Image img = Image.newBuilder().setContent(imgBytes).build();
  Feature feat = Feature.newBuilder().setType(Type.IMAGE_PROPERTIES).build();
  AnnotateImageRequest request =
      AnnotateImageRequest.newBuilder().addFeatures(feat).setImage(img).build();
  requests.add(request);

  BatchAnnotateImagesResponse response =
      ImageAnnotatorClient.create().batchAnnotateImages(requests);
  List<AnnotateImageResponse> responses = response.getResponsesList();

  for (AnnotateImageResponse res : responses) {
    if (res.hasError()) {
      out.printf("Error: %s\n", res.getError().getMessage());
      return;
    }

    // For full list of available annotations, see http://g.co/cloud/vision/docs
    DominantColorsAnnotation colors = res.getImagePropertiesAnnotation().getDominantColors();
    for (ColorInfo color : colors.getColorsList()) {
      out.printf(
          "fraction: %f\nr: %f, g: %f, b: %f\n",
          color.getPixelFraction(),
          color.getColor().getRed(),
          color.getColor().getGreen(),
          color.getColor().getBlue());
    }
  }
}

Node.js

For more on installing and creating a Cloud Vision API client, refer to Cloud Vision API Client Libraries.

// Imports the Google Cloud client library
const Vision = require('@google-cloud/vision');

// Instantiates a client
const vision = Vision();

// The path to the local image file, e.g. "/path/to/image.png"
// const fileName = '/path/to/image.png';

// Performs image property detection on the local file
vision.detectProperties(fileName)
  .then((results) => {
    const properties = results[0];

    console.log('Colors:');
    properties.colors.forEach((color) => console.log(color));
  });

PHP

For more on installing and creating a Cloud Vision API client, refer to Cloud Vision API Client Libraries.

use Google\Cloud\Vision\VisionClient;

// $projectId = 'YOUR_PROJECT_ID';
// $path = 'path/to/your/image.jpg'

$vision = new VisionClient([
    'projectId' => $projectId,
]);
$image = $vision->image(file_get_contents($path), [
    'IMAGE_PROPERTIES'
]);
$result = $vision->annotate($image);
print("Properties:\n");
foreach ($result->imageProperties()->colors() as $color) {
    $rgb = $color['color'];
    printf("red:%s\n", $rgb['red']);
    printf("green:%s\n", $rgb['green']);
    printf("blue:%s\n\n", $rgb['blue']);
}

Python

For more on installing and creating a Cloud Vision API client, refer to Cloud Vision API Client Libraries.

def detect_properties(path):
    """Detects image properties in the file."""
    vision_client = vision.Client()

    with io.open(path, 'rb') as image_file:
        content = image_file.read()

    image = vision_client.image(content=content)

    props = image.detect_properties()
    print('Properties:')

    for color in props.colors:
        print('fraction: {}'.format(color.pixel_fraction))
        print('\tr: {}'.format(color.color.red))
        print('\tg: {}'.format(color.color.green))
        print('\tb: {}'.format(color.color.blue))
        print('\ta: {}'.format(color.color.alpha))

Ruby

For more on installing and creating a Cloud Vision API client, refer to Cloud Vision API Client Libraries.

# project_id = "Your Google Cloud project ID"
# image_path = "Path to local image file, eg. './image.png'"

require "google/cloud/vision"

vision = Google::Cloud::Vision.new project: project_id
image  = vision.image image_path

image.properties.colors.each do |color|
  puts "Color #{color.red}, #{color.green}, #{color.blue}"
end

Detecting Image Properties in a remote image

For your convenience, the Cloud Vision API can perform Image Properties detection directly on an image file located in Google Cloud Storage or on the Web without the need to send the contents of the image file in the body of your request.

Protocol

Refer to the images:annotate API endpoint for complete details.

To perform Image Properties detection, make a POST request and provide the appropriate request body:

POST https://vision.googleapis.com/v1/images:annotate?key=YOUR_API_KEY
{
  "requests": [
    {
      "images": {
        "source": {
          "gcsImageUri": "gs://YOUR_BUCKET_NAME/YOUR_FILE_NAME"
        }
      },
      "features": [
        {
          "type": "IMAGE_PROPERTIES"
        }
      ]
    }
  ]
}

See the AnnotateImageRequest reference documentation for more information on configuring the request body.

If the request is successful, the server returns a 200 OK HTTP status code and the response in JSON format:

{
  "responses": [
    {
      "imagePropertiesAnnotation": {
        "dominantColors": {
          "colors": [
            {
              "color": {
                "red": 69,
                "green": 42,
                "blue": 27
              },
              "score": 0.15197733,
              "pixelFraction": 0.14140345
            },
            {
              "color": {
                "red": 159,
                "green": 193,
                "blue": 252
              },
              "score": 0.12624279,
              "pixelFraction": 0.046971671
            },
            {
              "color": {
                "red": 25,
                "green": 18,
                "blue": 13
              },
              "score": 0.12161674,
              "pixelFraction": 0.15410289
            },
            {
              "color": {
                "red": 120,
                "green": 168,
                "blue": 250
              },
              "score": 0.06179978,
              "pixelFraction": 0.018316509
            },
            {
              "color": {
                "red": 61,
                "green": 46,
                "blue": 28
              },
              "score": 0.068530552,
              "pixelFraction": 0.052263107
            },
            {
              "color": {
                "red": 181,
                "green": 202,
                "blue": 239
              },
              "score": 0.061842542,
              "pixelFraction": 0.030364702
            },
            {
              "color": {
                "red": 131,
                "green": 168,
                "blue": 234
              },
              "score": 0.054366827,
              "pixelFraction": 0.018153695
            },
            {
              "color": {
                "red": 122,
                "green": 162,
                "blue": 249
              },
              "score": 0.039461233,
              "pixelFraction": 0.010827092
            },
            {
              "color": {
                "red": 39,
                "green": 27,
                "blue": 12
              },
              "score": 0.034653772,
              "pixelFraction": 0.02596874
            },
            {
              "color": {
                "red": 51,
                "green": 24,
                "blue": 12
              },
              "score": 0.033614498,
              "pixelFraction": 0.024991859
            }
          ]
        }
      }
    }
  ]
}

C#

For more on installing and creating a Cloud Vision API client, refer to Cloud Vision API Client Libraries.

// Specify a Google Cloud Storage uri for the image.
var image = Image.FromUri(uri);
var client = ImageAnnotatorClient.Create();
var response = client.DetectImageProperties(image);
string header = "Red\tGreen\tBlue\tAlpha\n";
foreach (var color in response.DominantColors.Colors)
{
    Console.Write(header);
    header = "";
    Console.WriteLine("{0}\t{0}\t{0}\t{0}",
        color.Color.Red, color.Color.Green, color.Color.Blue,
        color.Color.Alpha);
}

Go

For more on installing and creating a Cloud Vision API client, refer to Cloud Vision API Client Libraries.

// detectProperties gets image properties from the Vision API for an image at the given file path.
func detectPropertiesURI(w io.Writer, file string) error {
	ctx := context.Background()

	client, err := vision.NewClient(ctx)
	if err != nil {
		return err
	}

	image := vision.NewImageFromURI(file)
	props, err := client.DetectImageProps(ctx, image)
	if err != nil {
		return err
	}

	fmt.Fprintln(w, "Dominant colors:")
	for _, quantized := range props.DominantColors {
		color := quantized.Color
		fmt.Fprintf(w, "%2.1f%% - #%02x%02x%02x\n", quantized.PixelFraction*100, color.R&0xff, color.G&0xff, color.B&0xff)
	}

	return nil
}

Java

For more on installing and creating a Cloud Vision API client, refer to Cloud Vision API Client Libraries.

public static void detectPropertiesGcs(String gcsPath, PrintStream out) throws IOException {
  List<AnnotateImageRequest> requests = new ArrayList<>();

  ImageSource imgSource = ImageSource.newBuilder().setGcsImageUri(gcsPath).build();
  Image img = Image.newBuilder().setSource(imgSource).build();
  Feature feat = Feature.newBuilder().setType(Type.IMAGE_PROPERTIES).build();
  AnnotateImageRequest request =
      AnnotateImageRequest.newBuilder().addFeatures(feat).setImage(img).build();
  requests.add(request);

  BatchAnnotateImagesResponse response =
      ImageAnnotatorClient.create().batchAnnotateImages(requests);
  List<AnnotateImageResponse> responses = response.getResponsesList();

  for (AnnotateImageResponse res : responses) {
    if (res.hasError()) {
      out.printf("Error: %s\n", res.getError().getMessage());
      return;
    }

    // For full list of available annotations, see http://g.co/cloud/vision/docs
    DominantColorsAnnotation colors = res.getImagePropertiesAnnotation().getDominantColors();
    for (ColorInfo color : colors.getColorsList()) {
      out.printf(
          "fraction: %f\nr: %f, g: %f, b: %f\n",
          color.getPixelFraction(),
          color.getColor().getRed(),
          color.getColor().getGreen(),
          color.getColor().getBlue());
    }
  }
}

Node.js

For more on installing and creating a Cloud Vision API client, refer to Cloud Vision API Client Libraries.

// Imports the Google Cloud client libraries
const Storage = require('@google-cloud/storage');
const Vision = require('@google-cloud/vision');

// Instantiates clients
const storage = Storage();
const vision = Vision();

// The name of the bucket where the file resides, e.g. "my-bucket"
// const bucketName = 'my-bucket';

// The path to the file within the bucket, e.g. "path/to/image.png"
// const fileName = 'path/to/image.png';

// Performs image property detection on the remote file
vision.detectProperties(storage.bucket(bucketName).file(fileName))
  .then((results) => {
    const properties = results[0];

    console.log('Colors:');
    properties.colors.forEach((color) => console.log(color));
  });

PHP

For more on installing and creating a Cloud Vision API client, refer to Cloud Vision API Client Libraries.

use Google\Cloud\ServiceBuilder;

// $projectId = 'YOUR_PROJECT_ID';
// $bucketName = 'your-bucket-name'
// $objectName = 'your-object-name'

$builder = new ServiceBuilder([
    'projectId' => $projectId,
]);
$vision = $builder->vision();
$storage = $builder->storage();

// fetch the storage object and annotate the image
$object = $storage->bucket($bucketName)->object($objectName);
$image = $vision->image($object, ['IMAGE_PROPERTIES']);
$result = $vision->annotate($image);

// print the response
print("Properties:\n");
foreach ($result->imageProperties()->colors() as $color) {
    $rgb = $color['color'];
    printf("red:%s\n", $rgb['red']);
    printf("green:%s\n", $rgb['green']);
    printf("blue:%s\n\n", $rgb['blue']);
}

Python

For more on installing and creating a Cloud Vision API client, refer to Cloud Vision API Client Libraries.

def detect_properties_uri(uri):
    """Detects image properties in the file located in Google Cloud Storage or
    on the Web."""
    vision_client = vision.Client()
    image = vision_client.image(source_uri=uri)

    props = image.detect_properties()
    print('Properties:')

    for color in props.colors:
        print('frac: {}'.format(color.pixel_fraction))
        print('\tr: {}'.format(color.color.red))
        print('\tg: {}'.format(color.color.green))
        print('\tb: {}'.format(color.color.blue))
        print('\ta: {}'.format(color.color.alpha))

Ruby

For more on installing and creating a Cloud Vision API client, refer to Cloud Vision API Client Libraries.

# project_id = "Your Google Cloud project ID"
# image_path = "Google Cloud Storage URI, eg. 'gs://my-bucket/image.png'"

require "google/cloud/vision"

vision = Google::Cloud::Vision.new project: project_id
image  = vision.image image_path

image.properties.colors.each do |color|
  puts "Color #{color.red}, #{color.green}, #{color.blue}"
end

Send feedback about...

Google Cloud Vision API Documentation