Analyze Images with Azure AI Vision

Azure AI Vision terms — defined before code

What you can ask the Vision API to detect

All visual features — what each one returns

Extracting text from images and documents

The Read API is Azure's most powerful OCR engine — it handles printed text, handwriting, and mixed content. It is accessed as part of Azure AI Vision (same resource, same endpoint) using the READ visual feature in Image Analysis 4.0.

What makes the Read API different from simple OCR

Face detection, attributes, and identification

Face detection attributes — what you get without approval

Face Identification Workflow (requires Limited Access)

Analysing images, extracting text, and reading OCR results

Install: pip install azure-ai-vision-imageanalysis azure-core

import os
from azure.ai.vision.imageanalysis import ImageAnalysisClient
from azure.ai.vision.imageanalysis.models import VisualFeatures
# VisualFeatures is an enum — each value requests one type of image analysis
from azure.core.credentials import AzureKeyCredential

# ── Connection details ─────────────────────────────────────────────────
# From your Azure AI Vision resource in the portal: Keys and Endpoint
# Endpoint format: https://<your-resource-name>.cognitiveservices.azure.com/
endpoint = os.environ.get("VISION_ENDPOINT")
key      = os.environ.get("VISION_KEY")

# Create the client — wraps the endpoint and credential for all Vision operations
client = ImageAnalysisClient(
    endpoint   = endpoint,
    credential = AzureKeyCredential(key)
)


# ══════════════════════════════════════════════════════════════════════
# EXAMPLE 1 — Full image analysis from a URL
# Requesting multiple visual features in a single API call
# ══════════════════════════════════════════════════════════════════════

image_url = "https://upload.wikimedia.org/wikipedia/commons/thumb/4/47/PNG_transparency_demonstration_1.png/280px-PNG_transparency_demonstration_1.png"

# analyze() is SYNCHRONOUS for URL-based images — the result comes back immediately
# (No polling needed for Image Analysis 4.0 with URLs — only the standalone Read API is async)
# visual_features: a list of VisualFeatures enum values — only these are analysed and billed
result = client.analyze(
    image_url       = image_url,
    visual_features = [
        VisualFeatures.CAPTION,        # Generate a one-sentence image description
        VisualFeatures.TAGS,           # List of descriptive keyword tags
        VisualFeatures.OBJECTS,        # Detected objects with bounding boxes
        VisualFeatures.PEOPLE,         # Detected human figures with bounding boxes
        VisualFeatures.READ,           # OCR — extract any text in the image
        VisualFeatures.SMART_CROPS,    # Suggest crop regions for thumbnails
    ],
    # smart_crops_aspect_ratios: list of desired width/height ratios for crop suggestions
    # 1.0 = square crop (e.g. social media profile), 1.78 = landscape widescreen 16:9
    smart_crops_aspect_ratios = [1.0, 1.78],
    # gender_neutral_caption: True = avoid gendered pronouns in captions (he/she → they)
    gender_neutral_caption    = True
)


# ── Caption ──────────────────────────────────────────────────────────
# result.caption is None if CAPTION was not in visual_features
if result.caption:
    # .text: the generated sentence — .confidence: how confident the model is (0.0 to 1.0)
    print(f"Caption: {result.caption.text}  (confidence: {result.caption.confidence:.2f})")


# ── Tags ──────────────────────────────────────────────────────────────
if result.tags:
    print("\nTags:")
    # result.tags.list: a list of ImageTag objects, sorted by confidence descending
    for tag in result.tags.list:
        # tag.name: the keyword (e.g. "car", "outdoor") — tag.confidence: certainty score
        print(f"  {tag.name}: {tag.confidence:.2f}")


# ── Objects with bounding boxes ────────────────────────────────────────
if result.objects:
    print("\nObjects:")
    # result.objects.list: each item is a DetectedObject
    for obj in result.objects.list:
        # obj.tags: what type of object — obj.bounding_box: where in the image it is
        name = obj.tags[0].name if obj.tags else "unknown"
        bb   = obj.bounding_box
        # bb.x, bb.y: top-left corner pixel position
        # bb.width, bb.height: dimensions of the rectangle in pixels
        print(f"  {name}: x={bb.x}, y={bb.y}, w={bb.width}, h={bb.height}")


# ── People detection ──────────────────────────────────────────────────
if result.people:
    print(f"\nPeople detected: {len(result.people.list)}")
    for person in result.people.list:
        bb = person.bounding_box
        # person.confidence: how confident the model is this is a human figure
        print(f"  Person at x={bb.x}, y={bb.y} — confidence: {person.confidence:.2f}")


# ── OCR text extraction (READ feature) ────────────────────────────────
if result.read:
    print("\nExtracted Text:")
    # result.read.blocks: list of text blocks (logical groups of text)
    # Each block has .lines; each line has .words
    for block in result.read.blocks:
        for line in block.lines:
            # line.text: the full text of this line (all words concatenated)
            print(f"  Line: '{line.text}'")
            for word in line.words:
                # word.text: the individual word — word.confidence: OCR confidence
                # word.bounding_polygon: list of {x, y} points forming the word's quadrilateral
                # (4 points, not necessarily rectangular — handles rotated/slanted text)
                pts = [(p.x, p.y) for p in word.bounding_polygon]
                print(f"    Word: '{word.text}' conf={word.confidence:.2f} at {pts}")


# ── Smart crop suggestions ─────────────────────────────────────────────
if result.smart_crops:
    print("\nSmart Crop Suggestions:")
    for crop in result.smart_crops.list:
        # crop.aspect_ratio: the ratio you requested (e.g. 1.0 for square)
        # crop.bounding_box: the suggested crop rectangle
        bb = crop.bounding_box
        print(f"  Ratio {crop.aspect_ratio}: x={bb.x}, y={bb.y}, w={bb.width}, h={bb.height}")


# ══════════════════════════════════════════════════════════════════════
# EXAMPLE 2 — Analysing a LOCAL IMAGE FILE
# Use analyze_from_url() for URLs, analyze() with image_data for local files
# ══════════════════════════════════════════════════════════════════════

# Read the local image file as binary bytes
with open("local-photo.jpg", "rb") as f:
    image_bytes = f.read()  # Read the entire file as raw binary

# analyze() also accepts image_data (bytes) instead of image_url
# image_data: pass the binary content and specify the MIME type
result_local = client.analyze(
    image_data      = image_bytes,   # The image as raw bytes
    visual_features = [VisualFeatures.CAPTION, VisualFeatures.TAGS]
)

if result_local.caption:
    print(f"\nLocal image caption: {result_local.caption.text}")

Python — Face API: Detection and Identification

Install: pip install azure-ai-vision-face  ·  Note: requires Limited Access approval for identification and verification.

from azure.ai.vision.face import FaceClient
from azure.ai.vision.face.models import (
    FaceDetectionModel,   # Which version of the face detection model to use
    FaceRecognitionModel, # Which version of the face recognition model for identification
    FaceAttributeTypeDetection01,  # Attributes available in the detection model
)
from azure.core.credentials import AzureKeyCredential

# Face API uses its OWN endpoint — different from Image Analysis
# Face API endpoint format: https://<region>.api.cognitive.microsoft.com/
FACE_ENDPOINT = os.environ.get("FACE_ENDPOINT")
FACE_KEY      = os.environ.get("FACE_KEY")

face_client = FaceClient(endpoint=FACE_ENDPOINT, credential=AzureKeyCredential(FACE_KEY))


# ── STEP 1: Detect faces in an image ──────────────────────────────────
# This does NOT identify anyone — just finds where faces are and which attributes they have
# No Limited Access approval needed for this step

detected_faces = face_client.detect_from_url(
    url               = "https://example.com/team-photo.jpg",
    # detection_model: DETECTION_03 is latest — best for small faces and masks
    detection_model   = FaceDetectionModel.DETECTION_03,
    # recognition_model: needed if you plan to identify or verify — must match training
    recognition_model = FaceRecognitionModel.RECOGNITION_04,
    # return_face_id: needed for identification — face IDs expire after 24 hours
    return_face_id    = True,
    # return_face_attributes: which detection attributes to analyse
    return_face_attributes = [
        FaceAttributeTypeDetection01.HEAD_POSE,   # Pitch, roll, yaw angles
        FaceAttributeTypeDetection01.BLUR,         # Focus quality
        FaceAttributeTypeDetection01.EXPOSURE,     # Lighting quality
        FaceAttributeTypeDetection01.GLASSES,      # Eyewear type
    ]
)

print(f"Found {len(detected_faces)} face(s)")
for face in detected_faces:
    # face.face_id: a temporary ID used for identification (expires after 24 hours)
    print(f"\nFace ID: {face.face_id}")

    # face_rectangle: where on the image the face appears
    r = face.face_rectangle
    print(f"  Location: top={r.top}, left={r.left}, width={r.width}, height={r.height}")

    # face_attributes: the attributes we requested above
    attrs = face.face_attributes
    if attrs:
        # head_pose: how the head is oriented
        if attrs.head_pose:
            print(f"  Head Pose: pitch={attrs.head_pose.pitch:.1f} roll={attrs.head_pose.roll:.1f} yaw={attrs.head_pose.yaw:.1f}")
        # blur: is the face in focus? .blur_level = LOW / MEDIUM / HIGH
        if attrs.blur:
            print(f"  Blur: {attrs.blur.blur_level}")
        # glasses: what eyewear is the person wearing (if any)
        if attrs.glasses:
            print(f"  Glasses: {attrs.glasses}")


# ── STEP 2: IDENTIFICATION (requires Limited Access approval) ──────────
# The code below demonstrates PersonGroup creation and identification
# This will NOT work without Microsoft Limited Access approval

GROUP_ID = "company-employees"

# Create the PersonGroup (only done once — reuse for all identifications)
face_client.person_group.create(
    person_group_id = GROUP_ID,        # Unique ID for this group (lowercase, no spaces)
    name            = "Company Employees",  # Human-readable name
    recognition_model = FaceRecognitionModel.RECOGNITION_04  # Must match detection model
)

# Add a Person (Alice) to the group — returns a person_id
alice = face_client.person_group_person.create(
    person_group_id = GROUP_ID,
    name            = "Alice Johnson"   # The person's name — stored for reference
)
# alice.person_id is a UUID that uniquely identifies Alice in this group

# Add face images for Alice (multiple photos from different angles recommended)
for photo_url in ["https://example.com/alice1.jpg", "https://example.com/alice2.jpg"]:
    face_client.person_group_person.add_face_from_url(
        person_group_id = GROUP_ID,
        person_id       = alice.person_id,  # Link this photo to Alice
        url             = photo_url
    )

# Train the PersonGroup — must be done before identification
# This is also async — call get_training_status() until status is "succeeded"
face_client.person_group.train(person_group_id=GROUP_ID)
print("PersonGroup training initiated — poll get_training_status() until succeeded")

# Identify a detected face against the PersonGroup
# detected_faces[0].face_id is the temporary face_id from the DETECT step above
identify_results = face_client.identify(
    face_ids        = [detected_faces[0].face_id],  # Which faces to identify
    person_group_id = GROUP_ID,                    # Which group to search against
)

for id_result in identify_results:
    if id_result.candidates:
        # candidates: sorted by confidence descending — first candidate is the best match
        best = id_result.candidates[0]
        # best.person_id: the UUID of the matched person — look up Alice by this ID
        # best.confidence: 0.0 to 1.0 — typically use 0.5+ as threshold for a match
        print(f"Identified: {best.person_id} with confidence {best.confidence:.2f}")
    else:
        print("No match found in PersonGroup")

Azure AI Vision — what the exam tests

Test your understanding