The Celx Programming Language
for Astronomical Simulation with Celestia
by Mark Meretzky

Cover illustration or frontispiece: A Philosopher Lecturing on the Orrery (1766) by Joseph Wright at the Derby Museums.

About This Document

This document is an HTML5 file with CANVAS tags for the diagrams. JavaScript is used for the diagrams, tables of contents, cross references, and index. If the Chrome browser fails to render a diagram, display and hide the JavaScript Console and the diagram will appear. If Firefox says “Unresponsive script”, press the Continue button.

Each diagram is pixels wide. Each Celx code sample is at most 80 characters wide, with eight-character tabs. One excerpt from celestia.cfg in opengl is 94 characters wide; a line in Celestia:newposition is 84 characters wide. The above Wright painting is a 800 × 600 jpg. The Celestia screenshot in screenShot is a 1024 × 790 png. © 2013 Mark Meretzky. All rights reserved.

Links to the Lua documentation go to Lua version 5.2, even though the current Celestia uses Lua 5.1. Links to the Celx source code are provided by the gateway at http://markmeretzky.com/cgi-bin/celx.cgi. Links to astronomical and mathematical topics go to Wikipedia. The HTML5 has been validated by http://validator.w3.org/ and (with the CANVAS tags stripped out) by tidy.

Introduction

Celestia Celestia is a computer application that displays a real-time, three-dimensional simulation of the Universe with photorealistic OpenGL graphics. When a full moon hangs over Manhattan, Celestia will render the Sun, the Moon, and New York in their actual positions and orientations. The universe can be displayed at any time and at any speed, forward, backward, or frozen. The user’s viewpoint can be fixed on the surface of a planet, mounted on a spacecraft, or piloted through the empty reaches of space. The viewpoint’s motion can be linear or curved, accelerated or constant, and accompanied by yaw, pitch, and roll.

Celestia thus combines the functionality of a camera, telescope, compass, GPS, orrery, planetarium, and starship, not to mention one of those little plastic disks with a grommet that shows you tonight’s constellations. The historically minded user can also simulate a sundial, sextant, astrolabe, armillary sphere, or a plain old noon mark.

Most people explore the Celestia universe by clicking and dragging a mouse, or, nowadays, by tapping and swiping a finger. It’s easy to go close enough to Jupiter to see the satellites, or to Saturn to see the rings. But for precise, reproducible results, far beyond those accessible to the casual user, Celestia can also be driven by a program or script.

A script can move the viewpoint to an exact position in space and time, with a precise velocity, acceleration, and orientation. We can go to Mongolia to watch a solar eclipse, or hire a jet to follow the path of totality. We can fly to the Moon with Ranger 7Ranger 7 (spacecraft)—or with George MélièsMéliès, George—and up from the Moon with Stanley KubrickKubrick, Stanley. We can observe the phases of Venus as seen from the Earth, or the phases of the Earth as seen from Mars. We can cruise alongside the Earth, keeping it stationary while the planets loop around it, or cruise alongside the CassiniCassini (spacecraft) spacecraft as HuygensHuygens (spacecraft) separates from it. And we can hold the camera steady enough to see the parallax of the star 61 Cygni.

A script can calculate an exact point in space—or in time. When is the sunset at a given date, at a given latitude and longitude on Earth? Or on the Moon, or on Mars? When are Easter and Passover, Eid al-Adha and Chinese New Year? When will Saturn’s rings be edge-on as seen from Earth? Or the orbital plane of Charon around Pluto? When will Mercury be at its next greatest elongation, and where will it appear against the background of the constellations? What will be its right ascension and declination, altitude and azimuth, and distance from the Earth? And does its perihelion really precess around the Sun as EinsteinEinstein, Albert predicted?

A script can overlay the Celestia window with OpenGL graphics. We can draw the lines on the face of a sundial, plot the equation of time, or construct the figure eight of the analemma—for any planet. We can draw on the surface of the celestial sphere, tracing the retrograde motion of Mars or the epicycles of the Ptolemaic solar system. We can draw on the surface of a planet, marking the path of an eclipse or an occultation. We can draw on the surface of the window, showing the orbital resonances of Jupiter’s moons with a corkscrew diagram. And we can draw in three-dimensional space, highlighting the Lagrangian points and equipotentials of a two-body system or building a wireframe model of Kepler’s Law of Equal Areas.

A script can search Celestia’s databases of stars and galaxies. We can plot the stars along the Main Sequence of the Hertzsprung-Russell diagram. We can see if the globular clusters are symmetrically distributed around the center of the Milky Way. We can check if the galaxies are really thicker along the supergalactic plane or thinner along the Zone of Avoidance. And we can list all the stars whose names contain the Arabic word for “tail”.

But all of these wonders are going to require programming. Celestia understands two programming languages, Cel Cel (programming language) and CelxCelx (programming language). The former is hardly a language at all, having no variables or control structure—loops, “if” statements, and functions. Celx, on the other hand, inherits these useful features from the language LuaLua (programming language), of which it is a superset. (Incidentally, the name Lua means “Moon” in Portuguese.) Celx also has classes of objects specifically for mathematics and astronomy, allowing us to harness the full power of Celestia’s simulation of the Universe with only a modest amount of coding.

The present book is a tutorial, cookbook, and reference for writing programs in the language Celx to drive Celestia. It covers the five groups of tasks that a program can do.

First, we can harvest information in numerical or graphical form from Celestia’s simulation of the universe. For example, we can ask when and where an eclipse will be total, how fast a planet will orbit the Sun, or from what angle a meteoroid stream will approach the Earth. Second, we can use this information to place the viewpoint into the simulation at a precisely computed time, place, velocity, and orientation. We can go to that eclipse and travel with it as it sweeps across the face of the Earth, or aim the camera at the radiant point of the meteor shower. Third, we can change the way the simulation is presented to the user. The window can be one large view or a splitscreen; the view can be telescopic or wide field; and the timescale can be fast forward or slow motion. The program can also overlay the window with graphics keyed to the simulated universe in the window. Fourth, we can interact with the real world. The program can read and write files, and react to keystrokes, mouse moves, or to the mere passage of real time. Finally, we can attach a Celx program to a spacecraft or planet in the simulation to pilot it on a new course. The resulting trajectory is called a “scripted orbit” or “scripted rotation”.

This book places Celx scripting squarely in the Unix tradition of making a program coöperate with its neighbors. A script is first of all a text file that can be generated by another program. The script can be launched from a command line in a shellscript or other script. It can communicate with other programs via pipes or other standard i/o, and can return an exit status to its parent. Our intent is to help users make Celx and Celestia part of a larger system involving, for example, Google Maps, a GPS or a telescope mounting, or a self-updating planetarium show. We also introduce a Standard Library for CelxCelx Standard Library, to take the rough edges off of Celx programming.

This book is addressed to the following people.

• The science educator and planetarium operator, seeking to demonstrate the motions and spatial relationships of the planets and moons, stars and galaxies.
• The student of celestial navigation or cartography, who wishes to simulate the view of the sky at any date, time, or place.
• The teacher of plane or spherical trigonometry, linear algebra, calculus, abstract algebra, or physics, in search of real-world applications for vectors and matrices, rotations and quaternions.
• The programmer, exploring the design of interfaces for navigating human beings through a three-dimensional space of objects.
• The graphic designer, animator, or filmmaker who needs to compose and fine-tune a dramatic still or video in a reproducible way.
• The stargazer who wishes to achieve independence from the standard almanacs, magazines, and websites by doing his or her own calculations of celestial events.
• The professional astrophysicist and historian.

How much math do you need for this book? If you remember your high school trigonometry—sine and cosine, arcsine and arccosine—you can read more than 90% of it. See trigonometryFun for the tutorial. How much programming? If you know about variables and assignment statements, loops and “if” statements, you can read more than 90% of it. See idiosyncrasies for the tutorial. How much astronomy and navigation? If you know the difference between latitude and longitude, horizon and zenith, you can read 100% of it. See sphericalAstronomy for the tutorial.

Reasoning in three dimensions takes practice. A desktop celestial sphere will aid the reader in visualizing the equinoxes, solstices, and the other cardinal directions in the many frames of reference offered by Celestia. If no sphere is available, get an orange and draw on it with a magic marker or stick pins into it. A conventional globe of the Earth will be helpful in seeing where the axes and other vectors pierce the terrestrial surface. The author always carries in his pocket a cheap little painted tin globe with a pencil sharpener in its base.

Celestia is free and runs on Macintosh macOS, Microsoft Windows, and Linux. It is open source and can be ported to any platform that has the languages C and C++ and the graphics library OpenGL. An enthusiastic user community has extended Celestia with additional planets and spacecraft (real and imagined), and surface imagery with new layers of information. But libraries of Celx functions and programs are coming more slowly, which is one of the reasons for this book.

The Celx viewpoint or camera is called the observerobserver (viewpoint), and is referred to herein as “he” only for convenience. I am grateful to the creators of Lua and Celestia, to Harald Schmidt Schmidt, Harald (documenter) for his pioneering Celx documentation, and to Marc Taylor Taylor, Marc (planetarium operator) for introducing me to the Celestia universe.

Versions and Conventions

This section lists the rules we obey, voluntarily or otherwise, when writing programs in Celx. You can skip it on first reading.

Language Versions

This book describes version 1.6.1 of Celestia, which implements a Celx language that is a superset of version 5.1.4 of LuaLua (programming language). Since the current version of Lua is already 5.2.2, we will be forced to write obsolete or deprecated code in a few places. See lua52 for the list of things to be changed in our Celx code when Celestia is upgraded to Lua 5.2.

For your version numbers of Lua, Celestia, and the Celx Standard Library, see the Lua variable _VERSION and the standard library variables std.celestiaVersion and std.libraryVersion.

The Celestia:geturlCelestia:geturl method of Celestia version 1.6.1 returns a cel:cel: URL URLURL (Uniform Resource Locator) containing a version number of 3. All earlier versions of Celestia generated a URL with no version number at all.

Source Directories

We will occasionally glance at the source code of Celestia and Lua. The Celestia source resides in a tree of directories whose root is named version. We will cite the files starting at this root. The Lua source is rooted at luaversion. The data files read by Celestia at runtime are in the Celx directory (celxDirectory) and its subdirectories: data, extras-standard, fonts, and textures.

The Celestia source code is mostly in the language C++C++ (programming language). The .m files are in Objective-CObjective-C (programming language) for Macintosh, and the .mm files are a mixture of Objective-C and C++. The Lua source code is in the language CC (programming language).

Naming Conventionsnaming conventions

Our convention in this book is to give lowercase names to Celx variables and functions. This includes variables that hold a constant value, in agreement with the Lua constant math.pi.

A name can be formed by concatenating two or more words. Celx already has three conflicting conventions for pasting them together.

1. Concatenation in all lowercase, as in the Lua functions tostring and tonumber, the Celx methods Celestia:getobserver and Celestia:newposition, and the field renderoverlay in the Lua hook table in luaHookFunctions. (A “method” is a certain type of function; see objectsAndClasses.)
2. Concatenation with underscores, as in the Celx variable KM_PER_MICROLY (lightyear) and the Celx functions celestia_cleanup_callback and celestia_keyboard_callback (callback).
3. Concatenation with embedded capitals, as in the field atmosphereHeight in the Celx info table (infoTable) and the field initialOrientation in the Observer:goto table.

Our convention in this book is to use concatenation in all lowercase for the names of methods; see objectsAndClasses. This agrees with the existing Celx convention for methods. We use concatenation with embedded capitals for the names of other functions and variables.

We place “longitude” before “latitude” in the names we invent, to agree with the Celx function Observer:gotolonglat. Examples include Celestia:newpositionlonglat and Vector:getlonglat.

What is the opposite of “end”? Celx uses both “start” and “begin”. For example, the Observer:goto table contains the fields startInterpolation and endInterpolation (animateRotation), while the table returned by a scripted orbit function contains the fields beginDate and endDate (Geostationary). Our convention is to use “start” because it has fewer syllables.

Some Celx methods return a Lua table, such as Celestia:tdbtoutc and Celestia:fromjulianday. Others return a list of values, such as Celestia:getscreendimension and Phase:timespan. Most of the methods we invent return tables; examples include Position:getlonglat, Vector:getlonglat, etc. Exceptions are Position:getxyz and Vector:getxyz, whose purpose is to return an argument list for the Lua function string.format, and std.tourl, which return the argument list for the method Celestia:newposition. Another exception is Object:family, which is required to return a list by the semantics of the Lua generic for statement. Finally, Rotation:getforwardup proved easier to use when it returned a list.

Celx Code Format

Every complete Celx program is printed in a solid box, adorned with a link to the source code online. A Celx code fragment is printed in a dashed box. Output is in a double box.

Note that “complete” is a relative term. If the program has the following require statement, --This is a Celx code fragment. require("std") the program will need the file std.luastd.lua (file) in order to run. This file contains the Celx Standard Library (standard) and is printed in full in stdCelx. Some programs will also need a Lua hook file (luaHookFunctions) or files containing scripted orbitsscripted orbit and/or rotationsscripted rotation (scriptedOrbit).

Our Celx code is written in the plain vanilla ASCII character set, with a maximum line length of 80 characters and 8-character tab stops. But these restrictions are not required by Celestia. We obey them only to make the code readable on every platform.

Despite being written in ASCII, many of our programs output non-ASCII characters. Examples include the symbols for degree, minute, and second (1° 2′ 3″). These “special” characters are encoded in the UTF-8UTF-8 (character encoding) format.

Play with Celestia

Let’s play with Celestia interactively before we start writing programs.

Download Celestia

Download Celestia from

The Macintosh macOS and Microsoft Windows versions install unproblematically. During the Windows installation, under “Select Additional Tasks”, check the checkbox for “Associate .cel and .celx scripts”. On Linux, download the Celestia package for your distribution. Do not download the “Linux (x86) Version 1.4.1” from the downloads page on the Celestia website—this version cannot run Celx programs.

At a much later stage, you might want to compile your own Celestia from its source code. See compileMacintosh for Macintosh macOS, compileWindows for Microsoft Windows, compileLinux for a Linux version of Unix, and solaris for the Solaris version.

Two Cel Programs that Come with Celestia

On startup, Celestia automatically runs an eight-second program named start.celstart.cel (Cel program). It whisks us safely away from the Sun and leaves us above the sunlit side of the Earth with the message “Welcome to Celestia!”. To immerse yourself in the Celestia universe, you can then maximize the Celestia window.

Another program is demo.celdemo.cel (Cel program), a four-minute tour of the Celestia universe. Pull down the Celestia menu on Mac, or the Help menu on Microsoft Windows, and select Run Demo. When done, it leaves us back at the Earth with the message “Demo completed.”

These programs are not hardwired into Celestia. They are specified in the configuration file celestia.cfgcelestia.cfg (configuration file):

To find the “Celx directory”Celx directory that holds the configuration file and the programs, see celxDirectory.

Keystroke and Mouse Commands

This section demonstrates some of Celestia’s interactive commandskeystroke commands. It previews the features that will be invoked non-interactively by the Celx programs later in the book. For the complete list of interactive commands, pull down Celestia’s Help menu and select Celestia Help on Mac, Controls on Microsoft Windows.

1. The Celestia point of view is called the observerobserver (viewpoint). When Celestia is launched, start.cel places him six Earth radii from the center of the Earth, facing the sunlit side of the planet. To rotate him around the Earth, you can then drag the mouse across the planet. On Mac, you right-drag or option-drag; on Microsoft Windows, you right-drag. You can also rotate him by holding down the shift key and pressing the four arrow keys. To roll the observer, press the left and right arrows without shifting. Visit Europe, Australia, and the North and South Poles.
2. A celestial object may be selectedselect (an object), causing its name to be displayed in the upper left corner of the window. The selected object is initially the Earth. To select a star, click on the star. To select the Earth again, click on the Earth. For the time being, let the Earth remain selected.
3. If the Earth somehow becomes unselected and goes out of the picture, there’s another way to get it selected again. Press return on Mac, Enter on Microsoft Windows, to get the prompt Target name:. Then type Earth and press return or Enter. The Earth is now selected. Press c to center the selected object in your field of view, and g to go there. Press HomeHome key and EndEnd key to go towards and away from the selected object. If your keyboard has no Home and End, you can drag up and down to get the same effect: command drag on Mac, left drag on Microsoft Windows.
4. Toggle the Earth’s features:
   
   i
   control-a
   control-l
   o clouds
   the rest of the atmosphere
   nightside lightslights (nightside) (lowercase L)
   the planets’ orbitsorbits (shown as lines) around the Sun (lowercase O)
   Note that the orbit of the selected planet is red. Go to the night side of the Earth and turn the ambient light level up and down with the curly braces } and {. Then go back to the default level of 0.10.
5. The astronomical name of the Sun is “Sol”Sol. Drag around the Earth to the subsolar pointsubsolar point—the point on the Earth where the Sun is directly overhead. Can you get the “Phase angle”phase angle in the upper left corner to go down to exactly zero? When you get as close as possible to zero, press ** (rear-view mirror command) (asterisk, the rear-view mirror command) to face the Sun. Press another * to face back to the Earth.
6. Was it hard to locate the subsolar point? Let’s mark it with a bright yellow vector (arrow). Right-click on the Earth and select Reference Vectors → Show Sun DirectionSun direction from the context menu.
7. Drag around the Earth to the antipode of the subsolar point, where the phase angle is 180°. Get as close to it as you can. The Sun will be hidden by the Earth.
8. Was it hard to locate the antipode? If so, display the yellow sun direction vector. Then change the Earth into an OpenGL wireframewireframe mode (OpenGL) by pressing control-w. You will now be able to see the vector through the Earth. Once you have located the antipode, turn the wireframe mode off with another control-w.
9. Press End and Home to withdraw from the Earth until it just barely covers the Sun. We have just traveled to the vertex (tip) of the Earth’s umbraumbra (of Earth). We can withdraw further to make an annular eclipseannular eclipse.
10. Get a better view of your eclipse with Celestia’s telescopic vision. First note the default FOV (field of view)field of view in the lower right corner. Press comma, (zoom in command) and period. (zoom out command) to zoom in and out. Then set the field of view back to the original value.
11. Go back to the Earth (select it and press g) just so we know where we are. Then look at the rest of the Universe and toggle the displays:
    
    /
    =
    control-b
    ;
      constellation constellations stick figures
    constellation names
    constellation boundaries
    “equatorial” grid equatorial grid showing right ascension and declination
    (celestial longitude and latitude)
    Make the stars brighter and dimmer with the square brackets ] and [. Then go back to the default magnitude magnitude, apparent of 7.0.
12. Turn on the equatorial grid and the constellation stick figures, and drag around the Earth until you are directly above the Earth’s South Pole. Observe that the Earth is now directly in front of the north celestial pole north celestial pole in Ursa MinorUrsa Minor, blocking our view of the North StarNorth Star, PolarisPolaris (star). Press End to get farther from the Earth so it blocks less of the sky.
13. Display the red, green, and blue “body axes” that come out of the Earth. Right-click on the Earth and select Reference Vectors → Show Body Axes. We will see in bodyfixedFrame that these are the axes of the Earth’s bodyfixed frame of referencebodyfixed frame of reference, but they are labelled with names that disagree with those used in a Celx program. The blue axis at the North Pole is is referred to in Celx as the bodyfixed Y axis, and the green one in the Indian Ocean is referred to in Celx as the bodyfixed negative Z axis.
14. Verify that the red bodyfixed X axis emerges from the Earth at latitude 0°, longitude 0° in the South Atlantic Ocean. Right-click on the Earth and select Reference Vectors → Show Planetographic Gridplanetographic grid. The green axis (the bodyfixed negative Z axis) emerges at latitude 0°, longitude 90° East in the Indian Ocean. Then turn off the body axes and planetographic grid.
15. Display the red, green, and blue “frame axes” that come out of the Earth, slightly duller than the body axes. Right-click and select Reference Vectors → Show Frame Axes. We will see in eclipticFrame that these are the axes of the Earth’s ecliptic frame of referenceecliptic frame of reference.
16. The start of spring in the northern hemisphere of the Earth is called the vernal equinoxvernal equinox, usually occurring around March 21. We also use the term to mean the direction from the Earth to the Sun at this point in time. This direction points towards the constellation PiscesPisces; in other words, the Sun blocks our view of Pisces on the first day of spring. Verify that the X axis of the Earth’s ecliptic frame (dull red) points towards the equinox. Turn on the constellation names, stick figures, and boundaries, and also the equatorial grid and wireframe mode.
17. The summer solstice summer solstice in the borderlands of Taurus Taurus and Gemini Gemini is the direction from the Earth to the Sun on the first day of summer in the Earth’s northern hemisphere. Once again, the labels that we see disagree with the names used in a Celx program. Verify that the dull green axis (which Celx would refer to as the negative Z axis of the Earth’s ecliptic frame) points towards the solstice. Verify that the dull blue axis (which Celx would refer to as the Y axis of the Earth’s ecliptic frame) points towards Polaris.
18. Press lowercase o to display the orbits of the planets around the Sun. If the Earth is selected, its orbit will be red. To see which way is the Earth traveling along its orbit, select Reference Vectors → Show Velocity Vectorvelocity vector.
19. To fast-forward the Earth’s rotation, press l (lowercase L) three times. The time scale (the rate at which time passes) is displayed temporarily in the lower left corner, permanently in the upper right corner. To return to normal speed, press lowercase k three times. To toggle the direction of time, press j. Watch the people turning on their lights as they move into the night side of the Earth.
20. Verify that the Earth’s (bright) bodyfixed axes rotate with the Earth, while the Earth’s (dull) ecliptic axes remain pointing at the vernal equinox and summer solstice. Then set the time scale back to the original rate of 1 (“Real time”).
21. Turn on the constellations with / (diagonal slash) and the equatorial grid with ; (semicolon). To pan the view left and right, up and down, drag on the sky. Pan over to the center of the Milky Way in SagittariusSagittarius at Right Ascension 17^h 46^m, Declination –29°. Make the galaxy brighter galaxy light gain and dimmer with the parentheses ) and (. Then go back to the default light gain of 0%.
22. Select HubbleHubble Space Telescope, the telescope in orbit around the Earth. Then press c c (center command) to center it and g g (go command) to go there. Drag around it and look at it from various angles. Does it have body axes and ecliptic axes? Select and go to the Moon, the planet Saturn, the star Betelgeuse, and the galaxy M 31 (a.k.a. the Andromeda Galaxy; one space after the uppercase M). To get back to the Earth from points outside our Solar System, you will have to select Sol/slash (in name of celestial object)Earth with a diagonal slash. Or simply press h h (home command) (home) to select the Sun, and g to go to it.
23. To toggle the Celestia consoleconsole, press ~~ (toggle console comand) (tilde). Scroll it up and down with the arrow keys. How many stars are in the binary database?
24. Quit Celestiaquit Celestia. On Mac, Celestia → Quit Celestia; on Microsoft Windows, File → Exit.

Sine and Cosine

On startup, the observer is deposited by start.cel at a position six Earth radii from the center of the Earth, or five radii from the surface. The trig trigonometry function sinesine (trig function), as we all remember, is “opposite over hypotenuse”. Conversely, arcsinarcsine (trig function) 1 6 is the angle whose sine is 1/6. This is the angle subtended (spanned) by half of the Earth from the observer’s point of view.
The whole Earth subtends an angle twice as wide: 2 arcsin 1 6
The angle returned by the Lua arcsine function is in radiansradian. To convert it to degrees, we multiply by 180/π. The Earth therefore subtends an angle of 180 π 2 arcsin 1 6 degrees from the observer’s point of view, approximately 19.1881364537209°. (We write our numbers with 15 significant digits; see doubleArithmetic.) Each degree consists of 60 minutes of arc, and each minute consists of 60 seconds. We can therefore write the angle as 19° 11′ 17.2912333953224″ Does this agree with the Earth’s “Apparent diameter” apparent diameter in the upper left corner of the window?

A First Celx Program

Let’s write a “Hello, World!” program“Hello, World!” program in Celx, save it on the disk, and run it.

The Celx DirectoryCelx directory

Before we write the program, we have to decide what directory to put it in. We will choose the directory that makes it easiest to run the program by typing an operating system command line. This directory is called the Celx directory and it already holds the configuration file celestia.cfgcelestia.cfg (configuration file) and the programs start.cel and demo.cel that we ran in play. It will also hold the Celx Standard Library file std.luastd.lua (file) (standard), the Lua hook file luahook.celx (luaHookFunctions), and the files for scripted orbits and rotations (scriptedOrbit).

Although the Celx directory is in a different location on each platform, we can always find it by searching for the file start.cel.

Macintosh macOS

To get to the Celx directory on a Mac, start with the application Celestia.app. A Mac application is actually a “package”package (Macintosh) of directories and files. (“Directory” and “folder” are synonymous on Mac.) The root directory of this package is named Celestia.app. The Celx directory is a sub-sub-sub directory named CelestiaResourcesCelestiaResources (Macintosh directory). To get there,

1. Double-click on the icon for the Celestia volume you downloaded.
2. Control-click on Celestia.app and select Show Package Contents.
3. Drill down through Contents and Resources to CelestiaResources.

When you get to the Celx directory, you should see the files celestia.cfg, start.cel, and demo.cel.

To go to the Celx directory in the Terminal application, give the following commands.

The entire Celestia volume is read-only. To store a program in the Celx directory, you must give yourself read and write privileges for that volume. Control-click on the icon for the Celestia volume, select Get Info, and open Sharing & Permissions.

If you have no permission to change the permissions, a workaround is to create a read/write copy of Celestia.app. Double-click on the Celestia volume, control-click on Celestia.app, and select Copy "Celestia.app". Then control-click on a new location (your desktop, or the Applications folder in the Macintosh HD) and select Paste Item to create a new Celestia.app. From now on, our Celx directory will be the CelestiaResources sub-sub-sub directory of the new Celestia.app. For example, if we pasted the new Celestia.app onto our desktop, we can get to the Celx directory with the following Terminal command. cd /Users/Yourname/Desktop/Celestia.app/Contents/Resources/CelestiaResources

Microsoft Windows

The Celestia Setup Wizard tells us the name of the Celx directory during installation. It defaults to a directory such as one of the following. C:\Users\Myname\AppData\Local\Celestia
C:\Program Files (x86)\Celestia
C:\Program Files\Celestia Go to the directory and look for the files celestia.cfg, start.cel, and demo.cel. If you don’t see the filename extensions (.cfg and .cel) in the directory, go to
Start → Control Panel → Appearance and Personalization → Folder Options → View → Advanced settings
and uncheck “Hide extensions for known file types”. Press Apply and OK.

Another way to get to the Celx directory is to open the Command Prompt window by running cmd.exe. Then give the following commands. cd C:\Users\Myname\AppData\Local\Celestia (or whichever directory it is) dir celestia.cfg start.cel demo.cel

Linux and Other Versions of Unix

The Celx directory defaults to /usr/local/share/celestia. A different default can be set by passing the command line options --prefix=PREFIX and --datarootdir=DIR to the configureconfigure (shellscript) shellscript that is run before Celestia is compiled. For help with these options, download the Celestia source code and say

cd version
./configure --help | more

If you don’t know where the Celx directory is, find it by searching for the file start.cel with the following command. Discard any error messages by directing them into the garbage pail /dev/null. There is no space between the 2 and the >. find / -type f -name start.cel -print 2> /dev/null

The Celx Program Itself

Our first Celx program will have to perform some kind of output, to prove to us that it actually ran. Otherwise our experiment would produce no result.

Go to the Celx directory (celxDirectory) and launch any text editor capable of creating a plain text file. It can be the text editor with which you examined start.cel in the above exercise. Write your program in a text file named hello.celx (or hello.clx, if you find it important to have a filename extension of exactly three characters).

We will draw a solid box around each program. Commentscomment start with a double dash, implying that Celx does not have the decrement operator “--” used in the language C. A double-dash comment extends to the end of the line. A double-dash comment with double square brackets can extend onto additional lines. Don’t forget the closing brackets.

Do not confuse the lowercase letter o with the digit 0, or the lowercase letter l with the digit 1. For example, the filename extension .celx has a lowercase l. Do not confuse the dash - with the underscore _, or the (parentheses) with the [square brackets] and {curly braces}.

--[[
This file is named hello.celx.
Keep the Sun reassuringly in view,
but position the observer away from its glare.
]]

observer = celestia:getobserver()
position = celestia:newposition(0, 0, 1)	--x, y, z coordinates
observer:setposition(position)

celestia:print("Hello, world!", 10)		--for 10 seconds
wait()			--Give Celestia a chance to update the window.

--[[
Celestia keeps running after the Celx program has finished.
The variables observer and position, and the objects to which they refer,
continue to exist and can be mentioned by subsequent Celx programs.
The text "Hello, world!" remains in the window even after the program
has finished.
]]

Save the file as plain text, since rich text would make Celestia complain about an invisible “curly brace in line 1”. In Mac TextEditTextEdit.app (Macintosh text editor), pull down the Format menu and select Make Plain Text. In Microsoft WordPadWordPad (Windows text editor), select

When the program is run in launch, the output of Celestia:print (celestiaPrint) will be white on black. But we will just give it a double border to save ink. Hello, world!

Objects and Classes, Arguments and Return Values

Let’s examine the objects and methods of the program in programItself. An objectobject (in programming language) is something that does useful jobs for us. There are many classes of objectsclass (of object), including the twelve classes that Celx has added to Lua (listed in additions). The name of each of these classes starts with an uppercase letter.

One class of object is named CelestiaCelestia (class). This class is unusual in that there is always exactly one object of this class (at least until we get to luaHookFunctions). We don’t have to create or destroy this object: it always exists. The object of class Celestia is named celestiacelestia (object), with a lowercase c.

The other two objects, observer and position, are created by the program. They belong to classes ObserverObserver (class) and PositionPosition (class) respectively. But the name of an object does not necessarily have to be the name of its class in lowercase. Just choose a name that reminds you of what the object does.

The jobs that an object can do are called the methodsmethod of the object. An object of class Celestia has methods named getobserver, newposition, and print. The methods of the objects of each class are listed in additions. To tell an object to call (perform) one of its methods, we write the name of the object on the left and the name of its method on the right, joined by a colon. We also write a pair of parentheses after the name of the method. Thus,

A method can access whatever data might be in the object to which it belongs. For example, the getobserver method of the celestia object can access the data in the celestia object. In addition, some methods must be fed additional data such as the three numbers we passed to newposition. These values are called the argumentsargument (of method) of the method and are written inside the parentheses. Even if there are no arguments, the parentheses are still required. Multiple arguments are separated by commas.

A method can produce an object or other value as the result of its work. This value is called the return valuereturn value (of method) of the method. For example, the getobserver method of the object of class Celestia (known henceforth as Celestia:getobserver) gets an object of class Observer and returns it to us. An Observer object represents a point of view in the simulated universe. It has a position, orientation, and velocity. The observer’s initial position is at the barycenterbarycenter (of Solar System) of the Solar System, always in or near the Sun.

We also receive a return value from Celestia:newposition, in this case an object of class Position. The new position was chosen to keep the Sun reassuringly in view—at a respectful distance. The three coördinates of this position are explained in universalFrame.

Some methods produce no return value. Observer:setposition moves the observer to a new position, but returns no value. Celestia:print displays text in the window, but returns no value. See celestiaPrint for the arguments of Celestia:print.

When Celestia is launched without specifying any Celx program, the program start.celstart.cel (Cel program) (programs) automatically whisks the observer to a safe distance from the barycenter. But when we launch Celestia by launching a Celx program, start.cel is not executed and the Celx program must get the observer away from the barycenter. This is an important responsibility. If we remain too close to the Sun, the glare will be blinding. Even worse, if we are inside the Sun, the Sun will be invisible and the user will be disoriented.

A method that does not belong to any object is called a functionfunction. For example, the function waitwait gives Celestia an opportunity to update its window. See wait.

Launch the Celx Program

We can launch our program hello.celx in three ways. The third way must be used if the Celx program produces “standard output” (standardOutput).

1. Launch Celestia, which automatically executes start.cel. Then pull down Celestia’s File menu, select Run Script…, and choose hello.celx. This will execute hello.celx without executing start.cel a second time.
2. Double-click on the operating system icon for hello.celx. This will launch Celestia without executing start.cel. Celestia will then execute hello.celx.
3. Type an operating system command line. This will launch Celestia without executing start.cel. Celestia will then execute hello.celx.

Details about launching on the three major platforms are in the following subsections.

There is no way to pass command line arguments to a Celx program.

A Celx program inherits many values from the previous Celx program(s) run by the same instance of Celestia. These values include the observer object, the renderflags (renderFlags), the nonlocal variables referring to objects and functions (functions), the permissions to access the local file system and operating system via the Lua variables io and os (osExit), and even the six-digit screenshotCount (screenShot). The simplest way to discard this baggage and guarantee a clean start is to quit Celestia and launch it again. For now, don’t worry about it.

A running Celx program can be pausedpause and unpaused with the space bar, and cancelledcancel (terminated) with the escape key. But the escape key does not cancel an event handler function (eventHandler) or a Lua hook function (luaHookFunctions).

The program we’re about to launch contains Celx code that will execute once and then come to an end. Later, we will see other ways of submitting Celx code to Celestia: as a Lua hook (opengl), a scripted orbit or rotation (scriptedOrbit), or a file that is required (standard) by any of the above. A Celx program can also run a Celx program in another file by calling the method Celestia:runscript, or a Celx program in a string by calling the Lua function loadstring.

One piece of trivia. On each platform, the name of the Celx program must be specified with at least one slashslash (in filename) if the program calls the methods Celestia:loadtexture or Celestia:runscript. For example, the name would have to be specified as ./hello.celx or /pathname/of/hello.celx instead of hello.celx.

Macintosh macOS

1. Launch Celestia, pull down the File menu, and select Run Script…. Observe that the resulting menu does not let us drill down into Celestia.app, making it impossible to reach the Celx directory CelestiaResources and run hello.celx. The solution is to move hello.celx into the scripts subdirectory of the Celx directory. We can then get to it by selecting File → Scripts.

2. We can also run hello.celx by double-clicking on the its icon in the Macintosh Finder. If the double click does not launch Celestia, make sure you have chosen Celestia as the application for opening .celx files. Control-click on hello.celx, select Open With, choose Celestia, and check “Always Open With”.

3. We can also run hello.celx by typing a command line in the Terminal application. The command line will launch the executable file Celestia, which will then execute hello.celx.

To make it easy to launch the executable Celestia, take the name of the directory that holds Celestia and append it to the PATH environment variable. You can accomplish this automatically every time you open a Terminal window by putting the following command into the .bash_profile.bash_profile (shellscript) file in your home directory.

Now close and reopen the Terminal window and type the following commands into it.

If no directory name is specified for hello.celx, Celestia will look for it in the Celx directory. In the jargon of operating systems, a pathname passed to Celestia is “relative to” the Celx directory.

The Celx program can be run again by typing command-r into Celestia. There is no need to make the Celx program “executable” with chmod, but see pound, which offers an easier way to run the program.

Microsoft Windows

1. Launch Celestia and pull down the File menu. Select Open Script… and choose your program hello.celx.

2. We can also run hello.celx by double-clicking on its operating system icon. If the double click does not launch Celestia, make sure you have chosen Celestia as the application for opening .celx files. Right-click on hello.celx, select Open With → Choose Program…, choose Celestia, and check “Always use the selected program to open this kind of file”.

3. We can also run hello.celx by opening the Command Prompt window and type one of the following commands. (Launch cmd.exe to open the window.) If no directory name is specified for hello.celx, Celestia will look for it in the Celx directory. In the jargon of operating systems, a pathname passed to Celestia is “relative to” the Celx directory.

The above commands should launch Celestia because we said “Associate .cel and .celx scripts” when we installed Celestia. If Celestia doesn’t launch, we will have to tell the computer that a .celx program should be executed by Celestia.

On Windows 7,
Start → Control Panel → Programs → Default Programs → Associate a file type or protocol with a program
The extension .celx should be listed. If it isn’t, make it open with Celestia.

On Windows XP,
Start → My Computer → Tools → Folder Options… → File Types
If CELX is not listed under Extensions, right-click on hello.celx and select Open. Press “Select the program from a list”, press OK, and browse to Celestia. Check “Always use the selected program to open this kind of file”.

On Windows Vista,
Start → Control Panel → Programs → Default Programs → Make a file type always open in a specific program
The extension .celx should be listed. If it isn’t, make it open with Celestia.

Linux and Other Versions of Unix

Do not install the outmoded Linux version 1.4.1 in the Celestia download page: it rejects a .celx file as an “Invalid filetype”. To run Celx on Linux, get a fresh Celestia from your Linux distribution or go to compileLinux and compile Celestia from the source code.

If no directory name is specified for hello.celx, Celestia will look for it in the Celx directory. In the jargon of operating systems, we say that a pathname passed to Celestia is “relative to” the Celx directory. The -f in front of hello.celx is necessary only if Celestia was compiled with the --with-glutGLUT (OpenGL Utility Toolkit) option of the configureconfigure (shellscript) shellscript. It is not necessary if Celestia was compiled with the --with-gnome, --with-gtk, or --with-kde options.

One exception: if Celestia was compiled --with-kdeKDE (K Desktop Environment), the pathname of the Celx program is relative to the user’s current directory, not the Celx directory. The location of the Celx program affects the arguments of the Celx methods Celestia:loadtexture and Celestia:runscript.

To launch Celestia or any Celx program on my Solaris Unix server, I first have to connect to the server by launching an X WindowX Window server on a Mac or Microsoft Windows. On a Mac, I launch X11.app and log into the Unix server with sshssh -Y. On Microsoft Windows, I launch XmingXming and log into the Unix server with PuTTYPuTTY set to “Enable X11 Forwarding”. Look under PuTTY Configuration → Category → Connection → SSH → X11 or Tunnels.

See pound to make the .celx file executable.

The Idiosyncrasies of Celx

Every language has its own features. Some of the distinguishing marks of Celx were inherited from Lua; others were introduced by Celestia.

Objects vs. Variables

Since the celestia object is heavily used in Celx, we could have given it a shorter name. The following code is a Celx fragment, not a complete program, so we’ll put a dashed box around it. c = celestia observer = c:getobserver() observer = c:newposition(0, 0, 1) The object of class Celestia is unaware that it now has an extra name. In fact, it never knew that it had the name celestia. c and celestia are actually the names of little containers called variablesvariable, completely external to the object. Each variable contains the memory address of an object, by means of which the computer can find its way to the object. The memory address is therefore called a referencereference to object to the object, and a variable that contains a reference is said to refer to the object. In our example, the variables c and celestia refer to the same object. For convenience, we will continue to speak of “the celestia object”, but what we really mean is “the object referred to by the variable named celestia”.

A variable is not an object and does not contain an object. Our assignment statement c = celestia copies the content of the variable celestia into the variable named observer. But this content is merely a reference to an object. The statement does not copy the object itself. Remember, there is only one object of type Celestia.

Our second assignment statement observer = c:getobserver() copies the return value of getobserver into the variable named observer. Again, this return value is merely a reference to an object of type Observer. The object itself is not copied: there is only one observer object in this program.

Functions and Local Variables

A group of Celx statements may be packaged as a functionfunction, shown below. The statements are called the body of the function, and are surrounded by the keywords function and end. To make the keywords more conspicuous, the body of the function indented.

Our convention is to name the first function mainmain (function), but this is not required by the language. In fact, the function is not actually named main, just as the celestia object is not actually named celestia. main is merely a variable that refers to the function, just as celestia is a variable that refers to the object. See the comment alongside the word main.

Packaging the program as a set of functions will let us control how long our variables and objects stay alive. Recall that our original program left behind the variables observer and position and the objects to which they refer. This is wasteful—and a potential breach of security because a subsequent program could manipulate those objects.

To ensure that each variable, object, and function is destroyed as soon as possible, we will mark every variable with the keyword locallocal variable. A local variable created inside the body of a function will exist only as long as the function is being executed; an example is the following variable observer. A local variable created outside the body of a function will exist only as long as the program is being executed; an example is the following variable main. As soon as an object or function has no more variables referring to it, the object or function is no longer accessible to any program and can be automatically incinerated by the Lua garbage collector.

--[[
Create and call a function named main.
]]

local function main()	--this line can also be written local main = function()

	--Keep the Sun in view, but get away from its glare.
	local observer = celestia:getobserver()
	local position = celestia:newposition(0, 0, 1)
	observer:setposition(position)

	celestia:print("Hello, world!", 10)
	wait()

	--[[
	The variables observer and position will be destroyed when we reach the
	following word "end".  Since there are no other variables that refer to
	the Observer and Position objects, these objects may now be destroyed at
	any time by the Lua garbage collector.
	]]
end

--[[
The following statement calls (i.e., executes) the main function.
This will execute the five statements that constitute the body of the function.
]]

main()

--[[
The variable main will be destroyed when we reach the end of the program.  Since
there are no other variables referring to the function, the function may now be
destroyed by the garbage collector.  As usual, Celestia keeps running after the
Celx program is over.
]]

We prefer to create each variable inside of a function. But there are two occasions when we cannot do this. First, each time a local statement is executed, it creates a new variable. If the statement is in a function that is called many times, it will therefore create many variables. If we want a single variable, the variable will have to be created outside of every function. The most common example will be a variable used by each call to a tick handler function (tickHandler).

Second, a variable created in a function can be mentioned only within that function. If the variable needs to be mentioned outside of a function, or in more than one function, the variable will have to be created outside of every function. The most common example will be the variable main, which we will always mention on the last line of a program, outside of every function.

Celx requires two special groups of functions to be nonlocal: the callback functions in callback and the scripted orbits and rotations in scriptedOrbit. All of our other functions will be local.

Methods and Non-methods

Celx functionsfunction fall into two groups, the methods and the non-methods. A methodmethod belongs to an object and can read and write the data in the object. For example, the following call to setposition sets the position of the observer object to which the method belongs. The object and its method are joined with a colon. observer:setposition(position)

A note on nomenclature. To call this method in a Celx program, we write the name of a variable in front of the colon. But to talk about the method itself, quite apart from any particular object of class Observer, we write the name of a class in front of the colon. The name of a Celx class starts with an uppercase letter. Thus we have just called the Observer:setposition method of the object to which the variable observer refers.

A non-method function is called with a dot and cannot read or write the object in front of it. For example, the following functions random and sqrt get no data from the object math. This object is just a convenient last name or family name for grouping these functions together. We will see in arrayOfStrings and standard that math and std are actually “tables”. local x = math.random() local y = math.sqrt(x) local c = std.utf8(0x0041) --the string "A" os.exit(0) --Terminate the Celx program and then terminate Celestia.

Some non-method functions are orphans, belonging to no object at all. They are written without any dot or colon. local s = tostring(10) local t = type(s) print("to the standard output") wait() --a non-method function that Celestia added to Lua main() --a non-method function that we created ourselves For the three non-method functions that Celx added to Lua, see additions.

Chain the Method Calls Together

We often call a method of an object returned by a previous method call. For example, local observer = celestia:getobserver() observer:setposition(position) These two statements could be telescoped into one statement. celestia:getobserver():setposition(position)

A longer sequence such as local earth = celestia:find("Sol/Earth") local position = earth:getposition() local x = position:getx() --position contains x, y, z coordinates. can be telescoped to local x = celestia:find("Sol/Earth"):getposition():getx() By the way, this x is our first variable that does not contain a reference to an object or to a function. It contains a plain old number.

Control Structurecontrol structure

By default, a program executes its statements one at a time from top to bottom. The control structure of a program causes it to execute its statements in a different order. Celx inherits its plain vanilla control structure statements from the language Lua. For examples, see the following sections and their exercises.

For a loop that counts by twos, see the oblate spheroid example in kilometer. For a loop that counts backwards, see the definition of the method Object:family in the file std.lua in stdCelx. For an infinite loop, see the while true do in parallax. Celx has no switch or continue statements. To terminate the Celx program without terminating Celestia, call the Lua functions error or assert (assert). To terminate the Celx program and terminate Celestia, call os.exitos.exit (osExit).

The waitwait Function

The Celx function wait gives Celestia a chance to update the picture in the window. Until we call wait, the picture will not change and the text will not be printed. Even the simulation time will remain frozen (settime). During the call to wait, the picture can move and the simulation time can advance. In fact, it is only during a wait that these things can happen. Another thing that can happen only during a wait is a call to the input function celestia_keyboard_callback (callback); see the while loop in callback.

As soon as a Celx program is over, Celestia automatically regains control and does any overdue rendering. Thus the wait we saw in programItself and functions was unnecessary since those programs took only a fraction of a second to run. But we will write the wait anyway, because it might become necessary if the code were modified. In a long program, for example, wait must be called at least once every five seconds of real time. A program that tries to run too long without calling wait will be terminated with the message Error: Timeout: script hasn't returned control to celestia (forgot to call wait()?) (Even if the program ends in this ignominious manner, the function celestia_cleanup_callback will still be called [callback]). The five-second limit could easily be reached by a program looping through Celestia’s database of a hundred thousand stars. For this reason, the limit can be temporarily extended by Celestia:settimeslice.

wait takes an optional argument giving the number of real-time seconds it will take to return. This can be used to give a long-running special effect such as Observer:goto time to complete its execution, or to give the user time to read a message.

Warning. The Celx function wait is implemented as a call to the Lua function coroutinecoroutine.yield. A call to wait will therefore never return if it is inside a callback function (callback), an event handler (eventHandler), a Lua hook (luaHookFunctions), the position method of a scripted orbit (scriptedOrbit), the orientation method of scripted rotation (scriptedRotation), or a Lua “coroutine”.

Quit Celestia with os.exitos.exit

Celestia normally continues to run after a Celx program has finished. But the program can also terminate Celestia; see standardOutput for an example involving “standard output”.

The Lua function os.exit terminates the Celx program and then terminates Celestia. The function celestia_cleanup_callback in callback will not be called. The argument of os.exit is the exit status number that Celestia will return to the operating system. In most operating systems, zero means success and any nonzero number means failure.

To get permissionaccess policy to mention the variable osos (and the variable ioio in standardOutput and outputFile) we must edit the configuration file celestia.cfgcelestia.cfg (configuration file) and change the parameter ScriptSystemAccessPolicyScriptSystemAccessPolicy (parameter in celestia.cfg) to "allow" or "ask", and relaunch Celestia. The program must also call the method Celestia:requestsystemaccess, even if the access policy is "allow". And if the access policy is "ask", the program must also call wait. No argument is necessary for the wait.

--[[
Demonstrate os.exit, if possible.
]]

local function main()
	--Keep the Sun in view, but get away from its glare.
	local observer = celestia:getobserver()
	local position = celestia:newposition(0, 0, 1)
	observer:setposition(position)

	--Get permission to mention os.  Will ask a question if
	--ScriptSystemAccessPolicy is "ask" in celestia.cfg.
	celestia:requestsystemaccess()
	wait()

	local duration = 5

	if os ~=~= (not equals operator) nil then	--The operator ~= means "is not equal to".
		--Arrive here if the access policy was "allow",
		--or if the access policy was "ask" and the answer was "yes".

		celestia:print("The Celx program will cause Celestia to exit.",
			duration)
		wait(duration)
		os.exit(0)	--0 for success
	end

	--Arrive here if the access policy was "deny",
	--or if the access policy was "ask" and the answer was "no".

	celestia:print("The Celx program can't cause Celestia to exit.",
		duration)
	wait(duration)
end

main()

If the access policy is "ask", Celestia:requestsystemaccess will ask the following question. WARNING: This script requests permission to read/write files and execute external programs. Allowing this can be dangerous. Do you trust the script and want to allow this? y = yes, ESC = cancel script, any other key = no Say yes. If you don’t, the Celx program will end but Celestia will keep running.

To see the exit status returned by Celestia to a Unix operating system, open a shell window. For example, on a Mac, open the Terminal window. In this window, launch Celestia and the Celx program with the following command. Follow it with an echo to display the exit status. Celestia hello.celx echo $? (most Unix shells, including Mac Terminal and Linux) echo $status (Unix C shell)

To see the exit status in on Microsoft Windows, launch cmd.exe to open the Command Prompt window. In this window, launch the Celx program with the following command start /wait command. Follow it with an echo to display the exit status. help start start /wait hello.celx echo %errorlevel%

Two Callback Functionscallback functions

If the program has a nonlocal function with the special name celestia_keyboard_callbackcelestia_keyboard_callback (function), it will be called automatically whenever a character key is pressed. “Characters” include letters, digits, punctuation marks, the blank and tab, delete (backspace), and return. Characters do not include the control, option, and command combinations, the Home and End keys, the four arrow keys, and Escape. For these special keys, write the keydown Lua hook in luaHookFunctions. The characters must be typed into the Celestia window, not the command window from which Celestia was launched.

celestia_keyboard_callback must be enabled by the method Celestia:requestkeyboard. Once enabled, celestia_keyboard_callback will be called even if the program is in the middle of a wait (wait). In fact, that’s the only time it can be called. See the following while loop.

The argument received by celestia_keyboard_callback is the key that was pressed. The following assertions (assert) are primarily for documentation: I don’t expect them to fail. The callback returns true to indicate that the character has been completely handled by the callback and that no further processing is necessary. This means that the character will not be executed as a Celestia keyboard command (play). For example, d will not run the demo and ; (semicolon) will not toggle the equatorial grid. Returning false will allow the character to be executed as a keyboard command. A missing return statement is equivalent to returning true.

The following program accepts one line of keyboard input spelling out a decimal number, possibly including a negative sign, decimal point, and exponent. For example, the line -123.456e-2 represents the number –123.456 × 10^–2 = –1.23456. The main function and the callback function communicate via the variable n. They display the input line, the cursor character, and the error message (if any) as the input line is being accumulated.

celestia_keyboard_callback should concentrate on accumulating the characters of input and recognizing special characters such as backspace and return. The time-consuming astronomical calculations should be triggered by a flag and performed outside the callback function. There should be no need for the callback function to call wait. In fact, a wait in a callback function will never return.

The operator ==== (equals operator) performs comparison for equality (no space between the equal signs). The operator .... (concatenation operator) performs string concatenation (no space between the dots). The characters \r\r (carriage return character) and \n\n (newline character) are the carriage returncarriage return (character) and newlinenewline (character). Multiple lines have to be printed as a single string, by means of a single call to Celestia:print, because each call to this method erases the previous text.

--[[
Let the user input a number from the keyboard.  Store it in n and print it.
]]

--variables used by celestia_keyboard_callback:
local n = nil	--Remains nil until we receive valid number and return key.
local line = ""	--Accumulate the line of input that the user types.
local errorMessage = ""

function celestia_keyboard_callback(c)	--can't be local
	assert(type(c) == "string")

	if c == "\r" then   --return key on Mac, Enter key on Microsoft Windows
		n = tonumber(line)	--Try to convert string to number.
		if n == nil then
			errorMessage = "\nThat wasn't a number.  Try again."
		end
	else
		errorMessage = ""	--Give user the benefit of the doubt.
		if c ~= "\b" then   --backspace (Mac delete, Windows Backspace)
			line = line .. c	--Append the char to the line.
		elseif line:lenstring.len() > 0 then	--If the line has a last char,
			line = line:substring.sub(1, -2)	--remove the last char.
		end
	end

	return true	--Do nothing else with this character.
end

local function main()
	--Keep the Sun in view, but get away from its glare.
	local observer = celestia:getobserver()
	local position = celestia:newposition(0, 0, 1)
	observer:setposition(position)

	local cursor = "_"
	celestia:requestkeyboard(true)	--Enable celestia_keyboard_callback.

	while n == nil do
		celestia:print("Type a number and press Return.\n"
			.. line .. cursor .. errorMessage)

		wait()	--Let Celestia call celestia_keyboard_callback.
	end

	--Arrive here after user has typed a valid number and pressed return.
	assert(type(n) == "number")
	celestia:requestkeyboard(false)	--Disable celestia_keyboard_callback.
	local duration = 5
	celestia:print("The number was\n" .. n, duration)
	wait(duration)
end

main()

A number can hold up to 15 significant digits (doubleArithmetic), but only at most 14 of them will print in the default format (numericFormatting). To get all 15, see the string.format in stringFormat.

Four Event Handlerevent handler Functions

A Celx program can detect four types of eventsevent, represented by the strings "key", "mousedown", "mouseup", and "tick". Four functions, called event handlers, can be called automatically when the events occur. The handlers are enabled by the method Celestia:registereventhandler.

An event handler will go on being called after the last line in the program has executed. The handler will be called even if the user has cancelled the program with the escape key, or if the program has died by not calling wait (wait). To disable a handler, see the exercise in tickHandler. The error messages from a handler are displayed in the console (console).

Tick Handlertick handler

The simplest event is a tick of the Celestia simulation. The simulation “ticks” about 60 times per second of real time when the main event loop of the graphics package is idle. The tick consists of a call to the C++ member function CelestiaCore::tick in version/src/celestia/celestiacore.cpp.

The handler for this event receives one argument, which is a table containing a field named dt giving the number of real-time seconds since the last tick. dt will be about 1/60, except for the first time this function is called. See arrayOfStrings for tables and tableOfFields for fields. The assertion (assert) in the handler is primarily for documentation. The handler prints the current simulation time in UTC, marching in sync with the time display in the upper right corner of the window. See time for UTC vs. TDB.

The number of percent signs in the first argument of string.formatformat must be equal to the number of subsequent arguments. (The first argument is composed of two concatenated strings and contains a total of seven percent signs.) The format %d prints a number as a decimal integer. The format %02d prints it as a decimal integer with at least two digits. If the number has only one digit, a leading zero will be supplied. The last four arguments of Celestia:print put the string up in the upper right corner of the window; see celestiaPrint.

The most common use of a tick handler is to update the display text, or the observer’s position or orientation. A handler may also be used to print OpenGL graphics (opengl) or to trigger an action when a certain time has been reached. For an example in real time, see the exercise below; for simulation time, see settime. The tick handler in radiantPoint measures the speed of a celestial object by recording the object’s position at two consecutive ticks, and dividing by the interval of simulation time between the ticks.

--[[
Call the tickHandler function every time the Celestia clock ticks.
]]

local function tickHandler(t)
	--t.dt is the number of real-time seconds since the previous tick.
	assert(type(t) == "table" and type(t.dt) == "number")

	--Get the current simulation time (not the current real time).
	local utc = celestia:tdbtoutc(celestia:gettime())

	local s = string.format(
		"%d/%d/%d %02d:%02d:%02d UTC\n"
		.. "seconds since last tick: %.15g",
		utc.month, utc.day, utc.year,
		utc.hour, utc.minute, math.floor(utc.seconds),
		t.dt)

	--Don't risk division by zero.
	if t.dt ~= 0 then
		--Append another line to s.
		s = s .. string.format("\nTicks per second: %.15g", 1 / t.dt)
	end

	celestia:print(s, 1, 1, 1, -28, -3)
end

local function main()
	--Keep the Sun in view, but get away from its glare.
	local observer = celestia:getobserver()
	local position = celestia:newposition(0, 0, 1)
	observer:setposition(position)

	celestia:registereventhandler("tick", tickHandler)
	wait()
end

main()

Key Handlerkey handler

A handler can also be registered for the "key" event. It is similar to the celestia_keyboard_callback in callback, but can be called when the program is not executing a wait. It can even be called even after the Celx program has terminated.

Unlike celestia_keyboard_callback, the handler will be called for both control and non-control keys. A control key will be received as a three-character string. For example, the Macintosh delete key is received as "C-h" because the ASCII code of a backspace is 8, and h is the eighth letter of the alphabet. Similarly, a return is received as "C-m" because the ASCII code of a carriage return is (decimal) 13. The four arrow keys are not received by this handler; see luaHookFunctions to catch them. The keystrokes must be typed into the Celestia window, not the command window from which Celestia was launched.

As in celestia_keyboard_callback, a return value of true prevents the character received by the handler from being executed as a Celestia keystroke command. A missing return statement in a key handler is equivalent to returning false.

Let’s write a handler to intercept a typical Celestia keystroke command. The argument of the handler, and the renderflags, are tables of fields. For fields in general, see tableOfFields. For the renderflags table in particular, see renderFlags.

--[[
Intercept the user's semicolon keystrokes which toggle the equatorial grid.
]]

local function keyHandler(t)
	assert(type(t) == "table" and type(t.char) == "string")

	if t.char == ";" then
		local flags = celestia:getrenderflags()
		if flags.grid then
			--Grid is on,
			--and will be turned off after the keyHandler returns.
			celestia:print("Equatorial grid off.")
		else
			--Grid is off,
			--and will be turned on after the keyHandler returns.
			celestia:print("Equatorial grid on.")
		end
	end

	return false	--Let the keystroke be executed as a command.
end

local function main()
	--Keep the Sun in view, but get away from its glare.
	local observer = celestia:getobserver()
	local position = celestia:newposition(0, 0, 1)
	observer:setposition(position)

	celestia:registereventhandler("key", keyHandler)
	celestia:print("Press semicolon to toggle the equatorial grid.", 10)
	wait()
end

main()

Mouse Handlersmouse handler

Handlers can be registered for the "mousedown" and "mouseup" events. For "mousemove", see luaHookFunctions. The x, y coördinates are nonnegative integers measured in pixels from an origin in the upper left corner of the Celestia window. Returning true from the handler will prevent Celestia from selecting the object that was clicked on. A missing return statement in a mouse handler is equivalent to returning false. local function mousedownHandler(t) assert(type(t) == "table" and type(t.button) == "number" and type(t.x) == "number" and type(t.y) == "number") celestia:print("mouse button number = " .. t.button .. " at pixel (" .. t.x .. ", " .. t.y .. ")", 5) return false --Let the click select an object. end

Nine Lua Hook FunctionsLua hook

Functions can be called automatically on nine more occasions, represented by the following strings. "charentered"
"keydown"
"mousebuttondown"
"mousebuttonmove"
"mousebuttonup"
"mousemove"
"renderoverlay"
"resize"
"tick" These functions, called Lua hooks, must be written in a separate file. Our convention is to name the file luahook.celx and place it in the Celx directory (celxDirectory). The filename is specified by placing the following parameter within the {curly braces} of the Configuration section of celestia.cfgcelestia.cfg (configuration file). (The parameter will have to be rewritten with a slash if a Lua hook calls the methods Celestia:loadtexture or Celestia:runscript.) #excerpt from celestia.cfg LuaHook "luahook.celx"

luahook.celx is executed once, when Celestia is launched. It creates a table containing the hooks and passes it to the method Celestia:setluahook. The hooks will be called automatically at the appropriate times. When a hook is called, the table is passed to the hook as the self argument of the hook. Using this argument, the hook can access all of the table’s fields. The table acts like an objectobject (in programming language) in an object-oriented language: the hooks are the object’s methods and the other fields of the table are the object’s instance variables. See Geostationary for a similar “object” implementing a scripted orbit.

On all platforms, the charenteredcharentered (Lua hook) hook receives all normal characters. On Macintosh, it also receives command characters but not control characters. On Windows, it receives control characters. A Mac command character or a Windows control character is received by charentered as a three-character string such as the "C-h" we saw with the "key" event handler in keyHandler. The keystrokes must be typed into the Celestia window, not the command window from which Celestia was launched.

The keydownkeydown (Lua hook) hook is called for special keys: the four arrows, Home and End, the numeric keypad, some of the function keys, and the letters a and z. See orbitObserver for an example with the arrow keys.

The arguments of mousebuttondownmousebuttondown (Lua hook), mousebuttonupmousebuttonup (Lua hook), and mousemovemousemove (Lua hook) are the x, y coördinates of the mouse. They are nonnegative integers measured from an origin at the upper left corner of the window. On most platforms, the arguments of mousebuttonmove are the change in the coördinates since the last call to mousebuttonmove. These numbers will be negative for a move to the upper left, but will always be close to zero. We will use these numbers in opengl to drag a graphic across the window.

mousebuttonmove makes little sense in Microsoft Windows. It is called for every mouse move, even when the mouse button is not pressed. Before the first press, its arguments give the offset from the origin in the upper left corner. After the mouse button is pressed and released at the same position, the arguments give the offset (positive or negative) from that position. While the mouse is being dragged, the arguments are zero and zero. After a drag, the arguments are the offset of the mouse from the center of the Celestia Window.

The renderoverlayrenderoverlay (Lua hook) hook is called each time the transparent overlay on the Celestia window is rendered. This happens many times per second, approximately with each tick of the simulation. The overlay contains text such as the name of the selected object in the upper left corner, the current time in the upper right, and the output of Celestia:print. All OpenGL graphics must be drawn in renderoverlay or in a tick handler (tickHandler). See the examples in opengl Analemma, Sundial, and project.

The resizeresize (Lua hook) hook is called when the Celestia window is resized, including the initial sizing when the window is created. The width and height are nonnegative integers measured in pixels.

Most hooks return the value false by default. This causes the keystroke or mousemove that triggered the hook to have its normal effect after the hook has finished. For example, a keystroke will be executed as one of the keystroke commands in keystroke. A return value of true allows nothing else to happen. It indicates that the keystroke or mouse move has been completely serviced by the hook, and that no further action is necessary.

--[[
This file is luahook.celx.
Create a table named luaHook containing 18 fields.
The values of the first 9 fields are strings.
The values of the last 9 fields are methods.
]]

local luaHook = {
	charenteredString = "",
	keydownString = "",
	mousebuttondownString = "",
	mousebuttonmoveString = "",
	mousebuttonupString = "",
	mousemoveString = "",
	renderoverlayString = "",
	resizeString = "",
	tickString = "",


	charentered = function(self, char)
		assert(type(self) == "table" and type(char) == "string")
		self.charenteredString = "charentered(\"" .. char .. "\")"

		--The default; let a character or a control character
		--be executed as a keystroke command.
		return false
	end,


	keydown = function(self, key, modifiers)
		assert(type(key) == "number" and type(modifiers) == "number")
		self.keydownString = "keydown(" .. key .. ", " .. modifiers
			.. ")"
		if key ~= 0 then
			self.keydownString = self.keydownString
				.. " \"" .. string.char(key) .. "\""
		end

		--The default; let a function key or numeric keypad digit (try
		--"4" and "6") be executed as a keystroke command.
		return false
	end,


	mousebuttondown = function(self, x, y, button)
		assert(type(button) == "number")
		self.mousebuttondownString = "mousebuttondown(" .. x .. ", "
			.. y .. ", " .. button .. ")"
		return false	--the default; let user drag border of splitview
	end,


	mousebuttonmove = function(self, dx, dy, modifiers)
		assert(type(modifiers) == "number")
		self.mousebuttonmoveString = "mousebuttonmove(" .. dx .. ", "
			.. dy .. ", " .. modifiers .. ")"
		return false	--the default; let user drag on sky
	end,


	mousebuttonup = function(self, x, y, button)
		assert(type(button) == "number")
		self.mousebuttonupString = "mousebuttonup(" .. x .. ", " .. y
			.. ", " .. button .. ")"
		return false	--the default; let user select the object
	end,


	mousemove = function(self, x, y)
		self.mousemoveString = "mousemove(" .. x .. ", " .. y .. ")"
		return false	--the default; let user drag on sky
	end,


	renderoverlay = function(self)
		self.renderoverlayString = "renderoverlay()"

		--When printing in upper left corner of window, 6th argument
		--must be <= -1 to avoid chopping off top line of text.
		celestia:print(
			self.charenteredString .. "\n"
			.. self.keydownString .. "\n"
			.. self.mousebuttondownString .. "\n"
			.. self.mousebuttonmoveString .. "\n"
			.. self.mousebuttonupString .. "\n"
			.. self.mousemoveString .. "\n"
			.. self.renderoverlayString .. "\n"
			.. self.resizeString .. "\n"
			.. self.tickString,
			1, -1, 1, 1, -1)

		--Return value is ignored.
	end,


	resize = function(self, width, height)
		self.resizeString = "resize(" .. width .. ", " .. height .. ")"
		--Return value is ignored.
	end,


	tick = function(self, dt)	--dt is seconds since last tick
		self.tickString = "tick(" .. dt .. ")"
		if dt ~= 0 then
			self.tickString = self.tickString
				.. " ticks per second = " .. 1 / dt
		end
		--Return value is ignored.
	end
}

celestia:setluahook(luaHook)
--Don't call the wait function in this file.

Launch Celestia, either with or without a Celx program. Press the keys, move the mouse, and resize the window.

Warning 1. Always check the Celestia console (console) when using Lua hooks, because that’s the destination for error messages produced by the assert and error (assert) functions in luahook.celx. Be careful of uppercase vs. lowercase mistakes. As usual, nonexistent variables and functions are given the value nil, which will probably trigger additional errors—sixty times per second.

Warning 2. There is no direct way for the regular Celx program (e.g., hello.celx) to communicate or synchronize its actions with the hooks in luahook.celx. A trick you could try is the Celestia:settimescale workaround in traceRetrograde. It may be possible to make part or all of the problem disappear by writing code in a tick handler (tickHandler) rather than in the "tick" Lua hook.

Warning 3. Celestia creates the table of Lua hooks very early in the startup process, before the solar system catalog (.ssc) files are read. Therefore Celestia:find cannot be called when the hooks are being created. find can be called later, however, when the hooks are called.

A similar technique must be employed to “require” the Celx standard library in luahook.celx. See standard.

Interactions between the Keyboard Functions

When a key is pressed, up to four Celx functions can be called automatically. In addition, the key can also be executed as a Celestia keystroke command. These functions are called in the following order.

1. the celestia_keyboard_callback in callback
2. the "key" event handler in keyHandler
3. the charentered Lua hook in luaHookFunctions
4. the keydown Lua hook in luaHookFunctions
5. the key is executed as a Celestia keystroke command in keystroke

Each of the first four functions can return true to prevent the subsequent steps from happening. This value means that the keystroke that triggered the function call has been completely serviced by the function, and no further action is necessary. One exception: the keydown hook, if present, is always called.

The Celx Standard LibraryCelx Standard Library

This book presents a Standard Library of classes, functions, and objects to provide the values and services most commonly needed in Celx programming. For example, the standard position at the start of many programs, celestia:newposition(0, 0, 1), has been created once and for all in the library as the object std.position. The prefix “std.” means that the position belongs to a table named std. See tableOfFields for tables.

The features offered by the library fall into three groups.

1. The library contains standard utility functions, such as conversions between Cartesian and polar coördinates or between characters and their UTF-8 representation. It also contains useful objects such as the safe position std.position and the vector std.xaxis, convenient arrays such as std.monthName and std.zodiac, and physical constants such as std.pixelsPerIn and std.tilt (the tilt of the Earth’s axis in radians, approximately 23°).
2. Celx provides two classes, Position (position) and Vector (vectors), that contain the same Cartesian coördinates but have to be handled differently. For example, the method Frame:from accepts a Position but not a Vector, while Rotation:transform accepts a Vector but not a Position. The library makes Position and Vector more interchangeable.
3. Celestia supplies many “frames of reference” or coördinate systems; see framesOfReference. The library can implement a new frame as a rotation of a frame supplied by Celx, keeping the origin at the same point. For example, right ascension and declination coördinates (j2000Equatorial) are easily implemented as a 23° rotation of Celx’s “universal” frame (universalFrame). And altitude and azimuth coördinates (celestialDome) for a given point on a given planet are implemented as a rotation of Celx’s “bodyfixed” frame for that planet (bodyfixedFrame); the particular rotation will depend on the point’s latitude and longitude. These coördinate systems are implemented with the library class RotatedFrame.

The source code of the library is the file in stdCelx. To install it, store it in a plain text file named std.luastd.lua (file) in the Celx directory (celxDirectory). After creating or modifying this file, Celestia must be relaunched.

To access the library, the following program calls the Lua function requirerequire (Lua function). The parentheses( ) (omitted for string argument) are not needed when the function argument is a double-quotedquotes around string string, so we could have omitted them. But the Celx programmer probably has to switch back and forth on an hourly basis to languages where the parentheses are required, so we leave them in. To verify that the library has been loaded, we check that there is a field for it in the package.loadedpackage.loaded table.

The method saneCelestia:sane is added to class Celestia when we require the standard library. It was inspired by the Unix command stty sane and resets the Celestia options to sane values. It displays the planets but not their orbits, the moons but not the asteroids, and the equatorial grid but not the ecliptic grid. For convenience, it returns the observer object.

--[[
Demonstrate that a .celx program can use the Celx Standard Library std
in the file std.lua.
]]
require("std")

local function main()
	--Keep the Sun in view, but get away from its glare.

	if package.loaded.std == nil then
		--require was unable to load the standard library.
		--We can't mention anything that starts with std.
		local observer = celestia:getobserver()
		observer:setposition(celestia:newposition(0, 0, 1))
	else
		--The standard library loaded successfully.
		--It's safe to use all the things that start with std.
		local observer = celestia:sane()
		observer:setposition(std.position)

		local s = "Celx Standard Library version " .. std.libraryVersion
		celestia:print(s, 60, -1, 1, 1, -1)	--upper left corner
	end

	wait()
end

main()

--[[
This file is luahook.celx.
Can't require("std") up here at the top of the file.
]]

local luaHook = {
	renderoverlay = function(self)
		if package.loaded.std == nil then  --standard lib not loaded yet
			--But we can require("std") down here.
			require("std")
		end

		--Demonstrate that renderoverlay can use std.
		celestia:print("std.libraryVersion = " .. std.libraryVersion, 1)
	end
}

celestia:setluahook(luaHook)

--[[
Display the environment variable LUA_PATH and the Lua string package.path.
]]
require("std")

local function main()
	--Keep the Sun in view, but get away from its glare.
	local observer = celestia:sane()
	observer:setposition(std.position)

	celestia:requestsystemaccess()	--Get permission to mention os.
	wait()

	local s = nil
	local LUA_PATH = os.getenv("LUA_PATH")

	if LUA_PATH == nil then
		s = "LUA_PATH does not exist."
	else
		--Put double quotes around it,
		--and a backslash in front of each double quote inside it.
		s = string.format("LUA_PATH = %q", LUA_PATH)
	end

	--Change each semicolon to a newline
	--to display each pattern in package.path on a separate line.
	s = s .. "\n\n" .. package.path:gsubstring.gsub(";", "\n")

	celestia:print(s, 60, -1, 1, 1, -1)	--upper left corner of window
	wait()
end

main()

Output and Input

We covered keyboard input and mouse input in callback, eventHandler, and luaHookFunctions because we classified them as language idiosyncrasies. This section covers the more conventional types of i/o.

PrintCelestia:print on the Celestia Window

The method Celestia:print prints on the transparent overlay on the Celestia window. The color defaults to white and can be overridden by Celestia:settextcolor. The same color should be returned by Celestia:gettextcolor, but it rounds each rgb component to the nearest 255th. For example, the .5 in the following program is rounded to 127/255 ≈ 0.498039. The alpha level is hardwired to 1 (totally opaque).

The font and size are specified by the TitleFontTitleFont (parameter in celestia.cfg) parameter in celestia.cfg: #Excerpt from celestia.cfg. #The file sansbold20.txf is in the fonts subdirectory of the Celx directory. #Don't forget the .txf extension ("texture font") and the double quotes. TitleFont "sansbold20.txf" The TitleFont defaults to the font specified by the another parameter, FontFont (parameter in celestia.cfg), which defaults to the font default.txfdefault.txf (font) in the fonts subdirectory of the Celx directory (celxDirectory). The font cannot be changed while the Celx program is running. To see all the glyphs in the font, see inputFile. For other uses of fonts, see the Celestia console in console, the OpenGL graphics in opengl, and the labels set by Object:mark.

The following program prints the basic statistics about the color, font, and size of Celestia:print. The %8g format prints at least eight characters. For example, the number 1 will have seven blanks in front of it.

--[[
Print the color and the dimensions of an "em" in the font used by
Celestia:print.
]]
require("std")

local function main()
	--Keep the Sun in view, but get away from its glare.
	local observer = celestia:sane()
	observer:setposition(std.position)

	celestia:settextcolor(.5, 1, 1)	--red, green, blue; alpha is 1
	local red, green, blue = celestia:gettextcolor()

	local name = celestia:getparamstring("TitleFont")	--case sensitive
	assert(type(name) == "string")
	if name == "" then	--not found
		name = celestia:getparamstring("Font")
	end
	if name == "" then
		name = "default.txf"
	end

	local font = celestia:loadfont("fonts/" .. name)
	--another way to get the same font:
	--local font = celestia:gettitlefont()
	assert(type(font) == "userdata" and tostring(font) == "[Font]")

	local mWidth = font:getwidth("M")	--Argument can be > 1 character.
	local mHeight = font:getheight()
	assert(mHeight > 0 and mWidth > 0)	--Prevent division by zero.
	local windowWidth, windowHeight = celestia:getscreendimension()

	local s = string.format(
		   "red   = %8g = %3d/255\n"
		.. "green = %8g = %3d/255\n"
		.. "blue  = %8g = %3d/255\n"
		.. "%s: one em is %d x %d pixels.\n"
		.. "Window is %d x %d pixels.\n"
		.. "Window therefore has room for %d lines of %d ems.",

		red, 255 * red,
		green, 255 * green,
		blue, 255 * blue,

		name, mWidth, mHeight,
		windowWidth, windowHeight,
		math.floor(windowHeight / mHeight),
		math.floor(windowWidth / mWidth))

	celestia:print(s, 60, -1, 1, 1, -1)	--upper left corner of window
	wait()
end

main()

The first argument of Celestia:print is the string to be printed, at most 2¹⁰ − 1 = 1023 characters. A longer string will not be printed. There is no need for the string to end with the newline character "\n". For special characters, see specialCharacters.

The second argument is the number of real-time seconds during which the text remains in the window. It defaults to 1.5, including a half-second fadeout whose duration is hardwired into the member function CelestiaCore::renderOverlay in version/src/celestia/celestiacore.cpp. To prevent the program from advancing to the next statement while the text is visible, follow the print with a wait of the same duration. local duration = 5 celestia:print("Your message here.", duration) wait(duration) --until the print fades away --Or you could use std.duration, which is also 5. To keep the text visible forever, or until overwritten by another call to Celestia:print, use a duration of math.huge.

The remaining arguments of Celestia:print are optional pairs of integers specifying a location in the window. The first pair represents the origin for the text. Each integer should be 0 or ±1.

The next pair of integers is the horizontal and vertical offsets from the text origin, measured in ems. Fractions will be ignored. The two pairs default to -1, -1, 0, 5, representing a point five lines above the lower left corner of the window. Celestia:flash prints at the same place.

Warning: with an origin at the top of the window, the vertical offset from the origin must be less than or equal to –1 to prevent the top line of text from being cut off. In other words, if the fourth argument is 1, the sixth argument must be less than or equal to –1.

Use the OpenGL functions in opengl for control over the alpha level and for pixel-level control over the location of the text. OpenGL also permits tilted and superimposed strings, multiple fonts and colors at the same time, and strings longer than 1023 characters. To print on a window divided into multiple views, see the splitview example in Iapetus.

LogCelestia:log to the Celestia Console

The Celestia debugging console displays the standard error output produced by Celestia itself. The console also displays the text written by a Celx program with the method Celestia:log. The method accepts one string argument, to which a newline will be automatically appended. Unlike Celestia:print, a call to Celestia:log does not overwrite the previous call’s text.

The console has room for only 200 lines of text, a default overridden by the LogSizeLogSize (parameter in celestia.cfg) parameter in celestia.cfg. (Actually, one less: 199.) A line longer than 120 characters will be split, counting as two separate lines for the 200-line limit.

The color (white) and alpha level (1) are hardwired into the member function CelestiaCore::draw in version/src/celestia/celestiacore.cpp. The font is specified by the FontFont (parameter in celestia.cfg) parameter in celestia.cfg: #Excerpt from celestia.cfg. Font "sans12.txf" It defaults to default.txf.

Let’s list the image files that are loaded when we go to the Earth:

--[[
Go to the Earth, causing its texture (image) files to be loaded.
]]
require("std")

local function main()
	local observer = celestia:sane()

	celestia:log("About to go to Earth.  The console font is "
		.. celestia:getparamstring("Font") .. ".")

	local earth = celestia:find("Sol/Earth")
	observer:goto(earth, std.duration)	--std.duration is 5 seconds.
	wait(std.duration)			--Wait until goto is finished.

	celestia:log("We have gone to Earth.")
	wait()
end

main()

Press ~ (tilde) to toggle the console, the up and arrow arrows to scroll it, and Page Up and Page Down to scroll ten lines at a time.

Write to the Standard Outputstandard output and Standard Error Output

The text written by Celestia:print and Celestia:log can easily be read by a human being. But it would be hard for another program to read this text, since it is written in pixels in a window. Data intended for consumption by another program, or for storage in a file, should be written to Celestia’s standard output and standard error outputstandard error output. Standard output is for successful output; standard error is for error messages.

Standard output is produced by the Lua function printprint (Lua function), not to be confused with the Celx method Celestia:print. The Lua print concatenates its arguments and follows them with a newline. To avoid the tabs and newline, call the writewrite (method of file) method of the object io.stdoutio.stdout (outputFile). Standard output can also be produced by the method Object:setatmosphere, and by the keystroke commands @ and ! in Celestia’s “super-secret edit mode”. Standard error output is producted by the write method of io.stderrio.stderr. Upon success, write returns true in Lua 5.1, and returns the io.stdout or io.stderr object in Lua 5.2. For access to the variables io and os, see osExit.

Sometimes a Celx program is run only for the purpose of producing standard output. This is often the case when the program is launched from a Unix shellscript, or when its standard output is directed into an output file or pipepipe (Unix). In this situation, we usually want the program to quit Celestia with the function os.exitos.exit (osExit) when the output is finished.

The standard output written by print might not go to the outside world immediately. It could be held in an area of memory inside Celestia called a bufferbuffered i/o. Successive calls to print will fill up more and more of the buffer. When the buffer is full, all of its data is flushed to the outside world in one big convoy. The buffer is also flushed automatically by os.exit when the program ends. The standard error output is unbuffered and requires no flush.

A Celestia that is launched from the command line and that produces buffered output such as standard output must be allowed to die a natural death, either by selecting Quit or Exit from Celestia’s File menu or by calling os.exit. If Celestia is launched from the command line and then assassinated with a control-ccontrol-c (keystroke), the last buffer of standard output might be trapped inside the dying Celestia and might never emerge.

--[[
Demonstrate standard output (for good news)
and standard error output (for bad news).
]]

local function main()
	--Get permission to mention io and os.
	celestia:requestsystemaccess()
	wait()

	if io == nil or os == nil then
		celestia:print("Cannot demonstrate standard i/o or os.exit.",
			10)
		wait()
	else
		--No newline is appended implicitly.
		local r = io.stdout:write("This is standard output ")
		assert(r)	--r is boolean in Lua 5.1

		--Newline is appended implicitly.
		print("and more standard output on the same line.")

		--No newline is appended implicitly.
		r = io.stderr:write("This is standard error output.\n")
		assert(r)

		--Before the Celestia window disappears,
		--give the user time to see that it has no text.
		wait(5)
		os.exit(0)	--flushes the output buffer
	end
end

main()

Most forms of output are directed to a destination specified (at least implicitly) in the program itself: Celestia:print outputs to the window and Celestia:log to the console. But the standard output and standard error output are sent to destinations specified in the command line that launched the program. Let’s take the Macintosh Terminal as an example; the other command lines follow the same rules.

1. With no i/o redirection, the Celx program’s standard output and standard error output are directed to the command window itself. (A Celestia compiled --with-glutGLUT (OpenGL Utility Toolkit) also requires a -f argument before the program name.) Celestia progname.celx This is standard output and more standard output on the same line. This is standard error output.
2. The standard output can be directed to a file on the disk, while the standard error output goes to the command window. Celestia progname.celx >> (i/o redirection) out.txt This is standard error output.
3. Conversely, the standard error output can go to a file while the standard output goes to the command window. There is no space between the 2 and the >. Celestia progname.celx 2>2> (i/o redirection) err.txt This is standard output and more standard output on the same line.
4. We can direct the outputs to two separate files. Celestia progname.celx > out.txt 2> err.txt
5. Or we can combine both outputs in one same file. Celestia progname.celx > same.txt 2>&12>&1 (i/o redirection)

On Microsoft Windows, the standard output and standard error output of Celestia vanish into thin air. This is because Celestia never creates a Microsoft “console”console (Microsoft Windows) by calling the AllocConsole function. The workaround is to write the data to an output file (outputFile).

Read from the Standard Inputstandard input

For Unix programmers, we present a filterfilter, Unix that copies its standard input to its standard output. As the standard input flows through the program, it is also copied to the Celestia window.

By default, the standard input comes from the keyboard. In this case, the keystrokes must be typed into the shell window, not the Celestia window, and we must press return at the end of each line. The standard input can also come from a pipe. To make the pipe work without human intervention, set the ScriptAccessPolicy in celestia.cfg to "allow" and relaunch Celestia.

Both waitwaits around the following call to readread (method of file) are necessary to keep the string s up to date. If either one is missing, the string lags behind the characters as they are typed. If both are missing, the tick handler is never called.

On Microsoft Windows, the read method always returns nil. The standard output is broken too; see standardOutput.

--[[
Copy the standard input to the standard output.  Along the way, carbon copy it
into the Celestia window, like the Unix utility teetee (Unix utility).
]]
require("std")

--variable used by tickHandler:
local s = ""

local function tickHandler()
	celestia:print(s, 1, -1, 1, 1, -1) --upper left, in case s is multi-line
end

local function main()
	local observer = celestia:sane()
	observer:setposition(std.position)
	celestia:requestsystemaccess()     --get permission to mention io and os
	wait()
	celestia:registereventhandler("tick", tickHandler)

	while true do
		wait()
		local c = io.stdinio.stdin:read(1)	--one character
		wait()
		if c == nil then		--end of file
			break
		end
		--Write the standard output in uppercase, so we can tell it
		--apart from the standard input in the shell window.
		io.stdout:write(c:upper())
		s = s .. c
	end

	--Arrive here on end of file.
	celestia:registereventhandler("tick", nil)
	local duration = 5
	celestia:print(s .. "\nEOF", duration, -1, 1, 1, -1)
	wait(duration)
	os.exit(0)
end

main()

Standard input comes from a source specified on the command line that launched the program:

1. With no i/o redirection, the Celx program’s standard input comes from the keyboard. (A Celestia compiled --with-glut also requires a -f argument before the program name.) Celestia progname.celx
2. The standard input can come from an input file. Celestia progname.celx < in.txt
3. The standard input can come from an input pipepipe (Unix). anotherprog | Celestia progname.celx

Write to an Output Fileoutput file

For output to a file whose name is specified in the program itself, we have the conventional trio of openio.open, writewrite (method of file), and closeclose (method of file). The first argument of io.open is the name of the output file to be created, by default in the Celx directory. The second argument is "w" for write. See osExit for access to the variables io and os, and standardOutput for a warning about buffered output.

--[[
Create and open an output file, write to it, and close it.
Check for every checkable error.
]]

local function main()
	--Get permission to mention io and os.

	celestia:requestsystemaccess()
	wait()
	if io == nil or os == nil then
		celestia:print("Cannot demonstrate file output or os.exit.", 10)
		wait()
		return	--Don't execute any more of the main function.
	end

	--Open the file.

	local name = "outfile.txt"
	local handle, message, code = io.open(name, "w")   --create or overwrite
	if handle == nil then
		local s = "couldn't open file " .. name .. "\n"
			.. message .. ", code " .. code .. "\n"
		io.stderr:write(s)
		wait()
		os.exit(1)	--1 indicates failure on my operating system
	end
	assert(type(handle) == "userdata" and io.type(handle) == "file")

	--Write to the file.

	local success, message, code =
		handle:write("This output goes to a file on the disk.\n")
	if success == nil then
		local s = "couldn't write to file " .. name .. "\n"
			.. message .. ", code " .. code .. "\n"
		io.stderr:write(s)
		wait()
		os.exit(1)
	end

	--Close the file.

	local success, message, code = handle:close()
	if success == nil then
		local s = "couldn't close file " .. name .. "\n"
			.. message .. ", code " .. code .. "\n"
		io.stderr:write(s)
		wait()
		os.exit(1)
	end
	assert(type(handle) == "userdata" and io.type(handle) == "closed file")

	--os.executeos.execute("chmod 444 " .. name)   --change mode: only on Unix systems
	wait()
	os.exit(0)		--0 indicates success on my operating system
end

main()

The program creates the file output.txt, containing the following.

Read from an Input Fileinput file

Let’s read from one of Celestia’s own data files. We’ll pick a .txftxf file (Texture Font) file (an OpenGL txf font) to demonstrate textual input (the first four bytes of the file) and binary input (the rest of the file). The binary numbers are read in 16- and 32-bit sizes, and in big-endianendian (byte order) or little-endian byte order. To assemble the binary numbers, we shift shift the individual bytes into position by multiplying them by a power of 2. For example, multiplying a byte by 2⁸ = 256 shifts it 8 bits to the left. Lua 5.2 will let us shift the bytes with bit32.lshift.

This program also demonstrates random access i/o with file:seekseek (method of file). With the argument "cur", this method skips the designated number of bytes starting from the current position in the file.

The first character in the file is the byte of “all ones”. Lua 5.2 will let us write this character as "\xFF", but Lua 5.1 makes us write it as "\255". The std.utf8 function (specialCharacters) converts a Unicode code number into the string of UTF-8 bytes representing that character.

--[[
Display all the glyphs (characters) that belong to the TitleFont in
celestia.cfg, 16 per line, with the four-hex-digit Unicode number of each glyph.
]]
require("std")

--Read an n-byte integer in binary: 2 or 4 bytes
local reverse = nil	--true if bytes need to be reversed

local function read(handle, n)
	assert(type(handle) == "userdata" and io.type(handle) == "file"
		and (n == 2 or n == 4))
	local s = handle:read(n)
	assert(type(s) == "string" and s:lenstring.len() == n)
	if reverse then
		s = s:reversestring.reverse()
	end
	local b = {s:bytestring.byte(1, n)}		--b is an array of n numbers.
	assert(type(b) == "table" and #b == n)
	local i = 0
	for j = 1, n do
		i = 2^8 * i + b[j]
	end
	return i
end

local function main()
	local observer = celestia:sane()
	local position = celestia:newposition(1, 0, 0)	--Sun not in window.
	observer:setposition(position)

	--Get permission to mention io.

	celestia:requestsystemaccess()
	wait()
	if io == nil then
		celestia:print("Cannot demonstrate file input.", 10)
		wait()
		return
	end

	local name = "fonts/" .. celestia:getparamstring("TitleFont")
	local handle, message, code = io.open(name, "r")	--r for "read"
	if handle == nil then
		local s = "couldn't open file " .. name .. "\n"
			.. message .. ", code " .. code
		celestia:print(s, 60)
		return
	end

	if handle:read(4) ~= "\255txf" then	--a byte of "all ones"
		celestia:print("couldn't read four-byte header in " .. name, 60)
		return
	end

	--Do we have to reverse the bytes of the integers read from the file?
	local b = {handle:read(4):byte(1, 4)}	--b is an array of four numbers.

	if b[1] == 0x78 and b[2] == 0x56 and b[3] == 0x34 and b[4] == 0x12 then
		reverse = true
	elseif b[4] == 0x78 and b[3] == 0x56 and b[2] == 0x34 and b[1] == 0x12
		then
		reverse = false
	else
		local s = string.format(
			"unfamiliar byte order %02X %02X %02X %02X in %s",
			b[1], b[2], b[3], b[4], name)
		celestia:print(s, 60)
		return
	end

	handle:seek("cur", 3 * 4)	--Skip the next 3 four-byte integers.
	local maxAscent = read(handle, 4)
	local maxDescent = read(handle, 4)
	local n = read(handle, 4)	--number of glyphs in font

	local s = string.format(
		"%s reverse: %s\n"
		.. "Max ascent: %u Max descent: %u Number of glyphs: %u\n",
		name, tostring(reverse),
		maxAscent, maxDescent, n)

	for i = 1, n do
		local unicode = read(handle, 2)	--unicode character number
		s = s .. string.format("%04X %s ", unicode, std.utf8(unicode))

		--Display 16 glyphs of the font per line.
		if i % 16 == 0 then	--if i is divisible by 16
			s = s .. "\n"
		end

		--Skip 6 one-byte integers and 2 two-byte integers.
		handle:seek("cur", 6 * 1 + 2 * 2)
	end

	celestia:print(s, math.huge, -1, 1, 1, -1)	--upper left corner
	handle:close()
	wait()
end

main()

On Macintosh and Microsoft Windows, the bytes are reversed. On Microsoft, the second argument of io.open must be "rb" because the input file is binarybinary input file.

Error Messages and Assertions

The Lua function errorerror (Lua function) displays an error message and terminates the Celx program, but it lets Celestia keep running. The function accepts one string argument, to which a newline is appended.

--[[
Call the Lua error function if anything goes wrong.
]]
require("std")

local function main()
	--Keep the Sun in view, but get away from its glare.
	local observer = celestia:sane()
	observer:setposition(std.position)

	--Get permission to mention io.
	celestia:requestsystemaccess()
	wait()

	if io == nil then
		error("Cannot demonstrate file input.")
		--Don't call wait here, because we never return from error.
	end

	local handle, message, code = io.open("fonts/default.txf", "r")
	if handle == nil then
		error("couldn't open file " .. name .. "\n"
			.. message .. ", code " .. code)
	end

	local success, message, code = handle:close()
	if success == nil then
		error("couldn't close file " .. name .. "\n"
			.. message .. ", code " .. code)
	end

	wait()
end

main()

The Lua assertassert (Lua function) function provides a more compact notation for the if/then/error/end. Its second argument defaults to the string "assertion failed!".

Unfortunately, the second argument of assert is evaluated even if the first one is false. The second argument might be an expensive call to string.format.

The Standard Library in stdCelx therefore calls error instead of assert.

In this book we will often write an assert just as concise documentation when introducing a new function, not because we think there is a realistic chance of failure. Plentiful examples were in the Lua hooks in luaHookFunctions.

Where do the assert and error messages go, and the similar messages from syntax errors and undefined variables? On Macintosh, the messages are written to Celestia’s standard output, followed by a dramatic “finis”finis on the standard error output. The messages therefore appear only if Celestia is launched from a command line in the Terminal application. On Microsoft Windows, the error messages appear in a modal dialog box entitled “Fatal Error”.

On Linux, a Celestia launched from the comand line will write its error messages to the standard output. A Celestia compiled --with-kdeKDE (K Desktop Environment) will also put up a dialog box with a Details button to display the message. This civilized behavior is the result of the call to CelestiaCore::setAlerter in the constructor for KdeApp in version/src/celestia/kde/kdeapp.cpp. A Celestia compiled with --with-glut, --with-gnome, or --with-gtk will not put up a dialog box. Instead, it will die with a SIGSEGVSIGSEGV (signal) signal (“Segmentation Faultsegmentation fault (core dumpedcore dump)”) because CelestiaCore::setAlerter is never called.

Errors and assertions are handled differently in a callback (callback), event handler (eventHandler), Lua hook (luaHookFunctions), or scripted orbit or rotation (scriptedOrbit). In this case the error message is written to the Celestia console (console), not to the standard output. The function that called error or assert is terminated, but the rest of the Celx program keeps running. (A message from a scripted orbit or rotation may disappear into thin air.)

2D OpenGL GraphicsOpenGL graphics

Celestia is implemented with the OpenGL graphics library, a set of functions for drawing 2D and 3D graphics. Some of them can be called directly by a Celx program. We will use them to plot the stars in the Hertzsprung-Russel diagram (loopDatabase), to draw an analemma (Analemma), to lay out the lines on a sundial (Sundial), and to trace the path of a celestial object (project).

Most of the Celx graphics functions are 2D. In this section, we will just draw a pair crosshairs on the Celestia window. For the third dimension, see the functions gl.Frustum, gl.Ortho, and glu.LookAt in additions.

The OpenGL functions draw on the transparent overlay that covers the Celestia window. To keep the graphics continuously visible, we will have to redraw them every time the overlay is rendered. The drawing will therefore have to take place in a tick handler (tickHandler) or in the tick or renderoverlay Lua hooks (luaHookFunctions). In this book, we’ll use the renderoverlay hook. To erase the graphics, the hook can simply return without drawing anything. The graphics will then disappear in the next sixtieth of a second.

A matrixmatrix (OpenGL) is a rectangle of numbers arranged in rows and columns. OpenGL maintains two stacksstack (OpenGL) of matrices. The matrix at the top of the projection stackprojection stack (OpenGL) controls how the graphics are mapped onto the overlay. We’ll push a plain vanilla identity matrixidentity matrix (OpenGL) onto this stack because we’re doing 2D graphics with no perspective or foreshortening. The matrix at the top of the modelview stackmodelview stack (OpenGL) controls how the graphics are positioned in space. We’ll push another identity matrix to keep the graphics lying flat in the plane of the overlay.

Each push is performed in three steps. First, the function gl.MatrixModegl.MatrixMode designates the stack onto which the matrix will be pushed. Then gl.PushMatrixgl.PushMatrix pushes a copy of the top matrix onto the stack. The two top matrices are now identical. Finally, gl.LoadIdentitygl.LoadIdentity changes the top matrix into an identity matrix. Don’t forget that the pushed matrix must eventually be popped off the stack.

OpenGL uses its own system of x, y coördinates for the pixels. The call to glu.Ortho2Dglu.Ortho2D sets the x coördinates of the overlay’s leftmost and rightmost columns of pixels to 0 and width − 1 respectively, and the y coördinates of the bottom and top rows of pixels to 0 and height − 1. This means that the origin (0, 0) is at the lower left corner of the overlay, with x increasing to the right and y increasing upwards. glu.Ortho2D modifies the identity matrix we pushed onto the projection stack, so it must be called while that stack is still the current one.

We don’t have to keep the origin in the lower left corner. The call to gl.Translate moves the origin to the center of the overlay to make it easier to draw the crosshairs.

The arguments of gl.Colorgl.Color specify an rgb color and an alpha level. With our alpha of .25, the crosshairs will contribute only .25 of the color of the pixels they occupy, while the objects covered by the crosshairs will contribute the remaining 1 − .25 = .75 of the color. These fractions are represented by the constants gl.SRC_ALPHAgl.SRC_ALPHA and gl.ONE_MINUS_SRC_ALPHAgl.ONE_MINUS_SRC_ALPHA.

gl.POINTSgl.POINTS draws a series of separate points (loopDatabase), gl.LINESgl.LINES a series of separate line segments (Sundial), gl.LINE_STRIPgl.LINE_STRIP a series of connected line segments (Analemma and project), and gl.LINE_LOOPgl.LINE_LOOP a series of connected line segments that returns to its starting point (loopDatabase). The following gl.LINES must be followed by an even number of vertices. The x and y coördinates of the vertices are listed between the gl.Begin and gl.End.

--[[
This file is luahook.celx.
Demonstrate OpenGL graphics by drawing vertical and horizontal crosshairs.
]]

local luaHook = {
	renderoverlay = function(self)
		--If it is now more than 60 seconds after Celestia started
		--running, stop calling this method.
		if celestia:getscripttime() > 60 then
			self.renderoverlay = nil
			return
		end

		if package.loaded.std == nil then   --standard lib not loaded yet
			require("std")        --not needed yet, but will be later
		end

		gl.MatrixMode(gl.PROJECTION)
		gl.PushMatrix()
		gl.LoadIdentity()

		--dimensions of the Celestia window, in pixels
		local width, height = celestia:getscreendimension()
		glu.Ortho2D(0, width, 0, height)   --left, right, bottom, top

		gl.MatrixMode(gl.MODELVIEW)
		gl.PushMatrix()
		gl.LoadIdentity()

		--The default origin (0, 0) is at the lower left corner of the
		--window.  Move the origin to the center.
		gl.Translate(width / 2, height / 2)

		gl.Enable(gl.BLEND)
		gl.BlendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA)
		gl.Disable(gl.LIGHTING)  --Make text and graphics self-luminous.
		gl.Disable(gl.TEXTURE_2D)	--disabled for graphics
		gl.Color(0, 1, 1, .25)		--red, green, blue, alpha
		gl.LineWidth(1)  --In pixels.  Defaults to 1; can have fraction.

		gl.Begin(gl.LINES)
						--Horizontal crosshair goes
		gl.Vertex(-width / 2, 0)	--from middle of left edge
		gl.Vertex( width / 2, 0)	--to middle of right edge.

						--Vertical crosshair goes
		gl.Vertex(0, -height / 2)	--from middle of bottom edge
		gl.Vertex(0,  height / 2)	--to middle of top edge.
		gl.End()

		gl.MatrixMode(gl.MODELVIEW)
		gl.PopMatrix()

		gl.MatrixMode(gl.PROJECTION)
		gl.PopMatrix()
	end
}

celestia:setluahook(luaHook)

--[[
Provide an unobtrusive background for the OpenGL graphics.
]]
require("std")

local function main()
	local observer = celestia:sane()
	observer:setposition(std.position)
	wait()
end

main()

In project we will establish a connection between the two-dimensional overlay and the three-dimensional simulated universe beyond it. Until then, the graphics will not be aware of the celestial objects in the universe.

Astronomical Numbers

How can we format the digits of an astronomical number? Even more importantly, how many digits are there to format? We raise this issue to forestall any hopeless quest for a level of precision that just isn’t present in the number.

Doubledouble precision floating point Arithmetic

A Celx number is implemented as a C language “double precision floating point number”, known familiarly as a double. This policy is set by the LUA_NUMBERLUA_NUMBER (macro) macros in the luaconf.hluaconf.h (header file) header files in the directories luaversion/src, version/macosx, and version/windows/inc/lua-5.1. The first macro is the most important.

On my machine, and probably also on yours, a nonzero double holds a value in one of two possible formats. The normalizednormalized (double) format is presented here; the denormalized in denormalized.

A normalized nonzero double holds a value of the form ± numerator 2⁵³ · 2^exponent Let’s look at each piece separately. The fraction numerator 2⁵³ is called the mantissamantissa (of double) of the number. On my machine, and probably also on yours, the numerator of the mantissa is an integer in the range 2⁵² = 4,503,599,627,370,496 to 2⁵³ − 1 = 9,007,199,254,740,991 inclusive. These limits make more sense in binary. 2⁵² = 10000000000000000000000000000000000000000000000000000
2⁵³ − 1 = 11111111111111111111111111111111111111111111111111111 We can now see that a numerator is a 53-bit number whose most significant bit is 1. There are 2⁵² possible values for the numerator, and the largest one is practically twice as big as the smallest.

The denominator is fixed at 2⁵³ = 9,007,199,254,740,992 so the value of the mantissa is in the range 4,503,599,627,370,496 9,007,199,254,740,992 ≤ mantissa ≤ 9,007,199,254,740,991 9,007,199,254,740,992 which we can simplify to .5 ≤ mantissa < 1

The exponentexponent (of double) of a double is an integer in the range –1021 to 1024 inclusive, with a base of 2. The values of the numerator, denominator, and exponent of a nonzero double can be isolated with the Lua function math.frexpmath.frexp and the standard library function std.fractionstd.fraction. The limits are available as macros in the C Standard Library header file float.hfloat.h (header file).

The largest possible normalized double has the largest mantissa and the largest exponent:

And the smallest positive normalized double has the smallest mantissa and the smallest exponent:

Of greater practical concern is the number of significant decimal digitssignificant digits a double can hold. These are the digits from the leftmost to the rightmost nonzero digits of the double, inclusive. Here is a number with 15 significant digits:

A double can always hold at least 15 significant digits, and sometimes more. Let’s demonstrate this with the fraction ⅓, always the acid test of precision. The double value closest to ⅓ does indeed have at least 15 threes before it breaks up into garbage. In fact, it has 16 of them. 6,004,799,503,160,661 2⁵³ · 2^–1 = 6,004,799,503,160,661 9,007,199,254,740,992 · 2^–1 = 6,004,799,503,160,661 18,014,398,509,481,984


= 0.333333333333333314829616256247390992939472198486328125

--[[
Demonstrate that a double can hold at least the first 15 threes of 1/3.
]]
require("std")

local function main()
	--Keep the Sun in view, but get away from its glare.
	local observer = celestia:sane()
	observer:setposition(std.position)

	local x = 1/3
	local mantissa, exponent = math.frexp(x)
	local denominator = 2 ^ std.mantissa
	local numerator = math.abs(mantissa) * denominator

	local signBit = 0
	if x < 0 then
		signBit = 1
	end

	--The numerator and denominator cannot be formatted with %d, even though
	--they are integers, because they are greater than or equal to 2^31.

	local s = string.format(
		"x =        %.54f\n"
		.. "sign bit = %d\n"
		.. "mantissa = %.54f\n"
		.. "exponent = %d\n"
		.. "numerator   of mantissa = %.0f\n"
		.. "denominator of mantissa = %.0f\n"
		.. "A double with a %d-bit mantissa "
		.. "can hold up to %d significant decimal digits.",
		x,
		signBit, mantissa, exponent,
		numerator, denominator,
		std.mantissa, std.significant)

	celestia:print(s, 60, -1, 1, 1, -1)	--upper left corner
	wait()
end

main()

The Macintosh output was

The Microsoft Windows output was

On both platforms, we will therefore format a double with string.format using the %.15g format in floatFormat.

--[[
Print the distance in lightyears from the Solar System Barycenter
to Betelgeuse.
]]
require("std")

local function main()
	--Keep the Sun in view, but get away from its glare.
	local observer = celestia:sane()
	observer:setposition(std.position)

	local barycenter = celestia:find("Solar System Barycenter")
	assert(barycenter:type() == "star" --The barycenter isn't really a star.
		and barycenter:getinfo().stellarClass == "Bary")

	local betelgeuse = celestia:find("Betelgeuse")
	assert(betelgeuse:type() == "star")

	--vector pointing from barycenter to Betelgeuse
	local toBetelgeuse = betelgeuse:getposition() - barycenter:getposition()

	local microlightyears = toBetelgeuse:length()
	local mantissa, exponent = math.frexp(microlightyears)

	local s = string.format(
		   "distance in microlightyears = %.15g\n"
		.. "distance in lightyears      = %.15g\n"
		.. "exponent = %d",
		microlightyears,
		microlightyears * 1e-6,
		exponent)

	celestia:print(s, 60)
	wait()
end

main()

Denormalized Numbersdenormalized (double)

We saw in doubleArithmetic that the smallest positive normalized doubledouble precision floating point is 2⁵² 2⁵³ · 2^–1021 = 2^–1022 ≈ 2.22507385850720 · 10^–308 Even smaller positive values can be stored in a denormalized or subnormal doublesubnormal (double). On my machine, and probably also on yours, a denormalized double has the form ± numerator 2⁵³ · 2^–1021 The numerator of a denormalized double is an integer in the range 1 to 2⁵² − 1 inclusive. The exponent is fixed at –1021. Thus the smallest positive denormalized double value is 1 2⁵³ · 2^–1021 = 2^–1074 ≈ 4.94065645841247 · 10^–324 which is 2⁵² ≈ 4.5 · 10¹⁵ times smaller than the smallest positive normalized double. These 15 orders of magnitude will postpone the inevitable day when underflow occurs.

Catastrophic Cancellationcatastrophic cancellation

The following value for cos θ is correct to 15 significant digits, and we expect no less. But the value for 1 − cos θ is correct to only 6 significant digits. The next 9 digits are garbageprecision, loss of. What happened?

--[[
Catastrophic cancellation:
cos(theta) is close to 1 for a very small angle theta.
]]
require("std")

local function main()
	local observer = celstia:sane()
	observer:setposition(std.position)
	local theta = math.rad(1 / (60 * 60))	--one second of arc

	local s = string.format(
		   "1              = %.15f\n" --15 dig to right of decimal point
		.. "cos(theta)     = %.15f\n"
		.. "1 - cos(theta) = %.25f computed\n"
		.. "1 - cos(theta) = %.25f correct value (to 15 sig digits)",

		1,
		math.cos(theta),
		1 - math.cos(theta),
		.0000000000117522152695259)

	celestia:print(s, 60)
	wait()
end

main()

The problem is that 1 and cos θ are very close together, differing only in their rightmost five digits. Beyond those digits, the difference is mostly garbage.

Is our angle of 1″ too small to bother with realistically? Not at all. Astronomers regularly deal in milliarcseconds when studying the angular diameter and exoplanets of a star. See the parallax example in parallax.

Fixed Pointfixed point numberArithmetic

In one special case, Celx uses a different numeric format to deliver a much higher level of precision. An object of class PositionPosition (class) (position) holds the x, y, z coördinates of a position in the Celestia universe. Each coördinate is stored in the format n · 2^–64 where n is an integer ranging from –2¹²⁷ = –170,141,183,460,469,231,731,687,303,715,884,105,728 ≈ –1.70141183460469 · 10³⁸ to 2¹²⁷ − 1 = 170,141,183,460,469,231,731,687,303,715,884,105,727 ≈ 1.70141183460469 · 10³⁸ inclusive. Since the exponent is fixed at –64, this format is called fixed point as opposed to the floating point in doubleArithmetic.

The largest fixed point number has the largest n: (2¹²⁷ − 1) · 2^–64 = 2⁶³ − 2^–64 = 9,223,372,036,854,775,808 – 1 18,446,744,073,709,551,616

= 9,223,372,036,854,775,807.9999999999999999999457898913757247782996273599565029144287109375 The smallest positive fixed point number has the smallest positive n: 1 · 2^–64 = 1 18,446,744,073,709,551,616

= .0000000000000000000542101086242752217003726400434970855712890625

≈ 5.42101086242752 · 10^–20 And the closest fixed point number to ⅓ has 19 threes before it breaks up into garbage: 6,148,914,691,236,517,205 · 2^–64 = 6,148,914,691,236,517,205 18,446,744,073,709,551,616

= 0.3333333333333333333152632971252415927665424533188343048095703125 That’s three orders of magnitude—a thousand times—more precise than the double value of ⅓, which had only 16 threes in doubleArithmetic.

How much precision do we get from a fixed point number in the Celestia universe? The unit of distance is the microlightyear, equal to 9,460,730.4725808 kilometers (lightyear). The distance in kilometers between positions represented by consecutive fixed point values is therefore 1 · 2^–64 · 9,460,730.4725808 = 9,460,730.4725808 18,446,744,073,709,551,616 ≈ 5.12867226583596 · 10^–13 That’s 5.12867226583596 · 10^–10 meters, or a little more than half a nanometernanometer. (One nanometer equals 10^–9 meters.)

Units of Measurement

Celestia’s units range from pixels to parsecs. Pixels belong to real space; parsecs to simulation space. There are also units of angular distance, mass, time, temperature, and flux.

Units of Linear Distance

Lightyears and Microlightyears

The speed of lightlight, speed of is 299,792,458 meters per second. The number of meters in a lightyearlightyear is therefore 299,792,458 · 60 · 60 · 24 · 365.25 = 9,460,730,472,580,800 which works out to 9,460,730,472,580.8 kilometers or approximately .306601393785551 parsecs (parsec). When the number of kilometers is stored as a single precision floating point number (doubleArithmetic), it is rounded to 9,460,730,822,656. An example is the default value of Object:radius for a deep sky object.

The position of an observer or a celestial object is measured in microlightyearsmicrolightyear. A microlightyear is a millionth of a lightyear, a mere 9,460,730.4725808 kilometers. This number is stored in the predefined global variable KM_PER_MICROLYKM_PER_MICROLY (Celx variable), uppercase with underscores.

Astronomical Unitsastronomical unit

The average distance from the Sun to the Earth is called an astronomical unit. Celestia uses the value 149,597,870.7 kilometers in version/src/celengine/astro.h, available in the standard library as std.kmPerAustd.kmPerAu. It is equivalent to roughly 16 microlightyears (std.microlyPerAustd.microlyPerAu). Astronomical units are used in the .ssc files for the orbits of planets, asteroids, and comets, but not for the satellites of the planets.

Parsecsparsec

A parsec is the distance from the Sun to an object whose annual parallaxparallax is 1″ (one second) of arc. The angle is exaggerated in the following diagram. In terms of astronomical units, 1 parsec = 1 sinsine (trig function) 1″ au ≈ 206,264.806247905 au This works out to approximately 3.26156377790433 lightyears (std.lyPerPcstd.lyPerPc) or 30,856,775,821,885.3 kilometers (std.kmPerPcstd.kmPerPc).

To approximate a parsec without computing sine, recall that the graph of sine goes through the origin at a 45° angle.

Thus for a tiny angle of θ radians we have sin θ ≈ θ Our angle of 1″ is equal to 2π 360 · 60 · 60 radians so sin 1″ = sin ( 2π 360 · 60 · 60 radians) ≈ 2π 360 · 60 · 60 Therefore 1 parsec ≈ 360 · 60 · 60 2π au ≈ 206,264.806272689 au which is correct to 10 significant digits.

Ancient versions of Celestia had an origin one milliparsec (about 206 astronomical units) from the Sun; see universalFrame. The milliparsec still shows up when we press the Follow Earth button in a Celestia compiled --with-kdeKDE (K Desktop Environment).

Kilometerskilometer

Intraplanetary distances are in kilometers:

The radius of a spacecraft is in kilometers. Multiply it by 1000 to convert to meters.

The radius of a deep sky object (a galaxy, globular cluster, open cluster, or nebula) is available in kilometers or lightyears:

The distance between two objects is available in kilometers or microlightyears:

Kilometers are used for the distance argument of Observer:gotolonglat and Observer:gotodistance.

Pixelspixels in Real Space

Measurements in pixels belong to the domain of the real space of the user, not the simulation space of the observer (universalFrame). Celestia assumes that the screen has 96 pixels per inch (std.pixelsPerInstd.pixelsPerIn). The dimensions of the window are in pixels; see Celestia:getscreendimension (celestiaPrint and windowDimensions) and the resize Lua hook (luaHookFunctions). Together with the user’s default distance of 400 millimeters from the screen, these dimensions determine the user’s field of view in real space (std.getverticalfov and std.gethorizontalfov). With the observer’s level of magnification, we can then determine the observer’s field of view in simulation space (Observer:getverticalfov and Observer:gethorizontalfov). One inch, by the way, equals 25.4 millimeters (std.mmPerInstd.mmPerIn). One mile equals 5280 feet (std.ftPerMilestd.ftPerMile).

Fonts, strings, and marks are measured in pixels, not pointspoint (font size); see Celestia:gettextwidth, Font:getwidth, Font:getheight, and Object:mark.

Units of Angular Distance

Degrees, Minutes, and Seconds of Arc

One full turn is divided into 360 degreesdegree (of arc) of arc. Each degree is divided into 60 minutesminute (of arc), and each minute into 60 secondssecond (of arc). Thus, 1° = 60′ = 3600″ A milliarcsecond is a thousandth of second. Celestia uses degrees for the field of view in a cel: URL; see Celestia:geturl.

Hours, Minutes, and Seconds of Right Ascensionright ascension

The angle through which the Earth rotates during a given period of time may be described as 0 to 360 degrees, or as 0 to 24 hourshour (of right ascension) of right ascension. In this system, 24^h = 360°
  1^h =   15° Dividing both sides by 60, we see that a minuteminute (of right ascension) of right ascension is 15 times bigger than a minute of arc: 1^m = 15′ Another division by 60 shows that a secondsecond (of right ascension) of right ascension is 15 times bigger than a second of arc. 1^s = 15″

We also give another interpretation to right ascension, thinking of it as the angle through which the Universe rotates around a stationary Earth. See j2000Equatorial.

Radiansradian

An angle can also be measured in radians. One full turn is divided into 2π radians, so 2π radians = 360°

We use 2π because it is the circumference of the unit circle, whose radius is 1. The size in radians of an angle is equal to the length of the portion of the circumference that is subtended by the angle. For example, an angle of 2π radians goes all the way around the circumference.

ππ (mathematical constant) is approximately 3.14159265358979 and is available as math.pimath.pi. local circumference = math.pi * diameter

Here are the conversion factors, to 15 significant digits.

Lua provides two conversion functions.

All Lua trig functions are in radians.

Celx functions and fields are in radians too.

The Celx Standard Library functions (standard) are in radians.

Units of Time

See time for the difference between simulation time and real time. Simulation time is measured in Earth days, starting with the methods Celestia:gettime and Celestia:settime. This type of day is the mean solar daymean solar day of 24 hours, not the sidereal daysidereal day of 23 hours, 56 minutes, 4 seconds.

Intervals of real time are measured in seconds, starting with the return value of Celestia:getscripttime. A second is 1 60 · 60 · 24  =  1 86,400 of a day. The method Celestia:getsystemtime returns the current real time, not the length of an interval, so its return value is in days.

The dimensionlessdimensionless quantity ratio between simulation time and real time is manipulated with Celestia:gettimescale and Celestia:settimescale. See settime.

Units of Temperature

Temperature is measured in degrees KelvinKelvin (unit of temperature). To convert Kelvin to CelsiusCelsius (unit of temperature), subtract 273.15. To convert Celsius to Fahrenheit, multiply by 212 − 32 100 − 0  =  9 5 and add 32.

The temperature of a star can be read from the temperature field of the star’s info table. See infoTable. The temperature of a non-luminous body can be displayed when Celestia is set to verbose mode. On Macintosh,
Celestia → Preferences… → General → Info Display
On Microsoft Windows,
Render → View Options… → Information Text
Then select the body as in keystroke.

Miscellaneous Units

The luminosity field of the info table (infoTable) of a star is measured in multiples of the Sun’s luminositySun, luminosity of. This value is 3.8462 · 10²⁶ watts in version/src/celengine/astro.cpp.

The mass field of the info table of an extrasolar planetextrasolar planet is measured in multiples of the mass of the EarthEarth, mass of. This value is 5.976 · 10²⁴ kilograms in version/src/celengine/astro.cpp. JupiterJupiter, mass of, to which extrasolar planets are often compared, is approximately 318 times as massive as the Earth.

The atmosphereCloudSpeed field of the info table of a planet or moon is measured in radians per day. (The corresponding field in a .ssc file is in degrees per day.) The argument of Observer:setspeed is in microlightyears per second of real time. The fifth argument of Celestia:print is in emsem (unit of width) (the width of an uppercase letter M).

Some measurements are dimensionlessdimensionless quantity because they are the ratios of two measurements with the same units. These include the albedo and oblateness fields of the info table, the timescale between the simulation time and the real time, the Eccentricity field of an EllipticalOrbit in data/solarsys.ssc, the magnification passed to Observer:setmagnification in Magnification, and the Rayleigh, absorption, and Mie coefficients passed to Object:setatmosphere. A mathematical purist would also say that an angle in radiansradian is dimensionless.

Some measurements are downright subjective. Consider the importance field of the info table of a location: is the second most important world capital really SeoulSeoul, South Korea?

Formattingformatting Numbers and Strings

Formatting a value means rendering it as a humanly-readable string of characters. For example, an integer (whole number) can be formatted in decimal or hexadecimal, and any number can be formatted in scientific notation or in the plain old notation. a string can be left or right justified. A date or time can be formatted as in tdb. For colors, see integerFormatting.

Numeric Formatting

This section assume that we have a normal Celx number. To print a fixed point number in a Position object, see bits128.

The Default Format

By default, a number is converted into a string with 14 significant decimal digits. The conversion can be performed in two ways: explicitly, by the Lua function tostringtostring (Lua function); or implicitly, by concatenation to an existing string. The existing string can even be the null string "".

--[[
Demonstrate the default format (14 significant digits)
in which a number is rendered as a string.
]]
require("std")

local function main()
	--Keep the Sun in view, but get away from its glare.
	local observer = celestia:sane()
	observer:setposition(std.position)

	local n = 1234567890.12345	--15 significant decimal digits
	local explicit = tostring(n)	--explicit conversion to string
	local implicit = n .. ""	--implicit conversion to string

	celestia:print(explicit .. "\n" .. implicit, 60)
	wait()
end

main()

These 14 digits are one less than the 15 digits guaranteed by a double in doubleArithmetic. The culprit is the “number format” macro in the header file luaversion/src/luaconf.hluaconf.h (header file).

Explicit Formatting with string.format

The Lua function string.formatstring.format gives us control over how a number is formatted. For example, it can wring out all 15 significant digits of a double, or round the double to fewer decimal places. The function accepts the same % formats% format (string.format) as the C function printfprintf (C function).

Integer Formatting

Let’s start with the integers. The format %d prints in decimal. An optional number before the %d specifies the minimum number of characters to be output; a narrower number will be padded with leading blanks or a zeroes.

The format %d prints a negative number with a minus sign, but a positive number with no plus sign. To print every value with an explicit sign, use %+d. (Zero will have a plus sign.)

Print an integer in base 10 with %d, in base 8 with %o, and in base 16 with %X or %x (upper or lowercase).

The format %u stands for “unsigned”unsigned number. It prints an integer in base 10, adding 2³¹ = 2,147,483,648 if necessary to make the integer nonnegative. See inputFile.

The %d cannot be used for an integer greater than or equal to 2³¹ = 2,147,483,648 or less than –2³¹ = –2,147,483,648. An integer in the range 2³¹ to 2³² − 1 = 4,294,967,296 inclusive can be formatted with %u, %o, %X, or %x. An integer greater than or equal to 2³¹ can a be formatted as a float (floatFormat) with no digits to the right of the decimal point.

Floating Point Formatting

The format %f prints a number with a fraction, by default with six digits to the right of the decimal point. A number before the %f specifies the minimum number of characters to be output. The number after the dot specifies the number of digits to the right of the decimal point.

The format %e delivers scientific notation, by default with six digits to the right of the decimal point.

The format %g behaves like %e or %f, depending on the magnitude of the value. The number after the dot specifies the total number of significant digits to be printed. To print the entire value, with no advance knowledge of its magnitude, your best bet is %.15g.

String Formatting

Format a string of characters with %s.

To add quotesquotes around string to the string, see the %q in standard.

Special Charactersspecial characters

Astronomical writing is full of special characters, starting with the symbols for degrees, minutes, and seconds: 1° 2′ 3″. Although it might be possible to write these characters in the source code of a Celx program, such usage is platform dependent. A portable way to represent a special character is via its UnicodeUnicode character number in the code charts at www.unicode.org. For example, the code number of the degree symbol ° is 176 in decimal and 00B0 in hexadecimal. To display the code number of every character in a font, see inputFile

A Unicode number is written as a four-digit hexadecimal number, with a leading 0x (zero lowercase X) in Celx to indicate its base. To print the corresponding character, the number must be broken down into a series of 8-bit bytes in UTF-8UTF-8 (character encoding) format, and then pasted back together with the Lua function string.charstring.char. For example, the following 0x03B1 (the code number of the lowercase Greek letter α) must be broken into 0xCE and 0xB1 before it can be reconstituted as a one-character string.

An easy way to convert a Unicode number into a one-character string is with the function std.utf8std.utf8. Even easier, the table std.charstd.char contains fields for the most common special characters.

--[[
Print a special character.
]]
require("std")

local function main()
	--Keep the Sun in view, but get away from its glare.
	local observer = celestia:sane()
	observer:setposition(std.position)

	--Three ways to print Greek lowercase alpha (Unicode 03B1).

	local s = string.char(0xCE, 0xB1) .. "\n"	--hard
		.. std.utf8(0x03B1) .. "\n"		--easier
		.. std.char.alpha .. "\n"		--easiest

		.. std.char.alpha .. " Orionis (Betelgeuse), Declination "
		..  7 .. std.char.degree .. " "
		.. 24 .. std.char.minute .. " "
		.. 25 .. std.char.second .. " North"

	local duration = 60
	celestia:print(s, duration)
	wait(duration)
end

main()

The string can also be composed with string:format (stringFormat).

Data Structures: Objects, Tables, and Databases

Lua Objects, Celx Objects, and Celestial Objects

A Celx variable can refer to an object, as we saw in objectsVsVariables. These objects fall into two groups. A Lua objectLua object is inherited from the language Lua and represents a computer science concept such as a string or an array. A Celx objectCelx object is unique to Celx and represents a mathematical or astronomical concept such as a vector or a planet. To tell them apart, call the Lua function typetype (Lua function).

A Celx object belongs to one of the twelve classesclass of Celx object in additions. Call the Lua function tostringtostring (Lua function) to find out which one.

The name of the class begins with an uppercase letter. We will ignore the [square brackets].

A Celx object belonging to class Object (i.e., class "[Object]") represents a celestial object such as a planet, spacecraft, or even a city or crater. To get a celestial object from one of Celestia’s databases, call the method Celestia:findCelestia:find with an argument such as one of the following. The argument is case-insensitive, but any chunk of whitespace in the argument must consist of exactly one space.

Celestia:find returns a Celx object of class Object. The method Object:name returns the rightmost segment of the object’s name (e.g., the "Moon" of "/Sol/Earth/Moon"), excluding the slashes and the characters to the left of any slash. The method Object:typeObject:type returns a string giving the object’s astronomical classification, such as "planet", "star", or "comet".

If Celestia:find cannot find the celestial object, its behavior will depend on whether the standard library has been required. If the library has been required, Celestia:find will call the Lua function errorerror (Lua function) with the message “Celestia:find could not find "<name>"”. And as we know, error never returns. If the library has not been required, Celestia:find will return a dummy object whose name and type are the strings "?" and "null" respectively. (If the library has been required, and a dummy object is desired as the result of an unsuccessful search, call Celestia:oldfind.)

Every celestial object has an “info table” of information (infoTable) The object’s name and type are also present as fields in the info table. The dummy object has an info table with no name field, and a type field whose value is the string "null".

By default, a goto takes five seconds of real time, available as the constant std.duration. To ensure that nothing else happens while the goto is in progress, we can wait (wait) for the same number of seconds.

--[[
Find a celestial object in Celestia's database.
]]
require("std")

local function main()
	--Keep the Sun in view, but get away from its glare.
	local observer = celestia:sane()
	observer:setposition(std.position)

	local name = "Sol/Mars"
	local object = celestia:find(name)

	--This is the check that Celestia:find does for us automatically,
	--since we required std.
	--[[
	if type(object) ~= "userdata"
		or tostring(object) ~= "[Object]"
		or object:type() == "null"
		or object:name() == "?" then
		error("Celestia:find could not find \"" .. name .. "\"")
	end
	]]

	celestia:select(object)			--display distance, radius, etc.

	local s = string.format(
		"type(object) = %s\n"
		.. "tostring(object) = %s\n"
		.. "object:name() = %s\n"
		.. "object:type() = %s\n",
		type(object), tostring(object),
		object:name(), object:type())

	celestia:print(s, 60, -1, 1, 1, -6)	--below selected object info
	observer:goto(object)	--go to a point 5 radii from the object's center
	wait(std.duration)	--the number of seconds that the goto takes
end

main()

We have just seen two types: the Lua function type and the type method of class Object. There is also a Lua function named typeio.type that checks if a file is currently open (inputFile), and a field named type in a celestial object’s info table (infoTable) and in the table passed to the method Object:addreferencemark.

An Array of Strings

Lua’s only data structure is the tabletable (Lua), an associative array or hash of key/value pairskey/value pair. We look up a key in a table to find the corresponding value. The following table is named zodiac. Its keys are not explicitly specified, so they default to increasing consecutive integers starting at 1. A table with these keys is called an arrayarray (Lua table) or a sequencesequence (Lua table); see the Lua documentation for the fine points. The operator ## (highest key operator) returns the highest key in the array, which is the number of key/value pairs. (In Lua 5.2, this operator has replaced the function table.maxn.) The value corresponding to each key in the following table is a string.

There are two ways to loop through an array: with a numeric for loopfor loop, or with a generic for loop and the Lua function ipairsipairs (Lua function). The generic loop calls ipairs once. The return value is another function, called an iteratoriterator. We never see this iterator, but it is called over and over by the loop. Each call returns the next key/value pair from the array. When a call returns nilnil (Lua value), the loop terminates.

The first three arguments of Celestia:setconstellationcolorCelestia:setconstellationcolor are the red, green, and blue components of the color, in the range 0 to 1. We’ll use the rgb values in the Renderer::EclipticColorRenderer::EclipticColor (C++ constant) in version/src/celengine/render.cpp. The optional fourth argument is an array of constellation names.

--[[
Create and print an array of strings.
]]
require("std")

local function main()
	--Keep the Sun in view, but get away from its glare.
	local observer = celestia:sane()
	observer:setposition(std.position)

	local zodiac = {	--Curly braces create a table.
		"Aries",	--Key is 1, value is "Aries".
		"Taurus",	--Key is 2, value is "Taurus".
		"Gemini",
		"Cancer",
		"Leo",
		"Virgo",
		"Libra",
		"Scorpius",
		"Sagittarius",
		"Capricornus",
		"Aquarius",
		"Pisces"	--Key is 12, value is "Pisces".
	}

	assert(type(zodiac) == "table" and #zodiac == 12)

	local s = string.format(
		"The zodiac has %d constellations, from %s to %s:\n\n",
		#zodiac,
		zodiac[1][ ] (subscripting operator),        --Look up first key & get corresponding value.
		zodiac[#zodiac])  --Look up last key & get corresponding value.

	--Two ways to do the same loop.

	--numeric for loop
	for i = 1, #zodiac do
		s = s .. i .. " " .. zodiac[i] .. "\n"
	end

	s = s .. "\n"	--Skip a line between the two lists.

	--generic for loop
	assert(type(ipairs) == "function")
	assert(type(ipairs(zodiac)) == "function") --An iterator is a function.

	for i, value in ipairs(zodiac) do
		s = s .. i .. " " .. value .. "\n"
	end

	celestia:setconstellationcolor(.5, .1, .1, zodiac)	--rgb
	celestia:print(s, 60, -1, 1, 1, -1)	--upper left corner of window
	wait()
end

main()

An Array of Celestial Objects

The keys in the next array are still integers, but now the values are celestial objects.

Human beings like to see their numbers right justified and their strings left justified. A positive width such as %2d will right justify, and a negative width such as %-9s will left justify. Of course, the columns will line up only if the font is monospace.

--[[
Print a table of celestial objects: the moons of NeptuneNeptuneNeptune
]]
require("std")

local function main()
	--Keep the Sun in view, but get away from its glare.
	local observer = celestia:sane()
	observer:setposition(std.position)

	local neptune = celestia:find("Sol/Neptune")
	local children = neptune:getchildren()	--an array of celestial objects
	assert(type(children) == "table")

	local s = ""

	for i, child in ipairs(children) do
		assert(type(child) == "userdata"
			and tostring(child) == "[Object]")

		s = s .. string.format("%2d %-9s %6.1f (%s)\n",
			i, child:name(), child:radius(), child:type())
	end

	celestia:print(s, 60, -1, 1, 1, -1)	--upper left corner of window
	wait()
end

main()

GalateaGalatea (moon of Uranus) is a minor moon even though it’s bigger than LarissaLarissa. See the comment at the start of data/solarsys.sscsolarsys.ssc (file).

Recursionrecursion: a Tree of Celestial Objects

A recursive data structure contains subparts with the same structure as the whole. An example is the family tree of the Sun, containing trees within trees within trees. The simplest way to traverse a recursive data structure is with a recursive function, one that calls itself.

Let’s write a recursive function that will print the entire tree rooted at the Sun, one object per line. The planets will be indented by one pair of spaces, their satellites by two pairs of spaces, and the satellites of the satellites by three pairs of spaces. The pair of spaces is written as a string literalliteral (a value in double quotes: "  "). To make the literal count as an object with methods, we have to enclose it in parentheses. To create multiple copies of this object, we call the Lua method string.repstring.rep (“replicate”).

Celestia:print will print no more than 2¹⁰ − 1 = 1023 characters of a string; see celestiaPrint. The string:substring.sub method returns a prefix of this length. To see the entire string, we can print it to the standard output (standardOutput), to an output file (outputFile), or to the Celestia console (console). In the latter case, we must set the LogSizeLogSize (parameter in celestia.cfg) in celestia.cfg to at least 222.

Another recursive function is the gcd (greatest common divisor) in windowDimensions.

--[[
This function displays the tree of celestial objects whose root is the first
argument.  The root is indented by level pairs of blanks.  Its children are
indented by level+1 pairs, its children's children by level+2 pairs, etc.
]]
require("std")

local function tree(root, level)
	assert(type(root) == "userdata" and tostring(root) == "[Object]"
		and type(level) == "number" and level >= 0
		and math.floor(level) == level)	--level is an integer

	local s = ("  "):repstring.rep(level) .. root:name() .. " (" .. root:type() .. ")"
	local children = root:getchildren()

	if #children == 0 then		--The array of children is empty.
		s = s .. "\n"
	else
		s = s .. " has " .. #children .. " satellite"
		if #children > 1 then
			s = s .. "s"	--plural
		end
		s = s .. ":\n"

		for i, child in ipairs(children) do
			s = s .. tree(child, level + 1)
		end
	end

	return s
end

local function main()
	--Keep the Sun in view, but get away from its glare.
	local observer = celestia:sane()
	observer:setposition(std.position)

	local sol = celestia:find("Sol")
	local s = tree(sol, 0)
	celestia:print(s:sub(1, 2^10 - 1), 60, -1, 1, 1, -1) --upper left
	wait()
end

main()

The indentation shows who belongs to whom:

A simpler way to perform the same traversal is with standard library method Object:familyObject:family. It returns an iterator which can be called over and over by a generic for loop, with each call returning a different celestial object. When the iterator returns nilnil (Lua value), the loop terminates. The level tells how far the object is located down the tree; the root is at level 0. The output is the same as in the previous example.

--[[
Traverse (in "preorder") the tree of celestial objects whose root is Sol.
]]
require("std")

local function main()
	--Keep the Sun in view, but get away from its glare.
	local observer = celestia:sane()
	observer:setposition(std.position)
	local s = ""

	for level, object in celestia:find("Sol"):family() do
		s = s .. ("  "):rep(level) .. object:name()
			.. " (" .. object:type() .. ")"

		local n = #object:getchildren()
		if n > 0 then
			s = s .. " has " .. n .. " satellite"
			if n > 1 then
				s = s .. "s"	--plural
			end
			s = s .. ":"
		end
		s = s .. "\n"
	end

	celestia:print(s:sub(1, 2^10 - 1), 60, -1, 1, 1, -1) --upper left
	wait()
end

main()

A Table of Fields

The keys of a table do not have to be integral, positive, or even numeric. For example, the keys of the following table are the strings "Aries", "Taurus", "Gemini", etc. A key/value pair whose key is a string is called a fieldfield (of table).

The first three fields are created without writing anything around the key. We can do this only if the key is a string that is a valid Lua variable name. The last three fields have keys that are not valid names. They are disqualified by the embedded blank in "Ursa Major", the leading digit in "4nax", and the special character ö in "Boötes". (The diaeresis may not be portable, and I don’t want to risk it. See specialCharacters for special characters.) If the key is not a valid name, it must be surrounded with [square brackets]. If the key is a string, it must also be surrounded with "double quotes".

A value can be accessed with a dot. (field operator) if its key is a valid Lua variable name; see epithet.Aries. The value must be accessed with square brackets if the key is not a valid name; see epithet["Ursa Major"].

We can loop through the fields of a table with the Lua function pairspairs (Lua function). Warning: the loop is guaranteed to visit every field in the table, but the order in which they will be visited is impossible to predict.

--[[
Loop through a table of fields (i.e., a table that is not an array)
with the function pairs.
]]
require("std")

local function main()
	--Keep the Sun in view, but get away from its glare.
	local observer = celestia:sane()
	observer:setposition(std.position)

	local epithet = {
		Aries = "Ram",		--"Aries" is the key, "Ram" is the value
		Taurus = "Bull",
		Gemini = "Twins",
		["Ursa Major"] = "Great Bear",  --"Ursa Major" is the key
		["4nax"] = "Furnace",
		["Bo" .. std.char.ouml .. "tes"] = "Herdsman"
	}

	local s = "Aries is the " .. epithet.Aries .. ".\n"
		.. "Ursa Major is the " .. epithet["Ursa Major"] .. ".\n\n"

	for key, value in pairs(epithet) do
		s = s .. key .. " the " .. value .. "\n"
	end

	celestia:print(s, 60, -1, 1, 1, -1)
	wait()
end

main()

The Info Tableinfo table

Each celestial object has a read-only table of fields called the info table. The table’s set of keys depends on the type of the object: a planet has an albedo, a star has a stellarClass, and a galaxy has a hubbleType. The corresponding values come from the database and catalogs files listed in the configuration file celestia.cfgcelestia.cfg (configuration file). The values are of many data types: name is a string, hasRings is a boolean, and parent is a celestial object or nil. A value that is neither a string nor a number must be explicitly converted tostring before it can be concatenatedconcatenation to another string with the .... (concatenation operator) operator. Just to be safe, we will convert all of them to strings.

The name, type, and radius fields of the info table have the same values as the name, type, and radius methods of class Object. (With one caveat. The radius method is always in kilometers. The radius field is in lightyears for deep sky objectsdeep sky object, and in kilometers for everything else.) The radius field of a planet is the equatorial radius, not the polar radius.

The height fields of the info table are in kilometers. The periods are in Earth days, even for comets. The atmosphereCloudSpeed is in radians per day, even though the CloudSpeed in data/solarsys.ssc is in degrees per day. Temperatures are in Kelvin (temperatureDistance), masses are in multiples of the Earth’s mass (miscDistance), and the lifespan endpoints are in TDB time (tdb). The infinitiesinfinity are formatted differently on each platform (inf on Mac and Linux, 1.#INF on Microsoft Windows) and are not to be taken as an endorsement of the Steady State theorySteady State theory (cosmology).

--[[
Display an object's info table.
]]
require("std")

local function main()
	--Keep the Sun in view, but get away from its glare.
	local observer = celestia:sane()
	observer:setposition(std.position)

	local object = celestia:find("Sol/Earth")
	local info = object:getinfo()
	assert(type(info) == "table")
	local s = ""

	for key, value in pairs(info) do
		s = s .. key .. " "

		if type(value) == "userdata" and tostring(value) == "[Object]"
			then
			s = s .. value:name()
		else
			s = s .. tostring(value)
		end

		s = s .. "\n"
	end

	celestia:print(s, 60, -1, 1, 1, -1)	--upper left corner of window
	wait()
end

main()

The Stefan-Boltzmann LawStefan-Boltzmann law

This section illustrates a few applications of the info table. We will read the albedo and parent fields of a planet, and the bolometricMagnitude and temperature fields of a star.

The Stefan–Boltzmann Law says that when a body’s temperature is doubled, the outflow of energy through its surface is multiplied by a factor of 16. The exact statement of the law is S = σT⁴ where T is the temperature in Kelvin, S is the outward flux in wattswatt per square meter, and σσ (Stefan-Boltzmann constant) is the Stefan–Boltzmann constantStefan-Boltzmann constant with a value of 5.670372 · 10^–8 Wm^–2 K^–4. For big objects, we will work with square kilometers instead of square meters. The σ, by the way, is the Greek lowercase letter sigma. It’s in the Celx standard library as std.char.sigma.

The Renderflagsrenderflags

The renderflags are a table of read/write boolean values that determine what features of the Universe are rendered. These include celestial objects such as planets and galaxies, reference lines such as grids and orbits, and rendering styles such as smoothlines and automag. See Object:setorbitvisibilityObject:setorbitvisibility for the complicated interactionorbit visibility between the renderflags and the orbitflags.

Let’s turn the flags off, sit in the dark for a few seconds, and restore them on exit with celestia_cleanup_callbackcelestia_cleanup_callback (function) (callback). See hertzsprungrussell for an example where we actually do turn off all the renderflags. The callback function uses the local variable save, so it would make no sense for the function to outlive this variable. But a callback has to be nonlocal.

--[[
Set the renderflags to sane values and print them.
Then turn them all off, wait in the dark for a few seconds,
and restore them to their sane values.
]]
require("std")

--Variables used by more than one function.
local save = {}		--Create an empty table.
local duration = 10	--seconds of real time

local function printFlags()
	local s = ""
	for key, value in pairs(celestia:getrenderflags()) do
		s = s .. key .. " " .. tostring(value) .. "\n"
	end
	return s
end

function celestia_cleanup_callback()		--can't be local
	--Restore the original flags.
	celestia:setrenderflags(save)
	celestia:print("Back to sane renderflags:\n" .. printFlags(),
		duration, -1, 1, 1, -1)
	wait(duration)
	celestia_cleanup_callback = nil		--Destroy this function.
end

local function main()
	local observer = celestia:sane()	--Changes the renderflags.
	observer:setposition(std.position)

	--Save the flags.
	local flags = celestia:getrenderflags()
	for key, value in pairs(flags) do
		save[key] = value
	end

	celestia:print("Renderflags set by Celestia:sane:\n" .. printFlags(),
		duration, -1, 1, 1, -1)
	wait(duration)

	--Turn off all the flags.  Sit in darkness for duration seconds.
	for key, value in pairs(flags) do
		flags[key] = false
	end
	celestia:setrenderflags(flags)

	celestia:print("Renderflags off:\n" .. printFlags(),
		duration, -1, 1, 1, -1)
	wait(duration)
end

main()

Here are the values set by Celestia:saneCelestia:sane, alphabetized for your convenience.

Test if a Key Exists

The special value nilnil (Lua value) can never be the value—or the key—of any field in a table. To test if a key exists, it therefore suffices to check if the corresponding value is nil. The following example loops through all the ancestors of a celestial object. The loop will keep going as long as there is a key named parent in the info table of the current object. See Object:pathname.

--[[
Loop through all the ancestors of an object.  Print them one per line.
]]
require("std")

local function main()
	--Keep the Sun in view, but get away from its glare.
	local observer = celestia:sane()
	observer:setposition(std.position)

	local object = celestia:find("Sol/Earth/Moon/Tycho")
	local s = object:name() .. " and its ancestors are\n"
	local i = 0

	repeat
		i = i + 1
		local info = object:getinfo()
		local type = object:type()
		if type == "location" then
			type = type .. ", " .. info.featureType
		elseif type == "star" then
			type = type .. ", " .. info.stellarClass
		end
		s = s .. string.format("%d %s (%s)\n", i, info.name, type)
		object = info.parent
	until object == nil

	local duration = 60
	celestia:print(s, duration, -1, 0, 1, 0)
	wait(duration)
end

main()

Loop Through a Database

Celestia comes with a database of a hundred thousand stars, including miscellaneous objects such as neutron stars and the barycenters of stellar systems. We can loop through the database with the iterator returned by Celestia:starsCelestia:stars.

The ArabicArabic language word for “head” is رأس (ra’s). Let’s find every star that’s a head. The following [Rr] is a wildcardwildcard (in pattern) that looks for an upper or lowercase letter R. A wildcard is a simple example of a patternpattern (Lua).

--[[
List the stars that are heads ("ras" in Arabic).
]]
require("std")

local function main()
	--Keep the Sun in view, but get away from its glare.
	local observer = celestia:sane()
	observer:setposition(std.position)
	wait()	--Render a view for the user to watch during the long loop.
	local s = ""

	--The method Celestia:stars returns an iterator.
	assert(type(celestia.stars) == "function"
		and type(celestia:stars()) == "function")

	for star in celestia:stars() do
		assert(type(star) == "userdata"
			and tostring(star) == "[Object]"
			and star:type() == "star")

		--If it's really a star,
		--and not the barycenter of a stellar system,
		if star:getinfo().stellarClass ~= "Bary" then

			local name = star:name()
			if name:findstring.find("[Rr]as") then	--"head (of)" in Arabic
				s = s .. name .. "\n"
			end
		end
	end

	celestia:print(s, 60, -1, 1, 1, -1)
	wait()
end

main()

Comments are in parentheses.

The Hertzsprung-Russell DiagramHertzsprung-Russel diagram

This section uses Celestia’s database of stars to construct the Hertzsprung-Russell diagram, which plots each star as a point in a two-dimensional space. The origin is in the lower right corner. The horizontal axis is the star’s temperature, increasing from right to left. The vertical axis is the star’s luminosity, increasing from bottom to top. The majority of stars lie along a diagonal line, called the main sequencemain sequence (of stars), from the lower right (cool and dim) to the upper left (hot and bright). An arm of giant starsgiant star extends to the upper right (cool and bright, hence very big).

Values in the diagram are plotted logarithmicallylogarithm: when we double the temperature, we always move to the left by the same distance. Thus the horizontal distance from 3,000 to 6,000 Kelvin is equal to the distance from 6,000 to 12,000 Kelvin.

If the star’s temperature is in the range 10^{self.logMinTemp} = 2,500 Kelvin to 10^{self.logMaxTemp} = 50,000 Kelvin inclusive, then the log₁₀ of its temperature will be in the range self.logMinTemp to self.logMaxTemp inclusive. The size of this range is self.rangeTemp. The expression               (math.log10(info.temperature) - self.logMinTemp) / self.rangeTemp will be a fraction in the range 0 to 1 inclusive. And the expression -self.width * (math.log10(info.temperature) - self.logMinTemp) / self.rangeTemp will be a distance in pixels in the range 0 to negative the width of the window, inclusive. (We want negative because the origin is in the lower right. A point to the left of the origin will have a negative x coördinate.) Luminosity is plotted similarly. Warning: the function math.log10 is no longer present in Lua 5.2.

The array self.a contains more than one hundred thousand values. Each value is an array of two numbers giving a star’s horizontal and vertical position in pixels measured from an origin at the lower right corner of the Celestia window. Depending on the speed of your machine, it might take several seconds to create self.a. This is a problem because a Celx program must call the waitwait function (wait) at least once every five seconds, and a call to wait inside a Lua hook never returns. Our solution is to increase the five-second limit by calling Celestia:settimesliceCelestia:settimeslice. When the entire database has been read into self.a, the tick hook wipes itself out by saying self.tick = nil.

--[[
This file is luahook.celx.
Plot the Hertzsprung-Russell diagram, featuring the main sequence of stars.
]]

celestia:setluahook {
	width = nil,		--of window, in pixels
	height = nil,
	a = {},			--array of stars, not including barycenters

	--logs of surface temperature in Kelvin
	logMinTemp = math.log10(2.5e3),	--coolest, right edge of window
	logMaxTemp = math.log10(5e4),	--hottest, left edge of window
	rangeTemp = nil,

	--logs of luminosity in multiples of Sol's
	logMinLum = math.log10(3e-4),	--dimmest, bottom edge of window
	logMaxLum = math.log10(2e4),	--brightest top edge of window
	rangeLum = nil,

	--Return the x, y coordinates in pixels of the given point,
	--measured from an origin in the lower right corner of the window.

	coordinates = function(self, temperature, luminosity)
		return -self.width
			* (math.log10(temperature) - self.logMinTemp)
			/ self.rangeTemp,

			self.height
			* (math.log10(luminosity) - self.logMinLum)
			/ self.rangeLum
	end,

	tick = function(self)
		self.tick = nil	--No need to call this hook more than once.
		require("std")
		self.rangeTemp = self.logMaxTemp - self.logMinTemp
		self.rangeLum = self.logMaxLum - self.logMinLum
		self.width, self.height = celestia:getscreendimension()

		celestia:settimeslice(10) --Ask for even more seconds if needed.
		for star in celestia:stars() do
			local info = star:getinfo()
			if info.stellarClass ~= "Bary" then
				table.insert(self.a, {self:coordinates(
					info.temperature, info.luminosity)})
			end
		end
		celestia:settimeslice(5)	--Restore the default.
	end,

	renderoverlay = function(self)
		gl.MatrixMode(gl.PROJECTION)
		gl.PushMatrix()
		gl.LoadIdentity()

		--dimensions of the Celestia window, in pixels
		local width, height = celestia:getscreendimension()
		glu.Ortho2D(0, width, 0, height)   --left, right, bottom, top

		gl.MatrixMode(gl.MODELVIEW)
		gl.PushMatrix()
		gl.LoadIdentity()

		--The default origin (0, 0) is at the lower left corner of the
		--window.  Move the origin to the lower right corner.
		gl.Translate(width, 0)

		gl.Enable(gl.BLEND)
		gl.BlendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA)
		gl.Disable(gl.LIGHTING)	--Make text and graphics self-luminous.
		gl.Disable(gl.TEXTURE_2D)	--disabled for graphics
		gl.Color(1, 1, 1, 1)		--red, green, blue, alpha

		gl.Begin(gl.POINTS)		--isolated points
		for i, value in ipairs(self.a) do
			gl.Vertex(value[1], value[2])
		end
		gl.End()

		--Yellow square around Sol.
		gl.Color(1, 1, 0, 1)
		local size = 2
		local info = celestia:find("Sol"):getinfo()

		local solX, solY =
			self:coordinates(info.temperature, info.luminosity)

		gl.Begin(gl.LINE_LOOP)			--connected lines
		gl.Vertex(solX + size, solY - size)	--lower right corner
		gl.Vertex(solX + size, solY + size)	--upper right
		gl.Vertex(solX - size, solY + size)	--upper left
		gl.Vertex(solX - size, solY - size)	--lower left
		gl.End()

		gl.MatrixMode(gl.MODELVIEW)
		gl.PopMatrix()

		gl.MatrixMode(gl.PROJECTION)
		gl.PopMatrix()
	end
}

--[[
Provide a black background for the OpenGL graphics.  Turn off all the flags.
]]
require("std")

local function main()
	celestia:sane()

	local flags = celestia:getrenderflags()
	for key, value in pairs(flags) do
		flags[key] = false
	end
	celestia:setrenderflags(flags)

	flags = celestia:getlabelflags()
	for key, value in pairs(flags) do
		flags[key] = false
	end
	celestia:setlabelflags(flags)

	flags = celestia:getoverlayelements()
	for key, value in pairs(flags) do
		flags[key] = false
	end
	celestia:setoverlayelements(flags)

	--No need to face away from the Sun: the Sun is not being rendered.
	wait()
end

main()

Create your own Iteratoriterator

We have seen five functions that return an iterator: ipairs (arrayOfStrings), pairs (tableOfFields), Object:locations (infoTable), Celestia:stars (loopDatabase), and Celestia:dsos (loopDatabase). Now let’s write our own function that returns an iterator.

The signs in the following program is clearly a function. What is surprising is that signs()—the return value of signs—is also a function. Since the latter function has no name we refer to it as an anonymous functionanonymous function. The anonymous function is called over and over by the generic for loop. Each call returns the next value in a series of values, or nilnil (Lua value) when the series is exhausted. The nil breaks us out of the loop. A function used in this way is referred to as an iterator.

The iterator is created inside the function signs. This allows the iterator mention the local variable(s) of signs, in this case i.

Our simple program calls signs only twice: in the assertion and at the start of the for loop. A more complicated program might call signs many times. Since signs creates and returns a new iterator each time it is called, we say that signs is a factory functionfactory function. A call to the factory creates more than just another copy of the iterator. It also creates another copy of the local variable(s), in this case i, for use by the iterator. Since each iterator has its own copy of i, we could have more than one iterator traversing the array at the same time.

--[[
Create an iterator for looping through a table.
]]
require("std")

local signsTable = {
	"Aries",
	"Taurus",
	"Gemini",
	"Cancer",
	"Leo",
	"Virgo"
}

local function signs()
	local i = 0		--the first key, minus 1

	--Create an iterator and return it.
	--The iterator is an anonymous function.

	return function()
		i = i + 1
		if i <= #signsTable then
			--The iterator returns a pair of values.
			return i, signsTable[i]
		end
	end
end

local function main()
	--Keep the Sun in view, but get away from its glare.
	local observer = celestia:sane()
	observer:setposition(std.position)

	local s = ""
	assert(type(signs) == "function" and type(signs()) == "function")

	--i and sign are the two values returned by each call to the iterator.
	for i, sign in signs() do
		s = s .. i .. " " .. sign .. "\n"
	end

	celestia:print(s, 60, -1, 1, 1, -1)
	wait()
end

main()

Types of Timetime

Simulation timesimulation time is the time that passes in the Celestia universe. It can be “get” and “set” with Celestia:gettime and settime, and speeded up, slowed down, halted, or reversed with Celestia:settimescale. Simulation time is measured in Earth days. Examples include the time fields of a celestial object’s info table (infoTable): rotationPeriod, orbitPeriod, lifespanStart, and lifespanEnd. The atmosphereCloudSpeed is in radians per day.

Real timereal time is the time that passes in the universe of the user sitting in front of the Celestia application. It cannot be set or accelerated—we just have to wait for it to pass. The current real time is returned by Celestia:getsystemtime and the Lua functions os.date and os.time. Intervals of real time are measured in seconds. For example, Celestia:getscripttime returns the number of seconds of real time since the Celx script started running, and the argument of wait specifies how many seconds until the script runs again. The standard library constants std.logo and std.duration are in seconds of real time. So are the time arguments and return value of the following functions.

1. Waiting functions: wait and Celestia:settimeslice
2. Printing methods: Celestia:print, flash, mmprint
3. Goto methods: Observer:goto, gotodistance, gotolocation, gotolonglat, gotosurface, center, centerorbit
4. Speed methods: Observer:setspeed and getspeed, in microlightyears per second of real time
5. Event functions: the tick handler (tickHandler) and the tick Lua hook (luaHookFunctions).

Real Timereal time

The current real time is returned by the method Celestia:getsystemtimeCelestia:getsystemtime in UTCUTC (Coördinated Universal Time), i.e., Greenwich Mean Time. The return value is updated only once per second. (The fractional part of the current second is chopped off by the C language castcast (C language) (int) in the member function astro::Date::systemDate in version/src/celengine/astro.cpp.) The return value is one big number called a Julian dateJulian date, giving the number of days that have elapsed since noon on Monday, January 1, 4713 B.C. The Julian date is currently up in the two millions and climbing, and can include a fraction.

The method Celestia:tdbtoutcCelestia:tdbtoutc breaks out a Julian date into a table with six humanly readable fields: year, month, day, hour, minute, seconds. The first five fields are integers. The last field can have a fraction, which we can chop off with math.floor or round with std.round. The month numbers range from 1 to 12 inclusive, the hours from 0 to 23 inclusive. The following program formats the hours, minutes, and seconds as two-digit numbers, with a leading zero if necessary.

The Lua function os.dateos.date can return the current real time in UTC or the local time zone. It accepts the same % formats% format (os.date) as the C function strftimestrftime (C function). For example, %z is our zone’s number of hours and minutes ahead of UTC. The return vaue is a humanly-readable string.

Three warnings. (1) The table returned by Celestia:tdbtoutc does not have the same field names as the tables passed to os.timeos.time and returned by os.date. (2) The table returned by Celestia:tdbtoutc is in UTC, while the table passed to os.time is in local time. (3) If your times are about 66 seconds ahead of where they should be, you have probably called Celestia:fromjulianday instead of Celestia:tdbtoutc. See stepThrough.

--[[
Display the current real time in UTC and the local time zone,
updated every second.  Microsoft Windows doesn't have the %z format.
]]
require("std")

local function tickHandler()
	local tdb = celestia:getsystemtime()   --tdb is the current Julian date.
	assert(type(tdb) == "number")
	local utc = celestia:tdbtoutc(tdb)
	assert(type(utc) == "table")

	local s = string.format(
		"Real Time:\n"
		.. "%.15g\n"
		.. "%d %.3s %d %02d:%02d:%02d UTC\n"   --only first 3 characters
		.. "%s\n"
		.. "%s",
		tdb,
		utc.year, std.monthName[utc.month], utc.day,
		utc.hour, utc.minute, std.round(utc.seconds),
		os.date("!%Y %b %d %H:%M:%S %Z"),    --exclamation point for UTC
		os.date( "%Y %b %d %H:%M:%S %Z (%z)"))     --no ! for local time

	celestia:print(s, 1, 1, 1, -22, -2) --upper right, below simulation time
end

local function main()
	--Keep the Sun in view, but get away from its glare.
	local observer = celestia:sane()
	observer:setposition(std.position)

	celestia:requestsystemaccess()	--Get permission to mention os.
	wait()

	celestia:registereventhandler("tick", tickHandler)
	wait()
end

main()

Simulation Timesimulation time

Simulation time can be expressed in UTC or TDB. UTCUTC (Coördinated Universal Time) is the Coördinated Universal Time kept by clocks on Earth. TDBTDB (Barycentric Dynamical Time) is the Barycentric Dynamical TimeBarycentric Dynamical Time that would be kept by a clock at the barycenterbarycenter (of Solar System) (center of mass) of the Solar System. TDB is untroubled by the difference in gravitation between mountaintop and ocean floor. It is not dilated by the acceleration of the Earth in its elliptical orbit. And it certainly doesn’t care that the Earth’s rotation is slowing down. Celestia uses TDB for all its internal needs, and UTC (or the local equivalent) only for the display in the upper right corner of the window.

Let’s display the current simulation time in TDB and UTC, updated wth every tick of the simulation The method Celestia:gettimeCelestia:gettime returns the simulation time as a Julian dateJulian date measured in TDB. We can convert it to UTC with Celestia:tdbtoutcCelestia:tdbtoutc.

--[[
Display the current simulation time in UTC and TDB, updated every tick.
]]
require("std")

local function tickHandler()
	local tdb = celestia:gettime()	--Get the Julian date in TDB.
	assert(type(tdb) == "number")

	local utc = celestia:tdbtoutc(tdb)
	assert(type(utc) == "table")

	local s = string.format(
		"Simulation time:\n"
		.. "%.15g\n"
		.. "%d %.3s %d %02d:%02d:%02d UTC",
		tdb,
		utc.year, std.monthName[utc.month], utc.day,
		utc.hour, utc.minute, math.floor(utc.seconds))

	celestia:print(s, 1, 1, 1, -17, -2)	--upper right, below time
end

local function main()
	--Keep the Sun in view, but get away from its glare.
	local observer = celestia:sane()
	observer:setposition(std.position)
	celestia:registereventhandler("tick", tickHandler)
	wait()
end

main()

The inverse of Celestia:tdbtoutc is Celestia:utctotdbCelestia:utctotdb. It takes six arguments (year, month, day, hour, minute, seconds) and boils them back down into a Julian date. The hour, minute, and seconds default to 0, the month and day default to 1, and the year defaults to 0. The fractional part of each argument except the last is ignored.

Celestia:utctotdb provides a user-friendly way to compose the argument of Celestia:settime; see settime.

Set the Time and the Timescale

Let’s watch the shadow of the Moon travel across Europe during the total solar eclipseeclipse, solar of August 11, 1999. We will go to the start of the eclipse, fast forward through it at 600 times the normal speed, and revert to the original speed when it is over.

It’s easy to go to the start of the eclipse with Celestia:settimeCelestia:settime, and speed up the time with Celestia:settimescaleCelestia:settimescale. But it’s harder to go back to the original time scale at the end of the eclipse. We’ll use a tick handler (tickHandler) to detect when the current time has reached the end of the eclipse. The tick handler will tell Celestia to stop calling the tick handler, and will set the time scale back to 1. To avoid unnecessary work, we create the variable t1 once and for all as a global rather than re-creating it every time the tickHandler is called.

Our vantage point will be four Earth radii above the subsolar pointsubsolar point—the point on the Earth where the Sun is directly overhead. A full explanation of how we keep the observer suspended there is in lockFrame. For now, we will create a moving “frame of reference” whose X axis always points from the Earth to the Sun. We keep the observer positioned on this axis, looking at the Earth, and oriented so that the universal Y axis (universalFrame) is pointing upwards.

In totality we will draw a line on the surface of the Earth along the path of totality.

--[[
Fast forward through a total solar eclipse at 600 times faster than normal
speed, then revert to the original speed.
Face the Earth from a point on the Earth-Sun line, with the north pole of the
ecliptic towards the top of the window.
]]
require("std")

--variable used by tickHandler:
local t1 = celestia:utctotdb(1999, 8, 11, 13, 50, 0.0)	--end of eclipse

local function tickHandler()
	if celestia:gettime() >= t1 then
		--Stop calling the tickHandler.
		celestia:registereventhandler("tick", nil)
		--Go back to the normal speed.
		celestia:settimescale(1)
	end
end

local function main()
	local observer = celestia:sane()
	celestia:hidelabel("planets")	--We know that the Earth is the Earth.

	--The International Space Station is a distracting dot.
	local iss = celestia:find("ISS")
	iss:setvisible(false)

	--Field of view of 30 degrees is wide enough to see the whole Earth.
	observer:setfov(math.rad(30))

	local sol = celestia:find("Sol")
	local earth = celestia:find("Sol/Earth")
	local lockFrame = celestia:newframe("lock", earth, sol)
	observer:setframe(lockFrame)	--Adhere the observer to the frame.

	local microlightyears = 5 * earth:radius() / KM_PER_MICROLY
	local position = celestia:newposition(microlightyears, 0, 0)
	observer:setposition(lockFrame:from(position))
	observer:lookat(earth:getposition(), std.yaxis)

	--a few minutes before total solar eclipse begins
	local t0 = celestia:utctotdb(1999, 8, 11, 8, 10, 0.0)
	celestia:settime(t0)

	--Start the fast-forward as soon as the "CELESTIA" logo disappears.
	wait(std.logo)

	--Fast forward one hour of simulation time per 6 seconds of real time.
	celestia:settimescale(60 * 60 / 6)
	celestia:registereventhandler("tick", tickHandler)
	wait()
end

main()

--[[
Demonstrate that the simulation time does not advance until we call wait.
]]
require("std")

local function main()
	--Keep the Sun in view, but get away from its glare.
	local observer = celestia:sane()
	observer:setposition(std.position)

	local s0 = celestia:getscripttime()	--real time in seconds
	local t0 = celestia:gettime()		--simulation time in days

	--Noticeable delay, but not long enough to require a call to wait.
	for i = 1, 2^27 do		--134,217,728
	end

	local s = string.format(
		"The loop took\n"
		.. "%.15g seconds of real time\n"
		.. "%.15g seconds of simulation time",
		celestia:getscripttime() - s0,
		(celestia:gettime() - t0) * 24 * 60 * 60)

	celestia:print(s, 60)
	wait()
end

main()

Time Dilationtime dilation

The methods Celestia:tdbtoutcCelestia:tdbtoutc and Celestia:utctotdbCelestia:utctotdb know that UTC speeds up and slows down relative to TDB. UTC passes slowly when the Earth is moving quickly (in early January, at perihelionperihelion (of Earth)—the Earth’s closest approach to the Sun). A January UTC day is therefore longer than a TDB day. UTC passes quickly when the Earth is moving slowly (in early July, at aphelionaphelion (of Earth)—the Earth’s farthest retreat from the Sun). A July UTC day is shorter than a TDB day.

The plus sign in the format %+.15g prints a leading plus or minus.

--[[
Print the average length in TDB days of a UTC day at various times of the year.
We'll print the average of the first n UTC days of each month.
]]
require("std")

local function main()
	--Keep the Sun in view, but get away from its glare.
	local observer = celestia:sane()
	observer:setposition(std.position)

	local year = celestia:tdbtoutc(celestia:gettime()).year	--current year
	local n = 10	--average the first n days of each month
	local s = ""

	for month = 1, #std.monthName do
		--average length of a UTC day, measured in TDB days.
		local d = (celestia:utctotdb(year, month, n + 1)
		         - celestia:utctotdb(year, month, 1)) / n

		s = s .. string.format(
			"%.2s: 1 UTC day = %17.15f TDB days = 1 day",
			std.monthName[month], d)

		if d ~= 1 then
			s = s .. string.format(" %+.15g seconds",
				(d - 1) * 24 * 60 * 60)
		end
		s = s .. "\n"
	end

	celestia:print(s, 60, -1, 1, 1, -1)
	wait()
end

main()

The 2.81631869825105e-05 in the first line of output stands for 2.81631869825105 · 10^–5 = .0000281631869825105

Thus a UTC day can be more than 10^–5 seconds longer than a TDB day. And it adds up. A hundred UTC days can be 10^–3 seconds longer than a hundred TDB days.

Leap Secondsleap second

We have seen that Celestia:tdbtoutcCelestia:tdbtoutc and Celestia:utctotdbCelestia:utctotdb know that UTC is slowed down and speeded up by the Earth’s orbit. They also know that UTC is occasionally delayed by a leap second. For example, they know that the interval between the following times is two seconds. 11:59:59 p.m. December 31, 2008 UTC
12:00:00 a.m. January 1, 2009 UTC

A parallel pair of methods, Celestia:fromjuliandayCelestia:fromjulianday and Celestia:tojuliandayCelestia:tojulianday, takes a less sophisticated view of time. They remain rigid in their belief that every minute has 60 seconds. They refuse to acknowledge that the Earth’s rotation is slowing down. They reject Einsteinian time dilation. A sure-fire way to get the 66-second error in tdb is to pass the return value of Celestia:tojulianday to Celestia:settime, or the return value of Celestia:gettime to Celestia:fromjulianday.

The following subtractions give us the interval in days between the times shown above. We multiply the intervals by 60 · 60 · 24 to convert them to seconds. The %.4f rounds the answer to the nearest ten-thousandth.

--[[
Demonstrate that Celestia:utctotdb knows about leap seconds, and that
Celestia::tojulianday doesn't, by printing the distance in seconds between
23:59:59 December 31, 2008
00:00:00 January   1, 2009
]]
require("std")

local function main()
	--Keep the Sun in view, but get away from its glare.
	local observer = celestia:sane()
	observer:setposition(std.position)

	local tdb0 =    celestia:utctotdb(2008, 12, 31, 23, 59, 59)
	local tdb1 =    celestia:utctotdb(2009,  1,  1,  0,  0,  0)

	local utc0 = celestia:tojulianday(2008, 12, 31, 23, 59, 59)
	local utc1 = celestia:tojulianday(2009,  1,  1,  0,  0,  0)

	local s = string.format(
		"Distance according to utctotdb:    %.4g second(s)\n"
		.. "Distance according to tojulianday: %.4g second(s)",
		(tdb1 - tdb0) * 60 * 60 * 24,
		(utc1 - utc0) * 60 * 60 * 24)

	celestia:print(s, 10)
	wait()
end

main()

Step Through the Calendarcalendar

The simpleminded pair Celestia:fromjuliandayCelestia:fromjulianday and Celestia:tojuliandayCelestia:tojulianday still have a modest but essential rôle to play. Precisely because of their belief in the 60-second minute, they provide a uniform way to step through the calendar. Celestia:tojulianday follows two cast-iron rules, reminiscent of the Peano axiomsPeano axioms (of arithmetic):

1. It converts UTC noon of January 1, 4713 B.C. into zero. (Since there was no year 0 A.D., the first argument of this call to Celestia:tojulianday has to be –4712.)
2. Adding or subtracting a number of days (possibly with a fraction) increases or decreases the return value by the same number. For example, it converts UTC noon of consecutive days into consecutive whole numbers.

Let’s find the day of the week of the current simulation time, even though we could easily get it from os.timeos.time and os.dateos.date. Since the first Julian day started at noon, we pass noon of the current day to Celestia:tojulianday. The variable std.dayNamestd.dayName is an array of seven strings, starting with "Monday" because the first Julian date, January 1, 4713 B.C., would have been a Monday if our calendar went back that far. The expression #std.dayName has the value 7. The operator %% (remainder operator) divides d by 7 and gives us a remainder in the range 0 to 6 inclusive. Adding 1 gives us a sum in the range 1 to 7 inclusive, which is used as the array subscript.

--[[
Print the day of the week of the current simulation time.
]]
require("std")

local function main()
	--Keep the Sun in view, but get away from its glare.
	local observer = celestia:sane()
	observer:setposition(std.position)

	--Get permission to mention os.
	celestia:requestsystemaccess()
	wait()

	local tdb = celestia:gettime()
	local utc = celestia:tdbtoutc(tdb)
	local d = celestia:tojulianday(utc.year, utc.month, utc.day, 12)
	local tab = {year = utc.year, month = utc.month, day = utc.day}

	local s = string.format(
		"Julian date %d\n"
		.. "%s %d/%d/%d\n"
		.. "%s",
		d, std.dayName[d % #std.dayName + 1],
		utc.month, utc.day, utc.year,
		os.date("%A %m/%d/%Y", os.time(tab)))

	celestia:print(s, 60)
	wait()
end

main()

--[[
List the days that had a leap second.
]]
require("std")

local function main()
	--Keep the Sun in view, but get away from its glare.
	local observer = celestia:sane()
	observer:setposition(std.position)

	--The year of the current simulation time
	local year = celestia:tdbtoutc(celestia:gettime()).year

	local first = celestia:tojulianday(1972,  1,  1, 12)
	local last  = celestia:tojulianday(year, 12, 31, 12)

	local s = ""
	for day = first, last do
		local utc0 = celestia:fromjulianday(day)
		local utc1 = celestia:fromjulianday(day + 1)

		local tdb0 = celestia:utctotdb(utc0.year, utc0.month, utc0.day)
		local tdb1 = celestia:utctotdb(utc1.year, utc1.month, utc1.day)

		if tdb1 - tdb0 > 1 + .5 / (60 * 60 * 24) then
			s = s .. string.format("%d/%d/%d\n",
				utc0.month, utc0.day, utc0.year)
		end
	end

	celestia:print(s, 60, -1, 1, 1, -1)
	wait()
end

main()