white-paper-scanner 1.0.0__tar.gz

white_paper_scanner-1.0.0/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: white-paper-scanner
+Version: 1.0.0
+Summary: A utility to automatically crop and flatten photos of documents into highly detailed scanned images.
+Author-email: Anouar Manaa <anouarmanaa19@gmail.com>
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: opencv-python-headless>=4.0
+Requires-Dist: numpy>=1.0
+
+# Paper Scanner
+
+A command-line utility to automatically transform tilted photographs of documents into perfectly flat, highly detailed scanned images.
+
+## Features
+- **Automatic Edge Detection**: Detects the four corners of a document.
+- **Perspective Flattening**: Warps a tilted photo into a perfect top-down view.
+- **Flat-Field Illumination Correction**: Removes harsh shadows and uneven lighting to generate a perfect white background while preserving the original ink colors and anti-aliasing of the text.
+- **Auto-Upscaling**: Mathematically doubles the megapixels and applies unsharp masking so your text stays razor-sharp even when zoomed all the way in.
+
+## Installation
+
+```bash
+pip install paper-scanner
+```
+
+## Usage
+
+```bash
+paper-scanner path/to/your/image.jpg
+```
+
+This will output a new file named `image_scanned.jpg` in the same directory.

white_paper_scanner-1.0.0/README.md

@@ -0,0 +1,23 @@
+# Paper Scanner
+
+A command-line utility to automatically transform tilted photographs of documents into perfectly flat, highly detailed scanned images.
+
+## Features
+- **Automatic Edge Detection**: Detects the four corners of a document.
+- **Perspective Flattening**: Warps a tilted photo into a perfect top-down view.
+- **Flat-Field Illumination Correction**: Removes harsh shadows and uneven lighting to generate a perfect white background while preserving the original ink colors and anti-aliasing of the text.
+- **Auto-Upscaling**: Mathematically doubles the megapixels and applies unsharp masking so your text stays razor-sharp even when zoomed all the way in.
+
+## Installation
+
+```bash
+pip install paper-scanner
+```
+
+## Usage
+
+```bash
+paper-scanner path/to/your/image.jpg
+```
+
+This will output a new file named `image_scanned.jpg` in the same directory.

white_paper_scanner-1.0.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "white-paper-scanner"
+version = "1.0.0"
+authors = [
+  { name="Anouar Manaa", email="anouarmanaa19@gmail.com" },
+]
+description = "A utility to automatically crop and flatten photos of documents into highly detailed scanned images."
+readme = "README.md"
+requires-python = ">=3.7"
+dependencies = [
+    "opencv-python-headless>=4.0",
+    "numpy>=1.0"
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.scripts]
+white-paper-scanner = "crop_paper.cli:main"

white_paper_scanner-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

white_paper_scanner-1.0.0/src/crop_paper/__init__.py

@@ -0,0 +1 @@
+from .cli import process_image, crop_paper

white_paper_scanner-1.0.0/src/crop_paper/cli.py

@@ -0,0 +1,145 @@
+import cv2
+import numpy as np
+import sys
+import os
+
+def order_points(pts):
+    # order points: top-left, top-right, bottom-right, bottom-left
+    rect = np.zeros((4, 2), dtype="float32")
+    
+    # top-left will have the smallest sum, bottom-right the largest sum
+    s = pts.sum(axis=1)
+    rect[0] = pts[np.argmin(s)]
+    rect[2] = pts[np.argmax(s)]
+
+    # top-right will have the smallest difference, bottom-left the largest difference
+    diff = np.diff(pts, axis=1)
+    rect[1] = pts[np.argmin(diff)]
+    rect[3] = pts[np.argmax(diff)]
+    
+    return rect
+
+def four_point_transform(image, pts):
+    rect = order_points(pts)
+    (tl, tr, br, bl) = rect
+
+    # compute width of new image
+    widthA = np.sqrt(((br[0] - bl[0]) ** 2) + ((br[1] - bl[1]) ** 2))
+    widthB = np.sqrt(((tr[0] - tl[0]) ** 2) + ((tr[1] - tl[1]) ** 2))
+    maxWidth = max(int(widthA), int(widthB))
+
+    # compute height of new image
+    heightA = np.sqrt(((tr[0] - br[0]) ** 2) + ((tr[1] - br[1]) ** 2))
+    heightB = np.sqrt(((tl[0] - bl[0]) ** 2) + ((tl[1] - bl[1]) ** 2))
+    maxHeight = max(int(heightA), int(heightB))
+
+    dst = np.array([
+        [0, 0],
+        [maxWidth - 1, 0],
+        [maxWidth - 1, maxHeight - 1],
+        [0, maxHeight - 1]], dtype="float32")
+
+    M = cv2.getPerspectiveTransform(rect, dst)
+    warped = cv2.warpPerspective(image, M, (maxWidth, maxHeight))
+    return warped
+
+def process_image(image):
+    """
+    Takes an OpenCV image array (numpy ndarray) and returns the cropped, flattened, and scanned version.
+    """
+    # Resize image to speed up processing and improve contour detection
+    ratio = image.shape[0] / 500.0
+    orig = image.copy()
+    resized_image = cv2.resize(image, (int(image.shape[1] / ratio), 500))
+
+    # Convert to grayscale, blur slightly to remove high frequency noise, and find edges
+    gray = cv2.cvtColor(resized_image, cv2.COLOR_BGR2GRAY)
+    gray = cv2.GaussianBlur(gray, (5, 5), 0)
+    edged = cv2.Canny(gray, 75, 200)
+
+    # Find contours
+    contours, _ = cv2.findContours(edged.copy(), cv2.RETR_LIST, cv2.CHAIN_APPROX_SIMPLE)
+    contours = sorted(contours, key=cv2.contourArea, reverse=True)[:5]
+
+    screenCnt = None
+    for c in contours:
+        peri = cv2.arcLength(c, True)
+        approx = cv2.approxPolyDP(c, 0.02 * peri, True)
+        # If our approximated contour has four points, we can assume that we have found our paper
+        if len(approx) == 4:
+            screenCnt = approx
+            break
+
+    if screenCnt is None:
+        print("Warning: Could not automatically detect the outline of the paper. Proceeding without crop.")
+        warped = orig
+    else:
+        # Apply the perspective transform to crop it out
+        warped = four_point_transform(orig, screenCnt.reshape(4, 2) * ratio)
+
+    # 1. Crop a small margin (2.5%) off the edges to firmly remove any background/table artifacts
+    margin_y = int(warped.shape[0] * 0.025)
+    margin_x = int(warped.shape[1] * 0.025)
+    if margin_y > 0 and margin_x > 0:
+        warped = warped[margin_y:-margin_y, margin_x:-margin_x]
+        
+    # 2. Convert to grayscale to estimate background illumination
+    gray = cv2.cvtColor(warped, cv2.COLOR_BGR2GRAY)
+    
+    # 3. Estimate background illumination to remove shadows
+    kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (25, 25))
+    bg = cv2.morphologyEx(gray, cv2.MORPH_DILATE, kernel)
+    bg = cv2.GaussianBlur(bg, (25, 25), 0)
+    
+    # 4. Divide EACH color channel by the background (Flat-field correction for color)
+    scanned = np.zeros_like(warped)
+    for i in range(3):
+        scanned[:, :, i] = cv2.divide(warped[:, :, i], bg, scale=255)
+    
+    # 5. Apply Gamma Correction to preserve and darken thin fonts!
+    gamma = 2.2
+    table = np.array([((i / 255.0) ** gamma) * 255 for i in np.arange(0, 256)]).astype("uint8")
+    scanned = cv2.LUT(scanned, table)
+    
+    # 6. Apply a gentle contrast stretch to deepen the blacks 
+    scanned = cv2.convertScaleAbs(scanned, alpha=1.2, beta=-10)
+    
+    # 7. Ensure the background is perfectly white without destroying colored elements
+    gray_scanned = cv2.cvtColor(scanned, cv2.COLOR_BGR2GRAY)
+    scanned[gray_scanned > 210] = [255, 255, 255]
+    
+    # 8. Multiply Megapixels! 
+    scanned = cv2.resize(scanned, None, fx=2.0, fy=2.0, interpolation=cv2.INTER_LANCZOS4)
+    
+    # 9. Apply a subtle Unsharp Mask to guarantee the text is razor-sharp when zooming in
+    gaussian = cv2.GaussianBlur(scanned, (0, 0), 2.0)
+    scanned = cv2.addWeighted(scanned, 1.5, gaussian, -0.5, 0)
+    
+    return scanned
+
+def crop_paper(image_path):
+    print(f"Processing '{image_path}'...")
+    image = cv2.imread(image_path)
+    if image is None:
+        print(f"Error loading {image_path}. Check if the file exists.")
+        return
+
+    scanned = process_image(image)
+
+    base_name = os.path.basename(image_path)
+    name, _ = os.path.splitext(base_name)
+    output_path = f"{name}_scanned.jpg"
+    
+    cv2.imwrite(output_path, scanned)
+    print(f"Successfully saved scanned image to '{output_path}'")
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: white-paper-scanner <path_to_image>")
+        sys.exit(1)
+        
+    target_image = sys.argv[1]
+    crop_paper(target_image)
+
+if __name__ == "__main__":
+    main()

white_paper_scanner-1.0.0/src/white_paper_scanner.egg-info/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: white-paper-scanner
+Version: 1.0.0
+Summary: A utility to automatically crop and flatten photos of documents into highly detailed scanned images.
+Author-email: Anouar Manaa <anouarmanaa19@gmail.com>
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: opencv-python-headless>=4.0
+Requires-Dist: numpy>=1.0
+
+# Paper Scanner
+
+A command-line utility to automatically transform tilted photographs of documents into perfectly flat, highly detailed scanned images.
+
+## Features
+- **Automatic Edge Detection**: Detects the four corners of a document.
+- **Perspective Flattening**: Warps a tilted photo into a perfect top-down view.
+- **Flat-Field Illumination Correction**: Removes harsh shadows and uneven lighting to generate a perfect white background while preserving the original ink colors and anti-aliasing of the text.
+- **Auto-Upscaling**: Mathematically doubles the megapixels and applies unsharp masking so your text stays razor-sharp even when zoomed all the way in.
+
+## Installation
+
+```bash
+pip install paper-scanner
+```
+
+## Usage
+
+```bash
+paper-scanner path/to/your/image.jpg
+```
+
+This will output a new file named `image_scanned.jpg` in the same directory.

white_paper_scanner-1.0.0/src/white_paper_scanner.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+src/crop_paper/__init__.py
+src/crop_paper/cli.py
+src/white_paper_scanner.egg-info/PKG-INFO
+src/white_paper_scanner.egg-info/SOURCES.txt
+src/white_paper_scanner.egg-info/dependency_links.txt
+src/white_paper_scanner.egg-info/entry_points.txt
+src/white_paper_scanner.egg-info/requires.txt
+src/white_paper_scanner.egg-info/top_level.txt

white_paper_scanner-1.0.0/src/white_paper_scanner.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

white_paper_scanner-1.0.0/src/white_paper_scanner.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+white-paper-scanner = crop_paper.cli:main

white_paper_scanner-1.0.0/src/white_paper_scanner.egg-info/requires.txt

@@ -0,0 +1,2 @@
+opencv-python-headless>=4.0
+numpy>=1.0

white_paper_scanner-1.0.0/src/white_paper_scanner.egg-info/top_level.txt

@@ -0,0 +1 @@
+crop_paper