EncodeImage

EncodeImage — Returns the plot image data

Synopsis

$plot->EncodeImage([$encoding])

Description

EncodeImage returns the plot image as a string, using one of three encodings. This function can be used when special processing of the plot image data is necessary, rather than the default behavior of sending the image via standard output (usually to a browser), or writing it to a file. In particular, EncodeImage can be used to embed a PHPlot image inside an HTML file without requiring a separate script.

Parameters

$encoding

Optional string indicating the encoding to use for the return value. If supplied, it must be one of the following values:

EncodingDescription
raw No encoding - the raw data representing the image is returned.
base64 Encodes the image data using base64 (RFC2045).
dataurl Encodes the image data for a 'data:' URL scheme. This is the default. See notes below.

Return Value

Returns the image data, using the indicated encoding.

Notes

The default value for $encoding is dataurl.

raw encoding returns the image data. If the image file format was set to the default PNG, the return result would be a valid PNG file if it was written to a file.

base64 encoding starts with the same data as raw, and encodes it as ASCII characters using the PHP function base64_encode and returns the result. Note that the result is not broken into lines, as required by some applications. Use the PHP function chunk_split if this is needed.

dataurl encoding returns the image data suitable for use as the value of the 'src' attribute in an HTML 'img' tag using the data URL scheme. This embeds the image into the HTML, and so it does not require an external image file. The data URL scheme is defined by RFC 2397.

Warning

RFC 2397 makes it clear that the scheme is intended for embedding small images, and that there may be length limitations on the encoded data. However, there are other applications (for example LibreOffice) that use the data URL scheme for large images. While it has been found to work with large images in the major web browsers, testing in your own environment is recommended.

When using EncodeImage to get the plot image, rather than letting PHPlot output the image to standard output or a file, you must call SetPrintImage(False) to prevent DrawGraph from sending the image data to standard output. You should also call SetFailureImage(False) to prevent PHPlot from producing an unexpected image on standard output in case of a fatal error.

An example of using the dataurl encoding is:

$plot = new PHPlot(800, 600);
$plot->SetPrintImage(False);  // Do not output the image
... // Plot settings, data, etc.
$plot->DrawGraph();  // Make the plot but do not output it
echo "<img src=\"" . $plot->EncodeImage() . "\">\n";

A more complete example can be found in Section 5.39, “Example - Embedding Image with EncodeImage”.

History

This function was added in PHPlot-5.5.0.

SourceForge.net Logo

This version of the manual was produced for the PHPlot Sourceforge project web service site, which requires the logo on each page.

To download a logo-free copy of the manual, see the PHPlot project downloads area.