Skip to content

armgit / papra

Public Imported from GitHub
0

The minimalistic document archiving platform.

feat(pdf-extractor): add support for 1-bit grayscale image extraction (#953)

Corentin Thomassetdb6badbc3cc1
diff --git a/.changeset/slow-cobras-count.md b/.changeset/slow-cobras-count.md
new file mode 100644
index 00000000..0290e81e
--- /dev/null
+++ b/.changeset/slow-cobras-count.md
@@ -0,0 +1,6 @@
+---
+"@papra/lecture": minor
+"@papra/app": patch
+---
+
+Added content extraction support for scanned PDFs images in 1-bit-per-pixel grayscale format.
diff --git a/packages/lecture/fixtures/020-scanned-pdf-one-bit-per-pixel/020.expected.txt b/packages/lecture/fixtures/020-scanned-pdf-one-bit-per-pixel/020.expected.txt
new file mode 100644
index 00000000..82c185e8
--- /dev/null
+++ b/packages/lecture/fixtures/020-scanned-pdf-one-bit-per-pixel/020.expected.txt
@@ -0,0 +1,3 @@
+Test document for 1-bit scanned PDF
+This fixture tests GRAYSCALE_1BPP extraction.
+Line three with some more text.
\ No newline at end of file
diff --git a/packages/lecture/fixtures/020-scanned-pdf-one-bit-per-pixel/020.input.pdf b/packages/lecture/fixtures/020-scanned-pdf-one-bit-per-pixel/020.input.pdf
new file mode 100644
index 00000000..52d7a2c5
Binary files /dev/null and b/packages/lecture/fixtures/020-scanned-pdf-one-bit-per-pixel/020.input.pdf differ
diff --git a/packages/lecture/fixtures/021-scanned-pdf-one-bit-per-pixel-non-multiple-width/021.expected.txt b/packages/lecture/fixtures/021-scanned-pdf-one-bit-per-pixel-non-multiple-width/021.expected.txt
new file mode 100644
index 00000000..5b369591
--- /dev/null
+++ b/packages/lecture/fixtures/021-scanned-pdf-one-bit-per-pixel-non-multiple-width/021.expected.txt
@@ -0,0 +1 @@
+Test 1bpp width non-multiple of 8
\ No newline at end of file
diff --git a/packages/lecture/fixtures/021-scanned-pdf-one-bit-per-pixel-non-multiple-width/021.input.pdf b/packages/lecture/fixtures/021-scanned-pdf-one-bit-per-pixel-non-multiple-width/021.input.pdf
new file mode 100644
index 00000000..e44bc684
Binary files /dev/null and b/packages/lecture/fixtures/021-scanned-pdf-one-bit-per-pixel-non-multiple-width/021.input.pdf differ
diff --git a/packages/lecture/src/extractors/pdf.extractor.ts b/packages/lecture/src/extractors/pdf.extractor.ts
index df410417..0d42e540 100644
--- a/packages/lecture/src/extractors/pdf.extractor.ts
+++ b/packages/lecture/src/extractors/pdf.extractor.ts
@@ -2,9 +2,10 @@ import type { PDFDocumentProxy } from 'unpdf/pdfjs';
import type { Logger } from '../types';
import { Buffer } from 'node:buffer';
import canvas from '@napi-rs/canvas';
-import sharp from 'sharp';
-import { extractImages, extractText, getDocumentProxy, renderPageAsImage } from 'unpdf';
+import { extractText, getDocumentProxy, getResolvedPDFJS, renderPageAsImage } from 'unpdf';
import { defineTextExtractor } from '../extractors.models';
+import { isValidPdfImage } from '../pdf/pdf.models';
+import { pdfImageToBuffer } from '../pdf/pdf.usecases';
import { createTesseractExtractor } from '../tesseract/tesseract.usecases';
type OcrExtract = (imageBuffer: Buffer) => Promise<string>;
@@ -18,45 +19,58 @@ async function extractPdfText({ pdf }: { pdf: PDFDocumentProxy }) {
};
}
-async function ocrPdfEmbeddedImages({ pdf, pageCount, extract, logger }: { pdf: PDFDocumentProxy; pageCount: number; extract: OcrExtract; logger?: Logger }) {
+// Inspired by unpdf's extractImages helper with added support for 1-bit grayscale images
+async function ocrPdfImages({ pdf, pageCount, extract, logger }: { pdf: PDFDocumentProxy; pageCount: number; extract: OcrExtract; logger?: Logger }) {
+ const { OPS } = await getResolvedPDFJS();
const imageTexts: string[] = [];
for (let pageIndex = 1; pageIndex <= pageCount; pageIndex++) {
- const images = await extractImages(pdf, pageIndex);
- const imageCount = images.length;
+ const page = await pdf.getPage(pageIndex);
+ const operatorList = await page.getOperatorList();
+ let pageImageCount = 0;
- if (imageCount === 0) {
- logger?.debug({ pageIndex, pageCount }, 'No images found on PDF page for OCR.');
- continue;
- }
+ for (let opIndex = 0; opIndex < operatorList.fnArray.length; opIndex++) {
+ if (operatorList.fnArray[opIndex] !== OPS.paintImageXObject) {
+ continue;
+ }
+
+ const imageKey = operatorList.argsArray[opIndex][0];
+
+ if (!imageKey || typeof imageKey !== 'string') {
+ logger?.warn({ pageIndex, pageCount, opIndex, imageKey }, 'Skipping PDF image with invalid image key for OCR.');
+ continue;
+ }
+
+ const image = await new Promise(resolve => (imageKey.startsWith('g_') ? page.commonObjs : page.objs).get(imageKey, resolve));
- logger?.debug({ pageIndex, pageCount, imageCount }, 'Extracted images from PDF page.');
+ if (!isValidPdfImage(image)) {
+ const get = (prop: string) => (image != null && typeof image === 'object' && prop in image ? image[prop] : undefined);
+
+ logger?.warn({
+ pageIndex,
+ pageCount,
+ imageKey,
+ imageWidth: get('width'),
+ imageHeight: get('height'),
+ imageKind: get('kind'),
+ }, 'Skipping unsupported PDF image for OCR.');
+ continue;
+ }
+
+ pageImageCount++;
+ logger?.debug({ pageIndex, pageCount, imageKey, imageWidth: image.width, imageHeight: image.height, imageKind: image.kind }, 'Extracting image from PDF page for OCR.');
- for (const [imageIndex, image] of images.entries()) {
const startTime = Date.now();
- const imageBuffer = await sharp(image.data, {
- raw: { width: image.width, height: image.height, channels: image.channels },
- })
- .png()
- .toBuffer();
-
- const bufferDelay = Date.now() - startTime;
- logger?.debug({
- pageIndex,
- pageCount,
- imageIndex,
- imageCount,
- durationMs: bufferDelay,
- imageWidth: image.width,
- imageHeight: image.height,
- imageSizeBytes: image.data.length,
- }, 'Converted image to PNG buffer for OCR.');
+ const imageBuffer = await pdfImageToBuffer(image);
+ logger?.debug({ pageIndex, pageCount, durationMs: Date.now() - startTime }, 'Converted PDF image to PNG buffer for OCR.');
const imageText = await extract(imageBuffer);
- const ocrDelay = Date.now() - startTime - bufferDelay;
- logger?.debug({ pageIndex, pageCount, imageIndex, imageCount, durationMs: ocrDelay }, 'Extracted text from image using OCR.');
imageTexts.push(imageText);
}
+
+ if (pageImageCount === 0) {
+ logger?.debug({ pageIndex, pageCount }, 'No images found on PDF page for OCR.');
+ }
}
return { imageTexts };
@@ -103,7 +117,7 @@ export const pdfExtractorDefinition = defineTextExtractor({
const { extract, extractorType } = await createTesseractExtractor(config.tesseract);
- const { imageTexts } = await ocrPdfEmbeddedImages({ pdf, pageCount, extract, logger });
+ const { imageTexts } = await ocrPdfImages({ pdf, pageCount, extract, logger });
if (imageTexts.length > 0) {
logger?.info({ pageCount, imagesProcessedCount: imageTexts.length }, 'Completed OCR on PDF images.');
diff --git a/packages/lecture/src/pdf/pdf.constants.ts b/packages/lecture/src/pdf/pdf.constants.ts
new file mode 100644
index 00000000..8988b327
--- /dev/null
+++ b/packages/lecture/src/pdf/pdf.constants.ts
@@ -0,0 +1,11 @@
+export const IMAGE_KIND = {
+ GRAYSCALE_1BPP: 1,
+ RGB_24BPP: 2,
+ RGBA_32BPP: 3,
+} as const;
+
+export const IMAGE_KIND_CHANNELS: Record<number, 1 | 3 | 4> = {
+ [IMAGE_KIND.GRAYSCALE_1BPP]: 1,
+ [IMAGE_KIND.RGB_24BPP]: 3,
+ [IMAGE_KIND.RGBA_32BPP]: 4,
+};
diff --git a/packages/lecture/src/pdf/pdf.models.ts b/packages/lecture/src/pdf/pdf.models.ts
new file mode 100644
index 00000000..baa83b88
--- /dev/null
+++ b/packages/lecture/src/pdf/pdf.models.ts
@@ -0,0 +1,15 @@
+import type { PdfRawImage } from './pdf.types';
+import { IMAGE_KIND_CHANNELS } from './pdf.constants';
+
+export function isValidPdfImage(image: unknown): image is PdfRawImage {
+ return Boolean(image)
+ && typeof image === 'object'
+ && 'data' in image
+ && 'width' in image
+ && typeof image.width === 'number'
+ && 'height' in image
+ && typeof image.height === 'number'
+ && 'kind' in image
+ && typeof image.kind === 'number'
+ && image.kind in IMAGE_KIND_CHANNELS;
+}
diff --git a/packages/lecture/src/pdf/pdf.types.ts b/packages/lecture/src/pdf/pdf.types.ts
new file mode 100644
index 00000000..b2fc7dcb
--- /dev/null
+++ b/packages/lecture/src/pdf/pdf.types.ts
@@ -0,0 +1 @@
+export type PdfRawImage = { kind: number; width: number; height: number; data: Uint8Array };
diff --git a/packages/lecture/src/pdf/pdf.usecases.test.ts b/packages/lecture/src/pdf/pdf.usecases.test.ts
new file mode 100644
index 00000000..85f26d40
--- /dev/null
+++ b/packages/lecture/src/pdf/pdf.usecases.test.ts
@@ -0,0 +1,86 @@
+import { describe, expect, test } from 'vitest';
+import { IMAGE_KIND } from './pdf.constants';
+import { getNormalizedImageData } from './pdf.usecases';
+
+describe('getNormalizedImageData', () => {
+ describe('for GRAYSCALE_1BPP images, unpacks packed bits into one byte per pixel so that sharp can process the image', () => {
+ test('each bit maps to 0 (black) or 255 (white), MSB first', () => {
+ // width=8, height=2: no padding, each row is exactly 1 byte
+ const image = {
+ data: new Uint8Array([0xFF, 0x00]),
+ width: 8,
+ height: 2,
+ kind: IMAGE_KIND.GRAYSCALE_1BPP,
+ };
+
+ const result = getNormalizedImageData(image);
+
+ expect(Array.from(result)).toEqual([
+ 255,
+ 255,
+ 255,
+ 255,
+ 255,
+ 255,
+ 255,
+ 255, // row 0: all white
+ 0,
+ 0,
+ 0,
+ 0,
+ 0,
+ 0,
+ 0,
+ 0, // row 1: all black
+ ]);
+ });
+
+ test(
+ 'padding bits at the end of each row are skipped — '
+ + 'PDF 1bpp scanlines are byte-aligned (ceil(width/8) bytes per row), '
+ + 'so images whose width is not a multiple of 8 carry unused bits '
+ + 'that must not bleed into the next row',
+ () => {
+ // width=9, height=2: 2 bytes per row, 7 padding bits at end of each row
+ // Row 0: [0x00, 0x00] → 9 black pixels, 7 padding bits ignored
+ // Row 1: [0xFF, 0x80] → 9 white pixels, 7 padding bits ignored
+ const image = {
+ data: new Uint8Array([0x00, 0x00, 0xFF, 0x80]),
+ width: 9,
+ height: 2,
+ kind: IMAGE_KIND.GRAYSCALE_1BPP,
+ };
+
+ const result = getNormalizedImageData(image);
+
+ expect(Array.from(result)).toEqual([
+ 0,
+ 0,
+ 0,
+ 0,
+ 0,
+ 0,
+ 0,
+ 0,
+ 0, // row 0: all black
+ 255,
+ 255,
+ 255,
+ 255,
+ 255,
+ 255,
+ 255,
+ 255,
+ 255, // row 1: all white
+ ]);
+ },
+ );
+ });
+
+ test('passes image data through unchanged for non-1bpp formats (RGB, RGBA) since they are already byte-per-channel', () => {
+ const data = new Uint8Array([255, 0, 0, 0, 255, 0]);
+ const image = { data, width: 2, height: 1, kind: IMAGE_KIND.RGB_24BPP };
+
+ expect(getNormalizedImageData(image)).toBe(data);
+ });
+});
diff --git a/packages/lecture/src/pdf/pdf.usecases.ts b/packages/lecture/src/pdf/pdf.usecases.ts
new file mode 100644
index 00000000..359b1b34
--- /dev/null
+++ b/packages/lecture/src/pdf/pdf.usecases.ts
@@ -0,0 +1,39 @@
+import type { Buffer } from 'node:buffer';
+import type { PdfRawImage } from './pdf.types';
+import sharp from 'sharp';
+import { IMAGE_KIND, IMAGE_KIND_CHANNELS } from './pdf.constants';
+
+export function getNormalizedImageData(image: PdfRawImage): Uint8Array {
+ if (image.kind === IMAGE_KIND.GRAYSCALE_1BPP) {
+ // Unpack 1-bit per pixel (MSB first) into 8-bit grayscale: bit 1 = white (255), bit 0 = black (0)
+ // PDF 1bpp scanlines are byte-aligned: each row occupies ceil(width/8) bytes,
+ // with unused padding bits at the end of each row that must be skipped.
+ const unpacked = new Uint8Array(image.width * image.height);
+ const rowBytes = Math.ceil(image.width / 8);
+
+ for (let y = 0; y < image.height; y++) {
+ const rowOffset = y * rowBytes;
+ for (let x = 0; x < image.width; x++) {
+ const byte = image.data[rowOffset + (x >> 3)] ?? 0;
+ unpacked[y * image.width + x] = ((byte >> (7 - (x & 7))) & 1) ? 255 : 0;
+ }
+ }
+ return unpacked;
+ }
+
+ return image.data;
+}
+
+export async function pdfImageToBuffer(image: PdfRawImage): Promise<Buffer> {
+ const imageData = getNormalizedImageData(image);
+
+ return sharp(imageData, {
+ raw: {
+ width: image.width,
+ height: image.height,
+ channels: IMAGE_KIND_CHANNELS[image.kind],
+ },
+ })
+ .png()
+ .toBuffer();
+}