plot::Scene
-- a graphical
sceneplot::Scene
(object1, object2...)
combines
the graphical objects object1
, object2
etc.
to a graphical scene.
plot::Scene(object1 <, object2...> <, option1,
option2...>)
scene |
- | a graphical scene: an object of domain type plot::Scene |
object1, object2, ... |
- | 2D or 3D graphical objects |
option1, option2, ... |
- | scene options of the form OptionName =
value |
plot
, plot2d
, plot3d
, plot::copy
plot::Scene
represent two- or
three-dimensional graphical scenes that can be displayed via
plot(...)
.
The parameters object1
, object2
etc. must
be graphical objects generated by routines of the library plot
. Graphical primitives
include graphs of functions (of domain type plot::Function2d
and plot::Function3d
), points and
polygons (of domain type plot::Point
and plot::Polygon
, respectively), and
surfaces (of domain type plot::Surface3d
).
option1
, option2
etc. are
specified by equations OptionName = value
. The following
tables give an overview of the available options for two- and
three-dimensional scenes.
This table contains options and their default values for two-dimensional graphical scenes:
OptionName (2D) |
admissible values | default value |
Arrows | TRUE , FALSE |
FALSE |
Axes | Box, Corner, None, Origin | Origin |
AxesOrigin | Automatic, [x0, y0]
|
Automatic |
AxesScaling | [Lin/Log, Lin/Log] | [Lin, Lin] |
BackGround | [r, g, b] |
RGB::White |
Discont | TRUE , FALSE |
FALSE |
FontFamily | "helvetica" , "lucida" ,
.. |
"helvetica" |
FontSize | positive integers | 8 |
FontStyle | "bold" , .. |
"bold" |
ForeGround | [r, g, b] |
RBG::Black |
GridLines | Automatic, None or [xValue, yValue] . Admissible values
for xValue , yValue are Automatic, integers, Steps =
d or Steps = [d,
n] . |
None |
GridLinesColor | [r, g, b] |
RGB::Gray |
GridLinesWidth | positive integers | 1 |
GridLinesStyle | SolidLines, DashedLines | DashedLines |
Labeling | TRUE , FALSE |
TRUE |
Labels | [string, string] |
["x", "y"] |
LineStyle | SolidLines, DashedLines | SolidLines |
LineWidth | positive integers | 1 |
PlotDevice | Screen, "filename" ,
["filename",Ascii] ,
["filename",Binary] |
Screen |
PointStyle | Circles, FilledCircles, FilledSquares, Squares | FilledSquares |
PointWidth | positive integers | 30 |
RealValuesOnly | TRUE , FALSE |
FALSE |
Scaling | Constrained, UnConstrained | UnConstrained |
Ticks | Automatic, None, an integer or [xValue, yValue] .
Admissible values for xValue , yValue are Automatic, an integer, Steps =
d , Steps = [d, n] or a
list of user defined ticks. |
Automatic |
Title | strings | "" |
TitlePosition | Above, Below, [x, y] |
Above |
ViewingBox | Automatic or [xValue,
yValue] . Admissible values for xValue ,
yValue are Automatic or a range
a..b . |
Automatic |
plotOptions2d
for further
details on each option.OptionName (3D) |
admissible values | default value |
Arrows | TRUE , FALSE |
FALSE |
Axes | Box, Corner, None, Origin | Box |
AxesOrigin | Automatic, [x0, y0,
z0] |
Automatic |
AxesScaling | [Lin/Log, Lin/Log, Lin/Log] | [Lin, Lin, Lin] |
BackGround | [r, g, b] |
RGB::White |
CameraPoint | Automatic, [x, y,
z] |
Automatic |
FocalPoint | Automatic, [x, y,
z] |
Automatic |
FontFamily | "helvetica" , "lucida" ,
.. |
"helvetica" |
FontSize | positive integers | 8 |
FontStyle | "bold" , .. |
"bold" |
ForeGround | [r, g, b] |
RGB::Black |
Labeling | TRUE , FALSE |
TRUE |
Labels | [string, string, string] |
["x","y","z"] |
LineStyle | SolidLines, DashedLines | SolidLines |
LineWidth | positive integers | 1 |
PlotDevice | Screen, "filename" ,
["filename",Ascii] ,
["filename",Binary] |
Screen |
PointStyle | Circles, FilledCircles, FilledSquares, Squares | FilledSquares |
PointWidth | positive integers | 30 |
Scaling | Constrained, UnConstrained | UnConstrained |
Ticks | Automatic, None or integers | Automatic |
Title | strings | "" |
TitlePosition | Above, Below, [x, y] |
Above |
ViewingBox | Automatic | Automatic |
plotOptions3d
for further
details on each option.plot::Scene
is a named entry of the object which can be
accessed via the slot operator ::
.
Each attribute has the property ``read'', i.e., the value of an
attribute attr
of a graphical primitive o
can
be read with o::attr
. If the attribute also has the
``write'' property, then the value of the attribute can be changed with
o::attr := new_value
. See example 3.
The following attributes are available for an object representing a graphical scene:
attribute | meaning | properties |
dimension |
The dimension of the scene, i.e., the integer 2 or 3. | read |
objects |
A list of the graphical primitives of the scene. A
graphical primitive is an object of type "graphprim" . The
initial value is the list [object1, object2...] of the
parameters object1 , object2 ... |
read/write |
options |
A table of plot options of the graphical scene. Note
that if you change the value of this attribute, the entries of the
assigned table are not checked to be valid plot options for graphical
scenes. Invalid entries lead to runtime errors.
The initial value of this attribute is the table stored under the
domain entry |
read/write |
plotdata |
List of the plot data of the graphical scene in a
plot2d and plot3d conforming syntax,
respectively. The value of this attribute can be read if the method
"getPlotdata" (see below) was called before. The initial
value is the empty list [] . |
read |
The graphical objects object1
,
object2
etc. must have the same dimension. A mix of two-
and three-dimensional primitives in a single scene is not
supported!
The operands of an object of plot::Scene
are the
parameters object1
, object2
... (in this
order).
Operands of a graphical scene can be accessed either using the
system function op
, the
index operator [ ]
, or
using the attribute objects
described above. For
example, if scene
is such an object, then the calls
op(scene,1)
, scene[1]
and
scene::objects[1]
return the parameter
object1
.
Via scene[1] := g
, the first object of the scene is
replaced by the graphical primitive g
(that must be of the
type "graphprim"
).
See the methods "op"
, "_index"
,
"set_index"
and "slot"
below.
Use the slot operator ::
to get or set plot options of
such objects afterwards, i.e., when they have been created. For
example, if scene
is such an object, then
scene::Axes := None
removes the axes in the graphical
scene.
Evaluating an object of type plot::Scene
returns
itself.
Calling an object of plot::Scene
as a function yields
the object itself, regardless of the arguments. The arguments are
not evaluated.
is a table of plot options for two-dimensional graphical scenes and
their default values. Each entry has the form OptionName =
default_value
.
When an object of the domain plot::Scene
is created,
then a copy of this table is stored under the attribute
options
(see the table of attributes above), where those
options are added and replaced, respectively, which are given by the
(optional) parameters option1
... of the creating call (see
``Creating Elements'' above).
Plot options, which are not contained in the table stored under the
attribute options
will not be included in the plot data of
the object created by the method "getPlotdata"
(see
below).
For those options, the corresponding default value internally set by
the function plot2d
is
used when plotting the object. See the table of plot options above,
which gives a summary of the available plot options for two-dimensional
graphical scenes and their default values.
To change the default value of some plot options, the option name
and its default value may be added to the table
"defaultOptions"
, or replaced by a new value,
respectively.
is a set of the available option names for plots of two-dimensional graphical scenes.
is a table of plot options for three-dimensional graphical scenes
and their default values. Each entry has the form OptionName =
default_value
.
When an object of the domain plot::Scene
is created,
then a copy of this table is stored under the attribute
options
(see the table of attributes above), where those
options are added and replaced, respectively, which are given by the
(optional) parameters option1
... of the creating call (see
``Creating Elements'' above).
Plot options, which are not contained in the table stored under the
attribute options
will not be included in the plot data of
the object created by the method "getPlotdata"
(see
below).
For those options, the corresponding default value internally set by
the function plot3d
is
used when plotting the object. See the table of plot options above,
which gives a summary of the available plot options for
three-dimensional graphical scenes and their default values.
To change the default value of some plot options, the option name
and its default value may be added to the table
"defaultOptions"
, or replaced by a new value,
respectively.
is a set of the available option names for plots of three-dimensional graphical scenes.
_index(dom scene, positive integer i)
i
th graphical primitive of
scene
. If i
is greater than the number of
graphical primitives of scene
, then FAIL
is
returned._index
, i.e., one may use it in the
form scene[i]
, or in functional notation
_index(scene, i)
.dimension(dom scene)
dimension
, i.e.,
the integer 2 or 3 (see the table of attributes
above).getPlotdata(dom scene)
[SceneOptions, [Mode = ...],
...]
, i.e., a plot description of scene
in a
plot2d
and plot3d
conforming syntax,
respectively.
For example, with s := plot::Scene::getPlotdata(scene)
the call plot2d(op(s)
and plot3d(op(s)
,
respectively, gives a plot of scene
.
options
(see the table of attributes above). For any other
plot option not contained in this table, the corresponding default
value set by the function plot2d
and plot3d
, respectively, for graphical
scenes is used when plotting the object.plotdata
of scene
.nops(dom scene)
scene
.nops
, i.e., one may use it in the form
nops(scene)
.op(dom scene, positive
integer i)
i
th graphical primitive of
scene
. If i
is greater than the number of
graphical primitives of scene
, then FAIL
is
returned.op
, i.e., one may use it in the form
op(scene, i)
.set_index(dom scene, positive integer i, graphprim
o)
i
th graphical primitive of
scene
by o
.i
is greater than the number of graphical
primitives of scene
, or if g
is not an object
of type "graphprim"
, then a warning message is issued. In
this case the call of this method has no effect on the object
scene
.slot(dom scene, string slotname)
slotname
of
scene
. slotname
may either be the name of an
attribute or the name of a plot option. See the tables of available
plot options and attributes above.slotname
is the name of a plot option, but the
option is not contained in the table stored under the attribute
options
, then FAIL
is returned.
If slotname
is an invalid attribute or option, then an
error message is issued.
slot
, i.e., one may use it in the form
scene::slotname_id
(here, slotname_id
must be
the identifier corresponding to the string slotname
), or
in functional notation slot(scene, slotname)
.slot(dom scene, string slotname, any val)
slotname
to the value val
.slotname
, or if val
is not an admissible
value for slotname
, then a warning message is issued. In
this case, the value of slotname
remains unchanged.slot
, i.e., one may use it in the form
scene::slotname_id := val
(here, slotname_id
must be the identifier corresponding to the string
slotname
), or in functional notation slot(scene,
slotname, val)
.checkOption2d(equation OptionName =
value)
OptionName
is a known plot
option for a two-dimensional scene (see the table of available plot
options above), and value
is an admissible value for this
option.[TRUE, OptionName,
newValue]
is returned. Note that the value of the option could
have been converted into an admissible format. Thus,
newValue
must be used as the value of the option
OptionName
instead of value
.[FALSE, error_msg]
is returned.
The string error_msg
is a description of the located
problem, which can be passed, for example, to the system function
error
to raise a
user-specified exception.checkOption3d(equation OptionName =
value)
OptionName
is a known plot
option for a three-dimensional scene (see the table of available plot
options above), and value
is an admissible value for this
option.[TRUE, OptionName,
newValue]
is returned. Note that the value of the option could
have been converted into an admissible format. Thus,
newValue
must be used as the value of the option
OptionName
instead of value
.[FALSE, error_msg]
is returned.
The string error_msg
is a description of the located
problem, which can be passed, for example, to the system function
error
to throw an error
message to the user.copy(dom scene)
scene
.plot::copy
. See its help page for
details.expose(dom scene)
scene
.expose
, i.e., one may use it in the
form expose(scene)
.modify(dom scene, equation ident = val...)
scene
and changes the
slots Name1
... of this copy to the new values
value1
...Name1
... must be names of attributes
or plot options of the domain plot::Scene
. Otherwise a
warning message is issued, and the slot remains unchanged. Also, if one
of the values value1
... is not an admissible value for the
corresponding attribute or plot option, respectively, the change of the
slot is ignored.
See the tables of available options and attributes above.
plot::modify
.print(dom scene)
plot::Scene()
. It is used to print objects of
plot::Scene
to the screen.expose(scene)
to expose the graphical primitives of the scene.print
for details.The following calls return objects representing the graphs of the sinus and cosinus function in the interval [0, 2*PI]:
>> f1 := plot::Function2d(sin(x), x = 0..2*PI); f2 := plot::Function2d( cos(x), x = 0..2*PI, Color = RGB::Blue )
plot::Function2d(sin(x), x = 0..2 PI) plot::Function2d(cos(x), x = 0..2 PI)
The call plot(f1, f2)
displays these graphs
f1
and f2
. In fact, the function plot
first creates a graphical
scene consisting of these two graphs as follows:
>> s := plot::Scene(f1, f2)
plot::Scene()
and then displays this scene:
>> plot(s)
To change default values of some scene options, pass the
scene options to the call of plot::Scene
as additional
arguments, or, if an object of plot::Scene
is already
created, change the value of the corresponding option with the slot
operator ::
and call plot
again to display the changed
object.
For example, to draw grid lines in the background of the plot of the
graphical scene s
created in the previous input, we
enter:
>> s::GridLines := Automatic: plot(s)
We create a graphical scene consisting of a graph of the sequence n -> sin(n)/n in the interval [1, 50], enclosed by the graphs of the functions x -> 1/x and x -> -1/x:
>> s := plot::Scene( plot::Function2d(1/x, x = 1..50), plot::Pointlist([n, sin(n)/n] $ n = 1..50, Color = RGB::Blue), plot::Function2d(-1/x, x = 1..50) )
plot::Scene()
We plot the scene:
>> plot(s)
One can access the graphical primitives of a graphical
scene using the index operator []
. For example, the sequence created
above is the second operand of the scene s
:
>> pl := s[2]
plot::Pointlist()
Any change of the object pl
, for example, a
change of some plot options, reacts on the plot of the scene
s
:
>> pl::PointWidth := 15: plot(s)
This is due to the reference effect for domains. If
changes of an object should not reflect the scene in that the object is
contained, one must first explicitly create a copy of the corresponding
object using the function plot::copy
:
>> pl2 := plot::copy(pl)
plot::Pointlist()
Now changes on the object pl2
do not react
on the object pl
of the graphical scene s
.
For example, if we change the draw mode of the point list
pl2
in order to connect every two points of the point list
by a line, the plot of the scene s
remains unchanged:
>> pl2::DrawMode := Connected: plot(s)
whereas the copied object pl2
is displayed
as follows:
>> plot(pl2)
This example illustrates how to read and write attributes of graphical scenes (see the table of available attributes in ``Details'' above).
Plot options, which are explicitly set for a graphical scene, are
stored under the attribute options
and can be read with
the slot operator ::
:
>> s := plot::Scene( plot::Curve2d([sin(x), cos(x)], x = 0..2*PI), Axes = Box ): s::options
table( TitlePosition = Above, PointWidth = 30, LineStyle = SolidLines, AxesScaling = [Lin, Lin], Axes = Box, BackGround = [1.0, 1.0, 1.0], Ticks = Automatic, ViewingBox = Automatic, RealValuesOnly = FALSE, Labeling = TRUE, Discont = FALSE, GridLinesStyle = DashedLines, ForeGround = [0.0, 0.0, 0.0], AxesOrigin = Automatic, LineWidth = 1, PointStyle = FilledSquares, GridLines = None, Arrows = FALSE, GridLinesWidth = 1, Scaling = UnConstrained, GridLinesColor = [0.752907, 0.752907, 0.752907] )
These are default values of some options of
two-dimensional graphical scenes, defined by the entry
"defaultOptions2d"
of the domain
plot::Scene
:
>> plot::Scene::defaultOptions2d
table( TitlePosition = Above, PointWidth = 30, LineStyle = SolidLines, AxesScaling = [Lin, Lin], Axes = Origin, BackGround = [1.0, 1.0, 1.0], Ticks = Automatic, ViewingBox = Automatic, RealValuesOnly = FALSE, Labeling = TRUE, Discont = FALSE, GridLinesStyle = DashedLines, ForeGround = [0.0, 0.0, 0.0], AxesOrigin = Automatic, LineWidth = 1, PointStyle = FilledSquares, GridLines = None, Arrows = FALSE, GridLinesWidth = 1, Scaling = UnConstrained, GridLinesColor = [0.752907, 0.752907, 0.752907] )
When the plot data of a graphical scene is created
(calling the method "getPlotdata"
), only those plot
options are used that are contained in the table
s::options
:
>> plot::Scene::getPlotdata(s)
[TitlePosition = Above, PointWidth = 30, LineStyle = SolidLines, AxesScaling = [Lin, Lin], Axes = Box, BackGround = [1.0, 1.0, 1.0], Ticks = Automatic, ViewingBox = Automatic, RealValuesOnly = FALSE, Labeling = TRUE, Discont = FALSE, GridLinesStyle = DashedLines, ForeGround = [0.0, 0.0, 0.0], AxesOrigin = Automatic, LineWidth = 1, PointStyle = FilledSquares, GridLines = None, Arrows = FALSE, GridLinesWidth = 1, Scaling = UnConstrained, GridLinesColor = [0.752907, 0.752907, 0.752907], [Mode = Curve, [sin(x), cos(x)], x = [0.0, 6.283185307], Grid = [100], Color = [Flat, [1.0, 0.0, 0.0]]]]
This means that for any other available scene option not
contained in the table s::options
(e.g., the option Title), the default value is internally set by the
function plot2d
when
plotting the scene.
Use delete
to remove
plot options set for a graphical scene:
>> delete s::options[Axes]: s::options
table( TitlePosition = Above, PointWidth = 30, LineStyle = SolidLines, AxesScaling = [Lin, Lin], BackGround = [1.0, 1.0, 1.0], Ticks = Automatic, ViewingBox = Automatic, RealValuesOnly = FALSE, Labeling = TRUE, Discont = FALSE, GridLinesStyle = DashedLines, ForeGround = [0.0, 0.0, 0.0], AxesOrigin = Automatic, LineWidth = 1, PointStyle = FilledSquares, GridLines = None, Arrows = FALSE, GridLinesWidth = 1, Scaling = UnConstrained, GridLinesColor = [0.752907, 0.752907, 0.752907] )
Now the value of the option Axes
is the default value set by plot2d
(which is the value
Origin
), or read from the preferences of the
MuPAD's graphic tool VCam:
>> plot(s)