Package: augraphy
Augraphy is a Python library that creates multiple copies of original documents though an augmentation pipeline that randomly distorts each copy -- degrading the clean version into dirty and realistic copies rendered through synthetic paper printing, faxing, scanning and copy machine processes.Highly-configurable pipelines apply adjustments to the originals to create realistic old or noisy documents by acting as a factory, producing almost an infinite number of variations from their source.  This simulation of realistic paper-oriented process distortions can create large amounts of training data for AI/ML processes to learn how to remove those distortions.Treatments applied by Augraphy fabricate realistic documents that appear to have been printed on dirty laser or inkjet printers, scanned by dirty office scanners, faxed by low-resolution fax machines and otherwise mistreated by real-world paper handling office equipment.What makes Augraphy Magical?Virtually no readily available datasets exist with both acleanandnoisyversion of target documents.  Augraphy addresses that problem by manufacturing large volumes of high-quality noisy documents to train alongside their clean source originals.Training neural networks typically requires augmenting limited sources of data in a variety of ways so that networks can learn to generalize their solutions.  Networks designed to work with scanned document images must be trained with images that have the type of distortions and noise typical of real-world scanned office documents.However, if we only have real-world dirty documents, then we don’t have a good way to know for sure what the right answer is when training a neural network.  By going in the reverse direction, starting with the clean document we hope a trained network will produce, we can simulate training data with dirty documents for which we already have a perfect original.With flawless rendering of distorted "originals", we can train a model to undo all that distortion and restore the document to its original form.  It’s pretty much magic!How It WorksAugraphy's augmentation pipeline starts with an image of a clean document.  The pipeline begins by extracting the text and graphics from the source into an "ink" layer.  (Ink is synonymous with toner within Augraphy.)  The augmentation pipeline then distorts and degrades the ink layer.A paper factory provides either a white page or a randomly-selected paper texture base.  Like the ink layer, the paper can also be processed through a pipeline to further provide random realistic paper textures.After both the ink and paper phases are completed, processing continues by applying the ink, with its desired effects, to the paper.  This merged document image is then augmented further with distortions such as adding folds or other physical deformations or distortions that rely on simultaneous interactions of paper and ink layers.The end result is an image that mimics real documents.Example Before / After ImagesExample UsageTo use the default pipeline which contains all available augmentations and sensible defaults:fromaugraphyimport*pipeline=default_augraphy_pipeline()image=cv2.imread("image.png")augmented=pipeline(image)DocumentationFor full documentation, including installation and tutorials, check thedoc directory.List of AugmentationsPixel Level AugmentationsPixel level augmentations apply augmentation to the input image only, that including alpha layer of the image. Additional inputs such as mask, keypoints or bounding boxes will not be affected.AugmentationImageAlpha LayerBadPhotoCopy✓-BindingsAndFasteners✓-BleedThrough✓-Brightness✓-BrightnessTexturize✓-ColorPaper✓-ColorShift✓-DelaunayTessellation✓-DirtyDrum✓-DirtyRollers✓-Dithering✓-DotMatrix✓-Faxify✓-Gamma✓-Hollow✓-InkBleed✓-InkColorSwap✓-InkMottling✓-Jpeg✓-Letterpress✓-LightingGradient✓-LinesDegradation✓-LowInkPeriodicLines✓-LowInkRandomLines✓-LowLightNoise✓-Markup✓-NoiseTexturize✓-NoisyLines✓-PatternGenerator✓-ReflectedLight✓-Scribbles✓-ShadowCast✓-SubtleNoise✓-VoronoiTessellation✓-WaterMark✓-Spatial level AugmentationsSpatial level augmentations apply augmentation to all inputs such as image (including alpha layer), mask, keypoints and bounding boxes.AugmentationImageAlpha LayerMaskKeypointsBounding BoxesBookBinding✓✓✓✓✓*Folding✓✓✓✓✓*Geometric✓✓✓✓✓*GlitchEffect✓✓✓✓✓*InkShifter✓✓✓✕✕PageBorder✓✓✓✓✓*SectionShift✓✓✓✓✓*Squish✓✓✓✓✓*Remarks:[-] : augmentation doesn't affect this input.[✓] : augmentation is supported on this input.[✕] : augmentation is not supported on this input.[✓*] : augmentation is supported on this input under certain criteria.Benchmark ResultsThe benchmark results are computed with Augraphy 8.2 and Tobacco3482 dataset (resume subset with a total of 120 images). It is evaluated with a 2 cores machine - Intel(R) Xeon(R) Gold 6226R CPU @ 2.90GHz. The mask is using a binarized version of image. For keypoints, it is using 1000 random points in the image and for bounding boxes, 100 random bounding boxes with random size are used.AugmentationImg/secMemory(MB)Img/sec(mask)Memory(MB)(mask)Img/sec(keypoints)Memory(MB)(keypoints)Img/sec(bounding boxes)Memory(MB)(bounding boxes)BadPhotoCopy0.17202.810.12215.600.13204.550.12216.29BindingsAndFasteners28.2121.0829.7521.0236.3921.0229.0921.23BleedThrough0.39684.690.39684.690.39684.690.39684.69BookBinding0.09611.710.08616.870.09611.740.09611.67Brightness4.92147.994.90147.994.95147.995.07147.99BrightnessTexturize1.83181.741.83181.741.84181.741.86181.74ColorPaper4.83105.664.99105.664.96105.664.96105.66ColorShift0.79126.940.82126.940.77126.940.76126.94DelaunayTessellation0.1160.410.1260.290.1160.360.1060.37DepthSimulatedBlur0.0176.080.0176.080.0176.080.0176.08DirtyDrum0.83482.510.94481.560.90481.680.92481.52DirtyRollers1.47249.551.77249.431.80249.431.78249.43DirtyScreen0.78435.360.78435.360.77435.360.77435.36Dithering3.39126.823.66126.803.66126.813.79126.80DotMatrix0.5380.750.5780.520.5780.520.5780.52DoubleExposure1.6463.401.6763.401.6263.401.6563.40Faxify1.37138.341.43141.281.41136.951.27149.24Folding3.1857.501.2460.403.4457.603.5557.20Gamma29.2625.3626.9025.3628.2325.3632.0325.36Geometric135.7512.68137.6412.68145.8012.68127.1012.68GlitchEffect1.14132.351.10132.651.03134.141.05134.11Hollow0.17343.170.17343.170.17343.170.17343.17InkBleed3.23177.513.19177.513.17177.513.16177.51InkColorSwap3.4751.993.5851.993.5151.993.6151.99InkMottling5.4155.995.4755.995.4955.995.3955.99InkShifter0.17426.860.15426.430.17426.780.17426.58LCDScreenPattern2.14494.092.12493.622.14494.742.13496.46Jpeg5.5525.875.6025.865.5225.875.6625.87LensFlare0.02405.970.01405.820.01405.820.01405.82Letterpress0.35135.710.33140.720.34137.250.34136.31LightingGradient0.37638.310.38638.300.39638.300.40638.30LinesDegradation1.28174.761.27174.931.28174.921.31174.59LowInkPeriodicLines5.1712.755.2612.755.5612.755.1012.75LowInkRandomLines91.5212.7586.1212.7587.5812.7598.2812.75LowLightNoise0.27481.950.28481.950.27481.950.27481.95Markup2.33161.882.41158.132.58146.272.60147.53Moire0.97575.741.03575.571.05575.571.05575.57NoiseTexturize0.83249.360.85249.360.80249.360.82249.36NoisyLines0.89446.650.83448.430.86447.880.85448.52PageBorder0.49193.950.49188.460.48188.300.49192.04PatternGenerator0.7651.530.7651.500.7451.500.7451.50ReflectedLight0.06109.900.06109.820.06109.880.06110.02Scribbles1.1194.730.8696.900.8796.960.86100.55SectionShift117.1512.96101.7113.02107.8812.95115.2212.96ShadowCast0.7550.790.6850.800.6850.800.7450.80Squish0.72450.440.72450.790.73450.830.76451.00Stains1.11469.141.14469.141.16469.141.11469.14SubtleNoise1.44215.551.47215.551.47215.551.48215.55VoronoiTessellation0.0758.070.0757.740.0757.890.0758.13WaterMark2.09363.621.86404.621.78409.502.02380.21Alternative Augmentation LibrariesThere are plenty of choices when it comes toaugmentation libraries.  However, only Augraphy is designed to address everyday office automation needs associated with paper-oriented process distortions that come from printing, faxing, scanning and copy machines.  Most other libraries focus on video and images pertinent to camera-oriented data sources and problem domains.  Augraphy is focused on supporting problems related to automation of document images such as OCR, form recognition, form data extraction, document classification, barcode decoding, denoising, document restoration, identity document data extraction, document cropping, etc.  Eventually, Augraphy will be able to support photo OCR problems with augmentations designed to emulate camera phone distortions.ContributingPull requests areverywelcome.  Please open an issue to propose and discuss feature requests and major changes.CitationsIf you used Augraphy in your research, please cite the project.BibTeX:@inproceedings{augraphy_paper,
    author = {Groleau, Alexander and Chee, Kok Wei and Larson, Stefan and Maini, Samay and Boarman, Jonathan},
    title = {Augraphy: A Data Augmentation Library for Document Images},
    booktitle = {Proceedings of the 17th International Conference on Document Analysis and Recognition ({ICDAR})},
    year = {2023},
    url = {https://arxiv.org/pdf/2208.14558.pdf}
}

@software{augraphy_library,
    author = {The Augraphy Project},
    title = {Augraphy: an augmentation pipeline for rendering synthetic paper printing, faxing, scanning and copy machine processes},
    url = {https://github.com/sparkfish/augraphy},
    version = {8.2.6}
}Star HistoryPlease add a "star" to the repo.  It's exciting to us when we see your interest, which keep us motivated to continue investing in the project!LicenseCopyright 2023 Sparkfish LLCAugraphy is free and open-source software distributed under the terms of theMITlicense.