Artículo técnico

Halftone JBIG2 en PDFlibPas: HSKIP y offsets negativos

El decoder nativo de regiones halftone JBIG2 de PDFlibPas indexa la máscara skip HSKIP como HSKIP[ng, mg], tal como la define ITU-T T.88 §6.6.5.1, y coloca las cuadrículas que llegan a coordenadas negativas, ya sea por un HGX o HGY negativo o por rotación, con un floor shift de verdad. Ambos detalles son fáciles de hacer mal sin que se levante ningún error: la región halftone simplemente sale corrupta o desplazada, y los dos errores se esconden detrás de datos de prueba que resultan ser simétricos o no negativos. El segundo enciende una propiedad de Delphi y Free Pascal que muerde mucho más allá de JBIG2: shr sobre un entero con signo es un shift lógico, no el >> aritmético que el estándar asume

Las regiones halftone son el tipo de región JBIG2 menos común, así que un decoder puede procesar miles de documentos escaneados antes de toparse con una fotografía con screen codificada como tal. Cuando le toca, el fallo es feo: el archivo parsea, las longitudes de los segmentos suman bien, la página tiene el tamaño correcto, y la región es basura

¿Qué decodifica en realidad una región halftone de JBIG2?

Una región halftone de JBIG2 es una cuadrícula de bitmaps chicos elegidos de un pattern dictionary, y el trabajo real del decoder es computar un índice para cada celda de la cuadrícula y la posición en pixels donde esa celda aterriza. El pattern dictionary guarda HNUMPATS patrones de HPW × HPH pixels. El segmento de región halftone describe entonces una cuadrícula de HGW columnas por HGH filas y una imagen de escala de grises del mismo tamaño, codificada como bitplanes Gray-coded. Cada bitplane se decodifica con el procedimiento de región genérica sobre un bitmap de HGW × HGH, primero el plano más significativo, y los planos juntos le dan a cada celda su índice de patrón

La colocación de celdas usa aritmética de punto fijo con una fracción de 8 bits. El origen de la cuadrícula HGX, HGY es un par de valores de 32 bits, y el vector de cuadrícula HRX, HRY describe el paso entre celdas vecinas, lo que permite una cuadrícula rotada. Para la fila de cuadrícula mg y la columna de cuadrícula ng, T.88 §6.6.5 computa la posición en pixels como:

  • x = (HGX + mg × HRY + ng × HRX) >> 8
  • y = (HGY + mg × HRX − ng × HRY) >> 8

La máscara skip entra por el flag opcional HENABLESKIP. Cuando el flag está activo, §6.6.5.1 construye un bitmap HGW × HGH llamado HSKIP y pone HSKIP[ng, mg] en 1 para cada celda cuyo patrón queda completamente fuera de la región: x + HPW <= 0, x >= HBW, y + HPH <= 0 o y >= HBH. Los bitplanes de escala de grises se decodifican entonces con esa máscara como bitmap skip de la región genérica, así que el decoder aritmético ni lee ni actualiza contexto para una celda saltada. Decoder y encoder deben coincidir en cada bit de HSKIP, o los dos codificadores aritméticos se desincronizan

¿Por qué una máscara HSKIP transpuesta solo rompe cuadrículas no cuadradas?

Una máscara skip escrita con sus coordenadas intercambiadas solo se nota en una cuadrícula no cuadrada, porque una cuadrícula cuadrada mantiene cada coordenada intercambiada dentro de la máscara. Con un accessor de pixels (columna, fila), un builder que pasa (mg, ng), fila primero, escribe la máscara transpuesta, mientras el decoder de bitplanes de escala de grises la lee como (ng, mg). Si el loop de colocación de patrones lee la máscara en el orden intercambiado del builder, los dos coinciden, y un review de la lógica de colocación por sí solo la aprueba. Variables de loop nombradas contra lo que iteran lo empeoran, como un col que camina filas de cuadrícula junto a un Row que camina columnas de cuadrícula

Tome una cuadrícula de 5 × 3 de patrones de 4 × 4 sobre una región de 16 × 8. Con HRX = 1024 y HRY = 0, la columna de cuadrícula 4 aterriza en x = 16 y la fila de cuadrícula 2 en y = 8, ambas fuera de la región. La máscara correcta marca siete celdas: toda la columna 4 y toda la fila 2. Las escrituras intercambiadas intentan poner pixels en los índices de fila 3 y 4 en una máscara de solo tres filas de alto, y un setter de bitmap que ignora silenciosamente escrituras fuera de rango las tira. Lo que sobrevive es la columna 2, filas 0 a 2. El decoder entonces salta dos celdas que el encoder codificó, y decodifica seis celdas que el encoder saltó

Máscaras skip halftone JBIG2 de PDFlibPas para una cuadrícula de 5 por 3 donde la HSKIP[ng, mg] correcta marca la columna 4 y la fila 2 como saltadas, mientras que las escrituras transpuestas dirigidas a las filas 3 y 4 de una máscara de tres filas se descartan en silencio y solo sobrevive la columna 2, desincronizando los codificadores aritméticos
Solo una cuadrícula no cuadrada expone una máscara transpuesta, y la desincronización de codificadores resultante corrompe la región en vez de levantar un error

El decoder aritmético no falla cuando eso pasa. Decodifica pixels extra de bits que pertenecen a celdas posteriores, sus contextos leen vecinos equivocados, y cada índice de patrón después del primer desacuerdo es ruido, razón por la cual el síntoma es una región corrupta en vez de unas pocas celdas mal puestas. En una cuadrícula cuadrada el mismo error suele ser invisible: ninguna coordenada intercambiada sale de la máscara, y cuando las celdas fuera de la región son simétricas respecto de la diagonal, una cuadrícula que sobresale de los bordes derecho e inferior por el mismo número de celdas, por ejemplo, la máscara transpuesta es bit por bit la correcta. HENABLESKIP además es opcional, debe ser 0 cuando la imagen de escala de grises está codificada con MMR, y los encoders rara vez lo activan, así que el error tiene muy pocas formas de verse. En PDFlibPas el builder escribe HSKIP[ng, mg] y el loop de colocación lee en el mismo orden

¿Por qué los offsets negativos de cuadrícula halftone fallan en tres capas?

Una cuadrícula halftone que empieza a la izquierda o por encima de su región puede fallar en tres lugares distintos de un decoder, y cada error esconde el siguiente. T.88 permite esta geometría a propósito. Un encoder que alinea su screen con la página en vez de con la región, o que usa una cuadrícula rotada, produce naturalmente esquinas de celda negativas que la región recorta. Las tres capas tienen que estar bien juntas, porque resolver cualquier una por separado solo cambia el síntoma

Capa 1: un campo con signo leído como unsigned

T.88 §7.4.5.1.2 define HGX y HGY como valores de 32 bits con signo. Léalos a través del mismo helper de 32 bits usado para campos unsigned, uno que clampea cada resultado negativo a 0, y una cuadrícula pensada para empezar en HGX = -900 se mueve en silencio al origen de la región; en el ejemplo de abajo la imagen completa sale dos filas más abajo. El clamp además esconde las otras dos capas: con el origen forzado a ser no negativo, una coordenada negativa solo puede aparecer por una cuadrícula rotada con HRY > 0, donde y = HGY + mg × HRX − ng × HRY baja de cero para las columnas de cuadrícula posteriores

Capa 2: shr no es >> 8

T.88 escribe >> 8 y se refiere a un shift aritmético, que redondea hacia menos infinito. La traducción literal es shr 8, y en Delphi y Free Pascal shr sobre un entero con signo es un shift lógico: el bit de signo entra como cero. Para un Integer que guarda -512, shr 8 da 16777214 en lugar de -2. Un patrón que debería dibujarse en y = -2 y recortarse a su mitad inferior se manda 16 millones de filas más abajo y se descarta como fuera de región. Nada crashea; simplemente la fila superior del halftone desaparece

Capa 3: comparar punto fijo en vez de pixels

Un test de skip sobre valores de punto fijo no es equivalente a uno sobre posiciones en pixels cuando la fracción no es cero. Esquivar el shift lógico probando xx + HPW × 256 <= 0 sobre el valor sin desplazar parece un equivalente del test de T.88. Con HGX = -900 y un patrón de 4 pixels, eso da -900 + 1024 = 124, que es positivo, así que la celda no se salta. El estándar desplaza primero: floor(-900 / 256) = -4, y -4 + 4 = 0 cumple x + HPW <= 0, así que la celda está completamente fuera y debe saltarse. El encoder la salta, el decoder la decodifica, y la imagen de escala de grises se desvía exactamente igual que en el caso de la máscara transpuesta

Tres trampas halftone de JBIG2 para una cuadrícula con HGX negativo: un campo con signo leído por un helper unsigned se clampea a cero, el shift right de T.88 traducido como un shr lógico manda un patrón 16 millones de filas hacia abajo, y un test de skip sobre valores de punto fijo mantiene una celda que el encoder saltó
Cada error esconde el siguiente, razón por la cual PDFlibPas maneja las tres capas en un solo helper compartido HalftoneGridPixel que usan el builder de la máscara y el loop de colocación

Tome una cuadrícula de 4 × 3 de patrones de 4 × 4 con HGX = -900, HGY = -512, HRX = 1024 sobre una región de 12 × 10. Las columnas de cuadrícula aterrizan en x = -4, 0, 4 y 8, así que la columna 0 está completamente fuera y va en HSKIP; las filas de cuadrícula aterrizan en y = -2, 2 y 6, así que la fila 0 debe recortarse a sus dos filas de pixels inferiores en vez de descartarse. Resolver las capas de a una a la vez muestra la pila:

Capas resueltas correctamenteRegión decodificada
NingunaCuadrícula arrastrada al origen, imagen completa dos filas más abajo
Solo lectura con signo de HGX / HGYFalta la primera fila de cuadrícula, el resto corrupto por la deriva del test de skip
Lectura con signo, floor shift y test de skip en espacio de pixelsIdéntica, pixel por pixel, a la página computada de T.88 §6.6.5 y a dos decoders de referencia independientes

PDFlibPas pone todo esto en un solo helper, HalftoneGridPixel, compartido por el builder de la máscara skip y el loop de colocación. Acumula la coordenada en Int64 para que un producto mg × HRX grande no pueda hacer wrap, divide entre 256 redondeando hacia menos infinito, y clampea a ±MaxInt div 2 para que una cuadrícula corrupta no pueda hacer overflow después en la aritmética de bitmaps. El test de skip compara esos valores en pixels contra HPW, HPH, HBW y HBH, exactamente como lo plantea §6.6.5.1

¿Cómo se escribe un right shift aritmético en Delphi?

Delphi no tiene un operador de shift aritmético, así que un right shift con signo correcto hay que escribirlo como una división floor, y el div a secas no es esa división. div trunca hacia cero. Para valores no negativos truncamiento y floor coinciden, y también coinciden para valores negativos que son múltiplos exactos del divisor, razón por la cual -512 div 256 = -2 se ve bien en un test rápido. Discrepan en todo lo demás: -900 div 256 es -3, mientras el floor es -4, y -1 div 256 es 0, mientras el floor es -1. Una coordenada JBIG2 con fracción distinta de cero es exactamente el caso donde div da el pixel equivocado

En los compiladores Delphi Win32 y Win64, una variable Integer que guarda -512 desplazada a la derecha 8 bits da 16777214, y un Int64 que guarda -512 da 72057594037927934. Free Pascal también define shr como shift lógico y trae SarLongint y SarInt64 en su unidad System para la versión aritmética, pero esas funciones no existen en Delphi, así que el código compartido entre los dos compiladores necesita su propio helper:

// División floor: redondea hacia menos infinito para cualquier signo de A y B.
// B no debe ser 0, y FloorDiv(Low(Integer), -1) hace overflow igual que div
function FloorDiv(A, B: Integer): Integer;
begin
  Result := A div B;
  if (A mod B <> 0) and ((A < 0) <> (B < 0)) then
    Dec(Result);
end;

// Right shift aritmético (el ">>" de C y T.88 sobre valores con signo).
// Para Value negativo, not Value = -Value - 1 es no negativo, así que
// el shr lógico es seguro ahí, y el not exterior mapea el resultado de vuelta
function SarInt32(Value: Integer; Shift: Integer): Integer;  // Shift 0..31
begin
  if Value >= 0 then
    Result := Value shr Shift
  else
    Result := not ((not Value) shr Shift);
end;

function SarInt64(Value: Int64; Shift: Integer): Int64;      // Shift 0..63
begin
  if Value >= 0 then
    Result := Value shr Shift
  else
    Result := not ((not Value) shr Shift);
end;

El truco del not nunca desplaza un número negativo, así que no depende de cómo trate el compilador el bit de signo, y nunca hace overflow, incluido Low(Integer). Ambos helpers coincidieron con una referencia floor en Int64 sobre varios millones de valores, cada shift de 0 a 31 y los bordes Low(Integer) y High(Integer) en Delphi Win32, Delphi Win64 y Free Pascal x86_64. Un sanity check que vale la pena guardar en cualquier test unitario que toque coordenadas:

var
  V: Integer;
begin
  V := -900;
  Writeln(V shr 8);           // 16777212  shift lógico, la trampa
  Writeln(V div 256);         // -3        truncamiento hacia cero
  Writeln(FloorDiv(V, 256));  // -4        lo que T.88 quiere decir con >> 8
  Writeln(SarInt32(V, 8));    // -4
end;
Recta numérica de PDFlibPas para la coordenada -900 desplazada a la derecha 8 bits: shr da 16777212, div trunca a -3, mientras que FloorDiv y SarInt32 ambas aterrizan en el valor floor -4 que ITU-T T.88 quiere decir con el shift, lo que importa solo cuando la fracción de punto fijo no es cero
Truncamiento y floor coinciden solo en múltiplos exactos, así que -512 div 256 pasa un test rápido y -900 div 256 elige el pixel equivocado

Math.Floor(V / 256) también devuelve -4, pero su desvío por Double pierde precisión para valores Int64 por encima de 253, así que la geometría entera debería quedarse en enteros

¿Qué llamadas de PDFlibPas ejecutan el decoder halftone?

El decoder halftone JBIG2 corre cuando PDFlibPas renderiza una página con el renderer embebido, porque renderizar necesita pixels. RenderPageToFile y RenderPageToStream llegan ambas a él a través de los image streams JBIG2Decode de la página, así que re-renderizar una página halftone es la forma directa de comprobar qué produce el decoder. El mismo decoder maneja los otros tipos de región JBIG2, cubiertos en tablas de Huffman custom de JBIG2 en el decoder puro en Pascal y decodificar archivos JBIG2 de acceso aleatorio en Delphi, y el bitmap renderizado alimenta conversiones como renderizar páginas PDF a monocromo de 1 bit

uses
  SysUtils, PDFlibrary;

var
  Lib: TPDFlib;
  Page: Integer;
begin
  Lib := TPDFlib.Create;
  try
    if Lib.LoadFromFile('scanned-halftone.pdf', '') <> 1 then
      raise Exception.CreateFmt('Load failed, error %d', [Lib.LastErrorCode]);
    for Page := 1 to Lib.PageCount do
      // Renderizar decodifica cada región JBIG2, halftones incluidos
      if Lib.RenderPageToFile(150, Page, PDF_RENDER_PNG,
        Format('page-%.3d.png', [Page])) <> 1 then
        Writeln('Page ', Page, ' was not rendered');
  finally
    Lib.Free;
  end;
end.

La extracción de imágenes normalmente toma otro camino. GetPageImageList devuelve las imágenes JBIG2 en forma nativa, y SaveImageListItemDataToFile o GetImageListItemDataToString le entregan un archivo JBIG2 independiente construido de los bytes del stream: el file header, los datos de JBIG2Globals y un segmento de fin de archivo alrededor de los datos de página. La propiedad 400 de GetImageListItemIntProperty reporta 6 para tal item. En ese camino nada se decodifica, así que un .jb2 extraído que se ve correcto en otro visor mientras la página renderizada muestra ruido apunta al camino de decodificación y no al stream:

var
  ListID, I: Integer;
begin
  Lib.SelectPage(1);
  ListID := Lib.GetPageImageList(0);
  if ListID = 0 then
    Exit;
  try
    for I := 1 to Lib.GetImageListCount(ListID) do
      if Lib.GetImageListItemIntProperty(ListID, I, 400) = 6 then  // standalone JBIG2
        Lib.SaveImageListItemDataToFile(ListID, I, 0,
          Format('page1-image%d.jb2', [I]));
  finally
    Lib.ReleaseImageList(ListID);
  end;
end;

Cuando las máscaras o la conversión de color fuerzan un fallback renderizado, el item vuelve como bitmap decodificado y el decoder halftone sí corre. Más sobre image lists en extracción de texto, imágenes y fuentes de PDF en Delphi

Referencia rápida: reglas de la cuadrícula halftone JBIG2

  • Indexe la máscara skip como HSKIP[ng, mg], columna de cuadrícula primero, y léala en el mismo orden donde sea que se coloquen celdas (T.88 §6.6.5.1)
  • Pruebe cualquier código halftone o de cuadrícula con una cuadrícula no cuadrada y un conjunto asimétrico de celdas fuera de la región, porque una cuadrícula cuadrada puede esconder completamente un índice transpuesto
  • Lea HGX y HGY como valores de 32 bits con signo (T.88 §7.4.5.1.2), nunca a través de un helper unsigned que clampee los negativos
  • Traduzca el >> 8 del estándar como una división floor entre 256, no como shr 8 ni como div 256
  • Ejecute el test de skip sobre posiciones en pixels ya desplazadas; la forma de punto fijo difiere siempre que la fracción no sea cero, como muestra HGX = -900 con un patrón de 4 pixels
  • Acumule coordenadas de cuadrícula en Int64 y clampee antes de entregarlas a código de bitmaps, para que una cuadrícula corrupta no pueda hacer overflow

PDFlibPas renderiza, extrae y edita documentos PDF desde Delphi y C++Builder con un decoder JBIG2 nativo en Pascal que maneja máscaras skip halftone, orígenes de cuadrícula negativos y cuadrículas rotadas como especifica T.88. Vea la librería PDF de Delphi PDFlibPas para features, ediciones y una descarga de prueba