Subversion Repositories cheapmusic

Rev

Blame | Last modification | View Log | RSS feed 

<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /><title>4.3. Truecolor Images</title><link rel="stylesheet" type="text/css" href="phplotdoc.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.78.1" /><link rel="home" href="index.html" title="PHPlot Reference Manual" /><link rel="up" href="advanced.html" title="Chapter 4. PHPlot Advanced Topics" /><link rel="prev" href="adv-serialize.html" title="4.2. PHPlot Object Serialization" /><link rel="next" href="callbacks.html" title="4.4. Callbacks" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">4.3. Truecolor Images</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="adv-serialize.html">Prev</a> </td><th width="60%" align="center">Chapter 4. PHPlot Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="callbacks.html">Next</a></td></tr></table><hr /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="adv-truecolor"></a>4.3. Truecolor Images</h2></div></div></div><div class="abstract"><p class="title"><strong></strong></p><p>
This section contains information about using
<a class="link" href="concepts.html#def-truecolor">Truecolor images</a> in PHPlot.
This material supplements the text in the <a class="xref" href="conc-colors.html" title="3.5. Colors">Section 3.5, &#8220;Colors&#8221;</a>.
  </p></div><p>
Truecolor image support was added to PHPlot-5.1.1. With Truecolor image
support, you can:
  </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Create images with a larger number of colors</p></li><li class="listitem"><p>Control color transparency with alpha blending</p></li><li class="listitem"><p>Perform advanced image processing operations</p></li></ul></div><p>
</p><p>
An example of using Truecolor with PHPlot can be found in
<a class="xref" href="ex-truecolor-histogram.html" title="5.24. Example - Using Truecolor To Make a Histogram">Section 5.24, &#8220;Example - Using Truecolor To Make a Histogram&#8221;</a>.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-truecolor-overview"></a>4.3.1. Using Truecolor Images in PHPlot</h3></div></div></div><p>
To make a Truecolor image in PHPlot, create an object of the derived class
<code class="literal">PHPlot_truecolor</code> instead of the class
<code class="literal">PHPlot</code>.
For example, replace this:
</p><pre class="programlisting">$plot = new PHPlot(800, 600);
</pre><p>
with this:
</p><pre class="programlisting">$plot = new PHPlot_truecolor(800, 600);
</pre><p>
</p><p>
That is all you need to do in order to create truecolor images. All PHPlot
methods are compatible with PHPlot_truecolor objects. An image file
produced from a PHPlot_truecolor object with no other programming changes
will be the same as an image file produced from a PHPlot object except as
described under <a class="xref" href="adv-truecolor.html#adv-truecolor-fileformats" title="4.3.5. Image Formats and File Formats, Palette and Truecolor">Section 4.3.5, &#8220;Image Formats and File Formats, Palette and Truecolor&#8221;</a>.
</p><p>
One of the advantages of truecolor images is the ability to use
variable transparency. This is described in the next two sections.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-truecolor-alpha"></a>4.3.2. Understanding Variable Transparency (Alpha)</h3></div></div></div><p>
Colors in a truecolor image have four components: red, green, blue, and
alpha. The alpha component corresponds to the transparency of a color.
An alpha value of zero means the color is opaque, and an alpha value
of 127 means the color is transparent, or clear.<a href="#ftn.idp1375167612" class="footnote" id="idp1375167612"><sup class="footnote">[4]</sup></a>
In between values, from 1 to 126, correspond to various amounts of
transparency.
</p><p>
Transparency is only meaningful when drawing objects on top of objects, or
objects on top of the image background. An object drawn with an
opaque color (alpha=0) will replace whatever was in the image before the
object was drawn at that position. An object drawn with an transparent
color (alpha=127) is invisible and does not affect the appearance of the
image. An object drawn with a color that has an alpha value between 1 and
126 will be combined with whatever was in the image before the object was
drawn using alpha blending.
</p><p>
The PHP Manual explains alpha blending like this: "In blending mode, the
alpha channel component of the color supplied to all drawing functions
determines how much of the underlying color should be allowed to shine
through. As a result, gd automatically blends the existing color at that
point with the drawing color, and stores the result in the image. The
resulting pixel is opaque."<a href="#ftn.idp1375104516" class="footnote" id="idp1375104516"><sup class="footnote">[5]</sup></a>
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
Note that the PHP Manual says the resulting pixel is opaque. This means
that objects drawn with alpha above 0 are partially or completely transparent
only relative to other objects in that same image. This does not result
in an image with transparent portions which would show through to a browser
or desktop background, for example.
(Read the PHP Manual page for <code class="function">imagesavealpha</code> for more
about this behavior and how to change it.)
Use <a class="xref" href="SetTransparentColor.html" title="SetTransparentColor"><span class="refentrytitle">SetTransparentColor</span></a> to make portions of an image
transparent to web page or desktop backgrounds.
  </p></div><p>

The following figure shows the effect of alpha blending when drawing lines.
The left side shows the normal overlaying of lines, and the right side
shows alpha-blended overlaying of lines with alpha = 60 (that is, 60/127
transparency).
The effect of alpha blending can be seen where the data lines cross.
Note: These plots use wide lines (3 pixels) and the portions of
the images are magnified 2x to show detail.
  </p><div class="informalfigure"><div class="mediaobject"><img src="images/alpha-blending.png" alt="Line intersections without and with alpha blending." /></div></div><p>
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-truecolor-using-alpha"></a>4.3.3. Using Variable Transparency (Alpha) in PHPlot</h3></div></div></div><p>
To use partially transparent colors (that is, colors with an alpha channel)
with a PHPlot_truecolor object, you can specify an alpha value as part of a
color specification, and you can specify a default alpha value for all data
colors.
</p><p>
Use of alpha values with a color specification is described below,
in <a class="xref" href="adv-truecolor.html#adv-truecolor-forms" title="4.3.4. Color Parameter Form Extensions">Section 4.3.4, &#8220;Color Parameter Form Extensions&#8221;</a>.
Here are some examples of using colors with an alpha specification.
</p><p>
This sets the color used for labels to red=192, green=192, blue=33, and
alpha=50 (that is, 50/127 transparency).
</p><pre class="programlisting">$plot-&gt;SetTextColor(array(192, 192, 33, 50));
</pre><p>
</p><p>
This sets the color used for tick marks to the color 'blue' from the color
map, with alpha value 64 (64/127 transparency).
</p><pre class="programlisting">$plot-&gt;SetTickColor('blue:64');
</pre><p>
</p><p>
This sets colors for the first three data sets to red, green, and blue with
different alpha values. The three colors are represented using
different formats for illustration purposes.
</p><pre class="programlisting">$plot-&gt;SetDataColors(array(
      array(255, 0, 0, 60), // Red with alpha=60
      '#00ff0050',          // Green with alpha=80 (0x50)
      'blue:70'));          // Blue with alpha=70
</pre><p>
</p><p>
Instead of specifying the alpha value for each data set color, you can
provide a default alpha value for all data colors using the third argument to
This uses the colors specified in $my_color_array with a default alpha of
50. The default is applied to any color definition which does not already
have an alpha value.
<a class="xref" href="SetDataColors.html" title="SetDataColors"><span class="refentrytitle">SetDataColors</span></a>.
</p><pre class="programlisting">$plot-&gt;SetDataColors($my_color_array, NULL, 50);
</pre><p>
</p><p>
This can also be used to apply an alpha value to the default data colors.
This retains the default data colors, but applies alpha = 50 (50/127
transparency) to all the colors. This is a quick way to get partially
transparent data colors without re-specifying all the colors.
</p><pre class="programlisting">$plot-&gt;SetDataColors(NULL, NULL, 50);
</pre><p>
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-truecolor-forms"></a>4.3.4. Color Parameter Form Extensions</h3></div></div></div><p>
In addition to the forms specified in <a class="xref" href="conc-colors.html#conc-colors-forms" title="3.5.1. Color Parameter Forms">Section 3.5.1, &#8220;Color Parameter Forms&#8221;</a>,
colors specifications can include an alpha value. Although this works with
palette images as well as truecolor images, specifying alpha values
with palette images provides limited value.
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
A color name, as defined by <a class="xref" href="SetRGBArray.html" title="SetRGBArray"><span class="refentrytitle">SetRGBArray</span></a> or from a built-in
color map if SetRGBArray was not called, followed by a colon and an alpha
value as a decimal number, for example: 'red:60'. The alpha value is
between 0 (opaque) and 127 (transparent).
Note that colors in the color map can be defined with or without an alpha
value. An alpha value appended to the color name overrides any specified
in the color map. For example, if the color 'red2' is defined in the color
map as array(255,0,0,80) - that is, red with 80/127 transparency - then
'red2' has alpha of 80, and 'red2:40' has alpha of 40.
    </p></li><li class="listitem"><p>
Numeric color component values, in the form <code class="literal">#rrggbbaa</code>.
Here rr is red, gg is green, and bb is blue, and each component
value is represented as a 2-digit hexadecimal number between 00 and ff.
Also aa is alpha, represented as a 2 digit hexadecimal number between 00 and 7f.
For example, <code class="literal">#00ff0010</code> is green with 16/127 transparency.
    </p></li><li class="listitem"><p>
A PHP array of red, green, blue, and alpha color component values.
Each value of red, green, and blue are in the range 0 to 255 inclusive,
and the alpha component is in the range 0 to 127 inclusive.
For example,
<code class="literal">array(0,255,0,16)</code> is the same green with 16/127 transparency.
    </p></li></ol></div><p>
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-truecolor-fileformats"></a>4.3.5. Image Formats and File Formats, Palette and Truecolor</h3></div></div></div><p>
PHPlot can produce JPEG, PNG, and GIF image files (and possibly others).
You select the PHPlot output image file format with
<a class="xref" href="SetFileFormat.html" title="SetFileFormat"><span class="refentrytitle">SetFileFormat</span></a>.
</p><p>
PHPlot works with GD images before producing an image file. There are two
types of GD images: truecolor and palette. Truecolor images represent
pixels as 32 bit values, combining 8 bits each of red, green, and blue
components with a 7 bit alpha (transparency) value. Palette images use a
color table with at most 256 entries, and represent pixels as 8 bit indexes
into the color table. The palette image color table entries have 32 bit
values, with the same components as truecolor image pixel values. So
palette images in GD can have at most 256 unique colors, but there is no
limitation on the number of unique colors in truecolor images.
</p><p>
As long as you don't specify a background image when creating your plot object,
truecolor images are created with the <code class="literal">PHPlot_truecolor</code> class,
and palette images are created with the <code class="literal">PHPlot</code> class.
If you specify a background image, the GD image created by PHPlot matches the
type - truecolor or palette - of your background image file.
More on background image files can be found in
<a class="xref" href="adv-truecolor.html#adv-truecolor-background" title="4.3.7. Background Images">Section 4.3.7, &#8220;Background Images&#8221;</a> below.
</p><p>
What happens when you output the GD image to an image file depends on the
image file format you select.
</p><p>
JPEG image files are always truecolor. Whether you have a GD palette image
or truecolor image, you will get a truecolor image file.  Note: You are
discouraged from using JPEG images with PHPlot, because they are not
optimal for this type of graphical information due to use of lossy
compression.
</p><p>
GIF image files are always palette type, limited to 256 colors. If
you have a GD palette image, you will get a palette GIF image file with the
colors you used in your plot. If you have a a GD truecolor image, GD will
convert your image to palette format, reducing the number of colors to 256
if necessary. This may change the appearance of your plot. Note that some
versions of the PHP manual for <code class="function">imagecreatetruecolor()</code>
incorrectly state that you cannot output a GIF file from a truecolor GD image.
</p><p>
PNG image files support truecolor images and palette images of various
color depths.  If you have a GD palette image, you will get a palette PNG
image file. If you have a GD truecolor image, you will get a truecolor PNG
image file. Note that by default, even though PNG truecolor image files
support an alpha channel, GD eliminates the alpha channel when producing a
PNG file. The visual effects of alpha blending are reproduced using opaque
colors. GD apparently does this due to poor support in viewers for alpha
channels. Refer to the PHP Manual page on
<code class="function">imagesavealpha()</code> for details.
</p><p>
The following figure shows the relationship between constructor, background
image format, GD image type, and image file format.
  </p><div class="informalfigure"><div class="mediaobject"><img src="images/truecolor-formats.png" alt="Constrictor, GD image type, and image file formats." /></div></div><p>
</p><p>
In the initial release of Truecolor support in PHPlot-5.1.1, alpha channel
information was ignored when using a PHPlot object, and only used with a
PHPlot_truecolor object. This was changed in PHPlot-5.1.2, and alpha
channel information is used for both PHPlot and PHPlot_truecolor classes.
However, alpha channel information is not always useful with palette
images.
More on this can be found in <a class="xref" href="adv-truecolor.html#adv-truecolor-palette" title="4.3.9. Palette Images and Advanced Color Features">Section 4.3.9, &#8220;Palette Images and Advanced Color Features&#8221;</a> below.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-truecolor-plottypes"></a>4.3.6. Truecolor Images and Plot Types</h3></div></div></div><p>
All PHPlot plot types work with truecolor images, but not all plot types
work well with alpha blending of data colors.
</p><p>
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Pie Charts</span></dt><dd><p>
Avoid using alpha blending with pie charts. The underlying GD
routines do not fill the pie areas in a way that allows proper blending of
colors. Flat pie charts (using SetShading(0)) are not too bad, showing some
artifacts, but shaded or 3D-look pie charts are poorly rendered.
      </p></dd><dt><span class="term">Bar Charts, </span><span class="term">Stacked Bar Charts</span></dt><dd><p>
Bars are drawn properly, but the 3D shading affects get blended, resulting
in less than ideal appearance. Flat, outlined bars (using SetShading(0))
are fine with transparency, but when shading is on the 3D shadows overlap
portions of the bars. With alpha blending, the overlaps take on new colors.
      </p></dd></dl></div><p>
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-truecolor-background"></a>4.3.7. Background Images</h3></div></div></div><p>
When creating a PHPlot or PHPlot_truecolor object, you can provide an
existing image filename to the constructor as the fourth argument,
<em class="parameter"><code>$input_file</code></em>.
</p><pre class="programlisting">$plot = new PHPlot(800, 600, NULL, 'myimage.png');
</pre><p>
This image file becomes the background for your plot. (The function
<a class="xref" href="dev-internal.html#SetInputFile">SetInputFile</a> also does this,
but is deprecated for use except through the constructor.)
</p><p>
If you provide an input file to the constructor, the image associated with
your PHPlot or PHPlot_truecolor object takes on the type of the input file:
palette or truecolor. It does not matter which constructor you use when
specifying an input file as background.
(This was changed after the initial release of truecolor support.
In PHPlot-5.1.1, you must use the PHPlot_truecolor constructor in order to
use some truecolor features even when you use a truecolor background
image file. Starting with PHPlot-5.1.2 you can use either constructor.)
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
The above applies only when an input file is specified to the PHPlot
or PHPlot_truecolor constructor.  It does not apply to
an image background set with <a class="xref" href="SetBgImage.html" title="SetBgImage"><span class="refentrytitle">SetBgImage</span></a>
nor to a plot area background set with <a class="xref" href="SetPlotAreaBgImage.html" title="SetPlotAreaBgImage"><span class="refentrytitle">SetPlotAreaBgImage</span></a>.
  </p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-truecolor-callbacks"></a>4.3.8. Additional Operations on Truecolor Images Using Callbacks</h3></div></div></div><p>
Advanced operations on truecolor PHPlot images are possible using PHPlot
callbacks. See <a class="xref" href="callbacks.html" title="4.4. Callbacks">Section 4.4, &#8220;Callbacks&#8221;</a> for more information about using
callbacks.  Here are some of the operations you can perform, and the
corresponding GD functions.  Refer to the GD section of the PHP Manual for
more information on these functions.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
Some of these functions are only available when PHP was built with the
bundled version of the GD library.
  </p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="adv-truecolor-callbacks-antialias"></a>4.3.8.1. imageantialias()</h4></div></div></div><p>
You can turn on anti-aliasing of truecolor images. This must be done before
anything is drawn, so the pre-drawing callback <code class="literal">draw_setup</code>
is used. Here is a partial example:
</p><pre class="programlisting">function pre_plot($img)
{
    imageantialias($img, True);
}
...
$plot = new PHPlot_truecolor(1024, 768);
$plot-&gt;SetCallback('draw_setup', 'pre_plot');
</pre><p>
</p><p>
Note: There are limitations with anti-aliased images. You cannot use wide
lines (<a class="xref" href="SetLineWidths.html" title="SetLineWidths"><span class="refentrytitle">SetLineWidths</span></a>).
Patterned lines do not work, so if you are displaying
X or Y grid lines you must use <a class="xref" href="SetDrawDashedGrid.html" title="SetDrawDashedGrid"><span class="refentrytitle">SetDrawDashedGrid</span></a>(False)
to make these solid.
Also note that TrueType Font (TTF) text is always anti-aliased, even on
palette images, regardless of the use of <code class="function">imageantialias()</code>.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="adv-truecolor-callbacks-alphablending"></a>4.3.8.2. imagealphablending() and imagelayereffect()</h4></div></div></div><p>
These functions control the combining of partially transparent colors. They
can be used via a <code class="literal">draw_setup</code> callback, in the same way
as <code class="function">imageantialias</code> in the example above.
Note that alpha blending is on by default with all truecolor images.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="adv-truecolor-callbacks-gammacorrect"></a>4.3.8.3. imagegammacorrect()</h4></div></div></div><p>
You can have the GD library perform gamma adjustment on a truecolor image.
This must be done after all drawing, so the post-drawing callback
<code class="literal">draw_all</code> is used. Here is a partial example:
</p><pre class="programlisting">function post_plot($img)
{
    imagegammacorrect($img, 1.0, 0.5); // Input gamma=1, output gamma=.5
}

...
$plot = new PHPlot_truecolor(1024, 768);
$plot-&gt;SetCallback('draw_all', 'post_plot');
</pre><p>
</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-truecolor-palette"></a>4.3.9. Palette Images and Advanced Color Features</h3></div></div></div><p>
You will have a GD palette image if you use the <code class="literal">PHPlot</code>
constructor without a background image file, or if you use either the
<code class="literal">PHPlot</code> or <code class="literal">PHPlot_truecolor</code>
constructors with a background image file that is a palette image (GIF or
some types of PNG). You can use alpha color specifications with palette GD
images, but this is not recommended. The results are not well documented,
but the following behavior has been observed:
</p><p>
  </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
There is no alpha blending. Drawing operations simply replace existing
pixels values with the new pixel values. (These are actually index values
into the color table.)
      </p></li><li class="listitem"><p>
Alpha values are ignored when the image is output to a JPEG or GIF file.
All colors are output as opaque.
      </p></li><li class="listitem"><p>
Alpha values are preserved in PNG image files. These will be palette, not
truecolor, PNG images, with the color table containing the alpha values.
You can therefore have palette PNG files with partial transparency, however
not all viewers properly support this.
      </p></li></ul></div><p>
</p><p>
Nothing described in <a class="xref" href="adv-truecolor.html#adv-truecolor-callbacks" title="4.3.8. Additional Operations on Truecolor Images Using Callbacks">Section 4.3.8, &#8220;Additional Operations on Truecolor Images Using Callbacks&#8221;</a> works with
palette images, including gamma adjust and anti-aliasing (except that
TrueType Font text is always anti-aliased.)
</p></div><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.idp1375167612" class="footnote"><p><a href="#idp1375167612" class="para"><sup class="para">[4] </sup></a>
PHPlot follows the GD Library convention here. Other systems use alpha=0 to
mean transparent, and a maximum alpha value to mean opaque.
  </p></div><div id="ftn.idp1375104516" class="footnote"><p><a href="#idp1375104516" class="para"><sup class="para">[5] </sup></a>From the PHP Reference Manual,
imagealphablending</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="adv-serialize.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="advanced.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="callbacks.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4.2. PHPlot Object Serialization </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 4.4. Callbacks</td></tr></table></div></body></html>