is-page-empty 1.0.4__py3-none-any.whl

is_page_empty/__init__.py

@@ -0,0 +1,62 @@
+try:
+    import skimage
+    def load_image(fn):
+        return skimage.io.imread(fn)
+except ImportError:
+    try:
+        import imageio.v3 as iio
+        def load_image(fn):
+            return iio.imread(fn)
+    except ImportError:
+        import PIL, numpy
+        def load_image(fn):
+            im = PIL.Image.open(fn)
+            return numpy.array(im)
+    
+import sys
+
+CUTOFF = 0.02
+
+def score(im):
+    ratio_bright = (im > 127).mean()
+    return min(ratio_bright, 1-ratio_bright)
+
+
+def is_empty(im, cutoff=CUTOFF):
+    if isinstance(im, str):
+        im = load_image(im)
+        if len(im.shape) == 3:
+            im = im[..., 0] / 3 + im[..., 1] / 3 + im[..., 2] / 3
+
+    smaller_dim, larger_dim = sorted(im.shape)
+    max_stride = smaller_dim / 10
+
+    scores = [
+        score(im[
+            x:int(x+max_stride),
+            y:int(y+max_stride)
+        ])
+        for x in range(0, (im.shape[0] - int(max_stride) - 1), int(max_stride))
+        for y in range(0, (im.shape[1] - int(max_stride) - 1), int(max_stride))
+    ]
+
+    im_score = sum(sorted(scores)[-3:]) / 3
+    return im_score < cutoff, im_score
+
+
+def main():
+    import argparse
+    parser = argparse.ArgumentParser()
+    parser.add_argument('infile')
+    parser.add_argument('-c', dest='cutoff', type=float, default=CUTOFF)
+    parser.add_argument('-r', dest='retval', action='store_true')
+    parser.add_argument('-v', dest='verbose', action='store_true')
+    args = parser.parse_args()
+    empty, im_score = is_empty(args.infile, args.cutoff)
+    if args.verbose:
+        verdict = '' if empty else 'not '
+        print(f"File {args.infile} is {verdict}empty (score: {im_score})")
+    if args.retval:
+        status=(0 if empty else 1)
+        sys.exit(status)
+

is_page_empty-1.0.4.dist-info/METADATA

@@ -0,0 +1,45 @@
+Metadata-Version: 2.5
+Name: is-page-empty
+Version: 1.0.4
+Summary: A very simple script that tests whether an image is likely empty.
+Project-URL: Homepage, https://github.com/johannes-bauer/is_page_empty
+Author-email: Johannes Bauer <atomm-clap@interesting-problems.de>
+License: MIT
+License-File: LICENSE
+Keywords: argument-parser,cli,subcommands
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Provides-Extra: imageio
+Requires-Dist: imageio>=2.0.0; extra == 'imageio'
+Provides-Extra: pil
+Requires-Dist: numpy>=2.2; extra == 'pil'
+Requires-Dist: pillow>=12.0.0; extra == 'pil'
+Provides-Extra: skimage
+Requires-Dist: scikit-image>=0.20.0; extra == 'skimage'
+Description-Content-Type: text/markdown
+
+# is_page_empty
+
+A simple package/script that checks whether a given image file is empty.
+
+Install it with one of the optional dependencies `skimage`, `imageio`, or `pil` or provide that skimage, imageio, or pillow are installed.
+
+Then you can check whether an image file is empty using the commandline:
+
+```bash
+if is_page_empty some_image.png; then echo "Yes, it's empty"; else echo "No, it's not empty."; fi
+```
+
+Or you can use the package to check programmatically
+
+```python
+import is_page_empty
+if is_empty('path/to/image/file.png'):
+    print("That file is empty.")
+```
+
+The script simply cuts the page into small squares, counts the number of pixels below a certain threshold in each, and compares the sum of those numbers in the squares with the highest numbers to a cutoff threshold.
+
+This has been very robust, in my experience, for scanned text; in particular in double-sided prints, where some of the print on the other side may shine through, and in pages with punched holes, which are rendered black in the print.

is_page_empty-1.0.4.dist-info/RECORD

@@ -0,0 +1,6 @@
+is_page_empty/__init__.py,sha256=JbN4rTxBYuId_hY0EFbcJdEkIZcI39fgIKxKAUPLh84,1737
+is_page_empty-1.0.4.dist-info/METADATA,sha256=3aQTf7fxfP8B0qg5YZiu6XccoDc8x146VkQ_QSdALf8,1856
+is_page_empty-1.0.4.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+is_page_empty-1.0.4.dist-info/entry_points.txt,sha256=UF9TaZcI1JzdtdbziPLEmKtbclCivNHW9fIhHolywr8,53
+is_page_empty-1.0.4.dist-info/licenses/LICENSE,sha256=tdWMFnpC0OpoU7-yfwW0RcSvdMsIufbN9MzsDU2OK4Y,1071
+is_page_empty-1.0.4.dist-info/RECORD,,

is_page_empty-1.0.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

is_page_empty-1.0.4.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+is_page_empty = is_page_empty:main

is_page_empty-1.0.4.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 johannes-bauer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.