Using ForensicVision

Requirements

There is no internet requirement. The only network activity the application ever performs is a model-weight download that you start yourself.

Installation

git clone https://github.com/SihabSahariar/ForensicVision.git
cd ForensicVision

py -3.11 -m venv .venv
.venv\Scripts\Activate.ps1

python -m pip install --upgrade pip
python -m pip install -r requirements.txt

python main.py --check

sudo apt update
sudo apt install python3.11 python3.11-venv git \
                 libgl1 libglib2.0-0 libxkbcommon-x11-0 \
                 libxcb-cursor0 libxcb-icccm4 libxcb-image0 \
                 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 \
                 libxcb-xinerama0 libxcb-shape0

git clone https://github.com/SihabSahariar/ForensicVision.git
cd ForensicVision
python3.11 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

python main.py --check

python main.py --check prints the environment report: Python version, whether PyTorch and CUDA were found, the weights folder and how many models are ready. It exits without starting the GUI, so it is safe to run over SSH or in CI.

GPU acceleration

Neural models run on CPU by default. To use an NVIDIA GPU, install a CUDA build of PyTorch before or after the requirements file — the wheel index decides which build you get:

# CUDA 12.6 build (check pytorch.org for the current index URL)
pip install torch --index-url https://download.pytorch.org/whl/cu126

# confirm the GPU is visible
python -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"

The status bar shows the active device, the CUDA version and live VRAM use. If an inference run exhausts VRAM, ForensicVision retries with a smaller tile before giving up, and tells you in the log that it did so. You can pin the tile size yourself in Tools → Preferences.

• Tile size — the square the image is cut into for inference. Lower it if you run out of memory; raise it for slightly better quality at block boundaries.
• Tile overlap — how far tiles extend into their neighbours. The overlap is blended with a raised-cosine window, so seams do not appear.
• FP16 — halves VRAM use on supported cards. It changes results in the last decimal places; the precision used is recorded in the provenance record.

Full detail, including the CUDA/PyTorch compatibility matrix, is in GPU_SETUP.md.

First run

python main.py

On first launch ForensicVision creates a configuration folder and an empty cases folder, and opens with no case loaded. Nothing is downloaded. The status bar reads Models: N/32 ready — the classical operators are always ready; the rest become ready once you install their weights.

To have something to work with immediately:

python scripts/make_sample.py                             # ten synthetic test images
python main.py --image samples/sample_cctv.jpg --no-case  # open one without a case

The interface

1. Menu bar — File, Case, Evidence, Analysis, Restoration, View, Tools, Help.
2. Toolbar — the eight most frequent actions.
3. Viewer / Compare tabs — the image, and the before/after workspace.
4. Inspector — one dock with five tabs: Case, Analysis, Restore, History, Log. Jump with Alt+1…5, cycle with Ctrl+Tab, hide with F9.
5. Status bar — the safe-mode lock, the compute device, VRAM, and how many models are ready.

Viewing and navigation

• Zoom — mouse wheel zooms under the cursor; 1 2 4 8 jump to 100/200/400/800%; F fits, R resets.
• Pan — middle-drag, or hold Space and drag.
• Pixel readout — hover for coordinates, RGB, grey and HSV, sampled from the source array rather than the rendered pixmap. C toggles a crosshair.
• Above 200% zoom the image is drawn with nearest-neighbour sampling, so you inspect real samples instead of an interpolated reconstruction.

Creating a case

File → New Case (Ctrl+N). You are asked for a case ID, a title, the investigator, the organisation and a description. All of it is written into the case manifest and printed on the report's title page.

A case is a single self-contained folder with its own SQLite database, so it can be zipped, archived or handed over as a unit. See Case folder layout. File → Recent Cases reopens the last few; Ctrl+Shift+O opens any other.

Importing evidence

File → Import Evidence (Ctrl+O). Accepted formats: .jpg .jpeg .jpe .png .bmp .tif .tiff .webp.

Import performs five things, in this order:

1. Copies the file into evidence/original/ — the file you selected is never modified or moved.
2. Computes SHA-256, SHA-512 and MD5 of the stored copy. SHA-256 is authoritative; MD5 exists only to cross-reference legacy tooling.
3. Extracts EXIF, IPTC, XMP where present, plus image geometry and — for JPEG — the quantisation tables.
4. Marks the stored copy read-only on the filesystem while Safe Mode is on.
5. Writes an evidence.import audit entry recording the source path, the digest and the safe-mode state at the time.

The Case tab then shows the tree and, below it, every metadata field with its value. Copy SHA-256 puts the digest on the clipboard; Verify integrity re-hashes the stored file and compares it against the recorded digest.

Analysing an image

Analysis → Analyse Image (A), or right-click the image. Results appear on the Analysis tab as nine indicators, each scored 0–100 and colour-coded green, amber or red.

Detailed analysis opens the full report: for every indicator, the estimator's name and each raw measurement it produced. Right-click a bar to copy a single score, all scores, or the raw measurements behind one.

The JPEG artefacts indicator is the one exception worth knowing about: when the file is a JPEG, the encoder's quantisation tables are read directly from the container. That is a measurement, not an estimate — encode quality is recovered to within a point.

Forensic visualisations

Analysis → Forensic Visualisations, or right-click the image. Eleven renderings are available, all drawn in place of the image without modifying it. Clear Visualisation returns to the frame.

Error level analysis deserves a caveat: it highlights regions that recompress differently from their surroundings. That can indicate editing, but it is also produced by ordinary things — resizing, text overlays, differing local detail. ELA is an aid to looking, never a verdict on authenticity.

Regions of interest

Pick a selection tool from Evidence, the toolbar or the context menu: rectangle (Ctrl+1), ellipse (Ctrl+2), polygon (Ctrl+3) or freehand (Ctrl+4). Drag on the image to draw; Esc cancels. For a polygon, right-click closes the shape.

With a region active you can:

• Analyse ROI (Shift+A) — score only that region, which is usually far more useful than a whole-frame score when one part of the image is the point.
• Enhance ROI (Shift+E) — restore only that region and blend it back.
• Crop to ROI — create a cropped derivative, itself hashed and recorded.
• Export ROI — write just that region to a file.
• Zoom to ROI — fill the viewport with it.

Restoring an image

Auto Enhance — the recommended path

Restoration → Auto Enhance (E). The engine reads the analysis, chooses operators for the indicators above threshold, orders them sensibly — artefact removal before contrast, enlargement last — and shows you the proposal.

Nothing has run at this point. In the review dialog you can:

• read the rationale for each step — which measurement triggered it, why it sits where it does, and what non-generative alternative exists;
• reorder steps with Up and Down;
• untick a step to skip it while keeping it in the record;
• select a step and change its parameters;
• add a step the recommendation did not include;
• press Cancel and run nothing at all.

Neural steps are shown in amber, and a banner names the pipeline as containing a generative step. Confirm and the pipeline runs on a worker thread; the progress bar reports each step, and Cancel stops at the next step boundary rather than mid-write.

Running a single operator

The Restore tab groups all thirty operators by task. Expand a group, choose a model, and its description, kind and readiness appear beneath it, followed by the controls for its parameters.

• Preview — run on the visible region only, without recording anything.
• Run — execute on the whole image and register the derivative.
• Add to pipeline — stage the step. Build several, then Edit pipeline… to review, or Ctrl+R to run the staged sequence.

Each step's output becomes the next step's input, and the digests chain: step N's output digest is step N+1's input digest. That makes the route from original to final derivative verifiable link by link, not just end to end. Restoration → Return to Original discards the working derivative from the view; it does not delete anything already recorded.

Face restoration

Comparing results

View → Compare Original / Enhanced (Ctrl+D) opens the Compare tab.

Exporting a derivative

File → Export Derivative (Ctrl+S), or Export As… (Ctrl+Shift+S) to choose a path and format.

Prefer a lossless format — .png, .tif, .tiff or .bmp — so the exported pixels are bit-identical to the derivative that was hashed. Exporting to JPEG recompresses the image, and the file you hand over will no longer match the digest in the report.

Every export writes a JSON provenance sidecar next to the image recording the input digest, the model, its version and licence, every parameter, the device, the precision and the timestamp.

Generating a report

Case → Generate Report (Ctrl+P). Choose an output path, name the investigator and organisation, add any case-specific limitations, and pick which optional sections to include — metadata, before/after images, the difference map and the audit trail.

The PDF has fourteen sections:

The mandatory disclaimer is printed on the title page and in the footer of every page, so a printed extract cannot lose it. The finished PDF is hashed and registered in the case database as a report record.

Model Manager

Tools → Model Manager (Ctrl+M).

Every model is listed with its task, kind, version, status, download size and licence. Selecting one shows its full detail: registry key, authors, licence, paper, repository, the method it implements, its parameters, and each weight file with its expected SHA-256.

Installing weights

1. Select the model and read its licence — several restrict use to non-commercial research.
2. Press Install. A confirmation shows the source URL, the file size and whether the download can be verified against a published SHA-256.
3. The download runs on a worker thread and can be cancelled. On completion the digest is checked; a mismatch discards the file.
4. Verify re-hashes an installed file at any time. Remove weights deletes it.

Batch processing

Tools → Batch Processing applies one reviewed pipeline to every image in a folder. Choose the input folder, the output folder and the pipeline, and each image is imported, processed and recorded exactly as it would be individually — with its own hashes, provenance sidecar, history and audit entries.

Batch runs sequentially on a single worker rather than in parallel. GPU inference serialises anyway, so parallelism would only raise peak VRAM and the chance of an out-of-memory failure. Progress is per file, and cancelling stops at the next file boundary, leaving completed work intact and recorded.

OCR and object detection

Both are optional integrations, reached from Analysis or the context menu.

• OCR Region… reads text from the current image or region. It needs Tesseract installed on the system; set the binary path in Preferences if it is not on PATH.
• Detect Objects… runs a detector over the image and lists what it found with confidences. Face detection uses OpenCV YuNet and reports five-point landmarks, so a detected face can be sent straight to face restoration as a region.

Forensic Safe Mode

On by default; the status bar shows 🔒 FORENSIC SAFE MODE ENABLED. While it is on:

• imported originals are marked read-only on the filesystem;
• the original is never a valid write target for any operation;
• deleting evidence and editing the processing history are refused;
• every state-changing operation writes an audit entry that records the safe-mode state at the time;
• reports include the complete provenance chain.

Turning it off (Tools → Forensic Safe Mode) requires confirming an explicit warning, and the change is itself audited — so a report will show that it was disabled, when, and what happened afterwards. There is no reason to disable it during casework.

Preferences

Tools → Preferences.

Settings live in the per-user configuration folder — on Windows %LOCALAPPDATA%\ForensicVision\config, on Linux ~/.config/ForensicVision. Deleting it resets the application to defaults; cases are unaffected.

Keyboard shortcuts

Also available in the application from Help → Keyboard Shortcuts.

Undo and redo affect the view only. Original evidence is never modified, so there is nothing to undo on it.

Command line

Case folder layout

CASE-0007/
├── case.json            # human-readable manifest
├── case.db              # SQLite: evidence, derivatives, steps, audit
├── evidence/original/   # imported originals, read-only in Safe Mode
├── derivatives/         # every enhanced image + JSON provenance sidecars
├── analysis/            # stored analysis results
├── reports/             # generated PDFs
├── metadata/            # extracted metadata
└── logs/                # per-case log

The folder is self-contained: archive or copy it and the case travels with its database, its provenance and its reports. Derivatives form a tree — a derivative of a derivative records its parent — which is what the History tab renders and what lets any result be traced back to the original.

Scripting the engine

The restoration engine has no Qt dependency, so it can be driven from a plain Python script — for automation, experiments or as the basis of another front end.

from analysis import analyze_image
from core.image_io import load_image
from restoration import register_all_models
from restoration.auto_engine import AutoRestorationEngine
from restoration.pipeline import PipelineRunner

register_all_models()
image = load_image("frame.jpg")
report = analyze_image(image)

recommendation = AutoRestorationEngine().recommend(report)
for step in recommendation.pipeline.steps:
    print(step.display_name, step.parameters, step.info().may_synthesise)
# FBCNN (colour)      {'override_quality': False, 'quality_factor': 50}  True
# CLAHE Contrast      {'clip_limit': 2.0, 'tile_grid': 8}                False
# Real-ESRGAN x4plus  {'scale': 4}                                       True

result = PipelineRunner(device="auto").run(image, recommendation.pipeline)
print(result.may_synthesise)                  # True
print(result.steps[-1].output_hashes.sha256)  # the derivative's digest

The module layout and the extension points for adding an indicator or a model are described in ARCHITECTURE.md.

Troubleshooting

“PyTorch not installed” but I installed it

Check that you installed into the same environment you are launching from — python -c "import torch; print(torch.__file__)" from the active virtual environment. If you are running a packaged build, this message can also mean the bundle's PyTorch is broken rather than absent; run --self-test, which fails loudly instead of quietly degrading to CPU-with-classical-only.

CUDA is not detected

The default PyTorch wheel is CPU-only. Install a CUDA build from the index URL on pytorch.org matching your driver, then confirm with python -c "import torch; print(torch.cuda.is_available())".

Out of memory during inference

Lower the tile size in Preferences, enable FP16, close other GPU applications, or set the device to cpu for that run. With auto-reduce enabled the application retries with a smaller tile before failing, and says so in the log.

The application will not start on Linux

Almost always a missing Qt platform library. Run with QT_DEBUG_PLUGINS=1 python main.py to see which one, and install the packages listed under Installation. Over SSH you need X forwarding or a local session; --check and --self-test work headless.

I cannot delete a case folder

Safe Mode marks imported originals read-only, and Windows will refuse to remove them. Clear the read-only attribute first, or delete the case from within the application.

A downloaded weight file fails verification

The download is discarded and nothing is installed — that is the intended behaviour. Retry; if it fails again, download the file manually from the repository shown in the model detail and use Install from file….

Where are the logs?

The Log tab shows the current session live. On disk, each case writes to its own logs/ folder, and the application log is in the per-user configuration folder. --debug raises the level.

Frequently asked questions

Can I use ForensicVision's output in court?

That is a question for your jurisdiction, your instructing authority and your own expertise — not for this documentation. What the software can tell you is exactly what it did: every operation, parameter, model, licence and digest is recorded and printed. ForensicVision has no history of court acceptance and makes no claim of admissibility. Where an established, validated commercial tool is available and appropriate, use it.

Can it read an unreadable licence plate?

No tool can. If the characters were never sampled, they are not in the file and no amount of processing will recover them — a model asked for a plate will produce a plausible plate, which is not the same thing. What enhancement can legitimately do is make marginally-sampled detail easier to see. Compare against the Lanczos baseline: if the neural result shows characters the deterministic upscale does not even hint at, treat them as invented.

Does it ever modify my original file?

No. Import copies the file; the copy is what is hashed and stored read-only. The file you selected is never written to, moved or renamed.

Does it phone home?

No. There is no telemetry, no account, no activation and no licence server. The only network request the application ever makes is a model-weight download you start yourself, to a URL it shows you first — and it can be disabled entirely in Preferences.

Why keep classical operators when neural models exist?

Because they cannot invent detail, and because they sometimes simply win. On motion blur Wiener deconvolution beats Restormer by 4 dB in the bundled benchmark; on defocus blur Richardson–Lucy beats Wiener by 3 dB. They also give you a non-generative baseline to compare any neural result against.

Are results reproducible?

Classical operators are deterministic and reproduce exactly. Neural inference reproduces on the same device, precision and library versions — all of which are recorded — but GPU floating-point accumulation order means a different card or a different PyTorch build can differ in the last decimal places. The provenance record captures everything needed to attempt an exact reproduction.

How do I contribute?

Issues and pull requests are welcome at github.com/SihabSahariar/ForensicVision. The conventions that matter most: never fake a result, every operator declares whether it can invent detail, every estimator names its method, nothing long-running touches the GUI thread, and tests accompany behaviour changes.

Limitations

A summary. The authoritative list is LIMITATIONS.md, and it is the most important file in the repository.