Azure AI Vision Imageanalysis Py

1---
2name: azure-ai-vision-imageanalysis-py
3description: |
4  Azure AI Vision Image Analysis SDK for captions, tags, objects, OCR, people detection, and smart cropping. Use for computer vision and image understanding tasks.
5  Triggers: "image analysis", "computer vision", "OCR", "object detection", "ImageAnalysisClient", "image caption".
6package: azure-ai-vision-imageanalysis
7---
8 
9# Azure AI Vision Image Analysis SDK for Python
10 
11Client library for Azure AI Vision 4.0 image analysis including captions, tags, objects, OCR, and more.
12 
13## Installation
14 
15```bash
16pip install azure-ai-vision-imageanalysis
17```
18 
19## Environment Variables
20 
21```bash
22VISION_ENDPOINT=https://<resource>.cognitiveservices.azure.com
23VISION_KEY=<your-api-key>  # If using API key
24```
25 
26## Authentication
27 
28### API Key
29 
30```python
31import os
32from azure.ai.vision.imageanalysis import ImageAnalysisClient
33from azure.core.credentials import AzureKeyCredential
34 
35endpoint = os.environ["VISION_ENDPOINT"]
36key = os.environ["VISION_KEY"]
37 
38client = ImageAnalysisClient(
39    endpoint=endpoint,
40    credential=AzureKeyCredential(key)
41)
42```
43 
44### Entra ID (Recommended)
45 
46```python
47from azure.ai.vision.imageanalysis import ImageAnalysisClient
48from azure.identity import DefaultAzureCredential
49 
50client = ImageAnalysisClient(
51    endpoint=os.environ["VISION_ENDPOINT"],
52    credential=DefaultAzureCredential()
53)
54```
55 
56## Analyze Image from URL
57 
58```python
59from azure.ai.vision.imageanalysis.models import VisualFeatures
60 
61image_url = "https://example.com/image.jpg"
62 
63result = client.analyze_from_url(
64    image_url=image_url,
65    visual_features=[
66        VisualFeatures.CAPTION,
67        VisualFeatures.TAGS,
68        VisualFeatures.OBJECTS,
69        VisualFeatures.READ,
70        VisualFeatures.PEOPLE,
71        VisualFeatures.SMART_CROPS,
72        VisualFeatures.DENSE_CAPTIONS
73    ],
74    gender_neutral_caption=True,
75    language="en"
76)
77```
78 
79## Analyze Image from File
80 
81```python
82with open("image.jpg", "rb") as f:
83    image_data = f.read()
84 
85result = client.analyze(
86    image_data=image_data,
87    visual_features=[VisualFeatures.CAPTION, VisualFeatures.TAGS]
88)
89```
90 
91## Image Caption
92 
93```python
94result = client.analyze_from_url(
95    image_url=image_url,
96    visual_features=[VisualFeatures.CAPTION],
97    gender_neutral_caption=True
98)
99 
100if result.caption:
101    print(f"Caption: {result.caption.text}")
102    print(f"Confidence: {result.caption.confidence:.2f}")
103```
104 
105## Dense Captions (Multiple Regions)
106 
107```python
108result = client.analyze_from_url(
109    image_url=image_url,
110    visual_features=[VisualFeatures.DENSE_CAPTIONS]
111)
112 
113if result.dense_captions:
114    for caption in result.dense_captions.list:
115        print(f"Caption: {caption.text}")
116        print(f"  Confidence: {caption.confidence:.2f}")
117        print(f"  Bounding box: {caption.bounding_box}")
118```
119 
120## Tags
121 
122```python
123result = client.analyze_from_url(
124    image_url=image_url,
125    visual_features=[VisualFeatures.TAGS]
126)
127 
128if result.tags:
129    for tag in result.tags.list:
130        print(f"Tag: {tag.name} (confidence: {tag.confidence:.2f})")
131```
132 
133## Object Detection
134 
135```python
136result = client.analyze_from_url(
137    image_url=image_url,
138    visual_features=[VisualFeatures.OBJECTS]
139)
140 
141if result.objects:
142    for obj in result.objects.list:
143        print(f"Object: {obj.tags[0].name}")
144        print(f"  Confidence: {obj.tags[0].confidence:.2f}")
145        box = obj.bounding_box
146        print(f"  Bounding box: x={box.x}, y={box.y}, w={box.width}, h={box.height}")
147```
148 
149## OCR (Text Extraction)
150 
151```python
152result = client.analyze_from_url(
153    image_url=image_url,
154    visual_features=[VisualFeatures.READ]
155)
156 
157if result.read:
158    for block in result.read.blocks:
159        for line in block.lines:
160            print(f"Line: {line.text}")
161            print(f"  Bounding polygon: {line.bounding_polygon}")
162            
163            # Word-level details
164            for word in line.words:
165                print(f"  Word: {word.text} (confidence: {word.confidence:.2f})")
166```
167 
168## People Detection
169 
170```python
171result = client.analyze_from_url(
172    image_url=image_url,
173    visual_features=[VisualFeatures.PEOPLE]
174)
175 
176if result.people:
177    for person in result.people.list:
178        print(f"Person detected:")
179        print(f"  Confidence: {person.confidence:.2f}")
180        box = person.bounding_box
181        print(f"  Bounding box: x={box.x}, y={box.y}, w={box.width}, h={box.height}")
182```
183 
184## Smart Cropping
185 
186```python
187result = client.analyze_from_url(
188    image_url=image_url,
189    visual_features=[VisualFeatures.SMART_CROPS],
190    smart_crops_aspect_ratios=[0.9, 1.33, 1.78]  # Portrait, 4:3, 16:9
191)
192 
193if result.smart_crops:
194    for crop in result.smart_crops.list:
195        print(f"Aspect ratio: {crop.aspect_ratio}")
196        box = crop.bounding_box
197        print(f"  Crop region: x={box.x}, y={box.y}, w={box.width}, h={box.height}")
198```
199 
200## Async Client
201 
202```python
203from azure.ai.vision.imageanalysis.aio import ImageAnalysisClient
204from azure.identity.aio import DefaultAzureCredential
205 
206async def analyze_image():
207    async with ImageAnalysisClient(
208        endpoint=endpoint,
209        credential=DefaultAzureCredential()
210    ) as client:
211        result = await client.analyze_from_url(
212            image_url=image_url,
213            visual_features=[VisualFeatures.CAPTION]
214        )
215        print(result.caption.text)
216```
217 
218## Visual Features
219 
220| Feature | Description |
221|---------|-------------|
222| `CAPTION` | Single sentence describing the image |
223| `DENSE_CAPTIONS` | Captions for multiple regions |
224| `TAGS` | Content tags (objects, scenes, actions) |
225| `OBJECTS` | Object detection with bounding boxes |
226| `READ` | OCR text extraction |
227| `PEOPLE` | People detection with bounding boxes |
228| `SMART_CROPS` | Suggested crop regions for thumbnails |
229 
230## Error Handling
231 
232```python
233from azure.core.exceptions import HttpResponseError
234 
235try:
236    result = client.analyze_from_url(
237        image_url=image_url,
238        visual_features=[VisualFeatures.CAPTION]
239    )
240except HttpResponseError as e:
241    print(f"Status code: {e.status_code}")
242    print(f"Reason: {e.reason}")
243    print(f"Message: {e.error.message}")
244```
245 
246## Image Requirements
247 
248- Formats: JPEG, PNG, GIF, BMP, WEBP, ICO, TIFF, MPO
249- Max size: 20 MB
250- Dimensions: 50x50 to 16000x16000 pixels
251 
252## Best Practices
253 
2541. **Select only needed features** to optimize latency and cost
2552. **Use async client** for high-throughput scenarios
2563. **Handle HttpResponseError** for invalid images or auth issues
2574. **Enable gender_neutral_caption** for inclusive descriptions
2585. **Specify language** for localized captions
2596. **Use smart_crops_aspect_ratios** matching your thumbnail requirements
2607. **Cache results** when analyzing the same image multiple times
261