Create Image Stencils in Python

To create an image stencil in Python, configure ImageVectorizer with BezierPathBuilder and StencilConfiguration, set the stencil type and color, call vectorize(input_path), and save the returned SVGDocument as an SVG file.

An image stencil is a simplified vector version of a raster image. Instead of preserving every color and detail, stencil output focuses on clean shapes, outlines, or limited-color regions that can be used for design, print, cutting, templates, and stylized artwork.

When to Use Image Stenciling

Use image stenciling when the final SVG should be intentionally simplified. It is a good fit for artwork that needs strong contours, limited colors, or a single-color graphic style. Logos, icons, signs, line drawings, and high-contrast illustrations usually produce cleaner stencils than noisy photos.

If you want to preserve more source colors and details, use normal image vectorization instead.

Aspose.SVG APIs Used

API	Purpose
ImageVectorizer	Converts the raster source to an SVG document
ImageVectorizerConfiguration	Stores vectorization and stencil settings
BezierPathBuilder	Builds vector paths from traced contours
ImageTraceSmoother	Smooths traced contours before path construction
StencilConfiguration	Configures stencil output
StencilType	Defines the stencil mode
Color	Sets the stencil color

Create Image Stencil in Python

The following example turns image.png into a mono-color stencil SVG. It configures smoothing and path approximation, limits the color count used during vectorization, and applies StencilConfiguration to produce stencil-style output.

import os
from aspose.svg.drawing import Color
from aspose.svg.imagevectorization import (
    BezierPathBuilder,
    ImageTraceSmoother,
    ImageVectorizer,
    StencilConfiguration,
    StencilType,
)

# Create a mono-color SVG stencil from a raster image
input_folder = "data/"
output_folder = "output/"
input_path = os.path.join(input_folder, "image.png")
output_path = os.path.join(output_folder, "image-stencil.svg")
os.makedirs(output_folder, exist_ok=True)

path_builder = BezierPathBuilder()
path_builder.trace_smoother = ImageTraceSmoother(2)
path_builder.error_threshold = 20.0
path_builder.max_iterations = 10

vectorizer = ImageVectorizer()
vectorizer.configuration.path_builder = path_builder
vectorizer.configuration.colors_limit = 5
vectorizer.configuration.line_width = 1.0

stencil_config = StencilConfiguration()
stencil_config.type = StencilType.MONO_COLOR
stencil_config.color = Color.from_rgb(0, 0, 255)
vectorizer.configuration.stencil = stencil_config

with vectorizer.vectorize(input_path) as document:
    document.save(output_path)

The generated image-stencil.svg contains vector geometry styled according to the stencil configuration. Change Color.from_rgb() to set another stencil color, and adjust colors_limit, trace_smoother, and error_threshold to balance detail and simplicity.

Stencil Settings That Affect Output

Setting	Effect	Practical guidance
stencil_config.type	Selects the stencil mode	Use StencilType.MONO_COLOR for single-color stencil artwork
stencil_config.color	Sets the output stencil color	Pick a high-contrast color for previews, print, or cutting workflows
colors_limit	Controls color quantization before stencil output	Lower values simplify the source and usually produce cleaner stencil shapes
trace_smoother	Smooths contour fragments	Increase it to reduce jagged edges, but check small details
error_threshold	Controls path approximation tolerance	Lower values preserve more detail; higher values simplify paths
line_width	Sets the generated line width	Adjust it to match the target visual scale

Common Mistakes and Fixes

Problem	Likely cause	Fix
Stencil has too much detail	Source image is noisy or colors_limit is too high	Preprocess the source, reduce colors, or increase smoothing
Important shapes disappear	Simplification is too aggressive	Lower smoothing or reduce error_threshold
Output looks jagged	Contours were traced with too little smoothing	Increase trace_smoother and inspect the SVG at the target size
Photo output is complex	Continuous-tone photos are difficult to simplify cleanly	Use high-contrast artwork or reduce the photo before vectorization

Related Articles

• Vectorize Images in Python – Convert raster images to SVG and tune vectorization settings.
• Image and Text Vectorization – Compare image vectorization, image stencils, and text vectorization.
• Temporary License – Evaluate Aspose.SVG without evaluation limitations.