NAME
GraphBasics - toolbox for drawing text/line-segments to dvi for
mat
INCLUDE
include "GraphBasics.h"
SYNTAX
class GraphBasics
{
Os out;
ColorScale scale;
bool pen_up;
int spdim; // number of space dimensions
FieldPlotType plot_type;
String nameofset; // name/header for output file
SetOfNo(real) drawlinebuf,movelinebuf,pointbuf; // Buffers for point lists
real current_value,last_value,max_arrowlen;
Ptv(real) scalingfactors;
void addPointToList
(
SetOfNo(real)& buf,
const Ptv(real)& point
);
void flushLineBuf
(
SetOfNo(real)& buf,
const bool empty_list // false: last point in buffer is left
);
void flushPointBuf();
void writeLineBuf ();
void writePointBuf ();
void writePlotSpec ();
void writeValue();
bool penIsUp () const { return pen_up; }
bool penIsDown () const { return notbool(pen_up); }
void endOfDataSet ();
public:
GraphBasics
(
const String& filename, // name of output file
const int spacedim = 3, // Number of space dims
const FieldPlotType pltype = UNSPECIFIED, // plot type
const char* name_of_data_set = "NONAME",
const Format_type format = ASCII // ASCII/BINARY
);
~GraphBasics ();
void penUp() { pen_up = true; }
void penDown() { pen_up = false; }
void move (const Ptv(real)& to);
void move (const real x, const real y, const real z);
void move (const real x, const real y);
void drawLine (const Ptv(real)& from, const Ptv(real)& to);
void drawLine
(
const real xfrom,
const real yfrom,
const real zfrom,
const real xto,
const real yto,
const real zto
);
void drawLine
(
const real xfrom,
const real yfrom,
const real xto,
const real yto
);
// add to list:
void drawLine (const Ptv(real)& to);
void drawLine (const real x, const real y, const real z);
void drawLine (const real x, const real y);
void fillPolygon (const Ptv(real) points[], const int npoints);
void markPoint (const Ptv(real)& point);
void markPoint (const real x, const real y, const real z);
void markPoint (const real x, const real y);
void writeText
(
const char* text,
const Ptv(real)* start_pt = NULL,
const Ptv(real)* end_pt = NULL
);
void drawArrow
(
const Ptv(real)& start_pt,
const Ptv(real)& vector
);
void drawArrow
(
const real start_pt_x,
const real start_pt_y,
const real start_pt_z,
const real vector_x,
const real vector_y,
const real vector_z
);
void drawArrow
(
const real start_pt_x,
const real start_pt_y,
const real vector_x,
const real vector_y
);
void setValue (const real value);
void setMaxArrowLen (const real length);
// absolute foreground color information is written:
void setColorScale
(
const real min_value, // min value of scalar field
const Colors& low, // color associated with min_value
const real max_value, // max value of scalar field
const Colors& high // color associated with max_value
);
// absolute foreground color information is written:
void setColorScale
(
const real min_value, // min value of scalar field
const real r_low, // basic colors associated with min_value
const real g_low,
const real b_low,
const real max_value, // max value of scalar field
const real r_high, // basic colors associated with min_value
const real g_high,
const real b_high
);
// sets scaling factors for each coordinate direction:
void setCoordinateScalingFactors
(
const real xfactor = 1,
const real yfactor = 1,
const real zfactor = 1
);
int getDim () const {return spdim;}
void close (); // closes the output (forced by destruct.)
};
KEYWORDS
graphics, device independent graphics format, geometric primi
tives
DESCRIPTION
The class is a toolbox containing a collection of simple drawing
commands for drawing to a device independent graphical format.
The output in this format can then be filtered to a specific
device dependent format by an export module.
Note that the GraphBasics functions do not normally flush or
close the output file so this file may be incomplete after a call
to a GraphBasics function. To make the file complete and ready
for reading, call the close function. The close function physi
cally closes the file which means that the GraphBasics object
cannot be used after this (errors will occur when trying to write
to a closed file). Here is an example that illustrates the
importance of closing a GraphBasics object before using the out
put file:
GraphBasics plotter ("mygrid.gb", 2);
DrawFE::drawGrid (grid, plotter); // make a grid plot
plotter.close(); // important!!!
OpSysUtil::execFilter("gb2mtv", "mygrid.gb", "mygrid.mtv");
CONSTRUCTORS AND INITIALIZATION
The constructor takes the name of the output file, the number of
space dimensions, the plot type, and the name of the data set as
arguments. Only the name of the output file is strictly required
- the other parameters have sensible default values.
MEMBER FUNCTIONS
penUp - sets the artificial pen to UP position.
penDown - sets the artificial pen to DOWN position.
move - moves pen to given position. If pen is down, a line will
be drawn from the last position to the new. If pen is up, pen
will be moved to the new position without drawing. Value of the
line (e.g. represented as a color) will be as specified in the
last call to setValue.
drawLine - draws a line. If two points are given, a line will be
drawn from the first to the last. If only one point is given, a
line will be drawn from the last point given, if any, to the
given point.
fillPolygon - Fills the area defined by the points given with the
current color (value). There are no restrictions on the number of
points that can be specified, so the problems that might arise if
the number of points is bigger than the number of space dimen
sions has to be handled by the export modules or by the visual
ization tools.
markPoint - Marks the given point.
writeText - Writes the given text between two given points. If no
points are given, origo will be used for both the startpoint and
the endpoint. The result of this will depend on the chosen filter
and the visualization tool.
drawArrow - Draws an arrow from the given point along the given
vector.
setValue - Specifies a scalar value to be associated with all
primitives drawn until the next setValue call. This value will
typically be used by the export modules to find an absolute color
for the primitives, but some visualization tools have the ability
to do this themselves, and will therefore need only the values.
setMaxArrowLen - sets a maximum length for the arrows that will
be drawn by drawArrow.
setColorScale - sets a minimum and maximum scalar value, and one
color associated with each of these two values. This scale is the
basis for interpolations performed by the export modules or the
visualization tools. The function is overloaded, and can take a
color as input both as a Colors structure or as three separate
real values (RGB).
setCoordinateScalingFactors - sets scaling factors for each coor
dinate direction. The scaling factors default to 1, but can be
set explicitly with this function.
close - flushes all internal buffers and closes the output file.
The function is usually used when it is desireable to finish and
close the file at a particular point in a program. The destruc
tor also calls close, but since GraphBasics objects are usually
deleted automatically when they go out of scope, it may be too
late for the user to wait for the object to go out of scope
before the output file can be used.
Most of the functions are overloaded, and can take point input
either as a Ptv(real) vector, or as two or three real values,
depending on the number of space dimensions.
MORE EXPLANATION
There are overloaded versions of several of the functions to sim
plify usage. The overloading makes it possible to give coordi
nates as a Ptv (the Diffpack class for points), as two or three
separate real values depending on the number of dimensions, or as
a reference to a coordinate list. If a coordinate list (and
optionally a value list and/or a normal vector list of the same
length) has been given, you can use the functions using list ref
erences to produce more compact data files and thereby support
faster data transfer. Also, when exporting data to visualization
programs that support coordinate lists, program operation will
generally be much snappier. For visualization programs that do
not support coordinate lists the filters will expand the lists as
neccessary.
The setValue function in combination with the setColorScale func
tion enables the user to specify the color for each primitive. A
function call will determine the color attributes of all subse
quent primitives until the next function call. A color interpo
lation has to be performed to map a value to a color, given the
minimum and the maximum value and corresponding colors. This
color interpolation is performed by the filters, not by the
GraphBasics toolbox. This is to compensate for differences in
color representation from program to program.
Using the setNormal function for specifying surface normals
enables better shading methods in some visualization programs.
For programs which do not need or can not use such information,
the filters will ignore it. If the setNormal function has been
called, the specified normal will be used for all subsequent
primitives until the next setNormal function call.
Support for more geometric primitive types in the GraphBasics
toolbox might be introduced in the future to cover new drawing
algorithms.
EXAMPLES
First, we present a short code to show how to call GraphBasics
functions.
#include <GraphBasics.h>
#include <OpSysUtil.h>
int main (int argc, const char* argv[])
{
initDiffpack (argc, argv, true);
Ptv(real) n2(2),n3(3);
// 2D
GraphBasics gb2("gb2",2);
gb2.drawLine (-0.1,-0.1, 1.1,1.2);
n2.fill(0,0); gb2.writeText("p0",&n2);
n2.scan("0.5 0.5"); gb2.writeText("p0.5",&n2);
n2.fill(1,2); gb2.writeText("p12",&n2);
gb2.markPoint(0.2,1.3); gb2.markPoint(0.3,1.4);
// 3D
GraphBasics gb3("gb3",3);
n3.fill(0,0,0); gb3.writeText("p0",&n3);
n3.fill(0.5,0.5,0.5); gb3.writeText("p3D0.5",&n3);
n3.fill(1,2,1); gb3.writeText("p13",&n3);
gb3.markPoint(0.2,1.3,0.8); gb3.markPoint(0.3,1.4,1);
gb3.drawLine(-0.1,-0.1,-0.1,1.1,1.2,1);
gb2.close(); gb3.close();
OpSysUtil::execFilter ("gb2mtv", "gb2", "gb2.mtv");
OpSysUtil::execFilter ("gb2mtv", "gb3", "gb3.mtv");
#ifndef WIN32
OpSysUtil::execProgram ("plotmtv", "-3d gb2.mtv gb3.mtv");
#endif
}
Some examples of output files are now given. The important thing
about the syntax of the format is that commands are always pre
ceded by a '>'. This is the character used to search for the next
command, and this means that you can write comments of any length
right in front of the '>', as long as you avoid using this char
acter. First example:
ASCII
>NAME Test of this file format$
>TYPE UNSPECIFIED
Comments can be written between the commands.
>DIM 2
>COLORS
1.0 0.0 0.0
0.0 0.0 1.0
>SCALE -10.0 10.0
>VALUE -10.0
>MAX_ARROWLEN 1
>LINE : 3
2.0 3.1
4.3 2.5
2.4 1.2
>POINT : 2
0.0 0.0
1.0 -1.0
>VALUE 10.0
>POLYGON : 3
-1.3 -0.6
0.3 0.6
1.9 2.5
>TEXT :Positioned string$
-1.2 0 0.2
-0.2 1.2 4
Arrow takes startpoint and vector
>ARROW
-3.4 3.5
1.1 1.1
>TEXT FROM 2.3 7.5 : A positioned string$
>END
As you surely can deduce, the first number following the
LINE,POINT and POLYGON commands are the number of points that are
following. Note the colon after these commands. If this colon is
followed by a '@' character, it indicates the beginning of a
binary data section. A binary section will start with an int con
taining the number of points that will follow. Then a sequence of
numbers follows. This will be numpoints*numspacedim*sizeof(float)
long, and will be written in the xdr machine-independent data
format. Optionally, a BINARY parameter can be specified to the
GraphBasics constructor. In this case the whole output file will
be completely binary. The binary format is constructed like this
a '@' is the first character in the file (for the ASCII format
the file will start with ASCII). Following this character is an
integer containing the enum value of a command, and the data
needed for this command. Lists with variable numbers of points
will start with an int containing the number of points. After the
end of the point list is an integer containing the next command,
and so on.
The lines and points in this example will by be drawn in red,
while the VALUE command before the POLYGON command specifies that
the polygon and arrow will be blue. This is because of the fol
lowing relationship: the SCALE command gives a minimium and a
maximum value for the value entered by the VALUE command. The
COLORS command specifies two RGB colors corresponding to these
minimum and maximum values, and a color interpolation based on
this can be performed by either the export module or the visual
ization tool.
A short example of a three dimensional output
ASCII
Comments are OK.
>NAME Three-D$
>TYPE CONTOUR_LINES
>DIM 3
>COLORS
0.5 0.5 0.0
0.0 0.3 0.9
>SCALE 0 1
>VALUE 0.5
>MAX_ARROWLEN 1
>LINE : 2
0.4 0.2 0.9
1.1 2.5 2.3
>END
DEVELOPED BY
SINTEF Applied Mathematics, Oslo, Norway, and University of Oslo,
Dept. of Mathematics, Norway
AUTHOR
Fred Ivar Larsen, SINTEF/UiO