Navigation C API Pages Python bindings Applications

Python Core module

The python binding maps mostly to the C API with the gp_ prefix stripped.

However structures as gp_pixmap are not created by the gp_pixmap_alloc() function but have proper constructor and destructor to keep the Python reference counting happy.

Then there are a bit more tricky solutions, such as gp_progress_cb which needs a proxy function to call the python callback from the C code.


import gfxprim.core as core

    # Create 100x100 RGB888 pixmap
    c = core.pixmap(100, 100, core.C.PIXEL_RGB888)

    print("w={} h={} bpp={}".format(c.w, c.h, c.bpp))

Creates a pixmap of a particular size and pixel type.

First two parameters are width and height third is pixel type which is an enumeration

May raise OSError with errno set to ENOMEM if allocation has failed.

May raise OSError with errno set to EINVAL for invalid pixel type and/or zero width or height.

import gfxprim.core as core

    pixel = pixmap.get_pixel(x, y)

Returns a pixel value at x and y. If coordinates are outside the image zero is returned.

import gfxprim.core as core

    pixmap.put_pixel(x, y, pixel)

Puts a pixel at specified coordinates. If coordinates are outside of the image nothing is done.

Note You may want to see coordinate system description.
import gfxprim.core as core

    grayscale = pixmap.convert(core.C.PIXEL_G8)

Returns pixmap converted into the desired pixel format.

The conversion is naive i.e. the values are just divided/multiplied.

import gfxprim.core as core

    # Blits pixmap to target starting at
    # sx and sy in the source pixmap
    # tx and ty in in the target
    pixmap.blit(sx, sy, target, tx, ty, w, h)

    # Alternatively the size can be described by
    # coordinates in the source or target
    pixmap.blit(sx, sy, target, tx, ty, sx2=, sy2=)
    pixmap.blit(sx, sy, target, tx, ty, tx2=, ty2=)

Copy a rectangle from self to target.

The blits can do naive conversions (same as convert) however such blits are a bit slower.

Blit is clipped.


Pixel in GFXprim is a number large enough to store a pixel value. Pixel is passed as a parameter to all drawing functions.

There are several functions to create a pixel value for a particular pixel type from color.

import gfxprim.core as core

    # You can create a pixel from RGB and pixel type
    black = core.rgb_to_pixel(0, 0, 0, core.C.PIXEL_G1)

    # Or using shortcut from pixmap
    black = pixmap.rgb_to_pixel(0, 0, 0)

These functions creates a pixel suitable for drawing into a bitmap with particular pixel type.

import gfxprim.core as core

    # Print all supported pixel types
    for i in core.pixel_types:
            print("Pixel type '{}' size {}".format(, i.size))

The pixel_types array stores all supported pixel types

Progress Callback

Progress callback is the last parameter of loaders and filters. It can be either a python function or a touple with a function at first position. In the latter case the second touple element is passed to the callback function as a second parameter. First parameter of the callback is a floating point number with the current progress in percents.

Progress callback must return an integer number. Returning non-zero will abort the operation and the function, called with the callback as a parameter, will return OSError with errno set to ECANCELED.

Debug Functions

import gfxprim.core as core


    level = core.get_debug_level()

Sets and gets the GFXprim debug level. See debug messages description for more details.

These are basic Pixmap methods from core module. Importing other modules will add some other (for example gfx module adds all drawing functions).