# OpenCV Image Analyzer: Faces, Quality & Colors (`punkrecordsdata/opencv-image-analyzer`) Actor
Analyze image URLs with OpenCV: face detection with landmarks, blur and exposure scores, dominant colors and duplicate hashes. Export CSV, Excel, JSON, XML.
- **URL**: https://apify.com/punkrecordsdata/opencv-image-analyzer.md
- **Developed by:** [RecordsData](https://apify.com/punkrecordsdata) (community)
- **Categories:** Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet
## Pricing
from $11.25 / 1,000 image analyzeds
This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.
Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event
## What's an Apify Actor?
An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.
## How to integrate an Actor?
If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.
For examples already wired to this Actor's own input schema, see the [API](#api) section below.
Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).
# README
## 🔬 OpenCV Image Analyzer - PunkRecordsData
> 🚀 **Analyze any image URL in seconds.** The OpenCV Image Analyzer runs real computer vision on your image URLs and returns 22 structured fields per image: face detection with 5 facial landmarks and confidence scores, sharpness and exposure metrics, dominant color palettes, and perceptual hashes for duplicate detection. No AI API keys, no per-token costs, fully deterministic results you can export to CSV, Excel, JSON or XML.
The OpenCV Image Analyzer is an image analysis tool built on OpenCV 5, the industry-standard computer vision library, running YuNet (a modern deep-learning face detector) plus classic, battle-tested vision algorithms. Feed it a list of direct image URLs and it downloads each image, analyzes it inside the actor, and writes one structured row per image to the dataset. Nothing is sent to any third-party AI service: the whole analysis happens inside the run, which makes results reproducible, private and fast.
In a measured run, 5 images were fully analyzed (faces, quality, colors and hashes all enabled) in under 3 seconds of processing time. JPEG, PNG, WebP, GIF (first frame), AVIF, TIFF and SVG inputs are supported, up to 30 MB per image.
| 🎯 Target Audience | 💡 Primary Use Cases |
|---|---|
| E-commerce catalog managers | Flag blurry or badly exposed product photos before they go live |
| Content moderation and trust teams | Detect whether user avatars and uploads contain faces |
| Digital asset managers and archivists | Find near-duplicate images across large libraries with perceptual hashes |
| Marketing and brand teams | Extract dominant color palettes from creatives and competitor visuals |
| Data engineers | Enrich scraped image URLs with structured vision metadata in one pipeline step |
### 📋 What the OpenCV Image Analyzer does
- **Face detection with landmarks.** YuNet, OpenCV's deep-learning face detector, returns a bounding box, a confidence score and 5 facial landmarks (both eyes, nose, both mouth corners) for every face. You control the minimum confidence threshold.
- **Image quality metrics.** Sharpness score via variance of Laplacian, a blurry yes/no verdict, brightness, contrast, an exposure verdict (Normal / Overexposed / Underexposed) and the percentage of clipped shadows and highlights.
- **Dominant color extraction.** K-means clustering returns 1 to 10 dominant colors as hex codes with the percentage of the image each one covers, plus the average color.
- **Perceptual hashes for duplicate detection.** 64-bit aHash and dHash per image. Images whose hashes differ by only a few bits are visually near-identical, even across resizes and re-compressions.
- **File metadata.** Format, width, height, megapixels, aspect ratio and file size, read from the original file with EXIF orientation honored.
> 💡 **Why it matters:** every module is a real OpenCV computation, not an LLM guess. The same image always produces the same numbers, so you can build thresholds, alerts and pipelines on top of them. Each module is billed separately and can be switched off, so you only pay for the analysis you actually use.
### 📊 Output of the image analysis
One row per image, 22 fields:
| Field | Description |
|---|---|
| 🖼 `imageUrl` | The analyzed image (rendered as a thumbnail in the dataset view) |
| 📄 `format`, `width`, `height`, `megapixels`, `aspectRatio`, `fileSizeBytes` | File metadata from the original image |
| 🙂 `faceCount`, `faces` | Number of faces and, per face: box, confidence, eyes, nose, mouth corners |
| 🔪 `sharpnessScore`, `isBlurry` | Variance of Laplacian and a Yes/No blur verdict (threshold 100) |
| ☀️ `brightness`, `contrast`, `exposure` | Gray-level mean, standard deviation and exposure verdict |
| 🌓 `clippedShadowsPct`, `clippedHighlightsPct` | Percentage of pure-black and pure-white pixels |
| 🎨 `dominantColors`, `averageColorHex` | K-means palette with hex + coverage percent, and the mean color |
| 🔑 `aHash`, `dHash` | 64-bit perceptual hashes for near-duplicate detection |
| 🕒 `scrapedAt`, ❌ `error` | Analysis timestamp and error column (null on success) |
Real sample records from a live run:
```json
{
"imageUrl": "https://raw.githubusercontent.com/opencv/opencv/4.x/samples/data/messi5.jpg",
"format": "jpeg",
"width": 548,
"height": 342,
"megapixels": 0.19,
"aspectRatio": "274:171",
"fileSizeBytes": 72937,
"faceCount": 1,
"faces": [{ "x": 226, "y": 93, "width": 31, "height": 40, "confidence": 0.92,
"rightEye": [239, 106], "leftEye": [251, 107], "nose": [248, 114],
"mouthRight": [241, 121], "mouthLeft": [251, 122] }],
"sharpnessScore": 786.7,
"isBlurry": "No",
"brightness": 83.3,
"contrast": 46.4,
"exposure": "Normal",
"clippedShadowsPct": 1.3,
"clippedHighlightsPct": 0,
"dominantColors": [{ "hex": "#4d4047", "percent": 27.9 }, { "hex": "#1f2024", "percent": 25.6 }],
"averageColorHex": "#3d4938",
"aHash": "ffefe7e100383e00",
"dHash": "60644c9c9cb87c30",
"scrapedAt": "2026-09-28T14:59:39.929Z",
"error": null
}
```
```json
{
"imageUrl": "https://raw.githubusercontent.com/opencv/opencv/4.x/samples/data/starry_night.jpg",
"format": "jpeg", "width": 752, "height": 600, "faceCount": 0,
"sharpnessScore": 3035.9, "isBlurry": "No", "exposure": "Normal",
"dominantColors": [{ "hex": "#3a5882", "percent": 30.9 }, { "hex": "#16273f", "percent": 25.3 }],
"error": null
}
```
```json
{
"imageUrl": "https://raw.githubusercontent.com/opencv/opencv/4.x/samples/data/lena.jpg",
"format": "jpeg", "width": 512, "height": 512, "faceCount": 1,
"faces": [{ "x": 208, "y": 183, "width": 146, "height": 207, "confidence": 0.91 }],
"sharpnessScore": 387.1, "brightness": 124.2, "averageColorHex": "#b46469",
"aHash": "be98bd8d8b0b8f8c", "error": null
}
```
### ✨ Why choose this image analyzer
- **Deterministic, not generative.** Same image in, same 22 numbers out. Build reliable thresholds and automations on top of the output.
- **Private by design.** Images are processed inside the actor run. No image bytes ever leave for a third-party AI API.
- **Pay only for the modules you use.** Face detection, quality metrics, colors and hashes are separate billable events with their own on/off switches.
- **Modern face detection.** YuNet (2023 model) with landmarks and confidence scores, not the 2001-era Haar cascades most free tools still use.
- **Wide format support.** JPEG, PNG, WebP, GIF, AVIF, TIFF and SVG, up to 30 MB per image, EXIF orientation handled.
### 📈 How the OpenCV Image Analyzer compares to alternatives
| | This actor | Typical AI image analyzers |
|---|---|---|
| Analysis engine | OpenCV 5 computer vision | LLM / vision API calls |
| Deterministic output | Yes, always | No, answers vary per run |
| Face landmarks + confidence | Yes, per face | Rarely |
| Perceptual hashes for dedup | Yes (aHash + dHash) | No |
| Billable events | 5 separate, switchable | 1 flat fee per image |
| Image privacy | Never leaves the run | Sent to external AI provider |
Honest ceilings: analysis runs on a downsampled copy for very large sources (max 4096 px on the long side; reported dimensions are always the original's), face detection runs at up to 1280 px with boxes scaled back, and animated GIFs are analyzed on their first frame only. It does not describe image content in natural language; for captions you want an AI captioning tool, for measurable vision facts you want this one.
### 🚀 How to use the OpenCV Image Analyzer
1. Create a free Apify account (comes with $5 of platform credit) at console.apify.com.
2. Open the OpenCV Image Analyzer actor page and click **Try for free**.
3. Paste your image URLs into the **Image URLs** field (one per line, or import from a file/URL list).
4. Toggle the analysis modules you need: faces, quality, colors, hashes.
5. Click **Start**. Each image becomes one dataset row.
6. Download the results as CSV, Excel, JSON or XML from the **Storage** tab, or pull them via API.
### 💼 Business use cases
#### E-commerce photo QA
Run every product image through the quality module and reject uploads with `isBlurry: "Yes"`, `exposure: "Overexposed"` or more than 5% clipped highlights before they reach the storefront.
#### Avatar and profile moderation
Check that user profile pictures actually contain exactly one face with confidence above 0.8, and flag empty or group photos for review.
#### Deduplicating scraped image libraries
After scraping thousands of product or real-estate photos, compare aHash/dHash values to collapse re-uploads, resizes and re-compressions of the same picture into one canonical asset.
#### Brand and creative analysis
Extract dominant color palettes from your ads and your competitors' creatives to track color strategies across campaigns with concrete hex values and coverage percentages.
### 🔌 Automating the OpenCV Image Analyzer
Connect the actor to **Make**, **Zapier**, **Slack**, **Airbyte**, **GitHub** or **Google Drive** through Apify's native integrations: trigger a run whenever new image URLs land in a spreadsheet, push quality alerts into a Slack channel, or sync the analysis dataset into your warehouse on a schedule. The actor also works as a pipeline step after any scraper that outputs image URLs.
### 🌟 Beyond business use cases
- **Research:** batch-compute sharpness and exposure statistics across photo datasets for computer vision or photography studies.
- **Personal:** find duplicates and near-duplicates in a personal photo export before archiving it.
- **Non-profit:** audit accessibility and quality of imagery across a website without manual review.
- **Experimentation:** a zero-setup OpenCV playground; test YuNet detections and k-means palettes on any URL without installing anything.
### 🤖 Ask an AI assistant about this scraper
Copy this into ChatGPT, Claude or Perplexity to evaluate the actor for your use case:
> "I have a list of image URLs and need structured data about each image: whether it contains faces, whether it is blurry, its dominant colors and a hash to detect duplicates. Would the OpenCV Image Analyzer on Apify (apify.com/punkrecordsdata/opencv-image-analyzer) cover this, and how would I wire it into my pipeline?"
### ❓ Frequently Asked Questions
#### 🙂 How do I detect faces in a batch of images without an AI API key?
Enable the face detection module and run the actor on your URL list. Each face comes back with a bounding box, a 0-1 confidence score and 5 landmarks. No external API or key is involved.
#### 🌫 How do I check if an image is blurry programmatically?
The quality module computes the variance of Laplacian (`sharpnessScore`). Below 100 the actor marks `isBlurry: "Yes"`. The raw score is included so you can set your own stricter threshold.
#### 🔑 How do I find duplicate images with different file names or sizes?
Compare the `aHash` and `dHash` fields. Count differing bits between two hashes (Hamming distance); 0-5 differing bits out of 64 means the images are visually the same picture.
#### 🎨 Can it extract the color palette of an image as hex codes?
Yes. The dominant colors module runs k-means clustering and returns each color as a hex code with the percentage of the image it covers, plus an average color. Palette size is configurable from 1 to 10.
#### 📄 What image formats are supported?
JPEG, PNG, WebP, GIF (first frame), AVIF, TIFF and SVG, up to 30 MB per file.
#### 🖼 Does it work on images behind a CDN or hotlink protection?
Most CDNs serve images openly and work with the default settings. If a host blocks datacenter IPs, enable the Apify Proxy option in the input.
#### 🔒 Are my images sent to any third-party AI service?
No. All analysis runs inside the actor container with OpenCV compiled to WebAssembly. Image bytes never leave the run.
#### 💵 Do I pay for modules I switch off?
No. Each module (faces, quality, colors, hashes) is a separate billable event charged only when it actually runs. Failed downloads are never charged.
#### 🎯 How accurate is the face detection?
It uses YuNet (2023), a modern DNN detector that clearly outperforms classic Haar cascades, and reports a confidence score per face so you can filter as strictly as you need. Very small or heavily occluded faces below your confidence threshold are dropped.
#### 📦 Can I analyze thousands of images in one run?
Yes. Paid plans support up to 1,000,000 images per run; images are streamed one at a time with a prefetch pipeline, so memory stays flat. Free users get a 10-image preview.
#### ⚙️ What happens when one URL is broken?
The actor writes an error row for that URL (with the HTTP status or decode error) and continues. Error rows are never billed.
#### 📤 How do I export the results?
Open the run's dataset and download CSV, Excel, JSON or XML, or fetch the same data through the Apify API for automation.
### 🔌 Integrate with any app
Every run's dataset is available through the Apify API in JSON, CSV, Excel or XML, so you can pull results into Python, Node.js, Google Sheets, Power BI or any HTTP-capable tool. Webhooks can notify your systems the moment a run finishes.
### 🔗 Recommended Actors
- [Pinterest Scraper](https://apify.com/punkrecordsdata/pinterest-scraper) - collect pins and boards, then analyze their images here
- [TikTok Scraper](https://apify.com/punkrecordsdata/tiktok-scraper) - profiles and posts with cover images ready for analysis
- [MercadoLibre Scraper](https://apify.com/punkrecordsdata/mercadolibre-scraper) - product listings with photos across 18 countries
- [Pokemon Cards Scraper](https://apify.com/punkrecordsdata/pokemon-cards-scraper) - card data and imagery for collectors
> 💡 **Pro Tip:** browse the complete [PunkRecordsData collection](https://apify.com/punkrecordsdata) for more data tools.
**🆘 Need Help?** contact.punkrecordsdata@gmail.com
> **⚠️ Disclaimer:** independent tool. Downloads and analyzes only the image URLs you provide; make sure you have the right to process them. Sample images referenced above are the OpenCV project's own public samples.
# Actor input Schema
## `imageUrls` (type: `array`):
Direct URLs of the images to analyze. JPEG, PNG, WebP, GIF (first frame), AVIF, TIFF and SVG are supported.
## `maxItems` (type: `integer`):
Free users: Limited to 10 items (preview). Paid users: Optional, max 1,000,000
## `detectFaces` (type: `boolean`):
Detect faces with OpenCV's YuNet deep-learning detector: bounding box, confidence score and 5 facial landmarks (eyes, nose, mouth corners) per face.
## `minFaceConfidence` (type: `integer`):
Faces below this confidence score are discarded. 60 is a good default; lower it to catch small/partial faces, raise it to keep only frontal, clear faces.
## `qualityMetrics` (type: `boolean`):
Sharpness score (variance of Laplacian), blurry yes/no, brightness, contrast, exposure verdict and clipped shadows/highlights percentages.
## `extractColors` (type: `boolean`):
Extract the dominant color palette via k-means clustering: hex code and coverage percentage per color, plus the average color.
## `colorCount` (type: `integer`):
How many dominant colors to extract per image (k in k-means).
## `perceptualHash` (type: `boolean`):
64-bit average hash and difference hash for near-duplicate detection. Images with a small Hamming distance between hashes are visually similar.
## `proxyConfiguration` (type: `object`):
Most image CDNs are open, so no proxy is needed by default. Enable Apify Proxy only if the image host blocks datacenter IPs.
## Actor input object example
```json
{
"imageUrls": [
{
"url": "https://raw.githubusercontent.com/opencv/opencv/4.x/samples/data/lena.jpg"
},
{
"url": "https://raw.githubusercontent.com/opencv/opencv/4.x/samples/data/messi5.jpg"
},
{
"url": "https://raw.githubusercontent.com/opencv/opencv/4.x/samples/data/fruits.jpg"
},
{
"url": "https://raw.githubusercontent.com/opencv/opencv/4.x/samples/data/starry_night.jpg"
},
{
"url": "https://raw.githubusercontent.com/opencv/opencv/4.x/samples/data/baboon.jpg"
}
],
"maxItems": 10,
"detectFaces": true,
"minFaceConfidence": 60,
"qualityMetrics": true,
"extractColors": true,
"colorCount": 5,
"perceptualHash": true,
"proxyConfiguration": {
"useApifyProxy": false
}
}
```
# Actor output Schema
## `overview` (type: `string`):
Key fields per analyzed image
## `fullData` (type: `string`):
Complete dataset with all 22 fields
# API
You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.
## JavaScript example
```javascript
import { ApifyClient } from 'apify-client';
// Initialize the ApifyClient with your Apify API token
// Replace the '' with your token
const client = new ApifyClient({
token: '',
});
// Prepare Actor input
const input = {
"imageUrls": [
{
"url": "https://raw.githubusercontent.com/opencv/opencv/4.x/samples/data/lena.jpg"
},
{
"url": "https://raw.githubusercontent.com/opencv/opencv/4.x/samples/data/messi5.jpg"
},
{
"url": "https://raw.githubusercontent.com/opencv/opencv/4.x/samples/data/fruits.jpg"
},
{
"url": "https://raw.githubusercontent.com/opencv/opencv/4.x/samples/data/starry_night.jpg"
},
{
"url": "https://raw.githubusercontent.com/opencv/opencv/4.x/samples/data/baboon.jpg"
}
],
"maxItems": 10
};
// Run the Actor and wait for it to finish
const run = await client.actor("punkrecordsdata/opencv-image-analyzer").call(input);
// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
console.dir(item);
});
// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs
```
## Python example
```python
from apify_client import ApifyClient
# Initialize the ApifyClient with your Apify API token
# Replace '' with your token.
client = ApifyClient("")
# Prepare the Actor input
run_input = {
"imageUrls": [
{ "url": "https://raw.githubusercontent.com/opencv/opencv/4.x/samples/data/lena.jpg" },
{ "url": "https://raw.githubusercontent.com/opencv/opencv/4.x/samples/data/messi5.jpg" },
{ "url": "https://raw.githubusercontent.com/opencv/opencv/4.x/samples/data/fruits.jpg" },
{ "url": "https://raw.githubusercontent.com/opencv/opencv/4.x/samples/data/starry_night.jpg" },
{ "url": "https://raw.githubusercontent.com/opencv/opencv/4.x/samples/data/baboon.jpg" },
],
"maxItems": 10,
}
# Run the Actor and wait for it to finish
run = client.actor("punkrecordsdata/opencv-image-analyzer").call(run_input=run_input)
# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
print(item)
# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start
```
## CLI example
```bash
echo '{
"imageUrls": [
{
"url": "https://raw.githubusercontent.com/opencv/opencv/4.x/samples/data/lena.jpg"
},
{
"url": "https://raw.githubusercontent.com/opencv/opencv/4.x/samples/data/messi5.jpg"
},
{
"url": "https://raw.githubusercontent.com/opencv/opencv/4.x/samples/data/fruits.jpg"
},
{
"url": "https://raw.githubusercontent.com/opencv/opencv/4.x/samples/data/starry_night.jpg"
},
{
"url": "https://raw.githubusercontent.com/opencv/opencv/4.x/samples/data/baboon.jpg"
}
],
"maxItems": 10
}' |
apify call punkrecordsdata/opencv-image-analyzer --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"type": "http",
"url": "https://mcp.apify.com/?tools=fetch-actor-details,punkrecordsdata/opencv-image-analyzer"
}
}
}
```
The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).
## OpenAPI specification
Download the OpenAPI definition: https://api.apify.com/v2/actors/IkLW1h6xhVxM3UiYz/builds/kJ8YagjbFWywflaBq/openapi.json