Hmong Pattern AI Generation System - Complete Implementation

Status: ✅ 95% Complete - Implementation Finished, Ready for Training

🎯 Project Goal

Generate culturally-authentic Hmong textile patterns using AI while preserving traditional design principles through constraint-based generation.

---

✅ Completed Components

📊 Dataset (100% Complete)

• Link to the dataset: Link
• ✅ 55 original Hmong patterns with full metadata
• ✅ 550 augmented images (10x multiplication)
• ✅ Training splits: 386 train / 82 val / 82 test
• ✅ Auto-generated captions for all images
• ✅ Demo web viewer (demo_viewer.html)

🤖 Stage 1: Cultural Encoding (100% Complete)

• ✅ motif/models/visual_encoder.py - ResNet50 visual features (512-dim)
• ✅ motif/models/cultural_encoder.py - Metadata embeddings (256-dim)
• ✅ motif/models/combine_embeddings.py - Unified representation (768-dim)

🎨 Stage 2: Controlled Generative Model (100% Complete)

• ✅ train_diffusion.py - LoRA fine-tuning script with cultural conditioning
• ✅ motif/models/losses.py - Custom loss functions (Cultural Consistency Loss, Color Palette Loss)
• ✅ Training monitoring & checkpointing via Hugging Face Accelerate

🔍 Stage 3: Constraint Control (100% Complete)

• ✅ motif/validators/motif_validator.py - Checks presence of required motifs
• ✅ motif/validators/symbolic_validator.py - Verifies symbolic meaning consistency
• ✅ motif/validators/structure_validator.py - Validates geometric arrangement

⚙️ Infrastructure & Automation (100% Complete)

• ✅ run_full_pipeline.py - One-click execution of the entire workflow
• ✅ requirements.txt - All dependencies
• ✅ config.yaml - Training configuration
• ✅ docs/DEPLOYMENT.md - Cloud GPU deployment guide
• ✅ docs/ANNOTATION_METHODOLOGY.md - Technical documentation

---

🚀 Quick Start

1. Unified Pipeline (Recommended)

Run the entire workflow (Embedding Extraction → Training → Generation → Evaluation) with a single command:

# Ensure you are on a machine with a GPU (or use the cloud guides below)
python run_full_pipeline.py

2. View Dataset Demo

Open demo_viewer.html in your browser to inspect the augmented dataset and metadata.

3. Cloud Training (Google Colab / Kaggle)

Since training requires a GPU, we recommend using cloud notebooks.

Google Colab:

1. Upload folder to Google Drive
2. Open new Colab notebook
3. Mount Drive and run:

%cd /content/drive/MyDrive/GenAI
!pip install -q -r requirements.txt
!python train_diffusion.py

See docs/DEPLOYMENT.md for detailed instructions.

---

📁 Repository Structure

GenAI/
├── dataset/
│   ├── augmented/          # Augmented images (550 images)
│   ├── embeddings/         # Cached embeddings (.npz)
│   ├── metadata/           # JSON annotations (55 files)
│   ├── to_annotate/        # Original images (55 images)
│   └── training/           # Train/val/test splits
├── docs/                   # Documentation
├── motif/
│   ├── core/               # Pattern extraction logic
│   ├── data/               # Data processing & augmentation tools
│   ├── models/             # Encoders & loss functions
│   ├── pipeline/           # Inference & evaluation scripts
│   ├── validators/         # Stage 3 constraint checkers
│   └── visualization/      # Demo generators
├── outputs/                # Generated patterns & LoRA weights
├── static/                 # Web app assets
├── templates/              # Web app templates
├── app.py                  # Web interface application
├── config.yaml             # Training configuration
├── demo_viewer.html        # Interactive dataset viewer
├── evaluation_results.json # Metrics and results
├── Kaggle_Training.ipynb   # Notebook for cloud training
├── README.md               # This file
├── requirements.txt        # Python dependencies
├── run_full_pipeline.py    # Main automation script
└── train_diffusion.py      # Diffusion training script

---

🎨 Workflow Architecture

Input (Photos) → Stage 1 (Encoding) → Stage 2 (Generation) → Stage 3 (Validation) → Output
                      ↓                       ↓                      ↓
                Visual + Cultural     Stable Diffusion       Motif/Color/
                  Features              + LoRA               Structure Check

---

📊 Current Statistics

Metric	Value
Original Patterns	55
Augmented Dataset	550
Training Images	386
Validation Images	82
Test Images	82
Metadata Files	270
Unique Motifs	25+
Color Palette	11 colors

---

⏱️ Timeline

• ✅ Week 1-2: Data collection & annotation
• ✅ Week 3: Augmentation & training prep
• ✅ Week 4: Stage 1 implementation
• ✅ Week 5: Stage 2 implementation (Model & Loss)
• ✅ Week 6: Stage 3 implementation (Validators)
• ⏳ Now: Final Training & Paper Writing

Current Progress: ~95% complete

---

💻 Hardware Requirements

For Development (CPU OK)

• Data augmentation
• Annotation
• Demo viewing
• Running run_full_pipeline.py (it will skip training if no GPU is found, or fail gracefully)

For Training (GPU Required)

• Minimum: NVIDIA GPU with 12GB VRAM (RTX 3090, T4)
• Recommended: A100 (40GB)
• Training time: 8-12 hours

---

📚 Documentation

• docs/DEPLOYMENT.md - How to run on cloud GPU
• docs/ANNOTATION_METHODOLOGY.md - Annotation specs
• docs/NCKH_REPORT_SUMMARY.md - Report Summary

---

� License

This project is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0) license. See the LICENSE file for details.

You are free to:

• Share — copy and redistribute the material in any medium or format.
• Adapt — remix, transform, and build upon the material.

Under the following terms:

• Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made.
• NonCommercial — You may not use the material for commercial purposes.
• ShareAlike — If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.

---

�📧 Citation & Contact

If you use this work:

@misc{hmong-pattern-ai-2026,
  title={Culturally-Constrained Generative AI for Hmong Textile Patterns},
  author={[Nguyễn Thành Trung and Hoàng Mạnh Cường and Lưu Thế Hà and Nguyễn Đại Hoàng and Nguyễn Mạnh Hùng and Bùi Thu Hương]},
  year={2026},
  publisher={GitHub},
  url={https://github.com/ThanhTrunggDEV/GenAI}
}

---

Status: Ready for Training & Evaluation
Last Updated: 2026-01-23
GitHub: https://github.com/ThanhTrunggDEV/GenAI