Skip to content

A fast, helpful, and open-source document parser

merge main

Logan Markewich8a7141557b31
diff --cc cli/parse.ts
index ff2a08a,5104e20..5b72400
--- a/cli/parse.ts
+++ b/cli/parse.ts
@@@ -27,9 -28,15 +28,16 @@@ interface ParseCommandOptions
preciseBbox?: boolean;
preserveSmallText?: boolean;
password?: string;
+ experimental?: boolean;
config?: string;
quiet?: boolean;
+ debug?: boolean;
+ debugTrace?: boolean;
+ debugVisualize?: boolean;
+ debugOutput?: string;
+ debugTextFilter?: string[];
+ debugPage?: string;
+ debugRegion?: string;
}
interface ScreenshotCommandOptions {
@@@ -83,9 -90,21 +91,22 @@@ progra
.option("--no-precise-bbox", "Disable precise bounding boxes")
.option("--preserve-small-text", "Preserve very small text")
.option("--password <password>", "Password for encrypted/protected documents")
+ .option("--experimental", "Use experimental Rust-based PDF engine")
.option("--config <file>", "Config file (JSON)")
.option("-q, --quiet", "Suppress progress output")
+ .addOption(new Option("--debug", "Enable grid projection debug logging").hideHelp())
+ .addOption(new Option("--debug-trace", "Enable detailed render decision tracing").hideHelp())
+ .addOption(new Option("--debug-visualize", "Generate grid visualization PNGs").hideHelp())
+ .addOption(new Option("--debug-output <path>", "Output directory for debug files").hideHelp())
+ .addOption(
+ new Option("--debug-text-filter <texts...>", "Filter debug output by text content").hideHelp()
+ )
+ .addOption(
+ new Option("--debug-page <num>", "Filter debug output to specific page number").hideHelp()
+ )
+ .addOption(
+ new Option("--debug-region <coords>", 'Filter to bounding region "x1,y1,x2,y2"').hideHelp()
+ )
.action(async (file: string, options: ParseCommandOptions) => {
try {
const quiet = options.quiet || false;
@@@ -128,9 -147,27 +149,28 @@@
preciseBoundingBox: options.preciseBbox !== false,
preserveVerySmallText: options.preserveSmallText || false,
password: options.password,
+ experimental: options.experimental || false,
};
+ // Build debug config if any debug flags are set
+ if (options.debug || options.debugTrace || options.debugVisualize) {
+ let regionFilter: { x1: number; y1: number; x2: number; y2: number } | undefined;
+ if (options.debugRegion) {
+ const [x1, y1, x2, y2] = options.debugRegion.split(",").map(Number);
+ regionFilter = { x1, y1, x2, y2 };
+ }
+ config.debug = {
+ enabled: true,
+ trace: options.debugTrace,
+ visualize: options.debugVisualize,
+ visualizePath: options.debugOutput ?? "./debug-output",
+ outputPath: options.debugOutput ? `${options.debugOutput}/debug.log` : undefined,
+ textFilter: options.debugTextFilter,
+ pageFilter: options.debugPage ? parseInt(options.debugPage) : undefined,
+ regionFilter,
+ };
+ }
+
// Create parser
const parser = new LiteParse(config);
diff --cc src/core/parser.ts
index a711aca,f066049..2ed7cf2
--- a/src/core/parser.ts
+++ b/src/core/parser.ts
@@@ -160,71 -157,61 +160,72 @@@ export class LiteParse
log(`Loaded PDF with ${doc.numPages} pages`);
- let processedPages: import("./types.js").ParsedPage[];
-
- if (this.config.experimental && this.pdfEngine instanceof LiteParseRsEngine) {
- // Rust pipeline: extract + grid projection in one shot
- processedPages = await this.pdfEngine.parseDocument(
- doc,
- this.config.maxPages,
- this.config.targetPages
- );
- } else {
- // TypeScript pipeline: extract, OCR, then grid projection
- const pages = await this.pdfEngine.extractAllPages(
- doc,
- this.config.maxPages,
- this.config.targetPages
- );
+ try {
- // Extract pages
- const pages = await this.pdfEngine.extractAllPages(
- doc,
- this.config.maxPages,
- this.config.targetPages,
- { extractImages: this.config.ocrEnabled }
- );
-
- // run BEFORE grid projection
- if (this.ocrEngine) {
- await this.runOCR(doc, pages, log);
- }
++ let processedPages: import("./types.js").ParsedPage[];
++
++ if (this.config.experimental && this.pdfEngine instanceof LiteParseRsEngine) {
++ // Rust pipeline: extract + grid projection in one shot
++ processedPages = await this.pdfEngine.parseDocument(
++ doc,
++ this.config.maxPages,
++ this.config.targetPages
++ );
++ } else {
++ // TypeScript pipeline: extract, OCR, then grid projection
++ const pages = await this.pdfEngine.extractAllPages(
++ doc,
++ this.config.maxPages,
++ this.config.targetPages,
++ { extractImages: this.config.ocrEnabled }
++ );
+
- // run BEFORE grid projection
- if (this.ocrEngine) {
- await this.runOCR(doc, pages, log);
- }
++ // run BEFORE grid projection
++ if (this.ocrEngine) {
++ await this.runOCR(doc, pages, log);
++ }
-- // Process pages with complete grid projection (after OCR)
- processedPages = projectPagesToGrid(pages, this.config);
- }
- const processedPages = await projectPagesToGrid(pages, this.config);
++ // Process pages with complete grid projection (after OCR)
++ const processedPages = await projectPagesToGrid(pages, this.config);
- // Build bounding boxes if enabled
- if (this.config.preciseBoundingBox) {
- for (const page of processedPages) {
- page.boundingBoxes = buildBoundingBoxes(page.textItems);
- }
- }
- // Build bounding boxes if enabled
- if (this.config.preciseBoundingBox) {
- for (const page of processedPages) {
- page.boundingBoxes = buildBoundingBoxes(page.textItems);
++ // Build bounding boxes if enabled
++ if (this.config.preciseBoundingBox) {
++ for (const page of processedPages) {
++ page.boundingBoxes = buildBoundingBoxes(page.textItems);
++ }
+ }
- }
- // Build final text
- const fullText = processedPages.map((p) => p.text).join("\n\n");
- // Build final text
- const fullText = processedPages.map((p) => p.text).join("\n\n");
-
- const result: ParseResult = {
- pages: processedPages,
- text: fullText,
- };
-
- // Format based on output format
- switch (this.config.outputFormat) {
- case "json":
- result.json = JSON.parse(formatJSON(result));
- break;
- case "text":
- // Already in text format
- break;
- }
++ // Build final text
++ const fullText = processedPages.map((p) => p.text).join("\n\n");
+
- // Close PDF document
- await this.pdfEngine.close(doc);
++ const result: ParseResult = {
++ pages: processedPages,
++ text: fullText,
++ };
+
- // Cleanup OCR engine if it's Tesseract (to free memory)
- if (this.ocrEngine && "terminate" in this.ocrEngine) {
- await (this.ocrEngine as TesseractEngine).terminate();
- }
++ // Format based on output format
++ switch (this.config.outputFormat) {
++ case "json":
++ result.json = JSON.parse(formatJSON(result));
++ break;
++ case "text":
++ // Already in text format
++ break;
++ }
- // Cleanup temporary conversion files
- if (needsCleanup && cleanupPath) {
- await cleanupConversionFiles(cleanupPath);
- }
- return result;
++ return result;
++ }
+ } finally {
+ // Always release resources, even if processing throws
+ await this.pdfEngine.close(doc);
- const result: ParseResult = {
- pages: processedPages,
- text: fullText,
- };
+ if (this.ocrEngine && "terminate" in this.ocrEngine) {
+ await (this.ocrEngine as TesseractEngine).terminate();
+ }
- // Format based on output format
- switch (this.config.outputFormat) {
- case "json":
- result.json = JSON.parse(formatJSON(result));
- break;
- case "text":
- // Already in text format
- break;
+ if (needsCleanup && cleanupPath) {
+ await cleanupConversionFiles(cleanupPath);
+ }
}
-
- return result;
}
/**
diff --cc src/core/types.ts
index d67569c,3ff1e5d..1abcc14
--- a/src/core/types.ts
+++ b/src/core/types.ts
@@@ -137,14 -139,25 +139,34 @@@ export interface LiteParseConfig
*/
password?: string;
+ /**
+ * Use the experimental Rust-based PDF engine (`liteparse-rs`) instead of PDF.js.
+ * Requires the `liteparse-rs` binary to be built. Set the `LITEPARSE_RS_BIN`
+ * environment variable to override the default binary path.
+ *
+ * @defaultValue `false`
+ */
+ experimental?: boolean;
++
+ /**
+ * Debug configuration for grid projection. When enabled, logs detailed
+ * information about how text elements are snapped, anchored, and projected.
+ * Can also generate visual PNG overlays of the projection.
+ *
+ * @example
+ * ```typescript
+ * const parser = new LiteParse({
+ * debug: {
+ * enabled: true,
+ * textFilter: ["Total", "Revenue"],
+ * pageFilter: 2,
+ * visualize: true,
+ * visualizePath: "./debug-output",
+ * }
+ * });
+ * ```
+ */
+ debug?: GridDebugConfig;
}
/**