Skip to content

features.md

Latest commit

 

History

History
235 lines (163 loc) · 6.47 KB

features.md

File metadata and controls

235 lines (163 loc) · 6.47 KB

Funcionalidades

Geração de Mapas PBR

Height Map

Converte uma imagem colorida em um mapa de altura em escala de cinza.

Entrada: Imagem difusa (RGBA) Saída: Height map (grayscale, R32Float internamente)

Algoritmo:

  1. Converter para luminância (grayscale)
  2. Aplicar Gaussian blur em múltiplos níveis
  3. Combinar com pesos ajustáveis
  4. Aplicar contraste e spread

Uso típico:

  • Displacement mapping
  • Parallax occlusion mapping
  • Base para normal map generation

Normal Map

Gera vetores de superfície a partir do height map.

Entrada: Height map (gerado internamente) Saída: Normal map (RGB, formato DirectX/OpenGL)

Algoritmo:

  1. Calcular gradientes via operador Sobel
  2. Construir vetores normais (x, y, z)
  3. Normalizar e codificar para [0, 255]

Formato de saída:

  • Red channel: X component (-1 to +1) → 0 to 255
  • Green channel: Y component (-1 to +1) → 0 to 255
  • Blue channel: Z component (0 to +1) → 128 to 255

Uso típico:

  • Iluminação em tempo real
  • Bump mapping
  • Detalhes de superfície sem geometria adicional

Metallic Map

Detecta áreas metálicas por análise de cor.

Entrada: Imagem difusa original (RGBA) Saída: Metallic map (grayscale, 0 = dieletric, 1 = metal)

Algoritmo:

  1. Converter RGB para espaço HSL
  2. Analisar saturação e luminância
  3. Aplicar heurística de detecção metálica

Heurística:

  • Metais puros têm saturação baixa e luminância alta
  • Ouro/cobre têm matiz específico
  • Thresholds adaptativos baseados na imagem

Uso típico:

  • Physically based rendering (PBR)
  • Diferenciação metal/não-metal
  • Reflexos específicos por material

Smoothness Map

Define rugosidade/suavidade da superfície para PBR.

Entrada: Imagem difusa + mapa metallic (gerados internamente) Saída: Smoothness map (grayscale, 0 = rugoso, 1 = liso)

Algoritmo: Base smoothness (0.25) + contribuição do metallic (0.65 × metallic). Metais tendem a ser mais lisos.

Uso típico: Roughness/smoothness em shaders PBR (Unity, Unreal, etc.).

Edge Map

Destaca bordas e vincos a partir do mapa de normal.

Entrada: Normal map (gerado internamente) Saída: Edge map (grayscale)

Algoritmo: Gradiente da normal (amostras ±1 pixel em X e Y), combinado com contraste. Inspirado no Materialize original (Blit_Edge_From_Normal).

Uso típico: Outline, cavity, ou máscaras para pós-processamento.

AO Map (Ambient Occlusion)

Oclusão ambiente no estilo cavity, a partir do height map.

Entrada: Height map (gerado internamente) Saída: AO map (grayscale, 0 = ocluído, 1 = aberto)

Algoritmo: Amostras em 8 direções (raios 1 e 2 pixels); oclusão quando altura da amostra > centro; resultado invertido e escalado.

Uso típico: Sombreamento em frestas e cantos em pipelines PBR.

Formatos Suportados

Entrada (Leitura)

Formato Extensões Observações
PNG .png Recomendado, lossless
JPEG .jpg, .jpeg Lossy, bom para fotos
TGA .tga Legacy, games
BMP .bmp Limitado, suportado
EXR .exr HDR, linear

Saída (Escrita)

Formato Extensões Melhor uso
PNG .png Geral (lossless)
JPEG .jpg Compacto (lossy)
TGA .tga Games engines
EXR .exr Normal maps (float precision)

Configurações de qualidade:

  • PNG: Compression level 6 (padrão)
  • JPEG: Qualidade 95% (padrão), configurável 0-100
  • EXR: P-tiles, zip compression

Interface CLI

Comando Básico

materialize <INPUT> [OPTIONS]

Opções

Opção Curta Descrição Padrão
--output -o Diretório de saída .
--format -f Formato de saída (png, jpg, tga, exr) png
--quality -q Qualidade JPEG (0-100) 95
--verbose -v Modo verbose false
--quiet Não listar arquivos gerados no sucesso false
--help -h Mostrar ajuda -
--version -V Mostrar versão -

Exemplos de Uso

# Básico - gera na mesma pasta
materialize texture.png
# Resultado: texture_height.png, texture_normal.png, texture_metallic.png,
#           texture_smoothness.png, texture_edge.png, texture_ao.png

# Diretório de saída específico
materialize texture.png -o ./materials/

# Formato diferente
materialize texture.png -f exr

# JPEG com qualidade baixa (mais compacto)
materialize texture.jpg -f jpg -q 80

# Verbose - mostra progresso; --quiet suprime a lista de arquivos
materialize texture.png -v
materialize texture.png --quiet

# Instalar a skill do Cursor no projeto atual
materialize skill install

Features Futuras (Roadmap)

Versão 1.1 - Batch Processing

  • Diretório como input: materialize ./textures/
  • Paralelização: Processa múltiplas imagens simultaneamente
  • Progress bar: Indicação visual de progresso

Versão 2.0 - Configuração Avançada

  • Arquivo de configuração: materialize.toml para parâmetros customizados
  • Override por mapa: --height-blur=5.0 --normal-intensity=2.5

Versão 3.0 - Preview

  • Janela de preview: SDL2-based, visualização 3D rápida
  • Rotação/Pan/Zoom: Navegação básica

Casos de Uso

Game Development

# Pipeline de assets
for texture in assets/textures/raw/*.png; do
    materialize "$texture" -o assets/textures/processed/
done

3D Art / Blender

# Preparar textura para importação
materialize photo.jpg -f exr -o ~/blender_project/textures/
# Importar height para displacement, normal para bump, metallic para shader

Web Development (Three.js/Babylon)

# Otimizar para web (JPEG compacto)
materialize texture.png -f jpg -q 85 -o ./public/textures/

Archviz

# Materiais de alta qualidade
materialize marble_scan.png -f exr -o ./materials/marble/
# EXR preserva precisão de cor para materiais PBR

Limitações Conhecidas

MVP (Versão 1.0)

  1. Parâmetros fixos: Defaults hardcoded (smoothness base/metal, AO depth scale, etc.), sem ajuste fino
  2. Resolução máxima: Limitada por GPU memory (tipicamente 8K+)
  3. Um formato por execução: Todos os seis mapas no mesmo formato
  4. Sem alpha handling: Canal alpha ignorado no processamento
  5. AO simplificado: Cavity-style a partir do height; o Materialize original usa ray marching com normal+height

Futuro

Limitações serão endereçadas conforme roadmap (configuração, tiled processing, etc.)