## Accessing Geometric Elements

The main communication between CindyScript and the geometry part of Cinderella is accomplished by accessing the geometric objects of a construction. Geometric elements can be accessed in two different ways: either one can access an element by the name of its label or one can access lists of elements by special CindyScript operators. The interaction between Cinderella and CindyScript gives CindyScript the possibility to read essentially all parameters of the elements of a geometric construction. Most parameters can also be set by CindyScript. The following sections first describe the possible ways to address geometric objects and then provide a detailed list of the admissible parameters.

### Accessing Elements by Their Names

Every element in a geometric construction has a unique name, its label. This name can be used as a handle to CindyScript. Formally, in CindyScript the element plays the role of a predefined variable. The different parameters can be read and set via the . operator (dot operator). For instance, the line of code
`A.size=20`
sets the size of point A in a construction to the value 20. If a point or a line is contained in an arithmetic operator without a dot operator, then it is automatically converted to a vector representing its position. Thus a point is converted into an `[x,y]` vector representing its two-dimensional coordinates. A line is converted to an `[x,y,z]` vector representing its homogeneous coordinates. However, the coordinates have to be set by explicit use of the dot operator. If a handle to a geometric object is not used in an arithmetic expression, then it is still passed to the calculation as the geometric object. Since these concepts are a bit subtle, we will clarify them with a few examples.
Assume that A, B, and C are points in a Cinderella construction. The line
`A.xy=(B+C)/2`
sets the point A to be the midpoint of B and C. These two points are contained in an arithmetic expression, and therefore they are immediately inverted to an `[x,y]` vector. Setting the position of point A has to be done by explicitly using the `.xy` parameter.
The following program sets the color of all three points to green:

    pts=[A,B,C];
    forall(pts,p,
      p.color=[0,1,0];
    )

In this code the point names are passed as handles to the list `pts`. Traversing the list with the `forall` operator puts this handles one after the other into the variable `p`, from which their color parameter is accessed.

### Lists of Elements

Sometimes it is not necessary to access points individually by their name. In particular, this happens whenever one is interested in performing an operation on all points in a construction. This may happen, for instance, when one wants to calculate the convex hull of a point set. For this, CindyScript provides several operators that return lists of elements. For instance, the operator `allpoints()` returns a list of all points of a construction. We will demonstrate this with a very tiny example. The following program changes the color of the points depending on their position relative to the y-axis:

    pts=allpoints();
    forall(pts,p,
      if(p.x<0,
        p.color=[1,1,0],
        p.color=[0,1,0];
       )
    )

The following picture shows the application of the code to a random collection of points.

Working with lists of points

### Parameters for Geometric Objects

We now start with a complete description of all parameters that are currently accessible via CindyScript. This list may very well be extended in future releases of Cinderella. For each parameter we list the type of value expected for the parameter, whether it is a read only or a read and write parameter, and a short description of its purpose. Possible parameter types are usually as follows:

- real: a real number
- int: an integer number
- bool: either `true` or `false`
- string: a sequence of characters
- 2-vector: a two-dimensional vector
- 3-vector: a three-dimensional vector
- 3x3-matrix: a 3 × 3 matrix

Writing a parameter may sometimes be allowed only for free objects. We mark this by the word "free" in the corresponding column.
Parameters for all geometric elements:

name | read | write | type | purpose
`color` | yes | yes | 3-vector | The (red, green, blue) color vector of the object
`colorhsb` | yes | yes | 3-vector | The (hue, saturation, black) color vector of the object
`isshowing` | yes | yes | bool | Whether the object is shown (this is inherited by all elements that depend on the object)
`alpha` | yes | yes | real | The opacity of the object (between 0.0 and 1.0)
`labelled` | yes | yes | bool | Whether the object shows its label
`label` | yes | no | string | The label of the object
`trace` | yes | yes | bool | Whether the object leaves a trace
`tracelength` | yes | yes | int | The length of the trace

Parameters for points:

name | read | write | type | purpose
`x` | yes | free | real | The x-coordinate of the point
`y` | yes | free | real | The y-coordinate of the point
`xy` | yes | free | 2-vector | The xy-coordinates of the point
`coord` | yes | free | 2-vector | The xy-coordinates of the point
`homog` | yes | free | 3-vector | The homogeneous coordinates of the point
`angle` | yes | free | real | Applies only to PointOnCircle objects. The angle of the point on the circle
`size` | yes | yes | int | The size of the point (0..40)

Parameters for lines:

name | read | write | type | purpose
`homog` | yes | free | 3-vector | The homogeneous coordinates of the line
`angle` | yes | free | real | The angle of the line
`slope` | yes | free | real | The slope of the line
`size` | yes | yes | int | The size of the line (0..10)

Parameters for circles and conics:

name | read | write | type | purpose
`center` | yes | free | real | The center of the circle
`radius` | yes | free | real | The radius of the circle
`size` | yes | yes | int | The size of the border line (0..10)

Parameters for texts:

name | read | write | type | purpose
`text` | yes | yes | string | The content of the text
`pressed` | yes | yes | boolean | The state of this text, if it is a button

Parameters for animations:

name | read | write | type | purpose
`run` | yes | yes | bool | Whether the animation is running
`speed` | yes | yes | real | The relative animation speed

Parameters for transformations:

name | read | write | type | purpose
`matrix` | yes | no | 3x3 matrix | The homogeneous matrix of the transformation
`inverse` | yes | no | 3x3 matrix | The homogeneous matrix of the inverse transformation

### Parameters for CindyLab Objects

It is not only geometric properties that can be accessed by CindyScript. The simulation parameters of CindyLab constructions can also be read and sometimes set via CindyScript.
Parameters for all CindyLab elements:

name | read | write | type | purpose
`simulate` | yes | yes | bool | Whether the object takes part in the physics simulation or is neglected

Parameters for masses:

name | read | write | type | purpose
`mass` | yes | yes | real | The mass of the object
`charge` | yes | yes | int | The charge of the object
`friction` | yes | yes | real | The individual friction of the object
`radius` | yes | yes | real | The radius if the mass is treated as a ball
`vx` | yes | yes | real | The x-component of the velocity
`vy` | yes | yes | real | The y-component of the velocity
`v` | yes | yes | 2-vector | The velocity vector
`fx` | yes | no | real | The x-component of the force acting on the particle
`fy` | yes | no | real | The y-component of the force acting on the particle
`f` | yes | no | 2-vector | The force vector acting on the particle
`kinetic` | yes | no | real | The kinetic energy of the particle
`ke` | yes | no | real | The kinetic energy of the particle

Parameters for springs and Coulomb forces:

name | read | write | type | purpose
`l` | yes | no | real | The current length of the spring
`lrest` | yes | no | real | The rest length of the spring
`ldiff` | yes | no | real | The distance to the rest length of the spring
`strength` | yes | yes | real | The spring constant
`f` | yes | no | real | The force vector caused by the spring
`amplitude` | yes | yes | real | The amplitude for actuation
`speed` | yes | yes | real | The speed for actuation
`potential` | yes | no | real | The potential energy in the spring
`pe` | yes | no | real | The potential energy in the spring

Parameter velocities:

name | read | write | type | purpose
`factor` | yes | yes | real | The multiplication factor between graphical representation and actual velocity

Parameters for gravity:

name | read | write | type | purpose
`strength` | yes | yes | real | The strength of the gravity field
`potential` | yes | no | real | The potential energy of all masses in the gravity field
`pe` | yes | no | real | The potential energy of all masses in the gravity field

Parameters for suns:

name | read | write | type | purpose
`mass` | yes | yes | real | The mass of the sun
`potential` | yes | no | real | The potential energy of all masses in the sun field
`pe` | yes | no | real | The potential energy of all masses in the sun field

Parameters for magnetic areas:

name | read | write | type | purpose
`strength` | yes | yes | real | The strength of the magnetic field
`friction` | yes | yes | real | The friction in the magnetic area

Parameters for bouncers and floors:

name | read | write | type | purpose
`xdamp` | yes | yes | real | Damping in the x-direction
`ydamp` | yes | yes | real | Damping in the y-direction

Parameters for the environment:
The environment can be accessed by the built-in operator `simulation()`. The following slots of the environment can be accessed:

name | read | write | type | purpose
`gravity` | yes | yes | real | The global gravity
`friction` | yes | yes | real | The global friction
`kinetic` | yes | no | real | The overall kinetic energy
`ke` | yes | no | real | The overall kinetic energy
`potential` | yes | no | real | The overall potential energy
`pe` | yes | no | real | The overall potential energy

Page last modified on Monday 30 of October, 2006 [14:24:44 UTC].
The original document is available at http://doc.cinderella.de/tiki-index.php?page=Accessing%20Geometric%20Elements