tessl/pypi-google-cloud-vision

Google Cloud Vision API client library for image analysis, OCR, face detection, and machine learning-based visual content recognition.

—

Pending

Overview

Eval results

Files

Image Analysis and Annotation

Name: tessl/pypi-google-cloud-vision
Author: tessl

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.

ImageAnnotatorClient

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

Client Initialization

class ImageAnnotatorClient:
    def __init__(self, *, credentials=None, transport=None, client_options=None, client_info=None):
        """Initialize the ImageAnnotatorClient.
        
        Args:
            credentials: The authorization credentials to attach to requests
            transport: The transport to use for API calls  
            client_options: Custom options for the client
            client_info: The client info used to send a user-agent string
        """

Basic Usage

from google.cloud.vision import ImageAnnotatorClient, Image

# Initialize client
client = ImageAnnotatorClient()

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

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

# Access specific detection results
if response.face_annotations:
    print(f"Found {len(response.face_annotations)} faces")
    
if response.text_annotations:
    print(f"Text detected: {response.text_annotations[0].description}")
    
if response.label_annotations:
    labels = [label.description for label in response.label_annotations]
    print(f"Labels: {labels}")

Capabilities

Core Annotation Methods

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

def annotate_image(self, request, *, retry=None, timeout=None, metadata=()) -> AnnotateImageResponse:
    """Run image detection and annotation for a single image.
    
    Convenience method that automatically detects all features if none are specified.
    Supports reading from file handles and filenames.
    
    Args:
        request: AnnotateImageRequest or dict with 'image' and optional 'features'
        retry: Retry configuration for the request  
        timeout: Timeout for the request in seconds
        metadata: Additional metadata to send with the request
        
    Returns:
        AnnotateImageResponse: Complete analysis results for the image
    """

def batch_annotate_images(self, requests, *, retry=None, timeout=None, metadata=()) -> BatchAnnotateImagesResponse:
    """Run image detection and annotation for multiple images.
    
    Args:
        requests: List of AnnotateImageRequest objects
        retry: Retry configuration for the request
        timeout: Timeout for the request in seconds  
        metadata: Additional metadata to send with the request
        
    Returns:
        BatchAnnotateImagesResponse: Results for all processed images
    """

def batch_annotate_files(self, requests, *, retry=None, timeout=None, metadata=()) -> BatchAnnotateFilesResponse:
    """Run image detection and annotation for files (PDF/TIFF).
    
    Args:
        requests: List of AnnotateFileRequest objects
        retry: Retry configuration for the request
        timeout: Timeout for the request in seconds
        metadata: Additional metadata to send with the request
        
    Returns:
        BatchAnnotateFilesResponse: Results for all processed files  
    """

def async_batch_annotate_images(self, requests, output_config, *, retry=None, timeout=None, metadata=()) -> Operation:
    """Asynchronously run image detection for multiple images.
    
    Args:
        requests: List of AnnotateImageRequest objects
        output_config: OutputConfig specifying where to store results
        retry: Retry configuration for the request
        timeout: Timeout for the request in seconds
        metadata: Additional metadata to send with the request
        
    Returns:
        Operation: Long-running operation for the batch job
    """

def async_batch_annotate_files(self, requests, *, retry=None, timeout=None, metadata=()) -> Operation:
    """Asynchronously run image detection for files.
    
    Args:
        requests: List of AsyncAnnotateFileRequest objects  
        retry: Retry configuration for the request
        timeout: Timeout for the request in seconds
        metadata: Additional metadata to send with the request
        
    Returns:
        Operation: Long-running operation for the batch job
    """

Single-Feature Detection Methods

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

def face_detection(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse:
    """Perform face detection on an image.
    
    Args:
        image: Image object or dict with image data
        max_results: Maximum number of results to return  
        retry: Retry configuration
        timeout: Timeout in seconds
        metadata: Additional metadata
        kwargs: Additional properties for AnnotateImageRequest
        
    Returns:
        AnnotateImageResponse: Response with face_annotations populated
    """

def landmark_detection(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse:
    """Perform landmark detection on an image.
    
    Args:
        image: Image object or dict with image data
        max_results: Maximum number of results to return
        retry: Retry configuration  
        timeout: Timeout in seconds
        metadata: Additional metadata
        kwargs: Additional properties for AnnotateImageRequest
        
    Returns:
        AnnotateImageResponse: Response with landmark_annotations populated
    """

def logo_detection(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse:
    """Perform logo detection on an image.
    
    Args:
        image: Image object or dict with image data
        max_results: Maximum number of results to return
        retry: Retry configuration
        timeout: Timeout in seconds  
        metadata: Additional metadata
        kwargs: Additional properties for AnnotateImageRequest
        
    Returns:
        AnnotateImageResponse: Response with logo_annotations populated  
    """

def label_detection(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse:
    """Perform label detection on an image.
    
    Args:
        image: Image object or dict with image data
        max_results: Maximum number of results to return
        retry: Retry configuration
        timeout: Timeout in seconds
        metadata: Additional metadata  
        kwargs: Additional properties for AnnotateImageRequest
        
    Returns:
        AnnotateImageResponse: Response with label_annotations populated
    """

def text_detection(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse:
    """Perform text detection (sparse) on an image.
    
    Args:
        image: Image object or dict with image data
        max_results: Maximum number of results to return
        retry: Retry configuration
        timeout: Timeout in seconds
        metadata: Additional metadata
        kwargs: Additional properties for AnnotateImageRequest
        
    Returns:
        AnnotateImageResponse: Response with text_annotations populated
    """

def document_text_detection(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse:
    """Perform dense text document OCR on an image.
    
    Args:
        image: Image object or dict with image data  
        max_results: Maximum number of results to return
        retry: Retry configuration
        timeout: Timeout in seconds
        metadata: Additional metadata
        kwargs: Additional properties for AnnotateImageRequest
        
    Returns:
        AnnotateImageResponse: Response with full_text_annotation populated
    """

def safe_search_detection(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse:
    """Perform safe search detection on an image.
    
    Args:
        image: Image object or dict with image data
        max_results: Maximum number of results to return  
        retry: Retry configuration
        timeout: Timeout in seconds
        metadata: Additional metadata
        kwargs: Additional properties for AnnotateImageRequest
        
    Returns:
        AnnotateImageResponse: Response with safe_search_annotation populated
    """

def image_properties(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse:
    """Compute image properties.
    
    Args:
        image: Image object or dict with image data
        max_results: Maximum number of results to return
        retry: Retry configuration
        timeout: Timeout in seconds  
        metadata: Additional metadata
        kwargs: Additional properties for AnnotateImageRequest
        
    Returns:
        AnnotateImageResponse: Response with image_properties_annotation populated
    """

def crop_hints(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse:
    """Run crop hints detection on an image.
    
    Args:
        image: Image object or dict with image data
        max_results: Maximum number of results to return
        retry: Retry configuration
        timeout: Timeout in seconds
        metadata: Additional metadata
        kwargs: Additional properties for AnnotateImageRequest
        
    Returns:
        AnnotateImageResponse: Response with crop_hints_annotation populated
    """

def web_detection(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse:
    """Run web detection on an image.
    
    Args:
        image: Image object or dict with image data
        max_results: Maximum number of results to return
        retry: Retry configuration  
        timeout: Timeout in seconds
        metadata: Additional metadata
        kwargs: Additional properties for AnnotateImageRequest
        
    Returns:
        AnnotateImageResponse: Response with web_detection populated
    """

def product_search(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse:
    """Run product search on an image.
    
    Args:
        image: Image object or dict with image data
        max_results: Maximum number of results to return
        retry: Retry configuration
        timeout: Timeout in seconds
        metadata: Additional metadata  
        kwargs: Additional properties for AnnotateImageRequest
        
    Returns:
        AnnotateImageResponse: Response with product_search_results populated
    """

def object_localization(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse:
    """Run object localization on an image.
    
    Args:
        image: Image object or dict with image data
        max_results: Maximum number of results to return
        retry: Retry configuration
        timeout: Timeout in seconds
        metadata: Additional metadata
        kwargs: Additional properties for AnnotateImageRequest
        
    Returns:
        AnnotateImageResponse: Response with localized_object_annotations populated
    """

Usage Examples

Basic Image Analysis

from google.cloud.vision import ImageAnnotatorClient, Image

client = ImageAnnotatorClient()

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

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

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

# Check for labels  
for label in response.label_annotations:
    print(f"Label: {label.description} (confidence: {label.score})")

Specific Feature Detection

# Detect only faces with max 5 results
response = client.face_detection(image, max_results=5)
faces = response.face_annotations

# Detect only text
response = client.text_detection(image)  
text = response.text_annotations

# Detect labels with custom context
response = client.label_detection(
    image, 
    max_results=10,
    image_context={'lat_long_rect': {
        'min_lat_lng': {'latitude': 37.4, 'longitude': -122.1},
        'max_lat_lng': {'latitude': 37.5, 'longitude': -122.0}
    }}
)

Batch Processing

from google.cloud.vision import Feature

# Process multiple images
images = [
    Image(source={'image_uri': 'https://example.com/image1.jpg'}),
    Image(source={'image_uri': 'https://example.com/image2.jpg'}),
    Image(source={'image_uri': 'https://example.com/image3.jpg'})
]

requests = []
for img in images:
    requests.append({
        'image': img,
        'features': [
            {'type_': Feature.Type.FACE_DETECTION, 'max_results': 10},
            {'type_': Feature.Type.LABEL_DETECTION, 'max_results': 10}
        ]
    })

response = client.batch_annotate_images(requests=requests)

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

Local File Processing

# Read from local file
with open('local_image.jpg', 'rb') as image_file:
    content = image_file.read()

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

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

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

Advanced Configuration

from google.cloud.vision import ImageContext, TextDetectionParams, CropHintsParams

# Configure text detection parameters
text_params = TextDetectionParams(enable_text_detection_confidence_score=True)
image_context = ImageContext(text_detection_params=text_params)

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

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

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

ImageAnnotatorAsyncClient

Asynchronous version of the ImageAnnotatorClient for non-blocking operations.

class ImageAnnotatorAsyncClient:
    def __init__(self, *, credentials=None, transport=None, client_options=None, client_info=None):
        """Initialize the ImageAnnotatorAsyncClient.
        
        Args:
            credentials: The authorization credentials to attach to requests
            transport: The transport to use for API calls
            client_options: Custom options for the client
            client_info: The client info used to send a user-agent string
        """
    
    async def batch_annotate_images(self, requests, *, retry=None, timeout=None, metadata=()) -> BatchAnnotateImagesResponse: ...
    async def batch_annotate_files(self, requests, *, retry=None, timeout=None, metadata=()) -> BatchAnnotateFilesResponse: ...
    async def async_batch_annotate_images(self, requests, output_config, *, retry=None, timeout=None, metadata=()) -> Operation: ...
    async def async_batch_annotate_files(self, requests, *, retry=None, timeout=None, metadata=()) -> Operation: ...

Async Usage

import asyncio
from google.cloud.vision import ImageAnnotatorAsyncClient, Image, Feature

async def analyze_image_async():
    client = ImageAnnotatorAsyncClient()
    image = Image(source={'image_uri': 'https://example.com/photo.jpg'})
    
    # Use batch_annotate_images for single image (async client doesn't have annotate_image)
    request = {
        'image': image,
        'features': [{'type_': Feature.Type.LABEL_DETECTION}]
    }
    response = await client.batch_annotate_images(requests=[request])
    
    # Access the first (and only) response
    image_response = response.responses[0]
    print(f"Found {len(image_response.label_annotations)} labels")
    for label in image_response.label_annotations:
        print(f"- {label.description}: {label.score}")

# Run async function
asyncio.run(analyze_image_async())

Install with Tessl CLI

npx tessl i tessl/pypi-google-cloud-vision

docs