ImageMetaTag.savefig

The savefig wrapper

The only function that is usaully needed from this module is savefig wrapper iteself:

ImageMetaTag.savefig(filename, fig=None, img_tags=None, img_format=None, img_converter=0, do_trim=False, trim_border=0, do_thumb=False, keep_open=False, dpi=None, logo_file=None, logo_width=None, logo_height=None, logo_padding=0, logo_pos=0, db_file=None, db_timeout=6, db_attempts=20, db_replace=False, db_add_strict=False, db_full_paths=False, verbose=False)

A wrapper around matplotlib.pyplot.savefig, to include file size optimisation and image tagging.

The filesize optimisation depends on the img_converter input passes into ImageMetaTag.image_file_postproc().

Arguments:

• filename (can include the file extension, or that can be specified in the img_format option)

Options:

• fig - matplotlib figure to save

• img_format - file format of the image. If not supplied it will be guessed from the filename. Currently only the png file format is supported for tagging/conversion.

• img_tags - a dictionary of {tag_namevalue} pairs to be added to the image metadata. Both tag_name and value should be strings and if is not possible to save a tag_name that is used for system purposes of image readers/writers. (e.g. dpi, gamma,

  interlace, transparency etc.)

• db_file - a database file to be used by ImageMetaTag.db.write_img_to_dbfile() to store all image metadata so they can be quickly accessed.

• db_full_paths - by default, if the images can be expressed as relative path to the database file then the database will contain only relative links, unless db_full_paths is True.

• db_timeout - change the database timeout (in seconds).

• db_attempts - change the number of attempts to write to the database.

• db_replace - if True, an image’s metadata will be replaced in the database if it already exists. This can be slow, and the metadata is usually the same so the default is db_replace=False.

• db_add_strict - if True, any attempt to add an image whose metadata tag_names are not present in a pre-existing database will result in a ValueError being raised. If False, then adding a new metadata tag to the database will cause it be rewritten with the new item as a new column. All pre-existing images will have the new tag set to ‘None’. It is best to avoid using this functionality as it can be slow for large databases. Instead, all images should be ideally have all expected metadata tags included from the start but set to ‘None’ where they are not used.

• dpi - change the image resolution passed into matplotlib.savefig.

• keep_open - by default, this savefig wrapper closes the figure after use, except if keep_open is True.

• verbose - switch for verbose output (reports file sizes before/after conversion)

• img_converter - see ImageMetaTag.image_file_postproc().

• do_trim - see ImageMetaTag.image_file_postproc().

• trim_border - see ImageMetaTag.image_file_postproc().

• logo_file - see ImageMetaTag.image_file_postproc().

• logo_width - see ImageMetaTag.image_file_postproc().

• logo_height - see ImageMetaTag.image_file_postproc().

• logo_padding - see ImageMetaTag.image_file_postproc().

• logo_pos - see ImageMetaTag.image_file_postproc().

• do_thumb - see ImageMetaTag.image_file_postproc().

Recommended file structure

In order to produce a working web page in the easiest and quickest manner it is advisable to save the images in a structure along the lines of:

• A top level directory, in a location which will be served up by a web server. e.g. in directory in ${HOME}/public_html/ or ${HOME}/Public/.

  • The image metadata database files should be saved to this directory.

  • The images themselves should be saved in subdirectories within this directory.

    • When saving an image with ImageMetaTag.savefig() and saving metadata to a database, then it will store the file paths of the images as relative paths to the database files.

    • If you need to save these files elsewhere, due to storage limitations, then create a symbolic link to that location from the top level directory. When you save the files with ImageMetaTag.savefig() use the symbolic link in the path, so the database files still contains relative paths. The storage location will need to be accessible by the web-server which will provide access to the web pages.

    • Use the paths relative to the databse file to create an ImageMetaTag.ImageDict class with the metadata.

  • Once the ImageMetaTag.ImageDict has been created, then the web pages can be created in the top level, web accessible, directory.

  • By keeping the database and web pages in the same location, and storing relative paths in the ImageMetaTag.ImageDict then the paths to the images will also be correct in the web pages without having to do any complex path manipulation.

Other functions

The image_file_postproc function could be used to process pre-created images:

ImageMetaTag.image_file_postproc(filename, outfile=None, img_buf=None, img_dpi=None, img_converter=0, do_trim=False, trim_border=0, logo_file=None, logo_width=None, logo_height=None, logo_padding=0, logo_pos=0, do_thumb=False, img_tags=None, verbose=False)

Does the image post-processing for ImageMetaTag.savefig().

Arguments: filename the name of the image file to process

Options:

• outfile - If supplied, the processing will be applied to a new file, with this name. If not supplied, the post processing will overwrite the file given input file.

• img_buf - If the image has been saved to an in-memory buffer, then supply the image buffer here. This will speed up the post-processing.

• img_dpi - output image dpi (if available for the image format) as a tuple for horizontal/vertical values eg: (72, 72)

• img_converter - an integer switch controlling the level of file size compression

  • 0 - no compression

  • 1 - light compression, from RGBA to RGB

  • 2 - moderate compression, from RGBA to RGB, then to an adaptive 256 colour palette.

  • 3 - heavy compression, from RGBA to RGB, then to 8-bit web standard palette.

• do_trim - switch to trim whitespace from the edge of the image

• trim_border - if do_trim then this can be used to define an integer number of pixels as a border around the trim.

• logo_file - a file, or list of image files, to be added as logo(s) to the image. When multiple files are added to the same logo_pos then they are grouped horizontally from left to right before being added.

• logo_width - the desired width of a single logo, in pixels. If the supplied image file is not the right size, it will be resized using a method that applies filters and antialiasing that works well for shrinking images with text to a much smaller size. The aspect ratio of the logo image is always maintained. Either logo_width or logo_height need to be specified, and width overrides height if both are specified. Defaults to 40 pixels.

• logo_height - the desired height of each logo, in pixels, instead of logo_width.

• logo_padding - a number of pixels to pad around the logo (default to zero)

• logo_pos - corner, or list of corners, of the logo(s) (following pyplot.legend, but for corners):

  • 0: ‘best’ in this context will be upper left (default)

  • 1: ‘upper right’ (image grows in width to fit)

  • 2: ‘upper left’ (image grows in width to fit)

  • 3: ‘lower left’ (image grows in height to fit)

  • 4: ‘lower right’ (image grows in height to fit)

• do_thumb - switch to produce default sized thumbnail, or integer/tuple to define the maximum size in pixels

• img_tags: a dictionary of tags to be added to the image metadata

• verbose: switch for verbose output (reports file sizes before/after conversion)