GETTING_STARTED.md

MorphGuard On-Prem Setup & Training Guide

This guide walks you through setting up data sources, training the MorphDetector model, and running the live demo—entirely self-contained via the web UI or automation script.

Prerequisites

• Linux/Ubuntu 24.04 or compatible
• NVIDIA GPU (e.g., GeForce RTX 5070) with CUDA drivers installed
• Python 3.12 and venv module
• Git, curl, build-essential
• PostgreSQL with TimescaleDB extension (required, for real-time metrics)
• Ethereum node (required, for blockchain verification)

GPU and CUDA Compatibility

By default, MorphGuard runs all models on the CPU to ensure broad compatibility. If you have an NVIDIA GPU and a PyTorch build that supports your card’s compute capability (e.g., sm_120 for a GeForce RTX 5070), you can enable GPU inference:

# Install PyTorch:
# - CPU-only (broad compatibility):
pip install torch torchvision torchaudio
# - GPU (CUDA 11.x):
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
# - GPU nightly (CUDA 12.x, Python 3.12):
pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu122

# Enable GPU mode at runtime:
export USE_CUDA=1
    python app.py
    ```  


### Nightly Preview Builds
If you’re running Python 3.12 and want out-of-the-box support for CUDA 12.2+ (including sm_120 on RTX 5070), you can use the official PyTorch nightly wheels:
```bash
pip3 install --pre \
  --index-url https://download.pytorch.org/whl/nightly/cu122 \
  torch torchvision torchaudio

Note: the cu122 nightly index publishes cp312 (Python 3.12) wheels. Use a custom wheel server or build PyTorch from source with TORCH_CUDA_ARCH_LIST="...;12.0" if needed. This pulls the latest preview build containing PTX for sm_120 and prebuilt kernels, so GPU inference just works on Python 3.12 today.

If GPU memory is insufficient or your PyTorch install does not support your GPU’s compute capability, the models will automatically fall back to CPU to avoid out-of-memory errors.

Installation

1. Clone the repository:

   git clone https://github.com/your_org/MorphGuard.git
   cd MorphGuard
   

2. Create and activate a virtual environment:

   python3.12 -m venv venv
   source venv/bin/activate
   

3. Install Python dependencies:

   pip install --upgrade pip
   # Install PyTorch (choose one):
   # CPU-only:
   pip install torch torchvision torchaudio
   # GPU (CUDA 11.x):
   pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
   # GPU nightly (CUDA 12.x, Python 3.12):
   pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu122
   
   # Install remaining dependencies
   pip install timm flask flask-socketio pillow numpy gradio facenet-pytorch insightface onnxruntime-gpu open3d scikit-learn
   pip install requests sklearn  # for data scripts
   pip install dronekit pymavlink  # for DroneKit/MAVLink integration
   
   # Install TimescaleDB and Ethereum dependencies
   pip install psycopg2-binary  # PostgreSQL driver
   pip install web3 eth-account solcx  # Ethereum and Smart Contract support
   

4. Automated setup using the provided script:

   # Executes full setup with all dependencies
   bash setup.sh
   

5. Initialize TimescaleDB (if using metrics collection):

   # Install TimescaleDB extension (one-time)
   sudo bash scripts/install_timescaledb.sh
   
   # Initialize or migrate the database schema
   # - Creates hypertables, indexes, retention policies
   # - Applies in-place migrations (e.g. adds missing columns)
   # - Records a schema version to skip on subsequent runs
   python3 scripts/setup_timescaledb.py
   

   On first run this may take a few seconds. Subsequent runs detect the recorded schema version and immediately skip the setup (printing "Schema is already at version 1, skipping setup.").

   If you add new schema changes in the future, bump the SCHEMA_VERSION constant in scripts/setup_timescaledb.py so that the setup script applies only once per version.

6. Set up Ethereum verification (if using blockchain):

   # Deploy smart contract to local Ethereum node
   python ethereum/deploy_contract.py
   

Starting the Flask Server

# (Optional) Set SoundCloud stream URL for the landing page:
# export SOUNDCLOUD_STREAM_URL="https://soundcloud.com/your_user/your_track"
source venv/bin/activate
python app.py

By default it listens on 0.0.0.0:5000.

Note: On startup, app.py will automatically terminate any process listening on port 5000 before binding, so you can re-run the server without manually freeing the port.

Automated Verification Script

You can now automatically verify installation, clone 3D scan repositories, launch the server, and check the UI by running:

bash verify_setup.sh

A return code of 0 indicates success; any other code indicates a failure during one of the verification steps.

Web UI: Data Setup & Training

Browse to:

http://localhost:5000/setup?token=<YOUR_TOKEN>

Replace <YOUR_TOKEN> with the fixed token: -api03-S3CYYOvtQ23xP8pt34Gfkv4g_F1iCY6QOD_1PJqZAZ6nLZVXXMQqXLacIXI1swCUzwekjnDYeU9Mho244LT7gw-VkeZowAA

Step 1: Save API Keys

Enter/get your keys (persisted to unsplash_keys.json):

• Unsplash Access Key and Secret Key
• Pexels API Key

Step 2: Collect Real Faces

• Fetch Real Faces (Unsplash) → data/train/real/
• Fetch Real Faces (Unsplash) → data/train/real/
• Fetch Pexels Faces → data/train/real/
• Fetch LFW Faces (scikit-learn) → data/train/real/
• Fetch GAN Faces (ThisPersonDoesNotExist) → data/train/real/
• Fetch UTKFace (archive download) → data/train/real/

Step 3: Generate Morphs

• Generate Morphs → data/train/morph/

Step 4: Prepare Validation Set

• Fetch Val Real → data/val/real/
• Generate Val Morphs → data/val/morph/

Step 5: Start Detector Training

• Click Start Detector Training to launch on-GPU training via scripts/train_detector.py
• Real-time logs stream in the Logs panel (left)

System & Resource Monitoring

• Camera Detection: The UI will list available USB camera indexes under "System Info" (polls /api/devices/cameras). Use these for live video demos.
• GPU Utilization: Live GPU usage (util%, memory used/total) is shown under "System Info" (polls /api/devices/gpu).

Live Training Monitor

• On the right panel, view:
  • Training Loss chart (train vs. val loss per epoch)
  • Validation Accuracy chart (val accuracy per epoch)
  • Charts update automatically by polling /api/train/metrics every 10 s

Live Training Monitor

On the right you’ll see:

• Status: not_started → running (n/epochs) → complete
• Loss Chart: Train vs. Validation loss per epoch
• Accuracy Chart: Validation accuracy per epoch

Step 6: Model Map

• Click the Model Map tab in the top navigation of the Setup dashboard.
• Displays an interactive Mermaid.js flowchart illustrating:
  • Inference pipeline (upload → MorphDetector & Demorpher → results)
  • Continuous learning feedback loop (flags → dataset ingestion → thresholded fine-tuning)
  • Offline full training process (via run_full_training.sh)
• You can pan, zoom, and explore the chart directly in the browser.

Training Methodology & Performance

We use supervised deep learning (transfer learning) to train our MorphDetector model as a binary real-vs-morphed face classifier. Key details:

• Model Architecture: Fine-tune a pre-trained vision backbone (ResNet-18 by default, or any Vision Transformer from timm) with a lightweight custom classification head.
• Training Procedure: Standard multi-epoch back-propagation over labeled data. Default is 20 epochs (each epoch is one full pass over the dataset). No clustering or EM-style algorithms.
• Validation Accuracy: Typically 94 – 98% on held-out validation sets after 20 epochs, with most gains occurring in the first 5–10 epochs.
• Convergence & Logging: Per-epoch training/validation losses and validation accuracy are recorded to training_stats.json (or models/detector_metrics.json) and visualized in the “Live Training Monitor”.
• Inference Latency: Approximately 100 – 200 ms per 224×224 image on GPU; 300 – 500 ms on CPU.

Product Demo

Product Demo

Browse to (if running with default demo token):

http://localhost:5000/demo?token=-api03-S3CYYOvtQ23xP8pt34Gfkv4g_F1iCY6QOD_1PJqZAZ6nLZVXXMQqXLacIXI1swCUzwekjnDYeU9Mho244LT7gw-VkeZowAA

Or set your own token via the DEMO_TOKEN environment variable before starting the server:

export DEMO_TOKEN="<YOUR_TOKEN>"
python app.py

Then browse to:

http://localhost:5000/demo?token=<YOUR_TOKEN>

• Morph Detection: upload a face, get is_morphed, confidence, etc.
• Demorphing: select a demorph method (Transformer, GAN, Diffusion, or LDM), optionally enter a text prompt for LDM, upload a morphed face with an optional reference image, and view the demorphed output image
  • The demo UI now supports text conditioning for latent diffusion demorphing
  • Frequency-domain analysis (Fourier + wavelet) is used under the hood for improved morph detection
• Liveness Detection: switch to the “Liveness Detection” tab, upload a face image, and view depth, texture, reflection scores along with overall liveness decision.
• Identity Verification: switch to the “Identity Verification” tab, upload a selfie and an ID document, input a user ID and optional MFA code, then view match score, identity label, blockchain transaction ID, and MFA result.
• User Flagging & Continuous Learning: after detection or demorphing, click Flag, select a reason and the correct label. New examples are ingested into data/train and trigger a background fine-tuning job. Check live retrain status at the bottom (polls /api/demo/retrain_status).
• Identity Verification: enroll faces and verify matches via /api/verify
• Model Export: export the detector model as ONNX or TorchScript via /api/model/export
• Identity Verification: enroll user faces and verify matches (/api/verify endpoints)

Orchestration Scripts

MorphGuard provides three ways to bootstrap data, start training, and run end-to-end demos:

1. Python API driver (scripts/full_run.py)

Requirements:

• A running Flask server on http://localhost:5000
• Python virtualenv activated

Usage:

source venv/bin/activate
python scripts/full_run.py --verbose

What it does:

• Installs psycopg2-binary, OpenCV, and DroneKit dependencies
• Waits for the server to respond at /
• Logs in as admin (POST /login)
• Writes db_config.json for TimescaleDB
• Calls all /api/setup/... endpoints to fetch UTKFace, LFW, Pexels, Pixabay, Unsplash, and generate morphs
• Starts detector training (POST /api/train/detector)
• Runs a quick camera detection & demorphing test

Use this in CI pipelines or when the server is already running.

2. Auto-setup shell (scripts/auto_setup.sh)

Requirements:

• Flask server running on http://localhost:5000
• curl, pip, and bash

Usage:

bash scripts/auto_setup.sh

What it does:

• Logs in via curl (admin credentials)
• Installs psycopg2-binary and OpenCV
• Writes db_config.json
• Provisions TimescaleDB if needed
• Calls /api/setup/... via curl to save keys, fetch datasets, and generate morphs
• Starts detector training (POST /api/train/detector)
• Prints a summary and live monitor URL

3. One-stop orchestrator (run_full_training.sh)

Requirements:

• Linux/Ubuntu (bash), Python virtualenv

Usage:

bash run_full_training.sh

What it does:

• Kills any process on port 5000
• Launches python app.py (Flask server) in the background (logs → flask.log)

Site Structure & Access Policy

Site Map

• / (Landing Page)
  • Background video and interactive overlay.
  • Buttons:
    • "Enter MorphGuard Demo" → /demo if logged in; otherwise /lead.
    • "Data Setup & Training" → /setup_page if admin/approved user; otherwise /login.
  • Optional SoundCloud play/pause controls at bottom-left.
• /lead (Lead Capture)
  • User lead form for name/email.
• /lead_submitted (Lead Confirmation)
  • Confirmation of lead submission.
• /login (Login)
  • Admin and approved-user authentication.
• /demo (Demo UI)
  • Morph detection and demorphing interface (requires login).
• /logout
  • Clear session and redirect to landing.
• /setup_page (Data Setup & Training)
  • Data fetching, morph generation, and training hyperparameter UI (requires admin or approved user).
• /training (Live Training Monitor)
  • Real-time training metrics (requires login).

User Access Policy

• admin (username "admin") has full access to /demo, /setup_page, and /training.
• user accounts (approved users) have the same access as admin.
• user_lead accounts (leads) can log in and access /demo but are blocked from /setup_page and /training until approved by an admin:
  1. An admin approves a user_lead via the "Users" tab in Setup UI.
  2. Approval generates a password and converts the user to type user.
  3. The approved user can then log in and gain full access.
• Invokes bash scripts/auto_setup.sh in the background (logs → setup.log)
• Enters a 15-minute tail loop on both logs until training completes
• Prints final log excerpts when done

Use this for a fully automated, hands-off workflow: server start, data fetch, training, and log monitoring.

Next Steps

• Tune train_detector.py --val-split or supply custom data/val folders
• Control checkpoint retention via --max-checkpoints to keep only the most recent N epoch checkpoints (default 5)
• Swap backbones via --model-name
• Add demorph‐module training (not yet scaffolded)
• Experiment with /api/model/export to generate ONNX/TorchScript for edge deployment

For more details, see train_detector.py, app.py, and scripts/data_setup.py.

Current Status

The current on-prem demo and training pipeline supports:

• Web-based data collection from multiple sources (Unsplash, Pexels, Pixabay, LFW, GAN, UTKFace)
• Automated validation set creation (fetch & morph for data/val)
• Single-click model training with live logs and real-time metrics (loss & accuracy)
• Interactive demo for morph detection and demorphing via Flask and Chart.js
• Token-protected admin endpoints and persistent API key storage

Roadmap: Paid Features and Enterprise Enhancements

We plan to introduce premium capabilities for paying customers:

1. Multi-tenant user accounts and authentication (OAuth/JWT)
2. Role-based access control (RBAC) for separation of admin and viewer roles
3. Quota management and usage billing dashboards
4. Batch processing API endpoints for bulk image uploads
5. Audit logs and compliance reporting (GDPR/CCPA)
6. Custom model training jobs with parameter tuning (per customer)
7. ONNX export and smaller edge models for on-device inference
8. Mobile SDKs (iOS/Android) for client-side face capture & detection
9. Integration plugins for DroneKit/MAVLink to link detection results with drone streams
10. Advanced demorphing with GAN-based reconstructions and higher resolution outputs
11. Integration with identity verification workflows (KYC, passport scanners)
12. SLA-backed on-prem installers with automated updates and monitoring

Contact us for custom enterprise licensing, support, and roadmap prioritization.

RoadMap: Advanced Demorphing & Pipeline Automation

To leapfrog simple averaging and deliver high-fidelity demorph outputs, MorphGuard now includes a hybrid GAN + Diffusion pipeline. See scripts/demorph_pipeline.py for end-to-end automation.

B) Demorphing (GAN / Diffusion)

• StyleGAN2 inversion + latent editing: • Invert morphed image into StyleGAN2 latent space using pixel2style2pixel (pSp) encoder. • Use a learned “identity target” (reference face or average real-face code). • Perform a latent-space walk away from the morphed identity and decode back into a demorphed image.
• Conditional GAN (pix2pixHD-style): • Train a paired morphed→real generator with adversarial + L1 + perceptual (VGG-face) losses. • Incorporate an identity-preservation loss via an ArcFace or FaceNet embedding comparator.
• Diffusion Models: • Use Latent Diffusion (LDM) to denoise morphed inputs back to a single identity. • Condition denoising on a reference identity embedding for guided reverse diffusion.
• Loss Functions: • Perceptual loss (LPIPS) for visual fidelity. • Identity loss: minimize cosine distance in embedding space. • GAN loss with multi-scale discriminators (patch-GAN).

These approaches, especially a hybrid StyleGAN2 inversion + diffusion + identity-guided loss, represent a significant leap over simple linear averaging—delivering crisp, high-fidelity, identity-preserved outputs that outpace the competition.

Pipeline Automation

Use the helper script to clone, set up, and run each stage:

# Install dependencies
pip install omegaconf lpips diffusers transformers

# Clone repos and setup
python scripts/demorph_pipeline.py clone

# Invert a morphed image
python scripts/demorph_pipeline.py invert --input data/train/morph/example.jpg --output static/demorphed/psp_example.png

# Train a pix2pixHD model (requires paired dataset under data/pix2pix)
python scripts/demorph_pipeline.py train_pix2pix --data_dir data/pix2pix

# Run latent diffusion demorphing
python scripts/demorph_pipeline.py run_diffusion --input data/train/morph/example.jpg --output static/demorphed/ldm_example.png

After running each step, inspect static/demorphed/ for results, and iterate on loss weights or model checkpoints for optimal identity compatibility.

Automatic Retraining on New Data

To continuously improve the detector whenever new images arrive, MorphGuard includes a file-watcher: bash # Starts a background watcher that monitors data/train and data/val directories # and triggers a new training run when JPEG/PNG files are added. python scripts/data_watcher.py Enable or disable auto-retrain from the Setup UI via the "Enable Auto-Retrain" checkbox. All training hyperparameters are persisted in settings.json so the watcher reuses your last settings.

Repository Structure: Development and test files have been moved to the /Cleaning directory. The main directory contains only production-ready code for deployment. For development files and backups, see the /Cleaning directory structure.