Editing The Eggbot coordinate system

== Introduction ==

'''Note:''' This discussion applies to version 2.1 and later of the Eggbot Control extension.  For earlier versions of the Eggbot Control extension, see [[Where will my drawing begin on my egg? (v20)]].  To check which version of the Eggbot Control extension you have installed, select the '''*''' tab within the Eggbot Control extension.


* How does the Eggbot frame my drawing on my egg?
* Where does the Eggbot start drawing on my egg?
* Where is the coordinate (0,&nbsp;0) on my egg?

These are natural questions to ask. However, the answers may be somewhat unsatisfying if you do not first understand the nature of the Eggbot's drawing motors.  After reading this discussion, not only should you understand the answers to the above questions, but you should also develop an understanding of

* The conventions adopted for mapping your Inkscape drawings to the surface of your egg.
* The intrinsically relative nature of the drawing motors.
* And, how other mechanical aspects of the Eggbot impinge on drawing.

With that said, let's get down to business and discuss these "drawing" motors.

== The drawing motors ==

The Eggbot has mounted to its chassis two identical "drawing" motors.  One motor rotates the egg while the other moves the pen arm along an arc.  Either motor can rotate either clockwise or counter-clockwise.  As the two motors are mounted with their shafts at 90 degrees to one another, the pen arm arc is at a right angle to the egg's direction of rotation.  These two motors are of a type known as "stepper" motors.  There's also a third, smaller motor which is mounted to the pen arm.  We are not concerned with that motor in this discussion.

The first thing to understand about the two stepper motors is that they can be turned clockwise or counterclockwise in very precise, small steps.  Hence the name, "stepper" motor.  These steps are so small, that it takes 3200 steps total to turn either of the motor's shafts a complete turn (360 degrees) [1].  Consequently, turning either motor a total of 3200 steps in the same direction brings the motor shaft around to where it started.  It follows that if you advance either motor N&nbsp;+&nbsp;3200 steps, then that is the same as advancing it only N steps.

Now for a mechanical "gotcha".  Can you rotate a loaded egg a full circle?  Yes, you can.  Can you rotate that pen arm a full circle?  No, you cannot: the pen arm hits the head or tailstocks of the chassis.  So, while the pen arm's motor shaft can itself turn a full 360 degrees, the combination of the pen arm and chassis severely limits this range of motion.  So much so that the pen arm can only move about 56 degrees either side of vertical.  That makes for a total range of around 112 degrees or (conveniently) about 1000 motor steps.

So, let us recap what we know so far:

* A stepper motor rotates the egg clockwise or counter clockwise
* The egg can be rotated in either direction up to 3200 steps before comimg full circle back to where it started
* A stepper motor moves the pen arm back and forth
* The pen arm can be moved about 1000 steps of total travel

== The Inkscape drawing template ==

Armed with what we know so far, we can begin to adopt some conventions in mapping an Inkscape drawing to an Eggbot plot.  Inkscape uses a two-dimensional Cartesian coordinate system.  We can think of an Inkscape drawing in terms of (x,&nbsp;y) coordinates with the x-axis running horizontally across our computer screen and the y-axis running vertically.  Increasing x values run from left to right; increasing  y values run from top to bottom [2]. The units of measure in a drawing are somewhat arbitrary and in many cases only matter so far as rescaling the drawing to appear on specific output devices (e.g., a computer screen, a printer, or an Eggbot).  In theory, the Eggbot could determine each plot's bounding box and then scale the drawing to fit on an egg.  However, that's not very satisfactory and would require user controls to limit how much of the egg to draw on.  Rather than go that route, the Eggbot instead assumes that your Inkscape drawing is scaled one-to-one to your egg.  This does not mean that what you see on your screen will be the same size as what you see on your egg.  After all, Inkscape is rescaling your drawing when it draws it on your display.  What this means is that we've adopted the convention that each unit of length in your drawing corresponds to one stepper motor step.

With this 1:1 scaling convention, we identify Inkscape's x-axis with egg rotation and y-axis with pen arm travel.  We typically use an Inkscape drawing template with a width of 3200 pixels and a height of 800 pixels [3].  The width of our template then corresponds to the complete circumference of an egg, and the height to the approximate maximum range of pen travel. [3]  Horizontal lines in our Inkscape drawings will travel around the egg's axis of rotation, while vertical lines will travel towards or away from the head and tailstocks (e.g., from or towards the egg's poles).  For example, consider a horizonal line of length 1600 units in Inkscape.  When we plot this line on the Eggbot, the pen arm will not move at all.  It won't move because for a horizontal line, the y-coordinate is constant (unchanging).  When plotted, all that will happen is that the pen will be lowered and the egg rotated 1600 steps which corresponds to a half revolution (180 degrees).  Note that in the above description, it was stated that the pen arm doesn't move at all.  It doesn't even need to move to the starting point for the line.  Odd?  Interesting?  More on this after we first explain a very important detail about the Eggbot's stepper motors.

== The relative motion of stepper motors ==

Stepper motors such as those in your Eggbot do just one thing: rotate their shafts in discrete steps.  These stepper motors do not have fixed reference positions.  It's not possible to tell the motors to go to some specific angle of rotation or some distinguished location.  All you can do is tell the motors to turn a step in one direction or another.  Moreover, it's not possible to "read" from the stepper motors their configuration.  (Expensive, industrial stepper motors have built in encoders which allow this.)  As a result, these stepper motors can only be controlled using "relative" coordinates; i.e., moved N steps forwards or backwards from their ''present'' position.  They cannot be moved N steps forward or backwards from some fixed position since no fixed or distinguished positions exist.

A direct consequence of this relative nature of stepper motors is that the Eggbot has no idea what position the egg or pen arm is in when it begins a plot.  Let's repeat that: the Eggbot has no idea where the pen or egg is when it begins a plot.  At best, the Eggbot can track the cumulative number of forward (positive) and backwards (negative) steps each motor has taken since starting a plot [4].  Knowledge of the cumulative number of steps allows the Eggbot to return the pen to any previous position in the current plot, but that's all.  The "Return to home" option is implemented this way: after finishing a plot, each stepper motor is stepped the opposite number of net steps that that motor took while drawing the plot.  The final net travel for each motor then becomes zero steps.

Another direct consequence of this relativity is that there is little if any utility to having absolute Eggbot coordinates.  What's the use of an absolute position (0,&nbsp;0) in Eggbot plotting space when the Eggbot has no idea what asbolute position either stepper motor is in?  Nonetheless, it sure would be nice to know where your drawing will land on your egg....

== Where does my drawing start? ==

Enter the "Start with pen centered" option of the Eggbot Control extension's "Options" tab.  What this option says, when checked, is that the pen is '''assumed''' to be at the (x,&nbsp;y) point (W/2,&nbsp;H/2) in your drawing -- the drawing's geometric center.  Here, W is your drawing's width and H is your drawing's height.  For a drawing with dimensions 3200&nbsp;&times;&nbsp;800, this corresponds to the point (1600,&nbsp;800).

If you do not check the "Start with pen centered" option, then the Eggbot assumes that the pen is located at the starting point of the first line segment in your drawing.  For all but the simplest drawings, it's anyone's guess which part of your drawing this will correspond to: Inkscape chooses how to order pieces of your drawing.  As such, operating without the "Start with pen centered" option is something of a gamble.

So, how does the Eggbot frame your drawing?  It really doesn't frame it at all.  Instead, if you use the "Start with pen centered" option, then it assumes that the pen is positioned center of the drawing page -- the drawing and not your egg.  If you want the drawing's horizontal midline to correspond to the egg's equator then position the pen over the egg's equator.

Where does the Eggbot begin drawing on your egg?  Well, if the first line in your drawing starts at coordinate (x&#8320;,&nbsp;y&#8320;) ''and'' you use the "Start with pen centered" option, then the Eggbot will assume that the pen is pointed at the point (W/2,&nbsp;H/2) and it will move the pen arm y&#8320;&nbsp;&minus;&nbsp;H/2 steps before starting to draw.  If y&#8320;&nbsp;>&nbsp;H/2 this means moving the pen arm towards the tailstock (positive number of steps).  If y&#8320;&nbsp;<&nbsp;H/2, this means moving the pen arm towards the headstock (negative number of steps).  And if y&#8320;&nbsp;=&nbsp;H/2 then the pen arm need not move at all to reach the first point. 


::Remember that in an Inkscape document, the line y&nbsp;=&nbsp;0 runs along the top of the document and not the bottom; y-values increase as you move from the top of the page torwards the page's bottom. The point (0,&nbsp;0) is in the upper left corner of your drawing [2].


Where is (0,&nbsp;0) on your egg?  Turns out it really doesn't matter. But if you must know, when you start the plot with "Start with pen centered", the point (0,&nbsp;0) will be H/2 pen arm steps "up" towards the headstock and W/2 egg rotation steps to the right or clockwise if looking from the tailstock end towards the headstock.

And, now that you understand that the Eggbot uses relative coordinates, what about the Inkscape drawing template?  Does it need to be 3200 by 800 units?  Not really.   Nor is it too important what the coordinates of its corners are.  About all that really matters about the drawing template is whether or not you use the "Start with pen centered" option.  If you use that option, then you want to know where the geometric center is in your drawing.  That's because the Eggbot will assume that the pen starts there.

== See for yourself ==

Over at Thingiverse there is a coordinate demonstration plot which illustrates much of what has been discussed here,

:[http://www.thingiverse.com/thing:5250 http://www.thingiverse.com/thing:5250]

Download a copy of the SVG file for that plot and try plotting it on a light bulb or an egg.  If you use the "Start with pen centered" option, then where the pen is when you begin the plot is where the line y&nbsp;=&nbsp;400 from the drawing will be started.  This is because the drawing uses a height of 800&nbsp;pixels and thus the line y&nbsp;=&nbsp;400 is the page's horizontal midline.

http://mtbaldy.us/~dnewman/tspart/coordinate-demo-21.png

== Notes ==

[1] Technically, these stepper motors have only 200 distinct steps per revolution.  However, fractional "microsteps" in increments of one-half, one-quarter,  one-eighth, and one-sixteenth can be generated with repeatable accuracy.   By having the EiBotBoard produce one-sixteenth steps, the Eggbot software sees the stepper motors as having 16&nbsp;&times;&nbsp;200 steps.   (In the 2009 EggBot Beta "clear-chassis" kit, each motor had 400 steps per revolution, and EBB v 1.1 had step increments only down to one-eighth, giving the same final resolution.)<br/>
[2] Inkscape will show on the left side of the screen a y-axis ruler whose zero point starts at the bottom of the page.  This is odd and annoying as that is not how SVG works and is not consistent with the underlying SVG which Inkscape produces.  Questions about this behavior and requests for an option to control are common on the Inkscape forums.<br/>
[3] A template size of 3200&nbsp;&times;&nbsp;800 is a good first choice.  Depending upon the size, shape, and mounting position of your "egg", you may be able to use height larger than 800&nbsp;pixels or may have to use a smaller size.  See [[Framing and Pen Centering]] for a more detailed discussion of this topic.<br/>
[4] Between plots, the program doing the plotting exits and this knowledge is lost.  When a plot begins anew, the Eggbot doesn't know what happened the last time it plotted.  The only exception to this is when you pause a plot with the PRG button on the EiBotBoard.  In that case, the Eggbot saves some data in your drawing file.  The plot can be resumed from where it left off assuming that you don't turn the egg or move the pen. (Or if you do that you can then manually restore the egg and pen to the position at which the plot was paused.)<br/>