missing artifacts

added #[derive(Clone, Debug)]

.gitattributes

@@ -0,0 +1 @@
+docs/** linguist-generated

.github/workflows/python.yml

@@ -0,0 +1,183 @@
+# This file is autogenerated by maturin v1.11.5
+# To update, run
+#
+#    maturin generate-ci github
+#
+name: Python
+
+on:
+  push:
+    tags:
+      - '*'
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  linux:
+    runs-on: ${{ matrix.platform.runner }}
+    strategy:
+      matrix:
+        platform:
+          - runner: ubuntu-22.04
+            target: x86_64
+          - runner: ubuntu-22.04
+            target: x86
+          - runner: ubuntu-22.04
+            target: aarch64
+          - runner: ubuntu-22.04
+            target: armv7
+          - runner: ubuntu-22.04
+            target: s390x
+          - runner: ubuntu-22.04
+            target: ppc64le
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist --find-interpreter --manifest-path cmdapp/Cargo.toml
+          sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
+          manylinux: auto
+      - name: Upload wheels
+        uses: actions/upload-artifact@v5
+        with:
+          name: wheels-linux-${{ matrix.platform.target }}
+          path: dist
+
+  musllinux:
+    runs-on: ${{ matrix.platform.runner }}
+    strategy:
+      matrix:
+        platform:
+          - runner: ubuntu-22.04
+            target: x86_64
+          - runner: ubuntu-22.04
+            target: x86
+          - runner: ubuntu-22.04
+            target: aarch64
+          - runner: ubuntu-22.04
+            target: armv7
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist --find-interpreter --manifest-path cmdapp/Cargo.toml
+          sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
+          manylinux: musllinux_1_2
+      - name: Upload wheels
+        uses: actions/upload-artifact@v5
+        with:
+          name: wheels-musllinux-${{ matrix.platform.target }}
+          path: dist
+
+  windows:
+    runs-on: ${{ matrix.platform.runner }}
+    strategy:
+      matrix:
+        platform:
+          - runner: windows-latest
+            target: x64
+            python_arch: x64
+          - runner: windows-latest
+            target: x86
+            python_arch: x86
+          - runner: windows-11-arm
+            target: aarch64
+            python_arch: arm64
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.13
+          architecture: ${{ matrix.platform.python_arch }}
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist --find-interpreter --manifest-path cmdapp/Cargo.toml
+          sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
+      - name: Upload wheels
+        uses: actions/upload-artifact@v5
+        with:
+          name: wheels-windows-${{ matrix.platform.target }}
+          path: dist
+
+  macos:
+    runs-on: ${{ matrix.platform.runner }}
+    strategy:
+      matrix:
+        platform:
+          - runner: macos-15-intel
+            target: x86_64
+          - runner: macos-latest
+            target: aarch64
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist --find-interpreter --manifest-path cmdapp/Cargo.toml
+          sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
+      - name: Upload wheels
+        uses: actions/upload-artifact@v5
+        with:
+          name: wheels-macos-${{ matrix.platform.target }}
+          path: dist
+
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Build sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist --manifest-path cmdapp/Cargo.toml
+      - name: Upload sdist
+        uses: actions/upload-artifact@v5
+        with:
+          name: wheels-sdist
+          path: dist
+
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    # Specifying a GitHub environment is optional, but strongly encouraged
+    environment: python
+    if: ${{ startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch' }}
+    needs: [linux, musllinux, windows, macos, sdist]
+    permissions:
+      # Use to sign the release artifacts
+      id-token: write
+      # Used to upload release artifacts
+      contents: write
+      # Used to generate artifact attestation
+      attestations: write
+    steps:
+      - uses: actions/download-artifact@v6
+      - name: Generate artifact attestation
+        uses: actions/attest-build-provenance@v3
+        with:
+          subject-path: 'wheels-*/*'
+      - name: Install uv
+        if: ${{ startsWith(github.ref, 'refs/tags/') }}
+        uses: astral-sh/setup-uv@v7
+      - name: Publish to PyPI
+        if: ${{ startsWith(github.ref, 'refs/tags/') }}
+        run: uv publish 'wheels-*/*'

.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  release:
+    strategy:
+      matrix:
+        include:
+          - target: aarch64-unknown-linux-musl
+            os: ubuntu-latest
+          - target: x86_64-unknown-linux-musl
+            os: ubuntu-latest
+          - target: aarch64-apple-darwin
+            os: macos-latest
+          - target: x86_64-apple-darwin
+            os: macos-latest
+          - target: x86_64-pc-windows-msvc
+            os: windows-latest
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: taiki-e/upload-rust-binary-action@v1
+        with:
+          bin: vtracer
+          target: ${{ matrix.target }}
+          # (required) GitHub token for uploading assets to GitHub Releases.
+          token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/rust.yml

@@ -0,0 +1,35 @@
+name: Rust
+
+on:
+  pull_request:
+    paths-ignore:
+      - '**.md'
+      - '.github/ISSUE_TEMPLATE/**'
+  push:
+    paths-ignore:
+      - '**.md'
+      - '.github/ISSUE_TEMPLATE/**'
+    branches:
+      - master
+      - 0.*.x
+      - pr/**/ci
+      - ci-*
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref || github.run_id }}
+  cancel-in-progress: true
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Build
+      run: cargo build --verbose
+    - name: Run tests
+      run: cargo test --verbose

CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/)
+and this project adheres to [Semantic Versioning](http://semver.org/).
+
+## 0.6.12 - 2026-02-04
+
+* Python Binding
+
+## 0.6.5 - 2025-10-17
+
+* Update `fastrand` to `2.3`
+
+## 0.6.4 - 2024-03-29
+
+* Update `visioncortex` version to `0.8.8`
+
+## 0.6.3 - 2023-11-21
+
+* New converter API https://github.com/visioncortex/vtracer/pull/59
+
+## 0.6.1 - 2023-09-23
+
+* Fixed "The two lines are parallel!"
+
+### Python Binding
+
+Thanks to the contribution of [@etjones](https://github.com/etjones), we now have an official Python binding! https://github.com/visioncortex/vtracer/pull/55
+
+https://pypi.org/project/vtracer/0.6.10/
+
+## 0.5.0 - 2022-10-09
+
+* Handle transparent png images (cli) https://github.com/visioncortex/vtracer/pull/23
+
+## 0.4.0 - 2021-07-23
+
+* SVG path string numeric precision
+
+## 0.3.0 - 2021-01-24
+
+* Added cutout mode
+
+## 0.2.0 - 2020-11-15
+
+* Use relative & closed paths
+
+## 0.1.1 - 2020-11-01
+
+* SVG namespace
+
+## 0.1.0 - 2020-10-31
+
+* Initial release

Cargo.toml

@@ -3,4 +3,5 @@
 members = [
     "cmdapp",
     "webapp",
-]
+]
+resolver = "2"

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2020 Tsang Hao Fung
+Copyright (c) 2024 TSANG, Hao Fung
 
 Permission is hereby granted, free of charge, to any
 person obtaining a copy of this software and associated

README.md

@@ -1,79 +1,157 @@
 <div align="center">
 
   <img src="docs/images/visioncortex-banner.png">
-  <h1>visioncortex VTracer</h1>
+  <h1>VTracer</h1>
 
   <p>
-    <strong>Raster to Vector Graphics Converter built on top of visioncortex</strong>
+    <strong>Raster to Vector Graphics Converter</strong>
   </p>
 
   <h3>
-    <a href="//www.visioncortex.org/vtracer-docs">Document</a>
+    <a href="https://www.visioncortex.org/vtracer-docs">Article</a>
     <span> | </span>
-    <a href="//www.visioncortex.org/vtracer/">Demo</a>
+    <a href="https://www.visioncortex.org/vtracer/">Web App</a>
     <span> | </span>
-    <a href="//github.com/visioncortex/vtracer/releases/latest">Download</a>
+    <a href="https://github.com/visioncortex/vtracer/releases">Download</a>
   </h3>
 
-  <sub>Built with 🦀 by <a href="//www.visioncortex.org/">The Vision Cortex Research Group</a></sub>
+  <sub>Built with 🦀 by <a href="https://www.visioncortex.org/">The Vision Cortex Research Group</a></sub>
 </div>
 
 ## Introduction
 
 visioncortex VTracer is an open source software to convert raster images (like jpg & png) into vector graphics (svg). It can vectorize graphics and photographs and trace the curves to output compact vector files.
 
-Comparing to [Potrace]() which only accept binarized inputs (Black & White pixmap), VTracer has an image processing pipeline which can handle colored high resolution scans.
+Comparing to [Potrace](http://potrace.sourceforge.net/) which only accept binarized inputs (Black & White pixmap), VTracer has an image processing pipeline which can handle colored high resolution scans. tl;dr: Potrace uses a `O(n^2)` fitting algorithm, whereas `vtracer` is entirely `O(n)`.
 
-Comparing to Adobe Illustrator's Live Trace, VTracer's output is much more compact (less shapes) as we adopt a stacking strategy and avoid producing shapes with holes.
+Comparing to Adobe Illustrator's [Image Trace](https://helpx.adobe.com/illustrator/using/image-trace.html), VTracer's output is much more compact (less shapes) as we adopt a stacking strategy and avoid producing shapes with holes.
 
-A technical description of the algorithm is on [visioncortex.org/vtracer-docs](//www.visioncortex.org/vtracer-docs).
+VTracer is originally designed for processing high resolution scans of historic blueprints up to gigapixels. At the same time, VTracer can also handle low resolution pixel art, simulating `image-rendering: pixelated` for retro game artworks.
+
+Technical descriptions of the [tracing algorithm](https://www.visioncortex.org/vtracer-docs) and [clustering algorithm](https://www.visioncortex.org/impression-docs).
 
 ## Web App
 
-VTracer and its [core library](//github.com/visioncortex/visioncortex) is implemented in [Rust](//www.rust-lang.org/). It provides us a solid foundation to develop robust and efficient algorithms and easily bring it to interactive applications. The webapp is a perfect showcase of the capability of the Rust + HTML5 platform.
+VTracer and its [core library](//github.com/visioncortex/visioncortex) is implemented in [Rust](//www.rust-lang.org/). It provides us a solid foundation to develop robust and efficient algorithms and easily bring it to interactive applications. The webapp is a perfect showcase of the capability of the Rust + wasm platform.
 
 ![screenshot](docs/images/screenshot-01.png)
 
 ![screenshot](docs/images/screenshot-02.png)
 
-## Command Line
-```
-visioncortex VTracer                                                                                                      
-A cmd app to convert images into vector graphics.                                                                         
-                                                                                                                          
-USAGE:                                                                                                                    
-    vtracer [OPTIONS] --input <input> --output <output>                                                                   
-                                                                                                                          
-FLAGS:                                                                                                                    
-    -h, --help       Prints help information                                                                              
-    -V, --version    Prints version information                                                                           
-                                                                                                                          
-OPTIONS:                                                                                                                  
-        --colormode <color_mode>                 True color image `color` (default) or Binary image `bw`                  
-    -p, --color_precision <color_precision>      Number of significant bits to use in an RGB channel                      
-    -c, --corner_threshold <corner_threshold>    Minimum momentary angle (degree) to be considered a corner               
-    -f, --filter_speckle <filter_speckle>        Discard patches smaller than X px in size                                
-    -g, --gradient_step <gradient_step>          Color difference between gradient layers                                 
-    -i, --input <input>                          Path to input raster image                                               
-    -m, --mode <mode>                            Curver fitting mode `pixel`, `polygon`, `spline`                         
-    -o, --output <output>                        Path to output vector graphics                                           
-        --preset <preset>                        Use one of the preset configs `bw`, `poster`, `photo`                    
-    -l, --segment_length <segment_length>                                                                                 
-            Perform iterative subdivide smooth until all segments are shorter than this length                            
-                                                                                                                          
-    -s, --splice_threshold <splice_threshold>    Minimum angle displacement (degree) to splice a spline                   
+## Cmd App
+
+```sh
+visioncortex VTracer 0.6.0
+A cmd app to convert images into vector graphics.
+
+USAGE:
+    vtracer [OPTIONS] --input <input> --output <output>
+
+FLAGS:
+    -h, --help       Prints help information
+    -V, --version    Prints version information
+
+OPTIONS:
+        --colormode <color_mode>                 True color image `color` (default) or Binary image `bw`
+    -p, --color_precision <color_precision>      Number of significant bits to use in an RGB channel
+    -c, --corner_threshold <corner_threshold>    Minimum momentary angle (degree) to be considered a corner
+    -f, --filter_speckle <filter_speckle>        Discard patches smaller than X px in size
+    -g, --gradient_step <gradient_step>          Color difference between gradient layers
+        --hierarchical <hierarchical>
+            Hierarchical clustering `stacked` (default) or non-stacked `cutout`. Only applies to color mode.
+
+    -i, --input <input>                          Path to input raster image
+    -m, --mode <mode>                            Curver fitting mode `pixel`, `polygon`, `spline`
+    -o, --output <output>                        Path to output vector graphics
+        --path_precision <path_precision>        Number of decimal places to use in path string
+        --preset <preset>                        Use one of the preset configs `bw`, `poster`, `photo`
+    -l, --segment_length <segment_length>
+            Perform iterative subdivide smooth until all segments are shorter than this length
+
+    -s, --splice_threshold <splice_threshold>    Minimum angle displacement (degree) to splice a spline
 ```
 
-### Usage
+## Downloads
+
+You can download pre-built binaries from [Releases](https://github.com/visioncortex/vtracer/releases).
+
+You can also install the program from source from [crates.io/vtracer](https://crates.io/crates/vtracer):
+
+```sh
+cargo install vtracer
 ```
+
+> You are strongly advised to not download from any other third-party sources 
+
+### Usage
+
+```sh
 ./vtracer --input input.jpg --output output.svg
 ```
 
-## Library
+### Rust Library
 
-The library can be found on [crates.io/vtracer](//crates.io/crates/vtracer).
+You can install [`vtracer`](https://crates.io/crates/vtracer) as a Rust library.
 
-### Install
+```sh
+cargo add vtracer
 ```
-vtracer = "0.1.0"
+
+### Python Library
+
+Since `0.6`, [`vtracer`](https://pypi.org/project/vtracer/) is also packaged as Python native extensions, thanks to the awesome [pyo3](https://github.com/PyO3/pyo3) project.
+
+```sh
+pip install vtracer
 ```
+
+## In the wild
+
+VTracer is used by the following products (open a PR to add yours):
+
+<table>
+  <tbody>
+    <tr>
+      <td><a href="https://logo.aliyun.com/logo#/name"><img src="docs/images/aliyun-logo.png" width="250"/></a>
+      <br>Smart logo design
+      </td>
+      <td></td>
+    </tr>
+  </tbody>
+</table>
+
+## Citations
+
+VTracer has since been cited by a few academic papers in computer graphics / vision research. Please kindly let us know if you have cited our work:
+
++ SKILL 2023 [Framework to Vectorize Digital Artworks for Physical Fabrication based on Geometric Stylization Techniques](https://www.researchgate.net/publication/374448489_Framework_to_Vectorize_Digital_Artworks_for_Physical_Fabrication_based_on_Geometric_Stylization_Techniques)
++ arXiv 2023 [Image Vectorization: a Review](https://arxiv.org/abs/2306.06441)
++ arXiv 2023 [StarVector: Generating Scalable Vector Graphics Code from Images](https://arxiv.org/abs/2312.11556)
++ arXiv 2024 [Text-Based Reasoning About Vector Graphics](https://arxiv.org/abs/2404.06479)
++ arXiv 2024 [Delving into LLMs' visual understanding ability using SVG to bridge image and text](https://openreview.net/pdf?id=pwlm6Po61I)
+
+## How did VTracer come about?
+
+> The following content is an excerpt from my [unpublished memoir](https://github.com/visioncortex/memoir).
+
+At my teenage, two open source projects in the vector graphics space inspired me the most: Potrace and Anti-Grain Geometry (AGG).
+
+Many years later, in 2020, I was developing a video processing engine. And it became evident that it requires way more investment to be commercially viable. So before abandoning the project, I wanted to publish *something* as open-source for posterity. At that time, I already developed a prototype vector graphics tracer. It can convert high-resolution scans of hand-drawn blueprints into vectors. But it can only process black and white images, and can only output polygons, not splines.
+
+The plan was to fully develop the vectorizer: to handle color images and output splines. I recruited a very talented intern, [@shpun817](https://github.com/shpun817), to work on VTracer. I grafted the frontend of the video processing engine - the ["The Clustering Algorithm"](https://www.visioncortex.org/impression-docs#the-clustering-algorithm) as the pre-processor.
+
+Three months later, we published the first version on Reddit. Out of my surprise, the response of such an underwhelming project was overwhelming.
+
+## What's next?
+
+There are several things in my mind:
+
+1. Path simplification. Implement a post-process filter to the output paths to further reduce the number of splines.
+
+2. Perfect cut-out mode. Right now in cut-out mode, the shapes do not share boundaries perfectly, but have seams.
+
+3. Pencil tracing. Instead of tracing shapes as closed paths, may be we can attempt to skeletonize the shapes as open paths. The output would be clean, fixed width strokes.
+
+4. Image cleaning. Right now the tracer works best on losslessly compressed pngs. If an image suffered from jpeg noises, it could impact the tracing quality. We might be able to develop a pre-filtering pass that denoises the input.
+
+If you are interested in working on them or willing to sponsor its development, feel free to get in touch.

RELEASES.md

@@ -1,16 +0,0 @@
-Version 0.2.0 (2020-10-31)
-==========================
-
-- Use relative & closed paths
-
-
-Version 0.1.1 (2020-10-31)
-==========================
-
-- SVG namespace
-
-
-Version 0.1.0 (2020-10-31)
-==========================
-
-- Initial release

cmdapp/Cargo.toml

@@ -1,10 +1,10 @@
 [package]
 name = "vtracer"
-version = "0.2.0"
-authors = ["Chris Tsang <tyt2y7@gmail.com>"]
-edition = "2018"
+version = "0.6.12"
+authors = ["Chris Tsang <chris.2y3@outlook.com>"]
+edition = "2021"
 description = "A cmd app to convert images into vector graphics."
-license = "MIT OR Apache-2.0"
+license = "MIT"
 homepage = "http://www.visioncortex.org/vtracer"
 repository = "https://github.com/visioncortex/vtracer/"
 categories = ["graphics"]
@@ -13,4 +13,14 @@ keywords = ["svg", "computer-graphics"]
 [dependencies]
 clap = "2.33.3"
 image = "0.23.10"
-visioncortex = "0.3.0"
+visioncortex = { version = "0.8.8" }
+fastrand = { version = "2.3" }
+pyo3 = { version = "0.19.0", optional = true }
+
+[features]
+python-binding = ["pyo3"]
+wasm = ["fastrand/js"]
+
+[lib]
+name = "vtracer"
+crate-type = ["rlib", "cdylib"]

cmdapp/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) 2024 TSANG, Hao Fung
+
+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.

cmdapp/LICENSE-APACHE

@@ -1,201 +0,0 @@
-                              Apache License
-                        Version 2.0, January 2004
-                     http://www.apache.org/licenses/
-
-TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-1. Definitions.
-
-   "License" shall mean the terms and conditions for use, reproduction,
-   and distribution as defined by Sections 1 through 9 of this document.
-
-   "Licensor" shall mean the copyright owner or entity authorized by
-   the copyright owner that is granting the License.
-
-   "Legal Entity" shall mean the union of the acting entity and all
-   other entities that control, are controlled by, or are under common
-   control with that entity. For the purposes of this definition,
-   "control" means (i) the power, direct or indirect, to cause the
-   direction or management of such entity, whether by contract or
-   otherwise, or (ii) ownership of fifty percent (50%) or more of the
-   outstanding shares, or (iii) beneficial ownership of such entity.
-
-   "You" (or "Your") shall mean an individual or Legal Entity
-   exercising permissions granted by this License.
-
-   "Source" form shall mean the preferred form for making modifications,
-   including but not limited to software source code, documentation
-   source, and configuration files.
-
-   "Object" form shall mean any form resulting from mechanical
-   transformation or translation of a Source form, including but
-   not limited to compiled object code, generated documentation,
-   and conversions to other media types.
-
-   "Work" shall mean the work of authorship, whether in Source or
-   Object form, made available under the License, as indicated by a
-   copyright notice that is included in or attached to the work
-   (an example is provided in the Appendix below).
-
-   "Derivative Works" shall mean any work, whether in Source or Object
-   form, that is based on (or derived from) the Work and for which the
-   editorial revisions, annotations, elaborations, or other modifications
-   represent, as a whole, an original work of authorship. For the purposes
-   of this License, Derivative Works shall not include works that remain
-   separable from, or merely link (or bind by name) to the interfaces of,
-   the Work and Derivative Works thereof.
-
-   "Contribution" shall mean any work of authorship, including
-   the original version of the Work and any modifications or additions
-   to that Work or Derivative Works thereof, that is intentionally
-   submitted to Licensor for inclusion in the Work by the copyright owner
-   or by an individual or Legal Entity authorized to submit on behalf of
-   the copyright owner. For the purposes of this definition, "submitted"
-   means any form of electronic, verbal, or written communication sent
-   to the Licensor or its representatives, including but not limited to
-   communication on electronic mailing lists, source code control systems,
-   and issue tracking systems that are managed by, or on behalf of, the
-   Licensor for the purpose of discussing and improving the Work, but
-   excluding communication that is conspicuously marked or otherwise
-   designated in writing by the copyright owner as "Not a Contribution."
-
-   "Contributor" shall mean Licensor and any individual or Legal Entity
-   on behalf of whom a Contribution has been received by Licensor and
-   subsequently incorporated within the Work.
-
-2. Grant of Copyright License. Subject to the terms and conditions of
-   this License, each Contributor hereby grants to You a perpetual,
-   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-   copyright license to reproduce, prepare Derivative Works of,
-   publicly display, publicly perform, sublicense, and distribute the
-   Work and such Derivative Works in Source or Object form.
-
-3. Grant of Patent License. Subject to the terms and conditions of
-   this License, each Contributor hereby grants to You a perpetual,
-   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-   (except as stated in this section) patent license to make, have made,
-   use, offer to sell, sell, import, and otherwise transfer the Work,
-   where such license applies only to those patent claims licensable
-   by such Contributor that are necessarily infringed by their
-   Contribution(s) alone or by combination of their Contribution(s)
-   with the Work to which such Contribution(s) was submitted. If You
-   institute patent litigation against any entity (including a
-   cross-claim or counterclaim in a lawsuit) alleging that the Work
-   or a Contribution incorporated within the Work constitutes direct
-   or contributory patent infringement, then any patent licenses
-   granted to You under this License for that Work shall terminate
-   as of the date such litigation is filed.
-
-4. Redistribution. You may reproduce and distribute copies of the
-   Work or Derivative Works thereof in any medium, with or without
-   modifications, and in Source or Object form, provided that You
-   meet the following conditions:
-
-   (a) You must give any other recipients of the Work or
-       Derivative Works a copy of this License; and
-
-   (b) You must cause any modified files to carry prominent notices
-       stating that You changed the files; and
-
-   (c) You must retain, in the Source form of any Derivative Works
-       that You distribute, all copyright, patent, trademark, and
-       attribution notices from the Source form of the Work,
-       excluding those notices that do not pertain to any part of
-       the Derivative Works; and
-
-   (d) If the Work includes a "NOTICE" text file as part of its
-       distribution, then any Derivative Works that You distribute must
-       include a readable copy of the attribution notices contained
-       within such NOTICE file, excluding those notices that do not
-       pertain to any part of the Derivative Works, in at least one
-       of the following places: within a NOTICE text file distributed
-       as part of the Derivative Works; within the Source form or
-       documentation, if provided along with the Derivative Works; or,
-       within a display generated by the Derivative Works, if and
-       wherever such third-party notices normally appear. The contents
-       of the NOTICE file are for informational purposes only and
-       do not modify the License. You may add Your own attribution
-       notices within Derivative Works that You distribute, alongside
-       or as an addendum to the NOTICE text from the Work, provided
-       that such additional attribution notices cannot be construed
-       as modifying the License.
-
-   You may add Your own copyright statement to Your modifications and
-   may provide additional or different license terms and conditions
-   for use, reproduction, or distribution of Your modifications, or
-   for any such Derivative Works as a whole, provided Your use,
-   reproduction, and distribution of the Work otherwise complies with
-   the conditions stated in this License.
-
-5. Submission of Contributions. Unless You explicitly state otherwise,
-   any Contribution intentionally submitted for inclusion in the Work
-   by You to the Licensor shall be under the terms and conditions of
-   this License, without any additional terms or conditions.
-   Notwithstanding the above, nothing herein shall supersede or modify
-   the terms of any separate license agreement you may have executed
-   with Licensor regarding such Contributions.
-
-6. Trademarks. This License does not grant permission to use the trade
-   names, trademarks, service marks, or product names of the Licensor,
-   except as required for reasonable and customary use in describing the
-   origin of the Work and reproducing the content of the NOTICE file.
-
-7. Disclaimer of Warranty. Unless required by applicable law or
-   agreed to in writing, Licensor provides the Work (and each
-   Contributor provides its Contributions) on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-   implied, including, without limitation, any warranties or conditions
-   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-   PARTICULAR PURPOSE. You are solely responsible for determining the
-   appropriateness of using or redistributing the Work and assume any
-   risks associated with Your exercise of permissions under this License.
-
-8. Limitation of Liability. In no event and under no legal theory,
-   whether in tort (including negligence), contract, or otherwise,
-   unless required by applicable law (such as deliberate and grossly
-   negligent acts) or agreed to in writing, shall any Contributor be
-   liable to You for damages, including any direct, indirect, special,
-   incidental, or consequential damages of any character arising as a
-   result of this License or out of the use or inability to use the
-   Work (including but not limited to damages for loss of goodwill,
-   work stoppage, computer failure or malfunction, or any and all
-   other commercial damages or losses), even if such Contributor
-   has been advised of the possibility of such damages.
-
-9. Accepting Warranty or Additional Liability. While redistributing
-   the Work or Derivative Works thereof, You may choose to offer,
-   and charge a fee for, acceptance of support, warranty, indemnity,
-   or other liability obligations and/or rights consistent with this
-   License. However, in accepting such obligations, You may act only
-   on Your own behalf and on Your sole responsibility, not on behalf
-   of any other Contributor, and only if You agree to indemnify,
-   defend, and hold each Contributor harmless for any liability
-   incurred by, or claims asserted against, such Contributor by reason
-   of your accepting any such warranty or additional liability.
-
-END OF TERMS AND CONDITIONS
-
-APPENDIX: How to apply the Apache License to your work.
-
-   To apply the Apache License to your work, attach the following
-   boilerplate notice, with the fields enclosed by brackets "[]"
-   replaced with your own identifying information. (Don't include
-   the brackets!)  The text should be enclosed in the appropriate
-   comment syntax for the file format. We also recommend that a
-   file or class name and description of purpose be included on the
-   same "printed page" as the copyright notice for easier
-   identification within third-party archives.
-
-Copyright [yyyy] [name of copyright owner]
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-	http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.

cmdapp/README.md

@@ -0,0 +1,96 @@
+<div align="center">
+
+  <img src="https://raw.githubusercontent.com/visioncortex/vtracer/master/docs/images/visioncortex-banner.png">
+  <h1>VTracer</h1>
+
+  <p>
+    <strong>Raster to Vector Graphics Converter built on top of visioncortex</strong>
+  </p>
+
+  <h3>
+    <a href="https://www.visioncortex.org/vtracer-docs">Article</a>
+    <span> | </span>
+    <a href="https://www.visioncortex.org/vtracer/">Demo</a>
+    <span> | </span>
+    <a href="https://github.com/visioncortex/vtracer/releases/latest">Download</a>
+  </h3>
+
+  <sub>Built with 🦀 by <a href="https://www.visioncortex.org/">The Vision Cortex Research Group</a></sub>
+</div>
+
+## Introduction
+
+visioncortex VTracer is an open source software to convert raster images (like jpg & png) into vector graphics (svg). It can vectorize graphics and photographs and trace the curves to output compact vector files.
+
+Comparing to [Potrace](http://potrace.sourceforge.net/) which only accept binarized inputs (Black & White pixmap), VTracer has an image processing pipeline which can handle colored high resolution scans.
+
+Comparing to Adobe Illustrator's [Image Trace](https://helpx.adobe.com/illustrator/using/image-trace.html), VTracer's output is much more compact (less shapes) as we adopt a stacking strategy and avoid producing shapes with holes.
+
+VTracer is originally designed for processing high resolution scans of historic blueprints up to gigapixels. At the same time, VTracer can also handle low resolution pixel art, simulating `image-rendering: pixelated` for retro game artworks.
+
+A technical description of the algorithm is on [visioncortex.org/vtracer-docs](https://www.visioncortex.org/vtracer-docs).
+
+## Cmd App
+
+```sh
+visioncortex VTracer 0.6.0
+A cmd app to convert images into vector graphics.
+
+USAGE:
+    vtracer [OPTIONS] --input <input> --output <output>
+
+FLAGS:
+    -h, --help       Prints help information
+    -V, --version    Prints version information
+
+OPTIONS:
+        --colormode <color_mode>                 True color image `color` (default) or Binary image `bw`
+    -p, --color_precision <color_precision>      Number of significant bits to use in an RGB channel
+    -c, --corner_threshold <corner_threshold>    Minimum momentary angle (degree) to be considered a corner
+    -f, --filter_speckle <filter_speckle>        Discard patches smaller than X px in size
+    -g, --gradient_step <gradient_step>          Color difference between gradient layers
+        --hierarchical <hierarchical>
+            Hierarchical clustering `stacked` (default) or non-stacked `cutout`. Only applies to color mode.
+
+    -i, --input <input>                          Path to input raster image
+    -m, --mode <mode>                            Curver fitting mode `pixel`, `polygon`, `spline`
+    -o, --output <output>                        Path to output vector graphics
+        --path_precision <path_precision>        Number of decimal places to use in path string
+        --preset <preset>                        Use one of the preset configs `bw`, `poster`, `photo`
+    -l, --segment_length <segment_length>
+            Perform iterative subdivide smooth until all segments are shorter than this length
+
+    -s, --splice_threshold <splice_threshold>    Minimum angle displacement (degree) to splice a spline
+```
+
+### Install
+
+You can download pre-built binaries from [Releases](https://github.com/visioncortex/vtracer/releases).
+
+You can also install the program from source from [crates.io/vtracer](https://crates.io/crates/vtracer):
+
+```sh
+cargo install vtracer
+```
+
+### Usage
+
+```sh
+./vtracer --input input.jpg --output output.svg
+```
+
+## Rust Library
+
+You can install [`vtracer`](https://crates.io/crates/vtracer) as a Rust library.
+
+```sh
+cargo add vtracer
+```
+
+## Python Library
+
+Since `0.6`, [`vtracer`](https://pypi.org/project/vtracer/) is also packaged as Python native extensions, thanks to the awesome [pyo3](https://github.com/PyO3/pyo3) project.
+
+```sh
+pip install vtracer
+```

cmdapp/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "vtracer"
+version = "0.6.15"
+description = "Python bindings for the Rust Vtracer raster-to-vector library"
+authors = [ { name = "Chris Tsang",  email = "chris.2y3@outlook.com" } ]
+readme = "vtracer/README.md"
+requires-python = ">=3.7"
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Programming Language :: Rust",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Programming Language :: Python :: Implementation :: PyPy",
+]
+
+[dependencies]
+python = "^3.7"
+
+[dev-dependencies]
+maturin = "^1.2"
+
+[build-system]
+requires = ["maturin>=1.2,<2.0"]
+build-backend = "maturin"
+
+[tool.maturin]
+features = ["pyo3/extension-module", "python-binding"]
+compatibility = "manylinux2014"
+include = ["LICENSE"]

cmdapp/src/config.rs

@@ -1,26 +1,30 @@
 use std::str::FromStr;
-use std::path::PathBuf;
-use clap::{Arg, App};
-use visioncortex::path::PathSimplifyMode;
+use visioncortex::PathSimplifyMode;
 
+#[derive(Debug, Clone)]
 pub enum Preset {
     Bw,
     Poster,
-    Photo
+    Photo,
 }
 
-#[derive(Debug)]
+#[derive(Debug, Clone)]
 pub enum ColorMode {
     Color,
     Binary,
 }
 
+#[derive(Debug, Clone)]
+pub enum Hierarchical {
+    Stacked,
+    Cutout,
+}
+
 /// Converter config
-#[derive(Debug)]
+#[derive(Debug, Clone)]
 pub struct Config {
-    pub input_path: PathBuf,
-    pub output_path: PathBuf,
     pub color_mode: ColorMode,
+    pub hierarchical: Hierarchical,
     pub filter_speckle: usize,
     pub color_precision: i32,
     pub layer_difference: i32,
@@ -29,13 +33,13 @@ pub struct Config {
     pub length_threshold: f64,
     pub max_iterations: usize,
     pub splice_threshold: i32,
+    pub path_precision: Option<u32>,
 }
 
-#[derive(Debug)]
+#[derive(Debug, Clone)]
 pub(crate) struct ConverterConfig {
-    pub input_path: PathBuf,
-    pub output_path: PathBuf,
     pub color_mode: ColorMode,
+    pub hierarchical: Hierarchical,
     pub filter_speckle_area: usize,
     pub color_precision_loss: i32,
     pub layer_difference: i32,
@@ -44,14 +48,14 @@ pub(crate) struct ConverterConfig {
     pub length_threshold: f64,
     pub max_iterations: usize,
     pub splice_threshold: f64,
+    pub path_precision: Option<u32>,
 }
 
 impl Default for Config {
     fn default() -> Self {
         Self {
-            input_path: PathBuf::default(),
-            output_path: PathBuf::default(),
             color_mode: ColorMode::Color,
+            hierarchical: Hierarchical::Stacked,
             mode: PathSimplifyMode::Spline,
             filter_speckle: 4,
             color_precision: 6,
@@ -60,6 +64,7 @@ impl Default for Config {
             length_threshold: 4.0,
             splice_threshold: 45,
             max_iterations: 10,
+            path_precision: Some(2),
         }
     }
 }
@@ -76,6 +81,18 @@ impl FromStr for ColorMode {
     }
 }
 
+impl FromStr for Hierarchical {
+    type Err = String;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        match s {
+            "stacked" => Ok(Self::Stacked),
+            "cutout" => Ok(Self::Cutout),
+            _ => Err(format!("unknown Hierarchical {}", s)),
+        }
+    }
+}
+
 impl FromStr for Preset {
     type Err = String;
 
@@ -89,200 +106,12 @@ impl FromStr for Preset {
     }
 }
 
-fn path_simplify_mode_from_str(s: &str) -> PathSimplifyMode {
-    match s {
-        "polygon" => PathSimplifyMode::Polygon,
-        "spline" => PathSimplifyMode::Spline,
-        "none" => PathSimplifyMode::None,
-        _ => panic!("unknown PathSimplifyMode {}", s),
-    }
-}
-
 impl Config {
-    pub fn from_args() -> Self {
-        let app = App::new("visioncortex VTracer ".to_owned() + env!("CARGO_PKG_VERSION"))
-            .about("A cmd app to convert images into vector graphics.");
-
-        let app = app.arg(Arg::with_name("input")
-            .long("input")
-            .short("i")
-            .takes_value(true)
-            .help("Path to input raster image")
-            .required(true));
-
-        let app = app.arg(Arg::with_name("output")
-            .long("output")
-            .short("o")
-            .takes_value(true)
-            .help("Path to output vector graphics")
-            .required(true));
-
-        let app = app.arg(Arg::with_name("color_mode")
-            .long("colormode")
-            .takes_value(true)
-            .help("True color image `color` (default) or Binary image `bw`"));
-
-        let app = app.arg(Arg::with_name("preset")
-            .long("preset")
-            .takes_value(true)
-            .help("Use one of the preset configs `bw`, `poster`, `photo`"));
-
-        let app = app.arg(Arg::with_name("filter_speckle")
-            .long("filter_speckle")
-            .short("f")
-            .takes_value(true)
-            .help("Discard patches smaller than X px in size"));
-
-        let app = app.arg(Arg::with_name("color_precision")
-            .long("color_precision")
-            .short("p")
-            .takes_value(true)
-            .help("Number of significant bits to use in an RGB channel"));
-
-        let app = app.arg(Arg::with_name("gradient_step")
-            .long("gradient_step")
-            .short("g")
-            .takes_value(true)
-            .help("Color difference between gradient layers"));
-
-        let app = app.arg(Arg::with_name("corner_threshold")
-            .long("corner_threshold")
-            .short("c")
-            .takes_value(true)
-            .help("Minimum momentary angle (degree) to be considered a corner"));
-
-        let app = app.arg(Arg::with_name("segment_length")
-            .long("segment_length")
-            .short("l")
-            .takes_value(true)
-            .help("Perform iterative subdivide smooth until all segments are shorter than this length"));
-
-        let app = app.arg(Arg::with_name("splice_threshold")
-            .long("splice_threshold")
-            .short("s")
-            .takes_value(true)
-            .help("Minimum angle displacement (degree) to splice a spline"));
-
-        let app = app.arg(Arg::with_name("mode")
-            .long("mode")
-            .short("m")
-            .takes_value(true)
-            .help("Curver fitting mode `pixel`, `polygon`, `spline`"));
-
-        // Extract matches
-        let matches = app.get_matches();
-
-        let mut config = Config::default();
-        let input_path = matches.value_of("input").expect("Input path is required, please specify it by --input or -i.");
-        let output_path = matches.value_of("output").expect("Output path is required, please specify it by --output or -o.");
-
-        if let Some(value) = matches.value_of("preset") {
-            config = Self::from_preset(Preset::from_str(value).unwrap(), input_path, output_path);
-        }
-
-        config.input_path = PathBuf::from(input_path);
-        config.output_path = PathBuf::from(output_path);
-
-        if let Some(value) = matches.value_of("color_mode") {
-            config.color_mode = ColorMode::from_str(if value.trim() == "bw" || value.trim() == "BW" {"binary"} else {"color"}).unwrap()
-        }
-
-        if let Some(value) = matches.value_of("mode") {
-            let value = value.trim();
-            config.mode = path_simplify_mode_from_str(if value == "pixel" {
-                "none"
-            } else if value == "polygon" {
-                "polygon"
-            } else if value == "spline" {
-                "spline"
-            } else {
-                panic!("Parser Error: Curve fitting mode is invalid with value {}", value);
-            });
-        }
-
-        if let Some(value) = matches.value_of("filter_speckle") {
-            if value.trim().parse::<usize>().is_ok() { // is numeric
-                let value = value.trim().parse::<usize>().unwrap();
-                if value < 1 || value > 16 {
-                    panic!("Out of Range Error: Filter speckle is invalid at {}. It must be within [1,16].", value);
-                }
-                config.filter_speckle = value;
-            } else {
-                panic!("Parser Error: Filter speckle is not a positive integer with value {}.", value);
-            }
-        }
-
-        if let Some(value) = matches.value_of("color_precision") {
-            if value.trim().parse::<i32>().is_ok() { // is numeric
-                let value = value.trim().parse::<i32>().unwrap();
-                if value < 1 || value > 8 {
-                    panic!("Out of Range Error: Color precision is invalid at {}. It must be within [1,8].", value);
-                }
-                config.color_precision = value;
-            } else {
-                panic!("Parser Error: Color precision is not an integer with value {}.", value);
-            }
-        }
-
-        if let Some(value) = matches.value_of("gradient_step") {
-            if value.trim().parse::<i32>().is_ok() { // is numeric
-                let value = value.trim().parse::<i32>().unwrap();
-                if value < 0 || value > 255 {
-                    panic!("Out of Range Error: Gradient step is invalid at {}. It must be within [0,255].", value);
-                }
-                config.layer_difference = value;
-            } else {
-                panic!("Parser Error: Gradient step is not an integer with value {}.", value);
-            }
-        }
-
-        if let Some(value) = matches.value_of("corner_threshold") {
-            if value.trim().parse::<i32>().is_ok() { // is numeric
-                let value = value.trim().parse::<i32>().unwrap();
-                if value < 0 || value > 180 {
-                    panic!("Out of Range Error: Corner threshold is invalid at {}. It must be within [0,180].", value);
-                }
-                config.corner_threshold = value
-            } else {
-                panic!("Parser Error: Corner threshold is not numeric with value {}.", value);
-            }
-        }
-
-        if let Some(value) = matches.value_of("segment_length") {
-            if value.trim().parse::<f64>().is_ok() { // is numeric
-                let value = value.trim().parse::<f64>().unwrap();
-                if value < 3.5 || value > 10.0 {
-                    panic!("Out of Range Error: Segment length is invalid at {}. It must be within [3.5,10].", value);
-                }
-                config.length_threshold = value;
-            } else {
-                panic!("Parser Error: Segment length is not numeric with value {}.", value);
-            }
-        }
-
-        if let Some(value) = matches.value_of("splice_threshold") {
-            if value.trim().parse::<i32>().is_ok() { // is numeric
-                let value = value.trim().parse::<i32>().unwrap();
-                if value < 0 || value > 180 {
-                    panic!("Out of Range Error: Segment length is invalid at {}. It must be within [0,180].", value);
-                }
-                config.splice_threshold = value;
-            } else {
-                panic!("Parser Error: Segment length is not numeric with value {}.", value);
-            }
-        }
-
-        config
-    }
-
-    pub fn from_preset(preset: Preset, input_path: &str, output_path: &str) -> Self {
-        let input_path = PathBuf::from(input_path);
-        let output_path = PathBuf::from(output_path);
+    pub fn from_preset(preset: Preset) -> Self {
         match preset {
             Preset::Bw => Self {
-                input_path,
-                output_path,
                 color_mode: ColorMode::Binary,
+                hierarchical: Hierarchical::Stacked,
                 filter_speckle: 4,
                 color_precision: 6,
                 layer_difference: 16,
@@ -291,11 +120,11 @@ impl Config {
                 length_threshold: 4.0,
                 max_iterations: 10,
                 splice_threshold: 45,
+                path_precision: Some(2),
             },
             Preset::Poster => Self {
-                input_path,
-                output_path,
                 color_mode: ColorMode::Color,
+                hierarchical: Hierarchical::Stacked,
                 filter_speckle: 4,
                 color_precision: 8,
                 layer_difference: 16,
@@ -304,11 +133,11 @@ impl Config {
                 length_threshold: 4.0,
                 max_iterations: 10,
                 splice_threshold: 45,
+                path_precision: Some(2),
             },
             Preset::Photo => Self {
-                input_path,
-                output_path,
                 color_mode: ColorMode::Color,
+                hierarchical: Hierarchical::Stacked,
                 filter_speckle: 10,
                 color_precision: 8,
                 layer_difference: 48,
@@ -317,15 +146,15 @@ impl Config {
                 length_threshold: 4.0,
                 max_iterations: 10,
                 splice_threshold: 45,
-            }
+                path_precision: Some(2),
+            },
         }
     }
 
     pub(crate) fn into_converter_config(self) -> ConverterConfig {
         ConverterConfig {
-            input_path: self.input_path,
-            output_path: self.output_path,
             color_mode: self.color_mode,
+            hierarchical: self.hierarchical,
             filter_speckle_area: self.filter_speckle * self.filter_speckle,
             color_precision_loss: 8 - self.color_precision,
             layer_difference: self.layer_difference,
@@ -334,10 +163,11 @@ impl Config {
             length_threshold: self.length_threshold,
             max_iterations: self.max_iterations,
             splice_threshold: deg2rad(self.splice_threshold),
+            path_precision: self.path_precision,
         }
     }
 }
 
 fn deg2rad(deg: i32) -> f64 {
     deg as f64 / 180.0 * std::f64::consts::PI
-}
+}

cmdapp/src/converter.rs

@@ -1,45 +1,170 @@
-use std::path::PathBuf;
+use std::path::Path;
 use std::{fs::File, io::Write};
 
-use visioncortex::{Color, ColorImage, ColorName, color_clusters::RunnerConfig, color_clusters::Runner};
-use super::config::{Config, ColorMode, ConverterConfig};
+use super::config::{ColorMode, Config, ConverterConfig, Hierarchical};
 use super::svg::SvgFile;
+use fastrand::Rng;
+use visioncortex::color_clusters::{KeyingAction, Runner, RunnerConfig, HIERARCHICAL_MAX};
+use visioncortex::{Color, ColorImage, ColorName};
 
-/// Convert an image file into svg file
-pub fn convert_image_to_svg(config: Config) -> Result<(), String> {
+const NUM_UNUSED_COLOR_ITERATIONS: usize = 6;
+/// The fraction of pixels in the top/bottom rows of the image that need to be transparent before
+/// the entire image will be keyed.
+const KEYING_THRESHOLD: f32 = 0.2;
+
+/// Convert an in-memory image into an in-memory SVG
+pub fn convert(img: ColorImage, config: Config) -> Result<SvgFile, String> {
     let config = config.into_converter_config();
     match config.color_mode {
-        ColorMode::Color => color_image_to_svg(config),
-        ColorMode::Binary => binary_image_to_svg(config),
+        ColorMode::Color => color_image_to_svg(img, config),
+        ColorMode::Binary => binary_image_to_svg(img, config),
     }
 }
 
-fn color_image_to_svg(config: ConverterConfig) -> Result<(), String> {
-    let (img, width, height);
-    match read_image(config.input_path) {
-        Ok(values) => {
-            img = values.0;
-            width = values.1;
-            height = values.2;
-        },
-        Err(msg) => return Err(msg),
+/// Convert an image file into svg file
+pub fn convert_image_to_svg(
+    input_path: &Path,
+    output_path: &Path,
+    config: Config,
+) -> Result<(), String> {
+    let img = read_image(input_path)?;
+    let svg = convert(img, config)?;
+    write_svg(svg, output_path)
+}
+
+fn color_exists_in_image(img: &ColorImage, color: Color) -> bool {
+    for y in 0..img.height {
+        for x in 0..img.width {
+            let pixel_color = img.get_pixel(x, y);
+            if pixel_color.r == color.r && pixel_color.g == color.g && pixel_color.b == color.b {
+                return true;
+            }
+        }
+    }
+    false
+}
+
+fn find_unused_color_in_image(img: &ColorImage) -> Result<Color, String> {
+    let special_colors = IntoIterator::into_iter([
+        Color::new(255, 0, 0),
+        Color::new(0, 255, 0),
+        Color::new(0, 0, 255),
+        Color::new(255, 255, 0),
+        Color::new(0, 255, 255),
+        Color::new(255, 0, 255),
+    ]);
+    let mut rng = Rng::new();
+    let random_colors =
+        (0..NUM_UNUSED_COLOR_ITERATIONS).map(|_| Color::new(rng.u8(..), rng.u8(..), rng.u8(..)));
+    for color in special_colors.chain(random_colors) {
+        if !color_exists_in_image(img, color) {
+            return Ok(color);
+        }
+    }
+    Err(String::from(
+        "unable to find unused color in image to use as key",
+    ))
+}
+
+fn should_key_image(img: &ColorImage) -> bool {
+    if img.width == 0 || img.height == 0 {
+        return false;
     }
 
-    let runner = Runner::new(RunnerConfig {
-        batch_size: 25600,
-        good_min_area: config.filter_speckle_area,
-        good_max_area: (width * height),
-        is_same_color_a: config.color_precision_loss,
-        is_same_color_b: 1,
-        deepen_diff: config.layer_difference,
-        hollow_neighbours: 1,
-    }, img);
+    // Check for transparency at several scanlines
+    let threshold = ((img.width * 2) as f32 * KEYING_THRESHOLD) as usize;
+    let mut num_transparent_pixels = 0;
+    let y_positions = [
+        0,
+        img.height / 4,
+        img.height / 2,
+        3 * img.height / 4,
+        img.height - 1,
+    ];
+    for y in y_positions {
+        for x in 0..img.width {
+            if img.get_pixel(x, y).a == 0 {
+                num_transparent_pixels += 1;
+            }
+            if num_transparent_pixels >= threshold {
+                return true;
+            }
+        }
+    }
 
-    let clusters = runner.run();
+    false
+}
+
+fn color_image_to_svg(mut img: ColorImage, config: ConverterConfig) -> Result<SvgFile, String> {
+    let width = img.width;
+    let height = img.height;
+
+    let key_color = if should_key_image(&img) {
+        let key_color = find_unused_color_in_image(&img)?;
+        for y in 0..height {
+            for x in 0..width {
+                if img.get_pixel(x, y).a == 0 {
+                    img.set_pixel(x, y, &key_color);
+                }
+            }
+        }
+        key_color
+    } else {
+        // The default color is all zeroes, which is treated by visioncortex as a special value meaning no keying will be applied.
+        Color::default()
+    };
+
+    let runner = Runner::new(
+        RunnerConfig {
+            diagonal: config.layer_difference == 0,
+            hierarchical: HIERARCHICAL_MAX,
+            batch_size: 25600,
+            good_min_area: config.filter_speckle_area,
+            good_max_area: (width * height),
+            is_same_color_a: config.color_precision_loss,
+            is_same_color_b: 1,
+            deepen_diff: config.layer_difference,
+            hollow_neighbours: 1,
+            key_color,
+            keying_action: if matches!(config.hierarchical, Hierarchical::Cutout) {
+                KeyingAction::Keep
+            } else {
+                KeyingAction::Discard
+            },
+        },
+        img,
+    );
+
+    let mut clusters = runner.run();
+
+    match config.hierarchical {
+        Hierarchical::Stacked => {}
+        Hierarchical::Cutout => {
+            let view = clusters.view();
+            let image = view.to_color_image();
+            let runner = Runner::new(
+                RunnerConfig {
+                    diagonal: false,
+                    hierarchical: 64,
+                    batch_size: 25600,
+                    good_min_area: 0,
+                    good_max_area: (image.width * image.height) as usize,
+                    is_same_color_a: 0,
+                    is_same_color_b: 1,
+                    deepen_diff: 0,
+                    hollow_neighbours: 0,
+                    key_color,
+                    keying_action: KeyingAction::Discard,
+                },
+                image,
+            );
+            clusters = runner.run();
+        }
+    }
 
     let view = clusters.view();
 
-    let mut svg = SvgFile::new(width, height);
+    let mut svg = SvgFile::new(width, height, config.path_precision);
     for &cluster_index in view.clusters_output.iter().rev() {
         let cluster = view.get_cluster(cluster_index);
         let paths = cluster.to_compound_path(
@@ -49,30 +174,22 @@ fn color_image_to_svg(config: ConverterConfig) -> Result<(), String> {
             config.corner_threshold,
             config.length_threshold,
             config.max_iterations,
-            config.splice_threshold
+            config.splice_threshold,
         );
         svg.add_path(paths, cluster.residue_color());
     }
 
-    write_svg(svg, config.output_path)
+    Ok(svg)
 }
 
-fn binary_image_to_svg(config: ConverterConfig) -> Result<(), String> {
-
-    let (img, width, height);
-    match read_image(config.input_path) {
-        Ok(values) => {
-            img = values.0;
-            width = values.1;
-            height = values.2;
-        },
-        Err(msg) => return Err(msg),
-    }
+fn binary_image_to_svg(img: ColorImage, config: ConverterConfig) -> Result<SvgFile, String> {
     let img = img.to_binary_image(|x| x.r < 128);
+    let width = img.width;
+    let height = img.height;
 
     let clusters = img.to_clusters(false);
 
-    let mut svg = SvgFile::new(width, height);
+    let mut svg = SvgFile::new(width, height, config.path_precision);
     for i in 0..clusters.len() {
         let cluster = clusters.get_cluster(i);
         if cluster.size() >= config.filter_speckle_area {
@@ -87,23 +204,27 @@ fn binary_image_to_svg(config: ConverterConfig) -> Result<(), String> {
         }
     }
 
-    write_svg(svg, config.output_path)
+    Ok(svg)
 }
 
-fn read_image(input_path: PathBuf) -> Result<(ColorImage, usize, usize), String> {
+fn read_image(input_path: &Path) -> Result<ColorImage, String> {
     let img = image::open(input_path);
     let img = match img {
-        Ok(file) => file.to_rgba(),
+        Ok(file) => file.to_rgba8(),
         Err(_) => return Err(String::from("No image file found at specified input path")),
     };
 
     let (width, height) = (img.width() as usize, img.height() as usize);
-    let img = ColorImage {pixels: img.as_raw().to_vec(), width, height};
+    let img = ColorImage {
+        pixels: img.as_raw().to_vec(),
+        width,
+        height,
+    };
 
-    Ok((img, width, height))
+    Ok(img)
 }
 
-fn write_svg(svg: SvgFile, output_path: PathBuf) -> Result<(), String> {
+fn write_svg(svg: SvgFile, output_path: &Path) -> Result<(), String> {
     let out_file = File::create(output_path);
     let mut out_file = match out_file {
         Ok(file) => file,
@@ -113,4 +234,4 @@ fn write_svg(svg: SvgFile, output_path: PathBuf) -> Result<(), String> {
     write!(&mut out_file, "{}", svg).expect("failed to write file.");
 
     Ok(())
-}
+}

cmdapp/src/lib.rs

@@ -1,4 +1,4 @@
-// Copyright 2020 Tsang Hao Fung. See the COPYRIGHT
+// Copyright 2023 Tsang Hao Fung. See the COPYRIGHT
 // file at the top-level directory of this distribution and at
 // http://rust-lang.org/COPYRIGHT.
 //
@@ -10,8 +10,13 @@
 
 mod config;
 mod converter;
+#[cfg(feature = "python-binding")]
+mod python;
 mod svg;
 
 pub use config::*;
 pub use converter::*;
-pub use svg::*;
+#[cfg(feature = "python-binding")]
+pub use python::*;
+pub use svg::*;
+pub use visioncortex::ColorImage;

cmdapp/src/main.rs

@@ -1,14 +1,282 @@
-use vtracer::{Config, convert_image_to_svg};
+mod config;
+mod converter;
+mod svg;
+
+use clap::{App, Arg};
+use config::{ColorMode, Config, Hierarchical, Preset};
+use std::path::PathBuf;
+use std::str::FromStr;
+use visioncortex::PathSimplifyMode;
+
+fn path_simplify_mode_from_str(s: &str) -> PathSimplifyMode {
+    match s {
+        "polygon" => PathSimplifyMode::Polygon,
+        "spline" => PathSimplifyMode::Spline,
+        "none" => PathSimplifyMode::None,
+        _ => panic!("unknown PathSimplifyMode {}", s),
+    }
+}
+
+pub fn config_from_args() -> (PathBuf, PathBuf, Config) {
+    let app = App::new("visioncortex VTracer ".to_owned() + env!("CARGO_PKG_VERSION"))
+        .about("A cmd app to convert images into vector graphics.");
+
+    let app = app.arg(
+        Arg::with_name("input")
+            .long("input")
+            .short("i")
+            .takes_value(true)
+            .help("Path to input raster image")
+            .required(true),
+    );
+
+    let app = app.arg(
+        Arg::with_name("output")
+            .long("output")
+            .short("o")
+            .takes_value(true)
+            .help("Path to output vector graphics")
+            .required(true),
+    );
+
+    let app = app.arg(
+        Arg::with_name("color_mode")
+            .long("colormode")
+            .takes_value(true)
+            .help("True color image `color` (default) or Binary image `bw`"),
+    );
+
+    let app = app.arg(
+        Arg::with_name("hierarchical")
+            .long("hierarchical")
+            .takes_value(true)
+            .help(
+                "Hierarchical clustering `stacked` (default) or non-stacked `cutout`. \
+            Only applies to color mode. ",
+            ),
+    );
+
+    let app = app.arg(
+        Arg::with_name("preset")
+            .long("preset")
+            .takes_value(true)
+            .help("Use one of the preset configs `bw`, `poster`, `photo`"),
+    );
+
+    let app = app.arg(
+        Arg::with_name("filter_speckle")
+            .long("filter_speckle")
+            .short("f")
+            .takes_value(true)
+            .help("Discard patches smaller than X px in size"),
+    );
+
+    let app = app.arg(
+        Arg::with_name("color_precision")
+            .long("color_precision")
+            .short("p")
+            .takes_value(true)
+            .help("Number of significant bits to use in an RGB channel"),
+    );
+
+    let app = app.arg(
+        Arg::with_name("gradient_step")
+            .long("gradient_step")
+            .short("g")
+            .takes_value(true)
+            .help("Color difference between gradient layers"),
+    );
+
+    let app = app.arg(
+        Arg::with_name("corner_threshold")
+            .long("corner_threshold")
+            .short("c")
+            .takes_value(true)
+            .help("Minimum momentary angle (degree) to be considered a corner"),
+    );
+
+    let app = app.arg(Arg::with_name("segment_length")
+        .long("segment_length")
+        .short("l")
+        .takes_value(true)
+        .help("Perform iterative subdivide smooth until all segments are shorter than this length"));
+
+    let app = app.arg(
+        Arg::with_name("splice_threshold")
+            .long("splice_threshold")
+            .short("s")
+            .takes_value(true)
+            .help("Minimum angle displacement (degree) to splice a spline"),
+    );
+
+    let app = app.arg(
+        Arg::with_name("mode")
+            .long("mode")
+            .short("m")
+            .takes_value(true)
+            .help("Curver fitting mode `pixel`, `polygon`, `spline`"),
+    );
+
+    let app = app.arg(
+        Arg::with_name("path_precision")
+            .long("path_precision")
+            .takes_value(true)
+            .help("Number of decimal places to use in path string"),
+    );
+
+    // Extract matches
+    let matches = app.get_matches();
+
+    let mut config = Config::default();
+    let input_path = matches
+        .value_of("input")
+        .expect("Input path is required, please specify it by --input or -i.");
+    let output_path = matches
+        .value_of("output")
+        .expect("Output path is required, please specify it by --output or -o.");
+
+    let input_path = PathBuf::from(input_path);
+    let output_path = PathBuf::from(output_path);
+
+    if let Some(value) = matches.value_of("preset") {
+        config = Config::from_preset(Preset::from_str(value).unwrap());
+    }
+
+    if let Some(value) = matches.value_of("color_mode") {
+        config.color_mode = ColorMode::from_str(if value.trim() == "bw" || value.trim() == "BW" {
+            "binary"
+        } else {
+            "color"
+        })
+        .unwrap()
+    }
+
+    if let Some(value) = matches.value_of("hierarchical") {
+        config.hierarchical = Hierarchical::from_str(value).unwrap()
+    }
+
+    if let Some(value) = matches.value_of("mode") {
+        let value = value.trim();
+        config.mode = path_simplify_mode_from_str(if value == "pixel" {
+            "none"
+        } else if value == "polygon" {
+            "polygon"
+        } else if value == "spline" {
+            "spline"
+        } else {
+            panic!("Parser Error: Curve fitting mode is invalid: {}", value);
+        });
+    }
+
+    if let Some(value) = matches.value_of("filter_speckle") {
+        if value.trim().parse::<usize>().is_ok() {
+            // is numeric
+            let value = value.trim().parse::<usize>().unwrap();
+            if value > 16 {
+                panic!("Out of Range Error: Filter speckle is invalid at {}. It must be within [0,16].", value);
+            }
+            config.filter_speckle = value;
+        } else {
+            panic!(
+                "Parser Error: Filter speckle is not a positive integer: {}.",
+                value
+            );
+        }
+    }
+
+    if let Some(value) = matches.value_of("color_precision") {
+        if value.trim().parse::<i32>().is_ok() {
+            // is numeric
+            let value = value.trim().parse::<i32>().unwrap();
+            if value < 1 || value > 8 {
+                panic!("Out of Range Error: Color precision is invalid at {}. It must be within [1,8].", value);
+            }
+            config.color_precision = value;
+        } else {
+            panic!(
+                "Parser Error: Color precision is not an integer: {}.",
+                value
+            );
+        }
+    }
+
+    if let Some(value) = matches.value_of("gradient_step") {
+        if value.trim().parse::<i32>().is_ok() {
+            // is numeric
+            let value = value.trim().parse::<i32>().unwrap();
+            if value < 0 || value > 255 {
+                panic!("Out of Range Error: Gradient step is invalid at {}. It must be within [0,255].", value);
+            }
+            config.layer_difference = value;
+        } else {
+            panic!("Parser Error: Gradient step is not an integer: {}.", value);
+        }
+    }
+
+    if let Some(value) = matches.value_of("corner_threshold") {
+        if value.trim().parse::<i32>().is_ok() {
+            // is numeric
+            let value = value.trim().parse::<i32>().unwrap();
+            if value < 0 || value > 180 {
+                panic!("Out of Range Error: Corner threshold is invalid at {}. It must be within [0,180].", value);
+            }
+            config.corner_threshold = value
+        } else {
+            panic!("Parser Error: Corner threshold is not numeric: {}.", value);
+        }
+    }
+
+    if let Some(value) = matches.value_of("segment_length") {
+        if value.trim().parse::<f64>().is_ok() {
+            // is numeric
+            let value = value.trim().parse::<f64>().unwrap();
+            if value < 3.5 || value > 10.0 {
+                panic!("Out of Range Error: Segment length is invalid at {}. It must be within [3.5,10].", value);
+            }
+            config.length_threshold = value;
+        } else {
+            panic!("Parser Error: Segment length is not numeric: {}.", value);
+        }
+    }
+
+    if let Some(value) = matches.value_of("splice_threshold") {
+        if value.trim().parse::<i32>().is_ok() {
+            // is numeric
+            let value = value.trim().parse::<i32>().unwrap();
+            if value < 0 || value > 180 {
+                panic!("Out of Range Error: Segment length is invalid at {}. It must be within [0,180].", value);
+            }
+            config.splice_threshold = value;
+        } else {
+            panic!("Parser Error: Segment length is not numeric: {}.", value);
+        }
+    }
+
+    if let Some(value) = matches.value_of("path_precision") {
+        if value.trim().parse::<u32>().is_ok() {
+            // is numeric
+            let value = value.trim().parse::<u32>().ok();
+            config.path_precision = value;
+        } else {
+            panic!(
+                "Parser Error: Path precision is not an unsigned integer: {}.",
+                value
+            );
+        }
+    }
+
+    (input_path, output_path, config)
+}
 
 fn main() {
-    let config = Config::from_args();
-    let result = convert_image_to_svg(config);
+    let (input_path, output_path, config) = config_from_args();
+    let result = converter::convert_image_to_svg(&input_path, &output_path, config);
     match result {
         Ok(()) => {
             println!("Conversion successful.");
-        },
+        }
         Err(msg) => {
             panic!("Conversion failed with error message: {}", msg);
         }
     }
-}
+}

cmdapp/src/python.rs

@@ -0,0 +1,222 @@
+use crate::*;
+use image::{io::Reader, ImageFormat};
+use pyo3::{exceptions::PyException, prelude::*};
+use std::io::{BufReader, Cursor};
+use std::path::PathBuf;
+use visioncortex::PathSimplifyMode;
+
+/// Python binding
+#[pyfunction]
+fn convert_image_to_svg_py(
+    image_path: &str,
+    out_path: &str,
+    colormode: Option<&str>,       // "color" or "binary"
+    hierarchical: Option<&str>,    // "stacked" or "cutout"
+    mode: Option<&str>,            // "polygon", "spline", "none"
+    filter_speckle: Option<usize>, // default: 4
+    color_precision: Option<i32>,  // default: 6
+    layer_difference: Option<i32>, // default: 16
+    corner_threshold: Option<i32>, // default: 60
+    length_threshold: Option<f64>, // in [3.5, 10] default: 4.0
+    max_iterations: Option<usize>, // default: 10
+    splice_threshold: Option<i32>, // default: 45
+    path_precision: Option<u32>,   // default: 8
+) -> PyResult<()> {
+    let input_path = PathBuf::from(image_path);
+    let output_path = PathBuf::from(out_path);
+
+    let config = construct_config(
+        colormode,
+        hierarchical,
+        mode,
+        filter_speckle,
+        color_precision,
+        layer_difference,
+        corner_threshold,
+        length_threshold,
+        max_iterations,
+        splice_threshold,
+        path_precision,
+    );
+
+    convert_image_to_svg(&input_path, &output_path, config).unwrap();
+    Ok(())
+}
+
+#[pyfunction]
+fn convert_raw_image_to_svg(
+    img_bytes: Vec<u8>,
+    img_format: Option<&str>, // Format of the image (e.g. 'jpg', 'png'... A full list of supported formats can be found [here](https://docs.rs/image/latest/image/enum.ImageFormat.html)). If not provided, the image format will be guessed based on its contents.
+    colormode: Option<&str>,  // "color" or "binary"
+    hierarchical: Option<&str>, // "stacked" or "cutout"
+    mode: Option<&str>,       // "polygon", "spline", "none"
+    filter_speckle: Option<usize>, // default: 4
+    color_precision: Option<i32>, // default: 6
+    layer_difference: Option<i32>, // default: 16
+    corner_threshold: Option<i32>, // default: 60
+    length_threshold: Option<f64>, // in [3.5, 10] default: 4.0
+    max_iterations: Option<usize>, // default: 10
+    splice_threshold: Option<i32>, // default: 45
+    path_precision: Option<u32>, // default: 8
+) -> PyResult<String> {
+    let config = construct_config(
+        colormode,
+        hierarchical,
+        mode,
+        filter_speckle,
+        color_precision,
+        layer_difference,
+        corner_threshold,
+        length_threshold,
+        max_iterations,
+        splice_threshold,
+        path_precision,
+    );
+    let mut img_reader = Reader::new(BufReader::new(Cursor::new(img_bytes)));
+    let img_format = img_format.and_then(|ext_name| ImageFormat::from_extension(ext_name));
+    let img = match img_format {
+        Some(img_format) => {
+            img_reader.set_format(img_format);
+            img_reader.decode()
+        }
+        None => img_reader
+            .with_guessed_format()
+            .map_err(|_| PyException::new_err("Unrecognized image format. "))?
+            .decode(),
+    };
+    let img = match img {
+        Ok(img) => img.to_rgba8(),
+        Err(_) => return Err(PyException::new_err("Failed to decode img_bytes. ")),
+    };
+    let (width, height) = (img.width() as usize, img.height() as usize);
+    let img = ColorImage {
+        pixels: img.as_raw().to_vec(),
+        width,
+        height,
+    };
+    let svg =
+        convert(img, config).map_err(|_| PyException::new_err("Failed to convert the image. "))?;
+    Ok(format!("{}", svg))
+}
+
+#[pyfunction]
+fn convert_pixels_to_svg(
+    rgba_pixels: Vec<(u8, u8, u8, u8)>,
+    size: (usize, usize),
+    colormode: Option<&str>,       // "color" or "binary"
+    hierarchical: Option<&str>,    // "stacked" or "cutout"
+    mode: Option<&str>,            // "polygon", "spline", "none"
+    filter_speckle: Option<usize>, // default: 4
+    color_precision: Option<i32>,  // default: 6
+    layer_difference: Option<i32>, // default: 16
+    corner_threshold: Option<i32>, // default: 60
+    length_threshold: Option<f64>, // in [3.5, 10] default: 4.0
+    max_iterations: Option<usize>, // default: 10
+    splice_threshold: Option<i32>, // default: 45
+    path_precision: Option<u32>,   // default: 8
+) -> PyResult<String> {
+    let expected_pixel_count = size.0 * size.1;
+    if rgba_pixels.len() != expected_pixel_count {
+        return Err(PyException::new_err(format!(
+            "Length of rgba_pixels does not match given image size. Expected {} ({} * {}), got {}. ",
+            expected_pixel_count,
+            size.0,
+            size.1,
+            rgba_pixels.len()
+        )));
+    }
+    let config = construct_config(
+        colormode,
+        hierarchical,
+        mode,
+        filter_speckle,
+        color_precision,
+        layer_difference,
+        corner_threshold,
+        length_threshold,
+        max_iterations,
+        splice_threshold,
+        path_precision,
+    );
+    let mut flat_pixels: Vec<u8> = vec![];
+    for (r, g, b, a) in rgba_pixels {
+        flat_pixels.push(r);
+        flat_pixels.push(g);
+        flat_pixels.push(b);
+        flat_pixels.push(a);
+    }
+    let mut img = ColorImage::new();
+    img.pixels = flat_pixels;
+    (img.width, img.height) = size;
+
+    let svg =
+        convert(img, config).map_err(|_| PyException::new_err("Failed to convert the image. "))?;
+    Ok(format!("{}", svg))
+}
+
+fn construct_config(
+    colormode: Option<&str>,
+    hierarchical: Option<&str>,
+    mode: Option<&str>,
+    filter_speckle: Option<usize>,
+    color_precision: Option<i32>,
+    layer_difference: Option<i32>,
+    corner_threshold: Option<i32>,
+    length_threshold: Option<f64>,
+    max_iterations: Option<usize>,
+    splice_threshold: Option<i32>,
+    path_precision: Option<u32>,
+) -> Config {
+    // TODO: enforce color mode with an enum so that we only
+    // accept the strings 'color' or 'binary'
+    let color_mode = match colormode.unwrap_or("color") {
+        "color" => ColorMode::Color,
+        "binary" => ColorMode::Binary,
+        _ => ColorMode::Color,
+    };
+
+    let hierarchical = match hierarchical.unwrap_or("stacked") {
+        "stacked" => Hierarchical::Stacked,
+        "cutout" => Hierarchical::Cutout,
+        _ => Hierarchical::Stacked,
+    };
+
+    let mode = match mode.unwrap_or("spline") {
+        "spline" => PathSimplifyMode::Spline,
+        "polygon" => PathSimplifyMode::Polygon,
+        "none" => PathSimplifyMode::None,
+        _ => PathSimplifyMode::Spline,
+    };
+
+    let filter_speckle = filter_speckle.unwrap_or(4);
+    let color_precision = color_precision.unwrap_or(6);
+    let layer_difference = layer_difference.unwrap_or(16);
+    let corner_threshold = corner_threshold.unwrap_or(60);
+    let length_threshold = length_threshold.unwrap_or(4.0);
+    let splice_threshold = splice_threshold.unwrap_or(45);
+    let max_iterations = max_iterations.unwrap_or(10);
+
+    Config {
+        color_mode,
+        hierarchical,
+        filter_speckle,
+        color_precision,
+        layer_difference,
+        mode,
+        corner_threshold,
+        length_threshold,
+        max_iterations,
+        splice_threshold,
+        path_precision,
+        ..Default::default()
+    }
+}
+
+/// A Python module implemented in Rust.
+#[pymodule]
+fn vtracer(_py: Python, m: &PyModule) -> PyResult<()> {
+    m.add_function(wrap_pyfunction!(convert_image_to_svg_py, m)?)?;
+    m.add_function(wrap_pyfunction!(convert_raw_image_to_svg, m)?)?;
+    m.add_function(wrap_pyfunction!(convert_pixels_to_svg, m)?)?;
+    Ok(())
+}

cmdapp/src/svg.rs

@@ -1,45 +1,52 @@
 use std::fmt;
 use visioncortex::{Color, CompoundPath, PointF64};
 
+#[derive(Debug, Clone)]
 pub struct SvgFile {
     pub paths: Vec<SvgPath>,
     pub width: usize,
     pub height: usize,
+    pub path_precision: Option<u32>,
 }
 
+#[derive(Debug, Clone)]
 pub struct SvgPath {
     pub path: CompoundPath,
     pub color: Color,
 }
 
 impl SvgFile {
-    pub fn new(width: usize, height: usize) -> Self {
+    pub fn new(width: usize, height: usize, path_precision: Option<u32>) -> Self {
         SvgFile {
             paths: vec![],
             width,
             height,
+            path_precision,
         }
     }
 
     pub fn add_path(&mut self, path: CompoundPath, color: Color) {
-        self.paths.push(SvgPath {
-            path,
-            color,
-        })
+        self.paths.push(SvgPath { path, color })
     }
 }
 
 impl fmt::Display for SvgFile {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         writeln!(f, r#"<?xml version="1.0" encoding="UTF-8"?>"#)?;
-        writeln!(f,
+        writeln!(
+            f,
+            r#"<!-- Generator: visioncortex VTracer {} -->"#,
+            env!("CARGO_PKG_VERSION")
+        )?;
+        writeln!(
+            f,
             r#"<svg version="1.1" xmlns="http://www.w3.org/2000/svg" width="{}" height="{}">"#,
             self.width, self.height
         )?;
 
         for path in &self.paths {
-            path.fmt(f)?;
-        };
+            path.fmt_with_precision(f, self.path_precision)?;
+        }
 
         writeln!(f, "</svg>")
     }
@@ -47,11 +54,22 @@ impl fmt::Display for SvgFile {
 
 impl fmt::Display for SvgPath {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
-        let (string, offset) = self.path.to_svg_string(true, PointF64::default());
+        self.fmt_with_precision(f, None)
+    }
+}
+
+impl SvgPath {
+    fn fmt_with_precision(&self, f: &mut fmt::Formatter, precision: Option<u32>) -> fmt::Result {
+        let (string, offset) = self
+            .path
+            .to_svg_string(true, PointF64::default(), precision);
         writeln!(
-            f, "<path d=\"{}\" fill=\"{}\" transform=\"translate({},{})\"/>",
-            string, self.color.to_hex_string(),
-            offset.x, offset.y
+            f,
+            "<path d=\"{}\" fill=\"{}\" transform=\"translate({},{})\"/>",
+            string,
+            self.color.to_hex_string(),
+            offset.x,
+            offset.y
         )
     }
-}
+}

cmdapp/vtracer/README.md

@@ -0,0 +1,85 @@
+<div align="center">
+
+  <img src="https://github.com/visioncortex/vtracer/raw/master/docs/images/visioncortex-banner.png">
+  
+  <h1>VTracer: Python Binding</h1>
+
+  <p>
+    <strong>Raster to Vector Graphics Converter built on top of visioncortex</strong>
+  </p>
+
+  <h3>
+    <a href="//www.visioncortex.org/vtracer-docs">Article</a>
+    <span> | </span>
+    <a href="//www.visioncortex.org/vtracer/">Demo</a>
+    <span> | </span>
+    <a href="//github.com/visioncortex/vtracer/releases/latest">Download</a>
+  </h3>
+
+<sub>Built with 🦀 by <a href="//www.visioncortex.org/">The Vision Cortex Research Group</a></sub>
+
+</div>
+
+## Introduction
+
+visioncortex VTracer is an open source software to convert raster images (like jpg & png) into vector graphics (svg). It can vectorize graphics and photographs and trace the curves to output compact vector files.
+
+Comparing to [Potrace](http://potrace.sourceforge.net/) which only accept binarized inputs (Black & White pixmap), VTracer has an image processing pipeline which can handle colored high resolution scans.
+
+Comparing to Adobe Illustrator's [Image Trace](https://helpx.adobe.com/illustrator/using/image-trace.html), VTracer's output is much more compact (less shapes) as we adopt a stacking strategy and avoid producing shapes with holes.
+
+VTracer is originally designed for processing high resolution scans of historic blueprints up to gigapixels. At the same time, VTracer can also handle low resolution pixel art, simulating `image-rendering: pixelated` for retro game artworks.
+
+A technical description of the algorithm is on [visioncortex.org/vtracer-docs](//www.visioncortex.org/vtracer-docs).
+
+## Install (Python)
+
+```shell
+pip install vtracer
+```
+
+### Usage (Python)
+
+```python
+import vtracer
+
+input_path = "/path/to/some_file.jpg"
+output_path = "/path/to/some_file.vtracer.jpg"
+
+# Minimal example: use all default values, generate a multicolor SVG
+vtracer.convert_image_to_svg_py(inp, out)
+
+# Single-color example. Good for line art, and much faster than full color:
+vtracer.convert_image_to_svg_py(inp, out, colormode='binary')
+
+# Convert from raw image bytes
+input_img_bytes: bytes = get_bytes() # e.g. reading bytes from a file or a HTTP request body
+svg_str: str = vtracer.convert_raw_image_to_svg(input_img_bytes, img_format='jpg')
+
+# Convert from RGBA image pixels
+from PIL import Image
+img = Image.open(input_path).convert('RGBA')
+pixels: list[tuple[int, int, int, int]] = list(img.getdata())
+svg_str: str = vtracer.convert_pixels_to_svg(pixels, img.size)
+
+# All the bells & whistles, also applicable to convert_raw_image_to_svg and convert_pixels_to_svg. 
+vtracer.convert_image_to_svg_py(inp,
+                                out,
+                                colormode = 'color',        # ["color"] or "binary"
+                                hierarchical = 'stacked',   # ["stacked"] or "cutout"
+                                mode = 'spline',            # ["spline"] "polygon", or "none"
+                                filter_speckle = 4,         # default: 4
+                                color_precision = 6,        # default: 6
+                                layer_difference = 16,      # default: 16
+                                corner_threshold = 60,      # default: 60
+                                length_threshold = 4.0,     # in [3.5, 10] default: 4.0
+                                max_iterations = 10,        # default: 10
+                                splice_threshold = 45,      # default: 45
+                                path_precision = 3          # default: 8
+                                )
+
+```
+
+## Rust Library
+
+The (Rust) library can be found on [crates.io/vtracer](//crates.io/crates/vtracer) and [crates.io/vtracer-webapp](//crates.io/crates/vtracer-webapp).

cmdapp/vtracer/__init__.py

@@ -0,0 +1,2 @@
+from .vtracer import (convert_image_to_svg_py, convert_pixels_to_svg,
+                      convert_raw_image_to_svg)

cmdapp/vtracer/vtracer.pyi

@@ -0,0 +1,49 @@
+from typing import Optional
+
+def convert_image_to_svg_py(image_path: str, 
+                            out_path: str,   
+                            colormode: Optional[str] = None,        # ["color"] or "binary"
+                            hierarchical: Optional[str] = None,     # ["stacked"] or "cutout"
+                            mode: Optional[str] = None,             # ["spline"], "polygon", "none"
+                            filter_speckle: Optional[int] = None,   # default: 4
+                            color_precision: Optional[int] = None,  # default: 6
+                            layer_difference: Optional[int] = None, # default: 16
+                            corner_threshold: Optional[int] = None, # default: 60   
+                            length_threshold: Optional[float] = None, # in [3.5, 10] default: 4.0
+                            max_iterations: Optional[int] = None,   # default: 10
+                            splice_threshold: Optional[int] = None, # default: 45
+                            path_precision: Optional[int] = None,   # default: 8
+                        ) -> None:
+    ...
+
+def convert_raw_image_to_svg(img_bytes: bytes,
+                            img_format: Optional[str] = None,       # Format of the image (e.g. 'jpg', 'png'... A full list of supported formats can be found [here](https://docs.rs/image/latest/image/enum.ImageFormat.html)). If not provided, the image format will be guessed based on its contents. 
+                            colormode: Optional[str] = None,        # ["color"] or "binary"
+                            hierarchical: Optional[str] = None,     # ["stacked"] or "cutout"
+                            mode: Optional[str] = None,             # ["spline"], "polygon", "none"
+                            filter_speckle: Optional[int] = None,   # default: 4
+                            color_precision: Optional[int] = None,  # default: 6
+                            layer_difference: Optional[int] = None, # default: 16
+                            corner_threshold: Optional[int] = None, # default: 60   
+                            length_threshold: Optional[float] = None, # in [3.5, 10] default: 4.0
+                            max_iterations: Optional[int] = None,   # default: 10
+                            splice_threshold: Optional[int] = None, # default: 45
+                            path_precision: Optional[int] = None,   # default: 8
+                        ) -> str:
+    ...
+
+def convert_pixels_to_svg(rgba_pixels: list[tuple[int, int, int, int]],
+                            size: tuple[int, int],
+                            colormode: Optional[str] = None,        # ["color"] or "binary"
+                            hierarchical: Optional[str] = None,     # ["stacked"] or "cutout"
+                            mode: Optional[str] = None,             # ["spline"], "polygon", "none"
+                            filter_speckle: Optional[int] = None,   # default: 4
+                            color_precision: Optional[int] = None,  # default: 6
+                            layer_difference: Optional[int] = None, # default: 16
+                            corner_threshold: Optional[int] = None, # default: 60   
+                            length_threshold: Optional[float] = None, # in [3.5, 10] default: 4.0
+                            max_iterations: Optional[int] = None,   # default: 10
+                            splice_threshold: Optional[int] = None, # default: 45
+                            path_precision: Optional[int] = None,   # default: 8
+                        ) -> str:
+    ...

docs/COPYRIGHT

@@ -1,3 +1,3 @@
 Copyright (c) 2020 Tsang Hao Fung
 
-All Rights Reserved
+The content in the /docs directory is for GitHub pages, and is not covered under open source licenses.

docs/assets/samples/attributions.txt

@@ -1,23 +0,0 @@
-K1_drawing
-B/W 4
-https://commons.wikimedia.org/wiki/File:K1_drawing.jpg
-
-Cityscape Sunset_DFM3-01
-Color 4,8,32
-<a href="https://www.vecteezy.com/free-vector/building">Building Vectors by Vecteezy</a>
-
-Gum Tree Vector
-Color 4,8,32
-<a href="https://www.vecteezy.com/free-vector/nature">Nature Vectors by Vecteezy</a>
-
-vectorstock_31191940
-Color 8,7,64
-<a href="https://www.vectorstock.com/royalty-free-vector/dessert-poster-design-with-chocolate-cake-mousses-vector-31191940">Vector image by VectorStock / vectorstock</a>
-
-averie-woodard-4nulm-JUYFo-unsplash
-Color 8,7,24
-<span>Photo by <a href="https://unsplash.com/@averieclaire?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">averie woodard</a> on <a href="https://unsplash.com/s/photos/portrait?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Unsplash</a></span>
-
-angel-luciano-LATYeZyw88c-unsplash
-Color 10,8,48 180
-<span>Photo by <a href="https://unsplash.com/@roaming_angel?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Angel Luciano</a> on <a href="https://unsplash.com/s/photos/dog?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Unsplash</a></span>

docs/bootstrap.js

@@ -258,7 +258,7 @@
 /******/ 				promises.push(installedWasmModuleData);
 /******/ 			else {
 /******/ 				var importObject = wasmImportObjects[wasmModuleId]();
-/******/ 				var req = fetch(__webpack_require__.p + "" + {"../pkg/vtracer_webapp_bg.wasm":"7ef94c5089d40af744f2"}[wasmModuleId] + ".module.wasm");
+/******/ 				var req = fetch(__webpack_require__.p + "" + {"../pkg/vtracer_webapp_bg.wasm":"589cb57662b50620abca"}[wasmModuleId] + ".module.wasm");
 /******/ 				var promise;
 /******/ 				if(importObject instanceof Promise && typeof WebAssembly.compileStreaming === 'function') {
 /******/ 					promise = Promise.all([WebAssembly.compileStreaming(req), importObject]).then(function(items) {

docs/index.html

@@ -79,8 +79,7 @@
         }
         #canvas-container {
             position: relative;
-            width: 100%;
-            height: 100%;
+            height: max-content;
         }
         #svg, #frame {
             position: absolute;
@@ -91,7 +90,7 @@
             stroke: #ff0;
         }
         #droptext {
-            height: 100%;
+            height: 480px;
             color: #CC972E;
         }
         input[type=range]::-webkit-slider-thumb {
@@ -107,11 +106,11 @@
             background: #00275D;
             border-color: #CC972E;
         }
-        #gallery, #options {
+        #drop, #gallery, #options {
             border-top: 1px solid #686868;
         }
         #gallery {
-            border-bottom: 1px solid #686868;
+            padding-bottom: 0;
         }
         .galleryitem {
             cursor: pointer;
@@ -140,9 +139,11 @@
                     <a id="vc-logo" class="uk-logo" href="//www.visioncortex.org"><img style="height: 50px; margin: -30px 0 -25px 0;" src="./assets/visioncortex-logo.svg"></a>
                     <a id="vc-logo-light" class="uk-logo" href="//www.visioncortex.org"><img style="height: 50px; margin: -30px 0 -25px 0;" src="./assets/visioncortex-logo-light.svg"></a>
                     &nbsp;
-                    VTracer
+                    / VTracer
                 </div>
                 <div class="uk-navbar-right uk-padding-small">
+                    <a class="uk-button uk-button-default" href="//www.visioncortex.org/vtracer-docs">Article</a>
+                    &nbsp;&nbsp;
                     <a class="uk-button uk-button-default" href="//github.com/visioncortex/vtracer">GitHub</a>
                     &nbsp;&nbsp;
                     <a id="export" class="uk-button uk-button-primary">Download as SVG</a>    
@@ -152,6 +153,15 @@
                 <progress id="progressbar" class="uk-progress uk-align-right" value="0" max="100" style="width: 98%;"></progress>
             </div>
             <div class="uk-width-3-4">
+                <div id="drop" class="uk-padding uk-flex uk-flex-center">
+                    <div id="canvas-container" class="uk-width-1-1">
+                        <div id="droptext" class="uk-flex uk-flex-middle uk-flex-center">
+                            <p>Drag an image here, Cmd-V to paste or <a href="#" id="imageSelect">Select file</a></p>
+                        </div>
+                        <canvas id="frame"></canvas>
+                        <svg id="svg" version="1.1" xmlns="http://www.w3.org/2000/svg"></svg>
+                    </div>
+                </div>
                 <div id="gallery" class="uk-padding">
                     <div class="uk-inline" uk-slider>
                         <ul id="galleryslider" class="uk-slider-items uk-child-width-1-6 uk-grid uk-grid-small">
@@ -160,16 +170,7 @@
                         <a class="uk-position-center-left uk-position-small uk-hidden-hover" href="#" uk-slidenav-previous uk-slider-item="previous"></a>
                         <a class="uk-position-center-right uk-position-small uk-hidden-hover" href="#" uk-slidenav-next uk-slider-item="next"></a>
                     </div>
-                    <a class="uk-align-right uk-text-meta" style="margin:-5px;" uk-toggle="target: #credits-modal">Credits</a>
-                </div>
-                <div id="drop" class="uk-padding uk-flex uk-flex-center">
-                    <div id="canvas-container" class="uk-width-1-1" style="height: 480px;">
-                        <div id="droptext" class="uk-flex uk-flex-middle uk-flex-center">
-                            <p>Drag an image here, Cmd-V to paste or <a href="#" id="imageSelect">Select file</a></p>
-                        </div>
-                        <canvas id="frame"></canvas>
-                        <svg id="svg" version="1.1" xmlns="http://www.w3.org/2000/svg"></svg>
-                    </div>
+                    <a class="uk-align-right uk-text-meta" style="margin:-5px;" uk-toggle="target: #credits-modal">Photo Credits</a>
                 </div>
             </div>
             <div id="options" class="uk-width-1-4 uk-height-1-1 uk-grid-small uk-flex uk-flex-center" uk-grid>
@@ -193,6 +194,13 @@
                     </div>
                 </div>
 
+                <div class="clustering-color-options uk-width-1-1 uk-flex uk-flex-right">
+                    <div class="uk-button-group">
+                        <button id="clustering-cutout" class="uk-button uk-button-default uk-button-small" uk-tooltip="Shapes disjoint with others">Cutout</button>
+                        <button id="clustering-stacked" class="selected uk-button uk-button-default uk-button-small" uk-tooltip="Stack shapes on top of another">Stacked</button>
+                    </div>
+                </div>
+
                 <div class="uk-width-1-1 uk-flex uk-flex-right">
                     <div uk-tooltip="pos: left; title: Discard patches small than X px in size">
                         Filter Speckle <span class="uk-text-meta">(Cleaner)</span>
@@ -202,7 +210,7 @@
                     4
                 </div>
                 <div class="uk-width-5-6">
-                    <input id="filterspeckle" class="uk-range" type="range" min="1" max="128" step="1" value="4">
+                    <input id="filterspeckle" class="uk-range" type="range" min="0" max="128" step="1" value="4">
                 </div>
 
                 <div class="clustering-color-options uk-width-1-1 uk-flex uk-flex-right">
@@ -279,6 +287,19 @@
                     <input id="splice" class="uk-range" type="range" min="0" max="180" step="1" value="45">
                 </div>
                 
+                <div style="display: none">
+                <div class="spline-options uk-width-1-1 uk-flex uk-flex-right">
+                    <div uk-tooltip="pos: left; title: Number of decimal places used in svg path string">
+                        Path Precision <span class="uk-text-meta">(More digits)</span>
+                    </div>
+                </div>
+                <div id="pathprecisionvalue" class="spline-options uk-width-1-6">
+                    8
+                </div>
+                <div class="spline-options uk-width-5-6">
+                    <input id="pathprecision" class="uk-range" type="range" min="0" max="16" step="1" value="8">
+                </div>
+                </div>
             </div>
         </div>
 

webapp/Cargo.toml

@@ -1,8 +1,8 @@
 [package]
 name = "vtracer-webapp"
-version = "0.1.0"
-authors = ["Chris Tsang <tyt2y7@gmail.com>"]
-edition = "2018"
+version = "0.4.0"
+authors = ["Chris Tsang <chris.2y3@outlook.com>"]
+edition = "2021"
 description = "A web app to convert images into vector graphics."
 license = "MIT OR Apache-2.0"
 homepage = "http://www.visioncortex.org/vtracer"
@@ -22,7 +22,7 @@ console_log = { version = "0.2", features = ["color"] }
 wasm-bindgen = { version = "0.2", features = ["serde-serialize"]  }
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
-visioncortex = "0.3.0"
+visioncortex = "0.8.1"
 
 # The `console_error_panic_hook` crate provides better debugging of panics by
 # logging them with `console.error`. This is great for development, but requires

webapp/Readme.md

@@ -1,3 +1,7 @@
+<div align="center">
+  <img src="https://github.com/visioncortex/vtracer/raw/master/docs/images/visioncortex-banner.png">
+</div>
+
 # visioncortex VTracer
 
 A web app to convert raster images into vector graphics.

webapp/app/index.html

@@ -90,6 +90,13 @@
                     </div>
                 </div>
 
+                <div>
+                    <div>
+                        <button id="clustering-cutout" title="Shapes disjoint with others">Cutout</button>
+                        <button id="clustering-stacked" title="Stack shapes on top of another">Stacked</button>
+                    </div>
+                </div>
+
                 <div>
                     <div title="Discard patches small than X px in size">
                         Filter Speckle <span>(Cleaner)</span>
@@ -178,6 +185,19 @@
                     <input id="splice" type="range" min="0" max="180" step="1" value="45">
                 </div>
                 
+                <div style="display: none">
+                <div class="spline-options">
+                    <div title="Number of decimal places used in svg path string">
+                        Path Precision <span>(More digits)</span>
+                    </div>
+                </div>
+                <div id="pathprecisionvalue" class="spline-options">
+                    8
+                </div>
+                <div class="spline-options">
+                    <input id="pathprecision" class="uk-range" type="range" min="0" max="16" step="1" value="8">
+                </div>
+                </div>
             </div>
         </div>
         <script src="./bootstrap.js"></script>

webapp/app/index.js

@@ -7,7 +7,7 @@ const svg = document.getElementById('svg');
 const img = new Image();
 const progress = document.getElementById('progressbar');
 const progressregion = document.getElementById('progressregion');
-let mode = 'spline', clustering_mode = 'color';
+let mode = 'spline', clustering_mode = 'color', clustering_hierarchical = 'stacked';
 
 // Hide canas and svg on load
 canvas.style.display = 'none';
@@ -15,27 +15,31 @@ svg.style.display = 'none';
 
 // Paste from clipboard
 document.addEventListener('paste', function (e) {
-	if (e.clipboardData) {
-		var items = e.clipboardData.items;
-		if (!items) return;
+    if (e.clipboardData) {
+        var items = e.clipboardData.items;
+        if (!items) return;
 
-		//access data directly
-		for (var i = 0; i < items.length; i++) {
-			if (items[i].type.indexOf("image") !== -1) {
-				//image
-				var blob = items[i].getAsFile();
-				var URLObj = window.URL || window.webkitURL;
-				var source = URLObj.createObjectURL(blob);
-				setSourceAndRestart(source);
-			}
-		}
-		e.preventDefault();
-	}
+        //access data directly
+        for (var i = 0; i < items.length; i++) {
+            if (items[i].type.indexOf("image") !== -1) {
+                //image
+                var blob = items[i].getAsFile();
+                var URLObj = window.URL || window.webkitURL;
+                var source = URLObj.createObjectURL(blob);
+                setSourceAndRestart(source);
+            }
+        }
+        e.preventDefault();
+    }
 });
 
 // Download as SVG
 document.getElementById('export').addEventListener('click', function (e) {
-    const blob = new Blob([new XMLSerializer().serializeToString(svg)], {type: 'octet/stream'}),
+    const blob = new Blob([
+        `<?xml version="1.0" encoding="UTF-8"?>\n`,
+        `<!-- Generator: visioncortex VTracer -->\n`,
+        new XMLSerializer().serializeToString(svg)
+    ], {type: 'octet/stream'}),
     url = window.URL.createObjectURL(blob);
 
     this.href = url;
@@ -49,8 +53,10 @@ var presetConfigs = [
     {
         src: 'assets/samples/K1_drawing.jpg',
         clustering_mode: 'binary',
+        clustering_hierarchical: 'stacked',
         filter_speckle: 4,
         color_precision: 6,
+        path_precision: 8,
         layer_difference: 16,
         mode: 'spline',
         corner_threshold: 60,
@@ -62,8 +68,10 @@ var presetConfigs = [
     {
         src: 'assets/samples/Cityscape Sunset_DFM3-01.jpg',
         clustering_mode: 'color',
+        clustering_hierarchical: 'stacked',
         filter_speckle: 4,
         color_precision: 8,
+        path_precision: 8,
         layer_difference: 25,
         mode: 'spline',
         corner_threshold: 60,
@@ -75,8 +83,10 @@ var presetConfigs = [
     {
         src: 'assets/samples/Gum Tree Vector.jpg',
         clustering_mode: 'color',
+        clustering_hierarchical: 'stacked',
         filter_speckle: 4,
         color_precision: 8,
+        path_precision: 8,
         layer_difference: 28,
         mode: 'spline',
         corner_threshold: 60,
@@ -88,8 +98,10 @@ var presetConfigs = [
     {
         src: 'assets/samples/vectorstock_31191940.png',
         clustering_mode: 'color',
+        clustering_hierarchical: 'stacked',
         filter_speckle: 8,
         color_precision: 7,
+        path_precision: 8,
         layer_difference: 64,
         mode: 'spline',
         corner_threshold: 60,
@@ -98,24 +110,13 @@ var presetConfigs = [
         source: 'https://www.vectorstock.com/royalty-free-vector/dessert-poster-design-with-chocolate-cake-mousses-vector-31191940',
         credit: '<a href="https://www.vectorstock.com/royalty-free-vector/dessert-poster-design-with-chocolate-cake-mousses-vector-31191940">Vector image by VectorStock / vectorstock</a>',
     },
-    {
-        src: 'assets/samples/averie-woodard-4nulm-JUYFo-unsplash-s.jpg',
-        clustering_mode: 'color',
-        filter_speckle: 8,
-        color_precision: 7,
-        layer_difference: 24,
-        mode: 'spline',
-        corner_threshold: 60,
-        length_threshold: 4,
-        splice_threshold: 45,
-        source: 'https://unsplash.com/photos/4nulm-JUYFo',
-        credit: '<span>Photo by <a href="https://unsplash.com/@averieclaire?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">averie woodard</a> on <a href="https://unsplash.com/s/photos/portrait?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Unsplash</a></span>',
-    },
     {
         src: 'assets/samples/angel-luciano-LATYeZyw88c-unsplash-s.jpg',
         clustering_mode: 'color',
+        clustering_hierarchical: 'stacked',
         filter_speckle: 10,
         color_precision: 8,
+        path_precision: 8,
         layer_difference: 48,
         mode: 'spline',
         corner_threshold: 180,
@@ -124,66 +125,87 @@ var presetConfigs = [
         source: 'https://unsplash.com/photos/LATYeZyw88c',
         credit: '<span>Photo by <a href="https://unsplash.com/@roaming_angel?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Angel Luciano</a> on <a href="https://unsplash.com/s/photos/dog?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Unsplash</a></span>',
     },
+    {
+        src: 'assets/samples/tank-unit-preview.png',
+        clustering_mode: 'color',
+        clustering_hierarchical: 'stacked',
+        filter_speckle: 0,
+        color_precision: 8,
+        path_precision: 8,
+        layer_difference: 0,
+        mode: 'none',
+        corner_threshold: 180,
+        length_threshold: 4,
+        splice_threshold: 45,
+        source: 'https://opengameart.org/content/sideview-sci-fi-patreon-collection',
+        credit: '<span>Artwork by <a href="https://opengameart.org/content/sideview-sci-fi-patreon-collection">Luis Zuno</a> on <a href="https://opengameart.org/">opengameart.org</a></span>',
+    },
 ];
 
 // Insert gallery items dynamically
-for (let i = 0; i < presetConfigs.length; ++i) {
-	document.getElementById('galleryslider').innerHTML += 
-	`<li>
-	<div class="galleryitem uk-panel uk-flex uk-flex-center">
-		<a href="#">
-			<img src="${presetConfigs[i].src}" title="${presetConfigs[i].source}">
-		</a>
-	</div>
-	</li>`;
-    document.getElementById('credits-modal-content').innerHTML += 
-    `<p>${presetConfigs[i].credit}</p>`;
+if (document.getElementById('galleryslider')) {
+    for (let i = 0; i < presetConfigs.length; i++) {
+        document.getElementById('galleryslider').innerHTML += 
+        `<li>
+        <div class="galleryitem uk-panel uk-flex uk-flex-center">
+            <a href="#">
+                <img src="${presetConfigs[i].src}" title="${presetConfigs[i].source}">
+            </a>
+        </div>
+        </li>`;
+        document.getElementById('credits-modal-content').innerHTML += 
+        `<p>${presetConfigs[i].credit}</p>`;
+    }
 }
 
 // Function to load a given config WITHOUT restarting
 function loadConfig(config) {
-	mode = config.mode;
-	clustering_mode = config.clustering_mode;
+    mode = config.mode;
+    clustering_mode = config.clustering_mode;
+    clustering_hierarchical = config.clustering_hierarchical;
 
-	globalcorner = config.corner_threshold;
-	document.getElementById('cornervalue').innerHTML = globalcorner;
-	document.getElementById('corner').value = globalcorner;
-	
-	globallength = config.length_threshold;
-	document.getElementById('lengthvalue').innerHTML = globallength;
-	document.getElementById('length').value = globallength;
-	
-	globalsplice = config.splice_threshold;
-	document.getElementById('splicevalue').innerHTML = globalsplice;
-	document.getElementById('splice').value = globalsplice;
+    globalcorner = config.corner_threshold;
+    document.getElementById('cornervalue').innerHTML = globalcorner;
+    document.getElementById('corner').value = globalcorner;
+    
+    globallength = config.length_threshold;
+    document.getElementById('lengthvalue').innerHTML = globallength;
+    document.getElementById('length').value = globallength;
+    
+    globalsplice = config.splice_threshold;
+    document.getElementById('splicevalue').innerHTML = globalsplice;
+    document.getElementById('splice').value = globalsplice;
 
-	globalfilterspeckle = config.filter_speckle;
-	document.getElementById('filterspecklevalue').innerHTML = globalfilterspeckle;
-	document.getElementById('filterspeckle').value = globalfilterspeckle;
+    globalfilterspeckle = config.filter_speckle;
+    document.getElementById('filterspecklevalue').innerHTML = globalfilterspeckle;
+    document.getElementById('filterspeckle').value = globalfilterspeckle;
 
-	globalcolorprecision = config.color_precision;
-	document.getElementById('colorprecisionvalue').innerHTML = globalcolorprecision;
-	document.getElementById('colorprecision').value = globalcolorprecision;
+    globalcolorprecision = config.color_precision;
+    document.getElementById('colorprecisionvalue').innerHTML = globalcolorprecision;
+    document.getElementById('colorprecision').value = globalcolorprecision;
 
-	globallayerdifference = config.layer_difference;
-	document.getElementById('layerdifferencevalue').innerHTML = globallayerdifference;
-	document.getElementById('layerdifference').value = globallayerdifference;
+    globallayerdifference = config.layer_difference;
+    document.getElementById('layerdifferencevalue').innerHTML = globallayerdifference;
+    document.getElementById('layerdifference').value = globallayerdifference;
 
+    globalpathprecision = config.path_precision;
+    document.getElementById('pathprecisionvalue').innerHTML = globalpathprecision;
+    document.getElementById('pathprecision').value = globalpathprecision;
 }
 
 // Choose template from gallery
 let chooseGalleryButtons = document.querySelectorAll('.galleryitem a');
 chooseGalleryButtons.forEach(item => {
-	item.addEventListener('click', function (e) {
-		// Load preset template config
-		let i = Array.prototype.indexOf.call(chooseGalleryButtons, item);
-		if (presetConfigs.length > i) {
-			loadConfig(presetConfigs[i]);
-		}
+    item.addEventListener('click', function (e) {
+        // Load preset template config
+        let i = Array.prototype.indexOf.call(chooseGalleryButtons, item);
+        if (presetConfigs.length > i) {
+            loadConfig(presetConfigs[i]);
+        }
 
-		// Set source as specified
-		setSourceAndRestart(this.firstElementChild.src);
-	});
+        // Set source as specified
+        setSourceAndRestart(this.firstElementChild.src);
+    });
 });
 
 // Upload button
@@ -235,7 +257,8 @@ var globalcorner = parseInt(document.getElementById('corner').value),
     globalsplice = parseInt(document.getElementById('splice').value),
     globalfilterspeckle = parseInt(document.getElementById('filterspeckle').value),
     globalcolorprecision = parseInt(document.getElementById('colorprecision').value),
-    globallayerdifference = parseInt(document.getElementById('layerdifference').value);
+    globallayerdifference = parseInt(document.getElementById('layerdifference').value),
+    globalpathprecision = parseInt(document.getElementById('pathprecision').value);
 
 // Load past inputs from localStorage
 /*
@@ -272,6 +295,16 @@ document.getElementById('clustering-color').addEventListener('click', function (
     restart();
 }, false);
 
+document.getElementById('clustering-cutout').addEventListener('click', function (e) {
+    clustering_hierarchical = 'cutout';
+    restart();
+}, false);
+
+document.getElementById('clustering-stacked').addEventListener('click', function (e) {
+    clustering_hierarchical = 'stacked';
+    restart();
+}, false);
+
 document.getElementById('filterspeckle').addEventListener('change', function (e) {
     globalfilterspeckle = parseInt(this.value);
     document.getElementById('filterspecklevalue').innerHTML = this.value;
@@ -308,6 +341,12 @@ document.getElementById('splice').addEventListener('change', function (e) {
     restart();
 });
 
+document.getElementById('pathprecision').addEventListener('change', function (e) {
+    globalpathprecision = parseInt(this.value);
+    document.getElementById('pathprecisionvalue').innerHTML = this.value;
+    restart();
+});
+
 // Save inputs before unloading
 /*
 window.addEventListener('beforeunload', function () {
@@ -322,9 +361,19 @@ window.addEventListener('beforeunload', function () {
 function setSourceAndRestart(source) {
     img.src = source instanceof File ? URL.createObjectURL(source) : source;
     img.onload = function () {
-        svg.setAttribute('viewBox', `0 0 ${img.naturalWidth} ${img.naturalHeight}`);
+        const width = img.naturalWidth, height = img.naturalHeight;
+        svg.setAttribute('viewBox', `0 0 ${width} ${height}`);
         canvas.width = img.naturalWidth;
         canvas.height = img.naturalHeight;
+        if (height > width) {
+            document.getElementById('canvas-container').style.width = '50%';
+            document.getElementById('canvas-container').style.marginBottom = (height / width * 50) + '%';
+        } else {
+            document.getElementById('canvas-container').style.width = '';
+            document.getElementById('canvas-container').style.marginBottom = (height / width * 100) + '%';
+        }
+        ctx.drawImage(img, 0, 0, canvas.width, canvas.height);
+        ctx.getImageData(0, 0, canvas.width, canvas.height);
         restart();
     }
     // Show display
@@ -342,6 +391,10 @@ function restart() {
         el.style.display = clustering_mode == 'color' ? '' : 'none';
     });
 
+    document.getElementById('clustering-cutout').classList.remove('selected');
+    document.getElementById('clustering-stacked').classList.remove('selected');
+    document.getElementById('clustering-' + clustering_hierarchical).classList.add('selected');
+
     document.getElementById('none').classList.remove('selected');
     document.getElementById('polygon').classList.remove('selected');
     document.getElementById('spline').classList.remove('selected');
@@ -363,6 +416,7 @@ function restart() {
         'svg_id': svg.id,
         'mode': mode,
         'clustering_mode': clustering_mode,
+        'hierarchical': clustering_hierarchical,
         'corner_threshold': deg2rad(globalcorner),
         'length_threshold': globallength,
         'max_iterations': 10,
@@ -370,6 +424,7 @@ function restart() {
         'filter_speckle': globalfilterspeckle*globalfilterspeckle,
         'color_precision': 8-globalcolorprecision,
         'layer_difference': globallayerdifference,
+        'path_precision': globalpathprecision,
     });
     if (runner) {
         runner.stop();
@@ -393,7 +448,7 @@ class ConverterRunner {
         this.converter.init();
         this.stopped = false;
         if (clustering_mode == 'binary') {
-            svg.style.background = '#000';
+            svg.style.background = '#fff';
             canvas.style.display = 'none';
         } else {
             svg.style.background = '';

webapp/app/package.json

@@ -2,7 +2,7 @@
   "name": "vtracer-app",
   "version": "0.1.0",
   "description": "VTracer Webapp",
-  "author": "Chris Tsang <tyt2y7@gmail.com>",
+  "author": "Chris Tsang <chris.2y3@outlook.com>",
   "license": "proprietary",
   "private": true,
   "main": "index.js",

webapp/src/canvas.rs

@@ -46,7 +46,7 @@ impl Canvas {
         image.data().to_vec()
     }
 
-    pub fn get_image_data_as_image(&self, x: u32, y: u32, width: u32, height: u32) -> ColorImage {
+    pub fn get_image_data_as_color_image(&self, x: u32, y: u32, width: u32, height: u32) -> ColorImage {
         ColorImage {
             pixels: self.get_image_data(x, y, width, height),
             width: width as usize,

webapp/src/conversion/binary_image.rs

@@ -17,6 +17,7 @@ pub struct BinaryImageConverterParams {
     pub max_iterations: usize,
     pub splice_threshold: f64,
     pub filter_speckle: usize,
+    pub path_precision: u32,
 }
 
 #[wasm_bindgen]
@@ -54,7 +55,7 @@ impl BinaryImageConverter {
     pub fn init(&mut self) {
         let width = self.canvas.width() as u32;
         let height = self.canvas.height() as u32;
-        let image = self.canvas.get_image_data_as_image(0, 0, width, height);
+        let image = self.canvas.get_image_data_as_color_image(0, 0, width, height);
         let binary_image = image.to_binary_image(|x| x.r < 128);
         self.clusters = binary_image.to_clusters(false);
         self.canvas.log(&format!(
@@ -76,10 +77,11 @@ impl BinaryImageConverter {
                     self.params.max_iterations,
                     self.params.splice_threshold
                 );
-                let color = Color::color(&ColorName::White);
+                let color = Color::color(&ColorName::Black);
                 self.svg.prepend_path(
                     &paths,
                     &color,
+                    Some(self.params.path_precision),
                 );
             }
             self.counter += 1;

webapp/src/conversion/color_image.rs

@@ -1,6 +1,6 @@
 use wasm_bindgen::prelude::*;
-use visioncortex::PathSimplifyMode;
-use visioncortex::color_clusters::{IncrementalBuilder, Clusters, Runner, RunnerConfig};
+use visioncortex::{Color, ColorImage, PathSimplifyMode};
+use visioncortex::color_clusters::{Clusters, Runner, RunnerConfig, HIERARCHICAL_MAX, IncrementalBuilder, KeyingAction};
 
 use crate::canvas::*;
 use crate::svg::*;
@@ -8,11 +8,14 @@ use crate::svg::*;
 use serde::Deserialize;
 use super::util;
 
+const KEYING_THRESHOLD: f32 = 0.2;
+
 #[derive(Debug, Deserialize)]
 pub struct ColorImageConverterParams {
     pub canvas_id: String,
     pub svg_id: String,
     pub mode: String,
+    pub hierarchical: String,
     pub corner_threshold: f64,
     pub length_threshold: f64,
     pub max_iterations: usize,
@@ -20,6 +23,7 @@ pub struct ColorImageConverterParams {
     pub filter_speckle: usize,
     pub color_precision: i32,
     pub layer_difference: i32,
+    pub path_precision: u32,
 }
 
 #[wasm_bindgen]
@@ -35,6 +39,7 @@ pub struct ColorImageConverter {
 pub enum Stage {
     New,
     Clustering(IncrementalBuilder),
+    Reclustering(IncrementalBuilder),
     Vectorize(Clusters),
 }
 
@@ -64,8 +69,29 @@ impl ColorImageConverter {
     pub fn init(&mut self) {
         let width = self.canvas.width() as u32;
         let height = self.canvas.height() as u32;
-        let image = self.canvas.get_image_data_as_image(0, 0, width, height);
+        let mut image = self.canvas.get_image_data_as_color_image(0, 0, width, height);
+
+        let key_color = if Self::should_key_image(&image) {
+            if let Ok(key_color) = Self::find_unused_color_in_image(&image) {
+                for y in 0..height as usize {
+                    for x in 0..width as usize {
+                        if image.get_pixel(x, y).a == 0 {
+                            image.set_pixel(x, y, &key_color);
+                        }
+                    }
+                }
+                key_color
+            } else {
+                Color::default()
+            }
+        } else {
+            // The default color is all zeroes, which is treated by visioncortex as a special value meaning no keying will be applied.
+            Color::default()
+        };
+
         let runner = Runner::new(RunnerConfig {
+            diagonal: self.params.layer_difference == 0,
+            hierarchical: HIERARCHICAL_MAX,
             batch_size: 25600,
             good_min_area: self.params.filter_speckle,
             good_max_area: (width * height) as usize,
@@ -73,6 +99,12 @@ impl ColorImageConverter {
             is_same_color_b: 1,
             deepen_diff: self.params.layer_difference,
             hollow_neighbours: 1,
+            key_color,
+            keying_action: if self.params.hierarchical == "cutout" {
+                KeyingAction::Keep
+            } else {
+                KeyingAction::Discard
+            },
         }, image);
         self.stage = Stage::Clustering(runner.start());
     }
@@ -84,6 +116,37 @@ impl ColorImageConverter {
             },
             Stage::Clustering(builder) => {
                 self.canvas.log("Clustering tick");
+                if builder.tick() {
+                    match self.params.hierarchical.as_str() {
+                        "stacked" => {
+                            self.stage = Stage::Vectorize(builder.result());
+                        },
+                        "cutout" => {
+                            let clusters = builder.result();
+                            let view = clusters.view();
+                            let image = view.to_color_image();
+                            let runner = Runner::new(RunnerConfig {
+                                diagonal: false,
+                                hierarchical: 64,
+                                batch_size: 25600,
+                                good_min_area: 0,
+                                good_max_area: (image.width * image.height) as usize,
+                                is_same_color_a: 0,
+                                is_same_color_b: 1,
+                                deepen_diff: 0,
+                                hollow_neighbours: 0,
+                                key_color: Default::default(),
+                                keying_action: KeyingAction::Discard,
+                            }, image);
+                            self.stage = Stage::Reclustering(runner.start());
+                        },
+                        _ => panic!("unknown hierarchical `{}`", self.params.hierarchical)
+                    }
+                }
+                false
+            },
+            Stage::Reclustering(builder) => {
+                self.canvas.log("Reclustering tick");
                 if builder.tick() {
                     self.stage = Stage::Vectorize(builder.result())
                 }
@@ -104,6 +167,7 @@ impl ColorImageConverter {
                     self.svg.prepend_path(
                         &paths,
                         &cluster.residue_color(),
+                        Some(self.params.path_precision),
                     );
                     self.counter += 1;
                     false
@@ -123,10 +187,65 @@ impl ColorImageConverter {
             Stage::Clustering(builder) => {
                 builder.progress() / 2
             },
+            Stage::Reclustering(_builder) => {
+                50
+            },
             Stage::Vectorize(clusters) => {
                 50 + 50 * self.counter as u32 / clusters.view().clusters_output.len() as u32
             }
         }) as i32
     }
 
+    fn color_exists_in_image(img: &ColorImage, color: Color) -> bool {
+        for y in 0..img.height {
+            for x in 0..img.width {
+                let pixel_color = img.get_pixel(x, y);
+                if pixel_color.r == color.r && pixel_color.g == color.g && pixel_color.b == color.b {
+                    return true
+                }
+            }
+        }
+        false
+    }
+    
+    fn find_unused_color_in_image(img: &ColorImage) -> Result<Color, String> {
+        let special_colors = IntoIterator::into_iter([
+            Color::new(255, 0,   0),
+            Color::new(0,   255, 0),
+            Color::new(0,   0,   255),
+            Color::new(255, 255, 0),
+            Color::new(0,   255, 255),
+            Color::new(255, 0,   255),
+            Color::new(128, 128, 128),
+        ]);
+        for color in special_colors {
+            if !Self::color_exists_in_image(img, color) {
+                return Ok(color);
+            }
+        }
+        Err(String::from("unable to find unused color in image to use as key"))
+    }
+    
+    fn should_key_image(img: &ColorImage) -> bool {
+        if img.width == 0 || img.height == 0 {
+            return false;
+        }
+    
+        // Check for transparency at several scanlines
+        let threshold = ((img.width * 2) as f32 * KEYING_THRESHOLD) as usize;
+        let mut num_transparent_pixels = 0;
+        let y_positions = [0, img.height / 4, img.height / 2, 3 * img.height / 4, img.height - 1];
+        for y in y_positions {
+            for x in 0..img.width {
+                if img.get_pixel(x, y).a == 0 {
+                    num_transparent_pixels += 1;
+                }
+                if num_transparent_pixels >= threshold {
+                    return true;
+                }
+            }
+        }
+    
+        false
+    }
 }

webapp/src/conversion/mod.rs

@@ -1,6 +1,3 @@
 mod binary_image;
 mod color_image;
 mod util;
-
-pub use binary_image::*;
-pub use color_image::*;

webapp/src/lib.rs

@@ -7,7 +7,9 @@
 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
-
+#![doc(
+    html_logo_url = "https://github.com/visioncortex/vtracer/raw/master/docs/images/visioncortex icon.png"
+)]
 use wasm_bindgen::prelude::*;
 
 mod conversion;

webapp/src/svg.rs

@@ -13,11 +13,11 @@ impl Svg {
         Self { element }
     }
 
-    pub fn prepend_path(&mut self, paths: &CompoundPath, color: &Color) {
+    pub fn prepend_path(&mut self, paths: &CompoundPath, color: &Color, precision: Option<u32>) {
         let path = document()
             .create_element_ns(Some("http://www.w3.org/2000/svg"), "path")
             .unwrap();
-        let (string, offset) = paths.to_svg_string(true, PointF64::default());
+        let (string, offset) = paths.to_svg_string(true, PointF64::default(), precision);
         path.set_attribute("d", &string).unwrap();
         path.set_attribute(
             "transform",