• Stars
    star
    691
  • Rank 63,728 (Top 2 %)
  • Language
    Python
  • License
    Other
  • Created almost 10 years ago
  • Updated over 3 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Simple Vector Graphics for Python

[logo]

Gizeh - Cairo for tourists

Gizeh is a Python library for vector graphics:

# Let's draw a red circle !
import gizeh
surface = gizeh.Surface(width=320, height=260) # in pixels
circle = gizeh.circle(r=30, xy=[40,40], fill=(1,0,0))
circle.draw(surface) # draw the circle on the surface
surface.write_to_png("circle.png") # export the surface as a PNG

You can see examples of Gizeh in action (combined with MoviePy to make animations) in this blog post.

Gizeh is written on top of the module cairocffi, which is a Python binding of the popular C library Cairo. Cairo is powerful, but difficult to learn and use. Gizeh implements a few classes on top of Cairo that make it more intuitive.

Gizeh should work on any platform and with python 2 and 3.

Installation

To use Gizeh you must first install Cairo on your computer (see their website).

Gizeh depends on the Python packages cairocffi and Numpy. They will both be automatically installed (if they aren't already) during the installation of Gizeh. If you have trouble with the installation, head to the last section of this README for troubleshooting. If it doesn't help, you can ask for help on Github.

Installation from the sources: Gizeh can be installed by unzipping the source code in some directory and using this command in the same directory:

(sudo) python setup.py install

Installation with pip: Alternatively, you can install Gizeh directly from the Python Package Index with this command:

(sudo) pip install gizeh

This method may fail if ez_setup is not installed on your computer. In this case install ez_setup first, with

(sudo) pip install ez_setup

Contribute !

Gizeh is an open-source software written by Zulko and released under the MIT licence. The project is hosted on Github. Everyone is welcome to contribute !

User Guide

This guide, along with the examples in the gizeh/examples folder, should give you everything you need to get started. To go further, read the function docstrings.

Surfaces

A Surface is a rectangle of fixed dimensions (in pixels), on which you will draw elements, and that you can save or export as an image:

import gizeh

# initialize surface
surface = gizeh.Surface(width=320, height=260) # in pixels

# Now make a shape and draw it on the surface
circle = gizeh.circle(r=30, xy= [40,40], fill=(1,1,1))
circle.draw(surface)

# Now export the surface
surface.get_npimage() # returns a (width x height x 3) numpy array
surface.write_to_png("circle.png")

Elements

Basic elements are circles, rectangles, lines, texts, etc., that you can draw on a surface using my_element.draw(surface). You can specify the properties and coordinates of these elements at creation time:

  • xy : coordinates of the center of the object. At rendering time (in function surface.write_to_png) you can set the parameter y_origin to top (default) or bottom. If you leave it to top, (0,0) corresponds to the upper left corner of the final picture, and the bottom right corner has coordinates (width, height). If you choose y_origin=bottom, (0,0) will be at the bottom left of the picture (like in a standard plot) and (width, height) will be at the upper right corner.
  • angle : angle (in radians) of the rotation of the element around its center xy.
  • fill : what will fill the element (default is no fill). Can be a color (R,G,B), a color gradient, an image, etc. See section below.
  • stroke : What will fill the element's contour. Same rules as for fill.
  • stroke_width : the width (in pixels) of the element's contour. Default is 0 (no stroke).

Examples of elements:

Pi = 3.14
circ = gizeh.circle(r=30, xy=(50,50), fill=(1,1,1))
rect = gizeh.rectangle(lx=60.3, ly=45, xy=(60,70), fill=(0,1,0), angle=Pi/8)
sqr = gizeh.square(l=20, stroke=(1,1,1), stroke_width= 1.5)
arc = gizeh.arc(r=20, a1=Pi/4, a2=3*Pi/4, fill=(1,1,1))
text = gizeh.text("Hello world", fontfamily="Impact",  fontsize=40,
                  fill=(1,1,1), xy=(100,100), angle=Pi/12)
polygon = gizeh.regular_polygon(r=40, n=5, angle=np.pi/4, xy=[40,50], fill=(1,0,1))
line = gizeh.polyline(points=[(0,0), (20,30), (40,40), (0,10)], stroke_width=3,
                     stroke=(1,0,0), fill=(0,1,0))

Fill and stroke

When you make a shape, the fill and stroke parameters can be one of the following:

  • A RGB color of the form (r,g,b) where each element is comprised between 0 and 1 (1 is 100%).
  • A RGBA color of the form (r,g,b,a), where a is comprised between 0 (totally transparent) and 1 (totally opaque).
  • A gizeh.ColorGradient (see the docstring).
  • A gizeh.ImagePattern, i.e. an image (see the docstring).
  • A numpy array representing a RGB or RGBA image (not implemented yet).
  • A PNG image file (not implemented yet).

Transformations

Any element can be transformed (translated, rotated or scaled). All transformations are outplace: they do not modify the original element, they create a modified version of it.

Examples:

square_1 = gizeh.square(l=20, xy = [30,35], fill=(1,0,0))
square_2 = square_1.rotate(Pi/8) # rotation around [0,0] by default
square_3 = square_2.rotate(Pi/4, center=[10,15]) # rotation around a center
square_4 = square_1.scale(2) # two times bigger
square_5 = square1.scale(sx=2, sy=3) # width times 2, height times 3
square_6 = square_1.scale(2, center=[30,30]) # zoom: scales around a center
square_7 = square_1.translate(xy=[5,15]) # translation

Groups

A Group is a collection of elements which will be transformed and drawn together. The elements can be a basic element (square, circle...) or even groups.

Examples:

square = gizeh.square(l=20, fill=(1,0,0), xy=(40,40))
circle = gizeh.circle(r=20, fill=(1,2,0), xy=(50,30))
group_1 = gizeh.Group([square, circle])
group_2 = group.translate(xy=[30,30]).rotate(Pi/4)
group_3 = gizeh.Group([circle, group_1])

surface = gizeh.Surface(width=300,height=200)
group.draw(surface)
group_1.draw(surface)
group_2.draw(surface)
group_3.draw(surface)
surface.write_to_png("my_masterwork.png")

That's all folks !

That's about all there is to know. To go further, see the examples in the examples folder or the documentation directly in the code.

Installation support

Sometimes the installation through pip fails because

Some people have had problems to install cairocffi, Here is how they solved their problem:

On Debian/Ubuntu

sudo apt-get install python-dev python-pip ffmpeg libffi-dev
sudo pip install gizeh

On macOSX

pip install ez_setup


brew install pkg-config libffi
export PKG_CONFIG_PATH=/usr/local/Cellar/libffi/3.0.13/lib/pkgconfig/

# go to https://xquartz.macosforge.org and download and install XQuartz,
# which is needed for cairo, then...
brew install cairo

pip install gizeh

More Repositories

1

moviepy

Video editing with Python
Python
11,920
star
2

eagle.js

A hackable slideshow framework built with Vue.js
JavaScript
4,074
star
3

easyAI

Python artificial intelligence framework for games
Python
631
star
4

vapory

Photo-realistic 3D rendering with Python and POV-Ray
Python
472
star
5

pianoputer

Use your computer keyboard as a "piano".
Python
321
star
6

picnic.py

Easy Python packages creation.
Python
256
star
7

twittcher

Python module to watch Twitter user pages or search-results.
Python
63
star
8

unroll

Python package for Piano roll transcription to sheet music
Python
57
star
9

eaglejs-demo

Demo slideshows for Eagle.js
Vue
44
star
10

Minimix

A minimalist sound mixer / instrument emulator written in python
Python
43
star
11

pompei

Mosaics generation from movie frames
Python
42
star
12

-sheet-music--Gerhswin-Limehouse-Nights

Sheet music transcription of a G. Gershwin Public Domain piano roll performance
LilyPond
27
star
13

ddeint

Scipy-based Delay Differential Equation (DDE) solver
Python
26
star
14

pianoputer.js

Javascript implementation of the Pianoputer. Right now, it's bad. Very bad.
JavaScript
24
star
15

gix

Create, share and remix GIFs online
Vue
21
star
16

vmfactory

The Viennese Maze Factory
Python
15
star
17

zulko.github.com

My personal blog on Github
HTML
12
star
18

gif-captioning-with-css

Let's add CSS animations to a GIF!
Vue
5
star
19

moviepy_matplotlib

For issue on matplotlib
Python
5
star
20

bricks_and_scissors

Blog on the computational side of synthetic biology and DNA manufacturing
HTML
4
star
21

--video-editing---Cup-Song-Covers-Mix

Source code for a video featuring 60 covers of the Cup Song
4
star
22

funsliders

Graphical sliders to manually explore any function's input
Python
4
star
23

pianola

A web MIDI piano player, built for roll transcription
Vue
3
star
24

dna_weaver_paper

Manuscript for DNA Weaver
TeX
3
star
25

kbmix

script-based / keyboard-controlled sound mixer
2
star
26

sheet-music--Gershwin-sweet-and-lowdown

Transcription of the Sweet and Lowdown piano roll by George Gershwin
LilyPond
2
star
27

sheet-music--hindustan

Piano transcription of "Hindustan" from a piano roll
LilyPond
2
star
28

-sheet-music--Romance-for-guitar

Piano arrangement of the Romance for guitar made famous by the movie Jeux Interdits
2
star
29

unroll-online

Web app for piano roll transcription
JavaScript
1
star
30

Web_tools

Python
1
star
31

FLOT-Demo

A FLOT.js demo
JavaScript
1
star
32

sheet-music--duet-for-the-right-hand

A little piano piece for the right hand alone (lilypond file)
LilyPond
1
star