How savagehell8008/facial_reconstruction works
Project type and purpose
• This is a research‐style machine-learning pipeline for facial image enhancement and reconstruction using GANs (Patch-GAN, U-Net generator, custom discriminator).
• The “application” lives as Jupyter notebooks (facial_reconstruction_final.ipynb, facial_reconstruction_not_final.ipynb), driven by a Makefile and Python dependencies in requirements.txt.
File structure
• Top-level notebooks: define data loading, frame extraction, model training, inference, and visualization.
• Makefile targets:
– make requirements: installs Python packages (TensorFlow, iamgaug, etc.)
– make dataset: downloads & extracts raw images/frames.
• No separate “src” directory; core logic is embedded in notebooks.
• No deployment/config files—this is currently a research/training pipeline.
README for additional insights
• Model architecture:
– Generator: U-Net-style with skip connections
– Discriminator: Patch-GAN with BatchNorm/InstanceNorm & gradient penalty
• Runtime: batch size=16, CPU-only training (~4 h/epoch)
• Future plans: add DeBlur-GANv2, ESRGAN, 3D reconstruction modules
Main components
a. Data Layer
– Raw input frames/videos (downloaded via make dataset)
– Preprocessing cell in notebook (frame extraction, normalization, augmentation via iamgaug)
b. Training Pipeline
– Generator (U-Net)
– Discriminator (Patch-GAN)
– Loss functions (adversarial, L1, gradient penalty)
– Training loop (epochs, batch size, gradient accumulation)
c. Evaluation & Output
– Periodic model checkpoints
d. Environment & Orchestration
– Makefile (dependency install, data fetch)
– Jupyter notebook runtime (Python 3.8+, TensorFlow)
– Hardware node (Ryzen 5 CPU, 16 GB RAM)
Relationships and interactions
• Data → Preprocessor → Training Loop
• Within Training Loop: Generator ↔ Discriminator (adversarial feedback)
• After each epoch: Model Checkpoint → Evaluation/Visualization
• Notebook orchestrates the entire pipeline, calling Makefile targets as needed
Architectural patterns & design principles
• Pipeline pattern: sequential flow from raw data to model output
• Modular ML components: separate blocks for data prep, generator, discriminator, losses
• Iterative loop: training epochs feed back into model checkpoints
• Future-proofing: placeholders for new GAN modules (DeBlur-GANv2, ESRGAN, 3D methods)
Technologies & frameworks
• Python 3.8+
• TensorFlow (core ML library)
• iamgaug (augmentation)
• Patch-GAN & U-Net network classes
• Makefile for reproducible environment setup