On-line documentation systemWARNING: please do not rely on information from this page, as I am rewriting it. The auto-documentation is the place to look for reliable functions descriptions. Here are HTML pages directly generated from the KeyKit code: Functions libraryAn alternate way to browse the library is to use the on-line documentation facilities: funclist() functype() man() seecode() funclist(str) displays at the console a list of all KeyKit functions coded in the Keypath whose names contain the string str (a regular expression) functopic(str) displays at the console a list of all KeyKit functions coded in the Keypath whose topics (keywords) contain the string str (a regular expression). Only some GeoMaestro functions have defined topics, though. To get a list of all topics, call functopic() with no argument. man(fname) looks for documentation about the function called fname (a string) inside the code itself (there is a specific format for that, using the keywords #name, #usage, #desc and #see). It displays at the console all documentation it found, and if it found none it will at least display the first line of the function code, so that you know what are its arguments. It also gives the exact location of the code (file and line number) seecode() opens the text editor on the *.k file in the Keypath corresponding to the last successful call of man(). This way you can quickly have the function code at hand. Give it a try by typing the following commands at the console: funclist("note") man("makenote") seecode() If you're an Emacs user, you will find interest in the KeyKit major mode. Besides its editing utilities, it also includes a comprehensive auto-documentation browser; it is notably able to produce this kind of HTML pages. Now I have to go through my sources and make use of the documentation format so that the on-line system becomes comprehensive... it will take some time :) |
function NiceName(...) {return (HorribleName(...))}That's it !
[0 = 2, # number of tests in the region 1 = "(D_ = sqrt(Xx_*Xx_+Yy_*Yy_)) >= 1 && D_<=2 && Yy_>0", # first test: upper half of a ring 2 = "Xx_<0 && Yy_<0 && D_<=1"] # second test: quarter of a diskand here is the area it represents:
RD = RDisque(Or, 2)...its center is the origin and its radius is 2.
RD["rel"] = 1... its meaning as an optional argument in a projector call changes: this time, only the events located into the disk of radius 2 centered on their own projection on the support will be actually projected (the projected events will be the ones less than 2 units away from the support). The region follows the listening point on the support, so to say.
RD["rel"] = 0
Region(x, y, ch, reg)x, y: floats ch: integer (1 to NbCan) reg: regionReturns 1 if the triplet (x,y,ch) belongs to reg, else returns 0
...this is the basic function for using regions in GeoMaestro
RegionPoint(pt, region)pt: point reg: regionThis is a simpler version of Region(). It checks weither point pt belongs to reg (so here reg should be a pure geometrical region: with no test on the channel value)
RCanal(ch, ...) # region is the whole ch channel RDisque(c, r, ...) # disk centered on c with radius r RRect(a, b, ...) # rectangle whose corners are a and b RTri(a, b, c, ...) # triangle whose summits are a,b and ca, b, c: points r: float ch: integer (1 to NbCan)
these functions returns a region ("area" in french), either geometrical (disk, triangle, rectangle) or based on the channel value; they can also be combined
the (...) optional arguments are (op, reg):op: string ("" or "!") reg: regionop is an operator: if it is set to "!", the complementary of the region is returned.
reg is the optional region we're adding to (OR operator)
Example:Or = xy(0, 0) Oi = xy(0, 1) Oj = xy(1, 0) Reg1 = RTri(Or, Oi, Oj, "", RDisque(Or, 1, "!")) Reg2 = RRect(Oi, Oj, "", RDisque(Or, 1))... Reg1 is the area defined by the union of the whole plane minus the disk centered in Or with radius 1 (kind of a hole !) and the triangle (Or, Oi, Oj) (which is in the hole!). So it looks like the blue part in this picture:
... while Reg2 looks like this:
The above examples Reg1 and Reg2 shows AND-combinations of regions obtained within the definition of a new sub-region. But you can also combinate with OR or AND operators already existing regions with the following functions:
RegionET(reg1, reg2 , ...)RegionOU(reg1, reg2) reg1, reg2: regions (...): op, reg (see above) Intersection (ET=AND) and union (OU=OR) of two regions.
Let's see on a few examples:
this defines a ring:ring = RegionET(RDisque(Or, 1, "!"), RDisque(Or, 2))here we add the same ring to an existing "blob":blob = RegionET(RDisque(Or, 1, "!"), RDisque(Or, 2), "", blob)here is the region formed by two intersecting rings:ring1 = RegionET(RDisque(Or, 1, "!"), RDisque(Or, 2)) ring2 = RegionET(RDisque(Oi, 1, "!"), RDisque(Oi, 2)) inter = RegionET(ring1, ring2)...this to add inter to blob:blob = RegionOU(inter, blob)I suggest you try these examples at the console; to display regions in the GUI, click on [display] and enter the region's name.
SetEvPAC(ch, msb, p)ch: integer (1 to NbCan) msb, p: integers (0 to 127)write program change and MSB messages as the PAC value for channel ch
EvPAC(...)...: integers (1 to NbCan)returns the PAC values for channels (...) merged in a phrase
PlusP(a, b)
a,b: points
MPlusP(f, a, b)
f: float a,b: points
Milieu(a,b)a,b: points
returns the middle point of segment (a,b)
same as KeyKit xy() function, except that it doesn't transform float values to integer. Suitable to define points (two arguments) or segments (four arguments) from their coordinates.
Cerc(c, r)
c: point r: float
CerP(c, p)
c: point p: float
Seg(a,b)a,b: pointsorSeg(x0,y0,x1,y1)returns a segment defined by the corresponding arguments (the second syntax makes it identical to xyd() )
SegA(s)SegB(s)s: segment
returns one of the extremities of the segment s (as a point)
see here
Save geometrical objets in the BASE+"init.geo" file; this file is read by GeoMaestro when starting (see the Go() function in initialisations.k). All objects defined there (points, circles, regions, possibly arranged in arrays) are thus available in all GeoMaestro sessions. You can also directly edit this file with a text editor or a spreadsheet program.Sgeo(...)
Ct = xyd(1.5,-1) Circle = Cerc(Ct, 2.5) Sgeo("PCt", Ct, "Cir", Circle)... the two first lines define a point Ct and a circle Circle, the last one save them so that they will be available at the next GeoMaestro session under the names PCt and Cir.
Défini à la console: #points PCt 1.5 -1 #fin #cercles Cir 1.5 -1 2.5 #finsee also RemVar() et GVARS as an alternative way to keep the values of variables between two KeyKit sessions
see here
saves and restores arrays LOG, FT, FKK, FIF, SNARF and GVARS to/from a file.
default file name (if no argument is given): BASE+"variables.dat"
note: these arrays are also dumped with the GUI, so this is a parallel way to save and restore them
see here and an example here
see here
see here
see here
Geo(name, dir)name, dir: strings
Reads the .geo file whose name is dir+name+".geo"
When starting, GeoMaestro callsGeo("init", BASE)... which means it reads the BASE+"init.geo" file (see Sgeo())
Syntax of a .geo file:
declarations of objects must happen between specific tags; outside tags, you can write anything you want; between tags, comments must be preceded by #. Versions of GeoMaestro earlier than 1.003 don't accept tabulation: use spaces to separate fields.
Points are defined between the following tags:#points #finThree definition modes are available: rectangular, polar (start with "p") and relative (start with ">").
Example:#points Or 0 0 # Or = ["x"=0, "y"= 0] p Oj 1 0.5*Pi # Oj = Setpolar(1, 0.5*Pi) Oi 1 0 # Oi = ["x"=1, "y"= 0] > II 0 1 # II = PlusP(Oi, ["x"=0, "y"=1]) > II2 0 1 # II2 = PlusP(II, ["x"=0, "y"=1]) #finCircles are defined between the tags:#cercles #finTwo modes here: the circle center can be referenced by its name, or defined by its coordinates.
Example:#cercles C1 Or 1 # Or must have been defined before ! C2 0 0 2 # C2 = Cerc(["x"= 0, "y"=0], 2) #finRegions are defined between the tags:#regions #finThree types of region can be directly defined: triangle ("t"), disk ("d") and rectangle ("r").
Regions can also be combined with the logical operators AND ("ET") and OR ("OU").
Points used in declarations must be refered to using their names.
Example:#regions t Joe AA BB Ch2 # this defines a triangle called Joe # ..AA, BB and Ch2 are points (and must be defined before !) d Jack Or 2 # Jack is a disk of center Or and radius 2 r John AA BB # John is a rectangle whose diagonal is (AA, BB) t T1 Ch Chh BB # T1 is the intersection of T1, T2 and T3 ET t T2 Ch Ch2 AA # (all are triangles) ET t T3 AA BB Ch d D2 Chh 1 # D2 is the union of D2 and D1 OU d D1 Ch 1 # (both of them are disks) Jack # Jack becomes the union of previous Jack and D1 OU d D1 Ch 1 t- T1 Ch Chh BB # t-, d- and r- are used for complementary regions ET t- T2 Ch Ch2 AA ET t T3 AA BB Ch Mecs : Joe # Mecs is the union of Joe, John and Jack OU John OU Jack #fin
reads the MIDI file "filename" (and open a browser if given no argument), then convert it to the current tempo, so that it can be easily imported in a GeoMaestro scene. See here for a discussion on tempo matters, and tutorial 4 for an example of use.MIDIfile(filename)
UpdateNbCan(n)n: integer (n >= 16) Changes the number of GeoMaestro channels. It will change the format of the Ev, Volume, Pit, Dur, Pan, Time, Mer and CScore arrays. If the number of channels is reduced, the settings and events associated to the extra channels will be deleted.
NoDoubleQuotes(str) str: stringWhen called with no argument, this function lists at the console the aliases used to avoid double quotes in string indexes for array (see here). You can add your own aliases by updating the StringAlias array in intialisations.k
When call with argument str (a string), the corresponding replacement are done and a string without double quotes is returned. However, if it happens that a double quote is still present, an empty string is returned along with an error message at the console.
The main use of this function is to prevent strings containing double quotes to be dumped in one of the many tool's arrays, because this would make restoring the tool impossible.
same as KeyKit arraycopy() (I didn't know it already existed when I wrote it !)
you should always use ArCopy() or arraycopy() when setting an array value from another array, because arrays are pointers in KeyKit: if you simply say:array1 = array2...then array1 and array2 will refer to the same value: any change in array1 applies to array2 (and more trouble is to come if array1 is a global variable while array2 is local... or the opposite).
on the other hand, if you say:array1 = ArCopy(array2)...array1 and array2 are two distincts arrays
if arr is an array whose first-level integer indexes range from 0 or 1 to n without any missing number, thenSupprimeIndex(p, arr)returns arr with item number p deleted and the following indexes recalculated so that the last one is n-1 (other non-integer indexes are unchanged)
example:
Ar = [1 = "a", 2 = "b", 3 = "c", 4 = "d", "bof" = "et oui"] Br = SupprimeIndex(3, Ar)returns this value for Br:
[1 = "a", 2 = "b", 3 = "d", "bof" = "et oui"]
RemplaceInStr(string, s1, s2)replaces every occurence of substring s1 in string with substring s2 and returns the resulting string
Setpolar(a) Setpolar(r,theta) Getpolar(a) Getpolar(x, y)a: point r, theta, x, y: float
used to transform rectangular coordinates ["x"=.., "y"=..] to polar coordinates ["r"=.., "theta"=..]
IMPORTANT: the polar coordinates returned by Getpolar are not a valid point format for any other function than Setpolar()
SetpolarCP(a) SetpolarCP(r,theta) GetpolarCP(a) GetpolarCP(x, y)a: point r, theta, x, y: float
Same as Setpolar and Getpolar, but here the polar center is the point CentrePolaire, which is the origin of the polar grid and can take any value you want (Setpolar and Getpolar always refer to the origin point x=0,y=0)
IMPORTANT: the polar coordinates returned by GetpolarCP are not a valid point format for any other function than SetpolarCP()
Mod2Pi(angle)returns angle as a number from 0 to 2*Pi (not included)
Hexa(n)returns hexadecimal value for n (0 to 255) as a string
Hexa16(n)returns hexadecimal value for n (0 to 15) as a string
Arrondi(x)x: float
returns the closest integer to x
Signe(x)x: float
returns -1 if x <= 0 and 1 if x > 0
Abs(x)x: float
returns Signe(x)*x
EnvironEgal(x,y)returns 1 ifabs(x-y) < 0.001else returns 0
Id(arg,...)simply returns arg !
Minimum(x,y)returns x if x<y
else returns y
Maximun(x,y).. does the opposite
Dist(a,b)returns the distance (float) between points a and b
Thet(a,b)returns the angle between segment (a,b) and horizontal axe
Peri(c)c: circle
returns the perimeter of circle c
CreateNewEvent(x, y, ch, nodur) x, y: float ch: integer (1 to NbCan) nodur: phraseThe name says all...
PourToutEv(func,...) func: functionCalls func(ev, ...) for each active event ev
It is very important that func() returns an event value, because this will be the new value for ev; also, func() should not delete any event nor move an event from a channel to another; it can only change the event.
Example:function DispInfos(ev) { print(ev["x"], ev["y"], ev["nodur"]) return(ev) } PourToutEv(DispInfos)... will display x,y,and nodur values for each event in the Ev scene.
RemoveEv(ch,n) ch, n: integers (ch from 1 to NbCan)Removes (deletes !) event n in channel ch, and updates all index numbers for channel ch
EvLabeled(label) label: stringReturns the event labelled label, with the two extra fields "ch" and "n" allowing you to find back the event in the Ev array.
Example: if we haveEv[2][25] = ["x"=1, "y"=2, "nodur"='a', "label"="Charlotte"]then EvLabeled("Charlotte") returns the following array:["x"=1, "y"=2, "nodur"='a', "label"="Charlotte", "ch"=2, "n"=25]... usually only the "ch" and "n" fields are realy useful, since they make it possible to keep track of a specific event in a changing Ev scene (remember that the index number of an event is subject to changes, if others events are deleted or moved to another channel)