## `plot::Scene` -- a graphical scene

#### Introduction

`plot::Scene``(object1, object2...)` combines the graphical objects `object1`, `object2` etc. to a graphical scene.

#### Creating Elements

`plot::Scene(object1 <, object2...> <, option1, option2...>)`

#### Parameters

`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`

#### Related Domains

`RGB`

#### Related Functions

`plot`, `plot2d`, `plot3d`, `plot::copy`

#### Details

- Objects generated by `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`).

  See examples 1 and 2.

- Scene options `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

  See `plotOptions2d` for further details on each option.
- For three-dimensional graphical scenes the following options are available:

  `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

  See `plotOptions3d` for further details on each option.
- A so-called attribute of an object of the domain `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 `"defaultOptions2d"` and `"defaultOptions3d"`, respectively, where such options are replaced and added, respectively, which are given with the parameters `option1`... of the creating call. | 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!

#### Operands

The operands of an object of `plot::Scene` are the parameters `object1`, `object2`... (in this order).

#### Important Operations

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.

#### Result of Evaluation

Evaluating an object of type `plot::Scene` returns itself.

#### Function Call

Calling an object of `plot::Scene` as a function yields the object itself, regardless of the arguments. The arguments are not evaluated.

#### Entries

defaultOptions2d

  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.

optionNames2d

  is a set of the available option names for plots of two-dimensional graphical scenes.

defaultOptions3d

  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.

optionNames3d

  is a set of the available option names for plots of three-dimensional graphical scenes.

#### Method _index: indexed access to the operands of a graphical scene

- `_index(dom scene, positive integer i)`
- - Returns the `i`th graphical primitive of `scene`. If `i` is greater than the number of graphical primitives of `scene`, then `FAIL` is returned.
  - This method overloads the system function `_index`, i.e., one may use it in the form `scene[i]`, or in functional notation `_index(scene, i)`.

#### Method dimension: dimension of a graphical scene

- `dimension(dom scene)`
- - Returns the value of the attribute `dimension`, i.e., the integer 2 or 3 (see the table of attributes above).

#### Method getPlotdata: create the plot data of a graphical scene

- `getPlotdata(dom scene)`
- - Returns a list in the form `[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`.

  - Only those plot options will be included in the plot data of the point, that are contained in the table stored under the attribute `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.
  - The result is stored as the value of the attribute `plotdata` of `scene`.

#### Method nops: number of operands of a graphical scene

- `nops(dom scene)`
- - Returns the number of graphical primitives of `scene`.
  - This method overloads the system function `nops`, i.e., one may use it in the form `nops(scene)`.

#### Method op: extract operands of a graphical scene

- `op(dom scene, positive integer i)`
- - Returns the `i`th graphical primitive of `scene`. If `i` is greater than the number of graphical primitives of `scene`, then `FAIL` is returned.
  - This method overloads the system function `op`, i.e., one may use it in the form `op(scene, i)`.

#### Method set_index: set operands of a graphical scene

- `set_index(dom scene, positive integer i, graphprim o)`
- - Replaces the `i`th graphical primitive of `scene` by `o`.
  - If `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`.

#### Method slot: read and write attributes and plot options

- `slot(dom scene, string slotname)`
- - Reads the value of the slot `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.
  - If `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.

  - This method overloads the system function `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)`
- - Changes the value of the attribute or option with the name `slotname` to the value `val`.
  - If there is no attribute or option with the name `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.
  - This method overloads the system function `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)`.

#### Method checkOption2d: check a plot option

- `checkOption2d(equation OptionName = value)`
- - This method checks whether `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.
  - If both is correct, then the list `[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`.
  - Otherwise, the list `[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.

#### Method checkOption3d: check on plot options

- `checkOption3d(equation OptionName = value)`
- - This method checks whether `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.
  - If both is correct, then the list `[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`.
  - Otherwise, the list `[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.

#### Method copy: create a copy of a graphical scene

- `copy(dom scene)`
- - Returns a copy of the object `scene`.
  - This method is called from the function `plot::copy`. See its help page for details.

#### Method expose: expose the definition of a scene

- `expose(dom scene)`
- - This method returns a sequence of the graphical primitives of `scene`.
  - This method overloads the system function `expose`, i.e., one may use it in the form `expose(scene)`.

#### Method modify: modify a copy of a graphical scene

- `modify(dom scene, equation ident = val...)`
- - Creates a copy of the object `scene` and changes the slots `Name1`... of this copy to the new values `value1`...
  - The identifiers `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.

  - This method is called from the function `plot::modify`.

#### Method print: print a graphical scene

- `print(dom scene)`
- - This method returns an unevaluated expression of the form `plot::Scene()`. It is used to print objects of `plot::Scene` to the screen.
  - Call `expose(scene)` to expose the graphical primitives of the scene.
  - See the system function `print` for details.

#### Example 1

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)

#### Example 2

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)

#### Example 3

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)

#### Changes

- new function

Do you have questions or comments?
Copyright © SciFace Software GmbH & Co. KG 2000