0.6.1

* - Cargo.toml:  add `crate-type = ["cdylib"] to [lib]; lacking this is what was causing the executable to be put in wheels
- pyproject.toml: add "python-binding" to features for conditional compilation
- main.rs:  `cargo build` was failing for the vtracer executable; I think the previous import scheme had an implicit dependency on the library being built and called 'vtracer'. The other way to do this would have been to add an explicit dependency to the [[bin]], but making explicit imports here solves things directly

* re-enable linux builds; features are defined in the pyproject.toml now rather than in the workflow arguments

* And publish Linux, too!

.gitattributes

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

.github/workflows/python.yml

@@ -0,0 +1,121 @@
+# This file is autogenerated by maturin v1.2.3
+# To update, run
+#
+#    maturin generate-ci github
+#
+name: python
+
+on:
+  push:
+    tags:
+      - '*'
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  linux:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        target: [x86_64, x86, aarch64, armv7, s390x, ppc64le]
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: -m cmdapp/Cargo.toml --release --out dist --find-interpreter
+          sccache: 'true'
+          manylinux: auto
+      - name: Upload wheels
+        uses: actions/upload-artifact@v3
+        with:
+          name: wheels
+          path: dist
+
+  windows:
+    runs-on: windows-latest
+    strategy:
+      matrix:
+        target: [x64, x86]
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+          architecture: ${{ matrix.target }}
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: -m cmdapp/Cargo.toml --release --out dist --find-interpreter
+          sccache: 'true'
+      - name: Upload wheels
+        uses: actions/upload-artifact@v3
+        with:
+          name: wheels
+          path: dist
+
+  macos:
+    runs-on: macos-latest
+    strategy:
+      matrix:
+        target: [x86_64, aarch64]
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: -m cmdapp/Cargo.toml --release --out dist --find-interpreter
+          sccache: 'true'
+      - name: Upload wheels
+        uses: actions/upload-artifact@v3
+        with:
+          name: wheels
+          path: dist
+
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Build sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: -m cmdapp/Cargo.toml --out dist
+      - name: Upload sdist
+        uses: actions/upload-artifact@v3
+        with:
+          name: wheels
+          path: dist
+
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    # Specifying a GitHub environment is optional, but strongly encouraged
+    environment: python
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+    if: "startsWith(github.ref, 'refs/tags/')"
+    needs: [windows, macos, sdist, linux] 
+    steps:
+      - uses: actions/download-artifact@v3
+        with:
+          name: wheels
+      - name: Publish to PyPI
+        uses: PyO3/maturin-action@v1
+        with:
+          command: upload
+          args: --non-interactive --skip-existing *
+          # manylinux: auto

.github/workflows/rust.yml

@@ -0,0 +1,22 @@
+name: Rust
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+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,40 @@
+# 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.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

@@ -1,6 +1,7 @@
 [workspace]
 
 members = [
-	"cmdapp",
+    "cmdapp",
     "webapp",
-]
+]
+resolver = "2"

LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) 2022 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.

README.md

@@ -0,0 +1,131 @@
+<div align="center">
+
+  <img src="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).
+
+## 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 + wasm platform.
+
+![screenshot](docs/images/screenshot-01.png)
+
+![screenshot](docs/images/screenshot-02.png)
+
+## 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
+```
+
+## In the wild
+
+VTracer is used by the following projects (feel free 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>
+
+## What's next?
+
+There are several things in my mind:
+
+1. 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.
+
+2. Perfect cut-out mode. Right now in cut-out mode, the shapes do not share perfect boundaries, but have seams.
+
+3. 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

@@ -0,0 +1,27 @@
+# Version 0.6.0 (2023-09-08)
+
+-   Python bindings
+
+# Version 0.5.0 (2022-10-09)
+
+-   Handle transparent png images
+
+# Version 0.4.0 (2021-07-23)
+
+-   SVG path string numeric precision
+
+# Version 0.3.0 (2021-01-24)
+
+-   Added cutout mode
+
+# Version 0.2.0 (2020-11-15)
+
+-   Use relative & closed paths
+
+# Version 0.1.1 (2020-11-01)
+
+-   SVG namespace
+
+# Version 0.1.0 (2020-10-31)
+
+-   Initial release

Readme.md

@@ -1,52 +0,0 @@
-![logo](docs/images/visioncortex-banner.png)
-
-# visioncortex VTracer
-
-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 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.
-
-A technical description of the algorithm is on [visioncortex.org/vtracer-docs](//www.visioncortex.org/vtracer-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.
-
-![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                   
-```
-
-### Usage
-```
-./vtracer --input input.jpg --output output.svg
-```

cmdapp/Cargo.toml

@@ -1,8 +1,8 @@
 [package]
 name = "vtracer"
-version = "0.1.0"
-authors = ["Chris Tsang <tyt2y7@gmail.com>"]
-edition = "2018"
+version = "0.6.1"
+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"
 homepage = "http://www.visioncortex.org/vtracer"
@@ -13,4 +13,13 @@ keywords = ["svg", "computer-graphics"]
 [dependencies]
 clap = "2.33.3"
 image = "0.23.10"
-visioncortex = "0.2.0"
+visioncortex = { version = "0.8.1" }
+fastrand = "1.8"
+pyo3 = { version = "0.19.0", optional = true }
+
+[features]
+python-binding = ["pyo3"]
+
+[lib]
+name = "vtracer"
+crate-type = ["cdylib"]

cmdapp/LICENSE-MIT

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

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,28 @@
+[project]
+name = "vtracer"
+version = "0.6.10"
+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"
+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"
+sdist-include = ["LICENSE-MIT", "vtracer/README.md"]

cmdapp/src/config.rs

@@ -1,7 +1,7 @@
 use std::str::FromStr;
 use std::path::PathBuf;
 use clap::{Arg, App};
-use visioncortex::path::PathSimplifyMode;
+use visioncortex::PathSimplifyMode;
 
 pub enum Preset {
     Bw,
@@ -9,18 +9,22 @@ pub enum Preset {
     Photo
 }
 
-#[derive(Debug)]
 pub enum ColorMode {
     Color,
     Binary,
 }
 
+pub enum Hierarchical {
+    Stacked,
+    Cutout,
+}
+
 /// Converter config
-#[derive(Debug)]
 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,14 @@ pub struct Config {
     pub length_threshold: f64,
     pub max_iterations: usize,
     pub splice_threshold: i32,
+    pub path_precision: Option<u32>,
 }
 
-#[derive(Debug)]
 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,6 +49,7 @@ 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 {
@@ -52,6 +58,7 @@ impl Default for Config {
             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 +67,7 @@ impl Default for Config {
             length_threshold: 4.0,
             splice_threshold: 45,
             max_iterations: 10,
+            path_precision: Some(8),
         }
     }
 }
@@ -76,6 +84,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;
 
@@ -100,7 +120,8 @@ fn path_simplify_mode_from_str(s: &str) -> PathSimplifyMode {
 
 impl Config {
     pub fn from_args() -> Self {
-        let app = App::new("visioncortex VTracer").about("A cmd app to convert images into vector graphics.");
+        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")
@@ -121,6 +142,14 @@ impl Config {
             .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)
@@ -168,6 +197,11 @@ impl Config {
             .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();
 
@@ -186,6 +220,10 @@ impl Config {
             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" {
@@ -195,19 +233,19 @@ impl Config {
             } else if value == "spline" {
                 "spline"
             } else {
-                panic!("Parser Error: Curve fitting mode is invalid with value {}", value);
+                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 < 1 || value > 16 {
-                    panic!("Out of Range Error: Filter speckle is invalid at {}. It must be within [1,16].", value);
+                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 with value {}.", value);
+                panic!("Parser Error: Filter speckle is not a positive integer: {}.", value);
             }
         }
 
@@ -219,7 +257,7 @@ impl Config {
                 }
                 config.color_precision = value;
             } else {
-                panic!("Parser Error: Color precision is not an integer with value {}.", value);
+                panic!("Parser Error: Color precision is not an integer: {}.", value);
             }
         }
 
@@ -231,7 +269,7 @@ impl Config {
                 }
                 config.layer_difference = value;
             } else {
-                panic!("Parser Error: Gradient step is not an integer with value {}.", value);
+                panic!("Parser Error: Gradient step is not an integer: {}.", value);
             }
         }
 
@@ -243,7 +281,7 @@ impl Config {
                 }
                 config.corner_threshold = value
             } else {
-                panic!("Parser Error: Corner threshold is not numeric with value {}.", value);
+                panic!("Parser Error: Corner threshold is not numeric: {}.", value);
             }
         }
 
@@ -255,7 +293,7 @@ impl Config {
                 }
                 config.length_threshold = value;
             } else {
-                panic!("Parser Error: Segment length is not numeric with value {}.", value);
+                panic!("Parser Error: Segment length is not numeric: {}.", value);
             }
         }
 
@@ -267,7 +305,16 @@ impl Config {
                 }
                 config.splice_threshold = value;
             } else {
-                panic!("Parser Error: Segment length is not numeric with value {}.", value);
+                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);
             }
         }
 
@@ -282,6 +329,7 @@ impl Config {
                 input_path,
                 output_path,
                 color_mode: ColorMode::Binary,
+                hierarchical: Hierarchical::Stacked,
                 filter_speckle: 4,
                 color_precision: 6,
                 layer_difference: 16,
@@ -290,11 +338,13 @@ impl Config {
                 length_threshold: 4.0,
                 max_iterations: 10,
                 splice_threshold: 45,
+                path_precision: Some(8),
             },
             Preset::Poster => Self {
                 input_path,
                 output_path,
                 color_mode: ColorMode::Color,
+                hierarchical: Hierarchical::Stacked,
                 filter_speckle: 4,
                 color_precision: 8,
                 layer_difference: 16,
@@ -303,11 +353,13 @@ impl Config {
                 length_threshold: 4.0,
                 max_iterations: 10,
                 splice_threshold: 45,
+                path_precision: Some(8),
             },
             Preset::Photo => Self {
                 input_path,
                 output_path,
                 color_mode: ColorMode::Color,
+                hierarchical: Hierarchical::Stacked,
                 filter_speckle: 10,
                 color_precision: 8,
                 layer_difference: 48,
@@ -316,6 +368,7 @@ impl Config {
                 length_threshold: 4.0,
                 max_iterations: 10,
                 splice_threshold: 45,
+                path_precision: Some(8),
             }
         }
     }
@@ -325,6 +378,7 @@ impl Config {
             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,
@@ -333,6 +387,7 @@ impl Config {
             length_threshold: self.length_threshold,
             max_iterations: self.max_iterations,
             splice_threshold: deg2rad(self.splice_threshold),
+            path_precision: self.path_precision,
         }
     }
 }

cmdapp/src/converter.rs

@@ -1,10 +1,17 @@
 use std::path::PathBuf;
 use std::{fs::File, io::Write};
 
-use visioncortex::{Color, ColorImage, ColorName, color_clusters::RunnerConfig, color_clusters::Runner};
-use super::config::{Config, ColorMode, ConverterConfig};
+use fastrand::Rng;
+use visioncortex::{Color, ColorImage, ColorName};
+use visioncortex::color_clusters::{Runner, RunnerConfig, KeyingAction, HIERARCHICAL_MAX};
+use super::config::{Config, ColorMode, Hierarchical, ConverterConfig};
 use super::svg::SvgFile;
 
+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 image file into svg file
 pub fn convert_image_to_svg(config: Config) -> Result<(), String> {
     let config = config.into_converter_config();
@@ -14,8 +21,68 @@ pub fn convert_image_to_svg(config: Config) -> Result<(), String> {
     }
 }
 
+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 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;
+    }
+
+    // Check for transparency at several scanlines
+    let threshold = ((img.width * 2) as f32 * KEYING_THRESHOLD) as usize;
+    let mut num_transparent_boundary_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_boundary_pixels += 1;
+            }
+            if num_transparent_boundary_pixels >= threshold {
+                return true;
+            }
+        }
+    }
+
+    false
+}
+
 fn color_image_to_svg(config: ConverterConfig) -> Result<(), String> {
-    let (img, width, height);
+    let (mut img, width, height);
     match read_image(config.input_path) {
         Ok(values) => {
             img = values.0;
@@ -25,7 +92,24 @@ fn color_image_to_svg(config: ConverterConfig) -> Result<(), String> {
         Err(msg) => return Err(msg),
     }
 
+    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),
@@ -33,16 +117,44 @@ fn color_image_to_svg(config: ConverterConfig) -> Result<(), String> {
         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 clusters = runner.run();
+    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 svg_path = cluster.to_svg_path(
+        let paths = cluster.to_compound_path(
             &view,
             false,
             config.mode,
@@ -51,22 +163,14 @@ fn color_image_to_svg(config: ConverterConfig) -> Result<(), String> {
             config.max_iterations,
             config.splice_threshold
         );
-        svg.add_path(svg_path, cluster.residue_color());
+        svg.add_path(paths, cluster.residue_color());
     }
 
-    let out_file = File::create(config.output_path);
-    let mut out_file = match out_file {
-        Ok(file) => file,
-        Err(_) => return Err(String::from("Cannot create output file.")),
-    };
-    
-    out_file.write_all(&svg.to_svg_file().as_bytes()).unwrap();
-
-    Ok(())
+    write_svg(svg, config.output_path)
 }
 
 fn binary_image_to_svg(config: ConverterConfig) -> Result<(), String> {
-    
+
     let (img, width, height);
     match read_image(config.input_path) {
         Ok(values) => {
@@ -79,20 +183,19 @@ fn binary_image_to_svg(config: ConverterConfig) -> Result<(), String> {
     let img = img.to_binary_image(|x| x.r < 128);
 
     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 {
-            let svg_path = cluster.to_svg_path(
+            let paths = cluster.to_compound_path(
                 config.mode,
                 config.corner_threshold,
                 config.length_threshold,
                 config.max_iterations,
                 config.splice_threshold,
             );
-            let color = Color::color(&ColorName::Black);
-            svg.add_path(svg_path, color);
+            svg.add_path(paths, Color::color(&ColorName::Black));
         }
     }
 
@@ -102,7 +205,7 @@ fn binary_image_to_svg(config: ConverterConfig) -> Result<(), String> {
 fn read_image(input_path: PathBuf) -> Result<(ColorImage, usize, usize), 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")),
     };
 
@@ -118,8 +221,8 @@ fn write_svg(svg: SvgFile, output_path: PathBuf) -> Result<(), String> {
         Ok(file) => file,
         Err(_) => return Err(String::from("Cannot create output file.")),
     };
-    
-    out_file.write_all(&svg.to_svg_file().as_bytes()).unwrap();
+
+    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.
 //
@@ -11,7 +11,11 @@
 mod config;
 mod converter;
 mod svg;
+#[cfg(feature = "python-binding")]
+mod python;
 
 pub use config::*;
 pub use converter::*;
-pub use svg::*;
+pub use svg::*;
+#[cfg(feature = "python-binding")]
+pub use python::*;

cmdapp/src/main.rs

@@ -1,8 +1,10 @@
-use vtracer::{Config, convert_image_to_svg};
+mod config;
+mod converter;
+mod svg;
 
 fn main() {
-    let config = Config::from_args();
-    let result = convert_image_to_svg(config);
+    let config = config::Config::from_args();
+    let result = converter::convert_image_to_svg(config);
     match result {
         Ok(()) => {
             println!("Conversion successful.");

cmdapp/src/python.rs

@@ -0,0 +1,81 @@
+use crate::*;
+use pyo3::prelude::*;
+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);
+
+    // 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);
+
+    let config = Config {
+        input_path,
+        output_path,
+        color_mode,
+        hierarchical,
+        filter_speckle,
+        color_precision,
+        layer_difference,
+        mode,
+        corner_threshold,
+        length_threshold,
+        max_iterations,
+        splice_threshold,
+        path_precision,
+        ..Default::default()
+    };
+
+    convert_image_to_svg(config).unwrap();
+    Ok(())
+}
+
+/// 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)?)?;
+    Ok(())
+}

cmdapp/src/svg.rs

@@ -1,43 +1,66 @@
-use visioncortex::Color;
-
-pub struct SvgPath {
-    path: String,
-    color: Color,
-}
+use std::fmt;
+use visioncortex::{Color, CompoundPath, PointF64};
 
 pub struct SvgFile {
-    patches: Vec<SvgPath>,
-    width: usize,
-    height: usize,
+    pub paths: Vec<SvgPath>,
+    pub width: usize,
+    pub height: usize,
+    pub path_precision: Option<u32>,
+}
+
+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 {
-            patches: vec![],
+            paths: vec![],
             width,
             height,
+            path_precision,
         }
     }
 
-    pub fn add_path(&mut self, path: String, color: Color) {
-        self.patches.push(SvgPath {
+    pub fn add_path(&mut self, path: CompoundPath, color: Color) {
+        self.paths.push(SvgPath {
             path,
-            color
+            color,
         })
     }
+}
 
-    pub fn to_svg_file(&self) -> String {
-        let mut result: Vec<String> = vec![format!(r#"<?xml version="1.0" encoding="UTF-8"?>
-        <svg width="{}" height="{}">
-        "#, self.width, self.height)];
+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, 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 patch in &self.patches {
-            let color = patch.color;
-            result.push(format!("<path d=\"{}\" fill=\"#{:02x}{:02x}{:02x}\"/>\n", patch.path, color.r, color.g, color.b));
+        for path in &self.paths {
+            path.fmt_with_precision(f, self.path_precision)?;
         };
 
-        result.push(String::from("</svg>"));
-        result.concat()
+        writeln!(f, "</svg>")
+    }
+}
+
+impl fmt::Display for SvgPath {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        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
+        )
     }
 }

cmdapp/vtracer/README.md

@@ -0,0 +1,75 @@
+<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')
+
+# All the bells & whistles
+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 @@
+from .vtracer import convert_image_to_svg_py

cmdapp/vtracer/vtracer.pyi

@@ -0,0 +1,17 @@
+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:
+    ...

docs/COPYRIGHT

@@ -0,0 +1,3 @@
+Copyright (c) 2020 Tsang Hao Fung
+
+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":"a62b3494f02004811a57"}[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

@@ -11,6 +11,13 @@
         <!-- UIkit JS -->
         <script src="./uikit/js/uikit.min.js"></script>
         <script src="./uikit/js/uikit-icons.min.js"></script>
+        <script type="text/javascript">
+        (function(c,l,a,r,i,t,y){
+            c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};
+            t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;
+            y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);
+        })(window, document, "clarity", "script", "403biw7tra");
+        </script>
         <style>
         html, body {
             width: 100%;
@@ -72,8 +79,7 @@
         }
         #canvas-container {
             position: relative;
-            width: 100%;
-            height: 100%;
+            height: max-content;
         }
         #svg, #frame {
             position: absolute;
@@ -84,7 +90,7 @@
             stroke: #ff0;
         }
         #droptext {
-            height: 100%;
+            height: 480px;
             color: #CC972E;
         }
         input[type=range]::-webkit-slider-thumb {
@@ -100,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;
@@ -133,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>    
@@ -145,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">
@@ -153,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 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>
@@ -186,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>
@@ -195,7 +210,7 @@
                     4
                 </div>
                 <div class="uk-width-5-6">
-                    <input id="filterspeckle" class="uk-range" type="range" min="1" max="16" 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">
@@ -219,7 +234,7 @@
                     16
                 </div>
                 <div class="clustering-color-options uk-width-5-6">
-                    <input id="layerdifference" class="uk-range" type="range" min="0" max="255" step="1" value="16">
+                    <input id="layerdifference" class="uk-range" type="range" min="0" max="128" step="1" value="16">
                 </div>
 
                 <div class="uk-width-1-1 uk-flex uk-flex-right">
@@ -262,7 +277,7 @@
 
                 <div class="spline-options uk-width-1-1 uk-flex uk-flex-right">
                     <div uk-tooltip="pos: left; title: Minimum Angle Displacement (in degrees) to be considered a cutting point between curves">
-                        Splice Threshold <span class="uk-text-meta">(More accurate)</span>
+                        Splice Threshold <span class="uk-text-meta">(Less accurate)</span>
                     </div>
                 </div>
                 <div id="splicevalue" class="spline-options uk-width-1-6">
@@ -272,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,9 +1,10 @@
 [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"
 repository = "https://github.com/visioncortex/vtracer/"
 categories = ["graphics"]
@@ -21,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.2.0"
+visioncortex = "0.6.0"
 
 # 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,22 +15,22 @@ 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
@@ -49,8 +49,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 +64,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 +79,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 +94,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 +106,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 +121,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 +253,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 +291,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 +337,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 +357,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 +387,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 +412,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 +420,7 @@ function restart() {
         'filter_speckle': globalfilterspeckle*globalfilterspeckle,
         'color_precision': 8-globalcolorprecision,
         'layer_difference': globallayerdifference,
+        'path_precision': globalpathprecision,
     });
     if (runner) {
         runner.stop();
@@ -430,5 +481,6 @@ class ConverterRunner {
 
     stop () {
         this.stopped = true;
+        this.converter.free();
     }
 }

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

@@ -1,5 +1,5 @@
 use wasm_bindgen::prelude::*;
-use visioncortex::{clusters::Clusters, Color, ColorName, PointI32, PathSimplifyMode};
+use visioncortex::{clusters::Clusters, Color, ColorName, PathSimplifyMode};
 
 use crate::{canvas::*};
 use crate::svg::*;
@@ -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!(
@@ -69,7 +70,7 @@ impl BinaryImageConverter {
             self.canvas.log(&format!("tick {}", self.counter));
             let cluster = self.clusters.get_cluster(self.counter);
             if cluster.size() >= self.params.filter_speckle {
-                let svg_path = cluster.to_svg_path(
+                let paths = cluster.to_compound_path(
                     self.mode,
                     self.params.corner_threshold,
                     self.params.length_threshold,
@@ -77,10 +78,10 @@ impl BinaryImageConverter {
                     self.params.splice_threshold
                 );
                 let color = Color::color(&ColorName::White);
-                self.svg.prepend_path_with_fill(
-                    &svg_path,
-                    &PointI32::default(),
+                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, PointI32};
-use visioncortex::color_clusters::{IncrementalBuilder, Clusters, Runner, RunnerConfig};
+use visioncortex::PathSimplifyMode;
+use visioncortex::color_clusters::{IncrementalBuilder, Clusters, Runner, RunnerConfig, HIERARCHICAL_MAX};
 
 use crate::canvas::*;
 use crate::svg::*;
@@ -13,6 +13,7 @@ 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 +21,7 @@ pub struct ColorImageConverterParams {
     pub filter_speckle: usize,
     pub color_precision: i32,
     pub layer_difference: i32,
+    pub path_precision: u32,
 }
 
 #[wasm_bindgen]
@@ -35,6 +37,7 @@ pub struct ColorImageConverter {
 pub enum Stage {
     New,
     Clustering(IncrementalBuilder),
+    Reclustering(IncrementalBuilder),
     Vectorize(Clusters),
 }
 
@@ -64,8 +67,10 @@ 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 image = self.canvas.get_image_data_as_color_image(0, 0, width, height);
         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,
@@ -84,6 +89,35 @@ 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,
+                            }, 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())
                 }
@@ -94,17 +128,17 @@ impl ColorImageConverter {
                 if self.counter < view.clusters_output.len() {
                     self.canvas.log("Vectorize tick");
                     let cluster = view.get_cluster(view.clusters_output[self.counter]);
-                    let svg_path = cluster.to_svg_path(
+                    let paths = cluster.to_compound_path(
                         &view, false, self.mode,
                         self.params.corner_threshold,
                         self.params.length_threshold,
                         self.params.max_iterations,
                         self.params.splice_threshold
                     );
-                    self.svg.prepend_path_with_fill(
-                        &svg_path,
-                        &PointI32::new(0, 0),
+                    self.svg.prepend_path(
+                        &paths,
                         &cluster.residue_color(),
+                        Some(self.params.path_precision),
                     );
                     self.counter += 1;
                     false
@@ -124,6 +158,9 @@ 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
             }

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

@@ -1,5 +1,5 @@
 use web_sys::Element;
-use visioncortex::{Color, PointI32};
+use visioncortex::{Color, CompoundPath, PointF64};
 use super::common::document;
 
 pub struct Svg {
@@ -13,11 +13,12 @@ impl Svg {
         Self { element }
     }
 
-    pub fn prepend_path_with_fill(&mut self, path_string: &str, offset: &PointI32, 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();
-        path.set_attribute("d", path_string).unwrap();
+        let (string, offset) = paths.to_svg_string(true, PointF64::default(), precision);
+        path.set_attribute("d", &string).unwrap();
         path.set_attribute(
             "transform",
             format!("translate({},{})", offset.x, offset.y).as_str(),