gaseous-giganticus.1

.TH GASEOUS-GIGANGICUS 1 "May 2016" "Gaseous Giganticus" "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 ]
[ -B band-velocity-factor ]
[ -c count ]
[ -d velocity-field-data-file ]
[ -D fade-rate ]
[ -e band-speed-power ]
[ -E image-height ]
[ -d velocity-field-dumpfile ]
[ -f fbm-falloff ]
[ -g gain ]
[ -F velocity-field-dimension ]
[ -h ]
[ -H ]
[ -i input-file ]
[ -I image-save-period ]
[ -k ]
[ -K cache-aware-particles ]
[ -l ]
[ -L noise-levels ]
[ -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 ]
[ -T thread-iterations ]
[ --trap-nans ]
[ -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.
The gradient vector is rotated 90 degrees about an axis passing through
the center of the sphere and a point on the surface of the sphere
corresponding to the array position, always the same direction
(always clockwise or counterclockwise, doesn't matter which, so long
as it's always the same),
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
-d, --dump-velocity-field output-file
Dump out velocity field data to the specified file after initial calculation.
.TP
--dump-flowmap output-file
Dump out velocity field data to a series of six RGB png files with x and y velocities
encoded in the R and G channels. If the output-file is specified as, e.g. 'ABC', then
the output files will be ABC-1.png, ABC-2.png, ABC-3.png, ABC-4.png, ABC-5.png and
ABC-6.png  Note: The flowmap produced by this option is not correct, and has problems
at the seams between the cube faces. I tried 3 different ways to make this work but
never succeeded.
.TP
-D, --fade-rate
Particle fade rate.  Default is 0.01
.TP
-e band-speed-power
An exponent that controls width of counter-rotating bands. The value must be an odd
positive integer.  Default is 1.
.TP
-E, --equirectangular
Output an equirectangular image in addition to the usual cubemap images.
The image height must be an integer power of 2. The image width will be
twice the height. The file will be named ending with "-eqr.png".
(See -o option).
.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
Allow specifying a cubemap image as input to be used as a starting point.
The name specified is used as a prefix of 6 cubemap RGB or RGBA png images
to which '[x].png' is appended with [x] taking on the values 0 through 5.
By using this, the output of gaseous-giganticus can be used as input, and
further swirling may be done, e.g. at different scales, or the output of
other programs that produce cubemaps may be "swirled" to create
for example cloud cover images for earthlike planets.
.TP
.TP
-K --cache-aware
Allow specifying what fraction of particles should be positioned in a
cache-aware manner.  The allowable values are between 0.0 and 1.0.  0.0
means 100 percent of particles should be initially placed randomly on the
surface of the sphere.  1.0 means each particle should be placed on the
surface of a sphere in such a way that particles close in memory will refer
to velocity field array members also close in memory.  The regular grid
like positions of cache-aware placement of particles can result in some
artifacts, considerably mitigated by adding some jitter, and supplmented
by using some random placement.  The default value is
((1024.0 * 1024.0 * 6.0) / 8e6) so that of 8 million particles, about 6
million -- just enough to cover every texel of the 1024x1024x6 cubemap
-- are placed "cache-aware", and the remaining ~2M are placed randomly.
(8000000 being the default number of particles.) Using 100 percent
cache aware particle placement leads to a cache miss rate of about 50%,
while 100% random particle placement leads to about a 60% cache miss
rate.
.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
-L, --noise-levels
Number of fractal browning motion noise levels to use.  Default is 4, minimum is 1, and
maximum is 7.
.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.
If the -E option is active, an additional equirectangular image
will be output, out-eqr.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. Note: this will drastically increase runtime.
.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 specified 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.
-g, --gain
2nd and successive octaves of fbm noise are multiplied by
pow(fbm-falloff, (octave - 1) * gain). Default value is 1.0. Assuming that
fbm-falloff is less than 1.0, gain should be between 0.0 and 2.0. Values larger
than 1.0 give more prominence to lower octaves (noise will be smoother) while
values lower than 1.0 give more prominence to higher octaves (noise will be
rougher).
.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.
Using a smaller number may be useful for reducing runtime and
getting a lower quality preview of how things will look.
.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 chosen from reasonable ranges 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
-T, --thread-iterations
Number of iterations particle movement threads should execute before joining
and painting particles.  Default is 1.  Increasing this can increase the ratio
of CPU time spent moving particles as compared to painting particles, potentially
reducing total elapsed time. However, if too high, particles may move too far
between painting. You may also wish to decrease image-save-period if you increase
thread-iterations. Image-save-period is by default every 20 thread invocations.
.TP
--trap-nans
Use feenableexcept(3) to trap divide by zero, invalid and overflow floating point exceptions.
.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