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:

namereadwritetypepurpose
color yesyes 3-vectorThe (red, green, blue) color vector of the object
colorhsb yesyes 3-vectorThe (hue, saturation, black) color vector of the object
isshowing yesyes boolWhether the object is shown (this is inherited by all elements that depend on the object)
alpha yesyes realThe opacity of the object (between 0.0 and 1.0)
labelled yesyes boolWhether the object shows its label
label yesnostringThe label of the object
trace yesyesboolWhether the object leaves a trace
tracelength yesyesintThe length of the trace



Parameters for points:

namereadwritetypepurpose
x yesfreerealThe x-coordinate of the point
y yesfreerealThe y-coordinate of the point
xy yesfree2-vectorThe xy-coordinates of the point
coord yesfree2-vectorThe xy-coordinates of the point
homog yesfree3-vectorThe homogeneous coordinates of the point
angle yesfreerealApplies only to PointOnCircle objects. The angle of the point on the circle
size yesyesintThe size of the point (0..40)



Parameters for lines:

namereadwritetypepurpose
homog yesfree3-vectorThe homogeneous coordinates of the line
angle yesfreerealThe angle of the line
slope yesfreerealThe slope of the line
size yesyesintThe size of the line (0..10)



Parameters for circles and conics:

namereadwritetypepurpose
center yesfreerealThe center of the circle
radius yesfreerealThe radius of the circle
size yesyesintThe size of the border line (0..10)



Parameters for texts:

namereadwritetypepurpose
text yesyesstringThe content of the text
pressedyesyesbooleanThe state of this text, if it is a button



Parameters for animations:

namereadwritetypepurpose
run yesyesboolWhether the animation is running
speed yesyesrealThe relative animation speed



Parameters for transformations:

namereadwritetypepurpose
matrix yesno3x3 matrixThe homogeneous matrix of the transformation
inverse yesno3x3 matrixThe 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:

namereadwritetypepurpose
simulate yesyes boolWhether the object takes part in the physics simulation or is neglected



Parameters for masses:

namereadwritetypepurpose
mass yesyes realThe mass of the object
charge yesyes intThe charge of the object
friction yesyes realThe individual friction of the object
radius yesyes realThe radius if the mass is treated as a ball
vx yesyes realThe x-component of the velocity
vy yesyes realThe y-component of the velocity
v yesyes 2-vectorThe velocity vector
fx yesno realThe x-component of the force acting on the particle
fy yesno realThe y-component of the force acting on the particle
f yesno 2-vectorThe force vector acting on the particle
kinetic yesno realThe kinetic energy of the particle
ke yesno realThe kinetic energy of the particle



Parameters for springs and Coulomb forces:

namereadwritetypepurpose
l yesno realThe current length of the spring
lrest yesno realThe rest length of the spring
ldiff yesno realThe distance to the rest length of the spring
strength yesyes realThe spring constant
f yesno realThe force vector caused by the spring
amplitude yesyes realThe amplitude for actuation
speed yesyes realThe speed for actuation
potential yesno realThe potential energy in the spring
pe yesno realThe potential energy in the spring



Parameter velocities:

namereadwritetypepurpose
factor yesyes realThe multiplication factor between graphical representation and actual velocity



Parameters for gravity:

namereadwritetypepurpose
strength yesyes realThe strength of the gravity field
potential yesno realThe potential energy of all masses in the gravity field
pe yesno realThe potential energy of all masses in the gravity field



Parameters for suns:

namereadwritetypepurpose
mass yesyes realThe mass of the sun
potential yesno realThe potential energy of all masses in the sun field
pe yesno realThe potential energy of all masses in the sun field



Parameters for magnetic areas:

namereadwritetypepurpose
strength yesyes realThe strength of the magnetic field
friction yesyes realThe friction in the magnetic area



Parameters for bouncers and floors:

namereadwritetypepurpose
xdamp yesyes realDamping in the x-direction
ydamp yesyes realDamping 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:

namereadwritetypepurpose
gravity yesyes realThe global gravity
friction yesyes realThe global friction
kinetic yesno realThe overall kinetic energy
ke yesno realThe overall kinetic energy
potential yesno realThe overall potential energy
pe yesno realThe 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