Oyyi

Image Histogram

Generate a histogram of pixel values for an image, providing detailed distribution data for color or grayscale channels.

POST /api/image/histogram-equalization

Request Parameters

ParameterTypeRequiredDescription
fileFileYesThe image file to analyze. Supported formats: JPEG, PNG, WebP, BMP, TIFF, GIF.
binsIntegerNoThe number of bins (buckets) for the histogram. Options: 8, 16, 32, 64, 128, 256. Default: 256.
normalizeBooleanNoWhether to normalize the histogram values to the range 0-1. Default: false.
cumulativeBooleanNoWhether to return a cumulative histogram. Default: false.
include_statisticsBooleanNoWhether to include statistical information (min, max, mean, median, standard deviation) for each channel. Default: true.

Response

Returns a JSON object containing histogram data for each requested color channel, with optional statistical information.

Example Request

    // example.sh
curl -X POST "https://oyyi.xyz/api/image/histogram"   -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@image.jpg" \
  -F "channels=rgb" \
  -F "bins=256"
  

Example with Python

    // plot_histogram.py
import requests
import json
import matplotlib.pyplot as plt
import numpy as np

url = "https://oyyi.xyz/api/image/histogram"

files = {
    'file': open('image.jpg', 'rb')
}

data = {
    'channels': 'rgb',
    'bins': 256
}

response = requests.post(url, files=files, data=data)

# Parse the JSON response
histogram_data = response.json()

# Plot the histogram
plt.figure(figsize=(12, 6))
x = np.arange(len(histogram_data['r']))
plt.bar(x, histogram_data['r'], color='r', alpha=0.5, label='Red')
plt.bar(x, histogram_data['g'], color='g', alpha=0.5, label='Green')
plt.bar(x, histogram_data['b'], color='b', alpha=0.5, label='Blue')
plt.legend()
plt.title('RGB Histogram')
plt.xlabel('Pixel Value')
plt.ylabel('Frequency')
plt.savefig('histogram.png')
plt.show()
  

Example with JavaScript

    // plot_histogram.js
// Using fetch API
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('channels', 'rgb');
formData.append('bins', '256');

fetch('https://oyyi.xyz/api/image/histogram-equalization', {
  method: 'POST',
  body: formData
})
.then(response => response.json())
.then(histogramData => {
  console.log(histogramData);

  // Example: Plot histogram using Chart.js
  const ctx = document.getElementById('histogramChart').getContext('2d');
  const labels = Array.from({length: histogramData.r.length}, (_, i) => i);

  new Chart(ctx, {
    type: 'line',
    data: {
      labels: labels,
      datasets: [
        {
          label: 'Red',
          data: histogramData.r,
          borderColor: 'rgba(255, 99, 132, 1)',
          backgroundColor: 'rgba(255, 99, 132, 0.2)',
          fill: true
        },
        {
          label: 'Green',
          data: histogramData.g,
          borderColor: 'rgba(75, 192, 192, 1)',
          backgroundColor: 'rgba(75, 192, 192, 0.2)',
          fill: true
        },
        {
          label: 'Blue',
          data: histogramData.b,
          borderColor: 'rgba(54, 162, 235, 1)',
          backgroundColor: 'rgba(54, 162, 235, 0.2)',
          fill: true
        }
      ]
    },
    options: {
      responsive: true,
      title: {
        display: true,
        text: 'Image Histogram'
      }
    }
  });
})
.catch(error => console.error('Error:', error));
  

Example Response

    // response.json
{
  "r": [0, 12, 45, 78, 156, 234, 567, 890, ...],
  "g": [0, 23, 67, 134, 256, 345, 456, 678, ...],
  "b": [0, 34, 89, 145, 278, 367, 489, 567, ...],
  "luminance": [0, 21, 65, 123, 234, 345, 456, 678, ...],
  "channels": "rgb",
  "bins": 256,
  "statistics": {
    "r": {
      "min": 0,
      "max": 255,
      "mean": 127.45,
      "median": 130,
      "std_dev": 45.67
    },
    "g": {
      "min": 0,
      "max": 255,
      "mean": 135.78,
      "median": 142,
      "std_dev": 42.31
    },
    "b": {
      "min": 0,
      "max": 255,
      "mean": 118.92,
      "median": 115,
      "std_dev": 48.45
    },
    "luminance": {
      "min": 0,
      "max": 255,
      "mean": 128.72,
      "median": 132,
      "std_dev": 43.21
    }
  }
}
  

Channel Options

RGB

Returns histograms for the Red, Green, and Blue channels, plus a luminance histogram. Good for analyzing color distribution in standard color images.

HSV

Returns histograms for Hue, Saturation, and Value channels. Good for analyzing color properties in a more perceptually relevant way.

Grayscale

Returns a single histogram for the grayscale intensity values. Good for analyzing brightness distribution or for grayscale images.

All

Returns histograms for RGB, HSV, and grayscale channels. Comprehensive but results in a larger response.

Response Structure

FieldDescription
r, g, bArrays containing the histogram values for the Red, Green, and Blue channels (if RGB or All channels are requested).
h, s, vArrays containing the histogram values for the Hue, Saturation, and Value channels (if HSV or All channels are requested).
luminance or grayscaleArray containing the histogram values for the luminance/grayscale channel.
channelsThe channels that were requested.
binsThe number of bins used for the histogram.
statistics

Statistical information for each channel (if include_statistics is true):

  • min: The minimum pixel value
  • max: The maximum pixel value
  • mean: The average pixel value
  • median: The median pixel value
  • std_dev: The standard deviation of pixel values

How It Works

The histogram endpoint analyzes the distribution of pixel values in an image:

  1. Image Loading: The image is loaded and converted to the appropriate color space (RGB, HSV, or grayscale).
  2. Histogram Calculation: For each requested channel, the pixel values are counted and grouped into the specified number of bins.
  3. Normalization (Optional): If requested, the histogram values are normalized to the range 0-1 by dividing by the total number of pixels.
  4. Cumulative Calculation (Optional): If requested, each bin value is the sum of that bin and all previous bins, showing the cumulative distribution.
  5. Statistics Calculation (Optional): If requested, statistical measures like mean, median, and standard deviation are calculated for each channel.
  6. Response Formatting: The histogram data and statistics are formatted into a JSON response.

The result is a detailed analysis of the pixel value distribution in the image, which can be used for image analysis, comparison, or visualization.

Bin Size Comparison

Fewer Bins (8-32)

Smoother histogram, less detail, smaller response size

Medium Bins (64-128)

Balanced detail and smoothness

More Bins (256)

Maximum detail, shows fine variations, larger response size

Error Responses

Status CodeDescription
400Bad request. Missing required parameters, invalid channels value, invalid bins value, invalid normalize value, invalid cumulative value, invalid include_statistics value, or invalid file format.
413Payload too large. The file size exceeds the maximum allowed limit.
500Internal server error. Something went wrong on the server.

Notes

  • Histograms are useful for understanding the tonal distribution and contrast of an image.
  • For RGB images, the luminance histogram is calculated using a weighted sum of the RGB channels (0.299R + 0.587G + 0.114B).
  • The normalize parameter is useful when comparing histograms of images with different sizes.
  • The cumulative parameter is useful for analyzing the overall distribution of brightness or color.
  • For HSV histograms, the Hue channel is typically represented in the range 0-360 degrees, while Saturation and Value are in the range 0-100%.
  • The maximum file size allowed is 20MB.
  • For very large images, the histogram calculation may take longer, but the response size depends only on the number of bins, not the image size.

Use Cases

  • Analyzing image exposure and contrast
  • Detecting over or underexposed areas in photographs
  • Comparing color distributions between images
  • Creating histogram equalization algorithms for image enhancement
  • Identifying color casts or white balance issues
  • Analyzing the effectiveness of image adjustments
  • Creating data visualizations of image properties
  • Developing automatic image classification or categorization systems
  • Quality control for image processing pipelines