plumbking 0.1.0

Classical CV-based image leveling and thumbnail generator.

PlumbKing 👑 — Classical CV Image Leveling & Thumbnails

PlumbKing is a lightweight, classical-CV horizon leveling and thumbnail generator. It processes photo batches using a purely deterministic pipeline:

• Multi-scale K-Means segmentation
• Canny edge extraction
• Probabilistic Hough transform
• Weighted roll voting
• Optional RANSAC horizon correction

No ML models, no cloud calls — just fast, transparent image geometry.

---

✨ Features

• 📐 Automatic roll leveling (multi-scale classical CV)
• 🔍 Preview mode with confirmation before replacing originals
• 🧭 EXIF-aware rotation correction
• 🖼️ Structured thumbnail generation
• 🛠️ Debug output for each stage (--debug-dir)
• 🐧 Works on Linux, macOS, WSL

---

🚀 Installation

pip install plumbking

---

📦 Basic Usage

Level and thumbnail all images in a directory:

plumbking --directory /path/to/images

Dry-run (no writes):

plumbking --directory /path/to/images --dry-run

Enable full CV debug logging:

plumbking --directory /photos --debug-dir /tmp/pk-debug

This creates per-image folders containing:

• segmentation maps
• Canny edge maps
• Hough overlays
• RANSAC boundary maps
• intermediate resized crops

---

🔧 Workflow Summary

1. Scan the directory

2. Detect leveling candidates

3. Generate preview leveled images under _leveled_preview/

4. Prompt for approval

   • Yes → originals replaced by leveled versions
   • No → preview removed, originals kept

5. Generate missing thumbnails

---

⚙️ Environment Variables

Variable	Default	Meaning
THUMB_MAX_SIZE	720	Max width/height of thumbnails
LEVELED_PREVIEW_DIR	_leveled_preview	Directory used for preview leveling
LEVEL_ANALYSIS_SIZE	720	Downscale used during leveling analysis
LEVEL_DEBUG_DIR	(unset)	Optional global debug directory (overridden by --debug-dir)

---

📝 Notes

• Works best for horizon-bearing photos, architecture, landscapes
• Deterministic classical CV — great for reproducible pipelines
• Safe to rerun; naming conventions prevent double-processing
• Designed for large photo collections and batch workflows

---

One hand for the ship, one hand for the soul. Built aboard Moonshot.

• arpeggio.one
• art-c.club

     :=.:***.       .    .*   ==:            .*.                 ....          ...               
     .=.  :         =    .+   =-:            .*.                       ..        .               
     .=.   -        .=    :.  ==:....        .*.                                                 
     .+:   ..        *   .:.= -=:.           .*.                                                 
  .*+:+:    +     --:=+:=***-.:+-:           .*................     . ..  .   ...                
      ++=+:..+.==*+*+-#*++**=****.           .*.                                                 
-::..:-=++*********+*%%##%##:#**+             *:                                                 
::.......:.::.. .:-=+%@*. .+  =-:.           .*-                                       ..        
   -**=#*#*:::....   .  .  -.:+-+-:*****+*++=:=-                                                 
               . .===##-::.........      .    .+                       ......                    
         ..                   .:+-. =-:..... :+#+                                 ......:-=+****#
         ..                         ..   .  -:%:+..-+*****=*+##*=#%# ##%@@@@@@*@@@%%%#@@@@@@@%@@@
....:......       .             .   :.   . .. . .  .:  ###*#*+**+-#:  :-%%   ::.- .=*: .*#= ..:=*
++**+++++*+**##**##@%%%##*.   +%%%%%%%%%%%%%% :+#*=-+= =+-:++ :%*-=: - ==#.+:+=*#-=+:=**%@%@%#**%
==*+*##*+*+*+++++**#%%%#-+:   =##%%%%%%%@%%**:++-==:-...   ..... :+     -%##**:*#*#=:*#+++++++*%%
##+%%%@#@@*@@@@. @@%#+@=%*+@%-##%@%-=*@@#+*%--++*#       *##***=    +%* #%%%@%-@@%%+*+%+*+=+#+%@%
%%#@@%@%*@*@@@@+-%@%#*@%*  @%-%%#@%%:+@@%*#%#####       +*#####+     %* #%@@@#:@@@%##*#.:-:::..-%
#*+#@@@@:@-@@@@@ #@%#-@%+  @@+*- @@%+*@@%-#-                       - =-  *%%%#:%%+=***-*******##%
%+-@@%@@+@+%@%@@#+@.#+@@*  =@*#..@@+=*@%@##@%@%%%%%#%%%#*##*##**+*++ -  -+*#%#=%%--.+-*+++***++=+
.  +@@@@%@@#%%@@@=%..=@@+. .@++#=@@***@@@#*%%%%**#%%%%%###%#####+*+= .   **#**-*#.+==**********=*
.  .@@@@@@@@%%@@@+@-.+@@#*::@*##:+-%%%@@@+#%%##*%%%%%%*=#*+-:+#*=-.     -*#++*.####*-############
.   %@@@@@@@@%@@#-@*-%@@#+:.@+-+-=#***+.                                * ...... .=*=############
+:.-%@@@@+@#@*@@+:%*-%@@++.-@*-#-=@      =**+++++++++.   -.            =          .#*############
-...+@@@@+@##:@@#.#%-%*@=#: @+:-.     =*****+=--. -                   #=.........  =++***********
:.  :@@@@@@##-@@+:#%+#+@=%**@.                                       ==....        .-:::::::----=
*:  .@@@@@@@#+%@#:*%++%%+:+*         .=-++                          :*............ ..::..........
#=   @@@@@@@#+#@@%%#-:%%%= .      .                                .: ... ....      .:::::::::..:
@=   #%%@@@@@%%@@%*=+: -       **=.                        .      ::............    .-------:::::
%+=. *%%%%%%%%%%%%%@%##       .--.                     ..        +*-..................===----::--
%**: *%%%%%%%%#%%%%%=  #     :                    :-:         -==##...... ............=====------
%#+--+%%%%%%%%#%%%%@%% =. -:               .-==--:          -=+-:*................. ..:=====-----
@%=.-*%%%%%%%%%%%@@@@*  .        ..-=====---:.          .**+=-     ....................=----::::-
%%***#%%%%%%%%%@@@@# ::     **++==-=====-           +%##+.        -   ............... .--::-:::::
%%###*%%%%%%%@@@@@*      =*%%@@#+++=-.        .=#%%#-    :     =  .................... .    :.   
%%###*#%%%%%@@@@@@@##** .:@@%@@@@+.     .:.:*%%#.       .++=     ...................  ..    :... 
####**#%%%%%@@@@@@@@@%%@@@@@%@@@@@@-   -*#*-            -+-.     .................... ...   ..=. 
####**#%%@@@@@@@@@@@@%@@@@@##@@@@@%%#*-           -+=   : +. :   ....................:  -=- .:++ 
####*##%%%%@@@@@@@@@@@@@@%%%%%%%%+.            =****: . =-=  -:  .....................  ... .=++ 
##%##*##%%@@@@@@@%%%%%%%%%%%#:               =*#*#.     -+:  .= .*%##**:............ .  :...  ...