Renderização de Código de Barras

Aspose.BarCode FOSS para Python separa a codificação da renderização. Depois que um código de barras é codificado em um EncodedSymbol, uma implementação Renderer converte a matriz de módulos em saída visual. A biblioteca inclui SvgRenderer e PngRenderer.

RenderOptions

RenderOptions controla a saída visual de todos os renderizadores. Passe-o para to_svg() ou to_png() em qualquer objeto Barcode:

import aspose_barcode_foss as barcode
from aspose_barcode_foss import RenderOptions

bc = barcode.code128("Hello World")
svg = bc.to_svg(options=RenderOptions(
    scale=2.0,
    foreground_color="#003366",
    quiet_zone=10.0,
    show_text=True,
))

Propriedade	Tipo	Descrição
`scale`	`float`	Multiplicador de escala uniforme para todo o código de barras
`dpi`	`int`	Resolução para saída PNG (não afeta o SVG)
`module_width`	`float`	Largura de um módulo de código de barras em unidades do usuário
`module_height`	`float`	Altura de um módulo de código de barras em unidades do usuário
`quiet_zone`	`float`	Preenchimento de espaço em branco ao redor do código de barras
`foreground_color`	`str`	Cor hexadecimal para barras e módulos (por exemplo, `"#000000"`)
`background_color`	`str`	Cor hexadecimal para plano de fundo
`transparent_background`	`bool`	Fundo transparente para saída PNG
`show_text`	`bool`	Mostrar texto legível abaixo do código de barras
`font_family`	`str`	Fonte para texto legível
`font_size`	`float`	Tamanho da fonte para texto legível

ResolvedRenderOptions

ResolvedRenderOptions é a configuração totalmente mesclada produzida por OptionsResolver.resolve(). Ela combina RenderOptions fornecidos pelo usuário com os padrões SymbologyProfile. Todas as propriedades têm valores concretos (sem None).

A propriedade Barcode.default_render_options contém o RenderOptions passado no momento da geração (ou None se não fornecido).

Saída SVG

SvgRenderer produz saída SVG. Chame to_svg() em um objeto Barcode:

bc = barcode.ean13("590123412345")
svg_string = bc.to_svg()

# With custom options
svg_custom = bc.to_svg(options=RenderOptions(
    scale=3.0,
    foreground_color="#1a1a1a",
    show_text=True,
    font_family="Helvetica",
    font_size=12.0,
))

with open("ean13.svg", "w") as f:
    f.write(svg_custom)

to_svg() retorna um str contendo o documento SVG completo.

Saída PNG

PngRenderer produz saída PNG. Chame to_png() em um objeto Barcode:

bc = barcode.qr("https://example.com")
png_bytes = bc.to_png()

# With custom options
png_custom = bc.to_png(options=RenderOptions(
    scale=4.0,
    dpi=300,
    transparent_background=True,
))

with open("qr.png", "wb") as f:
    f.write(png_custom)

to_png() retorna bytes contendo os dados da imagem PNG.

Abstração do Renderizador

A classe base abstrata Renderer define a interface para todos os renderizadores:

class Renderer(ABC):
    def render(self, symbol, layout, options) -> RenderedArtifact: ...

SvgRenderer e PngRenderer implementam esta interface. Você pode chamar Barcode.render(renderer, options) para usar um renderizador específico diretamente:

from aspose_barcode_foss import SvgRenderer, RenderOptions

bc = barcode.code128("DATA")
artifact = bc.render(SvgRenderer(), RenderOptions(scale=2.0))
print(artifact.media_type)  # "image/svg+xml"
print(type(artifact.data))  # <class 'str'>

RenderedArtifact

O RenderedArtifact retornado por Renderer.render() contém:

Propriedade	Tipo	Descrição
`data`	`str	bytes`
`media_type`	`str`	Tipo MIME (`"image/svg+xml"` ou `"image/png"`)
`backend`	`str`	Identificador do renderizador

Layout de Texto

Cada simbologia tem um TextLayoutPolicy que determina como o texto legível por humanos é posicionado abaixo do código de barras. O método create_layout(symbol, options) retorna um TextLayout contendo objetos TextSegment com dados de posição e texto.

QR Code usa QrTextLayoutPolicy, que fornece um layout no-op (QR códigos não exibem texto legível por humanos).

Dicas e Melhores Práticas

Use scale para dimensionamento uniforme e module_width/module_height para controle preciso de dimensões — não combine ambos.
Defina dpi=300 para saída PNG de qualidade de impressão; o padrão é resolução de tela.
Use transparent_background=True para códigos de barras PNG que serão sobrepostos em fundos coloridos.
foreground_color e background_color aceitam strings de cor hex padrão ("#RRGGBB").
A saída SVG é independente de resolução — prefira SVG para incorporação na web e em PDF.

Problemas comuns

Problema	Causa	Correção
PNG aparece muito pequeno	A escala padrão é 1.0	Aumente `scale` ou defina `dpi`
Texto não visível	`show_text` tem como padrão `False`	Definir `show_text=True`
QR code não tem texto	QR simbologia não suporta texto legível por humanos	Comportamento esperado — QR usa layout de texto no-op
Cores não aplicadas	Nome da propriedade com erro de ortografia	Use nomes de propriedade exatos: `foreground_color`, `background_color`

Ver também

Aspose.BarCode for Python — Enterprise Documentation