Image Histogram
Generate a histogram of pixel values for an image, providing detailed distribution data for color or grayscale channels.
/api/image/histogram-equalization
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
file | File | Yes | The image file to analyze. Supported formats: JPEG, PNG, WebP, BMP, TIFF, GIF. |
bins | Integer | No | The number of bins (buckets) for the histogram. Options: 8 , 16 , 32 , 64 , 128 , 256 . Default: 256 . |
normalize | Boolean | No | Whether to normalize the histogram values to the range 0-1. Default: false . |
cumulative | Boolean | No | Whether to return a cumulative histogram. Default: false . |
include_statistics | Boolean | No | Whether 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
Field | Description |
---|---|
r , g , b | Arrays containing the histogram values for the Red, Green, and Blue channels (if RGB or All channels are requested). |
h , s , v | Arrays containing the histogram values for the Hue, Saturation, and Value channels (if HSV or All channels are requested). |
luminance or grayscale | Array containing the histogram values for the luminance/grayscale channel. |
channels | The channels that were requested. |
bins | The number of bins used for the histogram. |
statistics | Statistical information for each channel (if include_statistics is true):
|
How It Works
The histogram endpoint analyzes the distribution of pixel values in an image:
- Image Loading: The image is loaded and converted to the appropriate color space (RGB, HSV, or grayscale).
- Histogram Calculation: For each requested channel, the pixel values are counted and grouped into the specified number of bins.
- Normalization (Optional): If requested, the histogram values are normalized to the range 0-1 by dividing by the total number of pixels.
- Cumulative Calculation (Optional): If requested, each bin value is the sum of that bin and all previous bins, showing the cumulative distribution.
- Statistics Calculation (Optional): If requested, statistical measures like mean, median, and standard deviation are calculated for each channel.
- 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 Code | Description |
---|---|
400 | Bad request. Missing required parameters, invalid channels value, invalid bins value, invalid normalize value, invalid cumulative value, invalid include_statistics value, or invalid file format. |
413 | Payload too large. The file size exceeds the maximum allowed limit. |
500 | Internal 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