SOPack - A Collection of Terragen Plugins
-----------------------------------------
Sean O'Malley, started February 2000
http://www.geocities.com/ffrog.geo

Notices
~~~~~~~
The SOPack collection is copyright (C)2000-2004, Sean O'Malley.
Terragen is copyright (C)1997-2003, Matt Fairclough.
TGPGuiLib is copyright (C)2000, Jo Meder.

Use SOPack at your own risk. Please inquire regarding commercial
usage.

Installation
~~~~~~~~~~~~
Place the contents of the SOPack archive directly in
the folder where Terragen resides, or in a folder called
"Plugins" inside Terragen's folder.

This version of SOPack requires a version of Terragen
of AT LEAST v0.9.02, and some features require versions as
late as v0.9.17. Terragen can be downloaded from

 http://www.planetside.co.uk/

This also requires Jo Meder's TGPGuiLib, which can be obtained
from

 http://homepages.ihug.co.nz/~jomeder/tgpguilib/

Plugins contained in SOPACK.TGP:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1) Flip Vertical - Terrain Accessories Menu
2) Statistical Filter - Terrain Accessories Menu
3) Camera Effects - Photo Effects Menu
   * RenderCheat
   * Stereo Snapshot
   * SceneInfo
   * AfterGlow
   * Black & White
   * Sepia
   * Blur
   * HDR Output
   * TIF Output
4) Raindrops - Water Effects Menu
5) Water Opacity - Water Effects Menu
6) Terrain Morph - Terrain Effects Menu
7) Image Overlay - RGB Texture/Advanced Surface Distribution Menus
8) Contour Overlay - RGB Texture/Advanced Surface Distribution Menus
9) Strata Overlay - RGB Texture/Advanced Surface Distribution Menus
10) Grid Overlay - RGB Texture/Advanced Surface Distribution Menus

Plugin descriptions:
~~~~~~~~~~~~~~~~~~~~

1) SO Flip Vertical - Terrain Accessories Menu

   Flips the terrain upside-down. Frequently needed when importing
   RAW or other data, since Terragen sometimes reads files in
   "backwards."

2) SO Statistical Filter - Terrain Accessories Menu

   Applies several statistical filters to the terrain with
   varying matrix sizes. The Median filter is good for noise
   removal without hurting parts of the terrain unaffected by the
   noise. The Mean filter averages the pixels, smoothing the terrain.
   (The "Mean" filter replaced the old SO Smooth filter; it has
   the same functionality.) The "Highest" and "Lowest" filters
   accentuate either high or low small-scale features of the
   terrain.

3) Camera Effects Menu:

   SO RenderCheat: Load a previously-rendered scene into Terragen's
      render buffer before post-processing and other photo effects
      are applied. (For instance, the exposure can be tweaked over
      and over without re-rendering an entire scene.) How to use:
      1) Render the "plain" scene with no photo effects in use
         except "SO HDR Data Output" to produce an HDR file.
      2) Once an HDR file has been generated, remove "SO HDR Data
         Output" from the list of photo effect plugins.
      3) Turn off land and sky rendering and add "SO RenderCheat"
         to the plugin list. Edit the plugin and select the HDR
         file produced in step #1.
      4) Add and modify photo effects as needed; the scene now
         renders almost instantly!

   SO Stereo Snapshot: Creates a TGS (script) file based on the
      current camera position and orientation when the scene is
      rendered. This script contains information for the "left" and
      "right" cameras with a separation distance specifiable in the
      plugin. To use:
      1) Set up your Terragen world as usual (surface map, sun, etc).
      2) Place the camera where you wish to take a stereo scene.
      3) Add the Stereo Snapshot plugin to the list of Photo Effects.
      4) Edit the plugin: Specify the camera separation distance and
         the destination for the TGS file.
      5) Render a scene preview (rendering the whole scene is not
         necessary to produce the script).
      6) REMOVE the plugin from the Photo Effects list (this is
         important!).
      7) Execute the script just created; it will perform two full
         renders and leave two new BMP images in the directory where
         the TGS file is stored. These images correspond to the left
         and right cameras in the stereo scene.

   SO SceneInfo: Appends information about each scene rendered
      (while the plugin is active) to a text file selected by
      editing the plugin. The data is appended (as opposed to
      overwriting a previously-created file) so information about
      complete animations can be stored automatically. Currently,
      the plugin stores the information necessary to recreate
      camera and sun movement, plus other information that is not
      otherwise available or for which no script command exists.
      (For instance, this can tell you the color of the sun, its
      position in the sky, and whether it is within the screen
      boundaries.) See the change log for more specific information
      on the SceneInfo script format.

   SO AfterGlow: Apply a fuzzy "glow" effect to images. Softens
      the appearance of clouds and makes sunsets bleed more into
      the terrain. Artifacts MAY appear in intense lighting
      situations (e.g., strong sunlight with dark terrains), in
      which case the glow strength should be set closer to zero.

   SO Sepia: Apply a "sepia" filter to the final rendered image.
   (This color is a reddish monochrome seen in many old photographs.)

   SO Black & White: Make the image black and white.

   SO Blur: Blur the image.

   SO HDR Data Output:
   SO TIF Data Output:
      Output the rendered image to a file in Terragen's main directory
      called "TGIMGxxxxx.HDR" or "TGIMGxxxxx.TIF" respectively, where the xxxxx
      is a numeric time stamp. (It repeats itself every 28 hours approx.)

      The first format (HDR) is a Radiance-type High-Dynamic Resolution Image
      containing a much greater range of color than is output in a normal
      Terragen BMP. The second format is floating-point TIFF format which saves
      the same high-accuracy information (if only slightly less lossless). Possible
      uses for high-dynamic resolution images are for radiosity maps, other global
      illumination purposes, and for general viewing of Terragen images with a
      suitable HDR viewer.

4) SO Raindrops - Water Effects Menu

   Create circular raindrop-style ripples on the water surface. Parameters
   which can be specified are the Drop Count (how many drops to create),
   the minimum and maximum diameter of the drops (drop sizes will be distributed
   between these extremes), and the minimum and maximum number of "ripples"
   the drops can contain (specifies how complex the drop will appear). If a
   rectangular coverage area is specified (it should, by default, be set to
   the size of the currently-loaded terrain), the drops will be distributed inside
   the borders of the rectangle. Since many, many drops may be required to produce
   the desired effect, this allows drops to be located more densely within a
   specific area.

5) SO Water Opacity - Water Effects Menu

   A leftover plugin from before Terragen had native transparent water
   support. This plugin is mainly useful for 'special effects' since it can
   behave unexpectedly and be difficult to control. This will change the
   opacity of the subsurface coloring from completely opaque (at the shoreline)
   to completely transparent (at a specifiable depth). May appear not to have
   any effect at all depending on Terragen's own water transparency settings.

6) SO Terrain Morph - Terrain Effects Menu

   Terrain morph allows you to create an animation in which the terrain
   changes from one terrain to another over the course of the animation.
   (For instance, to simulate erosion or other effects of time.)

   The plugin will ask for the terrain to morph to, the number of frames
   in the animation, and what morphing algorithm to use. The cubic algorithm
   makes the terrain change gradually in the beginning, speed up, and then
   slow down toward the end. The linear algorithm changes at the same rate
   over the whole animation, which may appear more abrupt.

7) SO Image Overlay - RGB Texture/Advanced Surface Distribution Menus

   Overlay a 24-bit BMP image on a surface layer or adjust the distribution
   for the current surface layer.

   The plugin allows the bitmap to be overlayed on a localized portion of
   the terrain (to have greater detail in a particular spot or to place an
   overlay object in a particular area, for instance), or to cover the entire
   terrain at once.

   Tiling allows the same image to be repeated over and over so, for
   instance, a small, high-resolution image of a ground cover could be used
   over the entire terrain without wasting a lot of memory on a single
   larger version. The image will be tiled within the bounds set for it.

   The RGB texture aspect of this plugin overlays the BMP image on the current
   surface layer according to the blending option you specify. Multiple layers
   of this plugin can be added to any single surface layer (for instance, using
   several additive layers so more than one image is overlayed onto one surface
   layer), or single instances of this plugin can be applied to more than one
   surface layer. The Image Overlay plugin is available under the "Tex" menu
   for the current surfacemap layer.

   The Advanced Surface Distribution version uses the BMP image data to adjust the
   distribution of the current surfacemap layer. This can be used to more easily
   control where the surface is distributed, and works similarly to the image
   overlay in regards to the additive, subtractive, overlay, and transparency
   options. Easiest to control when the BMP file contains only greyscale image
   data. For the additive, overlay, and transparency blend methods, when the
   color in the bitmap is bright, the surface layer will appear on the terrain
   at full strength. When it's dimmer or black, the surface layer will be
   partially transparent or not there at all. (Reverse for the subtractive blend
   method.) This can be used to selectively add surfaces like ice or sand that
   should only appear in localized areas, or to make a surface partially
   transparent (which Terragen doesn't normally allow).

   These plugins work on terrains of any size Terragen allows. BMP files can
   be of ANY resolution (larger or smaller than the current terrain), however,
   the larger the BMP, the more detailed the overlay will be.

   The "Advanced..." settings allow the brightness and contrast of the overlay
   image to be manipulated inside of Terragen. These will have different
   effects depending on what overlay type is used, but they are a quick way to
   fix an image that appears too washed-out (or too bright!) when rendered on
   a surface layer.

   Can be used for overlaying roads, map features, images extracted
   from DRGs, etc.

8) SO Contour Overlay - RGB Texture/Advanced Surface Distribution Menus

   Overlay contour lines on the current surface layer, or adjust
   the surface distribution for a layer to have a set of contour lines
   affecting it.

   The adjustable parameters for this plugin are as follows:

    a) Contour Line Thickness - Vertical width of the lines. (Not
       really the "visual" thickness since the width of the line will
       also depend on the steepness of the underlying terrain.)

    b) Contour Line Offset - Offsets the entire set of contour lines
       vertically. For instance, if you want the lines to start at
       height 5 instead of height 0, set this to 5.

    c) Contour Line Interval - The vertical distance between the
       middle of each contour line. The larger this number, the
       farther apart the lines will be.

    d) Contour Line Color - The color of the contour lines.

9) SO Strata Overlay - RGB Texture/Advanced Surface Distribution Menus

   Overlay strata along a vertical area of terrain. Asks for the
   starting altitude, ending altitude, and a BMP image to use. The
   plugin will read the first lefthand column of the BMP image and build strata
   layers using it. As with all RGB textures, it can also be used to modify
   surface distribution to create strata with Terragen's surface maps. Note
   that this strata image need not be square (even a one-pixel wide image will
   suffice).

   The strata MAP is slightly more difficult to use, but can be used to modify
   the strata height over the entire terrain, making it higher or lower, producing
   fault- or marble-like effects. The strata map should be a 24-bit greyscale
   BMP image and may look similar to a heightfield. The brighter the color
   is in a certain area, the higher the strata will go at that point. The dimmer,
   the lower. Color [128,128,128] (medium grey) specifies that the strata will
   stay within its normal range. Colors dimmer than this [0-127] cause the strata to
   lose elevation, while higher colors [129-255] cause it to go up. The "maximum
   deviation" the plugin asks for controls how far this deviation will go at
   either of the extremes. For instance, if you specify a maximum deviation of
   5 and the strata will go from heights 10-50 normally, then when it reads
   pure white from the terrain map (255), the strata will be pushed up to the
   15-55 range. Alternatively, when the plugin reads 0 from the map for that
   particular point, the strata will be pushed down to the 5-45 range.

   It may be more intuitive to start with a fully greyed [128,128,128] strata
   elevation map image before modifying it.

   As a simple example, to create a strata layer that is at its lowest in the
   southern part of the terrain and gradually elevates towards the north, a
   vertical linear gradient could be used (dark toward the bottom and lighter
   to the top). To create a fault, a dark or light area can be inserted along
   the "fault line." (Keep in mind that the fault line would only be visible
   in a steep section of terrain perpendicular to it!) Various rippled textures
   can be used for marble effects.

10) SO Grid Overlay - RGB Texture/Advanced Surface Distribution Menus

   Overlays a solid-colored grid on the terrain. If a grid that covers
   the entire terrain is needed, select the terrain size in the Terrain
   Size dropdown box and leave the "Grid Bounds" settings alone; otherwise,
   set these values to the rectanglular region of the terrain where the
   grid should appear. (As usual, all settings are in Terragen units.)

   The "Grid Lines Along X/Y Axis" values set how dense the grid lines will
   be (higher values mean a denser grid). For instance, having 11 grid
   lines along a 257-unit axis will give a grid line every 25.7 units.
   An important point to note here is that if, for example, "11" is
   specified for an axis, there will be 10 rectangular regions on the
   terrain across that particular axis. That is why the minimum value for
   these settings is "2" (i.e., one grid line on one edge and one grid
   line on the other edge). So, the way this setting works, specify 1 more
   grid line than the needed number of enclosed rectangles across a
   particular axis: "6" if 5 enclosed regions are needed, "7" if 6 enclosed
   regions are needed, etc. Specifying "2" for both the X and Y axes will
   draw a simple rectangle.

   The Thickness setting sets the thickness of the lines in TG units. The
   Color setting does the obvious.

Tips
~~~~
When using the additive or subtractive functions on the Image Overlay,
use black for any area you don't want to appear. Remember the color
values are added (or subtracted), so bright colors will either make the
terrain either extremely bright or extremely dark, depending on whether
the color is added or subtracted.

The subtractive image overlay function turns the overlay image into a
negative. This function mainly exists so "fake" shadows can be projected
onto the terrain. (To make shadows, use dark shades of grey on the overlay
image. Remember the brighter the color on the overlay image, the darker
it'll appear on the terrain.)

Use the subtractive function on the surface distribution plugin to remove
a surface from a particular area, or the other functions to add a surface
to a particular area. Otherwise, surface distribution can only be controlled
based on slope and other parameters that Terragen allows you to control.

The surface distribution plugin also allows you to make a surface partially
transparent, which Terragen doesn't normally allow.

To create more accurate overlays for the map, use the layer functions
in an image editor to draw an overlay "on top" of an image of the terrain
you're working with.

When using the transparency overlay option, make sure absolute black
(RGB = 0,0,0) is used for any transparent areas. This means that if you
want to show black regions on the map, they can be visually black, such
as (RGB = 1,1,1), but still not be interpreted by the plugin as absolute
black.

Remember that all RGB Texture plugins can also be used to modify surface
distribution, but keep in mind that non-greyscale surface distribution will
not only change the distribution of the surface, but also the color of the
surface.