minosse 0.1.0__py3-none-any.whl

minosse/__init__.py

@@ -0,0 +1 @@
+from .detector import analyze, analyze_path, Result

minosse/__main__.py

@@ -0,0 +1,2 @@
+from .cli import main
+raise SystemExit(main())

minosse/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

minosse/cli.py

@@ -0,0 +1,49 @@
+"""Command line entry point.
+
+usage: python -m minosse [--proof [DIR]] <image> [image ...]
+
+--proof renders a side-by-side evidence sheet per image (original plus
+red heatmap panels for each fired signal) as <name>_proof.png, saved in
+DIR if given, else next to the input image.
+"""
+
+import os
+import sys
+
+from PIL import Image
+
+from .detector import analyze
+from .evidence import render
+
+
+def main(argv=None):
+    args = list(argv if argv is not None else sys.argv[1:])
+    proof = False
+    proof_dir = None
+    if "--proof" in args:
+        i = args.index("--proof")
+        args.pop(i)
+        if i < len(args) and os.path.isdir(args[i]):
+            proof_dir = args.pop(i)
+        proof = True
+    if not args:
+        print(__doc__.strip())
+        return 2
+    for path in args:
+        img = Image.open(path)
+        r = analyze(img)
+        print(f"{path}")
+        print(f"  signals : {', '.join(r.reasons) if r.reasons else 'none'}")
+        print(f"  decay={r.decay:.4f} vhf_mf={r.vhf_mf:.3f} "
+              f"resid_std={r.resid_std:.4f} flat_noise={r.flat_noise:.4f}")
+        print(f"  verdict : {r.verdict}")
+        if proof:
+            base = os.path.splitext(os.path.basename(path))[0] + "_proof.png"
+            out = os.path.join(proof_dir or os.path.dirname(path) or ".", base)
+            render(img, r).save(out)
+            print(f"  proof   : {out}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

minosse/detector.py

@@ -0,0 +1,110 @@
+"""Minosse — detect AI-generated / AI-edited images.
+
+Three complementary signals, each targeting a different artifact class:
+
+ringing
+    Diffusion VAE decoders leave oscillating ripple halos around
+    high-contrast strokes (text, UI borders). Measured as a radial
+    profile of band-passed energy vs. distance from strong edges:
+    real edges decay fast, ringing persists 10-40 px out.
+
+noisy-flats
+    AI images (and AI "film grain") carry noise in regions that should
+    be perfectly flat — solid UI panels, plain backgrounds. Real
+    screenshots have truly flat flats, and JPEG smooths photo flats.
+
+synthetic-noise
+    Generated/upsampled noise dies out before the Nyquist frequency,
+    while real sensor noise stays hot at the highest frequencies. An
+    image with strong overall residual noise but a cold top ring of the
+    spectrum — and noise present even in flat regions — is synthetic.
+
+Thresholds were tuned on data/clean (65 real photos + screenshots) and
+data/dirty (5 AI-generated/edited): 5/5 detected, 0/65 false positives.
+"""
+
+from dataclasses import dataclass, field
+
+import numpy as np
+from PIL import Image
+from scipy import ndimage
+
+_DIST_BINS = [(3, 6), (6, 10), (10, 15), (15, 25), (25, 40), (40, 60), (60, 120)]
+
+
+@dataclass
+class Result:
+    decay: float          # halo persistence: mid-distance / near-edge energy
+    halo_vs_bg: float     # mid-distance energy vs image's own background
+    vhf_mf: float         # spectral energy at Nyquist ring vs mid frequencies
+    resid_std: float      # overall noise-residual strength
+    flat_noise: float     # RMS residual inside coarse-flat regions
+    reasons: list = field(default_factory=list)
+    score: float = 0.0
+    verdict: str = ""
+
+
+def _features(img: Image.Image) -> dict:
+    img = img.convert("RGB")
+    if max(img.size) > 1600:
+        s = 1600 / max(img.size)
+        img = img.resize((int(img.width * s), int(img.height * s)), Image.LANCZOS)
+    a = np.asarray(img, dtype=np.float64) / 255.0
+    g = a.mean(2)
+
+    # --- ringing: band energy vs distance from strong edges
+    grad = np.hypot(ndimage.sobel(g, axis=1), ndimage.sobel(g, axis=0))
+    edge = grad > np.quantile(grad, 0.97)
+    band = ndimage.gaussian_filter(g, 0.8) - ndimage.gaussian_filter(g, 3.0)
+    energy = ndimage.uniform_filter(band * band, size=5)
+    dist = ndimage.distance_transform_edt(~edge)
+    prof = []
+    for d0, d1 in _DIST_BINS:
+        m = (dist >= d0) & (dist < d1)
+        prof.append(float(np.median(energy[m])) if m.any() else 0.0)
+    p = np.array(prof) + 1e-12
+    decay = float(np.median(p[2:5]) / p[0])
+    halo_vs_bg = float(np.median(p[2:5]) / np.median(p[5:7]))
+
+    # --- spectral shape of the noise residual (center crop, windowed FFT)
+    h, w = g.shape
+    s2 = min(512, h, w)
+    y0, x0 = (h - s2) // 2, (w - s2) // 2
+    gc = g[y0:y0 + s2, x0:x0 + s2]
+    res_c = gc - ndimage.median_filter(gc, 3)
+    win = np.hanning(s2)
+    F = np.abs(np.fft.fftshift(np.fft.fft2(res_c * win[:, None] * win[None, :]))) ** 2
+    yy, xx = np.indices(F.shape)
+    r = np.hypot(yy - s2 / 2, xx - s2 / 2) / (s2 / 2)
+    ring = lambda a_, b_: F[(r >= a_) & (r < b_)].mean()
+    vhf_mf = float(ring(0.95, 1.2) / (ring(0.25, 0.5) + 1e-20))
+    resid_std = float(np.std(res_c))
+
+    # --- noise inside coarse-flat regions
+    coarse = ndimage.gaussian_filter(g, 4)
+    cgrad = np.hypot(ndimage.sobel(coarse, axis=1), ndimage.sobel(coarse, axis=0))
+    flat = cgrad <= np.quantile(cgrad, 0.20)
+    res = g - ndimage.median_filter(g, 3)
+    flat_noise = float(np.sqrt(np.mean(res[flat] ** 2)))
+
+    return dict(decay=decay, halo_vs_bg=halo_vs_bg, vhf_mf=vhf_mf,
+                resid_std=resid_std, flat_noise=flat_noise)
+
+
+def analyze(img: Image.Image) -> Result:
+    f = _features(img)
+    reasons = []
+    if f["vhf_mf"] < 0.22 and f["decay"] > 0.065:
+        reasons.append("ringing")
+    if f["flat_noise"] > 0.015:
+        reasons.append("noisy-flats")
+    if f["vhf_mf"] < 0.09 and f["resid_std"] > 0.02 and f["flat_noise"] > 0.001:
+        reasons.append("synthetic-noise")
+
+    score = min(1.0, 0.75 * len(reasons)) if reasons else 0.0
+    verdict = "likely AI-generated/edited" if reasons else "likely clean"
+    return Result(**f, reasons=reasons, score=score, verdict=verdict)
+
+
+def analyze_path(path: str) -> Result:
+    return analyze(Image.open(path))

minosse/evidence.py

@@ -0,0 +1,98 @@
+"""Render visual proof sheets: original image next to panels that
+highlight, in red, the spatial evidence behind each fired signal.
+
+- ringing        : band-passed oscillation energy in the halo zone
+                   (3-40 px from strong edges, off-stroke)
+- noisy-flats    : noise residual energy inside coarse-flat regions
+- synthetic-noise: amplified full-frame noise residual (its spatial
+                   texture is the evidence; spectrum stats in caption)
+"""
+
+import numpy as np
+from PIL import Image, ImageDraw
+from scipy import ndimage
+
+from .detector import Result, _features  # noqa: F401  (shared pipeline)
+
+_PANEL_W = 640
+
+
+def _prep(img: Image.Image):
+    img = img.convert("RGB")
+    if max(img.size) > 1600:
+        s = 1600 / max(img.size)
+        img = img.resize((int(img.width * s), int(img.height * s)), Image.LANCZOS)
+    g = np.asarray(img, dtype=np.float64) / 255.0
+    return img, g.mean(2)
+
+
+def _heat_overlay(base: Image.Image, heat: np.ndarray, gain: float = 1.0) -> Image.Image:
+    """Dim grayscale base with the heat map burned in as red."""
+    h = np.clip(heat * gain, 0, 1)
+    gray = np.asarray(base.convert("L"), dtype=np.float64) / 255.0 * 0.35
+    rgb = np.stack([gray + h * 0.65, gray + h * 0.10, gray], axis=-1)
+    return Image.fromarray((np.clip(rgb, 0, 1) * 255).astype(np.uint8))
+
+
+def _abs_norm(x: np.ndarray, full_scale: float) -> np.ndarray:
+    """Absolute scaling: `full_scale` maps to 1.0. Calibrated to the
+    detector thresholds so clean images render dark instead of being
+    stretched to look hot by per-image normalization."""
+    return np.clip(np.sqrt(np.clip(x, 0, None)) / full_scale, 0, 1)
+
+
+def _maps(g: np.ndarray) -> dict:
+    grad = np.hypot(ndimage.sobel(g, axis=1), ndimage.sobel(g, axis=0))
+    edge = grad > np.quantile(grad, 0.97)
+    band = ndimage.gaussian_filter(g, 0.8) - ndimage.gaussian_filter(g, 3.0)
+    energy = ndimage.uniform_filter(band * band, size=5)
+    dist = ndimage.distance_transform_edt(~edge)
+
+    coarse = ndimage.gaussian_filter(g, 4)
+    cgrad = np.hypot(ndimage.sobel(coarse, axis=1), ndimage.sobel(coarse, axis=0))
+    flat = cgrad <= np.quantile(cgrad, 0.20)
+    res = g - ndimage.median_filter(g, 3)
+
+    # Ringing evidence = oscillation where the image should be smooth:
+    # 8-40 px from a strong edge (past the 1-2 px overshoot every real
+    # edge has) AND locally flat at coarse scale, so legitimate texture
+    # (fabric, foliage, carpet) is excluded.
+    smooth = cgrad <= np.quantile(cgrad, 0.60)
+    halo = (dist >= 8) & (dist < 40) & smooth
+    ringing = np.where(halo, energy, 0.0)
+    flat_noise = np.where(flat, ndimage.uniform_filter(res * res, size=9), 0.0)
+
+    # full-scale values sit a bit above the detector's firing thresholds
+    return {
+        "ringing": _abs_norm(ringing, 0.007),
+        "noisy-flats": _abs_norm(flat_noise, 0.03),
+        "synthetic-noise": np.clip(np.abs(res) * 12, 0, 1),
+    }
+
+
+def render(img: Image.Image, result: Result) -> Image.Image:
+    """Build a proof sheet: original + one evidence panel per fired
+    signal (all three panels if nothing fired, for comparison)."""
+    base, g = _prep(img)
+    maps = _maps(g)
+    signals = result.reasons if result.reasons else list(maps)
+
+    scale = _PANEL_W / base.width
+    size = (_PANEL_W, int(base.height * scale))
+    panels = [("original", base.resize(size, Image.LANCZOS))]
+    for name in signals:
+        overlay = _heat_overlay(base, maps[name])
+        panels.append((name, overlay.resize(size, Image.LANCZOS)))
+
+    cap_h = 26
+    sheet = Image.new("RGB", (_PANEL_W * len(panels), size[1] + cap_h), (12, 12, 12))
+    draw = ImageDraw.Draw(sheet)
+    for i, (name, panel) in enumerate(panels):
+        sheet.paste(panel, (i * _PANEL_W, cap_h))
+        label = name if name == "original" else (
+            f"{name} {'[FIRED]' if name in result.reasons else '(not fired)'}")
+        draw.text((i * _PANEL_W + 8, 6), label,
+                  fill=(255, 80, 80) if name in result.reasons else (200, 200, 200))
+    draw.text((sheet.width - 320, 6), f"verdict: {result.verdict}",
+              fill=(255, 80, 80) if result.reasons else (120, 220, 120))
+    return sheet

minosse-0.1.0.dist-info/METADATA

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: minosse
+Version: 0.1.0
+Summary: Detects AI-generated or AI-edited images using signal-processing artifact analysis — no ML model.
+Project-URL: Homepage, https://github.com/cesp99/Minosse
+Project-URL: Issues, https://github.com/cesp99/Minosse/issues
+Author: cesp99
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-detection,diffusion,image-forensics,signal-processing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Requires-Dist: numpy
+Requires-Dist: pillow
+Requires-Dist: scipy
+Description-Content-Type: text/markdown
+
+# Minosse
+
+Detects AI-generated or AI-edited images using three complementary,
+hand-crafted artifact signals — **no ML model, just signal processing.**
+
+Minosse looks for tell-tale traces that diffusion models and neural
+upsamplers leave behind: ringing halos around text, noise in flat
+regions that shouldn't have any, and a synthetic signature in the
+high-frequency spectrum.
+
+## Signals
+
+| Signal | What it catches | How it works |
+|---|---|---|
+| **ringing** | Diffusion VAE decoder halos | Radial profile of band-pass energy vs. distance from strong edges. Real edges decay fast; ringing persists 10–40 px out. |
+| **noisy-flats** | AI "film grain" on solid panels | RMS residual noise inside coarse-flat regions. Real screenshots are truly flat; JPEG smooths photo flats. |
+| **synthetic-noise** | Upsampled / generated noise | Spectral energy at the Nyquist ring vs. mid frequencies. Real sensor noise stays hot at the highest frequencies; synthetic noise dies off. |
+
+An image is flagged if **any** signal fires; the fired signals are reported
+along with the raw feature values.
+
+
+## Quick start
+
+```bash
+python -m venv .venv
+.venv/bin/pip install -r requirements.txt
+
+# Analyse a single image
+.venv/bin/python -m minosse path/to/image.png
+
+# Analyse multiple images with visual proof sheets
+.venv/bin/python -m minosse --proof results/ image1.png image2.jpg
+```
+
+### `--proof` output
+
+The `--proof` flag writes `<name>_proof.png`: a side-by-side sheet with
+the original image next to one panel per fired signal, with the artifact
+evidence burned in as a **red heatmap**.
+
+Heat is scaled absolutely (calibrated to the detection thresholds), so
+clean images render dark — the glow itself is the proof. For ringing,
+the map only shows oscillation in regions that *should* be smooth (8–40 px
+from strong edges, locally flat at coarse scale), so legitimate texture
+doesn't light up.
+
+## Python API
+
+```python
+from minosse import analyze, analyze_path, Result
+
+# From a file path
+r = analyze_path("image.png")
+print(r.verdict)       # "likely AI-generated/edited" or "likely clean"
+print(r.reasons)       # e.g. ["ringing", "synthetic-noise"]
+print(r.decay)         # ringing feature value
+print(r.vhf_mf)        # spectral ratio feature value
+print(r.flat_noise)    # flat-region noise feature value
+print(r.resid_std)     # overall residual noise
+
+# From a PIL Image
+from PIL import Image
+img = Image.open("image.png")
+r = analyze(img)
+```
+
+### `Result` fields
+
+| Field | Type | Description |
+|---|---|---|
+| `verdict` | `str` | `"likely AI-generated/edited"` or `"likely clean"` |
+| `reasons` | `list[str]` | Fired signal names: `ringing`, `noisy-flats`, `synthetic-noise` |
+| `score` | `float` | Confidence score `[0, 1]` (0.75 per firing signal, capped at 1.0) |
+| `decay` | `float` | Ringing persistence: mid-distance / near-edge band energy |
+| `halo_vs_bg` | `float` | Mid-distance energy vs. image background |
+| `vhf_mf` | `float` | Spectral ratio: Nyquist ring / mid frequencies |
+| `resid_std` | `float` | Standard deviation of the noise residual |
+| `flat_noise` | `float` | RMS residual inside coarse-flat regions |
+
+### Visual proof from Python
+
+```python
+from minosse import analyze, evidence
+from PIL import Image
+
+img = Image.open("image.png")
+r = analyze(img)
+sheet = evidence.render(img, r)
+sheet.save("proof.png")
+```
+
+## Project structure
+
+```
+minosse/
+├── minosse/
+│   ├── __init__.py      # Public API: analyze, analyze_path, Result
+│   ├── __main__.py      # python -m minosse entry point
+│   ├── cli.py           # Argument parsing and CLI loop
+│   ├── detector.py      # Feature extraction + threshold logic
+│   └── evidence.py      # Visual proof sheet renderer
+├── results/             # Default --proof output directory
+├── requirements.txt     # numpy, pillow, scipy
+└── README.md
+```
+
+## How it works (briefly)
+
+1. **Preprocessing** — the image is converted to RGB and downscaled if
+   its longest edge exceeds 1600 px.
+2. **Feature extraction** (`detector._features()`) — three independent
+   signal-processing pipelines compute scalar features from the
+   grayscale luminance.
+3. **Thresholding** — each feature is compared against a tuned threshold;
+   if it exceeds the threshold the corresponding signal is flagged.
+4. **Verdict** — if any signal fires, the image is marked likely
+   AI-generated/edited; otherwise it's likely clean.
+
+For a deeper explanation of each signal, see [docs/signals.md](docs/signals.md).
+
+## Caveats
+
+The thresholds are calibrated on a small set of examples and should be
+re-validated as more AI samples are added. See [docs/tuning.md](docs/tuning.md)
+for instructions on re-tuning.
+
+## License
+
+MIT

minosse-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+minosse/__init__.py,sha256=2QKb-KV8pdF7Q1C2I0xsoXBUTZKE8PwNODsbwee-nxk,52
+minosse/__main__.py,sha256=ee5vE0xcUZM3fPmxicvcw-IJXkm6nOwxARREHBWpF8Q,47
+minosse/_version.py,sha256=n_5vdJsPNu7wZ57LGuRL585uvll-hiuvZUBWzdG0RQU,520
+minosse/cli.py,sha256=JPoUPqq0fPmS2TKH2Rvf4Puu7uOfAv-frDDfrl1NNsM,1450
+minosse/detector.py,sha256=rvud6lZ3kYKeL3bggDY-P3aug0591w1RnIpiProLcNA,4353
+minosse/evidence.py,sha256=ByLLSjyjmJXaZyL_gkU-KS56HKIWcuilGKcvtNVC4Vc,4175
+minosse-0.1.0.dist-info/METADATA,sha256=10LoUd2C_LQCD9Yn3IvakAyAUeEKlpAXFjtEjudY6jI,5919
+minosse-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+minosse-0.1.0.dist-info/entry_points.txt,sha256=hqd_YmuzOB1tOABMTB-C1ijKkjdgrTp0PbOY20xWumM,45
+minosse-0.1.0.dist-info/licenses/LICENSE,sha256=RnUiRM7llD6-Twf5z-GgfFyZ-XrR_IBEq2Ryrlvp8ZM,1071
+minosse-0.1.0.dist-info/RECORD,,

minosse-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

minosse-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+minosse = minosse.cli:main

minosse-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carlo Esposito
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.