Fracplanet user manual

Introduction

Fracplanet is an application to generate simple 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 exported in formats directly usable by POV-Ray or Blender, or as more generally useful texture images.

Command line arguments

Some command line arguments (not listed here) are intercepted and interpreted by Qt. These are pretty much what you'd expect most X11 applications to handle e.g -geometry XxY. Fracplanet's own command line arguments are:

--help, -h

Display a list of recognised arguments.

--verbose, -v

Output information about fracplanet execution (and OpenGL) to stderr.

--display-list, -d

Start up the application with rendering in display list mode by default (c.f immediate mode). This is particularly useful when the application is running remotely as the generated meshes are then only sent to the local OpenGL display hardware once.

--invert-mouse-y, -y

Start application with mouse in non-joystick mode for flight.

--wireframe, -w

Start application with rendering set to wireframe mode.

GUI

The main part of the fracplanet GUI is a tabbed control. The terrain generated is shown in a separate window (which disappears while regenerating). A progress dialog is generally displayed while generating terrain (except during application 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", "Clouds").

Terrain

This tab is actually even further subdivided ("Basics", "Subdivision" and "Noise" tabs), but the list below doesn't distinguish.

Starting geometry: Generate...

A pull-down menu (or "combo-box") selects the initial geometry which will be "fractalized". Planet creates planets by subdividing an icosahedron. The other terrain area type create planar terrain areas by subdividing one or more triangles. Note that the square type doesn't produce very good results because the triangles it uses aren't equilateral.

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.

Terrain random 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.

Snow

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

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.

Colours

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 preferred an apocalyptic "lava world" with red rivers and oceans (use emission to make them glow), black shorelines and ash-grey terrain.

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.

Clouds

The cloud layer, when generated, is a triangle mesh with variable translucency at each vertex. Note that it's not a texture in the normal sense.

Clouds enabled

Select the check box to trigger creation of a cloud layer.

Subdivisions

When left unchecked, the cloud layer will be subdivided to the same degree as the terrain. Check the box for explicit control of cloud layer subdivision.

Clouds seed.

Change this to get a different cloud pattern.

Cloud height

Change this to get adjust the height of the clouds above the terrain.

Other "Create" tab controls

Generate

Click this button to regenerate the planet/terrain area without changing the random seeds.

...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.

...new terrain seed

Click this button increment the terrain 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, as the rivers flow over the terrain differently).

...new clouds seed

Click this button increment the clouds seed by one and regenerate. This will get you a different cloud layer.

Render tab

Options controlling OpenGL rendering appear on this tab. Generally none of these makes any difference to the state of the rendered mesh. However, some of the parameters do affect some export methods; see the individual item descriptions.

Wireframe checkbox

Selects OpenGL wireframe rendering mode.

Joystick mouse checkbox

This simply affects whether, when in flight mode, 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.

Display list

Selects OpenGL display list rendering. Display list rendering is generally but not always faster (depends on your OpenGL implementation and graphics drivers). The main reason display list rendering 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 additional memory consumed by the display list is also a problem for very large meshes.

Background colour

Colour picking buttons to control the colour used for the viewing area background. The low altitude colour is also used when exporting a cloud mesh to blender.

Ambient

The amount of ambient illumination. This is also used when exporting shaded textures.

Illumination azimuth and elevation

Control the illumination direction. These are also used when exporting shaded textures.

Status

A text field displaying information about the rendered mesh, and rendering performance (recent average frames-per-second).

Save tab

Strictly speaking it's Export which is provided, not save, as fracplanet's state cannot be restored (yet). There are currently three ways of exporting models from fracplanet for other uses: to POV-Ray, to Blender and as textures.

POV-Ray

Add atmosphere

This tick-box causes additional POV-Ray directives to be emitted to render a thin layer of atmosphere.

Sea object

This tick-box causes a single sphere or infinite plane 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 objects 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 include the .inc into their own scenes, probably wrapping it 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 a progress bar is used to track the completed percentage.

There are additional comments on usage with POV-Ray below.

Blender

Per vertex alpha

This check box selects Fracplanet's preferred method for outputting clouds: by specifying per-vertex alpha components. However, Blender seems to ignore these so a workround is used and an opaque cloud layer is output (which should be ok if you fly underneath it and light it sensibly). You probably don't want to switch this on.

Save (Blender)

Click this button to create a file (a file dialog will appear) which can be imported into Blender. Note that the save file takes the form of a Python script (traditionally a .py file extension) which can be executed by Blender to reconstruct the fracplanet model.

There are additional comments on usage with Blender below.

Texture

Saving as texture(s) gives you a set of 2D images which can be used by other rendering or modelling applications, if not immediately then perhaps after a little massaging with the ImageMagick or NetPBM tools. On saving you'll be prompted for a base filename.ppm. A number of files are then saved:

filename.ppm

The basic texture. This will be embedded in black pixels if the terrain isn't square e.g for the hexagonal terrain area. Planets produce a cylindrically projected latitude-longitude "spheremap".

filename_dem.pgm

The height field (a "DEM" is a Digital Elevation Model). This is output as a PGM image, with heights from 0.0 to 1.0 scaling to 0 to 65535. If the DEM contains a value greater than or equal to 256 (highly likely, except for exceptionally flat terrains), then it will be output as a 16-bit PGM which, while part of the PGM "standard" isn't well supported by many common graphics tools which appear to otherwise offer good PPM support (e.g The Gimp doesn't like it). The NetPBM tools are your best bet to convert this to something else (e.g pnmdepth). Imagemagick's simple "display" tool also handles them well, scaling the maximum value to white.

filename_norm.pgm

The surface normals; XYZ components are mapped to RGB; [-1, 1] is scaled to [0,255]. It is thought this should be useful for bump-mapping renderers (e.g Celestia) where the illusion of surface relief is produced by normal perturbation. If you intend to use this file, you almost certainly want to disable shading (see below), as your renderer will compute it later.

Other texture save options:

Shaded texture

Controls whether the texture map includes the effect of lighting. If you intend to use the information in the _norm.ppm or the _dem.pgm files to subsequently compute lighting, then you almost certainly do not want the output texture to be shaded. The amount of ambient lighting is taken from the slider on the render tab. (Disabling shading is the same effect as setting ambient to 1.0). The lighting direction is controlled by the render tab's illumination azimuth and elevation controls. If you want to use the OpenGL window to preview the lighting, you should set zero spin and tilt by hitting the "reset"button and dragging the tilt to the centre (unfortunately, this gives you an edge-on view of flat terrain areas so it may be necessary to use the "fly" mode).

Texture height

The number of pixels high the saved texture images are. The width is implicitly determined by the height. For flat terrain the width is the same as the height. For planets the width is twice the height because the height spans [-90,+90] degrees latitude, and the width spans [-180,180] degrees longitude.

There are additional comments exported texture usage below.

About tab

This tab displays information about the software (in particular the version number) and its license. There is a button to show a dialog containing user documentation, and another button to display information about the Qt toolkit.

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 60Hz, although this will typically only be reached at the lower 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, invert mouse-Y behaviour on the render tab). Roll is controlled by left/right mouse buttons, or the keyboard left/right arrow keys. Speed is controlled by the mouse wheel or the keyboard up/down arrow keys. Hit Esc to return to the normal viewing mode.

Fracplanet exports: usage notes

To ray-trace a saved terrain (saved as terrain.pov and terrain.inc, say) do:
povray -Q9 -geometry 768x576 terrain.pov
Expect to get MANY "determinant too small" messages, especially when using high degrees of subdivision. It used to take POV-Ray a LOT longer to read large models than to render them, but it seems to load much faster these days.

Note that clouds, if generated, are output using POV-Ray's double_illuminate and no_shadow declarations. double_illuminate means that both sides of clouds are the same colour (rather than the underside being black). no_shadow means that the clouds cast no shadow on the ground (where the clouds are solid, the shadows are completely black, which looks more unnatural than no shadows). If desired, the declarations can be found at the end of the saved .inc file and simply edited out.

(The author currently uses POV-Ray 3.6).

The easiest way to load mesh saved for blender is with blender's -P <filename.py> command line argument on startup. Note that you'll have to remove blender's default initially created object to see much of the fracplanet object. Also, its shading won't look much like it did in fracplanet until you change blender's viewport shading mode to something better than the "solid" default.

Blender consumes an alarming amount of memory. Even loading a planet generated with fracplanet's default five levels of subdivision consumes a quarter of a gigabyte of RAM. It would probably help if fracplanet made some effort to optimise its meshes, and/or made use of textures rather than trying to do everything using geometry, but it doesn't yet.

Blender's per-vertex-colours capability seems to ignore the alpha component of per-vertex colours, with the result that the cloud layer is rendered as a solid opaque colour. If anyone has a solution to this it would be gratefully received. Fracplanet's workround is to output an opaque surface with the blending (with the "low altitude" colour from the render tab controls) already done. The "per-vertex alpha" checkbox switches to the preferred behaviour in case it ever gets fixed.

Each mesh is output with 2 materials. The clouds just use material 0. For the terrain, material 0 is for land facets, material 1 for the sea. This may be useful for users wanting to give them different shader properties.

In Blender, the terrain mesh is named "fracplanet.terrain". There will also be a "fracplanet.cloud" if clouds were enabled.

Emissive terrain isn't supported.

If you want to manipulate the terrain, and know a bit of Python, an easy way might be to edit the .py file; at the start there are two functions defined: v called to create each vertex and f called to create each face.

(The author currently uses Blender 2.46).

It is hoped that the texture export option will be of use to those building planets for Celestia. (The author hasn't tried it himself yet; at time of writing Celestia is waiting to make it's way from Debian Unstable to Testing). Celestia's texture formats are well documented at the Celestia Motherlode, in particular by the Virtual Surface Textures document. The main issues for anyone doing this would seem to be the need to reduce the height map from 16 to 8 bit (easily changed by pnmdepth) and the possibility that fracplanet's normal map (if used, alternative Celestia can compute normal maps from the height map) needs it's components exchanging or reflecting. Celestia can also take a specular map, generally used to indicating the presence of reflective water (or snow); fracplanet doesn't output this (yet) but it should be possible to fake something by processing the height or texture map.

As a simple demonstration of how to use a saved planet texture, here's how to use it as a spheremap in POV-Ray. Save an unshaded spheremap.ppm from fracplanet, and do:
convert spheremap.ppm spheremap.png
convert -depth 8 spheremap_dem.pgm spheremap_dem.png
cat <<EOF > spheremap.pov
camera {perspective location <0,1,-4.5> look_at <0,0,0> angle 45}
light_source {<100,100,-100> color rgb<1,1,1>}
sphere
{
<0,0,0>,1
pigment { image_map {png "spheremap.png" map_type 1} }
normal { bump_map {png "spheremap_dem.png" map_type 1 bump_size 20.0} }
rotate <0,clock*360,0.0>
}
EOF
povray spheremap.pov +KFI1 +KFF100 +W640 +H480 +Of.png
animate f???.png


convert is one of the ImageMagick utilities. You could omit the line beginning "normal" but you will get a rather flat looking planet. The factor of 20.0 at the end of the line is a rather arbitrary parameter. Raise or lower it to adjust the apparent roughness of the planet.

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.