EncodeImage
Prev | PHPlot Function Reference | Next

## 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:

  Encoding | Description
  --- | ---
  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.

Prev | Up | Next
DrawMessage | Home | EndStream