Hugging Face's logo

Spaces:
Malaji71
/
Continuidad-Facial
Build error

App Files Community
Continuidad-Facial / README.md
Malaji71's picture
Malaji71
Update README.md
c1d7614 verified
preview code
|
raw
history blame contribute delete
11.6 kB

A newer version of the Gradio SDK is available: 6.13.0

Upgrade
metadata 
title: Continuidad Facial
emoji: 🏢
colorFrom: indigo
colorTo: blue
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: false
license: mit
short_description: Continuidad facial para proyectos audiovisuales

Continuidad Facial: Coherencia Visual de Personajes con IA

Continuidad Facial es una herramienta de inteligencia artificial para garantizar coherencia visual de personajes en proyectos audiovisuales, documentales y narrativas históricas.
Integra los algoritmos más potentes de restauración facial (CodeFormer, GFPGAN, Real-ESRGAN) con procesamiento de imagen profesional para mantener la identidad visual de personajes a través de múltiples escenas, épocas o medios.

No es un simple faceswap. Es una herramienta de continuidad narrativa.

🌐 Flujo del sistema 

Rostro fuente + Imagen objetivo
↓
Reducción automática de tamaño (max 2.5MB, 2500px)
↓
Faceswap con motor optimizado
↓
Conversión RGB forzada (compatibilidad B&N)
↓
Detección y recorte de rostro (RetinaFace)
↓
(Opcional) Upscaling con Real-ESRGAN x4
↓
(Opcional) Restauración con CodeFormer o GFPGAN
↓
(Opcional) Integración de piel con preservación de detalles
↓
(Opcional) Aplicación de LUT para estilo visual
↓
Composición final con blending suave

🔑 Características clave

  • Restauración facial inteligente: CodeFormer con control de fidelidad (0.0 = máxima calidad, 1.0 = máxima identidad).
  • Compatibilidad B&N: conversión RGB automática para imágenes en blanco y negro o escala de grises.
  • Integración de piel profesional: suavizado selectivo que preserva detalles faciales (ojos, labios, cejas).
  • Upscaling de alta calidad: Real-ESRGAN x4 para ampliar rostros pequeños antes de restaurar.
  • Estilos visuales con LUTs: biblioteca de .cube files para aplicar estilos cinematográficos.
  • Procesamiento por lotes: preparado para video (experimental).
  • Transparencia de salida: PNG sin pérdida o JPG optimizado según necesidad.

🛠️ Cómo usarlo

Pestaña "Imagen"

  1. Sube dos imágenes:

    • Rostro a mantener: el personaje cuya identidad quieres preservar.
    • Imagen objetivo: la escena donde quieres insertar ese rostro.

  2. (Opcional) Selecciona post-procesamiento:

    • Ninguno: ideal para imágenes vintage, B&N o estilo artístico.
    • CodeFormer: para calidad + identidad (ajusta Fidelidad: 0.2 = limpieza, 0.8 = identidad).
    • GFPGAN: para realismo textural (mejor para fotos reales).

  3. (Opcional) Ajusta integración de piel:

    • Intensidad: 0.0 = sin suavizado, 1.0 = máximo suavizado.
    • Feathering: 0 = sin transición, 30 = transición muy suave.

  4. (Opcional) Aplica un LUT para estilo visual (disponibles si tienes carpeta luts/).

  5. Selecciona formato de salida:

    • .jpg (más rápido, ideal para la mayoría de usos).
    • .png (máxima calidad, para postproducción profesional).

  6. Haz clic en "Generar personaje".

Pestaña "Video"

  1. Sube un rostro y un video objetivo.
  2. Ajusta la duración máxima (5-60 segundos).
  3. (Opcional) Aplica un LUT.
  4. Haz clic en "Generar video con personaje".

⚠️ El procesamiento de video es experimental y puede tardar varios minutos.

Pestaña "Mejora de imágenes"

  1. Sube una imagen con rostro dañado, borroso o de baja resolución.
  2. Ajusta los parámetros de CodeFormer:
    • Alinear rostro: corrige rotación/inclinación.
    • Mejorar fondo: restaura también el entorno.
    • Aumentar resolución facial: upscaling x2/x3/x4.
    • Fidelidad: balance entre calidad y preservación de rasgos.
  3. (Opcional) Aplica integración de piel y LUT.
  4. Haz clic en "Restaurar".

📁 Estructura de archivos 

.
├── app.py                    # Aplicación principal Gradio
├── requirements.txt          # Dependencias Python
├── models/                   # Modelos pre-entrenados (descarga manual)
│   ├── GFPGANv1.4.pth
│   └── RealESRGAN_x4plus.pth
├── luts/                     # LUTs personalizados (.cube)
│   ├── cinematic.cube
│   ├── vintage.cube
│   └── ...
└── README.md

📦 Dependencias 

--extra-index-url https://download.pytorch.org/whl/cpu
torch==1.13.1+cpu
torchvision==0.14.1+cpu
numpy==1.24.3
gradio==4.28.3
gradio-client==0.16.0
opencv-python-headless==4.8.0.74
moviepy==1.0.3
gfpgan==1.3.8
basicsr==1.4.2
realesrgan==0.3.0
facexlib==0.3.0
requests
dghs-imgutils==0.16.0
Pillow==10.0.0

Instalación 

pip install -r requirements.txt

Modelos pre-entrenados (opcional)

Si quieres usar GFPGAN o Real-ESRGAN localmente, descarga los modelos:

mkdir -p models
cd models

# GFPGAN
wget https://github.com/TencentARC/GFPGAN/releases/download/v1.3.0/GFPGANv1.4.pth

# Real-ESRGAN
wget https://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.5.0/RealESRGAN_x4plus.pth

🎯 Casos de uso

1. Documentales históricos

Aplica el rostro de un personaje histórico (basado en fotos antiguas) a recreaciones modernas, manteniendo la identidad visual a través de diferentes escenas.

2. Narrativas cinematográficas

Mantén la coherencia visual de un actor cuando:

  • Usas dobles de acción
  • Trabajas con diferentes condiciones de iluminación
  • Necesitas rejuvenecer o envejecer al personaje

3. Restauración de archivos familiares

Mejora fotos antiguas, dañadas o de baja resolución mientras preservas los rasgos reconocibles de tus seres queridos.

4. Producción de contenido AI-first

Mantén la identidad visual de personajes generados con IA a través de múltiples renders, estilos o escenas.

🔧 Configuración avanzada

Variables de entorno 

# Token de Hugging Face para espacios privados (opcional)
export FS="hf_..."

LUTs personalizados

  1. Coloca tus archivos .cube en la carpeta luts/.
  2. Puedes organizarlos en subcarpetas: luts/cinematic/filmic.cube.
  3. La app detectará automáticamente todos los LUTs disponibles.

Ajuste de límites de tamaño

Edita app.py en la función reducir_tamano_imagen_si_es_necesario():

# Cambiar límites por defecto
img = reducir_tamano_imagen_si_es_necesario(img, max_mb=5.0, max_lado=3000)

⚙️ Cómo funciona internamente

1. Detección de rostros

Usa RetinaFace (facexlib) con umbrales adaptativos (0.7 → 0.5 → 0.3 → 0.2 → 0.1) para detectar rostros incluso en condiciones difíciles.

2. Faceswap base

Motor privado optimizado (Malaji71/motor_cambiarcaras) para intercambio de rostros con alta fidelidad.

3. Conversión RGB

Todas las imágenes (incluso B&N) se convierten a RGB antes de procesarse, garantizando compatibilidad con CodeFormer/GFPGAN.

def leer_imagen_rgb(ruta):
    img = cv2.imread(ruta, cv2.IMREAD_UNCHANGED)
    if img.ndim == 2:  # Escala de grises
        img = cv2.cvtColor(img, cv2.COLOR_GRAY2RGB)
    elif img.shape[2] == 3:  # BGR
        img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
    return img

4. Integración de piel

Detecta bordes con Canny → aplica bilateral filter solo en zonas sin detalles → feathering gaussiano para transición suave.

edges = cv2.Canny(gray, lower_threshold, upper_threshold)
blurred = cv2.bilateralFilter(img, d=9, sigmaColor=80, sigmaSpace=80)
result[~mask_detail] = blurred[~mask_detail]  # Solo en piel

5. Composición final

Blending con máscara gradiente en los bordes del rostro para integración invisible:

mask = np.ones((h, w), dtype=np.float32)
border = min(10, h // 6, w // 6)
mask[:border, :] = np.linspace(0, 1, border)[:, None]  # Fade superior
mask[-border:, :] = np.linspace(1, 0, border)[:, None]  # Fade inferior

🚨 Limitaciones conocidas

  • Detección de rostros en anime/ilustraciones: actualmente no soportada (solo fotorrealista).
  • Procesamiento de video: experimental, puede ser lento en CPU.
  • Tamaño de archivo: limitado a ~2.5MB para compatibilidad con APIs externas.
  • Rostros muy rotados: pueden no detectarse correctamente (RetinaFace funciona mejor con rostros frontales).

🐛 Resolución de problemas

"No se detecta el rostro"

  • Asegúrate de que el rostro ocupe al menos el 10% de la imagen.
  • Verifica que el rostro esté bien iluminado y no muy rotado.
  • Prueba recortar la imagen manualmente antes de subirla.

"La imagen sale muy oscura/negra"

  • Ya está corregido en la última versión (conversión RGB forzada).
  • Si persiste, asegúrate de estar usando Pillow==10.0.0.

"CodeFormer no mejora la imagen"

  • Ajusta la fidelidad: valores bajos (0.2) priorizan calidad, valores altos (0.8) priorizan identidad.
  • Si el rostro es muy pequeño, activa "Aumentar resolución facial" primero.

"El resultado se ve borroso"

  • Usa GFPGAN en lugar de CodeFormer.
  • Si aun así está borroso, pasa el resultado por la pestaña "Mejora de imágenes" con CodeFormer + alta fidelidad.

🚀 Créditos

Modelos base

  • CodeFormer (Zhou et al., NeurIPS 2022) - Restauración facial robusta con control de fidelidad.
  • GFPGAN (Tencent ARC Lab) - Restauración facial práctica con GAN.
  • Real-ESRGAN (Xintao Wang et al.) - Super-resolución para imágenes reales.
  • RetinaFace vía facexlib - Detección de rostros robusta.

Infraestructura

  • Implementación optimizada por leonelhs - Configuración estable de CodeFormer en HF Spaces.
  • Motor de faceswap: Space privado Malaji71/motor_cambiarcaras.

Desarrollo

Este proyecto nace de la necesidad de coherencia narrativa en producciones audiovisuales que combinan archivo histórico, recreaciones y generación por IA.

Diseñado específicamente para guionistas, directores y creadores visuales que trabajan con narrativas complejas donde la identidad del personaje debe mantenerse a través de múltiples medios, épocas o estilos.

👥 Autores

Creado por Angel E. Pariente 🇬🇹
Dedicado a David Esteban Cubero y a la Academia Guiones y guionistas 🇺🇾

📄 Licencia

Este proyecto usa múltiples componentes de código abierto. Respeta las licencias individuales de cada modelo:

El código de integración (app.py) se proporciona tal cual para uso educativo y profesional.

🤝 Contribuciones

Las contribuciones son bienvenidas. Por favor:

  1. Haz fork del repositorio
  2. Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
  3. Commit tus cambios (git commit -m 'Add some AmazingFeature')
  4. Push a la rama (git push origin feature/AmazingFeature)
  5. Abre un Pull Request

📞 Soporte

Para reportar bugs o solicitar features, abre un issue en el repositorio.

Para consultas sobre uso profesional o integraciones personalizadas, contacta directamente con el autor.

Continuidad Facial - Coherencia visual para narrativas complejas 🎬