pixv

package module

v0.3.0 Latest Latest Go to latest Published: Jul 2, 2025 License: MIT Imports: 9 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/axseem/pixv

Links

Open Source Insights

README ¶

Vectorize your pixel art

What?

A CLI tool for converting raster images into SVG. The tool can convert any PNG/JPEG image, but its primary focus is pixel art. Using photos or other images with high pixel density or a wide range of colors might not produce the desired result.

Why?

Much of the software that displays raster images uses interpolation. This means applications try to create smooth color transitions between adjacent pixels. For small images, and especially pixel art, this behavior is often undesirable as it makes them blurry. Converting a pixel-art image to SVG solves this problem by defining shapes with sharp, scalable edges.

How does it work?

There are several vectorization strategies. They vary in speed, produced file size, and structure. All strategies use the <path/> tag, which allows shapes to be described with the fewest characters possible.

Vectorization Strategies

Square

Simply draws a square for each pixel from the image. This method is very fast and produces a perfect pixel matrix, but the resulting file sizes are large.

pixv_square

Rectangle

Combines adjacent pixels of the same color into rectangular chunks. Generated files are usually much smaller than the Square method, while still preserving great performance.

pixv_rectangle

Path

Traces the outline of same-colored shapes. This is the most efficient method in terms of file size but has the slowest processing time.

pixv_path

Size Comparison

The pixv logo is used for this comparison. Raster images were exported from Krita, removing any metadata and always using lossless quality.

Raster vs Vector

 Scale       1x     8x    32x   128x 
-------------------------------------
 PNG       251B   734B   4.5K    51K 
 JPEG      1.2K   1.0K   9.7K   215K 
-------------------------------------
 SVG       1.3K   1.3K   1.3K   1.3K

Different Strategies

 Scale                           Any 
-------------------------------------
 SVG(Path)                      1.3K 
 SVG(Rectangle)                 1.7K 
 SVG(Square)                    9.8K

How to use?

The following command will create an SVG variant of the given image in the current directory.

pixv image.png

For more information use pixv --help:

NAME:
   pixv - A CLI tool to vectorize pixel-art images

USAGE:
   pixv [global options]

VERSION:
   v0.3.0

AUTHOR:
   axseem: [email protected]

GLOBAL OPTIONS:
   --method string, -m string  Vectorization method: path, rectangle, or square (default: "path")
   --scale int, -s int         Scale multiplier for the output SVG (default: 1)
   --output string, -o string  Output file path. Defaults to input with .svg extension
   --help, -h                  show help
   --version, -v               print the version

How to install?

# Nix
nix profile install github:axseem/pixv

# Go
go install github.com/axseem/pixv@latest

You can also run pixv directly from the GitHub repository without a permanent installation:

nix run github:axseem/pixv

How to build?

git clone https://github.com/axseem/pixv.git
cd pixv
go build

Documentation ¶

Index ¶

func BuildSVG(width, height, scale int, pathsByColor map[color.RGBA][]string) string
func Vectorize(ctx context.Context, img image.Image, opts Options) (string, error)
type ImageData
- func NewImageData(img image.Image) *ImageData
type Options
type Strategy
- func (s Strategy) IsValid() bool

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

func BuildSVG ¶

func BuildSVG(width, height, scale int, pathsByColor map[color.RGBA][]string) string

BuildSVG constructs the final SVG string from the generated path data.

func Vectorize ¶

func Vectorize(ctx context.Context, img image.Image, opts Options) (string, error)

Vectorize converts a raster image into an SVG string using the specified options.

Types ¶

type ImageData ¶

type ImageData struct {
	// contains filtered or unexported fields
}

ImageData holds a pre-processed, optimized representation of an image.

func NewImageData ¶

func NewImageData(img image.Image) *ImageData

NewImageData creates a new ImageData object from a standard image.Image.

func (*ImageData) At ¶

func (d *ImageData) At(x, y int) color.RGBA

At returns the color of the pixel at (x, y).

func (*ImageData) Bounds ¶

func (d *ImageData) Bounds() image.Rectangle

Bounds returns the image dimensions.

func (*ImageData) IsVisited ¶

func (d *ImageData) IsVisited(x, y int) bool

IsVisited checks if the pixel at (x, y) has been visited. This is thread-safe.

func (*ImageData) Visit ¶

func (d *ImageData) Visit(x, y int) bool

Visit marks the pixel at (x, y) as visited. It returns true if the pixel was successfully marked. This is thread-safe.

type Options ¶

type Options struct {
	Method Strategy
	Scale  int
}

Options configures the vectorization process.

type Strategy ¶

type Strategy string

Strategy defines the vectorization algorithm to use.

const (
	StrategyPath      Strategy = "path"
	StrategyRectangle Strategy = "rectangle"
	StrategySquare    Strategy = "square"
)

func (Strategy) IsValid ¶

func (s Strategy) IsValid() bool

IsValid checks if the strategy is a recognized value.

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
cmd
pixv command

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL