FastQRGenerator

Recursos

Tudo que é preciso para ir de uma string a um símbolo escaneável, sem bagagem transitiva.

Instalação

<dependency>
  <groupId>io.github.fineiasantonio</groupId>
  <artifactId>fastqrgenerator</artifactId>
  <version>1.0.0-beta</version>
</dependency>

implementation 'io.github.fineiasantonio:fastqrgenerator:1.0.0-beta'

Começando

Nenhuma versão ou nível de ECC é obrigatório — a menor versão que couber é escolhida automaticamente, com nível M por padrão.

QRCodeGenerator generator = new QRCodeGeneratorBuilder().build();

QRCode qr = generator.generate("https://github.com/FineiasAntonio/FastQRGenerator");

try (FileOutputStream out = new FileOutputStream("qr.png")) {
    qr.writeImage(out, ImageExtensions.PNG);
}

String svg = qr.getAsSVG();   // SVG escalável, sem envolver AWT
qr.print();                   // blocos ANSI direto no terminal

Estilização

Cores, arredondamento de cantos e largura da zona de silêncio são definidos por um builder de estilo validado. Os três símbolos abaixo foram gerados por esta biblioteca.

estilo padrão

moduleColor("#4F46E5")
cornerRadius(0.5)

moduleColor("#0F766E")
cornerRadius(0.3)

QRCodeStyleDefinitions style = QRCodeStyleDefinitions.builder()
        .moduleColor("#4F46E5")
        .backgroundColor("#FFFFFF")
        .cornerRadius(0.5)
        .centerImage(logo)        // opcional; combine com ECCLevel.Q ou H
        .build();

byte[] png = qr.toImageBytes(ImageExtensions.PNG, 10, style);

Como um QR code é gerado

A biblioteca implementa do zero o pipeline completo da ISO/IEC 18004. Isto é o que acontece entre generate("...") e um símbolo escaneável:

1. Detecção de modo e codificação em bits

   O payload é varrido uma vez: só dígitos seleciona o modo numérico (3 dígitos empacotados em 10 bits); qualquer outra coisa seleciona o byte mode (UTF-8). O segmento de dados abre com um indicador de modo de 4 bits e um contador de caracteres, seguidos do payload empacotado, de um terminador e dos codewords de preenchimento alternados 0xEC/0x11 que completam exatamente a capacidade de dados do símbolo.

2. Seleção de versão

   Com o tamanho exato em bits conhecido, é selecionada a menor das 40 versões de símbolo (de 21×21 até 177×177 módulos) capaz de comportá-lo no nível de correção de erro escolhido — a menos que uma versão tenha sido fixada explicitamente.

3. Correção de erros Reed-Solomon

   Os codewords de dados são divididos em blocos, e cada bloco é dividido por um polinômio gerador sobre o corpo de Galois GF(2⁸); o resto dessa divisão vira os codewords de correção de erro do bloco. É essa redundância que permite que um símbolo sujo, danificado ou coberto por um logo ainda seja decodificado: os níveis L/M/Q/H recuperam cerca de 7/15/25/30% dos codewords.

4. Intercalação

   Os blocos de dados e de correção são entrelaçados codeword a codeword. Danos físicos tendem a ser localizados, então espalhar cada bloco pelo símbolo inteiro faz com que um risco ou mancha tire um pouco de cada bloco em vez de destruir um por completo.

5. Construção da matriz

   Os padrões de função são estampados na grade: os três padrões localizadores com seus separadores, as linhas de timing, os padrões de alinhamento e o módulo escuro — além das áreas reservadas para as informações de formato e versão. Os bits dos codewords então preenchem os módulos restantes seguindo o zigue-zague da spec, subindo e descendo em colunas de dois módulos a partir do canto inferior direito. A biblioteca computa essa ordem de posicionamento uma única vez por versão e a mantém em cache.

6. Seleção de máscara

   Oito padrões de máscara XOR são aplicados em teste sobre os módulos de dados. Cada candidato é pontuado pelas quatro regras de penalidade da ISO — sequências longas da mesma cor, blocos sólidos, padrões parecidos com o localizador e desbalanceamento claro/escuro — e vence a máscara de menor penalidade, para que o símbolo final evite padrões que confundem leitores. A pontuação usa análise de run-length com saída antecipada assim que um teste se prova pior que o melhor atual.

7. Informações de formato e versão

   O nível de correção de erro e a máscara vencedora são codificados com BCH e escritos duas vezes ao redor dos padrões localizadores; da versão 7 em diante, a informação de versão também é embutida com BCH. Os leitores decodificam essas áreas primeiro, e a redundância BCH as protege contra danos.

8. Renderização

   A matriz pronta é renderizada sob demanda: rasterizada em PNG/JPG/BMP com estilização (cores, módulos arredondados, logo central), emitida como SVG escalável construído direto da matriz sem AWT, impressa no terminal como blocos ANSI, ou lida módulo a módulo via isDark(row, col).

Modo numérico em números

Payloads só de dígitos — boletos, códigos de rastreio, IDs numéricos — são empacotados com 3 dígitos a cada 10 bits em vez de 8 bits por caractere. Símbolos menores significam geração mais rápida e leitura mais fácil. Medido em ECC nível M com seleção automática de versão: