53. gui.image — Saving OpenGL renderings to image files.

This module defines some functions that can be used to save the OpenGL rendering and the pyFormex GUI to image files. There are even functions for automatically saving multiple renderings to a series of files, for creating a movie from these images and for recording the GUI directly to a video file.

The most important functions in this module are

• saveImage(): save (parts of) the GUI to an image file

• recordSession(): record (parts of) the GUI to a video file

53.1. Functions defined in module gui.image

gui.image.get_image_formats_qt()

List the image formats supported by QImage

Returns:

• formats_r (list of str) – List of image formats that can be read by QImage

• formats_w (list of str) – List of image formats that can be written by QImage

gui.image.get_image_formats_pil()

List the image formats supported by PIL

Returns:

• formats_r (list of str) – List of image formats that can be read by PIL

• formats_w (list of str) – List of image formats that can be written by PIL

gui.image.get_image_formats_magick()

List the image formats supported by ImageMagick

Returns:

• formats_r (list of str) – List of image formats that can be read by ImageMagick

• formats_w (list of str) – List of image formats that can be written by ImageMagick

gui.image.get_image_formats_gl2ps()

List the image formats supported by gl2ps

Returns:

• formats_r (list of str) – An empty list, since gl2ps is write only.

• formats_w (list of str) – List of image formats that can be written by gl2ps

gui.image.get_image_formats(tool)

Return the image formats supported by a specific tool.

Detects and stores the formats or returns the already detected and stored formats.

Parameters:

tool (str) – The key corresponding with the tool to be used to read/write the image file. It should be one of ‘qt’, ‘pil’, ‘magick’, ‘gl2ps’.

Returns:

• formats_r (list of str) – List of the supported formats in read operations.

• formats_w (list of str) – List of the supported formats in write operations.

Notes

The returned formats are lower case strings corresponding with the conventional filename extension without the leading dot. Examples: ‘png’, ‘gif’.

gui.image.imageFormats(tool=None, mode=None)

Detect and return the list of supported image formats.

pyFormex supports reading and writing image files through different underlying tools: ‘qt’, ‘PIL’, ‘ImageMagick’, ‘gl2ps’. Each tool has its own supported set of image formats, often different for reading and writing. In pyFormex, image formats are lowercase strings corresponding with the conventional filename extension without the leading dot. Examples are ‘png’, ‘gif’, ‘ppm’, ‘eps’, ‘jpg’, ‘jpeg’.

Parameters:

• tool (str, optional) – If specified, it is a key corresponding with the underlying tool to be used to read/write the image file. It should be one of ‘qt’, ‘pil’, ‘magick’, ‘gl2ps’. If not specified, returns a dict with results for all tools.

• mode ('r' | 'w', optional) – The purpose of the format: read or write. If not specified, returns results for both. This parameter can only be used if tool is specified as well.

Returns:

list, tuple or dict – If both tool and mode are specified, returns a list with the supported formats by that tool for the specified mode. The list contains lower case strings corresponding with the conventional filename extension without the leading dot. Examples are ‘png’, ‘gif’, ‘ppm’, ‘eps’, ‘jpg’, ‘jpeg’.

If mode is not specified, returns a tuple (formats_r, formats_w) where formats_r is the list of supported formats for reading, and formats_w for writing.

Without parameters, returns a dict where the keys are the valid tool names and the values are the corresponding (formats_r, formats_w) tuples.

gui.image.checkImageFormat(tool, mode, fmt, verbose=True)

Check that an image format is supported by tool and mode.

Parameters:

• tool (str) – The key corresponding with the tool to be used to read/write the image file. It should be one of ‘qt’, ‘pil’, ‘magick’, ‘gl2ps’.

• mode ('r' | 'w') – The purpose of the format: read or write.

• fmt (str) – The image format to check.

• verbose (bool) – If True, a warning message will be displayed to the user if the format is not supported.

Returns:

str | None – The image format if it is supported by the specified tool and mode, or else None.

gui.image.save_qt(filename, format, quality=-1, canvas=None, size=None, crop=None, alpha=False)

Save an OpenGL canvas rendering as an image file.

Saves a QtCanvas rendering using the Qt library functions. This provides the ‘qt’ tool functionality of saveImage(), which is the prefered user level function for saving pyFormex renderings to image files.

Parameters:

• filename (path_like) – The file path to which to save the image.

• format (str) – One of the supported image formats. Any format supported by QImage for writing. The list can be got from imageFormats('qt', 'w').

• quality (int, optional) – The image quality for compressed formats.

• canvas (QtCanvas, optional) – The canvas to be saved. If not specified, the current active canvas is used.

• size (int tuple, optional) – A tuple (width, height) specifying the size of the output image. The default is to use the canvas size.

• crop (int 4-tuple, optional) – A tuple (x, y, w, h) defining a rectangular area to crop from the image. (x,y) is the top left corner and (w,h) are the width and height in pixels. The stored image will thus have size (w,h). Note that combining this parmeter with a canvas resizing using the size parameter will make it difficult to predict what exactly will end up in the cropped image. Therefore this parameter is commonly only used with the original canvas size.

See also

saveImage

the recommended high level versatile image saving function

save_window

save the pyFormex window as image file

save_gl2ps

save the OpenGL rendering in a vector format

gui.image.save_gl2ps(filename, format=None, canvas=None, title='', producer='')

Export the OpenGL rendering to PostScript/PDF/TeX format.

Exporting OpenGL renderings to PostScript is based on the PS2GL library by Christophe Geuzaine (http://geuz.org/gl2ps/), linked to Python by Toby Whites’s wrapper (http://www.esc.cam.ac.uk/~twhi03/software/python-gl2ps-1.1.2.tar.gz)

This function is only defined if the gl2ps module is found. It provides the ‘gl2ps’ tool functionality of saveImage(), which is the prefered user level function for saving pyFormex renderings to image files.

Parameters:

• filename (path_like) – The file path to which to save the image.

• format (str) – One of the supported image formats. Any format supported by gl2ps. The list can be got from imageFormats('gl2ps', 'w'), but at least includes ‘ps’, ‘eps’, ‘pdf’ and ‘tex’. In the case of ‘tex’, two files are actually written: one with the .tex extension, and one with .eps extension. If format is not specified, it is derived from the filename extension.

• canvas (QtCanvas, optional) – The canvas to be saved. If not specified, the current active canvas is used.

• title (str, optional) – An optional title to be written into the image file.

• producer (str, optional) – A producer string to be written in the image file. Default is a pyFormex identification.

See also

saveImage

the recommended high level versatile image saving function

save_qt

save the OpenGL rendering as a raster image

save_window

save the pyFormex window as image file

gui.image.save_window(filename, format, quality=-1, windowname=None, crop=None)

Save (part of) a window as an image file.

Saves any window or part of it to an image file. This uses the ‘import’ command from ImageMagick and can save in any format supported by it. It provides the ‘magick’ tool functionality of saveImage(), which is the prefered user level function for saving the pyFormex window to image files.

Parameters:

• filename (path_like) – The filename on which to save the image.

• format (str) – One of the supported image formats. See ImageMagick. The format needs to be specified. It is currently not derived from the file name.

• quality (int, optional) – See save_window_rect()

• windowname (str, optional) – The name of the window to be saved. The windowid or name of the window you want to save. To find the id/name of an open window, you can run the command xwininfo and click on the window. If not specified, the pyFormex main window is used. A value ‘root’ will save the full desktop window.

• crop (tuple|str, optional) – Define a subregion of the window to be saved. A subregion can be specified as a tuple (x,y,w,h) defining the rectangle to be saved: (x,y) is the position of the upper left corner with respect to the window origin; (w,h) are the width and height of the rectangle. Some subregions can also be conveniently specified by a string: ‘all’ will save all viewports of the central widget, ‘vp’ will save only the current viewport. The default None will save the whole window (without border decorations).

Notes

While this function can be used to save any window, it is primarily provided to save pyFormex windows. Therefore, in all cases, the pyFormex GUI and current canvas are raised and updated before saving.

See also

saveImage

the recommended high level versatile image saving function

save_qt

save the OpenGL rendering as a raster image

save_gl2ps

save the OpenGL rendering in a vector format

gui.image.save_window_rect(filename, format, quality=-1, window='root', crop=None)

Save a rectangular part of the screen to a an image file.

This uses the external program ‘import’ from Imagemagick to save a rectangle from any window on the screen.

Parameters:

• filename (path_like) – The name of the file on which to save the image.

• format (str) – The format of the image file. The available formats can be obtained from imageFormats(‘magick’, ‘w’).

• quality (int) – For compressed images, this defines the quality in percent. For PNG images, this is a value 0..9, where 0 is uncompressed and 9 is maximal compression. For JPEG, this is a value 1..100 where 100 is maximum quality. A value -1 selects the default quality, which is 0 for PNG and 90 for JPEG.

• crop (tuple of int, optional) – A tuple (x,y,w,h) specifying the rectangle to be saved from the window. (x,y,) is the top left corner relative to the window. (w,h) is the size of the rectangle. The default is to save the whole window.

See also

saveImage

the recommended high level versatile image saving function

save_window

save the pyFormex window to an image file

record_rect

record a screen rectangle to a video file

gui.image.add_tool_options(tool, extents)

Add extra tool if detected

gui.image.extent_options(tool)

Return possible extents for a tool

gui.image.tool_options(extent)

Return possible tools for an extent

gui.image.detect_tools()

Detect optional image saving tools

gui.image.image_tools()

Return a list with all image tools

gui.image.image_extents()

Return a list with all image extents

gui.image.saveImage(filename=None, extent='canvas', tool='qt', format=None, quality=-1, size=None, alpha=True, multi=False, hotkey=True, autosave=False, verbose=False)

Save the pyFormex rendering or window to an image file.

This is the recommended high level function for saving a pyFormex canvas rendering or even the whole pyFormex GUI window to an image file in one of the many supported formats.

This function can also be used to start/stop multisave mode, which can save a series of images.

Parameters:

• filename (path_like or NameSequence) – The path where the image is to be saved. If it is a NameSequence, the actual filename will be next(filename). If no filename is specified, nothing is saved and multisave mode is turned off if it was on (see also multi).

• extent (str) –

  Identifies which part of the GUI is to be saved. It should be one of the following

  • ’canvas’: the current OpenGL viewport

  • ’rectangle’: let the user pick a rectangle from the canvas

  • ’allvps’: all the OpenGL viewports, each in their own file. If there is more than one viewport, actual file names are derived from the specified filename by adding ‘_vp#’ (where # is the viewport number) before the file extension

  • ’central’: the central widget of the GUI, including all the OpenGL viewports, in a single image

  • ’window’: the pyFormex GUI main window, without the border

  • ’border’: the pyFormex GUI main window including border decorations

  • ’screen’: saves the full primary X11 screen

  Depending on the installed tools on your system, some options may not be available. The actually available options are given by image_extents().

• tool ('qt' | 'magick' | 'gl2ps') –

  The tool to be used to save the image. ‘qt’ is always available. The others depend on your installation. The actually available tools are given by image_tools(). The tool defines the possible values of extent:

  • qt: ‘canvas’, ‘rectangle, ‘allvps’

  • magick: ‘canvas’, ‘central’, ‘window’, ‘border’, ‘screen’

  • gl2ps: ‘canvas’

• format (str) – One of the supported image formats. The list of supported image formats depends on tool and can be found from imageFormats('qt', 'w'). If not specified, it is derived from the filename extension, converted to lower case and without the leading dot.

• quality (int, optional) – See save_window_rect().

• size (tuple (w,h), optional) – A tuple of width and height specifying the requested image size. The default is to use the size of the current onscreen rendering as this ensures the best quality. If the output size is not equal to the actual rendering size, the image is rendered offscreen and some OpenGL features might not be shown correctly.

• alpha (bool, optional) – This is an experimental feature not ready for use.

• multi (bool, optional) – If True and a filename was specified, multisave mode is switched on. In multisave mode, images will repeatedly be saved on demand or automatically. The filename is turned into a NameSequence to generate consecutive file names for the images. The images are saved with the same format, quality and size. In multisave mode, each call to saveNext() will save an image to the next generated file name. The starting of multisave mode in itself does not save any image. See also the hotkey and autosave options. Multisave mode can be turned off from the GUI File menu or by calling saveImage without a filename. Starting a new multisave mode will also quietly stop a previous multisave.

• hotkey (bool, optional) – If True (default) when multisave mode is activated, a new image can be saved by hitting a hotkey (configurable in the settings).

• autosave (bool, optional) – If True, a new image will be saved on each execution of the draw() function.

• verbose (True, optional) – If True, additional error or warning messages may be displayed.

See also

save_window

save the pyFormex window to an image file

save_qt

save the OpenGL rendering as a raster image

save_gl2ps

save the OpenGL rendering in a vector format

gui.image.saveNext()

In multisave mode, save the next image.

This is a quiet function that does nothing if multisave was not activated. It can thus safely be called on regular places in scripts where one would like to have a saved image. In interactive use, the user then has to be asked only once whether to activate the multisave mode or not.

gui.image.autoSaveOn()

Returns True if autosave multisave mode is currently on.

Use this function instead of directly accessing the multisave variable.

gui.image.createMovie(files, encoder='convert', outfn='output', **kargs)

Create a movie from a saved sequence of images.

Parameters:

• files (list of str) – A list of filenames, or a string with one or more filenames separated by whitespace. The filenames can also contain wildcards interpreted by the shell.

• encoder (str) – The external program to be used to create the movie. This will also define the type of output file, and the extra parameters that can be passed. The external program has to be installed on the computer. The default is ‘convert’, which will create animated gif. Other possible values are ‘mencoder’ and ‘ffmeg’, creating meg4 encode movies from jpeg input files.

• outfn (str) – output file name (not including the extension). Default is ‘output’.

• **kargs –

  Other parameters may be passed and may be needed, depending on the converter program used. Thus, for the default ‘convert’ program, each extra keyword parameter will be translated to an option -keyword value for the command. Example:

  createMovie('images*.png',delay=1,colors=256)
  

  will create an animated gif ‘output.gif’.

gui.image.changeBackgroundColorXPM(fn, color)

Change the background color of an .xpm image.

Parameters:

• fn (path_like) – The file name of an .xpm image file.

• color (str) – The color to be set as background color. It is an X11 color name or a web format hexadecimal color (‘#FFF’ or ‘#FFFFFF’ is white). A special value ‘None’ may be used to set a transparent background.

Notes

The current background color is selected from the lower left pixel. All pixels having that color will be changed.

This function is mainly intended for use by saveIcon().

gui.image.saveIcon(fn, size=32, transparent=True)

Save the current rendering as an icon.

Saves the current rendering as an .xpm image file.

Parameters:

• fn (path_like) – File name of the target image file. If it does not end with ‘.xpm’, this extension will be appended.

• size (int) – Pixel size of the output image.

• transparent (bool) – If True (default), the background will be set to transparent.

Notes

This function is primarily intended for creating icons for the pyFormex GUI.

gui.image.recordSession(filename, extent='window', framerate=25)

Create a video from the pyFormex window or another zone on the screen.

This uses ffmpeg to record a rectangular area of the screen to a video file.

Parameters:

• filename (path_like) – The path to the file to save. The filename should have an extension .mp4 for the ‘ffmpeg’ tool, and ‘.ogv’ for the ‘recordmydesktop’ tool.

• extent (str) – The part

gui.image.record_rect(filename, size, pos, framerate=25)

Record a rectangular part of the screen to a a video file.

This uses the external program ‘ffmpeg’ to record a rectangle from any window on the screen.

Parameters:

• filename (path_like) – The name of the file on which to save the image. This should by preference be a .mp4 file. If you want another format, one can always convert afterwards.

• size (tuple of int) – A tuple (w,h) specifying the width and height of the rectangle to grab. It is also the size of the output video. If you need another output size, convert the video afterwards.

• pos (tuple of int) – A tuple (x,y) with the position of the top left corner of the rectangle to grab. The values are relative to the primary screen origin.

• framerate (int, optional) – The number of frames to capture per second.

See also

recordSession

the recommended high level video recording function

save_window_rect

save a screen rectangle to an image file