api_op_DetectLabels.go

// Code generated by smithy-go-codegen DO NOT EDIT.

package rekognition

import (
	"context"
	awsmiddleware "github.com/aws/aws-sdk-go-v2/aws/middleware"
	"github.com/aws/aws-sdk-go-v2/aws/retry"
	"github.com/aws/aws-sdk-go-v2/aws/signer/v4"
	"github.com/aws/aws-sdk-go-v2/service/rekognition/types"
	smithy "github.com/awslabs/smithy-go"
	"github.com/awslabs/smithy-go/middleware"
	smithyhttp "github.com/awslabs/smithy-go/transport/http"
)

// Detects instances of real-world entities within an image (JPEG or PNG) provided
// as input. This includes objects like flower, tree, and table; events like
// wedding, graduation, and birthday party; and concepts like landscape, evening,
// and nature.  <p>For an example, see Analyzing Images Stored in an Amazon S3
// Bucket in the Amazon Rekognition Developer Guide.</p> <note> <p>
// <code>DetectLabels</code> does not support the detection of activities. However,
// activity detection is supported for label detection in videos. For more
// information, see StartLabelDetection in the Amazon Rekognition Developer
// Guide.</p> </note> <p>You pass the input image as base64-encoded image bytes or
// as a reference to an image in an Amazon S3 bucket. If you use the AWS CLI to
// call Amazon Rekognition operations, passing image bytes is not supported. The
// image must be either a PNG or JPEG formatted file. </p> <p> For each object,
// scene, and concept the API returns one or more labels. Each label provides the
// object name, and the level of confidence that the image contains the object. For
// example, suppose the input image has a lighthouse, the sea, and a rock. The
// response includes all three labels, one for each object. </p> <p> <code>{Name:
// lighthouse, Confidence: 98.4629}</code> </p> <p> <code>{Name: rock,Confidence:
// 79.2097}</code> </p> <p> <code> {Name: sea,Confidence: 75.061}</code> </p> <p>In
// the preceding example, the operation returns one label for each of the three
// objects. The operation can also return multiple labels for the same object in
// the image. For example, if the input image shows a flower (for example, a
// tulip), the operation might return the following three labels. </p> <p>
// <code>{Name: flower,Confidence: 99.0562}</code> </p> <p> <code>{Name:
// plant,Confidence: 99.0562}</code> </p> <p> <code>{Name: tulip,Confidence:
// 99.0562}</code> </p> <p>In this example, the detection algorithm more precisely
// identifies the flower as a tulip.</p> <p>In response, the API returns an array
// of labels. In addition, the response also includes the orientation correction.
// Optionally, you can specify <code>MinConfidence</code> to control the confidence
// threshold for the labels returned. The default is 55%. You can also add the
// <code>MaxLabels</code> parameter to limit the number of labels returned. </p>
// <note> <p>If the object detected is a person, the operation doesn't provide the
// same facial details that the <a>DetectFaces</a> operation provides.</p> </note>
// <p> <code>DetectLabels</code> returns bounding boxes for instances of common
// object labels in an array of <a>Instance</a> objects. An <code>Instance</code>
// object contains a <a>BoundingBox</a> object, for the location of the label on
// the image. It also includes the confidence by which the bounding box was
// detected.</p> <p> <code>DetectLabels</code> also returns a hierarchical taxonomy
// of detected labels. For example, a detected car might be assigned the label
// <i>car</i>. The label <i>car</i> has two parent labels: <i>Vehicle</i> (its
// parent) and <i>Transportation</i> (its grandparent). The response returns the
// entire list of ancestors for a label. Each ancestor is a unique label in the
// response. In the previous example, <i>Car</i>, <i>Vehicle</i>, and
// <i>Transportation</i> are returned as unique labels in the response. </p>
// <p>This is a stateless API operation. That is, the operation does not persist
// any data.</p> <p>This operation requires permissions to perform the
// <code>rekognition:DetectLabels</code> action. </p>
func (c *Client) DetectLabels(ctx context.Context, params *DetectLabelsInput, optFns ...func(*Options)) (*DetectLabelsOutput, error) {
	stack := middleware.NewStack("DetectLabels", smithyhttp.NewStackRequest)
	options := c.options.Copy()
	for _, fn := range optFns {
		fn(&options)
	}
	addawsAwsjson11_serdeOpDetectLabelsMiddlewares(stack)
	awsmiddleware.AddRequestInvocationIDMiddleware(stack)
	smithyhttp.AddContentLengthMiddleware(stack)
	AddResolveEndpointMiddleware(stack, options)
	v4.AddComputePayloadSHA256Middleware(stack)
	retry.AddRetryMiddlewares(stack, options)
	addHTTPSignerV4Middleware(stack, options)
	awsmiddleware.AddAttemptClockSkewMiddleware(stack)
	addClientUserAgent(stack)
	smithyhttp.AddErrorCloseResponseBodyMiddleware(stack)
	smithyhttp.AddCloseResponseBodyMiddleware(stack)
	addOpDetectLabelsValidationMiddleware(stack)
	stack.Initialize.Add(newServiceMetadataMiddleware_opDetectLabels(options.Region), middleware.Before)
	addRequestIDRetrieverMiddleware(stack)
	addResponseErrorMiddleware(stack)

	for _, fn := range options.APIOptions {
		if err := fn(stack); err != nil {
			return nil, err
		}
	}
	handler := middleware.DecorateHandler(smithyhttp.NewClientHandler(options.HTTPClient), stack)
	result, metadata, err := handler.Handle(ctx, params)
	if err != nil {
		return nil, &smithy.OperationError{
			ServiceID:     ServiceID,
			OperationName: "DetectLabels",
			Err:           err,
		}
	}
	out := result.(*DetectLabelsOutput)
	out.ResultMetadata = metadata
	return out, nil
}

type DetectLabelsInput struct {

	// The input image as base64-encoded bytes or an S3 object. If you use the AWS CLI
	// to call Amazon Rekognition operations, passing image bytes is not supported.
	// Images stored in an S3 Bucket do not need to be base64-encoded. If you are using
	// an AWS SDK to call Amazon Rekognition, you might not need to base64-encode image
	// bytes passed using the Bytes field. For more information, see Images in the
	// Amazon Rekognition developer guide.
	//
	// This member is required.
	Image *types.Image

	// Specifies the minimum confidence level for the labels to return. Amazon
	// Rekognition doesn't return any labels with confidence lower than this specified
	// value. If MinConfidence is not specified, the operation returns labels with a
	// confidence values greater than or equal to 55 percent.
	MinConfidence *float32

	// Maximum number of labels you want the service to return in the response. The
	// service returns the specified number of highest confidence labels.
	MaxLabels *int32
}

type DetectLabelsOutput struct {

	// The value of OrientationCorrection is always null. If the input image is in
	// .jpeg format, it might contain exchangeable image file format (Exif) metadata
	// that includes the image's orientation. Amazon Rekognition uses this orientation
	// information to perform image correction. The bounding box coordinates are
	// translated to represent object locations after the orientation information in
	// the Exif metadata is used to correct the image orientation. Images in .png
	// format don't contain Exif metadata. Amazon Rekognition doesn’t perform image
	// correction for images in .png format and .jpeg images without orientation
	// information in the image Exif metadata. The bounding box coordinates aren't
	// translated and represent the object locations before the image is rotated.
	OrientationCorrection types.OrientationCorrection

	// Version number of the label detection model that was used to detect labels.
	LabelModelVersion *string

	// An array of labels for the real-world objects detected.
	Labels []*types.Label

	// Metadata pertaining to the operation's result.
	ResultMetadata middleware.Metadata
}

func addawsAwsjson11_serdeOpDetectLabelsMiddlewares(stack *middleware.Stack) {
	stack.Serialize.Add(&awsAwsjson11_serializeOpDetectLabels{}, middleware.After)
	stack.Deserialize.Add(&awsAwsjson11_deserializeOpDetectLabels{}, middleware.After)
}

func newServiceMetadataMiddleware_opDetectLabels(region string) awsmiddleware.RegisterServiceMetadata {
	return awsmiddleware.RegisterServiceMetadata{
		Region:        region,
		ServiceID:     ServiceID,
		SigningName:   "rekognition",
		OperationName: "DetectLabels",
	}
}