Special Operators


This section presents a collection of operators that do not fit into any of the other categories. Nevertheless, most of them are extremely useful. Some of them are even necessary for the interaction of Cinderella and CindyScript.

Moving Elements


The calculations within CindyScript can be used to control the positions of free elements in a Cinderella construction. One way of doing this is to explicitly set the position information of a free element. For instance, if A is a free point, the line A.xy=[1,1] sets this point to the coordinates [1,1]. Another way of moving an element is with the moveto operator.


Moving a Free Element moveto(<geo>,<vec>):


Description: In this operator, <geo> is a free geometric object and <vec> describes a position to which this object should be moved. Invoking this operator simulates a move for this geometric object.

If <geo> is a free point, then <vec> can be a list [x,y] of two numbers or a list [x,y,z] of three numbers. The first case is interpreted as Euclidean coordinates, while the second case is interpreted as homogeneous coordinates and sets the point to [x/z,y/z].

If <geo> is a free line, then <vec> has to be a list of three numbers [a,b,c], and the line is set to the line described by the equation a∗x + b∗y + c = 0.

Examples: The following code lines summarize possible ways to move geometric elements (we also include the possibilities of moving elements by accessing their data fields):

//A is a free point
moveto(A,[1,4]);        //moves A to Euclidean coordinates [1,4]
A.xy=[1,4];             //moves A to Euclidean coordinates [1,4]
A.x=5;                  //sets the x coordinate of A to 5, lets the y coordinate unchanged
A.y=3;                  //sets the y coordinate of A to 3, lets the x coordinate unchanged
moveto(A,[2,3,2]);      //moves A to homogeneous coordinates [2,3,2]
A.homog=[2,3,2];        //moves A to homogeneous coordinates [2,3,2]

//a is a free line
moveto(a,[2,3,4]);      //moves a to homogeneous coordinates [2,3,4]
a.moveto=[2,3,4];       //moves a to homogeneous coordinates [2,3,4]

//b is a line through a point
a.slope=1;              //sets the slope of the line to 1

//C is a circle with free radius
C.radius=1;             //sets the radius of the circle to 1






Who has moved mover():


Description: This operator gives a handle to the element that is currently moved by the mouse.




The simulation simulation():


Description: This operator provides a handle to the simulation environment. With this operator one can access, for instance, the total kinetic or potential energy. The following fields are important in accessing a simulation:

  • friction: total friction of the simulation (real number, read write)
  • gravity: total gravity of the simulation (real number, read write)
  • kinetic: total kinetic energy of the simulation (real number, read only)
  • ke: total kinetic energy of the simulation (real number, read only)
  • potential: total potential energy of the simulation (real number, read only)
  • pe: total potential energy of the simulation (real number, read only)




User Input


Sometimes it is desirable to handle user input by mouse or the keyboard explicitly. There are special evaluation times "Mouse Down," "Mouse Up," "Mouse Click," "Mouse Drag," and "Key Typed" for this (see Entering Program Code). These evaluation times are captured exactly when the corresponding events occur. If one wants to react to the corresponding event data, there are two operators that read the input data.



Mouse position mouse():


Description: Returns a vector that represents the current position of the mouse if the mouse is pressed. The vector is given in homogeneous coordinates (this allows also for acces of inifite objects). If one needs the two-dimensional euclidean coordinates of the mouse position one can access them via mouse().xy.




Key input key():


Description: Returns a string that contains the last typed character.





Console Output


The CindyScript input window possesses a console to which one can direct text output. For most practical purposes this will not be used for the final construction. However, it is extremely useful for debugging.


Printing text print(<expr>):


Description: This operator prints the result of evaluating <expr> to the console.




Printing text err(<expr>):


Description: Prints the result of evaluating <expr> to the console. If <expr> is a variable, the variable name is printed as well. Very useful for debugging.




Printing text println(<expr>):


Description: This operator prints the result of evaluating <expr> to the console and adds a newline character to the end of the text.



Printing a newline println():


Description: This operator prints a newline character to the console.




Clearing the console clearconsole():


Description: Removes all text from the console.




Conditional print assert(<bool>,<expr>):


Description: This operator is mainly meant for convenience purpose when generating own error mesages. it is equivalent to if(!<bool>,println(<expr>)). It can be used to test wheter a condition is met and otherwise generate an error message.

Example: A typical usage of this operator may look as follows
assert(isinteger(k),"k is not an integer");









Time

CindyScript has an internal clock that provides access to the current date and time. The clock can be also used to synchronize some automated animations. Furthermore, an operator is provided that is synchronized with the current timestamp of a running animation or physics simulation.



Accessing time time():


Description: This operator returns a list [h,m,s,ms] of four integers. The four values correspond to "hour," "minute," "second," "millisecond" on the computer's clock.

Example: The following code produces a simple clock on a Cinderella view. The variable t contains the time information. The subsequent code is used to produce a clocklike drawing on the view. An auxiliary function p(w) is defined that produces points on the unit circle. The code must be placed in the "Tick" section of CindyScript in order for it to run continuously.


t=time();

p(x):=[sin(2*pi*x),cos(2*pi*x)];
O=[0,0];
S=p(t_3/60)*4;
M=p(t_2/60)*5;
H=p((t_1*60+t_2)/(12*60))*3.5;
draw(O,S);
draw(O,M,size->2);
draw(O,H,size->3);
apply(1..12,draw(p(#/12)*5));
apply(1..60,draw(p(#/60)*5,size->1));

drawtext((3,5),t);







Accessing the date date():


Description: This operator returns a list [y,m,d] of three integers. The three values correspond to "year," "month," and "day" on the computer's calendar.




Timestamp seconds():


Description: Returns the time elapsed since the last evaluation of resetclock(). The time is scaled in a way such that one unit corresponds to one second. The time's resolution is on the millisecond scale.




Resetting the internal seconds resetclock():


Description: Resets the value of the seconds() operator.




Accessing the timestamp of a simulation simulationtime():


Description: This operator gives a handle to the running time clock synchronized with the progression of an animation or simulation.

Caution: This operator is not yet properly implemented.





File operations


There is a limited number of operations that allow for the interaction of CindyScript with files that are stored elsewhere on the computer.



Loading data load(<string>):


Description: This operator takes the argument <string>, which is considered to be a file name (possibly preceded by directory information). If the file name is legitimate, then the entire information contained in the file will be returned as a string. This operator is particularly useful together with the tokenize operator, which helps to analyze structured data. The data are read from the currently active directory, which can be set with the setdirectory operator.

Example: Assume that in the file LoadDemo.txt the following data are stored:

abc,gfdg;1,3,5.6,3.141;56,abc,xxx,yyy

The following code reads the data and creates a list by tokenizing it with respect to ";" and ",".

x=load("LoadTest.txt");
y=tokenize(x,(";",","));
apply(y,println(#));


The resulting output is

[abc,gfdg]
[1,3,5.6,3.141]
[56,abc,xxx,yyy]





Importing program code import(<string>):


Description: This operator takes the argument <string>, which is considered to be a file name (including directory information). If the file name is legitimate, then the whole content of the file is assumed to be able to be parsed by CindyScript code, and it is immediately executed. In this way, one can load libraries with predefined functionality. It is advisable to use the import operator only in the "Init" section of CindyScript, since otherwise, the file will be read for each move.




Setting the directory setdirectory(<string>):


Description: This operator sets the directory for all subsequent file operations.





Opening a web page openurl(<string>):


Description: Opens a browser with the webpage given in <string>.





Parsing



Parsing a string parse(<string>):


Description: This operator parses a string to an expression and evaluates this expression. This operator is particularly useful in handling user input from text fields in a construction.

Examples:

expressionevaluates to
parse("3+7") 10


The code fragment

text="sin(x)+cos(x)";
f(x):=parse(text);


defines the function f(x) to be sin(x)+cos(x).





Interaction with geometry



Forcing a repaint operation repaint():


Description: This operator causes an immediate repaint of the drawing surface. This operator is meant to be used whenever a script has updated a construction and wants to display the changes. It is not allowd to use this operator in the draw or in the move slot.




Points on a locus locusdata(<locus>):


Description: This operator returns a list of points in xy-coordinates that are all on a locus given by the name <locus> of a geometric element.




Points on a locus incidences(<geo>):


Description: This operator returns a list all the elements that are generically incident to a geometric element <geo>.






Physics



Applying a force addforce(<mass>,<vec>):

Description: Applying a force <vec> to an existing mass <mass>. This operator is very useful to implement user defined force fields. It should be called in the Integration Tick slot.




Applying a force setforce(<mass>,<vec>):

Description: Setting the force <vec> for an existing mass <mass>. This operator is very useful to implement user defined force fields. It should be called in the Integration Tick slot.




Probing particle forces force(<vector>):


The operator force is closely related to physics simulations in CindyLab. It can be used for testing the force that would affect a mass particle at a specific position. The vector <vector> represents the position. The operator returns a two-dimensional vector that is the force at this position. If no modifiers are used, the operator assumes that the probe particle has mass=1, charge=1 and radius=1 (see Free Mass).

The following picture was generated using the drawforces operator and a color plot of the force operator. It shows the force field and force strength of the electrostatic field of two charges.




A.charge=(|C,G|-3)*3;
B.charge=(|E,H|-3)*3;
f(x):=max((0,min([x,1])));
colorplot([0.1,0.1,0.1]+hue(f(abs(force(#)/3))),(-10,-10),(20,10));
drawforces(stream->true,move->0.2,color->[0,0,0],resolution->10);


Modifiers: It is also possible to set the values of mass, charge and radius explicitly. Each of these values can be set by a modifier of the same name. If at least one of these values is set explicitly, then all unset values are set to zero. Thus force((0,0),charge->2) tests the force that would be present for a particle of charge=2, mass=0, and radius=0 at point [0,0].




Page last modified on Thursday 25 of May, 2006 [23:32:00 UTC].
The original document is available at http://doc.cinderella.de/tiki-index.php?page=Special%20Operators