剪裁提示会确定图片的建议剪裁区域顶点。

已应用剪裁提示(比例为 2:1):

剪裁提示检测请求
设置您的 Google Cloud 项目和身份验证
如果您尚未创建 Google Cloud 项目,请立即创建。展开本部分可查看相关说明。
- 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.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Verify that billing is enabled for your Google Cloud project.
-
Enable the Vision API.
-
Install the Google Cloud CLI.
-
如果您使用的是外部身份提供方 (IdP),则必须先使用联合身份登录 gcloud CLI。
-
如需初始化 gcloud CLI,请运行以下命令:
gcloud init
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Verify that billing is enabled for your Google Cloud project.
-
Enable the Vision API.
-
Install the Google Cloud CLI.
-
如果您使用的是外部身份提供方 (IdP),则必须先使用联合身份登录 gcloud CLI。
-
如需初始化 gcloud CLI,请运行以下命令:
gcloud init
- BASE64_ENCODED_IMAGE:二进制图片数据的 base64 表示(ASCII 字符串)。此字符串应类似于以下字符串:
/9j/4QAYRXhpZgAA...9tAVx/zDQDlGxn//2Q==
- PROJECT_ID:您的 Google Cloud 项目 ID。
cropHintsParams.aspectRatios
- 一个浮点数,对应于图片的指定比例(宽高比)。您最多可以提供 16 个剪裁比例。- CLOUD_STORAGE_IMAGE_URI:Cloud Storage 存储桶中有效图片文件的路径。您必须至少拥有该文件的读取权限。
示例:
gs://cloud-samples-data/vision/crop_hints/bubble.jpeg
- PROJECT_ID:您的 Google Cloud 项目 ID。
cropHintsParams.aspectRatios
- 一个浮点数,对应于图片的指定比例(宽高比)。您最多可以提供 16 个剪裁比例。
检测本地图片中的剪裁提示
您可以使用 Vision API 对本地图片文件执行特征检测。
对于 REST 请求,请将图片文件的内容作为 base64 编码的字符串在请求正文中发送。
对于 gcloud
和客户端库请求,请在请求中指定本地图片的路径。
REST
在使用任何请求数据之前,请先进行以下替换:
特定于字段的注意事项:
HTTP 方法和网址:
POST https://vision.googleapis.com/v1/images:annotate
请求 JSON 正文:
{ "requests": [ { "image": { "content": "BASE64_ENCODED_IMAGE" }, "features": [ { "type": "CROP_HINTS" } ], "imageContext": { "cropHintsParams": { "aspectRatios": [ 2.0 ] } } } ] }
如需发送请求,请选择以下方式之一:
curl
将请求正文保存在名为 request.json
的文件中,然后执行以下命令:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://vision.googleapis.com/v1/images:annotate"
PowerShell
将请求正文保存在名为 request.json
的文件中,然后执行以下命令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://vision.googleapis.com/v1/images:annotate" | Select-Object -Expand Content
如果请求成功,服务器将返回一个 200 OK
HTTP 状态代码以及 JSON 格式的响应。
响应:
{ "responses": [ { "cropHintsAnnotation": { "cropHints": [ { "boundingPoly": { "vertices": [ { "y": 520 }, { "x": 2369, "y": 520 }, { "x": 2369, "y": 1729 }, { "y": 1729 } ] }, "confidence": 0.79999995, "importanceFraction": 0.66999996 } ] } } ] }
Go
试用此示例之前,请按照《Vision 快速入门:使用客户端库》中的 Go 设置说明进行操作。 如需了解详情,请参阅 Vision Go API 参考文档。
如需向 Vision 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为本地开发环境设置身份验证。
// 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
在试用此示例之前,请按照Vision API 快速入门:使用客户端库中的 Java 设置说明进行操作。如需了解详情,请参阅 Vision API Java 参考文档。
import com.google.cloud.vision.v1.AnnotateImageRequest;
import com.google.cloud.vision.v1.AnnotateImageResponse;
import com.google.cloud.vision.v1.BatchAnnotateImagesResponse;
import com.google.cloud.vision.v1.CropHint;
import com.google.cloud.vision.v1.CropHintsAnnotation;
import com.google.cloud.vision.v1.Feature;
import com.google.cloud.vision.v1.Image;
import com.google.cloud.vision.v1.ImageAnnotatorClient;
import com.google.protobuf.ByteString;
import java.io.FileInputStream;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
public class DetectCropHints {
public static void detectCropHints() throws IOException {
// TODO(developer): Replace these variables before running the sample.
String filePath = "path/to/your/image/file.jpg";
detectCropHints(filePath);
}
// Suggests a region to crop to for a local file.
public static void detectCropHints(String filePath) 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(Feature.Type.CROP_HINTS).build();
AnnotateImageRequest request =
AnnotateImageRequest.newBuilder().addFeatures(feat).setImage(img).build();
requests.add(request);
// Initialize client that will be used to send requests. This client only needs to be created
// once, and can be reused for multiple requests. After completing all of your requests, call
// the "close" method on the client to safely clean up any remaining background resources.
try (ImageAnnotatorClient client = ImageAnnotatorClient.create()) {
BatchAnnotateImagesResponse response = client.batchAnnotateImages(requests);
List<AnnotateImageResponse> responses = response.getResponsesList();
for (AnnotateImageResponse res : responses) {
if (res.hasError()) {
System.out.format("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()) {
System.out.println(hint.getBoundingPoly());
}
}
}
}
}
Node.js
试用此示例之前,请按照《Vision 快速入门:使用客户端库》中的 Node.js 设置说明进行操作。 如需了解详情,请参阅 Vision Node.js API 参考文档。
如需向 Vision 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为本地开发环境设置身份验证。
// Imports the Google Cloud client library
const vision = require('@google-cloud/vision');
// Creates a client
const client = new vision.ImageAnnotatorClient();
/**
* TODO(developer): Uncomment the following line before running the sample.
*/
// const fileName = 'Local image file, e.g. /path/to/image.png';
// Find crop hints for the local file
const [result] = await client.cropHints(fileName);
const cropHints = result.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})`);
});
});
Python
试用此示例之前,请按照《Vision 快速入门:使用客户端库》中的 Python 设置说明进行操作。 如需了解详情,请参阅 Vision Python API 参考文档。
如需向 Vision 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为本地开发环境设置身份验证。
def detect_crop_hints(path):
"""Detects crop hints in an image."""
from google.cloud import vision
client = vision.ImageAnnotatorClient()
with open(path, "rb") as image_file:
content = image_file.read()
image = vision.Image(content=content)
crop_hints_params = vision.CropHintsParams(aspect_ratios=[1.77])
image_context = vision.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(f"\nCrop Hint: {n}")
vertices = [
f"({vertex.x},{vertex.y})" for vertex in hint.bounding_poly.vertices
]
print("bounds: {}".format(",".join(vertices)))
if response.error.message:
raise Exception(
"{}\nFor more info on error messages, check: "
"https://cloud.google.com/apis/design/errors".format(response.error.message)
)
其他语言
C#: 请按照客户端库页面上的 C# 设置说明操作,然后访问 .NET 版 Vision 参考文档。
PHP: 请按照客户端库页面上的 PHP 设置说明操作,然后访问 PHP 版 Vision 参考文档。
Ruby 版: 请按照客户端库页面上的 Ruby 设置说明操作,然后访问 Ruby 版 Vision 参考文档。
检测远程图片中的剪裁提示
您可以使用 Vision API 对位于 Cloud Storage 或网络中的远程图片文件执行特征检测。如需发送远程文件请求,请在请求正文中指定文件的网址或 Cloud Storage URI。
REST
在使用任何请求数据之前,请先进行以下替换:
特定于字段的注意事项:
HTTP 方法和网址:
POST https://vision.googleapis.com/v1/images:annotate
请求 JSON 正文:
{ "requests": [ { "image": { "source": { "gcsImageUri": "CLOUD_STORAGE_IMAGE_URI" } }, "features": [ { "type": "CROP_HINTS" } ], "imageContext": { "cropHintsParams": { "aspectRatios": [ 2.0 ] } } } ] }
如需发送请求,请选择以下方式之一:
curl
将请求正文保存在名为 request.json
的文件中,然后执行以下命令:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://vision.googleapis.com/v1/images:annotate"
PowerShell
将请求正文保存在名为 request.json
的文件中,然后执行以下命令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://vision.googleapis.com/v1/images:annotate" | Select-Object -Expand Content
如果请求成功,服务器将返回一个 200 OK
HTTP 状态代码以及 JSON 格式的响应。
响应:
{ "responses": [ { "cropHintsAnnotation": { "cropHints": [ { "boundingPoly": { "vertices": [ { "y": 520 }, { "x": 2369, "y": 520 }, { "x": 2369, "y": 1729 }, { "y": 1729 } ] }, "confidence": 0.79999995, "importanceFraction": 0.66999996 } ] } } ] }
Java
试用此示例之前,请按照《Vision 快速入门:使用客户端库》中的 Java 设置说明进行操作。 如需了解详情,请参阅 Vision Java API 参考文档。
如需向 Vision 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为本地开发环境设置身份验证。
import com.google.cloud.vision.v1.AnnotateImageRequest;
import com.google.cloud.vision.v1.AnnotateImageResponse;
import com.google.cloud.vision.v1.BatchAnnotateImagesResponse;
import com.google.cloud.vision.v1.CropHint;
import com.google.cloud.vision.v1.CropHintsAnnotation;
import com.google.cloud.vision.v1.Feature;
import com.google.cloud.vision.v1.Image;
import com.google.cloud.vision.v1.ImageAnnotatorClient;
import com.google.cloud.vision.v1.ImageSource;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
public class DetectCropHintsGcs {
public static void detectCropHintsGcs() throws IOException {
// TODO(developer): Replace these variables before running the sample.
String filePath = "gs://your-gcs-bucket/path/to/image/file.jpg";
detectCropHintsGcs(filePath);
}
// Suggests a region to crop to for a remote file on Google Cloud Storage.
public static void detectCropHintsGcs(String gcsPath) 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(Feature.Type.CROP_HINTS).build();
AnnotateImageRequest request =
AnnotateImageRequest.newBuilder().addFeatures(feat).setImage(img).build();
requests.add(request);
// Initialize client that will be used to send requests. This client only needs to be created
// once, and can be reused for multiple requests. After completing all of your requests, call
// the "close" method on the client to safely clean up any remaining background resources.
try (ImageAnnotatorClient client = ImageAnnotatorClient.create()) {
BatchAnnotateImagesResponse response = client.batchAnnotateImages(requests);
List<AnnotateImageResponse> responses = response.getResponsesList();
for (AnnotateImageResponse res : responses) {
if (res.hasError()) {
System.out.format("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()) {
System.out.println(hint.getBoundingPoly());
}
}
}
}
}
Go
试用此示例之前,请按照《Vision 快速入门:使用客户端库》中的 Go 设置说明进行操作。 如需了解详情,请参阅 Vision Go API 参考文档。
如需向 Vision 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为本地开发环境设置身份验证。
// 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
试用此示例之前,请按照《Vision 快速入门:使用客户端库》中的 Node.js 设置说明进行操作。 如需了解详情,请参阅 Vision Node.js API 参考文档。
如需向 Vision 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为本地开发环境设置身份验证。
// Imports the Google Cloud client libraries
const vision = require('@google-cloud/vision');
// Creates a client
const client = new vision.ImageAnnotatorClient();
/**
* TODO(developer): Uncomment the following lines before running the sample.
*/
// const bucketName = 'Bucket where the file resides, e.g. my-bucket';
// const fileName = 'Path to file within bucket, e.g. path/to/image.png';
// Find crop hints for the remote file
const [result] = await client.cropHints(`gs://${bucketName}/${fileName}`);
const cropHints = result.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})`);
});
});
Python
试用此示例之前,请按照《Vision 快速入门:使用客户端库》中的 Python 设置说明进行操作。 如需了解详情,请参阅 Vision Python API 参考文档。
如需向 Vision 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为本地开发环境设置身份验证。
def detect_crop_hints_uri(uri):
"""Detects crop hints in the file located in Google Cloud Storage."""
from google.cloud import vision
client = vision.ImageAnnotatorClient()
image = vision.Image()
image.source.image_uri = uri
crop_hints_params = vision.CropHintsParams(aspect_ratios=[1.77])
image_context = vision.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(f"\nCrop Hint: {n}")
vertices = [
f"({vertex.x},{vertex.y})" for vertex in hint.bounding_poly.vertices
]
print("bounds: {}".format(",".join(vertices)))
if response.error.message:
raise Exception(
"{}\nFor more info on error messages, check: "
"https://cloud.google.com/apis/design/errors".format(response.error.message)
)
gcloud
如需执行文本检测,请使用 gcloud ml vision suggest-crop
命令,如以下示例所示:
gcloud ml vision suggest-crop gs://cloud-samples-data/vision/crop_hints/bubble.jpeg
其他语言
C#: 请按照客户端库页面上的 C# 设置说明操作,然后访问 .NET 版 Vision 参考文档。
PHP: 请按照客户端库页面上的 PHP 设置说明操作,然后访问 PHP 版 Vision 参考文档。
Ruby 版: 请按照客户端库页面上的 Ruby 设置说明操作,然后访问 Ruby 版 Vision 参考文档。
试用
请尝试以下剪裁提示检测。您可以使用已指定的图片 (gs://cloud-samples-data/vision/crop_hints/bubble.jpeg
) 或指定您自己的图片。选择执行来发送请求。

请求正文:
{ "requests": [ { "image": { "source": { "gcsImageUri": "gs://cloud-samples-data/vision/crop_hints/bubble.jpeg" } }, "features": [ { "type": "CROP_HINTS" } ], "imageContext": { "cropHintsParams": { "aspectRatios": [ 2 ] } } } ] }