Running Crop Hints

Crop Hints suggests vertices for a crop region on an image.

Run Crop Hints on a local image

Protocol

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

To run Crop Hints, make a POST request and provide the appropriate request body:

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

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": [
    {
      "cropHintsAnnotation": {
        "cropHints": [
          {
            "boundingPoly": {
              "vertices": [
                {},
                {
                  "x": 280
                },
                {
                  "x": 280,
                  "y": 43
                },
                {
                  "y": 43
                }
              ]
            },
            "confidence": 0.79999995,
            "importanceFraction": 1
          }
        ]
      }
    }
  ]
}

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();
CropHintsAnnotation annotation = client.DetectCropHints(image);
foreach (CropHint hint in annotation.CropHints)
{
    Console.WriteLine("Confidence: {0}", hint.Confidence);
    Console.WriteLine("ImportanceFraction: {0}", hint.ImportanceFraction);
    Console.WriteLine("Bounding Polygon:");
    foreach (Vertex vertex in hint.BoundingPoly.Vertices)
    {
        Console.WriteLine("\tX:\t{0}\tY:\t{1}", vertex.X, vertex.Y);
    }
}

Go

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

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

	client, err := vision.NewImageAnnotatorClient(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
	}
	res, err := client.CropHints(ctx, image, nil)
	if err != nil {
		return err
	}

	fmt.Fprintln(w, "Crop hints:")
	for _, hint := range res.CropHints {
		for _, v := range hint.BoundingPoly.Vertices {
			fmt.Fprintf(w, "(%d,%d)\n", v.X, v.Y)
		}
	}

	return nil
}

Java

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

public static void detectCropHints(String filePath, PrintStream out) throws Exception,
    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.CROP_HINTS).build();
  AnnotateImageRequest request =
      AnnotateImageRequest.newBuilder().addFeatures(feat).setImage(img).build();
  requests.add(request);

  try (ImageAnnotatorClient client = ImageAnnotatorClient.create()) {
    BatchAnnotateImagesResponse response = client.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
      CropHintsAnnotation annotation = res.getCropHintsAnnotation();
      for (CropHint hint : annotation.getCropHintsList()) {
        out.println(hint.getBoundingPoly());
      }
    }
  }
}

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 = 'my-file.jpg';

// Find crop hints for the local file
vision.cropHints({
  source: {filename: fileName},
  options: {aspect_ratios: 0.25} })
  .then((results) => {
    const cropHints = results[0].cropHintsAnnotation;

    cropHints.cropHints.forEach((hintBounds, hintIdx) => {
      console.log(`Crop Hint ${hintIdx}:`);
      hintBounds.boundingPoly.vertices.forEach((bound, boundIdx) => {
        console.log(`  Bound ${boundIdx}: (${bound.x}, ${bound.y})`);
      });
    });
  })
  .catch((err) => {
    console.error('ERROR:', err);
  });

PHP

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

namespace Google\Cloud\Samples\Vision;

use Google\Cloud\Vision\VisionClient;

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

function detect_crop_hints($projectId, $path)
{
    $vision = new VisionClient([
        'projectId' => $projectId,
    ]);

    # Annotate the image
    $image = $vision->image(file_get_contents($path), ['CROP_HINTS']);
    $annotation = $vision->annotate($image);

    # Print the crop hints from the annotation
    printf("Crop Hints:\n");
    foreach ((array) $annotation->cropHints() as $hint) {
        $boundingPoly = $hint->boundingPoly();
        $vertices = $boundingPoly['vertices'];
        foreach ((array) $vertices as $vertice) {
            if (!isset($vertice['x'])) {
                $vertice['x'] = 0;
            }
            if (!isset($vertice['y'])) {
                $vertice['y'] = 0;
            }
            printf('X: %s Y: %s' . PHP_EOL, $vertice['x'], $vertice['y']);
        }
    }
}

Python

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

def detect_crop_hints(path):
    """Detects crop hints in an image."""
    client = vision.ImageAnnotatorClient()

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

    crop_hints_params = types.CropHintsParams(aspect_ratios=[1.77])
    image_context = types.ImageContext(crop_hints_params=crop_hints_params)

    response = client.crop_hints(image=image, image_context=image_context)
    hints = response.crop_hints_annotation.crop_hints

    for n, hint in enumerate(hints):
        print('\nCrop Hint: {}'.format(n))

        vertices = (['({},{})'.format(vertex.x, vertex.y)
                    for vertex in hint.bounding_poly.vertices])

        print('bounds: {}'.format(','.join(vertices)))

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

crop_hints = image.crop_hints

crop_hints.each do |crop_hint|
  puts "Crop hint bounds:"
  crop_hint.bounds.each do |bound|
    puts "#{bound.x}, #{bound.y}"
  end
end

Running Crop Hints on a remote image

For your convenience, the Cloud Vision API can run Crop Hints 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 run Crop Hints, make a POST request and provide the appropriate request body:

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

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": [
   {
      "cropHintsAnnotation": {
        "cropHints": [
          {
            "boundingPoly": {
              "vertices": [
                {},
                {
                  "x": 280
                },
                {
                  "x": 280,
                  "y": 43
                },
                {
                  "y": 43
                }
              ]
            },
            "confidence": 0.79999995,
            "importanceFraction": 1
          }
        ]
      }
    }
  ]
}

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
// or a publicly accessible HTTP or HTTPS uri.
var image = Image.FromUri(uri);
var client = ImageAnnotatorClient.Create();
CropHintsAnnotation annotation = client.DetectCropHints(image);
foreach (CropHint hint in annotation.CropHints)
{
    Console.WriteLine("Confidence: {0}", hint.Confidence);
    Console.WriteLine("ImportanceFraction: {0}", hint.ImportanceFraction);
    Console.WriteLine("Bounding Polygon:");
    foreach (Vertex vertex in hint.BoundingPoly.Vertices)
    {
        Console.WriteLine("\tX:\t{0}\tY:\t{1}", vertex.X, vertex.Y);
    }
}

Java

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

public static void detectCropHintsGcs(String gcsPath, PrintStream out) throws Exception,
    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.CROP_HINTS).build();
  AnnotateImageRequest request =
      AnnotateImageRequest.newBuilder().addFeatures(feat).setImage(img).build();
  requests.add(request);

  try (ImageAnnotatorClient client = ImageAnnotatorClient.create()) {
    BatchAnnotateImagesResponse response = client.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
      CropHintsAnnotation annotation = res.getCropHintsAnnotation();
      for (CropHint hint : annotation.getCropHintsList()) {
        out.println(hint.getBoundingPoly());
      }
    }
  }
}

Go

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

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

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

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

	fmt.Fprintln(w, "Crop hints:")
	for _, hint := range res.CropHints {
		for _, v := range hint.BoundingPoly.Vertices {
			fmt.Fprintf(w, "(%d,%d)\n", v.X, v.Y)
		}
	}

	return nil
}

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 Vision = require('@google-cloud/vision');

// Instantiates clients
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 = 'my-file.jpg';

const gcsPath = `gs://${bucketName}/${fileName}`;

// Find crop hints for the remote file
vision.cropHints({source: {imageUri: gcsPath}})
  .then((results) => {
    const cropHints = results[0].cropHintsAnnotation;

    cropHints.cropHints.forEach((hintBounds, hintIdx) => {
      console.log(`Crop Hint ${hintIdx}:`);
      hintBounds.boundingPoly.vertices.forEach((bound, boundIdx) => {
        console.log(`  Bound ${boundIdx}: (${bound.x}, ${bound.y})`);
      });
    });
  })
  .catch((err) => {
    console.error('ERROR:', err);
  });

PHP

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

namespace Google\Cloud\Samples\Vision;

use Google\Cloud\Vision\VisionClient;
use Google\Cloud\Storage\StorageClient;

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

function detect_crop_hints_gcs($projectId, $bucketName, $objectName)
{
    $vision = new VisionClient([
        'projectId' => $projectId,
    ]);
    $storage = new StorageClient([
        'projectId' => $projectId,
    ]);

    # Fetch the storage object and annotate the image
    $object = $storage->bucket($bucketName)->object($objectName);
    $image = $vision->image($object, ['CROP_HINTS']);
    $annotation = $vision->annotate($image);

    # Print the crop hints from the annotation
    printf("Crop Hints:\n");
    foreach ((array) $annotation->cropHints() as $hint) {
        $boundingPoly = $hint->boundingPoly();
        $vertices = $boundingPoly['vertices'];
        foreach ((array) $vertices as $vertice) {
            if (!isset($vertice['x'])) {
                $vertice['x'] = 0;
            }
            if (!isset($vertice['y'])) {
                $vertice['y'] = 0;
            }
            printf('X: %s Y: %s' . PHP_EOL, $vertice['x'], $vertice['y']);
        }
    }
}

Python

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

def detect_crop_hints_uri(uri):
    """Detects crop hints in the file located in Google Cloud Storage."""
    client = vision.ImageAnnotatorClient()
    image = types.Image()
    image.source.image_uri = uri

    crop_hints_params = types.CropHintsParams(aspect_ratios=[1.77])
    image_context = types.ImageContext(crop_hints_params=crop_hints_params)

    response = client.crop_hints(image=image, image_context=image_context)
    hints = response.crop_hints_annotation.crop_hints

    for n, hint in enumerate(hints):
        print('\nCrop Hint: {}'.format(n))

        vertices = (['({},{})'.format(vertex.x, vertex.y)
                    for vertex in hint.bounding_poly.vertices])

        print('bounds: {}'.format(','.join(vertices)))

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

crop_hints = image.crop_hints

crop_hints.each do |crop_hint|
  puts "Crop hint bounds:"
  crop_hint.bounds.each do |bound|
    puts "#{bound.x}, #{bound.y}"
  end
end

Send feedback about...

Google Cloud Vision API Documentation