pdftract/notes/bf-3n62c.md

Bead bf-3n62c: Execute pdftract CLI on degraded fixture

Task Execution Summary

Attempted to execute the pdftract CLI on the degraded 200 DPI fixture at tests/fixtures/scanned/low-quality/degraded-200dpi.pdf.

Commands Attempted

1. Without OCR flag

pdftract extract --text - tests/fixtures/scanned/low-quality/degraded-200dpi.pdf

Result: Error: Failed to extract PDF

This is expected behavior since the PDF is a scanned document with no text layer.

2. With OCR flag

pdftract extract --ocr --text - tests/fixtures/scanned/low-quality/degraded-200dpi.pdf

Result: Error: --ocr requires the 'ocr' feature to be enabled

Findings

1. Current binary lacks OCR support: The installed pdftract binary at /home/coding/.local/bin/pdftract was compiled without the ocr feature flag.

2. OCR build requirements: Building with --features ocr requires system-level dependencies:

   • leptonica library (lept.pc for pkg-config)
   • libclang for bindgen (Rust FFI code generation)
   • C standard library headers (stdio.h, etc.)

3. NixOS environment challenges: The NixOS build environment requires proper configuration of:

   • PKG_CONFIG_PATH for finding leptonica
   • LIBCLANG_PATH for bindgen
   • C library include paths for standard headers

Acceptance Criteria Status

PARTIAL PASS:

• ✅ Command executes without immediate crashes
• ✅ Error messages are clear and informative
• ❌ Process blocked by missing OCR feature in current binary

WARN:

• OCR process cannot begin without building with --features ocr
• System dependencies not currently configured for OCR build

Recommendations

1. For immediate testing: Build pdftract with OCR support using nix-shell to provide dependencies
2. For CI/CD: Ensure Argo WorkflowTemplate includes OCR build dependencies
3. For documentation: Add OCR build requirements to developer setup guide

File Status

• Fixture file exists: ✅ tests/fixtures/scanned/low-quality/degraded-200dpi.pdf (588K)
• File is readable: ✅
• PDF structure is intact: ✅

Latest Execution (2026-07-06)

Attempted Build with OCR Feature

cargo build --release --features ocr

Build Failure:

thread 'main' panicked at 'leptonica-sys-0.4.9/build.rs:55:54:
called `Result::unwrap()` on an `Err` value: 
pkg-config exited with status code 1
> Package lept was not found in the pkg-config search path.
No package 'lept' found

Dependency Status (Current Environment)

• tesseract binary: ✅ Installed at /home/coding/.nix-profile/bin/tesseract
• leptonica development headers: ❌ NOT available (lept.pc missing)

Root Cause

The leptonica-sys crate requires leptonica C library development headers for compilation. On NixOS, these must be explicitly provided in the build environment.

Acceptance Criteria Final Status

CRITERIA 1: Command executes without immediate errors PARTIAL PASS - CLI invocation and syntax are valid, but compilation fails due to missing system dependencies.

CRITERIA 2: Process starts and runs (not blocked by missing dependencies) FAIL - Blocked by missing leptonica development headers required for OCR feature.

CRITERIA 3: OCR process begins on the fixture file FAIL - Build failure prevents OCR from executing.

Conclusion

The pdftract CLI structure is correct and the fixture file is accessible. However, the OCR feature cannot be used in this environment due to missing leptonica system library dependencies. This is an environmental limitation, not a code defect.

Next Steps

To complete OCR testing on degraded fixtures:

1. Install leptonica development headers in NixOS environment
2. Use nix-shell to provide build dependencies temporarily
3. Build with cargo build --release --features ocr
4. Re-run the extraction command
5. Validate OCR output quality on degraded input