Fracplanet user documentation

Introduction

Fracplanet is an application to generate random planets and terrain with oceans, mountains, icecaps and rivers. Parameters are specified interactively and the results displayed using OpenGL. The generated objects can be dumped in Pov-Ray format.

Command line arguments

Fracplanet has no command line arguments other than those intercepted and interpreted by Qt. These are pretty much what you'd expect most X11 applications to handle e.g -geometry XxY and -fn font.

GUI

The fracplanet GUI is a tabbed control. The terrain generated is shown in a separate window (which disappears when regenerating). A progress dialog is generally displayed while generating terrain (except at startup).

Create tab

Note that none of the parameters adjustable on this tab have any effect on the displayed model until one of the "Regenerate" buttons is pressed. This tab is further subdivided into sub-tabs ("Terrain", "Snow", "Rivers", "Colours").

Planet/Terrain area: These radio buttons select the type of object to be created. Planet creates planets by subdividing an icosahedron. Terrain area creates planar terrain areas by subdividing 6 triangles arranged in a hexagon.
Base land height: This expresses the initial height of the terrain (relative to the sea level) as a percentage of the vertical maximum perturbation size. Negative values produce (on average) more ocean than land, positive values produce more land than ocean.
Perturbation seed: Specifies the random number generator seed used when creating terrain. Regenerating without changing this value will produce the same terrain, allowing the user to play with subdivision levels, colours etc while still retaining the same basic pattern of oceans and continents. The value is initially set to the system time on application start-up.
Power law: A power law applied to all above-sea-level heights after terrain generation. (This consists of normalising the height relative to the maximum height in the terrain model and raising it to the power of this number divided by 100). Values above 100 flatten low terrain, tending to produce smooth plains surrounding spiky mountains. Values below 100 flatten high terrain, tending to produce smooth highlands surrounded by steep cliffs.
Subdivisions: The number of subdivisions of the initial structure. Each successive level of subdivision increases the number of triangles by a factor of four, so users should increase this parameter with caution. This has a major impact on the amount of memory consumed, the frame rate and the responsiveness of the application.
Unperturbed subdivisions: Specifies the number of the subdivisions which will be performed without random perturbation of the vertices. Lower numbers (0, 1) produce a few large continents. Higher values produce many small islands.
Vertical perturbation: Specifies the maximum size of vertical perturbations at the first level of subdivision. The maximum perturbation size is then halved at each subsequent subdivision. Planets and terrain areas both have a nominal radius of 1.0, and the number here is divided by 100 so if you specify a vertical variation of 12 you could get mountains which are on the order of 12 percent of the planet's radius high, or larger if subsequent perturbations accumulate upwards at a point (of course suppressing initial large perturbations using the "Unperturbed" parameter will tend to reduce this). This is of course a ridiculous height for mountains on anything but an asteroid, but using realistic values will just produce very boring looking planets.
Horizontal perturbation: Specifies the maximum size of horizontal perturbations at the first level of subdivision. The maximum perturbation size is then halved at each subsequent subdivision. Beware of making this value too large as it can produce overhanging/self-intersecting terrain, on the other hand small values can be useful for breaking up obvious artifacts of the initial geometry.
Noise terms: Number of terms in a Perlin noise function added to the terrain heights. Each subsequent term doubles the frequency. The best way to get an appreciation of the qualitative differences between Perlin noise and subdivision-perturbation is to reduce "Vertical perturbation" (on the "Subdivision" tab) to zero and increase the number of noise terms.
Noise frequency
: Frequency of 1st noise term. 100 gives a scale on the order of the terrain radius. Subsequent terms double the frequency (and therefore halve their length scale).
Noise amplitude
: Amplitude of 1st noise term, as a percentage of the nominal object radius.
Noise amplitude decay rate
: The amplitude of subsequent noise terms decays to this percentage of the amplitude of the previous term. Fifty percent does the classic fractal thing of scaling perturbation size with length scale. Increasing it slightly (to e.g sixty percent) has the interesting effect of making rivers meander more as small-scale variations now have a bigger effect on local gradients than large scale features.
Snowline at equator: The nominal height of the snowline at the equator of a planet (and everywhere on a flat-based terrain area), expressed as a percentage of the maximum height of the terrain.
Snowline at pole: The nominal height of the snowline at the poles of a planet (unused for a flat-based terrain area), expressed as a percentage of the maximum height of the terrain.
Snowline power law: Tweaking this parameter lets you control whether the snowline remains high up and only plunges downward towards the poles, or whether it only quickly rises near the equator. Experiment, it has a fairly subtle effect.
Snowline slope suppression: The larger this value is, the harder it is for snow to stick to steep slopes (you can see this effect for real on any mountain range). This breaks up the snowline quite nicely, as it otherwise tends to stop at an artificially uniform height (reduce this parameter to zero to see what I mean).
Snowline glacier effect: If this parameter is positive, rivers tend to form glaciers and you will see e.g white lines running out of snowy areas, and frozen lakes. If this parameter is negative rivers find it harder to freeze and you will see them running through snowy areas and forming un-frozen lakes.
Rivers: Specifies the number of rivers to be generated. Note that rivers starting in the sea are immediately abandoned, but still count against this number (this is so the relative proportions of land/ocean can be tweaked without affecting the river source density). Rivers run from vertex to vertex along triangle edges, and are then rendered by blending from the river vertex colour to the surrounding terrain colour. This isn't ideal as they aren't very sharply defined. A previous version of the software flowed rivers from triangle to triangle which produced nice solid edged rivers (like the oceans are) but since they weren't flat it wasn't ideal either.
Rivers seed: Random number seed for river generation. If you change this, but not the perturbation seed, you can get a different river network on the same terrain.
Lake becomes sea: As a river is flowed across a terrain, it will sometimes form a lake as the water level rises sufficiently to overcome a terrain barrier. If the lake becomes sufficiently large (greater than the percentage of available surface area specified here) then it is considered to have become an inland sea and it is no longer necessary for the lake to rise until an outflow to be discovered (in the real world, surface evaporation replaces the outflow). Increasing this number may result in larger lakes, but the process of river generation can take considerably longer.
Oceans and rivers emissive: Sets the emission (also called "glow") of lakes and rivers, on a scale of 0-100. This is mainly to facilitate glowing lava planets. Note that for terrain generated with emission non-zero, an alternative OpenGL rendering path must be used which may be a little slower.
Change colours: Click on these buttons to bring up a colour-picking dialog and change the colour for the selected class of terrain. Each button displays the colour currently selected for that class. Obvious things you might want to do are to change the shoreline colour to the same colour as the low level terrain (those beaches are pretty absurdly wide otherwise), change the orange highlands to a more mountainous grey, or perhaps you preferd an apocalyptic "lava world" with red rivers and oceans (use emission to make them glow), black shorelines and ash-grey terrain.
Regenerate: Click this button to regenerate the planet/terrain area without changing the random seeds.
Regenerate with new rivers seed: Click this button to increment the river generation seed by one and regenerate. This gets you the same landscape with a different river network.
Regenerate with new perturbations seed: Click this button increment the perturbation seed by one and regenerate. This will get you a completely different terrain. (The river network will be different too, although it's seed won't have changed).

Save tab

Add atmosphere: This tick-box causes additional POV-Ray directives to be emitted to render a thin atmosphere.
Sea object: This tick-box causes a single sphere to generated for the oceans instead of numerous individual triangles.
Base filename: Enter the filename root to be used here. Two files will be generated, one with ".pov" appended, and one with ".inc" appended. The .inc file actually contains the object (using POV-Rays's mesh2 format), plus any other spheres generated due to the options above. The .pov just includes the .inc and adds a camera and light source and was primarily intended for testing: the expectation is that users will generally import the .inc into their own scenes, probably wrapping the include in a POV-Ray union with embedded translate/scale/rotate directives).
Save (POV-Ray): Click this button to create the POV-Ray files. This can take quite a long time so the progress bar is used to track the completed percentage.

Render tab

Options for OpenGL rendering appear on this tab. Note that none of these make any difference to the underlying mesh or POV-Ray's rendering of saved meshes. Currently the options are a tickbox to select wireframe rendering, another to select display-list rendering (the default is immediate mode), another to select joystick mode for the mouse in flight mode (this simply affects whether pulling the mouse down the screen flies you in that direction, or whether it's more like an aircraft joystick and pitches you up instead) and a slider controlling the amount of ambient light. The frame rate and current mesh size (number of triangles and vertices) is also displayed.

Display list rendering is generally but not always faster (depends on your OpenGL implementation and graphics drivers). The main reason display list is not enabled by default is that the application may pause for a long time while OpenGL processes the list when it is first rendered; the amount of memory consumed by the display list could also be a problem for very large meshes.

About tab

This tab displays information about the software (in particular the version number) and its license.

Display window

The display window, when shown, shows the current (most recently generated) terrain model. It is hidden when terrain is being regenerated or saved. The (badly named) "tilt" slider controls the latitude of the camera (when viewing a sphere-based object), and the elevation (as in azimuth-elevation) of the camera when viewing a planar based terrain area. Note that in the latter case the bottom half of the slider places the camera below base ground level/sea level, which results in little being seen due to back-face culling. The "spin rate" controls the rate at which the object is rotated. The display window update rate is clamped to 75Hz, although this will typically only be reached at the lowest levels of subdivision.

Hitting the "Fly" button puts you into free-flight mode. Pitch and yaw are controlled by the mouse position relative to the window centre (if the pitch control feels backwards, change mouse-Y behaviour on the render tab). Roll is controlled by left/right mouse buttons, or the left/right arrow keys. Speed is controlled by the mouse wheel or the up/down arrow keys. There is a summary of this displayed at the bottom of the window. Hit Esc to return to the usual viewing mode.

License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

The full license can be also viewed on fracplanet's "About" tab.