gaseous-giganticus.1

.TH GASEOUS-GIGANGICUS 1 "Dec 2015" "Space-Nerds-In-Space" "User Commands"

.SH NAME
gaseous-giganticus \- make 6 images forming a cube map for a gas giant planet 
.SH SYNOPSIS
.B gaseous-giganticus 
[ -a pole-attenuation ]
[ -b bands ]
[ -d velocity-field-data-file ]
[ -D fade-rate ]
[ -B band-velocity-factor ]
[ -c count ]
[ -C ]
[ -d velocity-field-dumpfile ]
[ -f fbm-falloff ]
[ -F velocity-field-dimension ]
[ -h ]
[ -H ]
[ -i input-file ]
[ -I image-save-period ]
[ -l ]
[ -m speed-multiplier ]
[ -n ]
[ -N ]
[ -o output-file-template ]
[ -O opacity ]
[ -p particle-count ]
[ -P ]
[ -r velocity-field-dumpfile ]
[ -R ]
[ -s stripe ]
[ -t thread-count ]
[ -v velocity-factor ]
[ -V ]
[ -w w-offset ]
[ -W wstep ]
[ --wstep_period period ]
[ -x number-of-vortices ]
[ --vortex-band-threshold threshold ]
[ --vortex-size size ]
[ --vortex-size-variance variance ]
[ -z noise-scale ]

.SH DESCRIPTION
.I  gaseous-giganticus
From a given input image, produces 6 images forming a cube map
for a gas giant planet.  
.PP
It works as follows.  6 square arrays
are arranged in a cube.  The cube is positioned within a 4 dimensional
Simplex noise field.   For each element in each of the 6 arrays, the
gradient in 3 dimensions is taken, forming a 3D vector.  The curl 
of this gradient field relative to the surface of a sphere enclosing the
cube is taken.  That is, each gradient vector is projected onto
the surface of a sphere enclosing the cube.  Depending on whether the
original gradient vector was "uphill" or "downhill" relative to the
surface of the sphere (pointing more away from or towards the center
of the sphere) the gradient vector is turned 90 degrees left or right,
respectively, within the plane tangent to the surface of the sphere
at that point.  This will produce a non-divergent velocity field which
can be used as a kind of fake incompressible fluid flow simulation.
Then, the velocity field is modified to add counter rotating bands.
.PP
Next, regions of the input image are mapped to the faces of the cube
(which is mapped to a sphere) Particles are randomly distributed onto
the surface of the sphere, and they are colored according to the
color of the image at the corresponding mapped location.  Then, the
particles are moved according to the velocity field.  At each iteration
the particles are projected into 6 images according to their position.
Also each image is very slightly faded towards the darkest color present
in the input image at each iteration -- this has the effect that the moving
particles leave fading trails on the images.  With enough particles the
fading trails are not visible, except in the small cracks where some small
divergences remain (this last may be due to some bug in the program.)
.SH OPTIONS
.TP
-a, --pole-attenuation
Attenuates band velocity near poles.  Without attenuation (value = 0.0f)
velocity of bands near poles is the same as velocity at the equator.  Due
to shorter distance around band near poles, this means the bands "spin"
faster.  Attenuating with a value of 1.0 means that the band velocity will
be adjusted to constant angular velocity.  A value of 0.8 means it will be
adjusted 80% towards constant angular velocity but will be 20% towards
constant linear velocity.  Lower attenuation means poles have higher angular
velocity (spin faster).  Default is 0.5.  Max is 1.0, min is 0.0.
.TP
-b, --bands 
Number of counter rotating bands.  Default is 6.0
.TP
-c, --count
Number of iterations to run the simulation.  Default is 1000
.TP
-C, --cloudmode
modulate output images to produce clouds
.TP
-d, --dump-velocity-field
Dump out velocity field data to the specified file after initial calculation.
.TP
-D, --fade-rate
Particle fade rate.  Default is 0.01
.TP
-i, --input
Input image filename.  Must be RGB or RGBA png file.
.TP
-I, --image-save-period
Interval of simulation iterations after which to output images.  Default is to
output images every 20 iterations of the simulation.
.TP
-k, --cubemap
Prefix of 6 cubemap RGB or RGBA png images to which '[x].png' is appended
with [x] taking on the values 0 through 5.
.TP
-l, --large-pixels
Use 3x3 pixels for particles instead of single pixel particles.  The allows getting away
with fewer particles and thus speeds up the process, however it will leave visible artifacts
at cubemap face boundaries so it is really only suitable for previewing.
.TP
-m, --speed-multiplier
Multiply band_speed_factor and velocity factor by this number.  It is a single
multiplier to affect both which is a bit easier than setting individual absolute
values for them.
.TP
-o, --output
Output image filename template.  Example: 'out-' will
produces 6 output files, out-0.png, out-1.png, ..., out-5.png
.TP
-O, --opacity
Specifies lower bound on particle opacity between 0.0 (transparent) and 1.0 (opaque).
Default is 0.2.
.TP
-w, --w-offset
w dimension offset in 4D simplex noise field Use -w to avoid (or obtain)
repetitive results.
.TP
-W, --wstep amount
w offset is periodically adjusted by specified amount and velocity field
is periodically recalculated.
.TP
--wstep-period period
Number of simulation iterations to run between updating the w value of the
four-dimensional noise field and recalulating the velocity field.  Default is
10.  Has no effect if --wstep is not specified. 
.TP
-f, --fbm-falloff value
Successively higher octaves of fractal Brownian motion noise are multiplied
by this value.  Default is 0.5.   So for example, the lowest octave of noise
is multiplied by 1.0, the 2nd octave by 0.5, the 3rd by 0.25, and the fourth
(last) by 0.125.  If fbm-falloff is specfied as 0.4, then the lowest octave
is multiplied by 1.0, the next by 0.4, the next by 0.16 and the last by 0.064.
.TP
-F, --vfdim
Set the velocity field dimension.  Default is 2048, yielding a velocity field
that is 6x2048x2048, which is quite large and can take considerable amount of
time to calculate.  Smaller values can produce quicker, but lower quality results
which can be useful for getting a quick preview.  Values below 128 will produce
rather strange results.  Minimum value is 16, maximum is 2048.
.TP
-h, --hot-pink
Gradually fade pixels to hot pink.  This will allow
divergences in the velocity field to be clearly seen,
as pixels that contain no particles will not be painted
and will become hot pink.
.TP
-H, --help
Print a help message and exit.
.TP
-n, --no-fade
Do not fade the image at all, divergences will be hidden
.TP
-N, --sequence-number
Do not overwrite each of the six output images each time they are written
(see the -I option).  Instead embed a sequence number in each of the six files.
This may be useful for producing a sequence of textures for animation.
.TP
-p, --particle-count
Use specified number of particles.  Default is 8000000.
.TP
-P, --plainmap
Use input image 6 times as the six faces of a cubemap.  This used to be the
default, but was usually overridden by the --sinusoidal option.  Now, the
sinusoidal option is the default, as it generally produces much more pleasing
results.
.TP
-v, --velocity-factor: 
Multiply velocity field by this number when
moving particles.  Default is 1200.0
.TP
-B, --band-vel-factor:
Multiply band velocity by this number when
computing velocity field.  Default is 2.9
.TP
-V, --vertical-bands
Make bands rotate around the Y axis instead of X axis
.TP
-r, --restore-velocity-field
Restore the velocity field data from a file created previously via the -d option
instead of calculating it from scratch.  This can save a lot of time if you are
happy with the fluid flows, but are experimenting with different input images.
.TP
-R, --random
Random values are used for bands, band-vel-factor, velocity-factor, noise-scale, and w-offset.
-S and -V options are also set.
.TP
-s, --stripe
Instead of using the whole image, use a vertical strip of the image (center) and
initialize particle colors to begin the simulation with stripes.  -V option affects
the orientation of the stripes.  Mutually exclusive with --sinusoidal option.
.TP
-S, --sinusoidal
Use sinusoidal projection of input image for initial coloring of particles.
-V option affects the orientation.  Mutually exclusive with --stripe option.
Sinusoidal is the default image projection.
.TP
-t, --threads
Use the specified number of CPU threads up to the
number of online CPUs.  Default is number of online CPUs.
.TP
--vortex-band-threshold
This option works in conjunction with the --bands option.  The --bands option specifies how
many counter-rotating bands encircle the planet.  If you imagine traversing from the north
pole to the south pole of the planet along a line of longitude, the velocity perpendicular
to the line of longitude varies smoothly, in a sine wave fashion, between -1 and +1, with
-1 and +1 being the regions of fastest movement, and 0 being no movement.  The
--vortex-band-threshold option specifies the maximum band velocity at which vortices may
be placed.  The default value is 0.4.  The effect is that vortices are forced to form
only in regions of low band velocity -- in other words, between the counter rotating bands
rather than in the middle of the counter rotating bands.  The range of this parameter is
clamped between 0.05 and 1.0;  If --bands is 0, then --vortex-band-threshold has no effect.
.TP
--vortex-size size
Make vortices (see --vortices option below) of the specified size which is expressed
as a fraction of the planet radius.  The default is 0.04, so the vortices produced will
have a radius which is around 0.037 times the radius of the planet.
.TP
--vortex-size-variance variance
This allows the vortex-size to vary by plus or minus the specified variance which is
expressed as a fraction of the planet radius.  The default value is 0.02.
.TP
-x, --vortices
the number of artificial circular vortices to add into the velocity field.
Default is zero.
.TP
-z, --noise-scale noisescale
Use the specified noise scale value.  Default is 2.6  This controls the
amount of the Simplex noise field that is sampled.  Smaller values will
give bigger whorls, larger values will give smaller whorls.  To give you
an idea of the range of values, see http://smcameron.github.io/space-nerds-in-space/gaseous-giganticus-noise-scale.html
I will attempt to describe the results of various scales below (descriptions of sizes are
approximate because I just eyeballed them.)

.DS
 0.12 Slightly wavy velocity field with features larger
      than the sphere.
 0.25 Wavy velocity field with features slightly smaller
      than the sphere.
 0.50 Wavy velocity field with whorls about 1/4th the
      diameter of the sphere.
 0.75 Lots more whorls about 1/8th the diameter of the sphere.
 1.00 Lots of whorls about 1/12th the diameter of the sphere.
 1.25 Whorls are smaller still.
 1.50 Whorls are maybe 1/20th the diameter of a sphere.
 1.75 Even smaller whorls.
 2.00 Smaller still.
 3.00 Whorls are starting to get chaotically small,
      maybe 1/40th diameter of sphere.
 6.00 Whorls are no longer primary feature instead
      sort blobby regions form.  As the noise scale
      gets higher, the blobby features get smaller.
.DE

.SH "EXAMPLES"
.TP

.DI
  ./gaseous-giganticus -V --sinusoidal --noise-scale 2.5 \\
        --velocity-factor 1300 --bands 10 --vortices 100 \\
	--vortex-size 0.04 --vortex-size-variance 0.02 \\
        -i input-image.png -o output-image-prefix
.DE

.SH "SEE ALSO"
snis_client, snis_server