0
# Image Analysis and Annotation
1

2
Core image analysis functionality for Google Cloud Vision API, providing comprehensive image understanding capabilities including face detection, object localization, text recognition, landmark detection, logo detection, and image properties analysis. The ImageAnnotatorClient offers both batch and single-image processing with extensive customization options and convenient helper methods.
3

4
## ImageAnnotatorClient
5

6
The primary client for image analysis operations, enhanced with VisionHelpers for convenience and dynamically generated single-feature detection methods.
7

8
### Client Initialization
9

10
```python { .api }
11
class ImageAnnotatorClient:
12
    def __init__(self, *, credentials=None, transport=None, client_options=None, client_info=None):
13
        """Initialize the ImageAnnotatorClient.
14
        
15
        Args:
16
            credentials: The authorization credentials to attach to requests
17
            transport: The transport to use for API calls  
18
            client_options: Custom options for the client
19
            client_info: The client info used to send a user-agent string
20
        """
21
```
22

23
### Basic Usage
24

25
```python
26
from google.cloud.vision import ImageAnnotatorClient, Image
27

28
# Initialize client
29
client = ImageAnnotatorClient()
30

31
# Create image from URL
32
image = Image(source={'image_uri': 'https://example.com/photo.jpg'})
33

34
# Analyze image with auto-detection of all features
35
response = client.annotate_image({'image': image})
36

37
# Access specific detection results
38
if response.face_annotations:
39
    print(f"Found {len(response.face_annotations)} faces")
40
    
41
if response.text_annotations:
42
    print(f"Text detected: {response.text_annotations[0].description}")
43
    
44
if response.label_annotations:
45
    labels = [label.description for label in response.label_annotations]
46
    print(f"Labels: {labels}")
47
```
48

49
## Capabilities
50

51
### Core Annotation Methods
52

53
Primary methods for image analysis with full control over features and batch processing.
54

55
```python { .api }
56
def annotate_image(self, request, *, retry=None, timeout=None, metadata=()) -> AnnotateImageResponse:
57
    """Run image detection and annotation for a single image.
58
    
59
    Convenience method that automatically detects all features if none are specified.
60
    Supports reading from file handles and filenames.
61
    
62
    Args:
63
        request: AnnotateImageRequest or dict with 'image' and optional 'features'
64
        retry: Retry configuration for the request  
65
        timeout: Timeout for the request in seconds
66
        metadata: Additional metadata to send with the request
67
        
68
    Returns:
69
        AnnotateImageResponse: Complete analysis results for the image
70
    """
71

72
def batch_annotate_images(self, requests, *, retry=None, timeout=None, metadata=()) -> BatchAnnotateImagesResponse:
73
    """Run image detection and annotation for multiple images.
74
    
75
    Args:
76
        requests: List of AnnotateImageRequest objects
77
        retry: Retry configuration for the request
78
        timeout: Timeout for the request in seconds  
79
        metadata: Additional metadata to send with the request
80
        
81
    Returns:
82
        BatchAnnotateImagesResponse: Results for all processed images
83
    """
84

85
def batch_annotate_files(self, requests, *, retry=None, timeout=None, metadata=()) -> BatchAnnotateFilesResponse:
86
    """Run image detection and annotation for files (PDF/TIFF).
87
    
88
    Args:
89
        requests: List of AnnotateFileRequest objects
90
        retry: Retry configuration for the request
91
        timeout: Timeout for the request in seconds
92
        metadata: Additional metadata to send with the request
93
        
94
    Returns:
95
        BatchAnnotateFilesResponse: Results for all processed files  
96
    """
97

98
def async_batch_annotate_images(self, requests, output_config, *, retry=None, timeout=None, metadata=()) -> Operation:
99
    """Asynchronously run image detection for multiple images.
100
    
101
    Args:
102
        requests: List of AnnotateImageRequest objects
103
        output_config: OutputConfig specifying where to store results
104
        retry: Retry configuration for the request
105
        timeout: Timeout for the request in seconds
106
        metadata: Additional metadata to send with the request
107
        
108
    Returns:
109
        Operation: Long-running operation for the batch job
110
    """
111

112
def async_batch_annotate_files(self, requests, *, retry=None, timeout=None, metadata=()) -> Operation:
113
    """Asynchronously run image detection for files.
114
    
115
    Args:
116
        requests: List of AsyncAnnotateFileRequest objects  
117
        retry: Retry configuration for the request
118
        timeout: Timeout for the request in seconds
119
        metadata: Additional metadata to send with the request
120
        
121
    Returns:
122
        Operation: Long-running operation for the batch job
123
    """
124
```
125

126
### Single-Feature Detection Methods
127

128
Convenience methods for specific detection features, dynamically generated from Feature.Type enum values.
129

130
```python { .api }
131
def face_detection(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse:
132
    """Perform face detection on an image.
133
    
134
    Args:
135
        image: Image object or dict with image data
136
        max_results: Maximum number of results to return  
137
        retry: Retry configuration
138
        timeout: Timeout in seconds
139
        metadata: Additional metadata
140
        kwargs: Additional properties for AnnotateImageRequest
141
        
142
    Returns:
143
        AnnotateImageResponse: Response with face_annotations populated
144
    """
145

146
def landmark_detection(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse:
147
    """Perform landmark detection on an image.
148
    
149
    Args:
150
        image: Image object or dict with image data
151
        max_results: Maximum number of results to return
152
        retry: Retry configuration  
153
        timeout: Timeout in seconds
154
        metadata: Additional metadata
155
        kwargs: Additional properties for AnnotateImageRequest
156
        
157
    Returns:
158
        AnnotateImageResponse: Response with landmark_annotations populated
159
    """
160

161
def logo_detection(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse:
162
    """Perform logo detection on an image.
163
    
164
    Args:
165
        image: Image object or dict with image data
166
        max_results: Maximum number of results to return
167
        retry: Retry configuration
168
        timeout: Timeout in seconds  
169
        metadata: Additional metadata
170
        kwargs: Additional properties for AnnotateImageRequest
171
        
172
    Returns:
173
        AnnotateImageResponse: Response with logo_annotations populated  
174
    """
175

176
def label_detection(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse:
177
    """Perform label detection on an image.
178
    
179
    Args:
180
        image: Image object or dict with image data
181
        max_results: Maximum number of results to return
182
        retry: Retry configuration
183
        timeout: Timeout in seconds
184
        metadata: Additional metadata  
185
        kwargs: Additional properties for AnnotateImageRequest
186
        
187
    Returns:
188
        AnnotateImageResponse: Response with label_annotations populated
189
    """
190

191
def text_detection(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse:
192
    """Perform text detection (sparse) on an image.
193
    
194
    Args:
195
        image: Image object or dict with image data
196
        max_results: Maximum number of results to return
197
        retry: Retry configuration
198
        timeout: Timeout in seconds
199
        metadata: Additional metadata
200
        kwargs: Additional properties for AnnotateImageRequest
201
        
202
    Returns:
203
        AnnotateImageResponse: Response with text_annotations populated
204
    """
205

206
def document_text_detection(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse:
207
    """Perform dense text document OCR on an image.
208
    
209
    Args:
210
        image: Image object or dict with image data  
211
        max_results: Maximum number of results to return
212
        retry: Retry configuration
213
        timeout: Timeout in seconds
214
        metadata: Additional metadata
215
        kwargs: Additional properties for AnnotateImageRequest
216
        
217
    Returns:
218
        AnnotateImageResponse: Response with full_text_annotation populated
219
    """
220

221
def safe_search_detection(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse:
222
    """Perform safe search detection on an image.
223
    
224
    Args:
225
        image: Image object or dict with image data
226
        max_results: Maximum number of results to return  
227
        retry: Retry configuration
228
        timeout: Timeout in seconds
229
        metadata: Additional metadata
230
        kwargs: Additional properties for AnnotateImageRequest
231
        
232
    Returns:
233
        AnnotateImageResponse: Response with safe_search_annotation populated
234
    """
235

236
def image_properties(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse:
237
    """Compute image properties.
238
    
239
    Args:
240
        image: Image object or dict with image data
241
        max_results: Maximum number of results to return
242
        retry: Retry configuration
243
        timeout: Timeout in seconds  
244
        metadata: Additional metadata
245
        kwargs: Additional properties for AnnotateImageRequest
246
        
247
    Returns:
248
        AnnotateImageResponse: Response with image_properties_annotation populated
249
    """
250

251
def crop_hints(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse:
252
    """Run crop hints detection on an image.
253
    
254
    Args:
255
        image: Image object or dict with image data
256
        max_results: Maximum number of results to return
257
        retry: Retry configuration
258
        timeout: Timeout in seconds
259
        metadata: Additional metadata
260
        kwargs: Additional properties for AnnotateImageRequest
261
        
262
    Returns:
263
        AnnotateImageResponse: Response with crop_hints_annotation populated
264
    """
265

266
def web_detection(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse:
267
    """Run web detection on an image.
268
    
269
    Args:
270
        image: Image object or dict with image data
271
        max_results: Maximum number of results to return
272
        retry: Retry configuration  
273
        timeout: Timeout in seconds
274
        metadata: Additional metadata
275
        kwargs: Additional properties for AnnotateImageRequest
276
        
277
    Returns:
278
        AnnotateImageResponse: Response with web_detection populated
279
    """
280

281
def product_search(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse:
282
    """Run product search on an image.
283
    
284
    Args:
285
        image: Image object or dict with image data
286
        max_results: Maximum number of results to return
287
        retry: Retry configuration
288
        timeout: Timeout in seconds
289
        metadata: Additional metadata  
290
        kwargs: Additional properties for AnnotateImageRequest
291
        
292
    Returns:
293
        AnnotateImageResponse: Response with product_search_results populated
294
    """
295

296
def object_localization(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse:
297
    """Run object localization on an image.
298
    
299
    Args:
300
        image: Image object or dict with image data
301
        max_results: Maximum number of results to return
302
        retry: Retry configuration
303
        timeout: Timeout in seconds
304
        metadata: Additional metadata
305
        kwargs: Additional properties for AnnotateImageRequest
306
        
307
    Returns:
308
        AnnotateImageResponse: Response with localized_object_annotations populated
309
    """
310
```
311

312
## Usage Examples
313

314
### Basic Image Analysis
315

316
```python
317
from google.cloud.vision import ImageAnnotatorClient, Image
318

319
client = ImageAnnotatorClient()
320

321
# Analyze image from URL 
322
image = Image(source={'image_uri': 'https://example.com/photo.jpg'})
323
response = client.annotate_image({'image': image})
324

325
# Check for faces
326
if response.face_annotations:
327
    for face in response.face_annotations:
328
        print(f"Face confidence: {face.detection_confidence}")
329
        print(f"Joy likelihood: {face.joy_likelihood}")
330

331
# Check for text
332
if response.text_annotations:
333
    print(f"Detected text: {response.text_annotations[0].description}")
334

335
# Check for labels  
336
for label in response.label_annotations:
337
    print(f"Label: {label.description} (confidence: {label.score})")
338
```
339

340
### Specific Feature Detection
341

342
```python
343
# Detect only faces with max 5 results
344
response = client.face_detection(image, max_results=5)
345
faces = response.face_annotations
346

347
# Detect only text
348
response = client.text_detection(image)  
349
text = response.text_annotations
350

351
# Detect labels with custom context
352
response = client.label_detection(
353
    image, 
354
    max_results=10,
355
    image_context={'lat_long_rect': {
356
        'min_lat_lng': {'latitude': 37.4, 'longitude': -122.1},
357
        'max_lat_lng': {'latitude': 37.5, 'longitude': -122.0}
358
    }}
359
)
360
```
361

362
### Batch Processing
363

364
```python
365
from google.cloud.vision import Feature
366

367
# Process multiple images
368
images = [
369
    Image(source={'image_uri': 'https://example.com/image1.jpg'}),
370
    Image(source={'image_uri': 'https://example.com/image2.jpg'}),
371
    Image(source={'image_uri': 'https://example.com/image3.jpg'})
372
]
373

374
requests = []
375
for img in images:
376
    requests.append({
377
        'image': img,
378
        'features': [
379
            {'type_': Feature.Type.FACE_DETECTION, 'max_results': 10},
380
            {'type_': Feature.Type.LABEL_DETECTION, 'max_results': 10}
381
        ]
382
    })
383

384
response = client.batch_annotate_images(requests=requests)
385

386
for i, image_response in enumerate(response.responses):
387
    print(f"Image {i+1}:")
388
    print(f"  Faces: {len(image_response.face_annotations)}")
389
    print(f"  Labels: {[l.description for l in image_response.label_annotations]}")
390
```
391

392
### Local File Processing
393

394
```python
395
# Read from local file
396
with open('local_image.jpg', 'rb') as image_file:
397
    content = image_file.read()
398

399
image = Image(content=content)
400
response = client.annotate_image({'image': image})
401

402
# Or use filename directly (helper will read the file)
403
response = client.annotate_image({
404
    'image': {'source': {'filename': 'local_image.jpg'}}
405
})
406

407
# Or pass file handle directly  
408
with open('local_image.jpg', 'rb') as image_file:
409
    response = client.annotate_image({'image': image_file})
410
```
411

412
### Advanced Configuration
413

414
```python
415
from google.cloud.vision import ImageContext, TextDetectionParams, CropHintsParams
416

417
# Configure text detection parameters
418
text_params = TextDetectionParams(enable_text_detection_confidence_score=True)
419
image_context = ImageContext(text_detection_params=text_params)
420

421
response = client.text_detection(image, image_context=image_context)
422

423
# Configure crop hints  
424
crop_params = CropHintsParams(aspect_ratios=[1.0, 1.5, 2.0])
425
image_context = ImageContext(crop_hints_params=crop_params)
426

427
response = client.crop_hints(image, image_context=image_context)
428
```
429

430
## ImageAnnotatorAsyncClient
431

432
Asynchronous version of the ImageAnnotatorClient for non-blocking operations.
433

434
```python { .api }
435
class ImageAnnotatorAsyncClient:
436
    def __init__(self, *, credentials=None, transport=None, client_options=None, client_info=None):
437
        """Initialize the ImageAnnotatorAsyncClient.
438
        
439
        Args:
440
            credentials: The authorization credentials to attach to requests
441
            transport: The transport to use for API calls
442
            client_options: Custom options for the client
443
            client_info: The client info used to send a user-agent string
444
        """
445
    
446
    async def batch_annotate_images(self, requests, *, retry=None, timeout=None, metadata=()) -> BatchAnnotateImagesResponse: ...
447
    async def batch_annotate_files(self, requests, *, retry=None, timeout=None, metadata=()) -> BatchAnnotateFilesResponse: ...
448
    async def async_batch_annotate_images(self, requests, output_config, *, retry=None, timeout=None, metadata=()) -> Operation: ...
449
    async def async_batch_annotate_files(self, requests, *, retry=None, timeout=None, metadata=()) -> Operation: ...
450
```
451

452
### Async Usage
453

454
```python
455
import asyncio
456
from google.cloud.vision import ImageAnnotatorAsyncClient, Image, Feature
457

458
async def analyze_image_async():
459
    client = ImageAnnotatorAsyncClient()
460
    image = Image(source={'image_uri': 'https://example.com/photo.jpg'})
461
    
462
    # Use batch_annotate_images for single image (async client doesn't have annotate_image)
463
    request = {
464
        'image': image,
465
        'features': [{'type_': Feature.Type.LABEL_DETECTION}]
466
    }
467
    response = await client.batch_annotate_images(requests=[request])
468
    
469
    # Access the first (and only) response
470
    image_response = response.responses[0]
471
    print(f"Found {len(image_response.label_annotations)} labels")
472
    for label in image_response.label_annotations:
473
        print(f"- {label.description}: {label.score}")
474

475
# Run async function
476
asyncio.run(analyze_image_async())
477
```