Skip to content

feat(degradations): model capture conditions, moving boxes with the pixels - #7

Merged
hBouanane merged 4 commits into
feat/document-enginefrom
feat/degradations
Aug 12, 2026
Merged

feat(degradations): model capture conditions, moving boxes with the pixels#7
hBouanane merged 4 commits into
feat/document-enginefrom
feat/degradations

Conversation

@hBouanane

Copy link
Copy Markdown
Collaborator

6 of 9 in the v1.0.0 series. Base: feat/document-engine.

The design point

A degradation takes the annotation as well as the image, and returns both.

A rotation that moves ink 8° but leaves the boxes where they were produces a dataset that looks fine and teaches a detector to be systematically wrong. That failure is invisible until training underperforms for no obvious reason.

What

  • base.pyDegradation protocol, DegradationPipeline with per-degradation probabilities and a record of exactly what fired, and map_page(), which rebuilds a whole annotation through an arbitrary point mapping.
  • geometric.pyRotation and PerspectiveWarp, each deriving an explicit forward homography and pushing every box, word and table cell through it. Rotated words gain polygons, since an axis-aligned box no longer describes them tightly.
  • photometric.py — sixteen degradations chosen for physical cause rather than visual effect: ink spread/erosion, bleed-through from the reverse of a thin sheet, downscaling (the failure mode that destroys Arabic diacritics and that blur does not reproduce), JPEG artefacts, shadow, vignette, glare, stains, folds.
  • presets.pyclean / scan / photo / fax / archive, ordered along the physical capture chain (optics → shading → sampling → compression), so a corpus is composed by capture condition rather than by an undifferentiated cloud of noise.

Verified

365 tests green (79 new). The central test measures the actual ink box in the degraded image and requires the annotation to track it at IoU > 0.8, rather than merely checking that something changed.

hBouanane and others added 4 commits August 12, 2026 22:20
…ixels

A degradation takes the annotation as well as the image and returns both.
This is the whole point: a rotation that moves ink but leaves boxes behind
produces a dataset that looks fine and teaches a detector to be
systematically wrong, and the failure is invisible until training
underperforms for no obvious reason.

- base.py: Degradation protocol, DegradationPipeline with per-degradation
  probabilities and a record of exactly what fired, and map_page(), which
  rebuilds an annotation through an arbitrary point mapping.
- geometric.py: Rotation and PerspectiveWarp, each deriving an explicit
  forward homography and mapping every box, word and table cell through it.
  Rotated words gain polygons, since an axis-aligned box no longer describes
  them tightly.
- photometric.py: sixteen degradations chosen for physical cause rather than
  visual effect - ink spread/erosion, bleed-through from the reverse of a
  thin sheet, downscaling (the failure mode that kills Arabic diacritics and
  that blur does not reproduce), JPEG artefacts, shadow, vignette, glare,
  stains and folds.
- presets.py: clean/scan/photo/fax/archive, ordered along the physical
  capture chain, so a corpus is composed by capture condition rather than by
  an undifferentiated cloud of noise.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@hBouanane
hBouanane merged commit 0ab12d8 into feat/document-engine Aug 12, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant