These are the instructions for my script-based spacetime diagram generator. Using a script-based system provides for a lot more options than could be easily accommodated with a graphical user interface (GUI). On the other hand, it requires reading instructions (sigh), which no one likes to do. I have made the instructions as simple and brief as possible. In addition to the quick reference, I also have some examples.
I welcome suggestions and problem reports.
Once you've generated a diagram, you can zoom in or out of with the mouse wheel or with Ctrl++ and Ctrl+-. You can also drag the diagram using the left mouse button.
A script conists of a series of commands, each one starting with a keyword and ending with a semicolon. Following the keyword are a set of attributes, each attribute being formed from an attribute name, followed by a colon and a value. That's the entire structure in a nutshell.
The following table lists all the command keywords with a short description of what each does and a list of the attributes it supports. Each attribute links to an explanation of the attribute.
| Keyword | Function | Attributes |
|---|---|---|
| Diagram | Sets up the diagram. This is the only setup command—all the rest are drawing commands. This command is always executed before any of the others; if you include it more than once, the last one wins. If you omit it, a default Diagram command is automatically used. | <setup> |
| Axes | Draws axes for any inertial frame. | origin, velocity, ticks, positiveOnly, <linestyle>, <xt> |
| IMFAxes | Draws the Instantaneous Moving Frame (IMF) axes at a specific time for an accelerating object. | origin, time, g, velocity, ticks, positiveOnly, velocity, <linestyle>, <xt>, <spacing> |
| Grid | Draws a grid for any inertial frame. | origin, velocity, <linestyle>, <spacing>, <xt> |
| Event | Draws an event. | origin, color |
| Worldline | Draws the worldline for an object moving at a constant speed. | origin, velocity, <linestyle>, <clip> |
| AccWorldline | Draws the worldline for an object moving at a constant acceleration. | origin, g, velocity, <linestyle>, <clip> |
| LightWorldline | Draws the worldline of light. | origin, positiveOnly, <linestyle> |
| LengthLine | Draws a line of a given length centered through a point. The angle of the line is derived from the velocity. | origin, length, velocity, <linestyle> |
| Line | Draws a line from one coordinate to another. | origin, endpoints, <linestyle> |
| AngledLine | Draws a line at a given angle through a given coordinate. | origin, angle, <linestyle>, <clip> |
| Name | Type | Default | Min | Max | Function |
|---|---|---|---|---|---|
| origin | vPoint | (0, 0) | The origin of the object being drawn. This is relative to the diagram origin. | ||
| time | float | 0 | A time which defines the Instantaneous Moving Frame of an accelerated object. | ||
| g | float | 0 | A constant acceleration. The formula used requires that units are in light years (x) and years (t). | ||
| velocity | float | 0 | -0.99999 | 0.99999 | In spacetime diagrams, a constant velocity implies an angle. |
| angle | float | 0 | -90 | 90 | An angle, in degrees, given when you can't (or don't want to) specify the angle as a velocity. |
| length | float | 0 | 0 | The length of a line in the rest frame. | |
| endpoints | endpoints | (0, 0) (1, 1) | The endpoints of a line segment given as two vPoints. | ||
| ticks | boolean | true | Show tick marks on axes. |
| Name | Type | Default | Min | Max | Function |
|---|---|---|---|---|---|
| width | integer | auto-resize | 1 | Sets the size of the display area, If both width and height are omitted, the display area is always resized to the maximum visible size. If one or the other is omitted, it is set to the maximum visible size, but is not resized after that. | |
| height | integer | auto-resize | 1 | Sets the size of the display area, If both width and height are omitted, the display area is always resized to the maximum visible size. If one or the other is omitted, it is set to the maximum visible size, but is not resized after that. | |
| origin | point | (50, 50) | The diagram origin is a percentage, from 0 to 100. Zero means left or bottom. 100 means right or top. Numbers in between shift the origin position accordingly. If the diagram is auto-resized, the origin does not change. Dragging with the mouse will change the origin. Zooming in or out may change the origin. | ||
| scale | float | 1 | 0.001 | 1000 | Unscaled coordinates (i.e. pixels) are scaled by this factor to produce scaled coordinates. The scale is defined by taking the lesser of the diagram width or height . A scale of 1 means that this distance is exactly 100 units, a scale of 2 would be 50 units and so on. |
| clip | clip | (-50, -50) (50, 50) | Since many of the objects we are drawing are infinite in length, the clip limits the amount drawn. |
| Name | Type | Default | Min | Max | Function |
|---|---|---|---|---|---|
| color | color | varies, usually 0 (black) | A color is specified as #XXXXXX (where XXXXXX is a hexadecimal number) or rgb(int, int, int). | ||
| thickness | float | 2 | 1 | 20 | The line thickness. |
| dashed | boolean | false | Draw a dashed line. |
| Name | Type | Default | Min | Max | Function |
|---|---|---|---|---|---|
| x | boolean | true | Draw the x axis. | ||
| t | boolean | true | Draw the t axis. |
| Name | Type | Default | Min | Max | Function |
|---|---|---|---|---|---|
| from | float | -99999 | This limits the drawing of the object to start no earlier than time 'from', where time is measured from the diagram origin | ||
| to | float | 99999 | This limits the drawing of the object to end at time 'to', where time is measured from the diagram origin. | ||
| clip | vClip | If given, this overrides from/to. The diagram is limited by the four bounding limits of the clip. The coordinates are relative to the rest frame. |
| Type | Definition |
|---|---|
| point | A point consists of two floating point numbers enclosed in parantheses and separated by commas. |
| vPoint |
vPoint coordinates can take a variety of forms, all of which eventually resolve to an (x, t) coordinate in the rest frame. The simplest form is (float, float), representing the x and t coordinates. The second form is (float, float, float). The first two numbers represent x' and t' in a moving frame whose velocity is specified by the third number. An inverse Lorentz transform converts these coordinates to x and t in the rest frame. The final form is (float, float, float, float, float). The first three numbers are are treated as above. The fourth and fifth numbers are offsets added to the calculated x and t coordinates. We're not quite done. Each of the first two numbers can be replaced by an expression in the form [float, float, float]. In this case, the first two numbers are coordinates x and t in the rest frame. The third number is the velocity of a moving frame. The (x, t) coordinates are transformed to (x', t') using the given velocity. If this expression substitutes for the first number, only the calculated x' coordinate is used; if for the second number, only the t coordinate is used. A value such as ([a, b, v], [a b, v], v) is a slow way to write (a, b). |
| endpoints | A pair of vPoint coordinates. |
| clip | A pair of point coordinates. |
| vClip | A pair of vPoint coordinates. |
| color |
Colors can be specified in three ways. The first is #RGB, where each of R (red), G (green), and B blue is a hexidecimal character. This first form is converted to the second form, #RRGGBB, by repeating each digit (e.g. #382 becomes #338822). The value of each pair of digits (from 00 to FF, or equivalently, from 0 to 255 in decimal) represents the amount of red, green, or blue to mix to create the desired color. The final form is rgb(integer, integer, integer). Using this form, you can specify the red, green, or blue values, respectively, using decimal integers ranging from 0 to 255. |
This is a very simple example that shows the axes for a rest and moving frame. The moving frame has a velocity of 10% c. The grid for the moving frame is also shown.
Note that objects are drawn in the order in which they appear in the script. The grid is "behind" the rest axes, which are behind the moving axes.
// Add Grids
Diagram width: 400, height: 400, origin: (10, 10), scale: 5;
Grid velocity: .1, color: #CCF;
Axes ;
Axes velocity: .1, color: #44C;
This diagram shows a single event and then maps the event to the rest and moving axes. The velocity in this case is 80% c.
The example takes advantage of the more advanced forms of coordinates to correctly draw the lines for the moving frame. [20, 20, .8] converts rest coordinate (20, 20) into the equivalent x or t coordinates for the moving frame. (0, [20, 20, .8], .8), for example, become (0, 6.666667, .8). The coordinate (0, 6.666667) is the inverse mapped back to the rest frame.
// Map an event to two different frames
Diagram height: 400, width: 400, origin: (10, 10), scale: 2;
// Map an event to different axes
Axes ;
Axes velocity: .8 color: #008800;
// Lines to rest axes
Line endpoints: (0, 20) (20, 20), dashed: true, color: #CCCCCC;
Line endpoints: (20, 0) (20, 20), dashed: true, color: #CCCCCC;
// Lines to moving axes
Line endpoints: (0, [20, 20, .8], .8) (20, 20), dashed: true, color: #88FF88;
Line endpoints: ([20, 20, .8], 0, .8) (20, 20), dashed: true, color: #88FF88;
// The event
Event origin: (20, 20) color: #CC0000;
This diagram is a geometrical representation of length contractions. It highlights that length contraction is actually a "foreshortening" of length in the time axis. The front of the length (measured at a specific moment in the rest frame) is from an earlier time than the rear.
The light blue lines represent the worldlines of each end of the length. The moving frame's t axis is the worldline for the middle of the length. The length, which is exactly 1 unit long in its rest frame, is shown at two points along its time axis.
The dashed lines and the thick green line represent the length as seen in the rest frame.
// Show Length Contraction
Diagram height: 400, width: 400, origin: (25, 25), scale: 25;
// Show the worldlines for the ends of the length
Worldline velocity: .8, origin: (-.5, 0, .8) color: #CCF;
Worldline velocity: .8, origin: (+.5, 0, .8) color: #CCF;
// Highlight the positions of the ends of the length, as seen by the
// rest frame
AngledLine angle: 90, origin: (0, .6, .8, -.3, 0) dashed: true, color: #CCC;
AngledLine angle: 90, origin: (0, .6, .8, +.3, 0) dashed: true, color: #CCC;
// Rest and moving axes
Axes ;
Axes velocity: .8, color: #008;
// Draw a line at rest time t = 1. which is where we will measure the
// length
AngledLine angle: 0, origin: (0, 1), color: #C00;
// This length we will measure is 1 unit long in its rest frame
// Draw the length so that the front of the length is at rest time t = 1
Line endpoints: (-1, .6, .8, +.3, 0) (0, .6, .8, +.3, 0) color: #840, thickness: 5;
// Draw the length so that the rear of the length is at rest time t = 1
Line endpoints: ( 0, .6, .8, -.3, 0) (1, .6, .8, -.3, 0) color: #840, thickness: 5;
// Draw the length seen in the rest frame
Line endpoints: (0, .6, .8, +.3, 0) ( 0, .6, .8, -.3, 0), color: #080, thickness: 5;
This is a variant of the famous twin paradox. A ship traveling at 80% c passes Earth heading for a point 4 light years distant. The Earth and ship clocks are synchronized to 0 as the ship passes. When the ship reaches its destination, it passes its clock time to another ship traveling toward Earth also at 80% c. When this ship reaches Earth, its clock says 6 years have passed; the Earth clock says 10 years have passed.
The diagram shows the axes for both ships. The blue worldline traces the outward and inward legs. Lines of simultaneity are shown for Earth (green) and the ships (red). Both the Earth and the ships see each other's clocks running slower, yet less time passes for the blue worldline.
// Twin Paradox
Diagram height: 400, width: 400, scale: 8.5, origin: (10, 10);
// Draw the base grid and axes
Grid ;
Axes ;
// Draw the axes for the two ships
Axes velocity: .8, color: #FF00FF, positiveOnly: true;
Axes velocity: -.8, color: #FF00FF, origin: (8, 0), positiveOnly: true;
// Draw the lines of simultaneity from S' to S
Line endpoints: (0, 1, .8) (-0.8, 1, .8), dashed: true, color: #CC0000;
Line endpoints: (0, 2, .8) (-1.6, 2, .8), dashed: true, color: #CC0000;
Line endpoints: (0, 3, .8) (-2.4, 3, .8), dashed: true, color: #CC0000;
Line endpoints: (0, 3, -.8, 8, 0) (-2.4, 3, -.8, 8, 0), dashed: true, color: #CC0000;
Line endpoints: (0, 4, -.8, 8, 0) (-1.6, 4, -.8, 8, 0), dashed: true, color: #CC0000;
Line endpoints: (0, 5, -.8, 8, 0) (-0.8, 5, -.8, 8, 0), dashed: true, color: #CC0000;
// Draw the lines of simultaneity from S to S'
Line endpoints: (0, 1) ([ .8, 1, .8], [ .8, 1, .8], .8), dashed: true, color: #00AA00;
Line endpoints: (0, 2) ([1.6, 2, .8], [1.6, 2, .8], .8), dashed: true, color: #00AA00;
Line endpoints: (0, 3) ([2.4, 3, .8], [2.4, 3, .8], .8), dashed: true, color: #00AA00;
Line endpoints: (0, 4) ([3.2, 4, .8], [3.2, 4, .8], .8), dashed: true, color: #00AA00;
Line endpoints: (0, 5) ([4.0, 5, .8], [4.0, 5, .8], .8), dashed: true, color: #00AA00;
Line endpoints: (0, 6) ([-4.8, 6, -.8], [-4.8, 6, -.8], -.8, 8, 0), dashed: true, color: #00AA00;
Line endpoints: (0, 7) ([-5.6, 7, -.8], [-5.6, 7, -.8], -.8, 8, 0), dashed: true, color: #00AA00;
Line endpoints: (0, 8) ([-6.4, 8, -.8], [-6.4, 8, -.8], -.8, 8, 0), dashed: true, color: #00AA00;
Line endpoints: (0, 9) ([-7.2, 9, -.8], [-7.2, 9, -.8], -.8, 8, 0), dashed: true, color: #00AA00;
// Draw the worldline for the trip out (ship 1) and back (ship 2)
Worldline velocity: 0.8, from: 0, to: 5. thickness: 5;
Worldline velocity: -0.8, origin: (8, 0), from: 5, to: 10, thickness: 5;
This diagram shows an accelerated worldline. The units are light years (x) and years (t). The acceleration is .01 Earth gravities. The greenish axes show the Instantaneous Moving Frame (IMF) at rest time 20.
// An accelerated worldline with an Instantaneous Moving Frame (IMF)
Diagram height: 400, width: 400, origin: (10, 10), scale: 4;
// Draw the base grid and axes
Grid color: #EEE;
Axes ;
// Create an accelerated world line with an IMF at time 20
IMFAxes g: .01 origin: (10, 0), time: 20, thickness: 1, color: #0BB;
AccWorldline g: .01, origin: (10, 0), from: 0 thickness: 3, color: #C00;