The Option File of Geomorph

The option file of Geomorph: geomorphrc

Introduction
An update checklist
Some interesting options

[files]
[interface]
[application]
[rendering]
[3d_preview]
[Camera_1] to [Camera_5]

Introduction

On startup, Geomorph reads some options or parameters in the geomorphrc file, such as where to save the temporary data, what is the default interface style, and so on.

This file is usually saved in the /home/<your_id>/geomorph directory. However, you may also have other geomorphrc files elsewhere. Geomorph first checks if it can find a geomorphrc file in the directory where the program is started. An other option is to give the geomorphrc file on the command line with its path: geomorph mydirectory/geomorphrc. Geomorph will recognize it as an option file instead as a terrain, as long as it called geomorphrc.

The geomorphrc file contains one line for each parameter. The parameters are grouped by blocks. The syntax is:

[block1]
option1 = value1 ; comments
option2 = value2 ; comments
...

[block2]
option3 = value3 ; comments
...

For instance, here is the beginning of my own file:

[files]                           ; Directories and files
def_dir              = geomorph   ; Default directory
hf_dir               = /home/patrice/geomorph ; Default directory (Height fields)
pov_dir              = /home/patrice/geomorph ; Default directory (Povray scenes)
tmp_dir              = /home/patrice/geomorph/tmp/ ; Default directory (temporary files)
doc_dir              = /usr/local/share/geomorph/doc/index.html ; Default directory (documentation)
doc_reader           = firefox    ; Default HTML reader

[interface]                       ; Interface
interface_style      = Integrated ; Interface style
menu_in_doc_window   = TRUE       ; Display the main menu in each document window
icons_in_doc_window = TRUE       ; Display the main menu icons in each document window
pad                  = 6          ; Dialog padding (pixels)
...

You may edit the file with you preferred text editor, but it is a lot easier to use the dialog provided by Geomorph. It is also safer because it limits choices by using scales and menus, so the input is validated. It is called by clicking the "Options at the application launch" icon

in the main menu bar.

The window shows each block as a tab. The controls allow to load and save a geomorphrc file from any directory:

The changes are effective only after restarting Geomorph.

The title of each option in the dialog are written as comments in the generated geomorphrc.

Notice that when you update Geomorph with a version providing more options, for instance from version 0.40 to 0.50, saving the option file from the provided dialog automatically adds the new variables.

An update checklist

For reference purpose, here are the main changes in geomorphrc from 0.4 to 0.5. If you reuse your geomorphrc file while updating, you may want to check these options and change them manually.

Tab	Option	Value in version 0.5x	Comment
[Directories and files]	Default directory (temporary files)	/home/<your_id>/geomorph/tmp	When updating, the directory is not created automatically. It is recommended to create it.
[Interface]	Interface style	Integrated	At least try the new style!
[Application]	Default history size (undo / redo)	10 instead of 5	Recommended
[Application]	Default terrain	"Subdiv2" instead of "Uniform"	"Subdiv2", with the provided default seed, gives the "standard Geomorph terrain". The preceding uniform gray canvas was best suited for drawing valleys and mountains with the pen.

Some interesting options

Most options are pretty obvious from their title. Options or details that may be of some importance are described here.

REMINDER: the changes would be effective only after restarting Geomorph.

[files]

This is where you set the directories and files for saving and processing data. Most users would be happy with the default settings.

2 points should be emphasized:

The "tmp_dir ; Default directory (temporary files)" variable is new in version 0.50. If you are updating Geomorph from an older version, be sure to create the directory. You may simply use your existing /home/.../geomorph directory.
You may want to initialize "doc_dir ; Default directory (documentation)" to geomorph.sourceforge.net, if you don't want to download the documentation package. Important: do not prefix the site name with http://.

[interface]

The first 3 options are new in version 0.50:

Interface style: controls whether the interface is "integrated" or is split in multiple windows, in the Gimp style, which was the initial Geomorph interface. The default in a fresh install is "integrated".
Display the main menu in each document window: this option is relevant only if the "Gimp style" is chosen. It displays the main bar menu redundantly, in each document window.
Display the main menu icons in each document window: same as the previous option, for menu icons.

Other options of interest are the Height field default size, which I suggest to set in pixels instead of percent (the percent is used if "no value" is chosen for the pixel parameter), and the Default image display size, which relates to how the height field appears in the interface. For instance, with a height field default size of 512 and a display size of 1024, the height field would be saved at 512x512 pixels and displayed blown up by 200%.

[application]

Default history size (undo / redo): was set to 5 before Geomorph 0.5, now set to 10. A bigger size means more memory, but memory is less a concern nowadays. Those who update may want to increase the size manually. However, beware of the OpenGL DRI memory leak, still seen on recent Linux systems.

Default terrain: This option is new from version 0.5. The default terrain up to Geomorph 0.4 was a uniform gray, intended to be used as a drawing canvas. Now, it's the default "Subdivision 2" terrain use in the Geomorph tutorials, but you can change it if you want.

Default seed for random generator: if you want to reproduce the tutorials with the default terrain, stick with the provided value of 0x6b8b4567. The 0x prefix means that this is an hexadecimal value, but you may also use a decimal integer.

[rendering]

The rendering is done with POV-Ray. For now, nothing is provided for other renderers.

Renderer: Should generally be set to "povray". With previous versions of POV-Ray, other names were used, like "povray35", "x-povray", and so on. You may also give a full path, if POV-Ray is not in your $PATH variable.

Render_width, render_height: default size of the POV-Ray output, overriding the values set in the general povray.ini file.

Scene: The default scene used for rendering your terrains. It could be any POV-Ray script, as long as it follows the Geomorph standard for setting the terrain name and the other options.

Hf_output_for_rendering: name of the temporary file where the edited terrain is written, in the tmp_dir directory. Usually test.png.

Output_prefix: the POV-Ray display output prefix. The POV-Ray display is written in a PNG file, like the terrain. If the terrain is saved in document0.png, the POV-Ray landscape would be rendered in <prefix>document0.png, whatever script is used. The default prefix is the underscore (_document0.png). A value is mandatory, otherwise you'll overwrite your terrains...

Other_render_options: The command line options passed to the "povray" program. The default are: +D +P +L/home/<your_id>/geomorph, respectively: display the output, pause after display until the user click on the image (important!), and use the geomorph directory as a source for POV-Ray include files (.inc).

[3d_preview]

These options control the preview in the right part of the document window, apart from the cameras, which are controlled in the next blocks.

3D mesh size (in nodes on one edge of the HF): size of the "mesh" in nodes used for displaying the terrain. One node is represented by 2 polygons. The default is 128x128 nodes. With more polygons, sharper details are seen, but refreshing the display is slower. Don't forget that a 256x256 mesh requires 4 times the processing of a 128x128 mesh. This parameter is equivalent to the "detail" button in the preview, given in % of the terrain size by power of 2 steps.

Default 3D mesh size when drawing (in nodes): Keeping the preview up to date requires a lot of processing when drawing or adjusting some parameters with scales. A technique used in Geomorph to avoid sluggishness is to decrease the mesh size when the user holds down the mouse button. So, this option controls the amount by which the mesh size is decreased. The default is 64x64, or 50% of the default mesh size. You can experiment with other values and test them by drawing.

Default preview size (in pixels): The image preview width in the document window.

Automatic update: TRUE or FALSE: controls whether or not the preview is refreshed when the terrain is modified. If set to FALSE, you'll need to click on the "Refresh" button. It may be useful to set it to FALSE when a high mesh size is used, or when the computer is not powerful enough.

Show the camera controls on startup: TRUE is the default, try FALSE for a more "zen" preview. Without the dialog, the camera can also be controlled by holding one of the 3 mouse buttons in the preview area, excepted for the field of view.

Hardware acceleration for OpenGL (DRI): TRUE or FALSE: controls whether or not the OpenGL hardware acceleration of your video card is used for displaying and texturing the polygons in the preview. In the current state of Geomorph (version 0.50), this option makes only a small performance difference, because the preview shows only simple static scenes, with simple textures. Furthermore, some X-Windows drivers cause a huge memory leakage when this option is set to TRUE. This was the case a few years ago with the ATI and Nvidia proprietary drivers, which seem OK now (2008), but this was observed recently under Ubuntu 7.10, using the free Intel driver on a laptop with the X3100 graphic chipset. For this reason, the default is FALSE. You may try to set it to TRUE and use the system monitor to compare the memory usage, when opening and closing documents.

[Camera_1] to [Camera_5]

These are the default settings for the 5 preview cameras, translated as POV-Ray cameras.

All options relate to specific parameters which can be set in the preview interface. The only parameter which cannot be set in the GUI is the Default aspect ratio, which affects the POV-Ray camera but not the preview. The default is 4:3 (for instance, consistent with render_width X render_height values of 800x600).

Unfortunately, there is no "save" function in the document window to save the parameters in the geomorphrc file. You have to set them manually, for now.

Written in June 2008.

Contact: Patrice St-Gelais

Back to the documentation index