Stereograph for linux, an advanced stereogram generator, v0.33b
(c) 2000-2003 by Fabian Januszewski <fabian.linux@januszewski.de>
------------------------------------------------------------------------------

Stereograph comes with ABSOLUTELY NO WARRANTY;
This is free software under the GPL, and you are welcome to redistribute it
under certain conditions;


TABLE OF CONTENTS

1.0 HOW TO INSTALL THIS PACKAGE
2.0 WHAT DOES STEREOGRAPH
	2.1 WHY ADVANCED?
3.0 RENDERER BASICS
4.0 REDNERING OPTIONS
5.0 TRANSPARENCY
6.0 SINGLE IMAGE STEREOGRAMS BASICS

For a VERY short summary of useful arguments ask the executable.



1.0 HOW TO INSTALL THIS PACKAGE


See INSTALL for a short reference.

Since release 0.17 libpng is required,
since release 0.32 libjpg is required.
In release 0.33 a rudimentary x11 interface was added.

There should be no problems if these libraries are properly installed.
Otherwise please take a look to the Makefile and modify it to suit
your system.

The current version of Stereograph is available at
stereograph.sourceforge.net.



2.0 WHAT DOES STEREOGRAPH


Stereograph is a stereogram generator. In detail it is a single image
stereogram (SIS) generator. That's a program that produces two-
dimensional images that seem to be three-dimensional (surely you know
the famous works of "The Magic Eye", Stereograph produces the same
output). You do _not_ need any pair of colored spectacles to regard
them - (nearly) everyone can learn it.


2.1 WHY ADVANCED?

Yes, that's an interesting question. I know that there are thousands
of SIS generators available out there. I bought one because I wanted
to create something special - but I was disappointed when I created my
first well-prepared composition. The quality was anything but
useful. In the third dimension (the depth of the image) I was able to
see different rough steps instead of really smooth transitions as
expected. I couldn't believe that. I had purchased a professional
program that should complete a serious job for me.  So I took a
pencil, a piece of paper and some time to find an optimized way of
processing stereograms. Stereograph is the result of all my inventions
related to this this problem. I implemented anti-aliasing for more
realistic level transitions and to follow exaclty the height structure
that is described in the base image. I added a zoom feature which has
the same effect but is more or less not useful for stereograms on a
computer screen but interesting for printing.  Additionally I expanded
the depth detail level of 256 levels to 765. If it should be one day
necessary to increase this level again, there are no limits to extend
this range up to 24 bits (16.7 millions) or even more, feel free.



3.0 RENDERER BASICS


  -b [base file]

     First of all we begin with a file describing the "relief" of our 3d
     model. The base file should contain all information about our
     object(s). It is a simple graphic where the brightness of a pixel
     defines its individual depth. The darker a pixel is, the more far away
     it will seem to be in the final stereogram - the brighter it is, the
     closer it will be. Usually only gray scale images are used to keep
     this information. As there are only 256 tones I decided to eliminiate
     this limitation. Of course, any gray scale image will be enough for a
     nice stereogram and can be used with stereograph. But for those that
     want to create smooth curved surfaces and so on, 256 levels are not
     sufficient. You should use the full bandwidth of 765 levels by using a
     special color map for rendering (POVRAY does a good job -
     www.povray.org). Internally the RGB values of each pixel are added to
     calculate the depth.

     For mathematically sophisticated individuals, Jean-Pierre Demailly has
     added the nice feature to compile c scripts on the fly that render a
     base. Please look at README.C for a quick overview of this feature.

  -t [texture file]

     Nearly everybody out there identifies with a stereogram the beautiful
     repetitive textures that are used to produce themselves. A good
     texture for a good stereogram needs a lot of love and details and some
     know-how or enough intuitive feelings to create one. The texture is
     the layer that everyone sees when regarding your stereogram - even if
     he cannot get in the third dimensions of your composition. Without an
     attractive texture you won't invite attractive visitors to your
     personal art work. ;)

     Technical note: the width of the texture stands for the maximum depth of
     any steregram and it cannot be greater than the distance of your two
     eyes - otherwise you won't be able to see anything in your stereogram but
     your beautiful great texture. As a hand rule, 100 should work nice for
     stereograms of 640*480 up to 800*600 pixels at most common screen
     resolutions. Use 110 to 120 for greater ones.

     For a quick look to the depth stereograph provides a  random texture
     generator. See below near '-w'

  -o [output file]

     The file where the stereogram is written to. If it exists stereograph
     won't ask for permission to overwrite it, it will just do it. The
     following file suffices are recognized by Stereograph:
     tga, png, ppm and jpg;

     output to stdout
     if no output file is specified stereograph writes the graphics data
     straight to stdout.

  -f [output format: tga/png/ppm/jpg]

     This optional argument let's you choose the output format Stereograph
     should write. Possible values are: "tga" for 24 bit uncompressed TARGA
     ouput, "png" for 32 bit compressed PNG output and finally "ppm" for
     PPM output; otherwise Stereograph will try to select the output format
     by the suffix of the output file name if there is one.



4.0 REDNERING OPTIONS

  Quality controling arguments

  -a <1 to 32>
     anti-aliasing
     describes a value between 1 and 32 that declares how many pixels shall
     be calculated by the renderer virtually for ONE pixel. So 1 is the
     absolute minimum, 4 is predefined. You can calculate easily: physically
     you habe n depth levels, where n is the width of the texture used for
     the stereogram. With the AA feature you now have theoretically a*n levels.
     This feature increases _massively_ the color depth of the output file -
     so always try to keep it in true color modes (24 bits or more). I've
     already converted different stereograms processed with AA (7+) to indexed
     ones and couldn't really feel a loss of 3d quality. It's always your
     decision and your former free disk space or net resources, a compromise
     with quality.

  -z <1 to 32>
     zoom
     based on the same idea as AA and has the same effects but physically
     increases the file size. Here 1 the minimum is predefined. It increases
     the width AND the height of the output stereogram by z - so be very
     careful with your free resources, it could end up in a great colorful
     mess...

     btw, for AA and zoom only integer values are expected.


  perspective

  -d <greater than 0.0 up to 8.0>
     distance
     describes the distance of your eyes and the virtual glass that is between
     you and your stereogram. Default value is 5.0 since release 0.30a, feel
     free to walk backwards up to 20.0 steps. 1.0 distance points reflect the
     distance between the screen and the maximum depth.

  -p <greater than 0.0 up to 1.0>
     front factor
     defines the depth of the nearest point (typically mere white). This value
     should be rendered linear which means that for a doubled value depth
     contrast of the scene should be doubled too.

  -e <-1.0..1.0>
     eye shift
     controls the perspective along the x axis (left to right). That is if e is
     positive the image is shifted slightly to the right. The predefined value
     of 0.0 is exactly the centered perspective.


  layout

  -x <0..(base image width) - (texture width) - 1>
     texture instert x
     where the texture is inserted the first time and where the rendering
     process begins its rounds. standard: 0 (left image border);

  -y <0..texture height - 1>
     texture instert y
     y offset of the texture. standard: 0 (top);

  -w <1(theoretically)..texture width/base width - 1>
     this argument specifies the texture width to use for the stereogram. This
     option tells stereograph to generate a random texture or if a texture was
     defined it resizes the texture to match your dimension. This can be very
     useful when rendering transparent stereograms with a lot of different
     textures that all differ in their width. Note that this can only reduce
     the width and stereograph doesn't care about image ratios. It just cuts
     your texture. Random textures cannot be used with transparent rendering.

  -M, -G, -C, S
     use one of there flags to define which color type the random texture
     should conform to. Use -M for monochrome, -G for a grayscale or -C for a
     random color texture. Please note that the random texture feature cannot
     be combined with transparent rendering and that anti-aliasing increases
     the color depth of you image - even if you use a monochrome texture.
     To disable anti-aliasing use '-a 1'.
     The -S flag is experimental - it generates an artistic random texture.


  aid
  
  -A this flag will add a pair of black triangles at the top of the stereogram
     to make it easier for unexperienced eyes to achieve the magic view.
     

  base options

  -I inverts a base (non-transparent rendering only);

  -l [level adjust type: none/back/top]
     adjusts the base levels for transparent rendering;
     the keyword 'none' keeps the defined height levels of the base images;
     the keyword 'back' adjusts the bottom area of all upper layers to the
     level defined by the preceding layer;
     the keyword 'top' adjusts the areas of upper layers that are not as far as
     the preceeding layer to the level of the preceding layer;


  disable linear rendering algorithm

  -L this option disables linear rendering


  the anti-artefacts feature

  -R this feature is enabled via the -r flag and tells stereograph to process
     every second line in reversed order to prevent artefacts. This flag should
     be used only with random textures. I am working on a more stealth
     algorithm that could be used with any texture. Please inform me about your
     experiences with this feature! Your feedback is important in the further
     development of this idea because as I know this implementation is really
     unique.


  output types

  -v orders stereograph to tell you everything he's doing;


5.0 TRANSPARENCY

Transparent stereograms are rendered in the same way as normal stereograms.
Stereograph accepts the same parametres, so the only difference for you is to
define more than one input base file and provide respectively the same number
of textures. The different bases must have the same dimensions, the textures
must equal themselves in the width. Otherwise stereograph will complain and
even not initialize the renderer.
Since release 0.29a transparent rendering needn't to be enabled via the -T
flag.

Examplecommand line:

> stereograph [ADDITIONAL OPTIONS] -b glass0.png glass1.png glass2.png\
	-t tex0.png tex1.png tex2.png -o glass_demo.png

or, running on a sh compatible shell you may simply use

> stereograph [ADDITIONAL OPTIONS] -b $(ls glass?.png) -t $(ls tex?.png)\
	-o glass_demo.png

At the moment there's no modifier for manipulating the alpha channels. The
alphas that may be defined in your png or targa files are ignored for now.
This feature is ALPHA. Please inform me about your experiences!


6.0 SINGLE IMAGE STEREOGRAMS BASICS

First of all, some basic rules.

As you can see any stereogram is composed of a texture that is repeated n times
on a horizontal line but not very regularly. There is a simple rule: the more
complex the scene, the more complex the resulting stereogram appears and the
more difficulty it becomes for a human being to regard it in its three
dimensions. The greater the contrast in the scene, the more artefacts are
produced as by-product of the rendering process and the fact that not every
pair of pixels on the screen is unequivocal for our eyes.

Before we discuss the necessary design properties of the three dimensional
scene you should know, that the texture design is at least as important as the
design of the scene. The more details a texture offers the more details from
your scene the final stereogram can offer to the spectator.
Finally the nicer your texture the more attractive your artwork becomes for the
people out there.

There are a lot of ways to produce a useful scene. For your first steps you can
simply use a graphics program like the GIMP for example. You will learn how to
use the different depth values as effective as possible. Put some text in your
scene to test the ability of detail reproduction of your texture. Not every
text and every font is readable in a stereogram but feel free to play with it!
Use small differences in your scene and try to avoid huge contrasts on the
horizontal line. In vertical direction you can do what you want - this behavior
won't result in any artifacts that may attack your beautiful stereogram.

Artifacts result of symmetric pixel distance constellations that result of
typical height structures of a scene in combination with a typical texture
constellation. Some shifting of the texture along x or y, some changes in the
texture or some adjustments of the eye perspective or of the distance could
correct this. If nothing helps, alter the width of your texture by one or two
pixels, that should be enough.