silukman-image-vectorizer 1.0.5__tar.gz

silukman_image_vectorizer-1.0.5/LICENSE

@@ -0,0 +1,30 @@
+MIT License
+
+Copyright (c) 2026 Image Vectorizer Developers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+Third-Party Software Attributions:
+This application bundles and uses the following open-source libraries:
+- PySide6 (LGPL v3) - https://www.qt.io/qt-for-python
+- OpenCV Python (Apache License 2.0) - https://github.com/opencv/opencv-python
+- Pillow (HPND License) - https://github.com/python-pillow/Pillow
+- Numpy (BSD-3-Clause) - https://github.com/numpy/numpy
+- VTracer (MIT License) - https://github.com/visioncortex/vtracer

silukman_image_vectorizer-1.0.5/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: silukman-image-vectorizer
+Version: 1.0.5
+Summary: A PySide6 desktop application for high-quality raster-to-vector (SVG) conversion.
+Author: Lukman-ss
+License: MIT
+Project-URL: Homepage, https://github.com/lukman-ss/silukman_image_vectorizer
+Project-URL: Bug-Tracker, https://github.com/lukman-ss/silukman_image_vectorizer/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: X11 Applications :: Qt
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PySide6>=6.0.0
+Requires-Dist: pillow>=9.0.0
+Requires-Dist: opencv-python>=4.5.0
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: vtracer>=0.1.6
+Dynamic: license-file
+
+# Image Vectorizer
+
+![Image Vectorizer Hero](app/resources/hero_image.png)
+
+Last updated: 2026-06-05
+
+Image Vectorizer is a Python and PySide6 desktop application foundation for
+working with raster images. The current application supports local image import,
+original and processed previews, image metadata display, and an initial
+grayscale and threshold processing pipeline. It can also detect, simplify, and
+preview color-aware vector paths using configurable quality, background removal,
+and comparison controls. The desktop UI supports accessible Light, Dark, and
+System theme modes, single SVG export, and responsive batch SVG processing.
+
+## Install Dependencies
+
+```bash
+python -m pip install -r requirements.txt
+```
+
+## Run
+
+From the project root:
+
+```bash
+python main.py
+```
+
+Or use the development runner:
+
+```bash
+python scripts/run_dev.py
+```
+
+## Build & Packaging
+
+To bundle the application into a standalone desktop executable for distribution:
+
+### On Windows
+```cmd
+.venv\Scripts\python scripts\build_app.py
+```
+
+### On macOS / Linux
+```bash
+.venv/bin/python scripts/build_app.py
+```
+
+The script will automatically handle:
+1. Cleaning previous build output folders.
+2. Generating a clean build using the configuration from `image_vectorizer.spec`.
+3. Creating the standalone package in the `dist/` directory.
+4. Auto-detecting the application icon in `app/resources` using the native
+   platform icon format when available.
+5. Running a post-build cleanup on temporary compilation artifacts.
+6. Using PyInstaller from `.venv` or the system PATH.
+
+## Documentation
+
+Project documentation is available in `docs/`.
+
+- `docs/architecture/` for system and pipeline architecture.
+- `docs/developer/` for setup, verification, benchmark, and packaging guides.
+- `docs/product/` for project overview, glossary, status, and roadmap.
+- `docs/user/` for UI workflow, performance tips, and troubleshooting.
+
+## CI/CD & Release Automation
+
+We use GitHub Actions to automate desktop application builds, version tagging, and release publishing.
+
+### 1. CI Build Workflow (`build.yml`)
+- Triggered automatically on push or pull requests to the `main` branch, or via manual run (`workflow_dispatch`).
+- Builds standalone application packages for Windows, macOS, and Linux in parallel.
+- Uploads the build outputs as workflow artifacts (`Image-Vectorizer-Windows`, `Image-Vectorizer-macOS`, `Image-Vectorizer-Linux`).
+
+### 2. Manual Tag Workflow (`create_tag.yml`)
+- Triggered manually from the Actions tab.
+- Accepts a semantic version tag (e.g. `v1.0.0`) and pushes it to the repository after validating that the format matches `v*.*.*` and the tag does not already exist.
+
+### 3. Release Publication Workflow (`release.yml`)
+- Automatically triggered when a new version tag (`v*.*.*`) is pushed.
+- Re-builds the application packages for all target platforms, compiles them, and attaches the archived builds to a newly created GitHub Release using the version number as the release name.
+
+### 4. PyPI Publishing Workflow (`publish_pypi.yml`)
+- Triggered automatically when a new version tag (`v*.*.*`) is pushed, or via manual run (`workflow_dispatch`).
+- Compiles the source distribution and wheel packages, validates package metadata using `twine`, and publishes the package to PyPI under the name `silukman-image-vectorizer` using the repository secret `PYPI_API_TOKEN`.
+
+### Difference Between Manual and CI Build
+- **Manual Build**: Runs locally via `scripts/build_app.py`. Uses local system libraries, virtual environment compilers, and target architecture. Best for fast local verification.
+- **CI Build**: Runs inside clean, isolated containers on GitHub-hosted runners (Windows, macOS, Linux). Guarantees reproducible builds and doesn't pollute local environments.
+
+

silukman_image_vectorizer-1.0.5/README.md

@@ -0,0 +1,92 @@
+# Image Vectorizer
+
+![Image Vectorizer Hero](app/resources/hero_image.png)
+
+Last updated: 2026-06-05
+
+Image Vectorizer is a Python and PySide6 desktop application foundation for
+working with raster images. The current application supports local image import,
+original and processed previews, image metadata display, and an initial
+grayscale and threshold processing pipeline. It can also detect, simplify, and
+preview color-aware vector paths using configurable quality, background removal,
+and comparison controls. The desktop UI supports accessible Light, Dark, and
+System theme modes, single SVG export, and responsive batch SVG processing.
+
+## Install Dependencies
+
+```bash
+python -m pip install -r requirements.txt
+```
+
+## Run
+
+From the project root:
+
+```bash
+python main.py
+```
+
+Or use the development runner:
+
+```bash
+python scripts/run_dev.py
+```
+
+## Build & Packaging
+
+To bundle the application into a standalone desktop executable for distribution:
+
+### On Windows
+```cmd
+.venv\Scripts\python scripts\build_app.py
+```
+
+### On macOS / Linux
+```bash
+.venv/bin/python scripts/build_app.py
+```
+
+The script will automatically handle:
+1. Cleaning previous build output folders.
+2. Generating a clean build using the configuration from `image_vectorizer.spec`.
+3. Creating the standalone package in the `dist/` directory.
+4. Auto-detecting the application icon in `app/resources` using the native
+   platform icon format when available.
+5. Running a post-build cleanup on temporary compilation artifacts.
+6. Using PyInstaller from `.venv` or the system PATH.
+
+## Documentation
+
+Project documentation is available in `docs/`.
+
+- `docs/architecture/` for system and pipeline architecture.
+- `docs/developer/` for setup, verification, benchmark, and packaging guides.
+- `docs/product/` for project overview, glossary, status, and roadmap.
+- `docs/user/` for UI workflow, performance tips, and troubleshooting.
+
+## CI/CD & Release Automation
+
+We use GitHub Actions to automate desktop application builds, version tagging, and release publishing.
+
+### 1. CI Build Workflow (`build.yml`)
+- Triggered automatically on push or pull requests to the `main` branch, or via manual run (`workflow_dispatch`).
+- Builds standalone application packages for Windows, macOS, and Linux in parallel.
+- Uploads the build outputs as workflow artifacts (`Image-Vectorizer-Windows`, `Image-Vectorizer-macOS`, `Image-Vectorizer-Linux`).
+
+### 2. Manual Tag Workflow (`create_tag.yml`)
+- Triggered manually from the Actions tab.
+- Accepts a semantic version tag (e.g. `v1.0.0`) and pushes it to the repository after validating that the format matches `v*.*.*` and the tag does not already exist.
+
+### 3. Release Publication Workflow (`release.yml`)
+- Automatically triggered when a new version tag (`v*.*.*`) is pushed.
+- Re-builds the application packages for all target platforms, compiles them, and attaches the archived builds to a newly created GitHub Release using the version number as the release name.
+
+### 4. PyPI Publishing Workflow (`publish_pypi.yml`)
+- Triggered automatically when a new version tag (`v*.*.*`) is pushed, or via manual run (`workflow_dispatch`).
+- Compiles the source distribution and wheel packages, validates package metadata using `twine`, and publishes the package to PyPI under the name `silukman-image-vectorizer` using the repository secret `PYPI_API_TOKEN`.
+
+### Difference Between Manual and CI Build
+- **Manual Build**: Runs locally via `scripts/build_app.py`. Uses local system libraries, virtual environment compilers, and target architecture. Best for fast local verification.
+- **CI Build**: Runs inside clean, isolated containers on GitHub-hosted runners (Windows, macOS, Linux). Guarantees reproducible builds and doesn't pollute local environments.
+
+

silukman_image_vectorizer-1.0.5/app/__init__.py

@@ -0,0 +1 @@
+"""Image Vectorizer application package."""

silukman_image_vectorizer-1.0.5/app/cli.py

@@ -0,0 +1,73 @@
+import sys
+import traceback
+
+
+def _show_startup_error(title: str, message: str) -> None:
+    try:
+        from PySide6.QtWidgets import QApplication, QMessageBox
+
+        app = QApplication.instance()
+        created = False
+        if app is None:
+            app = QApplication(sys.argv)
+            created = True
+        QMessageBox.critical(None, title, message)
+        if created:
+            app.processEvents()
+    except Exception:
+        pass
+
+
+def _validate_runtime_environment() -> None:
+    from app.core.paths import RESOURCES_DIR
+
+    required_resources = [
+        RESOURCES_DIR,
+        RESOURCES_DIR / "icon.png",
+        RESOURCES_DIR / "hero_image.png",
+    ]
+    missing_resources = [
+        str(path)
+        for path in required_resources
+        if not path.exists()
+    ]
+    if missing_resources:
+        missing = "\n".join(missing_resources)
+        raise RuntimeError(f"Missing packaged resource(s):\n{missing}")
+
+
+def main() -> int:
+    try:
+        from PySide6.QtWidgets import QApplication
+
+        from app.main_window import MainWindow
+
+        _validate_runtime_environment()
+
+        application = QApplication(sys.argv)
+        application.setApplicationName("Image Vectorizer")
+
+        window = MainWindow()
+        window.show()
+        return application.exec()
+    except ImportError as error:
+        msg = (
+            f"Failed to start Image Vectorizer: missing dependency ({error}).\n\n"
+            "Please ensure all dependencies are installed correctly."
+        )
+        print(msg, file=sys.stderr)
+        _show_startup_error("Dependency Error", msg)
+        return 1
+    except Exception as error:
+        print(f"Failed to start Image Vectorizer: {error}", file=sys.stderr)
+        traceback.print_exc()
+
+        _show_startup_error(
+            "Startup Error",
+            f"Image Vectorizer could not start:\n{error}",
+        )
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

silukman_image_vectorizer-1.0.5/app/config/__init__.py

@@ -0,0 +1 @@
+"""Application configuration package."""

silukman_image_vectorizer-1.0.5/app/config/settings.py

@@ -0,0 +1,40 @@
+from dataclasses import dataclass, field
+
+DEFAULT_WINDOW_WIDTH = 1200
+DEFAULT_WINDOW_HEIGHT = 760
+
+@dataclass
+class VTracerSettings:
+    """VTracer-specific settings."""
+    colormode: str = "color"          # color / binary
+    hierarchical: str = "stacked"     # stacked / cutout
+    mode: str = "spline"              # spline / polygon / none
+    filter_speckle: int = 4           # speckle size filter
+    color_precision: int = 6          # 1 to 8 (safer default max 6 to prevent 128 colors)
+    layer_difference: int = 16        # color difference threshold
+    corner_threshold: int = 60        # angle threshold for corners
+    length_threshold: float = 3.5     # curve length threshold
+    max_iterations: int = 16          # optimizer max iteration count
+    path_precision: int = 8           # SVG path output decimal precision
+
+@dataclass
+class VectorizationSettings:
+    """Settings that control the vectorization process."""
+    # Legacy OpenCV settings
+    min_area: float = 100.0          # Minimum contour area to keep (pixels)
+    approx_tolerance: float = 2.0    # Douglas-Peucker epsilon for approximation
+    smoothing_enabled: bool = False  # Whether to apply Gaussian smoothing pre-detection
+    invert: bool = False             # Invert binary image before detection
+    color_mode: str = "Unlimited colors"
+    color_count: int = 8
+    preserve_edges: bool = False
+    remove_background: bool = False
+    bg_tolerance: float = 20.0
+    threshold_val: int = 127         # Threshold value for legacy engine
+    palette_replacements: list[tuple[tuple[int, int, int], tuple[int, int, int]]] = field(default_factory=list)
+
+    # Active engine type: "VTracer" or "OpenCV Legacy"
+    engine_type: str = "VTracer"
+
+    # VTracer settings object
+    vtracer: VTracerSettings = field(default_factory=VTracerSettings)

silukman_image_vectorizer-1.0.5/app/core/__init__.py

@@ -0,0 +1 @@
+"""Core application utilities."""

silukman_image_vectorizer-1.0.5/app/core/constants.py

@@ -0,0 +1,6 @@
+APP_VERSION = "1.0.5"
+APPLICATION_TITLE = f"Image Vectorizer v{APP_VERSION}"
+SIDEBAR_TITLE = "Sidebar"
+PREVIEW_AREA_TITLE = "Preview Area"
+CONTROL_PANEL_TITLE = "Control Panel"
+STATUS_READY = "Ready"

silukman_image_vectorizer-1.0.5/app/core/image_pipeline.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import cv2
+import numpy as np
+from PySide6.QtGui import QImage
+
+
+def process_image_pipeline(file_path: str, threshold_val: int) -> tuple[QImage, np.ndarray]:
+    """Run the image processing pipeline.
+
+    Stages:
+    1. Load image and convert to grayscale.
+    2. Apply binary thresholding.
+    """
+    if not isinstance(threshold_val, int) or isinstance(threshold_val, bool):
+        raise ValueError("Threshold value must be an integer.")
+    if not 0 <= threshold_val <= 255:
+        raise ValueError("Threshold value must be between 0 and 255.")
+
+    img = cv2.imread(file_path, cv2.IMREAD_UNCHANGED)
+    if img is None:
+        raise ValueError("Failed to load image for processing pipeline.")
+
+    if img.ndim == 2:
+        gray = img
+    elif img.shape[2] == 4:
+        gray = cv2.cvtColor(img, cv2.COLOR_BGRA2GRAY)
+    elif img.shape[2] == 3:
+        gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+    else:
+        raise ValueError("Unsupported image channel layout.")
+
+    # Stage 2: Threshold processing
+    _, thresholded = cv2.threshold(gray, threshold_val, 255, cv2.THRESH_BINARY)
+
+    # Convert grayscale/binary numpy array to QImage
+    height, width = thresholded.shape
+    thresholded = np.ascontiguousarray(thresholded)
+    bytes_per_line = thresholded.strides[0]
+    
+    # QImage.Format_Grayscale8 is appropriate for single-channel 8-bit image data
+    q_image = QImage(
+        thresholded.data,
+        width,
+        height,
+        bytes_per_line,
+        QImage.Format.Format_Grayscale8
+    )
+
+    # Create a copy to ensure memory ownership of the pixel data is transferred to QImage
+    return q_image.copy(), thresholded

silukman_image_vectorizer-1.0.5/app/core/paths.py

@@ -0,0 +1,13 @@
+import sys
+from pathlib import Path
+
+
+if getattr(sys, "frozen", False) and hasattr(sys, "_MEIPASS"):
+    PROJECT_ROOT = Path(sys._MEIPASS)
+else:
+    PROJECT_ROOT = Path(__file__).resolve().parents[2]
+
+APP_DIR = PROJECT_ROOT / "app"
+RESOURCES_DIR = APP_DIR / "resources"
+DOCS_DIR = PROJECT_ROOT / "docs"
+SCRIPTS_DIR = PROJECT_ROOT / "scripts"