Skip to main content

Image Analysis

Extract color, texture, gradient, and feature details from your images. Heimdall Vision provides two powerful endpoints for comprehensive image analysis.

Get Your API Key

You'll need an API key from the Unstructured API Key tab to use image analysis features.

What You Can Analyze​

  • Product photos - Extract visual features for categorization
  • User uploads - Analyze and classify user-generated content
  • Document images - Process scanned documents and forms
  • Medical images - Extract features for diagnostic analysis
  • Security footage - Analyze surveillance images

Two Analysis Endpoints​

1. Process API - Color, Texture & Gradients​

Extract comprehensive visual features including color histograms, texture patterns, and gradient information.

2. Features API - Key Points & Descriptors​

Extract important points and descriptors for advanced image analysis and matching.

Process API - Visual Features​

Endpoint​

POST https://vision.heimdallapp.org/vision/v1/api/process

Request Headers​

  • x-api-key - API key that is issued when the endpoint is configured
  • x-username - Username associated with your account

Request Body​

  • file - The image file you want to analyze
warning

Valid image formats: .JPEG, .PNG, .GIF, .BMP, and .TIFF

Response Features​

Color Histograms​

  • red - Red channel histogram (31 buckets)
  • green - Green channel histogram (31 buckets)
  • blue - Blue channel histogram (31 buckets)
  • combined - Combined RGB histogram

Visual Analysis​

  • gradients - Histogram of oriented gradients (36 bins)
  • textures - Texture pattern probability histogram (26 bins)

Features API - Key Points​

Endpoint​

POST https://vision.heimdallapp.org/vision/v1/api/features

Response Features​

Spatial Information​

  • angles - List of angles corresponding to important points (0° = x-axis, 90° = y-axis)
  • distances - Euclidean distances from bottom-left corner to each point
  • descriptors - Color intensity change approximations for each point

Example Responses​

Process API Response​

{
    "filename": "dog.jpeg",
    "color_histograms": {
        "red": [1, 5, 4, 13, 12, 10, 14, 16, 31, 20, 30, 38, 77, 150, 376, 610, 761, 703, 839, 909, 1118, 1483, 961, 258, 216, 224, 259, 234, 218, 195, 145, 70],
        "green": [1, 5, 10, 12, 17, 19, 24, 34, 30, 30, 63, 62, 118, 125, 220, 347, 635, 891, 890, 843, 682, 510, 740, 1140, 1507, 773, 77, 62, 59, 46, 24, 4],
        "blue": [4, 5, 23, 29, 59, 95, 184, 364, 637, 970, 1111, 1026, 974, 821, 673, 889, 1183, 441, 76, 55, 51, 44, 41, 46, 47, 52, 37, 33, 18, 8, 4, 0],
        "combined": [/* combined RGB histogram */]
    },
    "gradients": [0.094623997622785, 0.09709568267504787, /* ... 36 gradient values */],
    "textures": [0.0, 0.0, 0.0, /* ... 26 texture values */, 1.0, 0.0]
}

Features API Response​

{
    "filename": "dog.jpeg",
    "angles": [50.648247373735266, 38.65980825409009, 23.629377730656817, /* ... */],
    "distances": [64.66065264130884, 102.44998779892558, 87.32124598286491, /* ... */],
    "descriptors": [0.3984375, 0.4609375, 0.51953125, /* ... */]
}

Sample Requests​

Process API - Visual Features​

import requests

url = 'https://vision.heimdallapp.org/vision/v1/api/process'
headers = {
    'X-api-key': 'YOUR-API-KEY',
    'X-username': 'YOUR-USERNAME'
}

# Upload image file
with open('image.jpg', 'rb') as image_file:
    files = {'file': ('image.jpg', image_file, 'image/jpeg')}
    response = requests.post(url, headers=headers, files=files)

if response.status_code == 200:
    result = response.json()
    print(f"Analyzed: {result['filename']}")
    print(f"Color histogram bins: {len(result['color_histograms']['red'])}")
    print(f"Gradient features: {len(result['gradients'])}")
    print(f"Texture features: {len(result['textures'])}")

Features API - Key Points​

import requests

url = 'https://vision.heimdallapp.org/vision/v1/api/features'
headers = {
    'X-api-key': 'YOUR-API-KEY',
    'X-username': 'YOUR-USERNAME'
}

# Upload image file
with open('image.jpg', 'rb') as image_file:
    files = {'file': ('image.jpg', image_file, 'image/jpeg')}
    response = requests.post(url, headers=headers, files=files)

if response.status_code == 200:
    result = response.json()
    print(f"Analyzed: {result['filename']}")
    print(f"Key points found: {len(result['angles'])}")
    print(f"Average distance: {sum(result['distances']) / len(result['distances']):.2f}")

Use Cases​

Product Categorization​

# Analyze product images for categorization
def categorize_product(image_features):
    # Use color histograms to determine product category
    red_hist = image_features['color_histograms']['red']
    green_hist = image_features['color_histograms']['green']
    blue_hist = image_features['color_histograms']['blue']
    
    # Calculate dominant colors
    dominant_red = red_hist.index(max(red_hist))
    dominant_green = green_hist.index(max(green_hist))
    dominant_blue = blue_hist.index(max(blue_hist))
    
    # Simple categorization logic
    if dominant_red > 20 and dominant_green < 10:
        return "Red Product"
    elif dominant_green > 20 and dominant_blue < 10:
        return "Green Product"
    else:
        return "Mixed Color Product"

Image Similarity​

# Compare images using feature descriptors
def compare_images(features1, features2):
    # Use descriptors for similarity comparison
    desc1 = features1['descriptors']
    desc2 = features2['descriptors']
    
    # Calculate cosine similarity
    import numpy as np
    dot_product = np.dot(desc1, desc2)
    norm1 = np.linalg.norm(desc1)
    norm2 = np.linalg.norm(desc2)
    
    similarity = dot_product / (norm1 * norm2)
    return similarity

Quality Assessment​

# Assess image quality using gradients and textures
def assess_image_quality(image_features):
    gradients = image_features['gradients']
    textures = image_features['textures']
    
    # Calculate gradient variance (higher = more detail)
    gradient_variance = np.var(gradients)
    
    # Calculate texture complexity
    texture_complexity = sum(textures)
    
    if gradient_variance > 0.1 and texture_complexity > 0.5:
        return "High Quality"
    elif gradient_variance > 0.05:
        return "Medium Quality"
    else:
        return "Low Quality"

Error Handling​

422 Unprocessable Entity

You will receive a 422 error if your request body structure is incorrect.

Common issues:

  • Invalid image format
  • Corrupted image file
  • Missing required headers
  • File too large

Next Steps​

Now that you can analyze images:

  1. Use The Forge - Batch process images with The Forge
  2. Build ML Models - Use image features in machine learning
  3. Deploy in Production - Integrate image analysis into your applications