El decodificador nativo de regiones halftone JBIG2 de PDFlibPas indexa la máscara de skip HSKIP como HSKIP[ng, mg], tal como la define la ITU-T T.88 §6.6.5.1, y coloca las rejillas que alcanzan coordenadas negativas, ya sea por un HGX o HGY negativo o por rotación, con un floor shift verdadero. Ambos detalles son fáciles de hacer mal sin que se lance ningún error: la región halftone simplemente sale troceada o desplazada, y los dos errores se esconden detrás de datos de test que resultan ser simétricos o no negativos. La segunda activa una propiedad de Delphi y Free Pascal que muerde mucho más allá de JBIG2: shr sobre un entero con signo es un desplazamiento lógico, no el >> aritmético que el estándar supone
Las regiones halftone son el tipo de región JBIG2 menos común, así que un decodificador puede procesar miles de documentos escaneados antes de toparse con una fotografía de trama codificada como una de ellas. Cuando le toca, el fallo es desagradable: el archivo parsea, las longitudes de segmento suman, la página tiene el tamaño correcto, y la región es basura
¿Qué decodifica realmente una región halftone JBIG2?
Una región halftone JBIG2 es una rejilla de bitmaps pequeños escogidos de un pattern dictionary, y el trabajo real del decodificador es calcular un índice para cada celda de la rejilla y la posición de píxel donde esa celda aterriza. El pattern dictionary contiene HNUMPATS patrones de HPW × HPH píxeles. El segmento de región halftone describe entonces una rejilla de HGW columnas por HGH filas y una imagen de escala de grises del mismo tamaño, codificada como bitplanes con Gray coding. 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 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 rejilla HGX, HGY es un par de valores de 32 bits, y el vector de rejilla HRX, HRY describe el paso entre celdas vecinas, lo que permite una rejilla rotada. Para la fila de rejilla mg y la columna de rejilla ng, T.88 §6.6.5 calcula la posición de píxel como:
x = (HGX + mg × HRY + ng × HRX) >> 8y = (HGY + mg × HRX − ng × HRY) >> 8
La máscara de skip entra por el flag opcional HENABLESKIP. Cuando el flag está activo, §6.6.5.1 construye un bitmap HSKIP de HGW × HGH y pone HSKIP[ng, mg] a 1 para toda celda cuyo patrón caiga por completo 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 skip bitmap de la región genérica, así que el decodificador aritmético ni lee ni actualiza contexto para una celda saltada. Decodificador y codificador deben concordar en cada bit de HSKIP, o los dos codificadores aritméticos pierden el paso
¿Por qué una máscara HSKIP traspuesta solo rompe rejillas no cuadradas?
Una máscara de skip escrita con las coordenadas intercambiadas solo se delata en una rejilla no cuadrada, porque una rejilla cuadrada mantiene cada coordenada intercambiada dentro de la máscara. Con un acceso de píxel (column, row), un builder que pasa (mg, ng), la fila primero, escribe la máscara traspuesta, mientras el decodificador del bitplane de escala de grises la lee como (ng, mg). Si el bucle de colocación de patrones lee la máscara en el orden intercambiado del builder, los dos coinciden, y una revisión que solo mire la lógica de colocación la da por buena. Los nombres de variables de bucle que contradicen lo que recorren lo empeoran, como un col que camina por filas de la rejilla junto a un Row que camina por columnas
Toma una rejilla de 5 × 3 con patrones de 4 × 4 sobre una región de 16 × 8. Con HRX = 1024 y HRY = 0, la columna 4 de la rejilla cae en x = 16 y la fila 2 en y = 8, ambas fuera de la región. La máscara correcta marca siete celdas: la columna 4 entera y la fila 2 entera. Las escrituras intercambiadas intentan poner píxeles en los índices de fila 3 y 4 de una máscara de solo tres filas de alto, y un setter de bitmap que ignora en silencio las escrituras fuera de rango las descarta. Lo que sobrevive es la columna 2, filas 0 a 2. El decodificador se salta por tanto dos celdas que el codificador codificó, y decodifica seis celdas que el codificador saltó
El decodificador aritmético no falla cuando eso pasa. Decodifica píxeles extra a partir de bits que pertenecen a celdas posteriores, sus contextos leen vecinos equivocados, y cada índice de patrón tras el primer desacuerdo es ruido, razón por la que el síntoma es una región troceada en lugar de unas pocas celdas desplazadas. En una rejilla 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 a la diagonal, por ejemplo una rejilla que sobresale de los bordes derecho e inferior el mismo número de celdas, la máscara traspuesta es bit a bit la correcta. HENABLESKIP además es opcional, debe ser 0 cuando la imagen de escala de grises va codificada en MMR, y los codificadores rara vez lo fijan, así que el error tiene muy pocas formas de salir a la luz. En PDFlibPas el builder escribe HSKIP[ng, mg] y el bucle de colocación lee en el mismo orden
¿Por qué los offsets de rejilla halftone negativos fallan en tres capas?
Una rejilla halftone que empieza a la izquierda o por encima de su región puede fallar en tres sitios distintos de un decodificador, y cada error esconde el siguiente. T.88 permite esa geometría a propósito. Un codificador que alinea su screen con la página en lugar de con la región, o que usa una rejilla rotada, produce de forma natural esquinas de celda negativas que la región recorta. Las tres capas tienen que estar bien a la vez, porque acertar una sola cambia solo el síntoma
Capa 1: un campo con signo leído como sin signo
La T.88 §7.4.5.1.2 define HGX y HGY como valores de 32 bits con signo. Léelos por el mismo helper de 32 bits usado para campos sin signo, uno que hace clamp de todo resultado negativo a 0, y una rejilla pensada para empezar en HGX = -900 se mueve en silencio al origen de la región; en el ejemplo de abajo la imagen entera sale dos filas demasiado abajo. El clamp también esconde las otras dos capas: con el origen forzado a no negativo, una coordenada negativa solo puede aparecer por una rejilla rotada con HRY > 0, donde y = HGY + mg × HRX − ng × HRY cae por debajo de cero en las columnas posteriores de la rejilla
Capa 2: shr no es >> 8
La T.88 escribe >> 8 y se refiere a un desplazamiento 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 desplazamiento lógico: el bit de signo entra como un 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 envía 16 millones de filas más abajo y se descarta como fuera de región. Nada se cuelga; la fila superior del halftone simplemente desaparece
Capa 3: comparar punto fijo en lugar de píxeles
Un test de skip sobre valores de punto fijo no es equivalente a uno sobre posiciones de píxel en cuanto la fracción es distinta de cero. Esquivar el desplazamiento lógico testeando 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 píxeles, 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 queda por completo fuera y hay que saltarla. El codificador la salta, el decodificador la decodifica, y la imagen de escala de grises se desvía exactamente igual que en el caso de la máscara traspuesta
Toma una rejilla de 4 × 3 con patrones de 4 × 4 en HGX = -900, HGY = -512, HRX = 1024 sobre una región de 12 × 10. Las columnas de la rejilla caen en x = -4, 0, 4 y 8, así que la columna 0 está por completo fuera y va en HSKIP; las filas de la rejilla caen en y = -2, 2 y 6, así que la fila 0 hay que recortarla a sus dos filas de píxel inferiores en lugar de descartarla. Acertar las capas de una en una muestra la pila:
| Capas tratadas correctamente | Región decodificada |
|---|---|
| Ninguna | Rejilla arrastrada al origen, imagen entera dos filas demasiado abajo |
| Solo lectura con signo de HGX / HGY | Falta la primera fila de rejilla, el resto emborronado por la deriva del test de skip |
| Lectura con signo, shift de suelo y test de skip en espacio de píxeles | Idéntica, píxel a píxel, a la página calculada de T.88 §6.6.5 y a dos decodificadores de referencia independientes |
PDFlibPas pone todo esto en un único helper, HalftoneGridPixel, compartido por el builder de la máscara de skip y el bucle de colocación. Acumula la coordenada en Int64 para que un producto mg × HRX grande no pueda dar la vuelta, divide entre 256 redondeando hacia menos infinito, y hace clamp a ±MaxInt div 2 para que una rejilla corrupta no desborde después la aritmética de bitmaps. El test de skip compara esos valores de píxel contra HPW, HPH, HBW y HBH, exactamente como lo plantea la §6.6.5.1
¿Cómo se escribe un shift a la derecha aritmético en Delphi?
Delphi no tiene operador de shift aritmético, así que un shift a la derecha con signo correcto hay que escribirlo como una división de suelo, y el div corriente no es esa división. div trunca hacia cero. Para valores no negativos truncamiento y suelo concuerdan, y también concuerdan para valores negativos que son múltiplos exactos del divisor, que es por lo que -512 div 256 = -2 parece estar bien en un test rápido. Discrepan en todo lo demás: -900 div 256 es -3, mientras el suelo es -4, y -1 div 256 es 0, mientras el suelo es -1. Una coordenada JBIG2 con fracción distinta de cero es exactamente el caso donde div da el píxel equivocado
En los compiladores Delphi Win32 y Win64, una variable Integer que contenga -512 desplazada a la derecha 8 da 16777214, y una Int64 que contenga -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 ayudante:
// División de suelo: redondea hacia menos infinito con cualquier signo de A y B.
// B no debe ser 0, y FloorDiv(Low(Integer), -1) desborda 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;
// Shift a la derecha aritmético (el ">>" de C y T.88 sobre valores con signo).
// Con Value negativo, not Value = -Value - 1 no es 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 desborda, incluido Low(Integer). Ambos ayudantes igualaron una referencia de suelo 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 merece la pena guardar en cualquier unit test que toque coordenadas:
var
V: Integer;
begin
V := -900;
Writeln(V shr 8); // 16777212 desplazamiento lógico, la trampa
Writeln(V div 256); // -3 truncamiento hacia cero
Writeln(FloorDiv(V, 256)); // -4 lo que T.88 entiende por >> 8
Writeln(SarInt32(V, 8)); // -4
end;
Math.Floor(V / 256) también devuelve -4, pero su rodeo 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 decodificador halftone?
El decodificador halftone JBIG2 entra en acción cuando PDFlibPas renderiza una página con el renderer incorporado, porque renderizar necesita píxeles. RenderPageToFile y RenderPageToStream llegan ambos a él por los streams de imagen JBIG2Decode de la página, así que volver a renderizar una página halftone es la vía directa para comprobar qué produce el decodificador. El mismo decodificador trata los otros tipos de región JBIG2, tratados en tablas de Huffman personalizadas JBIG2 en el decodificador Pascal puro 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 imágenes JBIG2 en forma nativa, y SaveImageListItemDataToFile o GetImageListItemDataToString te entrega un archivo JBIG2 independiente construido a partir de los bytes del stream: la cabecera de archivo, los datos JBIG2Globals y un segmento de fin de archivo en torno a los datos de página. La propiedad 400 de GetImageListItemIntProperty informa 6 para un elemento así. En ese camino no se decodifica nada, 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 // JBIG2 standalone
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 elemento vuelve como bitmap decodificado y el decodificador halftone sí corre. Más sobre image lists en la extracción de texto, imágenes y fuentes PDF en Delphi
Referencia rápida: reglas de la rejilla halftone JBIG2
- Indexa la máscara de skip como
HSKIP[ng, mg], la columna de rejilla primero, y léela en el mismo orden donde sea que se coloquen celdas (T.88 §6.6.5.1) - Testee cualquier código de halftone o de rejilla con una rejilla no cuadrada y un conjunto asimétrico de celdas fuera de región, porque una rejilla cuadrada puede esconder un índice traspuesto por completo
- Lea
HGXyHGYcomo valores de 32 bits con signo (T.88 §7.4.5.1.2), nunca a través de un ayudante sin signo que clampee los negativos - Traduzca el
>> 8del estándar como una división de suelo por 256, no comoshr 8ni comodiv 256 - Ejecute el test de skip sobre posiciones de píxel desplazadas; la forma de punto fijo difiere siempre que la fracción sea distinta de cero, como muestra
HGX = -900con un patrón de 4 píxeles - Acumule coordenadas de rejilla en
Int64y clampee antes de entregarlas a código de bitmap, para que una rejilla corrupta no pueda desbordar
PDFlibPas renderiza, extrae y edita documentos PDF desde Delphi y C++Builder con un decodificador JBIG2 Pascal nativo que trata máscaras de skip halftone, orígenes de rejilla negativos y rejillas rotadas como especifica T.88. Consulta la librería PDF PDFlibPas para Delphi para características, ediciones y una descarga de prueba