Pipeline de Renderização

Do documento às imagens de página

Entre OpenDocumentAsync e o PNG que chega ao navegador há duas etapas distintas: resolução do visualizador (qual engine carrega o documento, decidido uma vez por abertura) e processamento de página (o que acontece com cada imagem de página a cada solicitação). Conhecer ambas explica por que um formato é renderizado da maneira que é — e o que DefaultRender realmente alterna.

Etapa 1 — Resolvendo o visualizador de formato

A fábrica mapeia a extensão do arquivo para um visualizador através do catálogo de formatos, com três níveis de precedência:

  1. Visualizadores personalizados primeiro. Qualquer coisa que você registrou com DoconutOptions.RegisterViewer(extension, factory, defaultConfig?) supera todos os incorporados.
  2. Visualizadores de família incorporados. O catálogo mapeia cada extensão visualizável para uma família de visualizadores — Word, Excel, PowerPoint, Pdf, Cad, Dgn, Image, Tiff, Psd, Email, Visio, Project, Xps, Epub, Txt, Html, Mht, Dcn — cada um com seu próprio adaptador de engine. Se um plugin licenciado contribui com um visualizador para a mesma extensão, o visualizador do plugin substitui o incorporado. AddDoconut() valida as permissões de plugin registradas na inicialização; o fallback da fábrica para o visualizador incorporado é uma regra defensiva em tempo de execução.
  3. Formatos apenas de plugin. Algumas extensões não têm visualizador incorporado — DICOM (.dcm) existe apenas através do plugin DICOM. Abrir uma sem a capacidade necessária gera:
text
LicenseException: This document type requires the 'Dicom' plugin license.

Uma extensão que nenhum visualizador reivindica gera:

text
FormatNotSupportedException: Document format '<extension>' is not supported.

Após a resolução, a configuração é definida: seu objeto de configuração explícito se você passou um, caso contrário a configuração padrão do formato do catálogo. DocOptions.Password é copiado para a configuração de documentos protegidos.

Etapa 1b — Modo de redirecionamento (DefaultRender = false)

A maioria das configurações por formato expõe uma bandeira DefaultRender. Ela seleciona entre dois caminhos fundamentalmente diferentes:

  • DefaultRender = true — o documento é renderizado nativamente, diretamente para imagens de página.
  • DefaultRender = false — o documento é primeiro convertido para um PDF na memória, o engine de origem é liberado, e um visualizador de PDF assume. O PDF gerado incorpora texto real, então a pesquisa de texto completo obtém realces nativos precisos ao pixel; o pipeline força AllowSearch e AllowCopy ativados para o PDF redirecionado, já que a conversão é invisível ao usuário.

XPS e o padrão do catálogo para MHT utilizam o caminho de redirecionamento. Uma projeção em PDF pode fornecer pesquisa nativa para formatos como HTML e Microsoft Project. Se o PDF resultante contiver imagens sem camada de texto, o visualizador padrão não pode pesquisar esses pixels.

Use o modo de redirecionamento quando precisar de uma projeção PDF contendo texto — ao custo de uma conversão inicial quando o documento é aberto.

Etapa 2 — O pipeline de imagem de página

Páginas renderizadas são processadas por solicitação através de uma sequência fixa:

text
raw page PNG → watermark → rotate/flip → scale → annotation burn → PNG to the response
  • Marca d'água — aplicada a partir do estado da licença (licença ausente, temporária ou de assinatura expirada, domínio inválido, versão incorreta) e de DocOptions.Watermark para seu próprio texto personalizado. Um aplicativo devidamente licenciado — ou uma licença Temporária ativa — sem marca d'água personalizada pula esta etapa.
  • Rotacionar/inverter — o estado por página que o usuário define no widget (90°/180°/270°, inversões horizontal/vertical) é armazenado na sessão e aplicado em cada renderização subsequente daquela página.
  • Escala — miniaturas e níveis de zoom são produzidos escalando a página renderizada para o tamanho alvo solicitado; 0 significa servir no tamanho original.
  • Gravação de anotação — anotações salvas são desenhadas sobre o bitmap para que exportações e imagens de página as exibam.
  • Codificação — o resultado é codificado para PNG usando fluxos de memória agrupados e escrito diretamente na resposta HTTP.

Erros dentro do middleware são retornados como imagens de erro PNG (texto vermelho sobre branco) ao invés de páginas de erro HTTP, para que o widget possa exibi-las na área da página.

Cache de página

BaseConfig.CachePages (padrão true) mantém imagens de página renderizadas na memória durante a vida da sessão do documento, de modo que revisitar uma página não a re-renderiza. BaseConfig.ImageResolution (25–300 DPI, 0 = padrão do formato) é o principal ajuste de qualidade/memória; o padrão de cada formato está documentado em sua página de configuração.

Renderização em um nó vs. muitos

Tudo acima descreve a renderização em um único nó sob demanda para a sessão que abriu o documento. Uma implantação onde um nó renderiza e publica todo o conjunto de artefatos, e outros nós servem essas páginas a partir de armazenamento compartilhado, usa um caminho de leitura diferente — veja Implantações Distribuídas.

Fontes no Linux

As páginas são desenhadas com as fontes instaladas no servidor. No Linux, instale a biblioteca de configuração de fontes antes que o primeiro documento seja aberto (fontconfig no RHEL e Fedora):

bash
apt-get update && apt-get install -y libfontconfig1

Sem ela, abrir um documento falha com The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.. É o único pacote do sistema que Doconut precisa; libgdiplus não é necessário.

Suas dependências trazem um conjunto básico de fontes (DejaVu), então os documentos são renderizados imediatamente. Um documento que solicita uma fonte que o servidor não possui — Calibri, Arial ou Times New Roman em uma imagem Linux típica — recebe a fonte instalada mais próxima, de modo que o texto pode ter largura diferente e quebras de linha podem diferir do Windows. Para uma saída mais próxima do Windows, instale os substitutos métricos compatíveis fonts-liberation, fonts-crosextra-carlito e fonts-crosextra-caladea; adicione fonts-noto-core ou fonts-noto-cjk para outros scripts, ou copie seus próprios arquivos .ttf/.otf para /usr/share/fonts/ e execute fc-cache -f.

Alpine e outras distribuições baseadas em musl não são suportadas.

Onde ajustar o quê

O que você desejaAjuste
Páginas mais nítidasImageResolution na configuração do formato
Pesquisa de texto precisa em HTML/EPUB/email/MHT/MPPDefaultRender = false na configuração do formato
Menor uso de memória em documentos enormesCachePages = false, feche sessões explicitamente
Sua própria marca em cada páginaDocOptions.Watermark

Esta página foi útil?