init commit.

# Kumiko Manga/Comics Panel Extractor (WebUI)

Upload your manga or comic book images. This tool will automatically analyze the panels on each page,
crop them into individual image files, and package them into a single ZIP file for you to download.

This application is licensed under the **GNU Affero General Public License v3.0**.
The core panel detection is powered by the **kumikolib** library, created by **njean42** ([Original Project](https://github.com/njean42/kumiko)).

.gitignore

@@ -0,0 +1,7 @@
+__pycache__
+*.pyc
+tests/*.html
+tests/results/*
+.vs/
+venv/
+tmp/

LICENSE

@@ -0,0 +1,18 @@
+
+
+    Kumiko, the Comics Cutter is a set of tool for generating information about
+    panels locations within a comic books pages, and more.
+    Copyright (C) 2018 njean42
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as
+    published by the Free Software Foundation, either version 3 of the
+    License, or (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.

README.md

@@ -1,13 +1,136 @@
 ---
 title: KumikoMangaPanelExtractor
-emoji: 😻
-colorFrom: gray
-colorTo: pink
+emoji: 🕮
+colorFrom: indigo
+colorTo: green
 sdk: gradio
 sdk_version: 5.35.0
 app_file: app.py
 pinned: false
-short_description: Kumiko Manga/Comics Pane lExtractor (WebUI)
+short_description: Kumiko Manga/Comics Panel Extractor (WebUI)
 ---
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+___
+
+
+# Kumiko Manga/Comics Panel Extractor (WebUI)  
+
+Upload your manga or comic book images. This tool will automatically analyze the panels on each page,
+crop them into individual image files, and package them into a single ZIP file for you to download.
+
+This application is licensed under the **GNU Affero General Public License v3.0**.  
+The core panel detection is powered by the **kumikolib** library, created by **njean42** ([Original Project](https://github.com/njean42/kumiko)).
+
+___
+
+
+# Introduction
+
+![Kumiko mascot by Cthulhulumaid](https://raw.githubusercontent.com/njean42/kumiko/refs/heads/master/artwork/kumiko-big.png "Kumiko mascot by Cthulhulumaid")
+
+> Kumiko mascot by [Hurluberlue](https://www.twitch.tv/hurluberlue "twitch link"), [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/ "Creative Commons License")
+
+*Kumiko, the Comics Cutter* is a set of tools to compute useful information about comic book pages, panels, and more.
+Its main strength is to find out the **locations of panels** within a comic's page (image file).
+*Kumiko* can also compile information about panels for all pages in a comic book, and present it as one piece of data (JSON-formatted object).
+
+*Kumiko* makes use of the great (freely licensed) [opencv](https://opencv.org/) library, which provides image processing algorithms of all sorts.
+Mainly, the contour detection algorithm is used to detect panels within an image.
+
+
+# Demo
+
+*TL;WR* Too Long; Won't Read the whole doc?
+
+A **live demo** is [available here](https://kumiko.njean.me/demo), where you can try *Kumiko* out and cut your own comic pages into panels.
+
+
+# Philosophy
+
+*Kumiko* aims at being a functional library to extract information from comic pages / books.
+The goal is to provide a set of tools that is usable beforehand, to extract all needed information.
+
+External programs can later use the generated information for different purposes: panel-by-panel viewing, actual splitting of an image down into panels, etc.
+
+
+## Panel-by-panel comic reading
+
+Being able to jump from one panel to the next was the original idea behind *Kumiko*.
+
+![xkcd #208](doc/img/xkcd.png "xkcd #208")
+
+> [xkcd](https://www.xkcd.com) by Randall Munroe, [#208](https://www.xkcd.com/208/), [CC BY-NC 2.5](https://creativecommons.org/licenses/by-nc/2.5/)
+
+Comic viewers usually imply a very common *page-by-page reading paradigm*.
+You read a page, possibly zooming on it to be able to read speech bubbles, then click, tap, press a key or swipe to the next page.
+
+With knowledge about panels locations, we can imagine a comic reader that also offers *panel-by-panel reading*.
+This is especially interesting for **small screens**, on which you probably can't read the texts if a whole page is displayed.
+
+Just run `kumiko -i /path/to/comicpage.jpg -b firefox` on your *comicpage.jpg* file, and read it panel-by-panel in your browser!
+
+
+# Requirements
+
+`apt-get install python3-opencv` will install the only necessary library needed: *opencv*.
+
+This should do the trick for Debian distros and derivatives (Ubuntu, Linux Mint...).
+If you successfully use *Kumiko* on any other platform, please let us know!
+
+
+# Usage & Testing
+
+See the [usage doc](doc/Usage.md) for details on how to use the *Kumiko* tools.
+
+Also check the [testing doc](doc/Testing.md) if you want to test modified versions of the code.
+
+
+# Numbering
+
+The numbering is left-to-right, or right-to-left if requested.
+
+Here is an example of how *Kumiko* is going to number panels by default (numbers and red lines not in the original picture).
+
+![Pepper&Carrot](doc/img/numbering.png "Pepper&Carrot")
+
+> [Pepper & Carott](https://www.peppercarrot.com/) by [David Revoy](https://www.davidrevoy.com), [episode 2](https://www.peppercarrot.com/en/article237/episode-2-rainbow-potions), [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)
+
+
+# Contributing
+
+Feature requests and PR are welcome!
+
+*Kumiko* python code if formatted with [yapf](https://github.com/google/yapf).
+Config file is committed [here](.style.yapf).
+
+To format all your code, simply run:
+```bash
+yapf3 --recursive --in-place .
+```
+
+
+# Short- and longer-term features (roadmap)
+
+## Kumiko library
+
+* detect panels on a growing range of comic page layouts
+	* detect non-framed panels (without clear boundaries/borders)
+	* separate intertwined panels
+
+* ~~be able to detect panel contours on pages with non-white, non-black background~~ done in v1.5
+
+## Back-office (validation / edition tool)
+
+Let's face it: we probably can't ensure that *Kumiko* can perfectly find out the panels in *any* image.
+There is a huge diversity of panel boundaries, layouts and whatnot.
+
+This is why there could be some kind of back-office / editing tool that lets a human editor:
+
+* validate pages
+* add, delete, move or resize incorrect panels
+* report bugs
+* ...
+
+Such a tool would edit the JSON file representing a comic book information, for later use by other programs relying on it.

app.py

@@ -0,0 +1,243 @@
+"""
+Kumiko Manga/Comics Panel Extractor (WebUI)
+Copyright (C) 2025 avan
+
+This program is a web interface for the Kumiko library.
+The core logic is based on Kumiko, the Comics Cutter.
+Copyright (C) 2018 njean42
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+"""
+
+import gradio as gr
+import os
+import tempfile
+import shutil
+import numpy as np
+import cv2 as cv
+
+# Import Kumiko's core library and its page module dependency
+import kumikolib
+import lib.page
+
+# ----------------------------------------------------------------------
+# Core functions to solve the non-English path issue
+# ----------------------------------------------------------------------
+
+def imread_unicode(filename, flags=cv.IMREAD_COLOR):
+    """
+    Replaces cv.imread to support non-ASCII paths.
+    """
+    try:
+        with open(filename, 'rb') as f:
+            n = np.frombuffer(f.read(), np.uint8)
+            img = cv.imdecode(n, flags)
+            return img
+    except Exception as e:
+        print(f"Error reading file {filename}: {e}")
+        return None
+
+def imwrite_unicode(filename, img):
+    """
+    Replaces cv.imwrite to support non-ASCII paths.
+    """
+    try:
+        ext = os.path.splitext(filename)[1]
+        if not ext:
+            ext = ".jpg" # Default to jpg if no extension
+        result, n = cv.imencode(ext, img)
+        if result:
+            with open(filename, 'wb') as f:
+                f.write(n)
+            return True
+        else:
+            return False
+    except Exception as e:
+        print(f"Error writing to file {filename}: {e}")
+        return False
+
+# ----------------------------------------------------------------------
+# Monkey Patching
+# This dynamically replaces the problematic functions in the original
+# libraries without modifying their source code files.
+# ----------------------------------------------------------------------
+
+# Replace the cv.imread used in page.py with our new version
+lib.page.cv.imread = imread_unicode
+
+# Replace the cv.imwrite used in kumikolib.py with our new version
+kumikolib.cv.imwrite = imwrite_unicode
+
+
+# ----------------------------------------------------------------------
+# Gradio Processing Function
+# ----------------------------------------------------------------------
+
+def process_manga_images(files, output_structure, use_rtl, progress=gr.Progress(track_tqdm=True)):
+    """
+    The main processing logic for the Gradio interface.
+    Receives uploaded files and settings, processes them, and returns a path to a ZIP file.
+    """
+    if not files:
+        raise gr.Error("Please upload at least one image file.")
+
+    # Create temporary directories for processing
+    # 1. To store the cropped panel images
+    # 2. To store the final ZIP archive
+    panel_output_dir = tempfile.mkdtemp(prefix="kumiko_panels_")
+    zip_output_dir = tempfile.mkdtemp(prefix="kumiko_zip_")
+    
+    try:
+        # The 'files' object from gr.Files is a list of temporary file objects
+        image_paths = [file.name for file in files]
+        
+        progress(0, desc="Initializing Kumiko...")
+        
+        # Initialize Kumiko with the rtl setting from the UI
+        k = kumikolib.Kumiko({
+            'debug': False,
+            'progress': False,  # We use Gradio's progress bar instead
+            'rtl': use_rtl, # Use the value from the checkbox
+            'panel_expansion': True,
+        })
+        
+        # 1. Analyze all images
+        total_files = len(image_paths)
+        for i, path in enumerate(image_paths):
+            progress((i + 1) / total_files, desc=f"Analyzing: {os.path.basename(path)}")
+            try:
+                k.parse_image(path)
+            except lib.page.NotAnImageException as e:
+                print(f"Warning: Skipping file {os.path.basename(path)} because it is not a valid image. Error: {e}")
+                continue
+
+        # 2. Save the panels based on the selected output structure
+        #    This section replaces the original `k.save_panels()` call.
+        progress(0.8, desc="Saving all panels...")
+        nb_written_panels = 0
+        for page in k.page_list:
+            original_filename_base = os.path.splitext(os.path.basename(page.filename))[0]
+
+            for i, panel in enumerate(page.panels):
+                x, y, width, height = panel.to_xywh()
+                panel_img = page.img[y:y + height, x:x + width]
+                
+                output_filepath = ""
+                # Check user's choice for the output structure
+                if output_structure == "Group panels in folders":
+                    # Default behavior: one folder per image
+                    image_specific_dir = os.path.join(panel_output_dir, original_filename_base)
+                    os.makedirs(image_specific_dir, exist_ok=True)
+                    output_filename = f"panel_{i}.jpg"
+                    output_filepath = os.path.join(image_specific_dir, output_filename)
+                else: # "Create a flat directory"
+                    # New behavior: flat structure with prefixed filenames
+                    output_filename = f"{original_filename_base}_panel_{i}.jpg"
+                    output_filepath = os.path.join(panel_output_dir, output_filename)
+
+                # Save the panel using our unicode-safe writer
+                if imwrite_unicode(output_filepath, panel_img):
+                    nb_written_panels += 1
+                else:
+                    print(f"\n[ERROR] Failed to write panel image to {output_filepath}\n")
+
+        # 3. Package all cropped panels into a ZIP file
+        progress(0.9, desc="Creating ZIP archive...")
+        if nb_written_panels == 0:
+             raise gr.Error("Analysis complete, but no croppable panels were detected.")
+
+        zip_filename_base = os.path.join(zip_output_dir, "kumiko_output")
+        zip_filepath = shutil.make_archive(zip_filename_base, 'zip', panel_output_dir)
+        
+        progress(1, desc="Done!")
+        
+        return zip_filepath
+
+    except Exception as e:
+        # Catch any other potential errors during processing
+        raise gr.Error(f"An error occurred during processing: {e}")
+    finally:
+        # 4. Clean up the temporary directory for panels, regardless of success or failure
+        shutil.rmtree(panel_output_dir)
+        # Note: Gradio will automatically handle the cleanup of zip_output_dir because a file from it is returned.
+
+# ----------------------------------------------------------------------
+# Create and Launch the Gradio Interface
+# ----------------------------------------------------------------------
+
+with gr.Blocks(theme=gr.themes.Soft()) as demo:
+    gr.Markdown(
+        """
+        # Kumiko Manga/Comics Panel Extractor (WebUI)  
+        Upload your manga or comic book images. This tool will automatically analyze the panels on each page,
+        crop them into individual image files, and package them into a single ZIP file for you to download.
+        
+        This application is licensed under the **GNU Affero General Public License v3.0**.  
+        The core panel detection is powered by the **kumikolib** library, created by **njean42** ([Original Project](https://github.com/njean42/kumiko)).
+        """
+    )
+    
+    with gr.Row():
+        with gr.Column(scale=1):
+            image_input = gr.Files(
+                label="Upload Manga Images",
+                file_count="multiple",
+                file_types=["image"],
+            )
+            
+            with gr.Accordion("Advanced Settings", open=False):
+                # Add the new Radio button for selecting the output structure
+                output_structure_choice = gr.Radio(
+                    label="ZIP File Structure",
+                    choices=["Group panels in folders", "Create a flat directory"],
+                    value="Group panels in folders", # Default value
+                    info="Choose how to organize panels in the output ZIP file."
+                )
+                
+                # Add the new Checkbox for RTL setting
+                rtl_checkbox = gr.Checkbox(
+                    label="Right-to-Left (RTL) Reading Order",
+                    value=False, # Default to False
+                    info="Check this for manga that is read from right to left."
+                )
+            
+            process_button = gr.Button("Start Analysis & Cropping", variant="primary")
+        
+        with gr.Column(scale=1):
+            output_zip = gr.File(
+                label="Download Cropped Panels (ZIP)",
+            )
+
+    process_button.click(
+        fn=process_manga_images,
+        inputs=[image_input, output_structure_choice, rtl_checkbox],
+        outputs=output_zip,
+        api_name="process"
+    )
+
+    # gr.Examples(
+    #     examples=[
+    #         [
+    #             [os.path.join(os.path.dirname(__file__), "example1.jpg"), os.path.join(os.path.dirname(__file__), "example2.png")]
+    #         ]
+    #     ],
+    #     inputs=image_input,
+    #     outputs=output_zip,
+    #     fn=process_manga_images,
+    #     label="Examples (place example1.jpg and example2.png in the same directory as this script)"
+    # )
+
+
+if __name__ == "__main__":
+    demo.launch(inbrowser=True)

kumikolib.py

@@ -0,0 +1,130 @@
+import os
+import sys
+import tempfile
+import cv2 as cv
+import numpy as np
+import requests
+import subprocess
+from urllib.parse import urlparse
+
+from lib.page import Page, NotAnImageException
+from lib.debug import Debug
+
+
+class Kumiko:
+
+	options = {}
+
+	def __init__(self, options = None):
+		options = options or {}
+
+		for o in ['progress', 'rtl', 'debug']:
+			self.options[o] = o in options and options[o]
+
+		Debug.debug = self.options['debug']
+
+		self.options['min_panel_size_ratio'] = options.get('min_panel_size_ratio', None)
+
+		self.panel_expansion = options.get('panel_expansion', True)
+
+		self.page_list = []
+
+	def parse_url_list(self, urls):
+		if self.options['progress']:
+			print(len(urls), 'files to download', file = sys.stderr)
+
+		self.temp_folder = tempfile.TemporaryDirectory()
+
+		i = 0
+		nbdigits = len(str(len(urls)))
+		for url in urls:
+			filename = 'img' + ('0' * nbdigits + str(i))[-nbdigits:]
+
+			if self.options['progress']:
+				print('\t', url, (' -> ' + filename) if urls else '', file = sys.stderr)
+
+			i += 1
+			parts = urlparse(url)
+			if not parts.netloc or not parts.path:
+				continue
+
+			r = requests.get(url, timeout = 5)
+			with open(os.path.join(self.temp_folder.name, filename), 'wb') as f:
+				f.write(r.content)
+
+		self.parse_dir(self.temp_folder.name, urls = urls)
+
+	def parse_pdf_file(self, pdf_filename):
+		try:
+			subprocess.run(args = ['pdftoppm', '--help'], check = True, capture_output = True)
+		except FileNotFoundError:
+			print("Please `apt install pdftoppm` if you give PDF --input files to Kumiko", file = sys.stderr)
+			sys.exit(1)
+
+		self.temp_folder = tempfile.mkdtemp(prefix = "kumiko-pdf-pages-")
+
+		print(f"Using pdftoppm to extract jpeg files from pdf to {self.temp_folder}", file = sys.stderr)
+		subprocess.run(args = ['pdftoppm', '-jpeg', pdf_filename, f"{self.temp_folder}/"], check = True)
+
+		self.parse_dir(self.temp_folder)
+
+	def parse_dir(self, directory, urls = None):
+		filenames = []
+		for filename in os.scandir(directory):
+			filenames.append(filename.path)
+		self.parse_images(filenames, urls)
+
+	def parse_images(self, filenames, urls = None):
+		if self.options['progress']:
+			print(len(filenames), 'files to cut panels for', file = sys.stderr)
+
+		i = -1
+		for filename in sorted(filenames):
+			i += 1
+			if self.options['progress']:
+				print("\t", urls[i] if urls else filename, file = sys.stderr)
+
+			try:
+				self.parse_image(filename, url = urls[i] if urls else None)
+			except NotAnImageException:
+				if not filename.endswith(".license"):
+					print(f"\n[ERROR] Not an image, will be ignored: {filename}\n", file = sys.stderr)
+
+	def parse_image(self, filename, url = None):
+		self.page_list.append(
+			Page(
+				filename,
+				numbering = "rtl" if self.options['rtl'] else "ltr",
+				url = url,
+				min_panel_size_ratio = self.options['min_panel_size_ratio'],
+				panel_expansion = self.panel_expansion,
+			)
+		)
+
+	def get_infos(self):
+		return list(map(lambda p: p.get_infos(), self.page_list))
+
+	def save_panels(self, output_base_path = 'auto', output_format = "jpg"):
+		if output_base_path == 'auto':
+			output_base_path = tempfile.mkdtemp(prefix = "kumiko-out-")
+		elif not os.path.isdir(output_base_path):
+			print(
+				f"\n[ERROR] Given --save-panels directory is not a directory: {output_base_path}\n", file = sys.stderr
+			)
+			sys.exit(1)
+
+		nb_written_panels = 0
+		for page in self.page_list:
+			output_path = os.path.join(output_base_path, os.path.basename(page.filename))
+			os.makedirs(output_path, exist_ok = True)
+
+			for i, panel in enumerate(page.panels):
+				x, y, width, height = panel.to_xywh()
+				output_file = os.path.join(output_path, f"panel_{i}.{output_format}")
+				panel = page.img[y:y + height, x:x + width]
+				if cv.imwrite(output_file, panel):
+					nb_written_panels += 1
+				else:
+					print(f"\n[ERROR] Failed to write panel image to {output_file}\n", file = sys.stderr)
+
+		print(f"Saved {nb_written_panels} panel images to {output_base_path}", file = sys.stderr)

lib/debug.py

@@ -0,0 +1,280 @@
+import os
+import json
+import copy
+import re
+import time
+import cv2 as cv
+import numpy as np
+
+from lib.html import HTML
+
+
+class Debug:
+
+	colours = {
+		'white': (255, 255, 255),
+		'red': (0, 0, 255),
+		'green': (0, 255, 0),
+		'blue': (255, 0, 0),
+		'lightblue': (200, 200, 0),
+		'lightpurple': (200, 0, 200),
+		'yellow': (0, 200, 200),
+		'gray': (150, 150, 150),
+	}
+
+	# white, red and green are used to display main panels
+	subpanel_colours = list(colours.values())[3:]
+
+	debug = False
+	contour_size = None
+	steps = []
+	images = {}
+	time = time.time_ns()
+	base_img = img = None
+
+	@staticmethod
+	def set_base_img(img):
+		if not Debug.debug:
+			return
+
+		Debug.base_img = img
+		Debug.img = np.copy(img)
+
+	@staticmethod
+	def add_step(name, infos):
+		if not Debug.debug:
+			return
+
+		elapsed = Debug.show_time(f"{name} ({len(infos['panels'])} panels)")
+
+		Debug.steps.append({
+			'name': name,
+			'elapsed_since_last_step': elapsed,
+			'infos': copy.deepcopy(infos),
+		})
+
+	@staticmethod
+	def show_time(name):
+		if not Debug.debug:
+			return
+
+		Debug.prev_time = Debug.time
+		Debug.time = time.time_ns()
+
+		elapsed = Debug.time - Debug.prev_time
+		print(f"{name} − {elapsed/pow(10,6):.0f}ms")
+
+		return elapsed
+
+	imgID = 0
+
+	@staticmethod
+	def add_image(label, img = None):
+		if not Debug.debug:
+			return
+
+		clean_filename = re.sub(r'\W', '-', label)
+		filename = f"{Debug.imgID}-{clean_filename}.jpg"
+		Debug.imgID += 1
+		cv.imwrite(os.path.join('tests/results', filename), Debug.img if img is None else img)
+
+		# reinit image so we see only specific steps' contours/lines/dots
+		Debug.img = np.copy(Debug.base_img)
+
+		currstep = len(Debug.steps) - 1
+		if currstep not in Debug.images:
+			Debug.images[currstep] = []
+		Debug.images[currstep].append({'filename': filename, 'label': label})
+
+	@staticmethod
+	def html(images_dir, reldir):
+		html = ''
+		html += HTML.header(title = 'Debugging - Kumiko processing steps', reldir = reldir)
+
+		for i in range(len(Debug.steps) - 1):
+			j = i + 1
+
+			# Display debug images
+			if i in Debug.images:
+				html += HTML.imgbox(Debug.images[i])
+
+			# Display panels diffs
+			files_diff = Debug.get_files_diff(images_dir, [Debug.steps[i]['infos']], [Debug.steps[j]['infos']])
+
+			step_name = str(i + 1) + '. ' + Debug.steps[j]['name']
+
+			if len(files_diff) == 0:
+				html += f"<h2>{step_name} - no change</h2>"
+
+			for _, diffs in files_diff.items():
+				html += HTML.side_by_side_panels(
+					step_name,
+					f"took {Debug.steps[j]['elapsed_since_last_step']/pow(10,9):.2f} seconds",
+					diffs['jsons'],
+					f"BEFORE - {len(diffs['jsons'][0][0]['panels'])} panels",
+					f"AFTER  - {len(diffs['jsons'][1][0]['panels'])} panels",
+					images_dir = diffs['images_dir'],
+					known_panels = diffs['known_panels'],
+					diff_numbering_panels = diffs['diff_numbering_panels'],
+				)
+
+		html += HTML.footer
+		return html
+
+	@staticmethod
+	def get_files_diff(file_or_dir, json1, json2):
+		from lib.panel import Panel
+
+		files_diff = {}
+
+		for p in range(len(json1)):  # for each page
+
+			# check both images' filename and size, should be the same
+			if os.path.basename(json1[p]['filename']) != os.path.basename(json2[p]['filename']):
+				print('error, filenames are not the same', json1[p]['filename'], json2[p]['filename'])
+				continue
+			if json1[p]['size'] != json2[p]['size']:
+				print('error, image sizes are not the same', json1[p]['size'], json2[p]['size'])
+				continue
+
+			panels_v1 = list(map(lambda p: Panel(None, p), json1[p]['panels']))
+			panels_v2 = list(map(lambda p: Panel(None, p), json2[p]['panels']))
+
+			known_panels = [[], []]
+			j = -1
+			for p1 in panels_v1:
+				j += 1
+				if p1 in panels_v2:
+					known_panels[0].append(j)
+			j = -1
+			for p2 in panels_v2:
+				j += 1
+				if p2 in panels_v1:
+					known_panels[1].append(j)
+
+			images_dir = 'urls'
+			if file_or_dir != 'urls':
+				images_dir = file_or_dir if os.path.isdir(file_or_dir) else os.path.dirname(file_or_dir)
+				images_dir = os.path.relpath(images_dir, 'tests/results') + '/'
+
+			diff_numbering = []
+			diff_panels = False
+			if len(known_panels[0]) != len(panels_v1) or len(known_panels[1]) != len(panels_v2):
+				diff_panels = True
+			else:
+				for i in range(len(panels_v1)):
+					if panels_v1[i] != panels_v2[i]:
+						diff_numbering.append(i + 1)
+
+			if diff_panels or len(diff_numbering) > 0:
+				files_diff[json1[p]['filename']] = {
+					'jsons': [[json1[p]], [json2[p]]],
+					'images_dir': images_dir,
+					'known_panels': [json.dumps(known_panels[0]),
+										json.dumps(known_panels[1])],
+					'diff_numbering_panels': diff_numbering,
+				}
+
+		return files_diff
+
+	@staticmethod
+	def draw_contours(contours, colour = 'auto', with_hull = False):
+		if not Debug.debug:
+			return
+
+		if Debug.contour_size is None:
+			raise Exception("Fatal error, Debug.contour_size has not been defined")
+
+		for i in range(len(contours)):
+			if colour == 'auto':
+				colour = Debug.subpanel_colours[i % len(Debug.subpanel_colours)]
+
+			cv.drawContours(Debug.img, [contours[i]], 0, colour, Debug.contour_size)
+
+			if with_hull:
+				hull = cv.convexHull(contours[i])
+				cv.drawContours(Debug.img, [hull], 0, Debug.colours['yellow'], Debug.contour_size)
+
+	@staticmethod
+	def draw_segments(segments, colour, size = None):
+		if not Debug.debug:
+			return
+
+		if size is None:
+			size = Debug.contour_size
+
+		for segment in segments:
+			Debug.draw_line(segment.a, segment.b, colour, size = size)
+
+	@staticmethod
+	def draw_line(dot1, dot2, colour, size = None):
+		if not Debug.debug:
+			return
+
+		if Debug.contour_size is None:
+			raise Exception("Fatal error, Debug.contour_size has not been defined")
+
+		if size is None:
+			size = Debug.contour_size
+		cv.line(Debug.img, (dot1[0], dot1[1]), (dot2[0], dot2[1]), colour, size, cv.LINE_AA)
+
+	@staticmethod
+	def draw_dots(dots, colour):
+		if not Debug.debug:
+			return
+
+		for dot in dots:
+			Debug.draw_dot(dot[0], dot[1], colour)
+
+	@staticmethod
+	def draw_nearby_dots(polygon, nearby_dots):
+		if not Debug.debug:
+			return
+
+		for dots in nearby_dots:
+			dot1 = polygon[dots[0]][0]
+			dot2 = polygon[dots[1]][0]
+			Debug.draw_dot(dot1[0], dot1[1], Debug.colours['lightpurple'])
+			Debug.draw_dot(dot2[0], dot2[1], Debug.colours['lightpurple'])
+			Debug.draw_line(dot1, dot2, Debug.colours['lightpurple'], size = 1)
+
+	@staticmethod
+	def draw_dot(x, y, colour):
+		if not Debug.debug:
+			return
+
+		if Debug.contour_size is None:
+			raise Exception("Fatal error, Debug.contour_size has not been defined")
+
+		cv.circle(Debug.img, (x, y), Debug.contour_size * 2, colour, -1)
+
+	@staticmethod
+	def draw_panels(panels, colour):
+		if not Debug.debug:
+			return
+
+		if Debug.contour_size is None:
+			raise Exception("Fatal error, Debug.contour_size has not been defined")
+
+		for p in panels:
+			cv.rectangle(Debug.img, (p.x, p.y), (p.r, p.b), colour, Debug.contour_size)
+
+		# + draw inner white border
+		for p in panels:
+			cv.rectangle(
+				Debug.img, (p.x + Debug.contour_size, p.y + Debug.contour_size),
+				(p.r - Debug.contour_size, p.b - Debug.contour_size), Debug.colours['white'],
+				int(Debug.contour_size / 2)
+			)
+
+	@staticmethod
+	def draw_polygon(polygon):
+		if not Debug.debug:
+			return
+
+		for i in range(len(polygon)):
+			j = (i + 1) % len(polygon)
+			dot1 = polygon[i][0]
+			dot2 = polygon[j][0]
+			Debug.draw_line(dot1, dot2, Debug.colours['red'], size = 2)
+			Debug.draw_dot(dot1[0], dot1[1], Debug.colours['gray'])

lib/html.py

@@ -0,0 +1,106 @@
+import json
+
+
+class HTML:
+
+	@staticmethod
+	def header(title = '', reldir = ''):
+		return f"""<!DOCTYPE html>
+			<html>
+
+			<head>
+				<title>Kumiko Reader</title>
+				<meta charset="utf-8">
+				<meta name="viewport" content="width=device-width, initial-scale=1">
+				<script type="text/javascript" src="{reldir}jquery-3.2.1.min.js"></script>
+				<script type="text/javascript" src="{reldir}reader.js"></script>
+				<link rel="stylesheet" media="all" href="{reldir}style.css" />
+				<style type="text/css">
+					h2, h3 {{ text-align: center; margin-top: 3em; }}
+					.sidebyside {{ display: flex; justify-content: space-around; }}
+					.sidebyside > div {{ width: 45%; }}
+					.version, .step-info {{ text-align: center; }}
+					.kumiko-reader.halfwidth {{ max-width: 45%; max-height: 90vh; }}
+					.kumiko-reader.fullpage {{ width: 100%; height: 100%; }}
+				</style>
+			</head>
+
+			<body>
+			<h1>{title}</h1>
+
+		"""
+
+	@staticmethod
+	def nbdiffs(files_diff):
+		return f"<p>{len(files_diff)} differences found in files</p>"
+
+	pageId = 0
+
+	@staticmethod
+	def side_by_side_panels(title, step_info, jsons, v1, v2, images_dir, known_panels, diff_numbering_panels):
+		html = f"""
+			<h2>{title}</h2>
+			<p class="step-info">{step_info}</p>
+			<div class="sidebyside">
+				<div class="version">{v1} <span class="processing_time">− processing time {jsons[0][0]['processing_time'] if 'processing_time' in jsons[0][0] else "??"}s</span></div>
+				<div class="version">{v2} <span class="processing_time">- processing time {jsons[1][0]['processing_time']}s</span></div>
+			</div>
+			<div class="sidebyside">
+		"""
+
+		oneside = """
+			<div id="page{id}" class="kumiko-reader halfwidth debug"></div>
+			<script type="text/javascript">
+				var reader = new Reader({{
+					container: $('#page{id}'),
+					comicsJson: {json},
+					images_dir: {images_dir},
+					known_panels: {known_panels},
+					diff_numbering_panels: {diff_numbering_panels},
+				}});
+				reader.start();
+			</script>
+			"""
+		i = -1
+		for js in jsons:
+			i += 1
+			html += oneside.format(
+				id = HTML.pageId,
+				json = json.dumps(js),
+				images_dir = json.dumps(images_dir),
+				known_panels = known_panels[i],
+				diff_numbering_panels = diff_numbering_panels
+			)
+			HTML.pageId += 1
+
+		html += '</div>'
+		return html
+
+	@staticmethod
+	def imgbox(images):
+		html = "<h3>Debugging images</h3>\n<div class='imgbox'>\n"
+		for img in images:
+			html += f"\t<div><p>{img['label']}</p><img src='{img['filename']}' /></div>\n"
+
+		return html + "</div>\n\n"
+
+	@staticmethod
+	def reader(js, images_dir):
+		return f"""
+			<div id="reader" class="kumiko-reader fullpage"></div>
+			<script type="text/javascript">
+				var reader = new Reader({{
+					container: $('#reader'),
+					comicsJson: {js},
+					images_dir: {json.dumps(images_dir)},
+					controls: true
+				}});
+				reader.start();
+			</script>
+			"""
+
+	footer = """
+
+</body>
+</html>
+"""

lib/page.py

@@ -0,0 +1,404 @@
+import math
+import os
+import json
+import sys
+import time
+import cv2 as cv
+import numpy as np
+
+from lib.panel import Panel
+from lib.segment import Segment
+from lib.debug import Debug
+
+
+class NotAnImageException(Exception):
+	pass
+
+
+class Page:
+
+	DEFAULT_MIN_PANEL_SIZE_RATIO = 1 / 10
+
+	def get_infos(self):
+		actual_gutters = self.actual_gutters()
+
+		return {
+			'filename': self.url if self.url else os.path.basename(self.filename),
+			'size': self.img_size,
+			'numbering': self.numbering,
+			'gutters': [actual_gutters['x'], actual_gutters['y']],
+			'license': self.license,
+			'panels': list(map(lambda p: p.to_xywh(), self.panels)),
+			'processing_time': self.processing_time
+		}
+
+	def __init__(
+		self,
+		filename,
+		numbering = None,
+		debug = False,
+		url = None,
+		min_panel_size_ratio = None,
+		panel_expansion = True
+	):
+		self.filename = filename
+		self.panels = []
+		self.segments = []
+
+		self.processing_time = None
+		t1 = time.time_ns()
+
+		self.img = cv.imread(filename)
+		if not isinstance(self.img, np.ndarray) or self.img.size == 0:
+			raise NotAnImageException(f"File {filename} is not an image")
+
+		self.numbering = numbering or "ltr"
+		if not (numbering in ['ltr', 'rtl']):
+			raise Exception('Fatal error, unknown numbering: ' + str(numbering))
+
+		self.small_panel_ratio = min_panel_size_ratio or Page.DEFAULT_MIN_PANEL_SIZE_RATIO
+		self.panel_expansion = panel_expansion
+		self.url = url
+
+		self.img_size = list(self.img.shape[:2])
+		self.img_size.reverse()  # get a [width,height] list
+
+		Debug.contour_size = 3
+
+		# get license for this file
+		self.license = None
+		if os.path.isfile(filename + '.license'):
+			with open(filename + '.license', encoding = "utf8") as fh:
+				try:
+					self.license = json.load(fh)
+				except json.decoder.JSONDecodeError:
+					print(f"License file {filename+'.license'} is not a valid JSON file", file = sys.stderr)
+					sys.exit(1)
+
+		Debug.set_base_img(self.img)
+
+		Debug.add_step('Initial state', self.get_infos())
+		Debug.add_image('Input image')
+
+		self.gray = cv.cvtColor(self.img, cv.COLOR_BGR2GRAY)
+		Debug.add_image('Shades of gray', img = self.gray)
+		Debug.show_time("Shades of gray")
+
+		# https://docs.opencv.org/3.4/d2/d2c/tutorial_sobel_derivatives.html
+		ddepth = cv.CV_16S
+		grad_x = cv.Sobel(self.gray, ddepth, 1, 0, ksize = 3, scale = 1, delta = 0, borderType = cv.BORDER_DEFAULT)
+		# Gradient-Y
+		# grad_y = cv.Scharr(self.gray,ddepth,0,1)
+		grad_y = cv.Sobel(self.gray, ddepth, 0, 1, ksize = 3, scale = 1, delta = 0, borderType = cv.BORDER_DEFAULT)
+
+		abs_grad_x = cv.convertScaleAbs(grad_x)
+		abs_grad_y = cv.convertScaleAbs(grad_y)
+
+		self.sobel = cv.addWeighted(abs_grad_x, 0.5, abs_grad_y, 0.5, 0)
+		Debug.add_image('Sobel filter applied', img = self.sobel)
+		Debug.show_time("Sobel filter")
+
+		self.get_contours()
+		self.get_segments()
+		self.get_initial_panels()
+		self.group_small_panels()
+		self.split_panels()
+		self.exclude_small_panels()
+		self.merge_panels()
+		self.deoverlap_panels()
+		self.exclude_small_panels()
+
+		if self.panel_expansion:
+			self.panels.sort()  # TODO: move this below before panels sort-fix, when panels expansion is smarter
+			self.expand_panels()
+
+		if len(self.panels) == 0:
+			self.panels.append(Panel(page = self, xywh = [0, 0, self.img_size[0], self.img_size[1]]))
+
+		self.group_big_panels()
+
+		self.fix_panels_numbering()
+
+		self.processing_time = int((time.time_ns() - t1) / 10**7) / 100
+
+	def get_contours(self):
+		# Black background: values above 100 will be black, the rest white
+		_, thresh = cv.threshold(self.sobel, 100, 255, cv.THRESH_BINARY)
+		Debug.show_time("Image threshhold")
+
+		self.contours, _ = cv.findContours(thresh, cv.RETR_EXTERNAL, cv.CHAIN_APPROX_SIMPLE)[-2:]
+
+		Debug.add_image("Thresholded image", img = thresh)
+		Debug.show_time("Get contours")
+
+	def get_segments(self):
+		self.segments = None
+
+		lsd = cv.createLineSegmentDetector(0)
+		dlines = lsd.detect(self.gray)
+
+		Debug.show_time("Detected segments")
+
+		min_dist = min(self.img_size) * self.small_panel_ratio
+
+		while self.segments is None or len(self.segments) > 500:
+			self.segments = []
+
+			if dlines is None or dlines[0] is None:
+				break
+
+			for dline in dlines[0]:
+				x0 = int(round(dline[0][0]))
+				y0 = int(round(dline[0][1]))
+				x1 = int(round(dline[0][2]))
+				y1 = int(round(dline[0][3]))
+
+				a = x0 - x1
+				b = y0 - y1
+				dist = math.sqrt(a**2 + b**2)
+				if dist >= min_dist:
+					self.segments.append(Segment([x0, y0], [x1, y1]))
+
+			min_dist *= 1.1
+
+		self.segments = Segment.union_all(self.segments)
+
+		Debug.draw_segments(self.segments, Debug.colours['green'])
+		Debug.add_image("Segment Detector")
+		Debug.show_time("Compiled segments")
+
+	# Get (square) panels out of initial contours
+	def get_initial_panels(self):
+		self.panels = []
+		for contour in self.contours:
+			arclength = cv.arcLength(contour, True)
+			epsilon = 0.001 * arclength
+			approx = cv.approxPolyDP(contour, epsilon, True)
+
+			panel = Panel(page = self, polygon = approx)
+			if panel.is_very_small():
+				continue
+
+			Debug.draw_contours([approx], Debug.colours['red'])
+
+			self.panels.append(panel)
+
+		Debug.add_image('Initial contours')
+		Debug.add_step('Panels from initial contours', self.get_infos())
+
+	# Group small panels that are close together, into bigger ones
+	def group_small_panels(self):
+		small_panels = list(filter(lambda p: p.is_small(), self.panels))
+		groups = {}
+		group_id = 0
+
+		for i, p1 in enumerate(small_panels):
+			for p2 in small_panels[i + 1:]:
+				if p1 == p2:
+					continue
+
+				if not p1.is_close(p2):
+					continue
+
+				if p1 not in groups and p2 not in groups:
+					group_id += 1
+					groups[p1] = group_id
+					groups[p2] = group_id
+				elif p1 in groups and p2 not in groups:
+					groups[p2] = groups[p1]
+				elif p2 in groups and p1 not in groups:
+					groups[p1] = groups[p2]
+				elif groups[p1] != groups[p2]:
+					# group group1 and group2 together
+					for p, id in groups.items():
+						if id == groups[p2]:
+							groups[p] = groups[p1]
+
+		grouped = {}
+		for k, v in groups.items():
+			grouped[v] = grouped.get(v, []) + [k]
+
+		for small_panels in grouped.values():
+			big_hull = cv.convexHull(np.concatenate(list(map(lambda p: p.polygon, small_panels))))
+			big_panel = Panel(page = self, polygon = big_hull, splittable = False)
+
+			self.panels.append(big_panel)
+			for p in small_panels:
+				self.panels.remove(p)
+
+			Debug.draw_contours(list(map(lambda p: p.polygon, small_panels)), Debug.colours['lightblue'])
+			Debug.draw_contours([big_panel.polygon], Debug.colours['red'])
+
+		if group_id > 0:
+			Debug.add_image('Group small panels')
+		Debug.add_step('Group small panels', self.get_infos())
+
+	# See if panels can be cut into several (two non-consecutive points are close)
+	def split_panels(self):
+		did_split = True
+		while did_split:
+			did_split = False
+			for p in sorted(self.panels, key = lambda p: p.area(), reverse = True):
+				split = p.split()
+				if split is not None:
+					did_split = True
+					self.panels.remove(p)
+					self.panels += split.subpanels
+
+					Debug.draw_contours(list(map(lambda n: n.polygon, split.subpanels)), Debug.colours['blue'])
+					Debug.draw_line(split.segment.a, split.segment.b, Debug.colours['red'])
+					break
+
+			if did_split:
+				Debug.add_image(
+					'Split contours (blue contours, red split-segment, gray polygon dots, purple nearby dots)'
+				)
+
+		Debug.add_step(f"Panels from split contours ({len(self.segments)} segments)", self.get_infos())
+
+	def exclude_small_panels(self):
+		self.panels = list(filter(lambda p: not p.is_small(), self.panels))
+
+		Debug.add_step('Exclude small panels', self.get_infos())
+
+	# Splitting polygons may result in panels slightly overlapping, de-overlap them
+	def deoverlap_panels(self):
+		for p1 in self.panels:
+			for p2 in self.panels:
+				if p1 == p2:
+					continue
+
+				opanel = p1.overlap_panel(p2)
+				if not opanel:
+					continue
+
+				if opanel.w() < opanel.h() and p1.r == opanel.r:
+					p1.r = opanel.x
+					p2.x = opanel.r
+					continue
+
+				if opanel.w() > opanel.h() and p1.b == opanel.b:
+					p1.b = opanel.y
+					p2.y = opanel.b
+					continue
+
+		Debug.add_step('Deoverlap panels', self.get_infos())
+
+	# Merge panels that shouldn't have been split (speech bubble diving into a panel)
+	def merge_panels(self):
+		panels_to_remove = []
+		for i, p1 in enumerate(self.panels):
+			for j, p2 in enumerate(self.panels[i + 1:]):
+				if p1.contains(p2):
+					panels_to_remove.append(p2)
+					p1 = p1.merge(p2)
+				elif p2.contains(p1):
+					panels_to_remove.append(p1)
+					p2 = p2.merge(p1)
+
+		for p in set(panels_to_remove):
+			self.panels.remove(p)
+
+		Debug.add_step('Merge panels', self.get_infos())
+
+	# Find out actual gutters between panels
+	def actual_gutters(self, func = min):
+		gutters_x = []
+		gutters_y = []
+		for p in self.panels:
+			left_panel = p.find_left_panel()
+			if left_panel:
+				gutters_x.append(p.x - left_panel.r)
+
+			top_panel = p.find_top_panel()
+			if top_panel:
+				gutters_y.append(p.y - top_panel.b)
+
+		if not gutters_x:
+			gutters_x = [1]
+		if not gutters_y:
+			gutters_y = [1]
+
+		return {'x': func(gutters_x), 'y': func(gutters_y), 'r': -func(gutters_x), 'b': -func(gutters_y)}
+
+	def max_gutter(self):
+		return max(self.actual_gutters().values())
+
+	# Expand panels to their neighbour's edge, or page boundaries
+	def expand_panels(self):
+		gutters = self.actual_gutters()
+		for p in self.panels:
+			for d in ['x', 'y', 'r', 'b']:  # expand in all four directions
+				newcoord = -1
+				neighbour = p.find_neighbour_panel(d)
+				if neighbour:
+					# expand to that neighbour's edge (minus gutter)
+					newcoord = getattr(neighbour, {'x': 'r', 'r': 'x', 'y': 'b', 'b': 'y'}[d]) + gutters[d]
+				else:
+					# expand to the furthest known edge (frame around all panels)
+					min_panel = min(self.panels, key = lambda p: getattr(p, d)) if d in [
+						'x', 'y'
+					] else max(self.panels, key = lambda p: getattr(p, d))
+					newcoord = getattr(min_panel, d)
+
+				if newcoord != -1:
+					if d in ['r', 'b'] and newcoord > getattr(p, d) or d in ['x', 'y'] and newcoord < getattr(p, d):
+						setattr(p, d, newcoord)
+
+		Debug.add_step('Expand panels', self.get_infos())
+
+	# Fix panels simple sorting (issue #12)
+	def fix_panels_numbering(self):
+		changes = 1
+		while changes:
+			changes = 0
+			for i, p in enumerate(self.panels):
+				neighbours_before = [p.find_top_panel()]
+				neighbours_before += p.find_all_right_panels() if self.numbering == "rtl" else p.find_all_left_panels()
+
+				for neighbour in neighbours_before:
+					if neighbour is None:
+						continue
+					neighbour_pos = self.panels.index(neighbour)
+					if i < neighbour_pos:
+						changes += 1
+						self.panels.insert(neighbour_pos, self.panels.pop(i))
+						break
+				if changes > 0:
+					break  # start a new whole loop with reordered panels
+
+		Debug.add_step('Numbering fixed', self.get_infos())
+
+	# group big panels together
+	def group_big_panels(self):
+		grouped = True
+		while grouped:
+			grouped = False
+			for i, p1 in enumerate(self.panels):
+				for p2 in self.panels[i + 1:]:
+					p3 = p1.group_with(p2)
+
+					other_panels = [p for p in self.panels if p not in [p1, p2]]
+					if p3.bumps_into(other_panels):
+						continue
+
+					# are there big segments in this panel?
+					segments = []
+					for s in self.segments:
+						if p3.contains_segment(s) and s.dist() > p3.diagonal().dist() / 5:
+							if s not in segments:
+								segments.append(s)
+
+					if len(segments) > 0:  # maybe allow a small number of big segments here?
+						continue
+
+					self.panels.append(p3)
+					self.panels.remove(p1)
+					self.panels.remove(p2)
+					grouped = True
+					break
+
+				if grouped:
+					break
+
+		Debug.add_step('Group big panels', self.get_infos())

lib/panel.py

@@ -0,0 +1,479 @@
+import math
+import cv2 as cv
+import numpy as np
+
+from lib.segment import Segment
+from lib.debug import Debug
+
+
+class Panel:
+
+	@staticmethod
+	def from_xyrb(page, x, y, r, b):
+		return Panel(page, xywh = [x, y, r - x, b - y])
+
+	def __init__(self, page, xywh = None, polygon = None, splittable = True):
+		self.page = page
+
+		if xywh is None and polygon is None:
+			raise Exception('Fatal error: no parameter to define Panel boundaries')
+
+		if xywh is None:
+			xywh = cv.boundingRect(polygon)
+
+		self.x = xywh[0]  # panel's left edge
+		self.y = xywh[1]  # panel's top edge
+		self.r = self.x + xywh[2]  # panel's right edge
+		self.b = self.y + xywh[3]  # panel's bottom edge
+
+		self.polygon = polygon
+		self.splittable = splittable
+		self.segments = None
+		self.coverage = None
+
+	def w(self):
+		return self.r - self.x
+
+	def h(self):
+		return self.b - self.y
+
+	def diagonal(self):
+		return Segment((self.x, self.y), (self.r, self.b))
+
+	def wt(self):
+		return self.w() / 10
+		# wt = width threshold (under which two edge coordinates are considered equal)
+
+	def ht(self):
+		return self.h() / 10
+		# ht = height threshold
+
+	def to_xywh(self):
+		return [self.x, self.y, self.w(), self.h()]
+
+	def __eq__(self, other):
+		return all(
+			[
+				abs(self.x - other.x) < self.wt(),
+				abs(self.y - other.y) < self.ht(),
+				abs(self.r - other.r) < self.wt(),
+				abs(self.b - other.b) < self.ht(),
+			]
+		)
+
+	def __lt__(self, other):
+		# panel is above other
+		if other.y >= self.b - self.ht() and other.y >= self.y - self.ht():
+			return True
+
+		# panel is below other
+		if self.y >= other.b - self.ht() and self.y >= other.y - self.ht():
+			return False
+
+		# panel is left from other
+		if other.x >= self.r - self.wt() and other.x >= self.x - self.wt():
+			return True if self.page.numbering == 'ltr' else False
+
+		# panel is right from other
+		if self.x >= other.r - self.wt() and self.x >= other.x - self.wt():
+			return False if self.page.numbering == 'ltr' else True
+
+		return True  # should not happen, TODO: raise an exception?
+
+	def __le__(self, other):
+		return self.__lt__(other)
+
+	def __gt__(self, other):
+		return not self.__lt__(other)
+
+	def __ge__(self, other):
+		return self.__gt__(other)
+
+	def area(self):
+		return self.w() * self.h()
+
+	def __str__(self):
+		return f"{self.x}x{self.y}-{self.r}x{self.b}"
+
+	def __hash__(self):
+		return hash(self.__str__())
+
+	def is_small(self, extra_ratio = 1):
+		return any(
+			[
+				self.w() < self.page.img_size[0] * self.page.small_panel_ratio * extra_ratio,
+				self.h() < self.page.img_size[1] * self.page.small_panel_ratio * extra_ratio,
+			]
+		)
+
+	def is_very_small(self):
+		return self.is_small(1 / 10)
+
+	def overlap_panel(self, other):
+		if self.x > other.r or other.x > self.r:  # panels are left and right from one another
+			return None
+		if self.y > other.b or other.y > self.b:  # panels are above and below one another
+			return None
+
+		# if we're here, panels overlap at least a bit
+		x = max(self.x, other.x)
+		y = max(self.y, other.y)
+		r = min(self.r, other.r)
+		b = min(self.b, other.b)
+
+		return Panel(self.page, [x, y, r - x, b - y])
+
+	def overlap_area(self, other):
+		opanel = self.overlap_panel(other)
+		if opanel is None:
+			return 0
+
+		return opanel.area()
+
+	def overlaps(self, other):
+		opanel = self.overlap_panel(other)
+		if opanel is None:
+			return False
+
+		area_ratio = 0.1
+		smallest_panel_area = min(self.area(), other.area())
+
+		if smallest_panel_area == 0:  # probably a horizontal or vertical segment
+			return True
+
+		return opanel.area() / smallest_panel_area > area_ratio
+
+	def contains(self, other):
+		o_panel = self.overlap_panel(other)
+		if not o_panel:
+			return False
+
+		# self contains other if their overlapping area is more than 50% of other's area
+		return o_panel.area() / other.area() > 0.50
+
+	def same_row(self, other):
+		above, below = sorted([self, other], key = lambda p: p.y)
+
+		if below.y > above.b:  # stricly above
+			return False
+
+		if below.b < above.b:  # contained
+			return True
+
+		# intersect
+		intersection_y = min(above.b, below.b) - below.y
+		min_h = min(above.h(), below.h())
+		return min_h == 0 or intersection_y / min_h >= 1 / 3
+
+	def same_col(self, other):
+		left, right = sorted([self, other], key = lambda p: p.x)
+
+		if right.x > left.r:  # stricly left
+			return False
+
+		if right.r < left.r:  # contained
+			return True
+
+		# intersect
+		intersection_x = min(left.r, right.r) - right.x
+		min_w =  min(left.w(), right.w())
+		return min_w == 0 or intersection_x / min_w >= 1 / 3
+
+	def find_top_panel(self):
+		all_top = list(filter(lambda p: p.b <= self.y and p.same_col(self), self.page.panels))
+		return max(all_top, key = lambda p: p.b) if all_top else None
+
+	def find_bottom_panel(self):
+		all_bottom = list(filter(lambda p: p.y >= self.b and p.same_col(self), self.page.panels))
+		return min(all_bottom, key = lambda p: p.y) if all_bottom else None
+
+	def find_all_left_panels(self):
+		return list(filter(lambda p: p.r <= self.x and p.same_row(self), self.page.panels))
+
+	def find_left_panel(self):
+		all_left = self.find_all_left_panels()
+		return max(all_left, key = lambda p: p.r) if all_left else None
+
+	def find_all_right_panels(self):
+		return list(filter(lambda p: p.x >= self.r and p.same_row(self), self.page.panels))
+
+	def find_right_panel(self):
+		all_right = self.find_all_right_panels()
+		return min(all_right, key = lambda p: p.x) if all_right else None
+
+	def find_neighbour_panel(self, d):
+		return {
+			'x': self.find_left_panel,
+			'y': self.find_top_panel,
+			'r': self.find_right_panel,
+			'b': self.find_bottom_panel,
+		}[d]()
+
+	def group_with(self, other):
+		min_x = min(self.x, other.x)
+		min_y = min(self.y, other.y)
+		max_r = max(self.r, other.r)
+		max_b = max(self.b, other.b)
+		return Panel(self.page, [min_x, min_y, max_r - min_x, max_b - min_y])
+
+	def merge(self, other):
+		possible_panels = [self]
+
+		# expand self in all four directions where other is
+		if other.x < self.x:
+			possible_panels.append(Panel.from_xyrb(self.page, other.x, self.y, self.r, self.b))
+
+		if other.r > self.r:
+			for pp in possible_panels.copy():
+				possible_panels.append(Panel.from_xyrb(self.page, pp.x, pp.y, other.r, pp.b))
+
+		if other.y < self.y:
+			for pp in possible_panels.copy():
+				possible_panels.append(Panel.from_xyrb(self.page, pp.x, other.y, pp.r, pp.b))
+
+		if other.b > self.b:
+			for pp in possible_panels.copy():
+				possible_panels.append(Panel.from_xyrb(self.page, pp.x, pp.y, pp.r, other.b))
+
+		# don't take a merged panel that bumps into other panels on page
+		other_panels = [p for p in self.page.panels if p not in [self, other]]
+		possible_panels = list(filter(lambda p: not p.bumps_into(other_panels), possible_panels))
+
+		# take the largest merged panel
+		return max(possible_panels, key = lambda p: p.area()) if len(possible_panels) > 0 else self
+
+	def is_close(self, other):
+		c1x = self.x + self.w() / 2
+		c1y = self.y + self.h() / 2
+		c2x = other.x + other.w() / 2
+		c2y = other.y + other.h() / 2
+
+		return all(
+			[
+				abs(c1x - c2x) <= (self.w() + other.w()) * 0.75,
+				abs(c1y - c2y) <= (self.h() + other.h()) * 0.75,
+			]
+		)
+
+	def bumps_into(self, other_panels):
+		for other in other_panels:
+			if other == self:
+				continue
+			if self.overlaps(other):
+				return True
+
+		return False
+
+	def contains_segment(self, segment):
+		other = Panel.from_xyrb(None, *segment.to_xyrb())
+		return self.overlaps(other)
+
+	def get_segments(self):
+		if self.segments is not None:
+			return self.segments
+
+		self.segments = list(filter(lambda s: self.contains_segment(s), self.page.segments))
+
+		return self.segments
+
+	def split(self):
+		if self.splittable is False:
+			return None
+
+		split = self._cached_split()
+
+		if split is None:
+			self.splittable = False
+
+		return split
+
+	def _cached_split(self):
+		if self.polygon is None:
+			return None
+
+		if self.is_small(extra_ratio = 2):  # panel should be splittable in two non-small subpanels
+			return None
+
+		min_hops = 3
+		max_dist_x = int(self.w() / 3)
+		max_dist_y = int(self.h() / 3)
+		max_diagonal = math.sqrt(max_dist_x**2 + max_dist_y**2)
+		dots_along_lines_dist = max_diagonal / 5
+		min_dist_between_dots_x = max_dist_x / 10
+		min_dist_between_dots_y = max_dist_y / 10
+
+		# Compose modified polygon to optimise splits
+		original_polygon = np.copy(self.polygon)
+		polygon = np.ndarray(shape = (0, 1, 2), dtype = int, order = 'F')
+		intermediary_dots = []
+		extra_dots = []
+
+		for i in range(len(original_polygon)):
+			j = (i + 1) % len(original_polygon)
+			dot1 = tuple(original_polygon[i][0])
+			dot2 = tuple(original_polygon[j][0])
+			seg = Segment(dot1, dot2)
+
+			# merge nearby dots together
+			if seg.dist_x() < min_dist_between_dots_x and seg.dist_y() < min_dist_between_dots_y:
+				original_polygon[j][0] = seg.center()
+				continue
+
+			polygon = np.append(polygon, [[dot1]], axis = 0)
+
+			# Add dots on *long* edges, by projecting other polygon dots on this segment
+			add_dots = []
+
+			# should be splittable in [dot1, dot1b(?), projected_dot3, dot2b(?), dot2]
+			if seg.dist() < dots_along_lines_dist * 2:
+				continue
+
+			for k, dot3 in enumerate(original_polygon):
+				if abs(k - i) < min_hops:
+					continue
+
+				projected_dot3 = seg.projected_point(dot3)
+
+				# Segment should be able to contain projected_dot3
+				if not seg.may_contain(projected_dot3):
+					continue
+
+				# dot3 should be close to current segment − distance(dot3, projected_dot3) should be short
+				project = Segment(dot3[0], projected_dot3)
+				if project.dist_x() > max_dist_x or project.dist_y() > max_dist_y:
+					continue
+
+				# append dot3 as intermediary dot on segment(dot1, dot2)
+				add_dots.append(projected_dot3)
+				intermediary_dots.append(projected_dot3)
+
+			# Add also a dot near each end of the segment (provoke segment matching)
+			alpha_x = math.acos(seg.dist_x(keep_sign = True) / seg.dist())
+			alpha_y = math.asin(seg.dist_y(keep_sign = True) / seg.dist())
+			dist_x = int(math.cos(alpha_x) * dots_along_lines_dist)
+			dist_y = int(math.sin(alpha_y) * dots_along_lines_dist)
+
+			dot1b = (dot1[0] + dist_x, dot1[1] + dist_y)
+			# if len(intermediary_dots) == 0 or Segment(dot1b, intermediary_dots[0]).dist() > dots_along_lines_dist:
+			add_dots.append(dot1b)
+			extra_dots.append(dot1b)
+
+			dot2b = (dot2[0] - dist_x, dot2[1] - dist_y)
+			# if len(intermediary_dots) == 0 or Segment(dot2b, intermediary_dots[-1]).dist() > dots_along_lines_dist:
+			add_dots.append(dot2b)
+			extra_dots.append(dot2b)
+
+			for dot in sorted(add_dots, key = lambda dot: Segment(dot1, dot).dist()):
+				polygon = np.append(polygon, [[dot]], axis = 0)
+
+		# Re-merge nearby dots together
+		original_polygon = np.copy(polygon)
+		polygon = np.ndarray(shape = (0, 1, 2), dtype = int, order = 'F')
+
+		for i in range(len(original_polygon)):
+			j = (i + 1) % len(original_polygon)
+			dot1 = tuple(original_polygon[i][0])
+			dot2 = tuple(original_polygon[j][0])
+			seg = Segment(dot1, dot2)
+
+			# merge nearby dots together
+			if seg.dist_x() < min_dist_between_dots_x and seg.dist_y() < min_dist_between_dots_y:
+				intermediary_dots = [dot for dot in intermediary_dots if dot not in [dot1, dot2]]
+				extra_dots = [dot for dot in extra_dots if dot not in [dot1, dot2]]
+				original_polygon[j][0] = seg.center()
+				continue
+
+			polygon = np.append(polygon, [[dot1]], axis = 0)
+
+		Debug.draw_polygon(polygon)
+		Debug.draw_dots(intermediary_dots, Debug.colours['red'])
+		Debug.draw_dots(extra_dots, Debug.colours['yellow'])
+		Debug.add_image(f"Composed polygon {self} ({len(polygon)} dots, {len(intermediary_dots)} intermediary)")
+
+		# Find dots nearby one another
+		nearby_dots = []
+
+		for i in range(len(polygon) - min_hops):
+			for j in range(i + min_hops, len(polygon)):
+				dot1 = polygon[i][0]
+				dot2 = polygon[j][0]
+				seg = Segment(dot1, dot2)
+
+				if seg.dist_x() <= max_dist_x and seg.dist_y() <= max_dist_y:
+					nearby_dots.append([i, j])
+
+		if len(nearby_dots) == 0:
+			return None
+
+		Debug.draw_nearby_dots(polygon, nearby_dots)
+		Debug.add_image(f"Nearby dots ({len(nearby_dots)})")
+
+		splits = []
+		for dots in nearby_dots:
+			poly1len = len(polygon) - dots[1] + dots[0]
+			poly2len = dots[1] - dots[0]
+
+			# A panel should have at least three edges
+			if min(poly1len, poly2len) <= 2:
+				continue
+
+			# Construct two subpolygons by distributing the dots around our nearby dots
+			poly1 = np.zeros(shape = (poly1len, 1, 2), dtype = int)
+			poly2 = np.zeros(shape = (poly2len, 1, 2), dtype = int)
+
+			x = y = 0
+			for i in range(len(polygon)):
+				if i <= dots[0] or i > dots[1]:
+					poly1[x][0] = polygon[i]
+					x += 1
+				else:
+					poly2[y][0] = polygon[i]
+					y += 1
+
+			panel1 = Panel(self.page, polygon = poly1)
+			panel2 = Panel(self.page, polygon = poly2)
+
+			if panel1.is_small() or panel2.is_small():
+				continue
+
+			if panel1 == self or panel2 == self:
+				continue
+
+			if panel1.overlaps(panel2):
+				continue
+
+			split_segment = Segment.along_polygon(polygon, dots[0], dots[1])
+			split = Split(self, panel1, panel2, split_segment)
+			if split not in splits:
+				splits.append(split)
+
+		Debug.draw_segments([split.segment for split in splits], Debug.colours['red'], size = 2)
+		Debug.add_image(f"Splits ({len(splits)})")
+
+		splits = list(filter(lambda split: split.segments_coverage() > 50 / 100, splits))
+
+		if len(splits) == 0:
+			return None
+
+		# return the split that best matches segments (~panel edges)
+		best_split = max(splits, key = lambda split: split.covered_dist)
+
+		return best_split
+
+
+class Split:
+
+	def __init__(self, panel, subpanel1, subpanel2, split_segment):
+		self.panel = panel
+		self.subpanels = [subpanel1, subpanel2]
+		self.segment = split_segment
+
+		self.matching_segments = self.segment.intersect_all(self.panel.get_segments())
+		self.covered_dist = sum(map(lambda s: s.dist(), self.matching_segments))
+
+	def __eq__(self, other):
+		return self.segment == other.segment
+
+	def segments_coverage(self):
+		segment_dist = self.segment.dist()
+		return self.covered_dist / segment_dist if segment_dist else 0

lib/segment.py

@@ -0,0 +1,197 @@
+import math
+import numpy as np
+
+
+class Segment:
+
+	def __init__(self, a, b):
+		self.a = (int(a[0]), int(a[1]))
+		self.b = (int(b[0]), int(b[1]))
+
+		for dot in [self.a, self.b]:
+			if len(dot) != 2:
+				raise Exception(f"Creating a segment with more or less than two dots: Segment({a}, {b})")
+			if type(dot[0]) != int or type(dot[1]) != int:
+				raise Exception(f"Creating a segment with non-dots: Segment({a}, {b})")
+
+	def __str__(self):
+		return f"({self.a}, {self.b})"
+
+	def __eq__(self, other):
+		return any([
+			self.a == other.a and self.b == other.b,
+			self.a == other.b and self.b == other.a,
+		])
+
+	def dist(self):
+		return math.sqrt(self.dist_x()**2 + self.dist_y()**2)
+
+	def dist_x(self, keep_sign = False):
+		dist = self.b[0] - self.a[0]
+		return dist if keep_sign else abs(dist)
+
+	def dist_y(self, keep_sign = False):
+		dist = self.b[1] - self.a[1]
+		return dist if keep_sign else abs(dist)
+
+	def left(self):
+		return min(self.a[0], self.b[0])
+
+	def top(self):
+		return min(self.a[1], self.b[1])
+
+	def right(self):
+		return max(self.a[0], self.b[0])
+
+	def bottom(self):
+		return max(self.a[1], self.b[1])
+
+	def to_xyrb(self):
+		return [self.left(), self.top(), self.right(), self.bottom()]
+
+	def center(self):
+		return (
+			int(self.left() + self.dist_x() / 2),
+			int(self.top() + self.dist_y() / 2),
+		)
+
+	def may_contain(self, dot):
+		return all([
+			dot[0] >= self.left(),
+			dot[0] <= self.right(),
+			dot[1] >= self.top(),
+			dot[1] <= self.bottom(),
+		])
+
+	def intersect(self, other):
+		gutter = max(self.dist(), other.dist()) * 5 / 100
+
+		# angle too big ?
+		if not self.angle_ok_with(other):
+			return None
+
+		# from here, segments are almost parallel
+
+		# segments are apart ?
+		if any(
+			[
+				self.right() < other.left() - gutter,  # self left from other
+				self.left() > other.right() + gutter,  # self right from other
+				self.bottom() < other.top() - gutter,  # self above other
+				self.top() > other.bottom() + gutter,  # self below other
+			]
+		):
+			return None
+
+		projected_c = self.projected_point(other.a)
+		dist_c_to_ab = Segment(other.a, projected_c).dist()
+
+		projected_d = self.projected_point(other.b)
+		dist_d_to_ab = Segment(other.b, projected_d).dist()
+
+		# segments are a bit too far from each other
+		if (dist_c_to_ab + dist_d_to_ab) / 2 > gutter:
+			return None
+
+		# segments overlap, or one contains the other
+		#  A----B
+		#     C----D
+		# or
+		#  A------------B
+		#      C----D
+		sorted_dots = sorted([self.a, self.b, other.a, other.b], key = sum)
+		middle_dots = sorted_dots[1:3]
+		b, c = middle_dots
+
+		return Segment(b, c)
+
+	def union(self, other):
+		intersect = self.intersect(other)
+		if intersect is None:
+			return None
+
+		dots = [tuple(self.a), tuple(self.b), tuple(other.a), tuple(other.b)]
+		dots.remove(tuple(intersect.a))
+		dots.remove(tuple(intersect.b))
+		return Segment(dots[0], dots[1])
+
+	def angle_with(self, other):
+		return math.degrees(abs(self.angle() - other.angle()))
+
+	def angle_ok_with(self, other):
+		angle = self.angle_with(other)
+		return angle < 10 or abs(angle - 180) < 10
+
+	def angle(self):
+		return math.atan(self.dist_y() / self.dist_x()) if self.dist_x() != 0 else math.pi / 2
+
+	def intersect_all(self, segments):
+		segments_match = []
+		for segment in segments:
+			s3 = self.intersect(segment)
+			if s3 is not None:
+				segments_match.append(s3)
+
+		return Segment.union_all(segments_match)
+
+	@staticmethod
+	def along_polygon(polygon, i, j):
+		dot1 = polygon[i][0]
+		dot2 = polygon[j][0]
+		split_segment = Segment(dot1, dot2)
+
+		while True:
+			i = (i - 1) % len(polygon)
+			add_segment = Segment(polygon[i][0], polygon[(i + 1) % len(polygon)][0])
+			if add_segment.angle_ok_with(split_segment):
+				split_segment = Segment(add_segment.a, split_segment.b)
+			else:
+				break
+
+		while True:
+			j = (j + 1) % len(polygon)
+			add_segment = Segment(polygon[(j - 1) % len(polygon)][0], polygon[j][0])
+			if add_segment.angle_ok_with(split_segment):
+				split_segment = Segment(split_segment.a, add_segment.b)
+			else:
+				break
+
+		return split_segment
+
+	@staticmethod
+	def union_all(segments):
+		unioned_segments = True
+		while unioned_segments:
+			unioned_segments = False
+			dedup_segments = []
+			used = []
+			for i, s1 in enumerate(segments):
+				for s2 in segments[i + 1:]:
+					if s2 in used:
+						continue
+
+					s3 = s1.union(s2)
+					if s3 is not None:
+						unioned_segments = True
+						dedup_segments += [s3]
+						used.append(s1)
+						used.append(s2)
+						break
+
+				if s1 not in used:
+					dedup_segments += [s1]
+
+			segments = dedup_segments
+
+		return dedup_segments
+
+	def projected_point(self, p):
+		a = np.array(self.a)
+		b = np.array(self.b)
+		p = np.array(p)
+		ap = p - a
+		ab = b - a
+		if ab[0] == 0 and ab[1] == 0:
+			return a
+		result = a + np.dot(ap, ab) / np.dot(ab, ab) * ab
+		return (round(result[0]), round(result[1]))

requirements.txt

@@ -0,0 +1,3 @@
+opencv-python
+requests
+gradio

webui.bat

@@ -0,0 +1,162 @@
+@echo off
+
+:: The original source of the webui.bat file is stable-diffusion-webui
+:: Modified and enhanced by Gemini with features for venv management and requirements handling.
+
+:: --------- Configuration ---------
+set COMMANDLINE_ARGS=
+:: Define the name of the Launch application
+set APPLICATION_NAME=app.py
+:: Define the name of the virtual environment directory
+set VENV_NAME=venv
+:: Set to 1 to always attempt to update packages from requirements.txt on every launch
+set ALWAYS_UPDATE_REQS=1
+:: ---------------------------------
+
+
+:: Set PYTHON executable if not already defined
+if not defined PYTHON (set PYTHON=python)
+:: Set VENV_DIR using VENV_NAME if not already defined
+if not defined VENV_DIR (set "VENV_DIR=%~dp0%VENV_NAME%")
+
+mkdir tmp 2>NUL
+
+:: Check if Python is callable
+%PYTHON% -c "" >tmp/stdout.txt 2>tmp/stderr.txt
+if %ERRORLEVEL% == 0 goto :check_pip
+echo Couldn't launch python
+goto :show_stdout_stderr
+
+:check_pip
+:: Check if pip is available
+%PYTHON% -mpip --help >tmp/stdout.txt 2>tmp/stderr.txt
+if %ERRORLEVEL% == 0 goto :start_venv
+:: If pip is not available and PIP_INSTALLER_LOCATION is set, try to install pip
+if "%PIP_INSTALLER_LOCATION%" == "" goto :show_stdout_stderr
+%PYTHON% "%PIP_INSTALLER_LOCATION%" >tmp/stdout.txt 2>tmp/stderr.txt
+if %ERRORLEVEL% == 0 goto :start_venv
+echo Couldn't install pip
+goto :show_stdout_stderr
+
+:start_venv
+:: Skip venv creation/activation if VENV_DIR is explicitly set to "-"
+if ["%VENV_DIR%"] == ["-"] goto :skip_venv_entirely
+:: Skip venv creation/activation if SKIP_VENV is set to "1"
+if ["%SKIP_VENV%"] == ["1"] goto :skip_venv_entirely
+
+:: Check if the venv already exists by looking for Python.exe in its Scripts directory
+dir "%VENV_DIR%\Scripts\Python.exe" >tmp/stdout.txt 2>tmp/stderr.txt
+if %ERRORLEVEL% == 0 goto :activate_venv_and_maybe_update
+
+:: Venv does not exist, create it
+echo Virtual environment not found in "%VENV_DIR%". Creating a new one.
+for /f "delims=" %%i in ('CALL %PYTHON% -c "import sys; print(sys.executable)"') do set PYTHON_FULLNAME="%%i"
+echo Creating venv in directory %VENV_DIR% using python %PYTHON_FULLNAME%
+%PYTHON_FULLNAME% -m venv "%VENV_DIR%" >tmp/stdout.txt 2>tmp/stderr.txt
+if %ERRORLEVEL% NEQ 0 (
+    echo Unable to create venv in directory "%VENV_DIR%"
+    goto :show_stdout_stderr
+)
+echo Venv created.
+
+:: Install requirements for the first time if venv was just created
+:: This section handles the initial installation of packages from requirements.txt
+:: immediately after a new virtual environment is created.
+echo Checking for requirements.txt for initial setup in %~dp0
+if exist "%~dp0requirements.txt" (
+    echo Found requirements.txt, attempting to install for initial setup...
+    call "%VENV_DIR%\Scripts\activate.bat"
+    echo Installing packages from requirements.txt ^(initial setup^)...
+    "%VENV_DIR%\Scripts\python.exe" -m pip install -r "%~dp0requirements.txt"
+    if %ERRORLEVEL% NEQ 0 (
+        echo Failed to install requirements during initial setup. Please check the output above.
+        pause
+        goto :show_stdout_stderr_custom_pip_initial 
+    )
+    echo Initial requirements installed successfully.
+    call "%VENV_DIR%\Scripts\deactivate.bat"
+) else (
+    echo No requirements.txt found for initial setup, skipping package installation.
+)
+goto :activate_venv_and_maybe_update
+
+
+:activate_venv_and_maybe_update
+:: This label is reached if the venv exists or was just created.
+:: Set PYTHON to point to the venv's Python interpreter.
+set PYTHON="%VENV_DIR%\Scripts\Python.exe"
+echo Activating venv: %PYTHON%
+
+:: Always update requirements if ALWAYS_UPDATE_REQS is 1
+:: This section allows for updating packages from requirements.txt on every launch
+:: if the ALWAYS_UPDATE_REQS variable is set to 1.
+if defined ALWAYS_UPDATE_REQS (
+    if "%ALWAYS_UPDATE_REQS%"=="1" (
+        echo ALWAYS_UPDATE_REQS is enabled.
+        if exist "%~dp0requirements.txt" (
+            echo Attempting to update packages from requirements.txt...
+            REM No need to call activate.bat here again, PYTHON is already set to the venv's python
+            %PYTHON% -m pip install -r "%~dp0requirements.txt"
+            if %ERRORLEVEL% NEQ 0 (
+                echo Failed to update requirements. Please check the output above.
+                pause
+                goto :endofscript 
+            )
+            echo Requirements updated successfully.
+        ) else (
+            echo ALWAYS_UPDATE_REQS is enabled, but no requirements.txt found. Skipping update.
+        )
+    ) else (
+        echo ALWAYS_UPDATE_REQS is not enabled or not set to 1. Skipping routine update.
+    )
+)
+
+goto :launch
+
+:skip_venv_entirely
+:: This label is reached if venv usage is explicitly skipped.
+echo Skipping venv.
+goto :launch
+
+:launch
+:: Launch the main application
+echo Launching Web UI with arguments: %COMMANDLINE_ARGS% %*
+%PYTHON% %APPLICATION_NAME% %COMMANDLINE_ARGS% %*
+echo Launch finished.
+pause
+exit /b
+
+:show_stdout_stderr_custom_pip_initial
+:: Custom error handler for failures during the initial pip install process.
+echo.
+echo exit code ^(pip initial install^): %errorlevel%
+echo Errors during initial pip install. See output above.
+echo.
+echo Launch unsuccessful. Exiting.
+pause
+exit /b
+
+
+:show_stdout_stderr
+:: General error handler: displays stdout and stderr from the tmp directory.
+echo.
+echo exit code: %errorlevel%
+
+for /f %%i in ("tmp\stdout.txt") do set size=%%~zi
+if %size% equ 0 goto :show_stderr
+echo.
+echo stdout:
+type tmp\stdout.txt
+
+:show_stderr
+for /f %%i in ("tmp\stderr.txt") do set size=%%~zi
+if %size% equ 0 goto :endofscript
+echo.
+echo stderr:
+type tmp\stderr.txt
+
+:endofscript
+echo.
+echo Launch unsuccessful. Exiting.
+pause
+exit /b