Subversion Repositories cheapmusic

Rev

Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
98 - 1
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
2
<!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>
3
This section contains information about using
4
<a class="link" href="concepts.html#def-truecolor">Truecolor images</a> in PHPlot.
5
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>.
6
  </p></div><p>
7
Truecolor image support was added to PHPlot-5.1.1. With Truecolor image
8
support, you can:
9
  </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>
10
</p><p>
11
An example of using Truecolor with PHPlot can be found in
12
<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>.
13
</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>
14
To make a Truecolor image in PHPlot, create an object of the derived class
15
<code class="literal">PHPlot_truecolor</code> instead of the class
16
<code class="literal">PHPlot</code>.
17
For example, replace this:
18
</p><pre class="programlisting">$plot = new PHPlot(800, 600);
19
</pre><p>
20
with this:
21
</p><pre class="programlisting">$plot = new PHPlot_truecolor(800, 600);
22
</pre><p>
23
</p><p>
24
That is all you need to do in order to create truecolor images. All PHPlot
25
methods are compatible with PHPlot_truecolor objects. An image file
26
produced from a PHPlot_truecolor object with no other programming changes
27
will be the same as an image file produced from a PHPlot object except as
28
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>.
29
</p><p>
30
One of the advantages of truecolor images is the ability to use
31
variable transparency. This is described in the next two sections.
32
</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>
33
Colors in a truecolor image have four components: red, green, blue, and
34
alpha. The alpha component corresponds to the transparency of a color.
35
An alpha value of zero means the color is opaque, and an alpha value
36
of 127 means the color is transparent, or clear.<a href="#ftn.idp1375167612" class="footnote" id="idp1375167612"><sup class="footnote">[4]</sup></a>
37
In between values, from 1 to 126, correspond to various amounts of
38
transparency.
39
</p><p>
40
Transparency is only meaningful when drawing objects on top of objects, or
41
objects on top of the image background. An object drawn with an
42
opaque color (alpha=0) will replace whatever was in the image before the
43
object was drawn at that position. An object drawn with an transparent
44
color (alpha=127) is invisible and does not affect the appearance of the
45
image. An object drawn with a color that has an alpha value between 1 and
46
126 will be combined with whatever was in the image before the object was
47
drawn using alpha blending.
48
</p><p>
49
The PHP Manual explains alpha blending like this: "In blending mode, the
50
alpha channel component of the color supplied to all drawing functions
51
determines how much of the underlying color should be allowed to shine
52
through. As a result, gd automatically blends the existing color at that
53
point with the drawing color, and stores the result in the image. The
54
resulting pixel is opaque."<a href="#ftn.idp1375104516" class="footnote" id="idp1375104516"><sup class="footnote">[5]</sup></a>
55
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
56
Note that the PHP Manual says the resulting pixel is opaque. This means
57
that objects drawn with alpha above 0 are partially or completely transparent
58
only relative to other objects in that same image. This does not result
59
in an image with transparent portions which would show through to a browser
60
or desktop background, for example.
61
(Read the PHP Manual page for <code class="function">imagesavealpha</code> for more
62
about this behavior and how to change it.)
63
Use <a class="xref" href="SetTransparentColor.html" title="SetTransparentColor"><span class="refentrytitle">SetTransparentColor</span></a> to make portions of an image
64
transparent to web page or desktop backgrounds.
65
  </p></div><p>
66
 
67
The following figure shows the effect of alpha blending when drawing lines.
68
The left side shows the normal overlaying of lines, and the right side
69
shows alpha-blended overlaying of lines with alpha = 60 (that is, 60/127
70
transparency).
71
The effect of alpha blending can be seen where the data lines cross.
72
Note: These plots use wide lines (3 pixels) and the portions of
73
the images are magnified 2x to show detail.
74
  </p><div class="informalfigure"><div class="mediaobject"><img src="images/alpha-blending.png" alt="Line intersections without and with alpha blending." /></div></div><p>
75
</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>
76
To use partially transparent colors (that is, colors with an alpha channel)
77
with a PHPlot_truecolor object, you can specify an alpha value as part of a
78
color specification, and you can specify a default alpha value for all data
79
colors.
80
</p><p>
81
Use of alpha values with a color specification is described below,
82
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>.
83
Here are some examples of using colors with an alpha specification.
84
</p><p>
85
This sets the color used for labels to red=192, green=192, blue=33, and
86
alpha=50 (that is, 50/127 transparency).
87
</p><pre class="programlisting">$plot-&gt;SetTextColor(array(192, 192, 33, 50));
88
</pre><p>
89
</p><p>
90
This sets the color used for tick marks to the color 'blue' from the color
91
map, with alpha value 64 (64/127 transparency).
92
</p><pre class="programlisting">$plot-&gt;SetTickColor('blue:64');
93
</pre><p>
94
</p><p>
95
This sets colors for the first three data sets to red, green, and blue with
96
different alpha values. The three colors are represented using
97
different formats for illustration purposes.
98
</p><pre class="programlisting">$plot-&gt;SetDataColors(array(
99
      array(255, 0, 0, 60), // Red with alpha=60
100
      '#00ff0050',          // Green with alpha=80 (0x50)
101
      'blue:70'));          // Blue with alpha=70
102
</pre><p>
103
</p><p>
104
Instead of specifying the alpha value for each data set color, you can
105
provide a default alpha value for all data colors using the third argument to
106
This uses the colors specified in $my_color_array with a default alpha of
107
50. The default is applied to any color definition which does not already
108
have an alpha value.
109
<a class="xref" href="SetDataColors.html" title="SetDataColors"><span class="refentrytitle">SetDataColors</span></a>.
110
</p><pre class="programlisting">$plot-&gt;SetDataColors($my_color_array, NULL, 50);
111
</pre><p>
112
</p><p>
113
This can also be used to apply an alpha value to the default data colors.
114
This retains the default data colors, but applies alpha = 50 (50/127
115
transparency) to all the colors. This is a quick way to get partially
116
transparent data colors without re-specifying all the colors.
117
</p><pre class="programlisting">$plot-&gt;SetDataColors(NULL, NULL, 50);
118
</pre><p>
119
</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>
120
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>,
121
colors specifications can include an alpha value. Although this works with
122
palette images as well as truecolor images, specifying alpha values
123
with palette images provides limited value.
124
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
125
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
126
color map if SetRGBArray was not called, followed by a colon and an alpha
127
value as a decimal number, for example: 'red:60'. The alpha value is
128
between 0 (opaque) and 127 (transparent).
129
Note that colors in the color map can be defined with or without an alpha
130
value. An alpha value appended to the color name overrides any specified
131
in the color map. For example, if the color 'red2' is defined in the color
132
map as array(255,0,0,80) - that is, red with 80/127 transparency - then
133
'red2' has alpha of 80, and 'red2:40' has alpha of 40.
134
    </p></li><li class="listitem"><p>
135
Numeric color component values, in the form <code class="literal">#rrggbbaa</code>.
136
Here rr is red, gg is green, and bb is blue, and each component
137
value is represented as a 2-digit hexadecimal number between 00 and ff.
138
Also aa is alpha, represented as a 2 digit hexadecimal number between 00 and 7f.
139
For example, <code class="literal">#00ff0010</code> is green with 16/127 transparency.
140
    </p></li><li class="listitem"><p>
141
A PHP array of red, green, blue, and alpha color component values.
142
Each value of red, green, and blue are in the range 0 to 255 inclusive,
143
and the alpha component is in the range 0 to 127 inclusive.
144
For example,
145
<code class="literal">array(0,255,0,16)</code> is the same green with 16/127 transparency.
146
    </p></li></ol></div><p>
147
</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>
148
PHPlot can produce JPEG, PNG, and GIF image files (and possibly others).
149
You select the PHPlot output image file format with
150
<a class="xref" href="SetFileFormat.html" title="SetFileFormat"><span class="refentrytitle">SetFileFormat</span></a>.
151
</p><p>
152
PHPlot works with GD images before producing an image file. There are two
153
types of GD images: truecolor and palette. Truecolor images represent
154
pixels as 32 bit values, combining 8 bits each of red, green, and blue
155
components with a 7 bit alpha (transparency) value. Palette images use a
156
color table with at most 256 entries, and represent pixels as 8 bit indexes
157
into the color table. The palette image color table entries have 32 bit
158
values, with the same components as truecolor image pixel values. So
159
palette images in GD can have at most 256 unique colors, but there is no
160
limitation on the number of unique colors in truecolor images.
161
</p><p>
162
As long as you don't specify a background image when creating your plot object,
163
truecolor images are created with the <code class="literal">PHPlot_truecolor</code> class,
164
and palette images are created with the <code class="literal">PHPlot</code> class.
165
If you specify a background image, the GD image created by PHPlot matches the
166
type - truecolor or palette - of your background image file.
167
More on background image files can be found in
168
<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.
169
</p><p>
170
What happens when you output the GD image to an image file depends on the
171
image file format you select.
172
</p><p>
173
JPEG image files are always truecolor. Whether you have a GD palette image
174
or truecolor image, you will get a truecolor image file.  Note: You are
175
discouraged from using JPEG images with PHPlot, because they are not
176
optimal for this type of graphical information due to use of lossy
177
compression.
178
</p><p>
179
GIF image files are always palette type, limited to 256 colors. If
180
you have a GD palette image, you will get a palette GIF image file with the
181
colors you used in your plot. If you have a a GD truecolor image, GD will
182
convert your image to palette format, reducing the number of colors to 256
183
if necessary. This may change the appearance of your plot. Note that some
184
versions of the PHP manual for <code class="function">imagecreatetruecolor()</code>
185
incorrectly state that you cannot output a GIF file from a truecolor GD image.
186
</p><p>
187
PNG image files support truecolor images and palette images of various
188
color depths.  If you have a GD palette image, you will get a palette PNG
189
image file. If you have a GD truecolor image, you will get a truecolor PNG
190
image file. Note that by default, even though PNG truecolor image files
191
support an alpha channel, GD eliminates the alpha channel when producing a
192
PNG file. The visual effects of alpha blending are reproduced using opaque
193
colors. GD apparently does this due to poor support in viewers for alpha
194
channels. Refer to the PHP Manual page on
195
<code class="function">imagesavealpha()</code> for details.
196
</p><p>
197
The following figure shows the relationship between constructor, background
198
image format, GD image type, and image file format.
199
  </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>
200
</p><p>
201
In the initial release of Truecolor support in PHPlot-5.1.1, alpha channel
202
information was ignored when using a PHPlot object, and only used with a
203
PHPlot_truecolor object. This was changed in PHPlot-5.1.2, and alpha
204
channel information is used for both PHPlot and PHPlot_truecolor classes.
205
However, alpha channel information is not always useful with palette
206
images.
207
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.
208
</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>
209
All PHPlot plot types work with truecolor images, but not all plot types
210
work well with alpha blending of data colors.
211
</p><p>
212
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Pie Charts</span></dt><dd><p>
213
Avoid using alpha blending with pie charts. The underlying GD
214
routines do not fill the pie areas in a way that allows proper blending of
215
colors. Flat pie charts (using SetShading(0)) are not too bad, showing some
216
artifacts, but shaded or 3D-look pie charts are poorly rendered.
217
      </p></dd><dt><span class="term">Bar Charts, </span><span class="term">Stacked Bar Charts</span></dt><dd><p>
218
Bars are drawn properly, but the 3D shading affects get blended, resulting
219
in less than ideal appearance. Flat, outlined bars (using SetShading(0))
220
are fine with transparency, but when shading is on the 3D shadows overlap
221
portions of the bars. With alpha blending, the overlaps take on new colors.
222
      </p></dd></dl></div><p>
223
</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>
224
When creating a PHPlot or PHPlot_truecolor object, you can provide an
225
existing image filename to the constructor as the fourth argument,
226
<em class="parameter"><code>$input_file</code></em>.
227
</p><pre class="programlisting">$plot = new PHPlot(800, 600, NULL, 'myimage.png');
228
</pre><p>
229
This image file becomes the background for your plot. (The function
230
<a class="xref" href="dev-internal.html#SetInputFile">SetInputFile</a> also does this,
231
but is deprecated for use except through the constructor.)
232
</p><p>
233
If you provide an input file to the constructor, the image associated with
234
your PHPlot or PHPlot_truecolor object takes on the type of the input file:
235
palette or truecolor. It does not matter which constructor you use when
236
specifying an input file as background.
237
(This was changed after the initial release of truecolor support.
238
In PHPlot-5.1.1, you must use the PHPlot_truecolor constructor in order to
239
use some truecolor features even when you use a truecolor background
240
image file. Starting with PHPlot-5.1.2 you can use either constructor.)
241
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
242
The above applies only when an input file is specified to the PHPlot
243
or PHPlot_truecolor constructor.  It does not apply to
244
an image background set with <a class="xref" href="SetBgImage.html" title="SetBgImage"><span class="refentrytitle">SetBgImage</span></a>
245
nor to a plot area background set with <a class="xref" href="SetPlotAreaBgImage.html" title="SetPlotAreaBgImage"><span class="refentrytitle">SetPlotAreaBgImage</span></a>.
246
  </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>
247
Advanced operations on truecolor PHPlot images are possible using PHPlot
248
callbacks. See <a class="xref" href="callbacks.html" title="4.4. Callbacks">Section 4.4, &#8220;Callbacks&#8221;</a> for more information about using
249
callbacks.  Here are some of the operations you can perform, and the
250
corresponding GD functions.  Refer to the GD section of the PHP Manual for
251
more information on these functions.
252
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
253
Some of these functions are only available when PHP was built with the
254
bundled version of the GD library.
255
  </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>
256
You can turn on anti-aliasing of truecolor images. This must be done before
257
anything is drawn, so the pre-drawing callback <code class="literal">draw_setup</code>
258
is used. Here is a partial example:
259
</p><pre class="programlisting">function pre_plot($img)
260
{
261
    imageantialias($img, True);
262
}
263
...
264
$plot = new PHPlot_truecolor(1024, 768);
265
$plot-&gt;SetCallback('draw_setup', 'pre_plot');
266
</pre><p>
267
</p><p>
268
Note: There are limitations with anti-aliased images. You cannot use wide
269
lines (<a class="xref" href="SetLineWidths.html" title="SetLineWidths"><span class="refentrytitle">SetLineWidths</span></a>).
270
Patterned lines do not work, so if you are displaying
271
X or Y grid lines you must use <a class="xref" href="SetDrawDashedGrid.html" title="SetDrawDashedGrid"><span class="refentrytitle">SetDrawDashedGrid</span></a>(False)
272
to make these solid.
273
Also note that TrueType Font (TTF) text is always anti-aliased, even on
274
palette images, regardless of the use of <code class="function">imageantialias()</code>.
275
</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>
276
These functions control the combining of partially transparent colors. They
277
can be used via a <code class="literal">draw_setup</code> callback, in the same way
278
as <code class="function">imageantialias</code> in the example above.
279
Note that alpha blending is on by default with all truecolor images.
280
</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>
281
You can have the GD library perform gamma adjustment on a truecolor image.
282
This must be done after all drawing, so the post-drawing callback
283
<code class="literal">draw_all</code> is used. Here is a partial example:
284
</p><pre class="programlisting">function post_plot($img)
285
{
286
    imagegammacorrect($img, 1.0, 0.5); // Input gamma=1, output gamma=.5
287
}
288
 
289
...
290
$plot = new PHPlot_truecolor(1024, 768);
291
$plot-&gt;SetCallback('draw_all', 'post_plot');
292
</pre><p>
293
</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>
294
You will have a GD palette image if you use the <code class="literal">PHPlot</code>
295
constructor without a background image file, or if you use either the
296
<code class="literal">PHPlot</code> or <code class="literal">PHPlot_truecolor</code>
297
constructors with a background image file that is a palette image (GIF or
298
some types of PNG). You can use alpha color specifications with palette GD
299
images, but this is not recommended. The results are not well documented,
300
but the following behavior has been observed:
301
</p><p>
302
  </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
303
There is no alpha blending. Drawing operations simply replace existing
304
pixels values with the new pixel values. (These are actually index values
305
into the color table.)
306
      </p></li><li class="listitem"><p>
307
Alpha values are ignored when the image is output to a JPEG or GIF file.
308
All colors are output as opaque.
309
      </p></li><li class="listitem"><p>
310
Alpha values are preserved in PNG image files. These will be palette, not
311
truecolor, PNG images, with the color table containing the alpha values.
312
You can therefore have palette PNG files with partial transparency, however
313
not all viewers properly support this.
314
      </p></li></ul></div><p>
315
</p><p>
316
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
317
palette images, including gamma adjust and anti-aliasing (except that
318
TrueType Font text is always anti-aliased.)
319
</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>
320
PHPlot follows the GD Library convention here. Other systems use alpha=0 to
321
mean transparent, and a maximum alpha value to mean opaque.
322
  </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,
323
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>