GeoGen Script reference
Tutorial: Using the command line interface

This tutorial shows how to run GeoGen from the command line.

The geogen executable is located in the bin directory in the GeoGen's main directory. Starting this program will enter the interactive console and wait for a command.

tut_console_empty.png

Command load (shorthand l) can be used to load a script:

load myScript.ggs

This command loads the script and compiles it (and prints any compilation errors if necessary). Command run (r) can then be used to execute the script. A script can be executed as many times as you wish.

tut_console_run.png

Command rl reloads any modifications to the script, rr reloads and also runs the script (effectively combining above two commands into one, accelerating script development).

Script parameters

Following commands can be used to adjust execution of the scripts:

Command name Cue/shorthand Description
Render size
rs [width] [height]
Sets render size of the map. If only one argument is passed, that number is used as both width and height. Use "auto" to let the program determine the size automatically (default value of 1000 will be used, usually).
Render origin
ro [x] [y]
Sets position of the render origin (top left corner of the render). If only one argument is passed, that number is used as both X and Y. [0, 0] is used if not set.
Render scale
rsc [scale]
Sets render scale (0.5 = 2x zoomed out, 2.0 = 2x zoomed in). 1 is used if not set.
Map size
ms [width] [height]
Sets reference size of the map. If only one argument is passed, that number is used as both width and height. Use "auto" to let the program determine the size automatically - render size scaled by render scale will be used, usually. Therefore it is only necessary to specify map size if only a part of the map is being rendered. If the map is infinite, this will be ignored.
Random seed
rseed [seed]
Sets random seed. If the seed is a number, that number will be used. If it is a string, a hash of that string will be used.
Parameter
param [name] [value]
Sets value of a script parameter with given name. If the script doesn't support parameter with that name, it will be ignored.

All of these commands will print the current value of that attribute when invoked without any arguments.

Render origin and render size are applied after scaling. For example, if you want to render bottom left quarter of a 500x500 hundred map at 50% scale, use the following sequence of commands:

ms 500
/// rsc 0.5
/// ro 0 125
/// rs 125

Values set with all these commands will remain effective until changed once again with that command (throughout multiple execution of the script and even after loading another script).

Debugging scripts

Instead of executing the script with run, debug (d) can be used to enter the script debugger.

tut_console_debugger.png

When debugger is started, the program enters a debugger "context" (the LOADER>> is now replaced with DEBUGGER>>) which supports a completely different suite of commands. When the debugger starts, it is waiting before first instruction of the script. Command 'step' (or just hitting "enter") can be used to advance execution by one instruction. 'run' ('r') will keep advancing execution until an error is encountered or end of script is reached.

Variety of commands can be used to study current state of execution:

Command name Cue/shorthand Description
Object stack
os
Prints current object stack.
Call stack
cs
Prints current call stack.
Read variable
read [name]
Prints value of variable with given name. Uses normal variable name resolution mechanism from current location of execution.
Rendering sequence
rs
Prints current rendering sequence.
Managed objects
mo
Prints list of all alive managed objects along with their IDs and reference counts.

The debugger can be terminated at any time using the quit (q) command or by pressing CTRL+C. The program will the go to back to the loader.

When the script finishes executing successfully it will automatically switch to the renderer debugger.

Renderer debugger

Renderer debugger allows manual control over the rendering process. It works similar to the script debugger, except each step (or enter) advances the process by one rendering step instead of one instruction (run/r also works). Most other commands are different than in the loader or debugger context though.

tut_console_renderer.png

State of the renderer can be studied using these commands:

Command name Cue/shorthand Description
Rendering sequence
rs
Prints the rendering sequence.
Rendering sequence metadata
rsm
Prints rendering sequence metadata, including object liveness ranges and rendering bounds for each step.
Object table
ot
Prints information about each slot in the object table.
Save image
save [slot]
Saves object from given object table slot to the hard drive. It will be saved as a PNG file (or CSV file if it is an HeightProfile).
Managed objects
mo
Prints list of all alive managed objects along with their IDs and reference counts.
Enable/disable autosave
as [0/1]
Enables (if 1) or disables (if 0) automatic saving of the affected HeightMap/HeightProfile to the hard drive after each rendering step. These objects will be saved as they are in the object table, including areas which are outside rendering bounds of the executed rendering step (and may therefore be meaningless).