Skip to content

Release v1.0 - Checkpoints

Latest
Latest

Choose a tag to compare

View all tags
@migueljeronimogutierrez migueljeronimogutierrez released this 14 May 00:52
· 59 commits to main since this release
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 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)

CPU mode: the application runs without a GPU. Processing times will be significantly longer — map generation that takes ~6 s on GPU may take several minutes on CPU.

Performance note: all processing time estimates shown in the application interface were benchmarked on an NVIDIA GTX 1650 Max-Q (4 GB VRAM), CUDA 11.8, Python 3.11, Windows 11. Results on other hardware will vary.

Troubleshooting

install.bat fails immediately — Python 3.11 not found

Symptom: the script exits with Python 3.11 is not installed or not found.

Cause: Python 3.11 is not installed, or the py launcher cannot locate it (this can happen if only Python 3.12 or later is installed).

Fix:

  1. Download Python 3.11 from [python.org/downloads](https://www.python.org/downloads/release/python-3119/).
  2. During installation, check Add Python to PATH and Install for all users.
  3. Verify the installation: open a terminal and run py -3.11 --version. It should print Python 3.11.x.
  4. Run install.bat again.

PyTorch installs but CUDA is not detected at runtime

Symptom: the application title shows [CPU] despite having an NVIDIA GPU.

Cause: PyTorch was installed without the CUDA 11.8 index, or the NVIDIA driver is outdated.

Fix:

  1. Verify your driver version: open NVIDIA Control Panel → Help → System Information and check the driver version. It must be ≥ 452.39.
  2. If the driver is outdated, download the latest driver from [nvidia.com/drivers](https://www.nvidia.com/drivers).
  3. Reinstall PyTorch manually with the correct index:
.venv\Scripts\activate
pip uninstall torch torchvision -y
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118
  1. Restart the application.

Application fails to start — model weights not found

Symptom: the application raises a FileNotFoundError or crashes on startup with a message about missing checkpoint files.

Cause: the weight files are missing or placed in the wrong location.

Fix: verify that the three weight files are in exactly these paths relative to the repository root:

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

Folder and file names are case-sensitive. Create missing folders manually if needed.

Port 8501 is already in use

Symptom: the browser shows a connection error, or the terminal prints Port 8501 is already in use.

Cause: another Streamlit instance is already running.

Fix:

  1. Close any other terminal windows running MatForge or other Streamlit apps.
  2. Alternatively, launch on a different port:
.venv\Scripts\activate
streamlit run app.py --server.port 8502

Then open http://localhost:8502 manually in your browser.

Virtual environment fails after moving the folder

Symptom: launch_matforge.bat fails with path-related errors after the repository folder was moved to a different drive or location.

Cause: Python virtual environments store absolute paths and cannot be relocated.

Fix: delete the .venv folder and run install.bat again from the new location.

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

Classifier artifacts fail to load — scikit-learn version mismatch

Symptom: the application raises a ValueError or InconsistentVersionWarning related to scikit-learn when loading the material classifier.

Cause: the KNN classifier artifacts (.pkl files in artifacts/) were serialised with scikit-learn 1.5.2. A different version is installed.

Fix: reinstall the exact required version:

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

Map generation produces an error for small images

Symptom: clicking Generate Maps raises a RuntimeError about padding size being larger than the input dimension.

Cause: the effective resolution of the image after zoom is below 256 px in at least one dimension. MatForge requires a minimum effective input size of 256×256 px.

Fix: increase the zoom value in the sidebar until the displayed effective resolution is at or above 256×256 px.

Known limitations

  • Results at effective resolutions above 1024 px (e.g. after Super-Resolution on a large image) may be flat or lack surface detail. MatForge was trained on patches up to 1024 px.
  • Normal Map Quality evaluation is CPU-intensive. Maps larger than 512×512 px may take over a minute to evaluate.
  • Make Tileable results depend on the frequency content of the input material. Highly detailed or non-repetitive textures may show residual seams.
  • Procedural Variations are CPU-intensive. Processing time scales with map resolution.

License

MatForge App is released under the Apache License 2.0.

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

The pre-trained weights of PVT-v2-B1 were trained on ImageNet-1K, which carries a non-commercial research restriction. Use of this application for commercial purposes may require legal review.

MatForge App — Release v1.0 (Español)

Fecha de release: mayo 2026
Compatibilidad: Windows 10 / 11 (64 bits) · Python 3.11 · CUDA 11.8

Contenido del release

Este release contiene los pesos de los modelos necesarios para ejecutar MatForge App. El código fuente de la aplicación está disponible en el repositorio.

Assets incluidos:

  • best_gan.pt — modelo de inferencia MatForge (encoder PVT-v2-B1 + decoder FPN, fine-tuned con GAN)
  • sr_ft_phase1_best_lpips.pt — modelo de Super-Resolución (Real-ESRGAN, fine-tuned sobre MatSynth)
  • RealESRGAN_x4plus.pth — pesos base de Real-ESRGAN

Instalación

Paso 1 — Clonar o descargar el repositorio

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

Alternativamente, descarga el repositorio como ZIP desde la página del repositorio y extráelo.

Paso 2 — Colocar los pesos de los modelos

Descarga los tres archivos de pesos de este release y colócalos en las siguientes rutas dentro de la carpeta del repositorio:

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

Crea las carpetas si no existen.

Paso 3 — Ejecutar el instalador

Haz doble clic en install.bat o ejecútalo desde una terminal:

install.bat

Este script realizará los siguientes pasos:

  1. Crear un entorno virtual de Python 3.11 en .venv/.
  2. Instalar PyTorch con soporte CUDA 11.8.
  3. Instalar el resto de dependencias desde requirements.txt.

La instalación requiere conexión a internet y puede tardar varios minutos según la velocidad de conexión.

Paso 4 — Arrancar la aplicación

Haz doble clic en launch_matforge.bat o ejecútalo desde una terminal:

launch_matforge.bat

La aplicación se abrirá automáticamente en el navegador predeterminado en http://localhost:8501. La barra de título mostrará [CUDA] si se detectó una GPU compatible, o [CPU] si funciona en modo de reserva.

Requisitos del sistema

Componente Requisito
Sistema operativo Windows 10 / 11 (64 bits)
Python 3.11 (debe instalarse por separado)
GPU NVIDIA con 4 GB VRAM (compatible con CUDA), recomendada
CUDA 11.8
Driver NVIDIA ≥ 452.39
RAM 8 GB mínimo
Espacio en disco ~4 GB (modelos + entorno virtual)

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](https://www.python.org/downloads/release/python-3119/).
  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](https://www.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.

Assets 2
Loading