Skip to content

Releases: gutierrezmigueljeronimo/MatForge-App

Release list

Release v1.0 - Checkpoints

Release v1.0 - Checkpoints Latest
Latest

Choose a tag to compare

View all tags
@migueljeronimogutierrez migueljeronimogutierrez released this 14 May 00:52
v1.0
595e5cd

MatForge App — Release v1.0

Release date: May 2026 Compatibility: Windows 10 / 11 (64-bit) · Python 3.11 · CUDA 11.8

What's included

This release contains the model weights required to run MatForge App. The application source code is available in the repository.

Assets in this release:

  • best_gan.pt — MatForge inference model (PVT-v2-B1 encoder + FPN decoder, GAN fine-tuned)
  • sr_ft_phase1_best_lpips.pt — Super-Resolution model (Real-ESRGAN, fine-tuned on MatSynth)
  • RealESRGAN_x4plus.pth — Real-ESRGAN base weights

Installation

Step 1 — Clone or download the repository

git clone https://github.com/migueljeronimogutierrez/MatForge-App.git
cd MatForge-App

Alternatively, download the repository as a ZIP from the repository page and extract it.

Step 2 — Place the model weights

Download all three weight files from this release and place them in the following locations inside the repository folder:

MatForge-App/
└── checkpoints/
    ├── matforge/
    │   └── best_gan.pt
    └── sr/
        ├── sr_ft_phase1_best_lpips.pt
        └── RealESRGAN_x4plus.pth

Create the folders if they do not exist.

Step 3 — Run the installer

Double-click install.bat or run it from a terminal:

install.bat

This script will:

  1. Create a Python 3.11 virtual environment in .venv/.
  2. Install PyTorch with CUDA 11.8 support.
  3. Install all remaining dependencies from requirements.txt.

Installation requires an internet connection and may take several minutes depending on connection speed.

Step 4 — Launch the application

Double-click launch_matforge.bat or run it from a terminal:

launch_matforge.bat

The application will open automatically in your default browser at http://localhost:8501. The title bar will show [CUDA] if a compatible GPU was detected, or [CPU] if running in fallback mode.

System requirements

Component Requirement
Operating system Windows 10 / 11 (64-bit)
Python 3.11 (must be installed separately)
GPU NVIDIA with 4 GB VRAM (CUDA-capable), recommended
CUDA 11.8
NVIDIA Driver ≥ 452.39
RAM 8 GB minimum
Disk space ~4 GB (models + virtual environment)

Modo CPU: la aplicación funciona sin GPU. Los tiempos de procesado serán significativamente mayores — la generación de mapas que tarda ~6 s en GPU puede tardar varios minutos en CPU.

Nota sobre rendimiento: todas las estimaciones de tiempo mostradas en la interfaz se midieron en una NVIDIA GTX 1650 Max-Q (4 GB VRAM), CUDA 11.8, Python 3.11, Windows 11. Los resultados en otro hardware variarán.

Solución de problemas

install.bat falla inmediatamente — Python 3.11 no encontrado

Síntoma: el script termina con Python 3.11 is not installed or not found.

Causa: Python 3.11 no está instalado, o el lanzador py no puede localizarlo (puede ocurrir si solo está instalado Python 3.12 o posterior).

Solución:

  1. Descarga Python 3.11 desde python.org/downloads.
  2. Durante la instalación, marca Add Python to PATH e Install for all users.
  3. Verifica la instalación: abre una terminal y ejecuta py -3.11 --version. Debe mostrar Python 3.11.x.
  4. Ejecuta install.bat de nuevo.

PyTorch se instala pero CUDA no se detecta en tiempo de ejecución

Síntoma: la aplicación muestra [CPU] a pesar de tener una GPU NVIDIA.

Causa: PyTorch se instaló sin el índice de CUDA 11.8, o el driver de NVIDIA está desactualizado.

Solución:

  1. Verifica la versión del driver: abre el Panel de control de NVIDIA → Ayuda → Información del sistema y comprueba la versión. Debe ser ≥ 452.39.
  2. Si el driver está desactualizado, descarga el más reciente desde nvidia.com/drivers.
  3. Reinstala PyTorch manualmente con el índice correcto:
.venv\Scripts\activate
pip uninstall torch torchvision -y
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118
  1. Reinicia la aplicación.

La aplicación no arranca — pesos de los modelos no encontrados

Síntoma: la aplicación lanza un FileNotFoundError o se interrumpe al arrancar con un mensaje sobre archivos de checkpoint ausentes.

Causa: los archivos de pesos no están presentes o están colocados en una ruta incorrecta.

Solución: verifica que los tres archivos de pesos estén exactamente en estas rutas relativas a la raíz del repositorio:

checkpoints/matforge/best_gan.pt
checkpoints/sr/sr_ft_phase1_best_lpips.pt
checkpoints/sr/RealESRGAN_x4plus.pth

Los nombres de carpeta y archivo distinguen mayúsculas de minúsculas. Crea las carpetas que falten manualmente si es necesario.

El puerto 8501 ya está en uso

Síntoma: el navegador muestra un error de conexión, o la terminal imprime Port 8501 is already in use.

Causa: otra instancia de Streamlit ya está en ejecución.

Solución:

  1. Cierra cualquier otra ventana de terminal que ejecute MatForge u otras aplicaciones Streamlit.
  2. Alternativamente, lanza la aplicación en un puerto distinto:
.venv\Scripts\activate
streamlit run app.py --server.port 8502

Luego abre http://localhost:8502 manualmente en el navegador.

El entorno virtual falla tras mover la carpeta

Síntoma: launch_matforge.bat falla con errores de ruta tras mover el repositorio a una unidad o ubicación diferente.

Causa: los entornos virtuales de Python almacenan rutas absolutas y no pueden reubicarse.

Solución: elimina la carpeta .venv y ejecuta install.bat de nuevo desde la nueva ubicación.

# En PowerShell
Remove-Item -Recurse -Force .venv

Los artefactos del clasificador fallan al cargar — versión incompatible de scikit-learn

Síntoma: la aplicación lanza un ValueError o InconsistentVersionWarning relacionado con scikit-learn al cargar el clasificador de material.

Causa: los artefactos del clasificador KNN (archivos .pkl en artifacts/) fueron serializados con scikit-learn 1.5.2. Hay instalada una versión diferente.

Solución: reinstala la versión exacta requerida:

.venv\Scripts\activate
pip install scikit-learn==1.5.2

La generación de mapas produce un error con imágenes pequeñas

Síntoma: al hacer clic en Generate Maps aparece un RuntimeError sobre el tamaño de padding siendo mayor que la dimensión de entrada.

Causa: la resolución efectiva de la imagen tras el zoom es inferior a 256 px en al menos una dimensión. MatForge requiere un tamaño mínimo de entrada efectiva de 256×256 px.

Solución: aumenta el valor de zoom en el sidebar hasta que la resolución efectiva mostrada sea igual o superior a 256×256 px.

Limitaciones conocidas

  • Los resultados a resoluciones efectivas superiores a 1024 px (por ejemplo, tras Super-Resolución sobre una imagen grande) pueden ser planos o carecer de detalle superficial. MatForge fue entrenado con patches de hasta 1024 px.
  • La evaluación de Normal Map Quality es intensiva en CPU. Mapas superiores a 512×512 px pueden tardar más de un minuto en evaluarse.
  • Los resultados de Make Tileable dependen del contenido de frecuencias del material de entrada. Texturas muy detalladas o no repetitivas pueden mostrar costuras residuales.
  • Las Variaciones procedurales son intensivas en CPU. El tiempo de procesado escala con la resolución del mapa.

Licencia

MatForge App se distribuye bajo la Licencia Apache 2.0.

Componentes de terceros: PVT-v2-B1 / timm (Apache 2.0), DINOv2 (Apache 2.0), Real-ESRGAN (BSD-3-Clause), dataset MatSynth (CC0 / CC-BY 4.0), Three.js (MIT).

Los pesos preentrenados de PVT-v2-B1 fueron entrenados en ImageNet-1K, que lleva una restricción de uso no comercial. El uso de esta aplicación con fines comerciales puede requerir revisión legal.

# MatForge App — Release v1.0

Release date: May 2026
Compatibility: Windows 10 / 11 (64-bit) · Python 3.11 · CUDA 11.8

What's included

This release contains the ...

Read more
Assets 2
Loading