WebSVN – cheapmusic – /www/code/phplot-6.2.0/phplotdocs/adv-imgmap.html

<?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.10. Image Maps for Plot Data</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-streaming.html" title="4.9. Streaming Plots" /><link rel="next" href="examples.html" title="Chapter 5. PHPlot Examples" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">4.10. Image Maps for Plot Data</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="adv-streaming.html">Prev</a> </td><th width="60%" align="center">Chapter 4. PHPlot Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="examples.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-imgmap"></a>4.10. Image Maps for Plot Data</h2></div></div></div><div class="abstract"><p class="title"><strong></strong></p><p>
This section describes the use of the <code class="literal">data_points</code>
callback to generate an HTML image map (or other similar construct) from
plot data.
An image map created using this callback will contain links from the
data points or shapes on the plot.
This feature was first added in PHPlot-5.7.0 as an experimental feature,
and was first documented in this Reference Manual with PHPlot-6.0.0.
  </p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
    Use of callbacks is documented in <a class="xref" href="callbacks.html" title="4.4. Callbacks">Section 4.4, &#8220;Callbacks&#8221;</a>.
  </p></div><p>
The <code class="literal">data_points</code> callback makes the
<a class="link" href="concepts.html#def-devcoor">device coordinates</a> of
plotted data available to a script using PHPlot.
If a script registers a function as a handler for the
<code class="literal">data_points</code> callback name, the function will be called
repeatedly when the plot is being generated.  Each call will contain
parameters describing the graphics for the corresponding data point.
These parameters can be used to create an HTML image map.
</p><p>
This feature is most likely only useful when generating embedded image data
with PHPlot.
(See <a class="xref" href="EncodeImage.html" title="EncodeImage"><span class="refentrytitle">EncodeImage</span></a> for details on embedded image data.)
This is because HTML requires the image map be included in the
HTML page which contains the reference to the plot image.
The browser will first request the HTML page, then make a second request for
the image. Normally, the image is generated by a script using PHPlot, but
the image map has to be available before this script runs.
Using embedded image data allows a single PHP script to produce both the
image map and the image data, and return the result as a single page.
</p><p>
Nevertheless, it is also possible to create an image map with a non-embedded
image.  See <a class="xref" href="adv-imgmap.html#adv-imgmap-nonembed" title="4.10.4. Image Maps with Non-embedded Image Data">Section 4.10.4, &#8220;Image Maps with Non-embedded Image Data&#8221;</a> for details.
</p><p>
The <code class="literal">data_points</code> callback works with the following plot
types:
  </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<a class="link" href="conc-plottypes.html#plottype-bars" title="3.4.2. Plot Type: bars (Bar Plot)">bars</a> and
<a class="link" href="conc-plottypes.html#plottype-stackedbars" title="3.4.15. Plot Type: stackedbars (Stacked Bar Plot)">stackedbars</a>
(both horizontal and vertical)
      </p></li><li class="listitem"><p>
<a class="link" href="conc-plottypes.html#plottype-boxes" title="3.4.3. Plot Type: boxes (Box Plot)">boxes</a>
      </p></li><li class="listitem"><p>
<a class="link" href="conc-plottypes.html#plottype-bubbles" title="3.4.4. Plot Type: bubbles (Bubble Plot)">bubbles</a>
      </p></li><li class="listitem"><p>
<a class="link" href="conc-plottypes.html#plottype-ohlc" title="3.4.9. Plot Type: ohlc (Basic OHLC Plot)">ohlc</a>,
<a class="link" href="conc-plottypes.html#plottype-candlesticks" title="3.4.5. Plot Type: candlesticks (OHLC Candlesticks Plot)">candlesticks</a>, and
<a class="link" href="conc-plottypes.html#plottype-candlesticks2" title="3.4.6. Plot Type: candlesticks2 (OHLC Filled Candlesticks Plot)">candlesticks2</a>
      </p></li><li class="listitem"><p>
<a class="link" href="conc-plottypes.html#plottype-pie" title="3.4.10. Plot Type: pie (Pie Plot)">pie</a>
      </p></li><li class="listitem"><p>
<a class="link" href="conc-plottypes.html#plottype-points" title="3.4.11. Plot Type: points (Styled Dot Plot)">points</a> and
<a class="link" href="conc-plottypes.html#plottype-linepoints" title="3.4.7. Plot Type: linepoints (Lines and Points Plot)">linepoints</a>
(both standard and error bar plots)
      </p></li></ul></div><p>
No other plot type is supported. This includes
<code class="literal">lines</code>,
<code class="literal">squared</code>, and
<code class="literal">thinbarline</code>,
which do not have well-defined areas which could map to data points, and
<code class="literal">area</code>,
<code class="literal">squaredarea</code>,
<code class="literal">stackedarea</code>, and
<code class="literal">stackedsquaredarea</code>
for which this feature has not been implemented.
</p><p>
The rest of this section contains details on the callback, usage with
each plot type, and additional information.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-imgmap-usage"></a>4.10.1. Image Maps - Usage</h3></div></div></div><p>
To register a callback function to handle <code class="literal">data_points</code>, use:
</p><pre class="programlisting">$plot-&gt;SetCallback('data_points', 'my_handler', $my_arg);
</pre><p>
Where <code class="literal">my_handler</code> is the name of your function,
<code class="literal">$my_arg</code> is an optional additional argument to pass
to your function.
</p><p>
The <code class="literal">data_points</code> callback function
(<code class="function">my_handler()</code> above) will be called with 5
fixed-purpose arguments followed by variable arguments. The number and
purpose of the variable arguments depends on the plot type.  If your
handler only needs to work with one specific plot type, you can declare
these arguments in your function definition.
</p><p>
If your handler must handle multiple plot types, define your function without
arguments and use <code class="function">func_get_arg()</code> or
<code class="function">func_get_args()</code> to access the arguments.
You can use the value of the 3rd argument, <code class="literal">$shape</code>,
to determine the number and usage of the variable arguments, since there is
one specific function argument set for each value of <code class="literal">$shape</code>.
See <a class="xref" href="adv-imgmap.html#adv-imgmap-callback" title="4.10.2. Image Maps - data_points Callback Parameter Summary">Section 4.10.2, &#8220;Image Maps - data_points Callback Parameter Summary&#8221;</a> for more information.
</p><p>
Here are the fixed arguments to the <code class="literal">data_points</code>
callback function, with this general declaration:
</p><pre class="programlisting">function my_handler($img, $passthru, $shape, $row, $column, ...)
</pre><p>
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">$img</span></dt><dd><p>
The image resource (standard for all callbacks).
Not generally used with a <code class="literal">data_points</code> callback, which
cannot safely draw on the image (since PHPlot is in the middle of drawing
the plot on the same image).
      </p></dd><dt><span class="term">$passthru</span></dt><dd><p>
Pass-through argument, supplied in the <a class="xref" href="SetCallback.html" title="SetCallback"><span class="refentrytitle">SetCallback</span></a>() call
(standard for all callbacks, referred to above as <code class="literal">$my_arg</code>).
You can use this however you want, or ignore it.
      </p></dd><dt><span class="term">$shape</span></dt><dd><p>
A word describing the shape of the area being described. This does not
necessarily correspond to an HTML image map &lt;area&gt; shape.
Each plot type passes a specific shape value, and the shape value defines
the usage of the variable arguments.
      </p></dd><dt><span class="term">$row</span></dt><dd><p>
The number of the data row being plotted. This typically corresponds
to the ordinal of the X axis values (Y for horizontal plots), starting
with 0 for the first point, 1 for the second point, etc.
      </p></dd><dt><span class="term">$column</span></dt><dd><p>
The column, or data set index, starting with 0 for the first data set.
This indicates which Y value for a given X, for example, or
which bar within a bar group, or segment within a stacked bar.
(For horizontal plots, this would indicate which X for a given Y.)
Always 0 for pie charts and OHLC plots, which only have a single data set.
      </p></dd></dl></div><p>
</p><p>
For the variable arguments, refer to the sections below which describe each
plot type.
</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="adv-imgmap-bars"></a>4.10.1.1. Image Maps from Bars and Stackedbars Plots</h4></div></div></div><p>
With plot types <a class="link" href="conc-plottypes.html#plottype-bars" title="3.4.2. Plot Type: bars (Bar Plot)">bars</a>
and <a class="link" href="conc-plottypes.html#plottype-stackedbars" title="3.4.15. Plot Type: stackedbars (Stacked Bar Plot)">stackedbars</a>,
an image map can be produced which indicates the area of each bar or stacked
bar segment. This works with both vertical and horizontal plots.
</p><p>
For bar and stackedbar plots, the <code class="literal">data_points</code> callback
has this form:
</p><pre class="programlisting">function my_handler($img, $passthru, $shape, $row, $column, $x1, $y1, $x2, $y2)
</pre><p>
The first 2 arguments are standard for all PHPlot callbacks and are not
described here. The next 3 arguments are common to all data_points
callbacks, and there are 4 additional arguments:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">$shape</span></dt><dd><p>
Always <code class="literal">rect</code>, indicating a rectangle shape.
      </p></dd><dt><span class="term">$row</span></dt><dd><p>
This is the bar group index.
The left-most bar group (for vertical bar charts) is row 0.
      </p></dd><dt><span class="term">$column</span></dt><dd><p>
This is the bar index within a group.  For vertical plot type 'bars', index 0
is the left-most in the group. For vertical plot type 'stackedbars', index 0
is the bar segment closest to the X axis.
      </p></dd><dt><span class="term">$x1, $y1</span></dt><dd><p>
Device coordinates of the upper left corner of a bar or segment.
      </p></dd><dt><span class="term">$x2, $y2</span></dt><dd><p>
Device coordinates of the lower right corner of a bar or segment.
      </p></dd></dl></div><p>
</p><p>
Generating an image map for bar and stackedbar plots is straight-forward.
The provided <code class="literal">$shape</code> and coordinates are compatible with
HTML &lt;area&gt; markup.
You must provide the URL, alternate text, and optionally a title (tooltip text).
</p><p>
This example appends the image map line to a string.
sprintf() is used to convert the coordinates to integers for cleaner HTML.
</p><pre class="programlisting">$coords = sprintf("%d,%d,%d,%d", $x1, $y1, $x2, $y2);
$image_map .= "  &lt;area shape=\"rect\" coords=\"$coords\""
          .. " title=\"$title_text\" alt=\"$alt_text\" href=\"$url\"&gt;\n";
</pre><p>
The <code class="literal">$url</code>, <code class="literal">$title_text</code>, and
<code class="literal">$alt_text</code> would typically depend on the passed
<code class="literal">$row</code> and <code class="literal">$column</code>.
</p><p>
Refer to <a class="xref" href="ex-imagemap-bars.html" title="5.44. Example - Image Map from Bar Chart">Section 5.44, &#8220;Example - Image Map from Bar Chart&#8221;</a> for a complete example of an
image map for a bar chart.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="adv-imgmap-boxes"></a>4.10.1.2. Image Maps from Box Plots</h4></div></div></div><p>
With plot type <a class="link" href="conc-plottypes.html#plottype-boxes" title="3.4.3. Plot Type: boxes (Box Plot)">boxes</a>, an image map
can be produced which indicates the area of each data point.
This area is the bounding box which includes the box and both whiskers.
The bounding box does not include any outliers.
</p><p>
For box plots, the <code class="literal">data_points</code> callback
has this form:
</p><pre class="programlisting">function my_handler($img, $passthru, $shape, $row, $column, $x1, $y1, $x2, $y2)
</pre><p>
The first 2 arguments are standard for all PHPlot callbacks and are not
described here. The next 3 arguments are common to all data_points
callbacks, and there are 4 additional arguments:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">$shape</span></dt><dd><p>
Always <code class="literal">rect</code>, indicating a rectangle shape.
      </p></dd><dt><span class="term">$row</span></dt><dd><p>
The index of the data row, starting with 0 for the first X value.
      </p></dd><dt><span class="term">$column</span></dt><dd><p>
This is unused, and always 0.
      </p></dd><dt><span class="term">$x1, $y1</span></dt><dd><p>
Device coordinates of the upper left corner.
      </p></dd><dt><span class="term">$x2, $y2</span></dt><dd><p>
Device coordinates of the lower right corner.
      </p></dd></dl></div><p>
The upper left and lower right coordinates above refer to the bounding box
as described above.
</p><p>
Generating an image map for box plots is straight-forward.
The provided <code class="literal">$shape</code> and coordinates are compatible with
HTML &lt;area&gt; markup.
You must provide the URL, alternate text, and optionally a title (tooltip text).
</p><p>
This example appends the image map line to a string.
sprintf() is used to convert the coordinates to integers for cleaner HTML.
</p><pre class="programlisting">$coords = sprintf("%d,%d,%d,%d", $x1, $y1, $x2, $y2);
$image_map .= "  &lt;area shape=\"rect\" coords=\"$coords\""
          .. " title=\"$title_text\" alt=\"$alt_text\" href=\"$url\"&gt;\n";
</pre><p>
The <code class="literal">$url</code>, <code class="literal">$title_text</code>, and
<code class="literal">$alt_text</code> would typically depend on the passed
<code class="literal">$row</code>.
</p><p>
<a class="xref" href="ex-imagemap-bars.html" title="5.44. Example - Image Map from Bar Chart">Section 5.44, &#8220;Example - Image Map from Bar Chart&#8221;</a> contains a complete example of an
image map for a bar chart, and the parameters and usage for box plots are
the same except that the $col (column) parameter is always 0, since there
is only one data set.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="adv-imgmap-bubble"></a>4.10.1.3. Image Maps from Bubbles Plots</h4></div></div></div><p>
With plot type <a class="link" href="conc-plottypes.html#plottype-bubbles" title="3.4.4. Plot Type: bubbles (Bubble Plot)">bubbles</a>,
an image map can be produced which indicates the area of each bubble.
</p><p>
For bubbles plots, the <code class="literal">data_points</code> callback
has this form:
</p><pre class="programlisting">function my_handler($img, $passthru, $shape, $row, $column, $x, $y, $diam)
</pre><p>
The first 2 arguments are standard for all PHPlot callbacks and are not
described here. The next 3 arguments are common to all data_points
callbacks, and there are 3 additional arguments:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">$shape</span></dt><dd><p>
Always <code class="literal">circle</code>, indicating a disk shape.
      </p></dd><dt><span class="term">$row</span></dt><dd><p>
The row is the index for the independent variable X.
The first X value has index 0.
      </p></dd><dt><span class="term">$column</span></dt><dd><p>
The column is the index for the dependent variable Y.
For the first (or only) dataset for each X, the column index is 0.
      </p></dd><dt><span class="term">$x, $y</span></dt><dd><p>
Device coordinates of the center of the bubble.
      </p></dd><dt><span class="term">$diam</span></dt><dd><p>
Diameter of the bubble, in pixels.
      </p></dd></dl></div><p>
</p><p>
Generating an image map for bubble plots is straight-forward.
PHPlot provides parameters that are compatible with HTML image map markup,
except that PHPlot provides a diameter, and HTML requires the radius.
</p><p>
Here is an example of generating one area in an image map from a bubbles
plot. You must provide the URL, alternate text, and
optionally a title (tooltip text).  This appends the image map line to a
string.  sprintf() is used to convert the coordinates to integers for
cleaner HTML. 
</p><pre class="programlisting">$coords = sprintf("%d,%d,%d", $x, $y, $diam / 2);
$image_map .= "  &lt;area shape=\"circle\" coords=\"$coords\""
            . " title=\"$title_text\" alt=\"$alt_text\" href=\"$url\"&gt;\n";
</pre><p>
The <code class="literal">$url</code>, <code class="literal">$title_text</code>, and
<code class="literal">$alt_text</code> would typically depend on the passed
<code class="literal">$row</code> and <code class="literal">$column</code>.
</p><p>
Other than the above code, a script to generate an image map for a bubbles
plot would be similar to <a class="xref" href="ex-imagemap-bars.html" title="5.44. Example - Image Map from Bar Chart">Section 5.44, &#8220;Example - Image Map from Bar Chart&#8221;</a>, which produces
a bar chart.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="adv-imgmap-ohlc"></a>4.10.1.4. Image Maps from Financial OHLC Plots</h4></div></div></div><p>
With plot types <a class="link" href="conc-plottypes.html#plottype-ohlc" title="3.4.9. Plot Type: ohlc (Basic OHLC Plot)">ohlc</a>,
<a class="link" href="conc-plottypes.html#plottype-candlesticks" title="3.4.5. Plot Type: candlesticks (OHLC Candlesticks Plot)">candlesticks</a>, and
<a class="link" href="conc-plottypes.html#plottype-candlesticks2" title="3.4.6. Plot Type: candlesticks2 (OHLC Filled Candlesticks Plot)">candlesticks2</a>
(collectively called OHLC - open, high, low, close plots),
an image map can be produced which indicates the area of each data point.
For candlesticks and candlesticks2 plots, this area is the bounding box
containing the candlestick and its wicks.
For ohlc plots, this area is the bounding box formed by the vertical line
and horizontal ticks.
</p><p>
For OHLC plots, the <code class="literal">data_points</code> callback
has this form:
</p><pre class="programlisting">function my_handler($img, $passthru, $shape, $row, $column, $x1, $y1, $x2, $y2)
</pre><p>
The first 2 arguments are standard for all PHPlot callbacks and are not
described here. The next 3 arguments are common to all data_points
callbacks, and there are 4 additional arguments:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">$shape</span></dt><dd><p>
Always <code class="literal">rect</code>, indicating a rectangle shape.
      </p></dd><dt><span class="term">$row</span></dt><dd><p>
The index of the data row, starting with 0 for the first X value.
      </p></dd><dt><span class="term">$column</span></dt><dd><p>
This is unused, and always 0.
      </p></dd><dt><span class="term">$x1, $y1</span></dt><dd><p>
Device coordinates of the upper left corner.
      </p></dd><dt><span class="term">$x2, $y2</span></dt><dd><p>
Device coordinates of the lower right corner.
      </p></dd></dl></div><p>
The upper left and lower right coordinates above refer to the bounding box
as described above.
</p><p>
Generating an image map for OHLC plots is straight-forward.
The provided <code class="literal">$shape</code> and coordinates are compatible with
HTML &lt;area&gt; markup.
You must provide the URL, alternate text, and optionally a title (tooltip text).
</p><p>
This example appends the image map line to a string.
sprintf() is used to convert the coordinates to integers for cleaner HTML.
</p><pre class="programlisting">$coords = sprintf("%d,%d,%d,%d", $x1, $y1, $x2, $y2);
$image_map .= "  &lt;area shape=\"rect\" coords=\"$coords\""
          .. " title=\"$title_text\" alt=\"$alt_text\" href=\"$url\"&gt;\n";
</pre><p>
The <code class="literal">$url</code>, <code class="literal">$title_text</code>, and
<code class="literal">$alt_text</code> would typically depend on the passed
<code class="literal">$row</code>.
</p><p>
<a class="xref" href="ex-imagemap-bars.html" title="5.44. Example - Image Map from Bar Chart">Section 5.44, &#8220;Example - Image Map from Bar Chart&#8221;</a> contains a complete example of an
image map for a bar chart, and the parameters and usage for OHLC plots are
the same except that the $col (column) parameter is always 0, since there
is only one data set.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="adv-imgmap-pie"></a>4.10.1.5. Image Maps from Pie Plots</h4></div></div></div><p>
With plot type <a class="link" href="conc-plottypes.html#plottype-pie" title="3.4.10. Plot Type: pie (Pie Plot)">pie</a>,
an image map can be produced which indicates the area of each pie segment.
However, PHPlot only supplies the values which identify the outline of the
pie segment, and HTML maps do not support areas of this shape.
Therefore, the callback handler function needs to generate
one or more polygons which approximate the pie segment area.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
PHPlot does not attempt to draw pie segments that are too small (due to
the implementation of the PHP/GD drawing function). If a segment's calculated
start angle and end angle are equal (after converting to integers), the
segment will not be drawn, and the data_points callback will not be called for
that segment.
  </p></div><p>
For pie charts, the <code class="literal">data_points</code> callback has this form:
</p><pre class="programlisting">function my_handler($img, $passthru, $shape, $row, $column, $x, $y,
                    $pie_width, $pie_height, $start_angle, $end_angle)
</pre><p>
The first 2 arguments are standard for all PHPlot callbacks and are not
described here. The next 3 arguments are common to all data_points
callbacks, and there are 6 additional arguments:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">$shape</span></dt><dd><p>
Always <code class="literal">pie</code>, indicating a pie segment of an ellipse.
      </p></dd><dt><span class="term">$row</span></dt><dd><p>
The pie segment index, starting at 0 for the first segment.
(By default, segments are drawn counter-clockwise from 0 degrees, but this
can be changed.)
      </p></dd><dt><span class="term">$column</span></dt><dd><p>
This is unused, and always 0.
      </p></dd><dt><span class="term">$x, $y</span></dt><dd><p>
Device coordinates of the center of the pie.
      </p></dd><dt><span class="term">$pie_width</span></dt><dd><p>
Horizontal diameter of the pie, in pixels.
      </p></dd><dt><span class="term">$pie_height</span></dt><dd><p>
Vertical diameter of the pie, in pixels.
      </p></dd><dt><span class="term">$start_angle</span></dt><dd><p>
Starting angle for the segment, in clockwise degrees (see note).
      </p></dd><dt><span class="term">$end_angle</span></dt><dd><p>
Ending angle for the segment, in clockwise degrees.
      </p></dd></dl></div><p>
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
<span class="emphasis"><em>clockwise degrees</em></span> means (360 - A), where A is an angle
measured in the conventional sense: counter-clockwise from the X axis.
For example, a pie segment that starts at the top of the pie ('North') and
ends at the bottom point ('South') would have start_angle=270 and end_angle=90.
The start_angle is always greater than the end angle.
  </p></div><p>
Generating an image map for pie charts is more involved than with other
plot types.
Each pie segment is defined by the ellipse center point, the two diameter
values, and the start and end angles.
Due to the PHP/GD implementation, PHPlot uses clockwise angles (360-A), so
the start_angle is greater than the end_angle, and the segment is drawn
clockwise from the end_angle to the start_angle.
</p><p>
HTML image maps do not support ellipse section shapes directly.
Therefore, the callback function has to approximate the area using one or
more polygons.
</p><p>
The method shown in the example linked below approximates the pie segment
area using a polygon with one point at the pie center, one point at each
end of the arc, and zero or more points along the arc , such that the
maximum separation of points along the circumference is no more than 20
degrees. This has been found to produce a good fit for image maps.  More
details on the method can be found in the example.
</p><p>
Once you have your points (converted to integers, in an array
<code class="literal">$points</code> with X and Y values alternating), you can generate
a line in the image map as follows.
This example appends the image map line to a string.
</p><pre class="programlisting">$coords = implode(',', $points);
$image_map .= "  &lt;area shape=\"poly\" coords=\"$coords\""
           .  " title=\"$title_text\" alt=\"$alt_text\" href=\"$url\"&gt;\n";
</pre><p>
The <code class="literal">$url</code>, <code class="literal">$title_text</code>, and
<code class="literal">$alt_text</code> would typically depend on the passed
<code class="literal">$row</code>.
</p><p>
Refer to <a class="xref" href="ex-imagemap-pie.html" title="5.45. Example - Image Map from Pie Chart">Section 5.45, &#8220;Example - Image Map from Pie Chart&#8221;</a> for a complete example of an
image map for a pie chart.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="adv-imgmap-points"></a>4.10.1.6. Image Maps from Points and Linepoints Plots</h4></div></div></div><p>
With plot types <a class="link" href="conc-plottypes.html#plottype-points" title="3.4.11. Plot Type: points (Styled Dot Plot)">points</a>
and <a class="link" href="conc-plottypes.html#plottype-linepoints" title="3.4.7. Plot Type: linepoints (Lines and Points Plot)">linepoints</a>,
an image map can be produced which indicates the area around each point.
The lines in a linepoints plot are not part of the image map areas.
This also works with error plots that use these plot types, however the
error bars are not part of the image map areas.
</p><p>
For points and linepoints plots, the <code class="literal">data_points</code> callback
has this form:
</p><pre class="programlisting">function my_handler($img, $passthru, $shape, $row, $column, $x, $y)
</pre><p>
The first 2 arguments are standard for all PHPlot callbacks and are not
described here. The next 3 arguments are common to all data_points
callbacks, and there are 2 additional arguments:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">$shape</span></dt><dd><p>
Always <code class="literal">dot</code>, indicating a single point.
      </p></dd><dt><span class="term">$row</span></dt><dd><p>
The row is the index for the independent variable X.
The first X value has index 0.
      </p></dd><dt><span class="term">$column</span></dt><dd><p>
The column is the index for the dependent variable Y.
For the first (or only) dataset for each X, the column index is 0.
      </p></dd><dt><span class="term">$x, $y</span></dt><dd><p>
Device coordinates of the center of the point marker.
      </p></dd></dl></div><p>
</p><p>
Generating an image map for points and linepoints plots is straight-forward.
PHPlot provides only the center coordinates for each point marker. It
does not indicate the shape or size of the marker, nor the coordinates of
any line segments or error bars. To generate an image map, you should use a
fixed radius size and define the image map areas as circles with that
radius centered around each data point. You need to choose a radius. A
larger radius provides a larger clickable area, but the area of adjacent
points may overlap.
</p><p>
Here is an example of generating one area in an image map from a points
or linepoints plot. You must provide the URL, alternate text, and
optionally a title (tooltip text).  This appends the image map line to a
string.  sprintf() is used to convert the coordinates to integers for
cleaner HTML.  This example uses a 20 pixel radius for the areas around
each data point.
</p><pre class="programlisting">define('MAP_RADIUS', 20); // Capture area circle radii
$coords = sprintf("%d,%d,%d", $x, $y, MAP_RADIUS);
$image_map .= "  &lt;area shape=\"circle\" coords=\"$coords\""
           . " title=\"$title_text\" alt=\"$alt_text\" href=\"$url\"&gt;\n";
</pre><p>
The <code class="literal">$url</code>, <code class="literal">$title_text</code>, and
<code class="literal">$alt_text</code> would typically depend on the passed
<code class="literal">$row</code> and <code class="literal">$column</code>.
</p><p>
Other than the above code, a script to generate an image map for a points or
linepoints plot would be similar to <a class="xref" href="ex-imagemap-bars.html" title="5.44. Example - Image Map from Bar Chart">Section 5.44, &#8220;Example - Image Map from Bar Chart&#8221;</a>, which
produces a bar chart.
</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-imgmap-callback"></a>4.10.2. Image Maps - data_points Callback Parameter Summary</h3></div></div></div><p>
The following table contains a summary of the <code class="literal">data_points</code>
callback parameters for each supported plot type.


</p><div class="informaltable"><table summary="data_points callback parameter summary" border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>Plot Type(s)</th><th>Callback Parameters / Notes</th></tr></thead><tbody><tr><td rowspan="2">bars, stackedbars </td><td>$img, $passthru, $shape='rect', $row, $column, $x1, $y1, $x2, $y2</td></tr><tr><td>
          Image map area does not include shading.
        </td></tr><tr><td rowspan="2">boxes</td><td>$img, $passthru, $shape='rect', $row, 0, $x1, $y1, $x2, $y2</td></tr><tr><td>
          Rectangle shape includes box and whiskers. It does not include
          any outliers.
        </td></tr><tr><td rowspan="2">bubbles</td><td>$img, $passthru, $shape='circle', $row, $column, $x, $y, $diam</td></tr><tr><td>
          x,y is center. Use diam/2 for radius in image map circle area.
        </td></tr><tr><td rowspan="2">candlesticks, candlesticks, ohlc</td><td>$img, $passthru, $shape='rect', $row, 0, $x1, $y1, $x2, $y2</td></tr><tr><td>
          Rectangle shape includes body, wicks, ticks of each candlestick
          or OHLC marker.
        </td></tr><tr><td rowspan="2">pie</td><td>$img, $passthru, $shape='pie', $row, 0, $x, $y, $width, $height, $start_angle, $end_angle</td></tr><tr><td>
          Callback needs to fit a polygon to the ellipse segment.
        </td></tr><tr><td rowspan="2">points, linepoints</td><td>$img, $passthru, $shape='dot', $row, $column, $x, $y</td></tr><tr><td>
          x,y is center. Supply a radius for image map circle areas.
          Image map area will cover the points only, not lines.
        </td></tr></tbody></table></div><p>
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-imgmap-impl-notes"></a>4.10.3. Image Maps - Implementation Notes and Limitations</h3></div></div></div><p>
Since most PHPlot scripts will not produce image maps, the burden of
converting data points into a format for HTML image maps was left to the
implementation in the callback function. This is why PHPlot passes the
diameter values it already calculated (instead of radius values), and why
pie chart segments must be interpolated by the callback function.
</p><p>
You can generate image maps for error plots (data types
<a class="link" href="conc-datatypes.html#data-data-error">data-data-error</a> and
<a class="link" href="conc-datatypes.html#data-data-yx-error">data-data-yx-error</a>)
with points and linepoints plot types, but the image map areas will not
include the error bars. For these plot types, the only the coordinates of
the data points are provided.
</p><p>
PHPlot does not provide the data values from the data array that go with
the points. If you need these values, for example in tooltips, your callback
function needs to get them from the data array, using the $row and $column
index values. This may be complex for pie charts (for example, if you want
tooltip text to show the percentage value of the pie segment).
<a class="xref" href="ex-imagemap-pie.html" title="5.45. Example - Image Map from Pie Chart">Section 5.45, &#8220;Example - Image Map from Pie Chart&#8221;</a> shows access to data values for a pie
chart in the simple case of data type <code class="literal">text-data-single</code>.
<a class="xref" href="ex-imagemap-nonembed.html" title="5.46. Example - Image Map and Non-embedded Plot Image">Section 5.46, &#8220;Example - Image Map and Non-embedded Plot Image&#8221;</a> shows access to data values for a
bar chart.
</p><p>
For OHLC plots (candlesticks, candlesticks2, and ohlc plot types), and
for box plots,
PHPlot does not provide the callback with the coordinates of individual
features (such as the candlestick body rather than the high point wick).
PHPlot only provides the bounding box rectangle for the overall data point
graphic.
</p><p>
The image map must be located in the same HTML file as the image reference.
Although the HTML definition of the <code class="literal">usemap</code> attribute
of the <code class="literal">&lt;img&gt;</code> tag seems to indicate that a URL to an
external file containing the map may be used, this does not in fact work.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-imgmap-nonembed"></a>4.10.4. Image Maps with Non-embedded Image Data</h3></div></div></div><p>
It is also possible to generate an image map when the PHPlot script
produces an image in the normal way (not embedded) and returns it to the
browser as image data.  But the script will need to run twice: once to
generate the PHPlot image, and once to generate the containing HTML page
with the image map.  (You can use two separate scripts instead, but this is
not recommended, since both operations must create identical plots so the
image map areas correspond to the plot areas.)
</p><p>
In the following example, the script normally generates an HTML page. The page
contains an image map, generated with PHPlot, and also a
<code class="literal">&lt;img&gt;</code> image tag which points back to the same script
to have it generate the plot image.
When requesting the image, the script adds a parameter 'mode=plot' to the
URL. This tells the second execution of the script to generate the image
data instead of the HTML page.
</p><p>
The obvious drawback to this method is that you are processing a complete
plot twice each time a plot is needed. The first time, only the image map
is needed, and the plot itself is discarded. This is inefficient, especially
if the plotting script needs to query a database or perform extensive
calculations.
</p><p>
Another concern is if the script queries a database, the data could change
between the two uses of the script, resulting in an image map and plot
which do not correlate.
</p><p>
The rest of this section contains selected, annotated code from
<a class="xref" href="ex-imagemap-nonembed.html" title="5.46. Example - Image Map and Non-embedded Plot Image">Section 5.46, &#8220;Example - Image Map and Non-embedded Plot Image&#8221;</a>.
</p><p>
Start by checking for the mode parameter:
</p><pre class="programlisting"># Produce an image if the URL has mode=plot, and an HTML page otherwise:
$do_html = empty($_GET['mode']) || $_GET['mode'] != 'plot';
</pre><p>
</p><p>
The callback handler is the same as the other imagemap examples, in that it
appends to the global string $image_map one line from the image map.
</p><pre class="programlisting"># Callback for 'data_points' : Generate 1 line in the image map.
function store_map($im, $data, $shape, $row, $col, $x1, $y1, $x2, $y2)
{ ... }
</pre><p>
</p><p>
The <code class="function">generate_html()</code> function creates the containing
HTML page. Only parts of the code are shown.
</p><pre class="programlisting">function generate_html()
{
    global $image_map;
</pre><p>
</p><p>
Create a self-referencing URL with mode=plot parameter for the
<code class="literal">&lt;img&gt;</code> tag:
</p><pre class="programlisting">    # If the URL already has parameters, use &amp; separator, else ?.
    $sep = empty($_SERVER['QUERY_STRING']) ? '?' : '&amp;';
    $url = htmlspecialchars($_SERVER['REQUEST_URI'] . $sep .  'mode=plot');
</pre><p>
</p><p>
Now generate the HTML page. Include the image map using the global string
<code class="literal">$image_map</code>, which our callback function has
built line-by-line as PHPlot produced the plot.
Also include the reference to the plot image. This will result in the browser
making a second request to the script, this time with the mode=plot parameter.
</p><pre class="programlisting">    echo &lt;&lt;&lt;END
&lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
     "http://www.w3.org/TR/html4/loose.dtd"&gt;
&lt;html&gt;
...
&lt;map name="map1"&gt;
$image_map
&lt;/map&gt;
...
&lt;img src="$url" alt="Plot image" usemap="#map1"&gt;
...
&lt;/html&gt;

END;
}
</pre><p>
</p><p>
This ends the <code class="function">generate_html()</code> function.
</p><p>
In the main body of the script, create a PHPlot object and configure the
plot as usual.  Set the <code class="literal">data_points</code> callback. (You need only
do this in the case of generating HTML, not the image case.)
There are two other places where the operation differs for the HTML or image
generation, based on the <code class="literal">$do_html</code> flag: disabling automatic
output with <a class="xref" href="SetPrintImage.html" title="SetPrintImage"><span class="refentrytitle">SetPrintImage</span></a>, and calling
the <code class="function">generate_html()</code> function at the end.
</p><pre class="programlisting">$plot = new PHPlot(800, 600);
if ($do_html) {
    // Do not output the image in this mode:
    $plot-&gt;SetPrintImage(False);
    // Set the callback for image map generation:
    $plot-&gt;SetCallback('data_points', 'store_map');
}
... // Set up the plot, data values, plot type, etc.
// Output the image (in plot mode), or build the image map (in html mode):
$plot-&gt;DrawGraph();
if ($do_html) generate_html();
</pre><p>
</p><p>
That's all. If <code class="literal">$do_html</code> is true, no image will be produced
(due to <code class="literal">SetPrintImage(False)</code>),
and <code class="function">generate_html()</code> will be called.
If <code class="literal">$do_html</code> is false, <code class="function">DrawGraph()</code>
will output the plot image, and the map data will be not be produced or output.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="adv-streaming.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="examples.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4.9. Streaming Plots </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 5. PHPlot Examples</td></tr></table></div></body></html>
Subversion Repositories cheapmusic

(root)/www/code/phplot-6.2.0/phplotdocs/adv-imgmap.html @ 111 – Rev 98
