about.txt

# calenhad

Calenhad is GIS and terrain creation for imaginary worlds.

I identified some specific requirements for GIS when dealing with imaginary worlds that are not well catered for by traditional real-world GIS offerings such as QGIS, for all their comprehensiveness and pedigree. For instance:

  - if we are creating a world ourselves instead of describing the one God made, we are generating procedurally or by hand data which in real-world GIS is typically downloaded or produced by some other system. We need tools to generate topographic and other data to describe the world the user is imagining. I think that in general we will want to guide the high-_level structure of a planet (say where there will be continents and oceans, what rough shape they will be, where there will be mountain ranges, and so forth) and overlay low-_level detail (place specific features, sculpt particular pieces of topography, arrange the landscape to suit his story or game scenario) but let the computer generate realistic and appropriate landscapes for levels of detail between the satellite view and the street-_level view. Calenhad uses noise generation (initially libnoise and in due course a port of this to a GPU implementation) and potentially sculpting tools and a tectonics simulator to generate toporgraphy.

   - When we change the landscape we want pretty quick feedback to see the resulting geography. In real-world GIS it would be OK for the system to take some time to compose maps using a new raster file uploaded because we are not working with rasterised data interactively. Pipeline-based terrain generators such as WorldMachine do this for 2D terrain heightfields, and Calenhad now uses a shader running on the GPU to generate the terrain in three dimensions, project it and draw the maps.
   
   - Earth-based GIS has some difficulty dealing with planets whose astronomical data is different from Earth although it is possible to use geoids that represent the Moon, Mars, etc. On the other hand we do not need to be at all pendantic about the finer points: we don't need geolocations and altitudes down to the nanometre and we don't need a precisely calibrated triaxial geoid with bumps and dents in the right places; indeed it would be quite confusing and complicated to try to as well as slowing things down horribly. We therefore approximate the planet as a sphere. Of course an author might want a flat world, or a funny-shaped world, but GIS wouldn't help us there anyway.
   
The solution at the moment provides the following.

  - Pipeline editing for combinations of libnoise modules
  - Rendering of the output and interactive visualisation through a GLSL compute shader
  - Serialisation of a terrain generation pipeline to and from XML
  - Calculation of module parameters from entered mathematical expressions using variables
  - Organisation of libnoise-esque modules into groups
 
Architecture is C++ with no QML and Qt5.9. We use a handful of other libraries:

  - exprtk: parsing and calculating mathematical formulae entered as text
  - QWT: some of the widgets, such as the compass / navigator that appears on the map
  - GeographicLib: geodesic calculations on the geoid (we always use a sphere)
  - OpenGL: to compile and run the Übershader and display maps and globes from its output
  - QuaZip and its engine zlib: to package and unpackage the project files so they can be distributed as a single archive and dependencies managed within it.

  Note that libnoise is NOT a dependency. I replicated (almost) all of libnoise on the GPU (see the class calenhad::graph::Graph and the GLSL shader code in resources/shaders/map_cs.glsl). The noise generators themselves are not ported from libnoise where those algorithms would have wanted lots of standing data buffered to the GPU. We replace them with the following, in each case ported from C / C++ to a glsl compute shader:

    - Classic Perlin 4D Noise by Stefan Gustavson;
    - Simplex 4D Noise by Ian McEwan, Ashima Arts (this is additional to the noise types available in libnoise);
    - Cellular noise ("Worley noise") in 3D in GLSL by Stefan Gustavson 2011-04-19. This replaces libnoise's Voronoi module and has a couple of extra features; and
    - billow, ridged multifractal and turbulence ported from libnoise to glsl by yours truly.

  Other libnoise modules are ported directly with the exception of checkerboard, which is not really needed and a little awkward.

  The Übershader code is composed just in time by selecting code which calls the required algorithms and assembling it into a sequence of calls which translate the graph of modules in the model. This is done by the class calenhad::graph::Graph. The projections are also wired in during this code generation process and the code for them is in the various calenhad::mapping::projection classes. Those snippets of code are implementations of algorithms in John P Snyder's seminal work, "Map projections - A working manual".

Calenhad finally stands on the shoulders of the following giants:

   - Icosphere classes were ported from the C# implementation by Andreas Kahler (http://blog.andreaskahler.com/2009/06/creating-icosphere-mesh-in-code.html) to C++
   - Legend editor: this allows the colour scheme of the map to be editied and managed and is by Richard Steffen (https://store.kde.org/p/1132126/)
   - FlowLayout is one of the examples that comes with Qt5
   - TextEdit, which allows the code completion popup for mathematical expressions, is one of the examples that comes with Qt5
   - SizeGripItem, used to allow the manipulation of module groups, is by Cesar Silveira (https://github.com/cesarbs/sizegripitem)
   - The pipeline editor is adapted from code by Stansialw Adaszewski (http://adared.ch/qnodeseditor-qt-nodesports-based-data-processing-flow-editor/)
   - The geoutils include a method by James Chappell (https://www.storage-b.com/c/16) to write lat/long coordinates out in degrees, minutes and seconds of arc.