IMG2SVG | Michaell Alavedra

O propósito deste documento é apresentar uma análise abrangente do IMG2SVG, um sistema projetado para a conversão avançada de imagens raster em vetores SVG escaláveis. Ele detalha as motivações, o design estrutural e as decisões técnicas que sustentam o funcionamento da aplicação.

1. Utilidade e Funcionamento Geral

O Problema

A digitalização de gráficos frequentemente envolve lidar com imagens raster (bitmaps) que sofrem com pixelização e ruído, o que limita sua utilidade em mídias de alta resolução ou em design gráfico puro. A vetorização convencional exige ferramentas de desktop pesadas ou serviços em nuvem que podem comprometer a privacidade ou a imediatez. Além disso, as imagens de origem costumam ser granuladas, resultando em saídas vetorizadas com milhares de caminhos desnecessários que degradam o desempenho de renderização.

A Solução Operacional

Projetei o IMG2SVG como uma ferramenta Local-First focada em resolver a transição de raster para vetor de forma imediata e privada, dentro do navegador web.

O fluxo de trabalho principal é direto:

Upload e Seleção: O usuário fornece uma imagem raster por meio de um painel de upload ou selecionando um arquivo local armazenado anteriormente.
Pré-processamento: Antes de traçar os vetores, o sistema aplica filtros configuráveis (Box Blur, filtragem por mediana ou quantização K-Means). Isso estabiliza o ruído e simplifica a estrutura da imagem original.
Vetorização: A imagem é traçada e convertida em instruções matemáticas (SVG). Todo o processo de cálculo, que consome muitos recursos, é abstraído da interface principal para evitar bloqueios operacionais.
Iteração Visual: O usuário manipula as configurações e aplica alterações. A ferramenta persiste localmente tanto o resultado quanto a configuração utilizada, permitindo restaurar o trabalho exato em sessões posteriores.

2. Arquitetura Geral e Padrões Estruturais

Para garantir um desempenho ideal e manter o desacoplamento entre o núcleo computacional e a visualização, estruturei o projeto com base em uma clara separação de responsabilidades, com foco em aplicações web progressivas (PWA) orientadas a processamento intensivo.

Modelo “Local-First” e Descarregamento Computacional

A lógica de negócio exige processamento intensivo de CPU no lado do cliente. Por isso, deleguei integralmente as camadas de pré-processamento de pixels e de vetorização a Web Workers.

graph TD
    UI[Camada de UI e Estado] -->|Envia dados e parâmetros| Worker[Web Worker: imageTracerJS + Pré-processamento]
    Worker -->|Retorna string SVG| UI
    UI <-->|Lê / Persiste| IDB[(IndexedDB)]

Esse design impede que operações custosas, como o cálculo de centroides K-Means ou o traçado de caminhos vetoriais, bloqueiem a thread principal (Main Thread), garantindo uma interface de usuário fluida.

3. Modelagem de Dados e Lógica de Estado

O estado da aplicação se divide em duas dimensões principais: memória volátil para a interação em tempo real e memória persistente para o armazenamento de longo prazo.

Armazenamento Persistente

Utilizo o IndexedDB para armazenar entidades locais sem depender de um backend externo. Defini uma entidade principal, ImageRecord, que armazena não apenas os binários originais e os SVGs gerados, mas também as configurações exatas utilizadas.

erDiagram
    ImageRecord {
        number id PK
        string name
        Blob originalBlob
        string previewUrl
        string svgContent
        number createdAt
        number updatedAt
        Object settings
    }

Gerenciamento de Estado Reativo

O estado efêmero e global da interface do usuário é gerenciado por meio de uma única árvore de estado imutável (implementada com Zustand).

classDiagram
    class AppState {
        +number currentImageId
        +boolean processing
        +number progress
        +VectorizerSettings settings
        +String[] detectedColors
        +String[] hiddenColors
        +setCurrentImageId(id)
        +setProcessing(bool)
        +updateSettings(settings)
    }
    class VectorizerSettings {
        +number ltres
        +number qtres
        +number preprocessBlur
        +number preprocessQuantize
        +...
    }
    AppState *-- VectorizerSettings

Essa separação me permite reidratar facilmente a aplicação carregando um ImageRecord do banco de dados e aplicando suas settings diretamente ao AppState, restaurando a sessão do usuário com precisão.

4. Stack Tecnológico

A seleção de tecnologias responde à necessidade de equilibrar alto desempenho com uma arquitetura manutenível e fortemente tipada.

Tecnologia	Papel Arquitetural	Justificativa Técnica
Astro	Framework de roteamento e estrutura principal.	Permite a geração de sites estáticos com arquitetura de ilhas, reduzindo a carga de JavaScript na thread principal e habilitando PWA nativa (`@vite-pwa/astro`).
React	Construção da UI interativa (Componentes).	Implementado como ilhas (`client:only="react"`) para governar apenas a lógica dinâmica complexa de vetorização e iteração visual.
Zustand	Gerenciamento de estado global efêmero.	Fornece um mecanismo pub/sub leve que evita as re-renderizações desnecessárias associadas à Context API.
Dexie.js	Camada de persistência (wrapper de IndexedDB).	Simplifica transações assíncronas e facilita índices compostos para um armazenamento robusto de blobs no navegador.
Web Workers	Isolamento de threads computacionais.	Descarrega o pré-processamento de imagens (Filtro de Mediana, K-Means) e a invocação do `imagetracerjs` para liberar a thread principal.
Tailwind CSS	Sistema de design baseado em utilitários.	Mantém o CSS visualmente acoplado aos componentes sem aumentar a carga cognitiva em arquivos externos, garantindo suporte ao Modo Escuro.
Biome.js	Linter e formatador unificado.	Substitui o pipeline tradicional ESLint/Prettier, oferecendo uma análise estática mais rápida (baseada em Rust) para o código TypeScript.

Conclusão

A arquitetura implementada no IMG2SVG demonstra que o ecossistema web moderno é capaz de suportar aplicações tradicionalmente vinculadas a recursos de desktop ou a arquiteturas cliente-servidor pesadas. Ao utilizar Web Workers para descarregar tarefas computacionais e IndexedDB para construir uma experiência local-first resiliente, o sistema garante privacidade, desempenho e determinismo. O encapsulamento do estado por meio do Zustand e a segmentação dinâmica dos processos transformam uma série de tarefas matemáticas intensivas em um fluxo de trabalho interativo, fluido e confiável para a manipulação de vetores.