Guide · Open source
How to use Primitive: rebuild images from shapes
Updated · written with AI from the project's own documentation and checked against our catalogue data
Primitive is an open-source tool that rebuilds a picture out of simple geometric shapes such as triangles, ellipses and rectangles. It adds one shape at a time, choosing each shape so the result moves closer to the original, which gives an abstract, artistic look. This guide shows you how to install it with Go, run it on your own image, and choose the shape type, shape count and output format.
Primitivefogleman/primitive · ★ 13.6k · MIT Install options & downloads Quick start
- 1Install Go. Download and install Go from golang.org, following the official install guide.
- 2Install Primitive. Run go get -u github.com/fogleman/primitive in your terminal.
- 3Prepare a small image. Resize your input to about 256x256px, since small inputs run faster and keep enough detail.
- 4Run the command. Use primitive -i input.png -o output.png -n 100 to build the image from 100 shapes.
- 5Pick a shape mode. Use the -m flag to choose triangles, rectangles, ellipses, circles or another supported shape.
- 6Export your result. Use a .png, .jpg, .svg or .gif output name, and add a second -o flag to save more than one format.
What does Primitive do?
You give Primitive a target image. It starts with a blank canvas filled with the average colour of that image, then searches for the single best shape to draw on top. It repeats this process, adding one shape at a time.
The README says around 50 to 200 shapes are usually needed to reach a result that is recognisable yet artistic and abstract. The output is a stylised approximation, not an exact copy of the photo.
Install Primitive with Go
Primitive is a command-line tool written in Go. The README asks you to install Go first from the official Go install guide at golang.org, then run the install command below.
- Install Go from golang.org/doc/install.
- Run the install command in your terminal.
go get -u github.com/fogleman/primitiveRun Primitive on your own image
Use a small input image. The README suggests about 256x256px, since you do not need the detail and the code runs faster. The example below reads input.png, writes output.png and uses 100 shapes.
The -n flag sets the number of shapes, and the README notes that 50 to 200 is the usual range.
primitive -i input.png -o output.png -n 100Choose a shape mode and output size
The -m flag selects the shape type. The default is 1, which is triangles. The -s flag sets the output image size, with a default of 1024. The -r flag resizes large inputs before processing, with a default of 256.
- -m 0: combo (a mix of shapes)
- -m 1: triangle (default)
- -m 2: rectangle (axis-aligned)
- -m 3: ellipse
- -m 4: circle
- -m 5: rotated rectangle
- -m 6: beziers
- -m 7: rotated ellipse
- -m 8: polygon
- -s: output image size (default 1024)
- -r: resize large input images before processing (default 256)
primitive -i input.png -o output.png -n 100 -m 3 -s 2048Export PNG, JPG, SVG or GIF
The output format depends on the file extension you give to -o. PNG and JPG produce raster images. SVG produces vector output, which is useful if you want to scale or edit the art. GIF makes an animation showing shapes being added, but it requires ImageMagick, specifically its convert command.
You can use -o more than once to save both a PNG and an SVG from one run. Adding %d, %03d or similar to a PNG or SVG filename saves each frame separately.
- PNG: raster output
- JPG: raster output
- SVG: vector output
- GIF: animated output (needs ImageMagick's convert command)
primitive -i input.png -o output.png -o output.svg -n 100Other useful flags
The -a flag sets colour alpha, default 128. Setting it to 0 lets the algorithm choose alpha for each shape. The -bg flag sets a starting background colour as hex. The -j flag sets the number of parallel workers, and by default it uses all cores. The -v and -vv flags turn on verbose output.
- -a 0: let the algorithm choose alpha for each shape
- -bg: starting background colour in hex
- -j: number of parallel workers (default uses all cores)
- -v / -vv: verbose or very verbose output
What people use it for
- Making abstract, geometric artwork from a photo for print or screen
- Exporting an SVG of a photo for vector-style art
- Creating an animated GIF that shows shapes being added one at a time
- Studying how a Go program uses hill climbing to optimise an image
- Teaching how simple shapes can approximate a picture
Frequently asked questions
Is Primitive free to use?
Primitive is released under the MIT licence, as stated in the project summary. The MIT licence allows you to use, modify and share the code under its terms. Check the licence file in the repository for the full wording.
What do I need to install Primitive?
You need Go, which the README asks you to install from golang.org. After that, run go get -u github.com/fogleman/primitive to install the tool.
How many shapes should I use?
The README says around 50 to 200 shapes are needed to reach a result that is recognisable yet artistic. The example command uses 100 shapes as a starting point.
Why is my output not an exact copy of the photo?
Primitive makes a stylised approximation by adding one shape at a time to reduce the error. The README describes it as abstract and artistic, so it is not designed for exact reproduction.
Can I make an SVG from my image?
Yes. Use a .svg extension on the -o flag to produce vector output. You can also pass -o twice to save a PNG and an SVG from the same run.
Is there a version without the terminal?
The README mentions a native Mac application at primitive.lol, but it does not describe its features. The command-line tool is the way the README documents running Primitive.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Primitive suits artists, students and Go developers who want abstract, geometric versions of images and are comfortable using a terminal. If you need an exact photo copy or a point-and-click editor with documented features, look at a different tool. Potrace, which traces bitmaps into vector outlines, is one comparable option to consider.
Install options & downloads