square-up-cli-tool 1.0.0__tar.gz

square_up_cli_tool-1.0.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: square-up-cli-tool
+Version: 1.0.0
+Summary: Image Rotator & Cropper Tool
+Requires-Dist: Pillow
+Requires-Dist: pillow-heif
+Requires-Dist: opencv-python
+Requires-Dist: numpy
+Requires-Dist: streamlit

square_up_cli_tool-1.0.0/README.md

@@ -0,0 +1,65 @@
+# Square Up (Image Rotator & Cropper)
+
+A production-ready CLI and Web UI tool for automatically or manually deskewing scanned pages, photographs, postcards, and books. Leverages advanced OpenCV contour detection to dynamically isolate objects from flatbed scanner backgrounds, dropping messy edges gracefully. Natively supports formats including JPG, PNG, TIFF, TIF, HEIC, and WEBP.
+
+## Features
+- **Auto-Deskew**: Automatically detects the physical edges of items against a scanner bed to perfectly upright tilted scans using trigonometric geometry. 
+- **Manual Rotation**: Manually set precision rotation angles.
+- **Smart Cropping**: Professional modes for `close` (leaves a tiny sliver of scanner bed) and `flush` (cuts exactly inside the physical boundary to bleed out all background).
+- **Web UI**: Interactive Streamlit app for simple drag-and-drop viewing and processing.
+- **Raw Processing**: Processes and outputs `.tif` and `.tiff` formats completely uncompressed.
+
+## Installation (macOS / Linux / Windows)
+
+To install this tool safely on your system without conflicting with global packages, we strongly recommend using a Python Virtual Environment.
+
+**1. Clone or Download the Repository**
+Navigate to the directory where you downloaded these files in your terminal:
+```bash
+cd /path/to/where/you/saved/this
+```
+
+**2. Create and Activate a Virtual Environment**
+Creating an isolated environment ensures `pip` behaves nicely with your system (especially on newer versions of macOS).
+```bash
+python3 -m venv venv
+source venv/bin/activate
+```
+*(On Windows, activate using: `venv\Scripts\activate`)*
+
+**3. Install the Tool**
+This project uses a standard `pyproject.toml` file. You can install the tool directly into your environment like this:
+```bash
+pip install -e .
+```
+This automatically installs all requirements (OpenCV, Streamlit, Pillow, etc.) and registers the custom command `sup` to your terminal.
+
+---
+
+## Usage
+
+### 1. Command Line Interface (`sup` command)
+Because you installed the tool via `pip`, you don't need to run messy python scripts. You can just use the short command `sup`!
+
+```bash
+# Auto-Deskew and flush cut a vintage postcard to remove the scanner bed completely
+sup -i your_postcard.tif --auto-deskew --mode flush
+
+# Auto-Deskew and leave a tiny 1-2% physical border around the object
+sup -i scan.jpg --auto-deskew --mode close
+
+# Manual rotation by -10.5 degrees and exact flush crop
+sup -i image.heic -r -10.5 --mode flush
+
+# Specify a custom output path
+sup -i input.png -o output_dir/fixed.jpg --auto-deskew
+```
+
+### 2. Interactive Web UI
+If you prefer a visual approach where you can drag and drop your images and use sliders to fix your scans dynamically, start the interactive web app:
+
+```bash
+streamlit run app.py
+```
+
+This will automatically launch the tool in your web browser!

square_up_cli_tool-1.0.0/app.py

@@ -0,0 +1,89 @@
+import streamlit as st
+import os
+import tempfile
+from PIL import Image
+from image_processor import process_image
+
+st.set_page_config(page_title="Image Rotator & Cropper", layout="wide", page_icon="📸")
+
+st.title("📸 Image Rotator & Cropper")
+st.markdown("Easily process scanned documents or photographs. Upload an image, choose a cropping mode, and either let Auto-Deskew fix the alignment or adjust it manually!")
+
+# Sidebar styling
+st.sidebar.title("Configuration")
+st.sidebar.markdown("Use these options to configure exactly how your image is processed.")
+
+rotation_type = st.sidebar.radio(
+    "Rotation Mode", 
+    ["Auto-Deskew", "Manual Rotation"],
+    help="Auto-Deskew detects text layout angle. Manual lets you slide to your perfect angle."
+)
+
+rotation_angle = 0.0
+if rotation_type == "Manual Rotation":
+    rotation_angle = st.sidebar.slider("Rotation Angle (Degrees)", -180.0, 180.0, 0.0, step=0.5)
+    
+crop_mode = st.sidebar.selectbox(
+    "Cropping Mode", 
+    ["close", "flush"], 
+    format_func=lambda x: "Close (leaves a tiny sliver of scanner bed)" if x == "close" else "Flush (crops INSIDE the shape to remove all background)",
+    help="How closely should we crop to the detected content block?"
+)
+
+uploaded_file = st.file_uploader("Drag and drop your image (JPG, PNG, TIFF, WEBP, HEIC)", type=['jpg', 'jpeg', 'png', 'tiff', 'webp', 'heic'])
+
+if uploaded_file is not None:
+    # Build columns for preview
+    col_input, col_output = st.columns(2)
+    
+    with col_input:
+        st.subheader("Original Preview")
+        st.image(uploaded_file, use_container_width=True)
+        
+    process_btn = st.sidebar.button("Process Image", type="primary", use_container_width=True)
+    
+    if process_btn:
+        with st.spinner("Processing..."):
+            # Write uploaded buffer to a named temp file
+            ext = uploaded_file.name.split('.')[-1]
+            with tempfile.NamedTemporaryFile(delete=False, suffix=f".{ext}") as tmp_in:
+                tmp_in.write(uploaded_file.getbuffer())
+                input_path = tmp_in.name
+                
+            output_path = input_path + "_processed.jpg"
+            auto_deskew = (rotation_type == "Auto-Deskew")
+            
+            # Process using our core logic
+            res_path = process_image(
+                input_path=input_path,
+                output_path=output_path,
+                rotation_angle=rotation_angle,
+                auto_deskew=auto_deskew,
+                crop_mode=crop_mode
+            )
+            
+            if res_path and os.path.exists(res_path):
+                with col_output:
+                    st.subheader("Processed Result")
+                    result_img = Image.open(res_path)
+                    st.image(result_img, use_container_width=True)
+                    
+                    with open(res_path, "rb") as file:
+                        st.download_button(
+                            label="⬇️ Download Processed Image",
+                            data=file,
+                            file_name=f"processed_{uploaded_file.name}.jpg",
+                            mime="image/jpeg",
+                            use_container_width=True,
+                            type="primary"
+                        )
+            else:
+                st.error("Failed to process image. Make sure the content has distinct elements that can be thresholded or provide a different cropping mode.")
+                
+            # Clean up temp files
+            try:
+                os.remove(input_path)
+                if os.path.exists(output_path):
+                    os.remove(output_path)
+            except:
+                pass

square_up_cli_tool-1.0.0/image_processor.py

@@ -0,0 +1,225 @@
+import argparse
+import os
+import cv2
+import numpy as np
+from PIL import Image
+from pillow_heif import register_heif_opener
+
+# Register HEIF opener for Pillow to handle HEIC files automatically
+register_heif_opener()
+
+def get_object_mask(image_cv):
+    """
+    Finds the largest distinct object against a flatbed background using dynamic Canny edge detection.
+    """
+    gray = cv2.cvtColor(image_cv, cv2.COLOR_BGR2GRAY)
+    blurred = cv2.GaussianBlur(gray, (7, 7), 0)
+    
+    # Use Otsu's thresholding to dynamically find optimal Canny thresholds
+    val, _ = cv2.threshold(blurred, 0, 255, cv2.THRESH_BINARY | cv2.THRESH_OTSU)
+    lower = int(max(0, 0.5 * val))
+    upper = int(min(255, 1.5 * val))
+    edges = cv2.Canny(blurred, lower, upper)
+    
+    # Thicken edges and close shapes to form a solid blob
+    kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (15, 15))
+    dilated = cv2.dilate(edges, kernel, iterations=3)
+    closed = cv2.morphologyEx(dilated, cv2.MORPH_CLOSE, kernel, iterations=2)
+    
+    contours, _ = cv2.findContours(closed, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+    if not contours:
+        return None
+        
+    # Sort contours by area descending to find the largest object
+    contours = sorted(contours, key=cv2.contourArea, reverse=True)
+    return contours[0]
+
+def get_deskew_angle(image_cv):
+    """
+    Computes pure geometric angle to orthogonally align the detected bounding box.
+    """
+    contour = get_object_mask(image_cv)
+    if contour is None or cv2.contourArea(contour) < 500:
+        return 0.0
+        
+    rect = cv2.minAreaRect(contour)
+    box = cv2.boxPoints(rect)
+    
+    # Calculate angles for all 4 edges
+    edges_angles = []
+    for i in range(4):
+        p1 = box[i]
+        p2 = box[(i+1)%4]
+        dx = p2[0] - p1[0]
+        dy = p2[1] - p1[1]
+        
+        # Skip zero length edges just in case
+        if dx == 0 and dy == 0:
+            continue
+            
+        angle_deg = np.degrees(np.arctan2(dy, dx))
+        
+        # Normalize angle to [-45, 45) range (difference from horizontal/vertical)
+        norm_angle = angle_deg % 90
+        if norm_angle > 45:
+            norm_angle -= 90
+            
+        edges_angles.append(norm_angle)
+        
+    # Python median effectively averages the remaining sides, ignoring noise on 1 weird edge
+    skew_angle = np.median(edges_angles) if edges_angles else 0.0
+    return skew_angle
+
+def rotate_image(image, angle):
+    """Rotate PIL image by given angle, seamlessly blending with scanner background."""
+    bg = image.getpixel((5, 5))
+    if isinstance(bg, int):
+        bg = (bg, bg, bg)
+    elif len(bg) > 3:
+        bg = bg[:3]
+        
+    return image.rotate(angle, expand=True, resample=Image.Resampling.BICUBIC, fillcolor=bg)
+
+def crop_image(image_cv, crop_mode):
+    """
+    Finds the deskewed object's boundary and applies exact relative percentage padding.
+    """
+    contour = get_object_mask(image_cv)
+    if contour is None:
+        print("[WARNING] No object found to crop. Returning original.")
+        return image_cv
+        
+    x, y, w, h = cv2.boundingRect(contour)
+    img_h, img_w = image_cv.shape[:2]
+    
+    # Safety feature for extremely huge padding
+    if w > img_w * 0.98 and h > img_h * 0.98:
+         print("[WARNING] Object boundary merges with image boundaries (or is identically sized). Proceeding as-is.")
+         return image_cv
+    
+    if crop_mode == "flush":
+        pad_pct = -0.015  # -1.5% (Cuts cleanly into the physical postcard)
+    else:
+        pad_pct = 0.015  # 1.5% (Leaves a tiny border)
+        
+    pad_y = int(h * pad_pct)
+    pad_x = int(w * pad_pct)
+    
+    new_x = max(0, x - pad_x)
+    new_y = max(0, y - pad_y)
+    new_w = min(img_w - new_x, w + 2 * pad_x)
+    new_h = min(img_h - new_y, h + 2 * pad_y)
+    
+    # Final Crop
+    return image_cv[new_y:new_y+new_h, new_x:new_x+new_w]
+
+def process_image(input_path, output_path=None, rotation_angle=None, auto_deskew=False, crop_mode='close'):
+    """
+    Main pipeline to run rotation, then cropping.
+    """
+    try:
+        if not os.path.exists(input_path):
+            raise FileNotFoundError(f"File {input_path} not found.")
+            
+        pil_img = Image.open(input_path)
+        
+        # Ensure we have RGB
+        if pil_img.mode != "RGB":
+            pil_img = pil_img.convert("RGB")
+            
+        final_angle = 0.0
+        
+        # Determine rotation
+        if auto_deskew:
+            cv_img_for_deskew = cv2.cvtColor(np.array(pil_img), cv2.COLOR_RGB2BGR)
+            final_angle = get_deskew_angle(cv_img_for_deskew)
+            print(f"[INFO] Auto-deskew detected skew. Correcting by {final_angle:.2f} degrees")
+        elif rotation_angle is not None and rotation_angle != 0.0:
+            final_angle = rotation_angle
+            print(f"[INFO] Applying manual rotation: {final_angle} degrees")
+            
+        # Rotate
+        if final_angle != 0.0:
+            pil_img = rotate_image(pil_img, final_angle)
+            
+        # Convert to CV2 format for cropping
+        cv_img_to_crop = cv2.cvtColor(np.array(pil_img), cv2.COLOR_RGB2BGR)
+        print(f"[INFO] Cropping image using '{crop_mode}' mode.")
+        cropped_cv_img = crop_image(cv_img_to_crop, crop_mode=crop_mode)
+        
+        # Convert back to PIL for output serialization
+        final_pil_img = Image.fromarray(cv2.cvtColor(cropped_cv_img, cv2.COLOR_BGR2RGB))
+        
+        # Generate target path
+        if output_path is None:
+            base, ext = os.path.splitext(input_path)
+            # Standardize exotic types to JPG by default (keeping TIFF uncompressed)
+            if ext.lower() in ['.heic', '.webp']:
+                ext = '.jpg'
+            output_path = f"{base}_rotated_cropped{ext}"
+            
+        # Ensure directory exists
+        out_dir = os.path.dirname(os.path.abspath(output_path))
+        if out_dir:
+            os.makedirs(out_dir, exist_ok=True)
+            
+        save_kwargs = {}
+        if output_path.lower().endswith(('.jpg', '.jpeg')):
+            save_kwargs['quality'] = 95
+            
+        final_pil_img.save(output_path, **save_kwargs)
+        print(f"[SUCCESS] Saved processed image to: {output_path}")
+        return output_path
+        
+    except Exception as e:
+        print(f"[ERROR] Process failed for {input_path}: {e}")
+        return None
+
+def main():
+    parser = argparse.ArgumentParser(description="Image Rotator & Cropper")
+    parser.add_argument("--input", "-i", type=str, required=True, help="Path to input image file OR a directory of images.")
+    parser.add_argument("--output", "-o", type=str, default=None, help="Path to output file or directory. Appends _rotated_cropped if omitted.")
+    parser.add_argument("--rotate", "-r", type=float, default=0.0, help="Manual rotation angle in degrees (positive or negative)")
+    parser.add_argument("--auto-deskew", "-a", action="store_true", help="Automatically detect and correct layout skew")
+    parser.add_argument("--mode", "-m", choices=["close", "flush"], default="close", help="Crop mode: 'close' (leaves tiny outer border) or 'flush' (cuts slightly inward to eliminate scanner bed completely)")
+    
+    args = parser.parse_args()
+    
+    if os.path.isdir(args.input):
+        valid_exts = {'.jpg', '.jpeg', '.png', '.tiff', '.tif', '.webp', '.heic'}
+        if args.output and not os.path.isdir(args.output):
+            os.makedirs(args.output, exist_ok=True)
+            
+        count = 0
+        for f in os.listdir(args.input):
+            ext = os.path.splitext(f)[1].lower()
+            if ext in valid_exts:
+                in_path = os.path.join(args.input, f)
+                out_path = None
+                
+                if args.output:
+                    base = os.path.splitext(f)[0]
+                    out_ext = ext if ext in ['.tif', '.tiff'] else '.jpg'
+                    out_path = os.path.join(args.output, f"{base}_rotated_cropped{out_ext}")
+                    
+                print(f"\n--- Processing {f} ---")
+                process_image(
+                    input_path=in_path,
+                    output_path=out_path,
+                    rotation_angle=args.rotate,
+                    auto_deskew=args.auto_deskew,
+                    crop_mode=args.mode
+                )
+                count += 1
+        print(f"\n[DONE] Successfully batch-processed {count} images from '{args.input}'!")
+    else:
+        process_image(
+            input_path=args.input,
+            output_path=args.output,
+            rotation_angle=args.rotate,
+            auto_deskew=args.auto_deskew,
+            crop_mode=args.mode
+        )
+
+if __name__ == "__main__":
+    main()

square_up_cli_tool-1.0.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "square-up-cli-tool"
+version = "1.0.0"
+description = "Image Rotator & Cropper Tool"
+dependencies = [
+    "Pillow",
+    "pillow-heif",
+    "opencv-python",
+    "numpy",
+    "streamlit"
+]
+
+[project.scripts]
+sup = "image_processor:main"
+
+[tool.setuptools]
+py-modules = ["image_processor", "app"]

square_up_cli_tool-1.0.0/setup.cfg

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

square_up_cli_tool-1.0.0/square_up_cli_tool.egg-info/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: square-up-cli-tool
+Version: 1.0.0
+Summary: Image Rotator & Cropper Tool
+Requires-Dist: Pillow
+Requires-Dist: pillow-heif
+Requires-Dist: opencv-python
+Requires-Dist: numpy
+Requires-Dist: streamlit

square_up_cli_tool-1.0.0/square_up_cli_tool.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+app.py
+image_processor.py
+pyproject.toml
+square_up_cli_tool.egg-info/PKG-INFO
+square_up_cli_tool.egg-info/SOURCES.txt
+square_up_cli_tool.egg-info/dependency_links.txt
+square_up_cli_tool.egg-info/entry_points.txt
+square_up_cli_tool.egg-info/requires.txt
+square_up_cli_tool.egg-info/top_level.txt

square_up_cli_tool-1.0.0/square_up_cli_tool.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

square_up_cli_tool-1.0.0/square_up_cli_tool.egg-info/entry_points.txt

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

square_up_cli_tool-1.0.0/square_up_cli_tool.egg-info/requires.txt

@@ -0,0 +1,5 @@
+Pillow
+pillow-heif
+opencv-python
+numpy
+streamlit

square_up_cli_tool-1.0.0/square_up_cli_tool.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+app
+image_processor