sketchflow 0.1.0__tar.gz

sketchflow-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: sketchflow
+Version: 0.1.0
+Summary: A Python pencil sketch and outline processing library
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: opencv-python
+Provides-Extra: animation
+Requires-Dist: pygame; extra == "animation"
+
+# SketchFlow
+
+**SketchFlow** is a Python library for converting images into pencil sketches and artistic outlines.
+
+## Features
+
+- Convert images into pencil sketches.
+- Generate outline drawings.
+- Apply charcoal, soft, realistic, and detailed styles.
+- Customize image processing options.
+- Display and save processed images.
+- Animate the drawing process with optional Pygame support.
+
+## Installation
+
+```bash
+pip install sketchflow
+```
+
+For animation support:
+
+```bash
+pip install "sketchflow[animation]"
+```
+
+## Quick Start
+
+```python
+import sketchflow
+
+image = sketchflow.read("input.jpg")
+
+image.set_style("outline")
+
+image.show()
+```
+
+## Save the Result
+
+```python
+import sketchflow
+
+image = sketchflow.read("input.jpg")
+image.set_style("realistic")
+image.save("output.png")
+```
+
+## Available Styles
+
+- `realistic`
+- `outline`
+- `charcoal`
+- `soft`
+- `detailed`
+
+## Requirements
+
+- Python 3.10+
+- NumPy
+- OpenCV
+
+## License
+
+MIT License

sketchflow-0.1.0/README.md

@@ -0,0 +1,64 @@
+# SketchFlow
+
+**SketchFlow** is a Python library for converting images into pencil sketches and artistic outlines.
+
+## Features
+
+- Convert images into pencil sketches.
+- Generate outline drawings.
+- Apply charcoal, soft, realistic, and detailed styles.
+- Customize image processing options.
+- Display and save processed images.
+- Animate the drawing process with optional Pygame support.
+
+## Installation
+
+```bash
+pip install sketchflow
+```
+
+For animation support:
+
+```bash
+pip install "sketchflow[animation]"
+```
+
+## Quick Start
+
+```python
+import sketchflow
+
+image = sketchflow.read("input.jpg")
+
+image.set_style("outline")
+
+image.show()
+```
+
+## Save the Result
+
+```python
+import sketchflow
+
+image = sketchflow.read("input.jpg")
+image.set_style("realistic")
+image.save("output.png")
+```
+
+## Available Styles
+
+- `realistic`
+- `outline`
+- `charcoal`
+- `soft`
+- `detailed`
+
+## Requirements
+
+- Python 3.10+
+- NumPy
+- OpenCV
+
+## License
+
+MIT License

sketchflow-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sketchflow"
+version = "0.1.0"
+description = "A Python pencil sketch and outline processing library"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = [
+    "numpy",
+    "opencv-python"
+]
+
+[project.optional-dependencies]
+animation = ["pygame"]
+
+[tool.setuptools]
+py-modules = ["sketchflow"]

sketchflow-0.1.0/setup.cfg

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

sketchflow-0.1.0/sketchflow.egg-info/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: sketchflow
+Version: 0.1.0
+Summary: A Python pencil sketch and outline processing library
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: opencv-python
+Provides-Extra: animation
+Requires-Dist: pygame; extra == "animation"
+
+# SketchFlow
+
+**SketchFlow** is a Python library for converting images into pencil sketches and artistic outlines.
+
+## Features
+
+- Convert images into pencil sketches.
+- Generate outline drawings.
+- Apply charcoal, soft, realistic, and detailed styles.
+- Customize image processing options.
+- Display and save processed images.
+- Animate the drawing process with optional Pygame support.
+
+## Installation
+
+```bash
+pip install sketchflow
+```
+
+For animation support:
+
+```bash
+pip install "sketchflow[animation]"
+```
+
+## Quick Start
+
+```python
+import sketchflow
+
+image = sketchflow.read("input.jpg")
+
+image.set_style("outline")
+
+image.show()
+```
+
+## Save the Result
+
+```python
+import sketchflow
+
+image = sketchflow.read("input.jpg")
+image.set_style("realistic")
+image.save("output.png")
+```
+
+## Available Styles
+
+- `realistic`
+- `outline`
+- `charcoal`
+- `soft`
+- `detailed`
+
+## Requirements
+
+- Python 3.10+
+- NumPy
+- OpenCV
+
+## License
+
+MIT License

sketchflow-0.1.0/sketchflow.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+README.md
+pyproject.toml
+sketchflow.py
+sketchflow.egg-info/PKG-INFO
+sketchflow.egg-info/SOURCES.txt
+sketchflow.egg-info/dependency_links.txt
+sketchflow.egg-info/requires.txt
+sketchflow.egg-info/top_level.txt

sketchflow-0.1.0/sketchflow.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sketchflow-0.1.0/sketchflow.egg-info/requires.txt

@@ -0,0 +1,5 @@
+numpy
+opencv-python
+
+[animation]
+pygame

sketchflow-0.1.0/sketchflow.egg-info/top_level.txt

@@ -0,0 +1 @@
+sketchflow

sketchflow-0.1.0/sketchflow.py

@@ -0,0 +1,679 @@
+
+
+import os
+import sys
+import time
+import random
+import subprocess
+import platform
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+
+# ============================================================
+# DEFAULT SETTINGS
+# ============================================================
+
+MAX_WIDTH = 1500
+MAX_HEIGHT = 900
+
+PAPER_WIDTH = 1400
+PAPER_HEIGHT = 820
+
+FPS = 60
+PAPER_RGB = (250, 248, 242)
+WINDOW_BG = (43, 45, 48)
+HUD_COLOR = (45, 45, 45)
+HUD_SHADOW = (250, 248, 242)
+
+SEGMENTS_PER_FRAME = 12000
+MIN_SEGMENTS = 100
+MAX_SEGMENTS = 100000
+
+BLUR_KERNEL = 25
+DODGE_STRENGTH = 260.0
+CONTRAST_GAMMA = 1.25
+EDGE_BLEND = 0.30
+GRAIN_STRENGTH = 10
+PAPER_TEXTURE_STRENGTH = 0.14
+
+
+# ============================================================
+# IMAGE UTILITIES
+# ============================================================
+
+def load_image_bgr(path):
+    """Load an image, including paths containing Unicode characters."""
+    if not path:
+        raise ValueError("Please provide an image path.")
+
+    path = os.fspath(path)
+
+    if not os.path.isfile(path):
+        raise FileNotFoundError(f"Image not found: {path}")
+
+    data = np.fromfile(path, dtype=np.uint8)
+    image = cv2.imdecode(data, cv2.IMREAD_COLOR)
+
+    if image is None:
+        raise ValueError(
+            f"Could not decode image: {path}. "
+            "Please use a valid JPG, PNG, BMP or supported image."
+        )
+
+    return image
+
+
+def fit_to_box(image, max_width, max_height):
+    """Resize an image while preserving its aspect ratio."""
+    height, width = image.shape[:2]
+
+    scale = min(max_width / width, max_height / height)
+
+    new_width = max(1, round(width * scale))
+    new_height = max(1, round(height * scale))
+
+    interpolation = (
+        cv2.INTER_AREA if scale < 1 else cv2.INTER_CUBIC
+    )
+
+    return cv2.resize(
+        image,
+        (new_width, new_height),
+        interpolation=interpolation
+    )
+
+
+def make_paper_texture(shape, strength=PAPER_TEXTURE_STRENGTH):
+    """Create a subtle, repeatable paper texture."""
+    height, width = shape[:2]
+
+    rng = np.random.default_rng(42)
+
+    coarse = rng.normal(
+        0,
+        1,
+        (height // 8 + 1, width // 8 + 1)
+    ).astype(np.float32)
+
+    texture = cv2.resize(
+        coarse,
+        (width, height),
+        interpolation=cv2.INTER_CUBIC
+    )
+
+    texture = cv2.GaussianBlur(
+        texture,
+        (0, 0),
+        sigmaX=6,
+        sigmaY=6
+    )
+
+    texture = cv2.normalize(
+        texture,
+        None,
+        0,
+        1,
+        cv2.NORM_MINMAX
+    )
+
+    return 1.0 - strength * texture
+
+
+# ============================================================
+# PENCIL SKETCH ENGINE
+# ============================================================
+
+def pencil_sketch(
+    bgr,
+    blur_kernel=BLUR_KERNEL,
+    dodge_strength=DODGE_STRENGTH,
+    contrast_gamma=CONTRAST_GAMMA,
+    edge_blend=EDGE_BLEND,
+    grain_strength=GRAIN_STRENGTH,
+    paper_texture_strength=PAPER_TEXTURE_STRENGTH,
+):
+    """Convert a BGR image into a graphite-style pencil sketch."""
+
+    gray = cv2.cvtColor(bgr, cv2.COLOR_BGR2GRAY)
+    gray = cv2.GaussianBlur(gray, (3, 3), 0)
+
+    inverted = 255 - gray
+
+    kernel = max(1, int(blur_kernel))
+    if kernel % 2 == 0:
+        kernel += 1
+
+    blurred = cv2.GaussianBlur(
+        inverted,
+        (kernel, kernel),
+        0
+    )
+
+    blurred = np.maximum(blurred, 1)
+
+    dodge = np.clip(
+        gray.astype(np.float32) * dodge_strength / blurred,
+        0,
+        255
+    )
+
+    dodge = np.clip(
+        255.0 * np.power(dodge / 255.0, contrast_gamma),
+        0,
+        255
+    )
+
+    edges = cv2.Canny(gray, 35, 120).astype(np.float32)
+    edges = cv2.GaussianBlur(edges, (3, 3), 0)
+    edges = 255.0 - edges
+
+    blend = float(np.clip(edge_blend, 0, 1))
+
+    sketch = (
+        dodge * (1.0 - blend)
+        + edges * blend
+    )
+
+    rng = np.random.default_rng(7)
+
+    grain = rng.normal(
+        0,
+        max(0, grain_strength),
+        sketch.shape
+    ).astype(np.float32)
+
+    sketch = np.clip(sketch + grain, 0, 255)
+
+    texture = make_paper_texture(
+        sketch.shape,
+        float(np.clip(paper_texture_strength, 0, 1))
+    )
+
+    sketch = np.clip(sketch * texture, 0, 255)
+
+    return sketch.astype(np.uint8)
+
+
+# ============================================================
+# ANIMATION REVEAL ORDER
+# ============================================================
+
+def build_reveal_order(sketch):
+    """
+    Generate a randomized reveal sequence.
+    Darker regions tend to appear earlier in the animation.
+    """
+    height, width = sketch.shape
+
+    intensity = (255 - sketch).astype(np.float32)
+    intensity /= intensity.max() + 1e-6
+
+    rng = np.random.default_rng(123)
+
+    jitter = rng.normal(
+        0,
+        0.06,
+        intensity.shape
+    ).astype(np.float32)
+
+    score = np.clip(intensity + jitter, 0, 1)
+
+    band_count = 64
+
+    bands = np.clip(
+        (score * (band_count - 1)).astype(np.uint8),
+        0,
+        band_count - 1
+    )
+
+    # Avoid creating two full-size coordinate grids.
+    band_values = bands.ravel()
+    order_parts = []
+
+    for band in range(band_count - 1, -1, -1):
+        indices = np.flatnonzero(band_values == band)
+
+        if indices.size == 0:
+            continue
+
+        rng.shuffle(indices)
+
+        ys = indices // width
+        xs = indices % width
+
+        order_parts.append(
+            np.column_stack((ys, xs))
+        )
+
+    if order_parts:
+        order = np.concatenate(
+            order_parts
+        ).astype(np.int32, copy=False)
+    else:
+        order = np.empty((0, 2), dtype=np.int32)
+
+    return order
+
+
+# ============================================================
+# SKETCHFLOW IMAGE CLASS
+# ============================================================
+
+class SketchFlowImage:
+    """A processed sketch with preview, export and animation methods."""
+
+    def __init__(self, path):
+        self.path = os.fspath(path)
+
+        self.canvas_w = min(PAPER_WIDTH, MAX_WIDTH)
+        self.canvas_h = min(PAPER_HEIGHT, MAX_HEIGHT)
+
+        self.options = {
+            "blur_kernel": BLUR_KERNEL,
+            "dodge_strength": DODGE_STRENGTH,
+            "contrast_gamma": CONTRAST_GAMMA,
+            "edge_blend": EDGE_BLEND,
+            "grain_strength": GRAIN_STRENGTH,
+            "paper_texture_strength": PAPER_TEXTURE_STRENGTH,
+        }
+
+        self.orig_bgr = None
+        self.sketch = None
+        self.paper = None
+        self.order = None
+        self.revealed = None
+
+        self.img_h = 0
+        self.img_w = 0
+        self.offset_x = 0
+        self.offset_y = 0
+        self.total = 0
+        self.pos = 0
+
+        self._load()
+
+    def _load(self):
+        self.orig_bgr = fit_to_box(
+            load_image_bgr(self.path),
+            self.canvas_w,
+            self.canvas_h
+        )
+
+        self._process()
+
+    def _process(self):
+        """Regenerate sketch and animation data using current settings."""
+        self.sketch = pencil_sketch(
+            self.orig_bgr,
+            **self.options
+        )
+
+        self.img_h, self.img_w = self.sketch.shape
+
+        self.offset_x = (self.canvas_w - self.img_w) // 2
+        self.offset_y = (self.canvas_h - self.img_h) // 2
+
+        self.order = build_reveal_order(self.sketch)
+        self.total = len(self.order)
+        self.pos = self.total
+
+        self.revealed = np.ones(
+            (self.img_h, self.img_w),
+            dtype=bool
+        )
+
+        self.paper = self._create_paper()
+
+    def _require_image(self):
+        if self.sketch is None:
+            raise ValueError(
+                "No image loaded. Use sketchflow.read(path) first."
+            )
+
+    def _create_paper(self):
+        """Create a paper-coloured background with subtle texture."""
+        paper = np.empty(
+            (self.canvas_h, self.canvas_w, 3),
+            dtype=np.uint8
+        )
+
+        # OpenCV uses BGR channel order.
+        paper[:] = PAPER_RGB[::-1]
+
+        texture = make_paper_texture(
+            (self.canvas_h, self.canvas_w),
+            self.options["paper_texture_strength"]
+        )
+
+        return np.clip(
+            paper.astype(np.float32) * texture[..., None],
+            0,
+            255
+        ).astype(np.uint8)
+
+    def _generate_frame(self):
+        """Render the current animation state onto the paper."""
+        frame = self.paper.copy()
+
+        region = frame[
+            self.offset_y:self.offset_y + self.img_h,
+            self.offset_x:self.offset_x + self.img_w
+        ]
+
+        sketch_bgr = cv2.cvtColor(
+            self.sketch,
+            cv2.COLOR_GRAY2BGR
+        )
+
+        region[self.revealed] = sketch_bgr[self.revealed]
+
+        return frame
+
+    # --------------------------------------------------------
+    # PUBLIC API
+    # --------------------------------------------------------
+
+    def show(self):
+        """Show the complete sketch in an OpenCV window."""
+        self._require_image()
+
+        cv2.imshow(
+            "SketchFlow - Pencil Sketch",
+            self._generate_frame()
+        )
+
+        cv2.waitKey(0)
+        cv2.destroyAllWindows()
+
+        return self
+
+    def save(self, filename):
+        """
+        Save the pure sketch without paper padding.
+        The file extension determines the output format.
+        """
+        self._require_image()
+
+        filename = os.fspath(filename)
+        extension = Path(filename).suffix.lower()
+
+        if not extension:
+            raise ValueError(
+                "Provide a filename extension, such as .png or .jpg."
+            )
+
+        success, encoded = cv2.imencode(
+            extension,
+            self.sketch
+        )
+
+        if not success:
+            raise ValueError(
+                f"Unsupported output format: {extension}"
+            )
+
+        encoded.tofile(filename)
+
+        print(f"[SketchFlow] Saved: {os.path.abspath(filename)}")
+
+        return self
+
+    
+    def open(self, filename="sketchflow_preview.png"):
+        """Save the sketch and open it using the OS default image viewer."""
+        self._require_image()
+
+        # Save the sketch first
+        self.save(filename)
+
+        abs_path = os.path.abspath(os.fspath(filename))
+        system = platform.system()
+
+        try:
+            if system == "Windows":
+                os.startfile(abs_path)
+
+            elif system == "Darwin":
+                subprocess.Popen(["open", abs_path])
+
+            else:
+                subprocess.Popen(["xdg-open", abs_path])
+
+        except (OSError, subprocess.SubprocessError) as exc:
+            raise RuntimeError(
+                f"Could not open image with the system viewer: {exc}"
+            ) from exc
+
+        return self
+
+
+    def set_options(self, **kwargs):
+        """
+        Change sketch parameters and regenerate the image.
+
+        Supported:
+            blur_kernel
+            dodge_strength
+            contrast_gamma
+            edge_blend
+            grain_strength
+            paper_texture_strength
+        """
+        self._require_image()
+
+        unknown = set(kwargs) - set(self.options)
+
+        if unknown:
+            raise ValueError(
+                "Unknown option(s): "
+                + ", ".join(sorted(unknown))
+                + ". Supported options: "
+                + ", ".join(self.options)
+            )
+
+        updated = dict(self.options)
+        updated.update(kwargs)
+
+        if updated["dodge_strength"] <= 0:
+            raise ValueError("dodge_strength must be greater than 0.")
+
+        if updated["contrast_gamma"] <= 0:
+            raise ValueError("contrast_gamma must be greater than 0.")
+
+        if updated["blur_kernel"] < 1:
+            raise ValueError("blur_kernel must be at least 1.")
+
+        if updated["grain_strength"] < 0:
+            raise ValueError("grain_strength cannot be negative.")
+
+        if not 0 <= updated["edge_blend"] <= 1:
+            raise ValueError("edge_blend must be between 0 and 1.")
+
+        if not 0 <= updated["paper_texture_strength"] <= 1:
+            raise ValueError(
+                "paper_texture_strength must be between 0 and 1."
+            )
+
+        self.options = updated
+        self._process()
+
+        return self
+
+    def draw(self):
+        """Run the interactive Pygame pencil drawing animation."""
+        self._require_image()
+
+        try:
+            import pygame
+        except ImportError as exc:
+            raise ImportError(
+                "Animation requires pygame. Install it using: "
+                "pip install pygame"
+            ) from exc
+
+        self.pos = 0
+        self.revealed[:] = False
+
+        pygame.init()
+
+        try:
+            pygame.display.set_caption(
+                "SketchFlow - Pencil Drawing Animation"
+            )
+
+            screen = pygame.display.set_mode(
+                (self.canvas_w, self.canvas_h),
+                pygame.RESIZABLE
+            )
+
+            clock = pygame.time.Clock()
+            font = pygame.font.SysFont("consolas", 16, bold=True)
+
+            speed = SEGMENTS_PER_FRAME
+            paused = False
+            show_hud = True
+            running = True
+
+            while running:
+                for event in pygame.event.get():
+                    if event.type == pygame.QUIT:
+                        running = False
+
+                    elif event.type == pygame.KEYDOWN:
+                        if event.key == pygame.K_ESCAPE:
+                            running = False
+
+                        elif event.key == pygame.K_SPACE:
+                            paused = not paused
+
+                        elif event.key == pygame.K_r:
+                            self.pos = 0
+                            self.revealed[:] = False
+
+                        elif event.key == pygame.K_h:
+                            show_hud = not show_hud
+
+                        elif event.key in (
+                            pygame.K_PLUS,
+                            pygame.K_EQUALS,
+                            pygame.K_KP_PLUS
+                        ):
+                            speed = min(MAX_SEGMENTS, speed * 2)
+
+                        elif event.key in (
+                            pygame.K_MINUS,
+                            pygame.K_KP_MINUS
+                        ):
+                            speed = max(MIN_SEGMENTS, speed // 2)
+
+                        elif event.key == pygame.K_s:
+                            self.save("sketchflow_frame.png")
+
+                if not paused and self.pos < self.total:
+                    end = min(self.pos + speed, self.total)
+                    batch = self.order[self.pos:end]
+
+                    if batch.size:
+                        self.revealed[
+                            batch[:, 0],
+                            batch[:, 1]
+                        ] = True
+
+                    self.pos = end
+
+                frame = self._generate_frame()
+                rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
+
+                surface = pygame.surfarray.make_surface(
+                    rgb.swapaxes(0, 1)
+                )
+
+                screen.fill(WINDOW_BG)
+
+                win_w, win_h = screen.get_size()
+
+                # Fit the drawing to the available window area.
+                scale = min(
+                    win_w / self.canvas_w,
+                    win_h / self.canvas_h
+                )
+
+                display_w = max(1, int(self.canvas_w * scale))
+                display_h = max(1, int(self.canvas_h * scale))
+
+                if (display_w, display_h) != surface.get_size():
+                    surface = pygame.transform.smoothscale(
+                        surface,
+                        (display_w, display_h)
+                    )
+
+                x = (win_w - display_w) // 2
+                y = (win_h - display_h) // 2
+
+                screen.blit(surface, (x, y))
+
+                if show_hud:
+                    progress = (
+                        self.pos / max(self.total, 1)
+                    ) * 100
+
+                    status = (
+                        "PAUSED" if paused
+                        else "DONE" if self.pos >= self.total
+                        else "DRAWING"
+                    )
+
+                    lines = [
+                        f"Progress: {progress:5.1f}%",
+                        f"Speed: {speed:,} pixels/frame",
+                        f"State: {status}",
+                        "SPACE Pause | R Restart | H HUD | ESC Quit",
+                        "+/- Speed | S Save frame",
+                    ]
+
+                    for index, line in enumerate(lines):
+                        y_text = 10 + index * 21
+
+                        shadow = font.render(
+                            line, True, HUD_SHADOW
+                        )
+                        text_surface = font.render(
+                            line, True, HUD_COLOR
+                        )
+
+                        screen.blit(
+                            shadow,
+                            (13, y_text + 1)
+                        )
+                        screen.blit(
+                            text_surface,
+                            (12, y_text)
+                        )
+
+                pygame.display.flip()
+                clock.tick(FPS)
+
+        finally:
+            pygame.quit()
+
+        return self
+
+
+# ============================================================
+# SIMPLE LIBRARY ENTRY POINT
+# ============================================================
+
+def read(path):
+    """
+    Load an image and create a SketchFlowImage.
+
+    Example:
+        image = sketchflow.read("photo.jpg")
+    """
+    return SketchFlowImage(path)
+
+
+__all__ = ["read", "SketchFlowImage"]