Neural forensic restoration - diagnose and reverse media degradation chains.
Every image on the internet has been through hell: screenshotted, re-compressed, platform-resized, color-shifted, watermarked, and re-shared dozens of times. Existing tools blindly upscale or denoise. Artefex is different - it first diagnoses what happened to your media, then reverses each step specifically.
Think of it as git log for media degradation, followed by intelligent undo.
| Other tools | Artefex | |
|---|---|---|
| Approach | Blindly upscale/denoise everything | Diagnose first, then reverse each degradation step |
| Analysis | None | 13 forensic detectors - JPEG artifacts, platform fingerprinting, AI detection, steganography, forgery |
| Restoration | One-size-fits-all filter | Targeted fix per degradation - neural (ONNX) with classical fallback |
| Extensibility | Closed | Plugin system for custom detectors and restorers |
| Interface | Usually GUI-only | CLI + Python API + Web UI + Docker |
pip install artefex # core (images only)
pip install artefex[web] # adds web UI
pip install artefex[video] # adds video support
pip install artefex[neural] # adds ONNX neural models
pip install artefex[all] # everythingOr install from source:
git clone https://github.com/turnert2005/artefex.git
cd artefex
pip install -e ".[all]"Or with Docker:
docker compose up # web UI at http://localhost:8787# Diagnose what happened to an image
artefex analyze photo.jpg
# Get a quality grade (A-F)
artefex grade photo.jpg
# Reverse the degradation chain
artefex restore photo.jpg
# Full forensic audit
artefex audit photo.jpgartefex analyze photo.jpg # diagnose degradation chain
artefex analyze photo.jpg --json # machine-readable output
artefex analyze photo.jpg --verbose # detailed detection info
artefex analyze https://example.com/img.jpg # analyze from URL
artefex analyze ./photos/ # batch modeartefex grade photo.jpg # A-F grade with score
artefex grade ./photos/ --export csv # batch export as CSV
artefex grade ./photos/ --export markdown # batch export as markdownartefex report photo.jpg # text forensic report
artefex report photo.jpg --html # rich HTML report with charts
artefex timeline photo.jpg # ASCII degradation timeline
artefex story photo.jpg # natural language forensic narrative
artefex heatmap photo.jpg # spatial degradation heatmap
artefex palette photo.jpg # extract dominant color palette
artefex orient photo.jpg --fix # detect and fix orientation
artefex audit photo.jpg # comprehensive audit (all tools)artefex restore photo.jpg # reverse the degradation chain
artefex restore photo.jpg --format png # convert output format
artefex restore photo.jpg --no-neural # classical methods only
artefex restore ./photos/ # batch restore
artefex restore-preview photo.jpg # save each step as separate fileartefex compare original.jpg restored.jpg # MSE, PSNR, SSIM, heatmap
artefex gallery ./originals/ ./restored/ # HTML side-by-side gallery
artefex duplicates ./photos/ # find duplicate images
artefex duplicates ./photos/ --threshold 0.8 # adjust similarity thresholdartefex video-analyze clip.mp4 # sample frames for degradation
artefex video-restore clip.mp4 # restore frame by frameartefex web # launch web UI with drag-and-drop
artefex watch ./inbox/ --restore # auto-process new images
artefex dashboard ./photos/ # generate HTML overview dashboard
artefex rename-by-grade ./photos/ --dry-run # preview grade-based renaming
artefex parallel-analyze ./photos/ # multi-process batch analysisartefex version # show version and dependency status
artefex models list # show available neural models
artefex models import deblock-v1 model.onnx # import a model
artefex plugins # list installed plugins| Category | Detector | Method |
|---|---|---|
| Compression | JPEG artifacts | 8x8 block boundary discontinuity analysis |
| Compression | Multiple re-compressions | Double quantization + ringing detection |
| Resolution | Upscaling/loss | High-frequency spectral analysis + autocorrelation |
| Color | Color shift | Channel imbalance + clip ratio analysis |
| Artifacts | Screenshot remnants | Border uniformity + aspect ratio + dimensions |
| Noise | Sensor/added noise | Laplacian MAD estimation |
| Overlay | Watermarks | Tile correlation + histogram peaks + alpha channel |
| Metadata | EXIF stripping | Metadata presence/completeness checks |
| Provenance | Platform fingerprint | Dimension/compression/EXIF signatures for Twitter, Instagram, WhatsApp, Facebook, Telegram, Discord, Imgur |
| Provenance | AI-generated content | Frequency spectrum, histogram smoothness, noise uniformity, patch consistency |
| Security | Steganography | LSB analysis, chi-square test, entropy, pairs analysis |
| Provenance | Camera/device ID | Sensor noise PRNU analysis (DSLR, smartphone, webcam, scanner) |
| Forgery | Copy-move detection | Patch-based feature matching for cloned regions |
from artefex import analyze, restore, grade
# Diagnose
result = analyze("photo.jpg")
for d in result.degradations:
print(f"{d.name}: {d.confidence:.0%} confidence, severity {d.severity:.0%}")
# Grade
grade_result = grade("photo.jpg")
print(f"Grade: {grade_result}")
# Restore
restore("photo.jpg", output="photo_restored.png")Create .artefex.toml in your project or ~/.artefex.toml globally:
[analysis]
min_confidence = 0.15
[restore]
use_neural = true
output_format = "png"
[web]
port = 8787Also supports [tool.artefex] in pyproject.toml.
cd train/
python generate_data.py --source /path/to/clean --output ./data --type deblock
python deblock_train.py --data ./data --epochs 50
artefex models import deblock-v1 ./models/deblock_v1.onnxArtefex supports community plugins via Python entry points:
# In your plugin's pyproject.toml
[project.entry-points."artefex.detectors"]
my_detector = "my_package:MyDetector"
[project.entry-points."artefex.restorers"]
my_restorer = "my_package:MyRestorer"See examples/custom_plugin.py for a complete example.
artefex analyze <image>
|
v
+------------------------+
| 13 Built-in Detectors | JPEG, noise, color, resolution, screenshot,
| + Plugin Detectors | watermark, EXIF, platform, AI-gen, stego,
| | camera ID, copy-move forgery
+------------------------+
|
v
+------------------------+
| Degradation Chain | Sorted by severity, graded A-F
+------------------------+
|
v
+------------------------+
| Restoration Pipeline | Neural (ONNX) -> Plugin -> Classical
+------------------------+
|
v
restored image + report + heatmap + grade
- v0.1 - Detection engine + classical restoration
- v0.2 - Neural models, web UI, video, training, plugins
- v0.3 - Platform fingerprinting, AI detection, steganography, grading
- v0.4 - Pre-trained model weights + model hub
- v0.5 - Temporal coherence for video + audio support
- v1.0 - Stable API + community model zoo
We welcome contributions of all sizes - from typo fixes to new detectors. See CONTRIBUTING.md for setup and guidelines.
New here? Look for issues labeled good first issue - these are scoped tasks designed for first-time contributors.
Have questions? Join the Discussions.
MIT