image-analyser

Static image analysis (CLI + FastAPI) for the analyser family.

Given a single image file, image-analyser returns:

• Format — JPEG / PNG / WebP / AVIF / HEIC / GIF / TIFF / BMP, MIME type, resolution, megapixels, aspect class, colour mode, bit depth, alpha, file size.
• Hashes — SHA-256 of bytes, perceptual pHash and dHash for dedup.
• Metadata — EXIF (camera, lens, ISO, GPS, timestamp), IPTC, XMP, ICC profile, C2PA Content Credentials.
• Quality — blur (Laplacian variance), exposure (under / over / clipping), brightness, contrast, noise, JPEG-quality estimate.
• Colour — k-means dominant palette + average colour.
• Barcodes / QR codes — via pyzbar.
• Animation — frame count + duration for GIF / WebP.
• Object detection (opt-in [ml]) — DETR by default; configurable HuggingFace pipeline.
• Caption / textual description (opt-in [ml] or [api]) — local BLIP, or one of Anthropic / OpenAI / Google / OpenRouter.
• OCR (opt-in [ocr]) — Tesseract or EasyOCR.

Anything that can't run in the current install lands in result.skipped[] with a stable reason. Anything that raises lands in result.failed[]. The HTTP response stays 200.

Install

pip install image-analyser              # Tier 1 only
pip install image-analyser[ml]          # + DETR object detection + local BLIP captioning
pip install image-analyser[ocr]         # + Tesseract / EasyOCR
pip install image-analyser[api]         # + API captioning (no torch needed)
pip install image-analyser[all]         # everything

System dependencies:

• libzbar0 (for barcode/QR detection): brew install zbar / apt install libzbar0
• libmagic (for MIME detection): brew install libmagic / apt install libmagic1
• tesseract (only if [ocr] extra used and tesseract is the engine): brew install tesseract / apt install tesseract-ocr

CLI

image-analyser photo.jpg                          # pretty JSON
image-analyser photo.jpg --json                   # compact JSON
image-analyser photo.jpg --skip caption,ocr       # opt out
image-analyser photo.jpg --only metadata,quality  # opt in
image-analyser photo.jpg --caption-backend local  # force local BLIP
image-analyser serve                              # FastAPI on :8006
image-analyser serve --port 9000

Legal --skip / --only values: metadata, quality, colour, hashing, barcode, objects, caption, ocr.

Exit codes: 0 on success (even with failed[]), 2 on bad input, 1 on internal error.

HTTP API

# Multipart upload
curl -F file=@photo.jpg http://127.0.0.1:8006/analyse

# JSON with absolute path
curl -X POST -H "Content-Type: application/json" \
  -d '{"path":"/abs/path/photo.jpg","skip":["caption"]}' \
  http://127.0.0.1:8006/analyse

# Health check
curl http://127.0.0.1:8006/health
# {"status": "ok", "version": "0.1.0"}

Python library

from image_analyser import ImageAnalyser

result = ImageAnalyser().analyse("photo.jpg")
print(result.metadata.exif.camera if result.metadata.exif else "no EXIF")
print(result.quality.blur_score, result.colour.dominant)
for s in result.skipped:
    print("skipped", s.name, "—", s.reason)

Configuration

All env vars use the IMAGE_ANALYSER_ prefix.

API keys: standard provider env vars (ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, OPENROUTER_API_KEY).

Development

git clone https://github.com/michael-borck/image-analyser
cd image-analyser
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,all]"
python tests/fixtures/make_fixtures.py
pytest                  # fast tests
pytest -m slow          # opt-in ML / engine tests
ruff check .
mypy src

The analyser family

Licence

MIT © Michael Borck.