Minkowski Spacetime Diagrams Instructions

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.

Controls

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.

Scripts

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.

Commands

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>

Attributes

Miscellaneous Attributes

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.

The <setup> group

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.

The <linestyle> group

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.

The <xt> group

Name Type Default Min Max Function
x boolean true Draw the x axis.
t boolean true Draw the t axis.

The <clip> group

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.

The <spacing> group

Name Type Default Min Max Function
spacing float 1 0.00001 The spacing between tick marks or grid lines.
majorEvery integer 10 2 1000 Highlight every so many tick marks or grid lines.
positiveOnly boolean false Draw only from the origin forward in time.

Values

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.

Examples

Example 1: Grids

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;
      

Example 2: Event Mapping

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;
      

Example 3

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;
      

Example 4

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;
      

Example 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;