Thanks Ray. Some notes on your document:

This paragraph: "All Files must start with a 0,0 or 0,1 position. The end pair of numbers in the file must end with rho value opposite of the rho value in the first pair (if you start with a 0,0 you end with a theta, 0)" says three different and conflicting things. None of them are true. In fact, you must start with rho equal to 0 or 1. The theta values don't matter. The initial theta is treated as a "starting theta" and all subsequent thetas are relative to it. The ending theta does not need to be 0 or the starting theta.

This note "There are 2 'types' of instructions that the table can understand based on the difference between the theta values in the next set of instructions in the data set." is also not strictly true. The table only has one type of instruction, and that's a theta,rho pair. It moves that ball to that new position, interpolating in polar coordinates to get there. That's all. There isn't anything special about an erase (except the filename, which makes it run faster).

In my path generators some of them think in polar but convert to cartesian, and then all of them subdivide cartesian lines or bezier segments down until they are small enough and then output them as .thr polar. In that backend I also look for "too small" of polar movements and remove points to keep file sizes down. The values I use for cartesian subdivison and polar point removal are tuned to not make artifacts, but also not make too big of file.

Thanks Ray, for your extensive work in documenting some of the fundamentals underpinning how the Sisyphus file format works so others can create their own programs to create tracks. For the most part, you have correctly outlined these - but there are a pointers I'd like to add, clarify, or correct:

1.  All track files (filename.thr), must start with their Rho value either 0 or 1, and end with Rho either 0 or 1 - end and start Rho can be the same. I chose to start with this limitation so that tracks could easily be linked together without distracting traces connecting a new track's start to the last track's end. Therefore, there are four track "flavors": 00, 01, 10, 11. If a track finishes playing at Rho = 1, and the next track's start Rho is 0, the program will try to reverse the track - which will works for 01 and 10 tracks. If reversing doesn't fix it, the program adds an arc move out to the start of the next track. I call this limitation "conformality" and tracks that  abide by it, "conformal." (In the future, I would like to add an additional allowed start and end Rho at the "equator," meaning Rho = 0.5.)
2. Conformality ONLY applies to start and end Rho values. Theta at the start and end can be any real number (negative, zero, or positive). When a track starts, regardless of what the last track's last Theta was, it begins from that position, with all the next track's Theta movements relative to it. Again - this choice was to make linking tracks in a playlist more seamless.
3. There is only one "type" of move between two vertices (2D polar points, Theta value, Rho value). What you are calling an "Erase spiral" is just a long "Normal Movement."  Just as in a Cartesian (XY) system, a straight line can be defined by two points (no matter how long it is), the same is true in Sisyphus's polar system, except "lines" between two points are now Archimedes' spirals. All moves between points in the *.thr file are  spiral moves (pure Rho or pure Theta moves being special cases of a  "spiral").
4. In an XY system, if you are limited to only creating straight lines between points, but want to draw a curve, you can use lots of little straight segments to emulate the curve (more XY points = smoother curve). Analogously, in Sisyphus's polar system, if you want to draw a straight path on the sand, you do it by connecting lots of small spiral moves (add more polar points). Once you understand the curved nature of how the mechanism moves between two polar points in a *.thr file, there is nothing surprising about this being more pronounced near the center.
5. You are mathematically correct in your equations for converting X,Y coordinates to Theta, Rho - but it may be more useful to stick with using only X and Y values in these. So instead of using Theta = arcCos(X / Rho),  you can use Theta = arcTan(X / Y).
6. The "tricky part" you refer to stems with the fact the polar systems have a "seam" - where 360 degrees is the same place on the sand as 0 degrees (or 2*Pi radians = 0 radians). Although Sisyphus's circular sand field is a finite physical area, it is not finite mathematically in the theta axis. So even though Theta = 0, or 2*Pi, or 4*Pi put the ball on the same rotation around the field, moving between these Theta values is not the same thing as finishing at these positions. That is why the erase track - which traces a spiral with 100 rotations from inside to outside, can be defined by a simple two-point track: 0,0 and 0, 628.319 (which is 200*Pi). When writing programs to create tracks with unbounded Theta, if using XY tools to do so, the key is careful "record keeping" whenever the XY path being converted crosses over 0/2*Pi seam.
7. Normalizing (unitizing) the Rho range of a track: The rationale for confining Rho values between 0 and 1is to universalize tracks for all sizes of Sisyphus. So regardless of how large or small your Sisyphus is, it will still be able to play any track (though visible detail or smoothness of curves may suffer, depending on the track). It is not required that a track completely fill the area of the sand field by making the most of the Rho span - you can create tracks that do not. But most of the available tools automatically scale a track to do this (by looking at the largest Rho value after converting XY values to polar, and then dividing all Rho's by this value).
8. You can put comments at the head or in the body of *.thr files by starting the line with a '#' character.

Again - thank you for sharing your findings with others. I'm certain there are other ways of approaching Sisyphus track creation programming, and look forward to questions, comments, and further discussion.

Posted by: crsolomon

I developed a short guide for people who want to understand how the Sisyphus table interprets code so they can write their own images.   This came from a lot of trial and error as well as scraps gleaned from the reddit site.  Hopefully it will help would be programmers not make the same mistakes as well as realize how the table sees the world (which is NOT conventional polar as taught in school) 

sisyphus-table-programming-logic.docx

Thanks for the info...

I have also found that the best way to convert xy to polar is by determining the offset angle between point 1, and point 2, and then adding (or subtracting that angle to the current theta angle (of point 1)  This is good because it does not matter "where" the points are, and theta can be anything to start.

(so if you start with a erase track that ends at theta 450, the code will continue from there at 450ish)

Programatically it goes like this    

(btw concept taken from sisbot code models.js    "angleBetween")

Where X1Y1 is point 1  

ANG0=current Theta to point 1

X2Y2 is point 2 (next point) 

NEWTHETA = Theta to point 2

P = X1*X2 + Y1*Y2                                                        (Vector math stuff)
Rho = Sqrt((X1^2+Y1^2) * (X2^2+Y2^2))             (Vector math stuff)
If X1*Y2-Y1*X2 < 0 then SIGN=-1 else SIGN=1     (This determines direction)
ANGL = SIGN*Acos(P/Rho)                                      (Trig function to calc angle)
NEWTHETA = ANG0-ANGL                                     (Offset Theta by ANGL )

You then use

NEWTHETA and point 2 xy to calculate "next" point

I also use: if Rho>1 then Rho = 1.0 to prevent chatter

Hope this helps

 ddkEngr

1) I agree about the theta can be any value - I was trying to make the point that start and end rho had to be the opposite of the starting value.   I'll change that and since I make a point of always erasing the board when I start a pattern (to get a clean pattern , theta for me always is zero.   

2) I do realize that in essence there is only One type of command - just data pairs where the ball moves from one to the other.   But anyone programming  the table needs to be aware of the "jump" that occurs (and was illustrated in the document)  if you make the distance between points too great.  In essence you have a regular move and a large spiral move.   That was my point - to warn others that you have to be careful of the distance between your data points.

3)  The main part about Cartesian to Polar is that you have to keep up with which quadrant the x,y points are located in or the arcCos or arcTan function will give you the incorrect sign.  That is why I figure the quadrant first and then normalize the angle to positive value.   It insures that the sign is correct AND it allows me to get around the dreaded 2PI barrier because I know I can add or subtract 2 PI and make the angles "fit" so there is no jump.

As was suggested in another post - I have used the differential method to "build" a running theta from adding the differences between angles - but I had problems occasionally with that method producing a "jump".   It just shows there are different ways to do the calculation and make a smooth .thr file.

Anyway - My source code is in the text generator program and it works for anyone who is interested.  

I have updated the Guide and incorporated the comments (which I thank the others for giving) as well as added more illustrations and clarifications for beginning programmers.   I hope this helps others get past the bump of understanding the table behavior to produce more patterns.

Looks great, and is a nice resource for path creators.