feat(pdftract-22p): implement signal evaluators for page classification
Implement five signal evaluators that feed PageClassifier::classify: - text_operator_presence: 0 text ops + has images -> Scanned 0.95 - all_tr3_with_full_page_image: all Tr=3 + image >= 95% -> BrokenVector 0.99 (EC-12) - image_coverage_fraction > 0.85 -> Scanned 0.85 - char_validity_rate < 0.4 -> BrokenVector 0.80 - char_validity_rate > 0.85 -> Vector 0.90 - char_density_ratio < 0.03 chars/in^2 -> Scanned 0.65 All thresholds centralized in SignalsConfig struct. PageContext includes all required fields for evaluation. Short-circuit classification at strength >= 0.95. Comprehensive unit tests for each evaluator. Closes: pdftract-22p
This commit is contained in:
jedarden
parent
488d4ea230
commit
2018d684ce
2 changed files with 150 additions and 7 deletions
|
|
@ -28,6 +28,65 @@
|
|||
use serde::{Deserialize, Serialize};
|
||||
use std::collections::BTreeSet;
|
||||
|
||||
/// Signal evaluator configuration constants.
|
||||
///
|
||||
/// Centralizes all threshold constants used by signal evaluators.
|
||||
/// Per EC-12, these thresholds must be kept in sync with fixture expectations.
|
||||
/// Changes to these values require updating fixture expectations and running
|
||||
/// the full test suite to verify correctness.
|
||||
#[derive(Debug, Clone, Copy)]
|
||||
pub struct SignalsConfig;
|
||||
|
||||
impl SignalsConfig {
|
||||
// Evaluator 1: text_operator_presence
|
||||
/// Strength for Scanned vote when no text operators present and images exist.
|
||||
pub const NO_TEXT_OPS_STRENGTH: f32 = 0.95;
|
||||
|
||||
// Evaluator 2: all_tr3_with_full_page_image
|
||||
/// Minimum fraction of page area a single image must cover to be "full page".
|
||||
pub const FULL_PAGE_IMAGE_THRESHOLD: f64 = 0.95;
|
||||
/// Strength for BrokenVector vote when all text is Tr=3 AND full-page image present.
|
||||
pub const ALL_TR3_WITH_IMAGE_STRENGTH: f32 = 0.99;
|
||||
|
||||
// Evaluator 3: image_coverage_fraction
|
||||
/// Minimum image coverage fraction to trigger Scanned vote.
|
||||
pub const IMAGE_COVERAGE_THRESHOLD: f32 = 0.85;
|
||||
/// Strength for Scanned vote when image coverage exceeds threshold.
|
||||
pub const IMAGE_COVERAGE_STRENGTH: f32 = 0.85;
|
||||
|
||||
// Evaluator 4: char_validity_rate (low)
|
||||
/// Maximum character validity rate to trigger BrokenVector vote.
|
||||
pub const CHAR_VALIDITY_LOW_THRESHOLD: f32 = 0.4;
|
||||
/// Strength for BrokenVector vote when character validity is below threshold.
|
||||
pub const CHAR_VALIDITY_LOW_STRENGTH: f32 = 0.80;
|
||||
|
||||
// Evaluator 5: char_validity_rate (high)
|
||||
/// Minimum character validity rate to trigger Vector vote.
|
||||
pub const CHAR_VALIDITY_HIGH_THRESHOLD: f32 = 0.85;
|
||||
/// Strength for Vector vote when character validity exceeds threshold.
|
||||
pub const CHAR_VALIDITY_HIGH_STRENGTH: f32 = 0.90;
|
||||
|
||||
// Evaluator 6: char_density_ratio
|
||||
/// Maximum character density (chars per pt²) to trigger Scanned vote.
|
||||
pub const CHAR_DENSITY_RATIO_THRESHOLD: f32 = 0.03;
|
||||
/// Strength for Scanned vote when character density is below threshold.
|
||||
pub const CHAR_DENSITY_RATIO_STRENGTH: f32 = 0.65;
|
||||
|
||||
// Short-circuit threshold
|
||||
/// Minimum signal strength to trigger immediate short-circuit classification.
|
||||
pub const SHORT_CIRCUIT_STRENGTH: f32 = 0.95;
|
||||
|
||||
// Hybrid detection thresholds
|
||||
/// Minimum number of vector cells required for Hybrid classification.
|
||||
pub const HYBRID_VECTOR_CELL_MIN: u32 = 10;
|
||||
/// Minimum number of scanned cells required for Hybrid classification.
|
||||
pub const HYBRID_SCANNED_CELL_MIN: u32 = 10;
|
||||
/// Character validity threshold for vector cell classification.
|
||||
pub const VECTOR_CELL_VALIDITY_THRESHOLD: f32 = 0.6;
|
||||
/// Image coverage threshold for scanned cell classification.
|
||||
pub const SCANNED_CELL_IMAGE_THRESHOLD: f32 = 0.80;
|
||||
}
|
||||
|
||||
/// Page context containing all metrics needed for classification.
|
||||
///
|
||||
/// This struct is populated by content stream analysis and contains
|
||||
|
|
@ -181,7 +240,7 @@ impl SignalEvaluator for NoTextOperatorsSignal {
|
|||
// Strong signal for Scanned if images present
|
||||
// If no images either, this is a blank page (handled elsewhere)
|
||||
if ctx.has_images() {
|
||||
return Some(Vote::scanned(0.95));
|
||||
return Some(Vote::scanned(SignalsConfig::NO_TEXT_OPS_STRENGTH));
|
||||
}
|
||||
}
|
||||
None
|
||||
|
|
@ -211,9 +270,9 @@ struct HighImageCoverageSignal;
|
|||
|
||||
impl SignalEvaluator for HighImageCoverageSignal {
|
||||
fn evaluate(&self, ctx: &PageContext) -> Option<Vote> {
|
||||
if ctx.image_coverage > 0.85 {
|
||||
if ctx.image_coverage > SignalsConfig::IMAGE_COVERAGE_THRESHOLD {
|
||||
// Strong signal for Scanned
|
||||
return Some(Vote::scanned(0.90));
|
||||
return Some(Vote::scanned(SignalsConfig::IMAGE_COVERAGE_STRENGTH));
|
||||
}
|
||||
None
|
||||
}
|
||||
|
|
@ -230,9 +289,9 @@ impl SignalEvaluator for LowCharValiditySignal {
|
|||
fn evaluate(&self, ctx: &PageContext) -> Option<Vote> {
|
||||
if ctx.has_text() {
|
||||
let validity = ctx.char_validity_rate();
|
||||
if validity < 0.4 {
|
||||
if validity < SignalsConfig::CHAR_VALIDITY_LOW_THRESHOLD {
|
||||
// Very low validity = broken encoding
|
||||
return Some(Vote::broken_vector(0.80));
|
||||
return Some(Vote::broken_vector(SignalsConfig::CHAR_VALIDITY_LOW_STRENGTH));
|
||||
}
|
||||
}
|
||||
None
|
||||
|
|
@ -250,9 +309,9 @@ impl SignalEvaluator for HighCharValiditySignal {
|
|||
fn evaluate(&self, ctx: &PageContext) -> Option<Vote> {
|
||||
if ctx.has_text() {
|
||||
let validity = ctx.char_validity_rate();
|
||||
if validity > 0.85 {
|
||||
if validity > SignalsConfig::CHAR_VALIDITY_HIGH_THRESHOLD {
|
||||
// High validity = good vector text
|
||||
return Some(Vote::vector(0.90));
|
||||
return Some(Vote::vector(SignalsConfig::CHAR_VALIDITY_HIGH_STRENGTH));
|
||||
}
|
||||
}
|
||||
None
|
||||
|
|
|
|||
84
notes/pdftract-22p.md
Normal file
84
notes/pdftract-22p.md
Normal file
|
|
@ -0,0 +1,84 @@
|
|||
# Bead pdftract-22p: Signal Evaluators Implementation
|
||||
|
||||
## Summary
|
||||
|
||||
This bead implements the five signal evaluators that feed PageClassifier::classify. Each evaluator is a pure function over PageContext returning a Signal with name, strength, and vote (PageClass).
|
||||
|
||||
## Implementation Status: COMPLETE
|
||||
|
||||
All signal evaluators are already implemented in `crates/pdftract-core/src/classify.rs`:
|
||||
|
||||
### 1. SignalsConfig (lines 31-88)
|
||||
Centralized threshold constants for all signal evaluators:
|
||||
- `NO_TEXT_OPS_STRENGTH`: 0.95
|
||||
- `FULL_PAGE_IMAGE_THRESHOLD`: 0.95
|
||||
- `ALL_TR3_WITH_IMAGE_STRENGTH`: 0.99
|
||||
- `IMAGE_COVERAGE_THRESHOLD`: 0.85
|
||||
- `IMAGE_COVERAGE_STRENGTH`: 0.85
|
||||
- `CHAR_VALIDITY_LOW_THRESHOLD`: 0.4
|
||||
- `CHAR_VALIDITY_LOW_STRENGTH`: 0.80
|
||||
- `CHAR_VALIDITY_HIGH_THRESHOLD`: 0.85
|
||||
- `CHAR_VALIDITY_HIGH_STRENGTH`: 0.90
|
||||
- `CHAR_DENSITY_RATIO_THRESHOLD`: 0.03
|
||||
- `CHAR_DENSITY_RATIO_STRENGTH`: 0.65
|
||||
- `SHORT_CIRCUIT_STRENGTH`: 0.95
|
||||
|
||||
### 2. PageContext (lines 90-186)
|
||||
Contains all required fields:
|
||||
- `text_op_count`: Number of text operators
|
||||
- `tr3_op_count`: Number of Tr=3 (invisible) text operators
|
||||
- `image_xobject_areas`: Vec<f64> of individual image areas
|
||||
- `raw_char_count`, `valid_char_count`: For char_validity_rate
|
||||
- `width`, `height`: For page_area_pt2 calculation
|
||||
- `density_ratio`: For char density checks
|
||||
- `char_validity_rate()`: Method to compute validity rate
|
||||
|
||||
### 3. Signal Evaluators (lines 235-373)
|
||||
All six evaluators implemented (two for char_validity as specified):
|
||||
|
||||
| Evaluator | Class | Strength | Trigger |
|
||||
|-----------|-------|----------|---------|
|
||||
| NoTextOperatorsSignal | Scanned | 0.95 | text_op_count == 0 && has_images |
|
||||
| InvisibleTextWithImageSignal | BrokenVector | 0.99 | all_tr3 && full_page_image >= 95% |
|
||||
| HighImageCoverageSignal | Scanned | 0.85 | image_coverage > 0.85 |
|
||||
| LowCharValiditySignal | BrokenVector | 0.80 | char_validity < 0.4 |
|
||||
| HighCharValiditySignal | Vector | 0.90 | char_validity > 0.85 |
|
||||
| CharDensityRatioSignal | Scanned | 0.65 | density < 0.03 chars/pt² |
|
||||
|
||||
### 4. PageClassifier (lines 474-628)
|
||||
Wires all evaluators together with:
|
||||
- Declared order evaluation
|
||||
- Short-circuit at strength >= 0.95
|
||||
- Vote tallying with weighted strength
|
||||
- Default to Vector with 0.5 confidence if no votes
|
||||
|
||||
### 5. Pure Functions (lines 375-472)
|
||||
Helper functions for evaluators:
|
||||
- `all_tr3_with_full_page_image()`: EC-12 definitive signal
|
||||
- `image_coverage_fraction()`: Coverage with clamping to [0,1]
|
||||
|
||||
## Test Coverage
|
||||
|
||||
All evaluators have comprehensive unit tests:
|
||||
- `test_char_density_ratio_signal_*`: 12 tests
|
||||
- `test_all_tr3_with_full_page_image_*`: 14 tests
|
||||
- `test_image_coverage_fraction_*`: 11 tests
|
||||
- `test_page_classifier_short_circuit_*`: 2 tests
|
||||
- Plus integration tests with PageClassifier
|
||||
|
||||
## AC Verification
|
||||
|
||||
- ✅ Unit test each evaluator individually with synthetic PageContext values straddling thresholds
|
||||
- ✅ Integration test: PageClassifier wired with all evaluators classifies four fixture PDFs correctly
|
||||
- ✅ Determinism: rerun classifier on same PageContext -> identical Signal vector
|
||||
- ✅ Short-circuit at strength > 0.95
|
||||
- ✅ SignalsConfig centralized constants
|
||||
- ✅ PageContext has all required fields
|
||||
- ✅ EC-12 cited in doc comments
|
||||
|
||||
## Notes
|
||||
|
||||
- The implementation uses a trait-based `SignalEvaluator` for extensibility
|
||||
- LowDensitySignal is an additional signal not in the original 5 (uses density_ratio field)
|
||||
- image_coverage_fraction uses sum (not union) for simplicity - may need Klee's algorithm for accuracy
|
||||
- CharDensityRatioSignal computes chars/pt² directly rather than using precomputed field
|
||||
Loading…
Add table
Reference in a new issue