view release on metacpan or  search on metacpan

lib/IUP/MglPlot.pod  view on Meta::CPAN

=for comment based on iup-3.9 - http://www.tecgraf.puc-rio.br/iup/en/ctrl/iup_mglplot.html

=head1 NAME

IUP::MglPlot - [GUI element] canvas-like element for creating 2D plots (based on MathGL library)

=head1 DESCRIPTION

Creates a L<MathGL|http://mathgl.sourceforge.net/> based element for creating 2D and 3D plots with interface similar to L<IUP::PPlot>.

=begin HTML

<p>
  <table border="1">
    <tbody>
    <tr>
      <td><img src="http://kmx.github.io/perl-iup/img-3.9/ctrl/iup_mglplot0.png" border="0"></td>
      <td><img src="http://kmx.github.io/perl-iup/img-3.9/ctrl/iup_mglplot1.png" border="0"></td>
    </tr>
    <tr>
      <td><img src="http://kmx.github.io/perl-iup/img-3.9/ctrl/iup_mglplot2.png" border="0"></td>
      <td><img src="http://kmx.github.io/perl-iup/img-3.9/ctrl/iup_mglplot3.png" border="0"></td>
    </tr>
  </table>
</p>

=end HTML

=head1 USAGE

=head2 CREATION - new() method

 $plot = IUP::MglPlot->new( TITLE=>"Simple Data", GRID=>"YES" );

B<Returns:> the identifier of the created element, or C<undef> if an error occurs.

NOTE: You can pass to C<new()> other C<ATTRIBUTE=E<gt>'value'> or C<CALLBACKNAME=E<gt>\&func> pairs relevant
to this element - see L<IUP::Manual::02_Elements|IUP::Manual::02_Elements/"new()">.

=head2 Guide

Each plot can contain 2 or 3 B<axes> (X and Y and/or Z), a B<title>, a
B< legend> B<box>, a B<colorbar>, a B<grid>, a B<dataset> B<area> and
as many B<datasets> you want.

Each dataset is added using the L<PlotAdd1D|/PlotAdd1D>, L<PlotAdd2D|/PlotAdd2D>, L<PlotAdd3D|/PlotAdd3D>, 
L<PlotInsert1D|/PlotInsert1D>, L<PlotInsert2D|/PlotInsert2D>, L<PlotInsert3D|/PlotInsert3D>
L<PlotSet1D|/PlotSet1D>, L<PlotSet2D|/PlotSet2D> and L<PlotSet3D|/PlotSet3D> functions. All other plot
parameters are configured by attributes.

If no attribute is set, the default values were selected to best
display the plot.

B<IMPORTANT>: When setting attributes the plot is NOT redrawn until the
REDRAW attribute is set or a redraw event occurs.

The B<dataset area> is delimited by the min/max axis attributes. Data
is only plotted inside the dataset area. This area defines the 2D or 3D
plot coordinate space. The screen area is a 2D pixels coordinate space.
And finally the dataset also defines a normalized space, that means
min/max is converted to 0-1.

The B<legend box> is a list of the dataset names, each one drawn with
the same color of the correspondent dataset. The box is located in one
of the four corners of the dataset area.

The B<colorbar> is an additional axis showing the the colors used to
pseudo color the data for some plot modes.

The B<grid> is automatically spaced accordingly the current axis
displayed values.

The B<title> is always centered in the top of the plot.

The B<axes> are positioned at the origin (0,0,0), but can be
automatically positioned at the left-bottom. If values are only
positive then the origin will be placed in left bottom position. If
values are negative and positive then origin will be placed inside the
plot. The ticks in the axis are also automatically distributed.

=head2 Data

MathGL supports several kinds of data. IUP::MglPlot restricts this to a
few combinations. First there are 3 major classes:

=over

=item * B<Linear> sequential data are simply a sequence of points whether in
1D, 2D or 3D coordinates.

=item * B<Planar> data is a bi-dimensional array of values, just like a digital
image. Each value is C<f(x,y)>, where C<x> belongs to C<[-1, 1]> and C<y> to C<[-1, 1]>.

=item * B<Volumetric> data is a tri-dimensional array of values, that
represents a 3D volume. Each value is C<f(x,y,z)>, where C<x> belongs
to C<[-1, 1]>, C<y> to C<[-1, 1]> and C<z> to C<[-1, 1]>.

=back

Planar and volumetric data can be very memory consuming, so be careful
when using them. Linear data is the same representation accepted by
L<IUP::PPlot>, with the exception that L<IUP::MglPlot> has support for 3D
coordinates. Also planar and volumetric data in L<IUP::MglPlot> have x, y
and z coordinates equidistantly distributed from 0 to count-1.

Planar and volumetric data are stored in a 1D dataset created by
L<PlotNewDataSet|/"PlotNewDataSet()">, and filled with L<PlotSetData|/"PlotSetData()">,
L<PlotLoadData|/"PlotLoadData()"> or L<SetFromFormula|/"SetFromFormula()"> functions only.

=head2 Interaction - Zoom and Pan

Zoom and Pan operations can be done using keyboard or mouse actions in
2D and 3D plots.

Zoom can be done using the mouse wheel (Zoom in: scroll up; Zoom out:
scroll down), the Ctrl+Left mouse button pressed and vertical mouse
movements (Zoom in: bottom-up; Zoom out: top-down) or the plus '+'
(Zoom in) and minus 'E<minus>' (Zoom out) keys.

Pan is done using horizontal and vertical mouse movements with the left
mouse button pressed. By keyboard, the Ctrl+arrow keys combinations can
be used to shift the window. Arrow keys can also be used without using
the Ctrl key to slower movements.

lib/IUP/MglPlot.pod  view on Meta::CPAN

B<$count_y>, and the number of empty lines or the number of form feeds
('\f') defines B<$count_z>.

I<Can be used for linear, planar or volumetric data, but linear data is
limited to 1D coordinates.> I<You can convert planar data into linear
data using the DS_REARRANGE and DS_SPLIT attributes.>

=head3 PlotDrawMark()

  $plot->PlotDrawMark($x, $y, $z);

Draws a mark at given position in plot coordinates. It can be used only
inside PREDRAW_CB and POSTDRAW_CB callbacks. The attributes DRAWCOLOR,
DRAWMARKSTYLE and DRAWMARKSIZE can be used to control mark appearance.

=head3 PlotDrawLine()

 $plot->PlotDrawLine($x1, $y1, $z1, $x2, $y2, $z2);

Draws a line from position 1 to position 2 in plot coordinates. It can
be used only inside PREDRAW_CB and POSTDRAW_CB callbacks. The
attributes DRAWCOLOR, DRAWLINESTYLE and DRAWLINEWIDTH can be used to
control line appearance.

=head3 PlotDrawText()

 $plot->PlotDrawText($text, $x, $y, $z);

Draws a text at given position in plot coordinates. It can be used only
inside PREDRAW_CB and POSTDRAW_CB callbacks. The attributes DRAWCOLOR,
DRAWTEXTALIGN, DRAWFONTSTYLE and DRAWFONTSIZE can be used to control
text appearance. DRAWTEXTALIGN can be LEFT, CENTER or RIGHT.

=head2 ATTRIBUTES

=over

=item B<ALPHA>

I<(non inheritable)> Alpha value for overall transparency. Used
only when TRANSPARENT=Yes. Default: 0.5

=item B<ANTIALIAS>

I<(non inheritable)> Enable or disable the anti-aliasing
support. For screen display only, ignored when OPENGL=NO. Default: Yes.
When enabled text has a much better rendering, but 3D graphs will not
process depth properly.

=item L<BGCOLOR|IUP::Manual::03_Attributes/BGCOLOR>

the background color. Default: "255 255 255".

=item B<ERRORMESSAGE>

I<(read-only)(non inheritable)> If not C<undef> returns the last error message reported by MathGL.

=item L<FONT|IUP::Manual::03_Attributes/FONT>

the default font used in all text
elements of the plot: title, legend and labels. Font support is done
using the libraries Freetype and FTGL, so TrueType (*.ttf) and OpenType
(*.otf) font files can be loaded. If the font is not located in the
system, then it will try to find the font file in the current
directory, or in the path from the "IUP_MGLFONTS" environment variable,
or in the path from the "MGLFONTS" global attribute, or in a system
folder. The font name will be combined with the path to compose a file
name. A full path can also be used. If the font load fail, an internal
MathGL font is used.

=item L<FGCOLOR|IUP::Manual::03_Attributes/FGCOLOR>

the default color used in all
text elements of the plot: title, legend and labels. Default: "0 0 0".

=item B<OPENGL>

L<(non inheritable)> Enable or disable the rendering in OpenGL.
Default: No. When NO the rendering is slower, but when Yes some
features does not behave as expected. See L<Known Issues|/"Known Issues">.

=item B<REDRAW>

I<(write-only)(non inheritable)> redraw the plot and update the
display. Value is ignored. All other attributes will B<NOT> update the
display, so you can set many attributes without visual output. If the
element is redraw by the system because of a redraw event or by a call
to IUP::Update, it will have the same effect as if REDRAW was set.

=item B<RESET>

I<(write-only) (non inheritable)> restores all attributes to
their default values. Value is ignored.

=item B<TRANSPARENT>

I<(non inheritable)> Enable or disable the transparency support. Default: No.

=back

=head3 Interaction (non inheritable)

=over

=item B<ROTATE>

I<(non inheritable)> define the angles of the axis rotation in
degrees for 3D plots. The format is "angleX:angleY:angleZ". As example,
the "0.0:90:0.0" rotates the Y-axis plot in 90 degrees. Partial values
are also accepted, like "60::E<minus>45" or "::30" or "120". Default:
0:0:0.

=item B<ZOOM>

I<(non inheritable)> define the zoom to 2D and 3D plots. The
format is "x1:y1:x2:y2" in normalized coordinates, limited to the
interval [0-1]. As example, the "0:0:1:1" set a plot to default view
(centered in the drawing area). Partial values are also accepted, like
"0.2:0.2" or ":0.3::1.3" or "E<minus>0.4". If values are set only to x1
and/or x2 coordinates, the zoom is restricted to the X axis. On the
other hand, if values are set only to y1 and/or y2 coordinates, the
zoom is restricted to the Y axis. Default: 0:0:1:1

=back

=head3 Title Configuration (non inheritable)

=over

=item B<TITLE>

I<(non inheritable)> the title. Located always at the top center area.

=item B<TITLECOLOR>

title color. Default: FGCOLOR.

=item B<TITLEFONTSIZE>

title font size factor. It is a multiple of the FONT
size. Default: 1.6

=item B<TITLEFONTSTYLE>

title font style. If not defined the FONT attribute
will be used instead. Set to C<undef>, to use the FONT attribute values.
Style can be "PLAIN", "BOLD", "ITALIC" or "BOLDITALIC".

=back

=head3 Legend Configuration (non inheritable)

=over

=item B<LEGEND>

shows or hides the legend box. Can be YES or NO. Default: NO. LEGENDSHOW is also accepted.

=item B<LEGENDBOX>

draws a box around the legend area. Default: YES.

=item B<LEGENDCOLOR>

title color. Default: FGCOLOR.

=item B<LEGENDFONTSIZE>

legend font size factor. It is a multiple of the
FONT size. Default: 0.8

=item B<LEGENDFONTSTYLE>

legend font style. If not defined the FONT
attribute will be used instead. Set to C<undef>, to use the FONT attribute
values. Style can be "PLAIN", "BOLD", "ITALIC" or "BOLDITALIC".

=item B<LEGENDPOS>

legend box position. Can be: "TOPLEFT", "TOPRIGHT",
"BOTTOMLEFT", or "BOTTOMRIGHT. Default: "TOPRIGHT".

=back

=head3 Colorbar Configuration (non inheritable)

=over

=item B<COLORBAR>

shows or hides the colorbar. Can be YES or NO. Default:
NO.

=item B<COLORBAR(pos)>

colorbar position. Can be: "LEFT, "TOP", "RIGHT",
"BOTTOM". Default: "RIGHT".

=item B<COLORBARRANGE>

interval of data values used for pseudo coloring in some plot modes. Must be "min:max" ("%g:%g in C). Default from AXS_?MIN to AXS_?MAX according to COLORBARAXISTICKS.

=item B<COLORBARAXISTICKS>

axis used as reference for colorbar ticks.
Default: Z

=back

=head3 Grid Configuration (non inheritable)

=over

=item B<GRID>

shows or hides the grid in both or a specific axis. Can be:
XYZ (YES), X, Y, Z, XY, XZ, YZ or NO. Default: NO. The values
HORIZONTAL (Y) and X (VERTICAL) are accepted for IUP::PPlot
compatibility.

=item B<GRIDCOLOR>

grid color. Default: "200 200 200".

=item B<GRIDLINESTYLE>

line style of the grid. Can be: "CONTINUOUS",
"DASHED", "DOTTED", "DASH_DOT", "DASH_DOT_DOT". Default is
"CONTINUOUS".

=back

=head3 Box Configuration (non inheritable)

=over

=item B<BOX>

draws a bounding box around the dataset area. Default: NO.

=item B<BOXTICKS>

if BOX=Yes then major ticks are also drawn along the box.
Default: YES.

=item B<BOXCOLOR>

box color. Default: FGCOLOR.

=back

=head3 Dataset List Management (non inheritable)

=over

=item B<CLEAR>

I<(write-only)> removes all datasets. Value is ignored.

=item B<COUNT>

I<(read-only)> total number of datasets.

=item B<CURRENT>

current dataset index. Default is -1. When a dataset is
added it becomes the current dataset. The index starts at 0. All "DS_*"
attributes are dependent on this value.

=item B<REMOVE>

I<(write-only)> removes a dataset given its index.

=back

=head3 Dataset Configuration (non inheritable)

=over

=item B<DS_COLOR>

color of the current dataset and it legend text. Default
is dynamically generated for the 6 first datasets, others are default
to black "0 0 0". The first 6 are: 0="255 0 0", 1="0 0 255", 2="0 255
0", 3="0 255 255", 4="255 0 255", 5="255 255 0".

=item B<DS_COUNT>

I<(read-only)> returns the number of samples of the current
dataset. For planar or volumetric datasets returns count_x * count_y * count_z.

=item B<DS_DIMENSION>

I<(read-only)> returns the number of dimensions of the
data: 1, 2 or 3. For planar and volumetric datasets returns the actual
size of each dimension C<count_x x count_y x count_z>, for example
"600x400x1" (planar) or "512x512x512" (volumetric).

=item B<DS_LEGEND>

legend text of the current dataset. Default is
dynamically generated: "plot 0", "plot 1", "plot 2", ...

=item B<DS_LINESTYLE>

line style of the current dataset. Can be:
"CONTINUOUS", "LONGDASHED", "DASHED", "SMALLDASHED", "DOTTED",
"DASH_DOT", "SMALLDASH_DOT". Default is "CONTINUOUS".

=item B<DS_LINEWIDTH>

line width of the current dataset. Default: 1.0.

=item B<DS_MARKSTYLE>

mark style of the current dataset. Can be: "PLUS",
"STAR", "CIRCLE", "X", "BOX", "DIAMOND", "HOLLOW_CIRCLE", "HOLLOW_BOX",
"HOLLOW_DIAMOND". Default is "X".

=item B<DS_MARKSIZE>

mark size of the current dataset in normalized
coordinates. Default: 0.02.

=item B<DS_MODE>

drawing mode of the current dataset. Default: "LINE".

=over

Can be: LINE, BAR, MARK, MARKLINE, RADAR, AREA, BARHORIZONTAL, CHART,
STEP or STEM for linear datasets.

Can be: PLANAR_MESH, PLANAR_FALL, PLANAR_BELT, PLANAR_SURFACE,
PLANAR_BOXES, PLANAR_TILE, PLANAR_DENSITY, PLANAR_CONTOUR,
PLANAR_AXIALCONTOUR or PLANAR_GRADIENTLINES for planar datasets.

Can be: VOLUME_ISOSURFACE, VOLUME_DENSITY, VOLUME_CONTOUR or
VOLUME_CLOUD for volumetric datasets.

Each of these modes can have secondary attributes, that can be
configured only for the plot, and not for a specific dataset. See more
at L<DS_MODE Options|/"DS_MODE Options">.

=back

=item B<DS_REARRANGE>

I<(write-only)> rearrange planar data into linear data.
Value is ignored. It can rearrange planar data with count_y=2 or
count_y=3, into 2D or 3D linear data accordingly. It can also rearrange
planar data with count_y!=1 and count_x=2 or count_x=3 into 2D or 3D
linear data accordingly.

=item B<DS_SPLIT>

I<(write-only)> rearrange planar data into linear data, but
spliting into different datasets. It can rearrange planar data with
count_y=2 or count_y=3, into 2 or 3 datasets of 1D linear data
accordingly. The current dataset is modified and 1 or 2 new datasets
are created accordingly.