Skip to main content

Image analysis (Vision)

Extract color, texture, gradient, and ORB features from images via REST API.

Before you start

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. Lake unstructured ingest — Batch process images into bronze tables
  2. Build an ML model — Train on gold features from Lake
  3. Deploy in Production - Integrate image analysis into your applications