packages icon

 xpgs(6)                          Xpgs 2.5                           xpgs(6)
                                November 1994

      xpgs - a suite of programs to design, generate and animate SIRDS for
      the X Window System, and output SIS or autostereograms in a variety of

      xpgs [options] <polyh or xss file>

      SIRDS stands for Single-Image Random Dots Stereogram; other common
      terms are RDS, SIS and autostereograms though these do not strictly
      apply to, or imply, SIRDS.

      The theory of SIRDS and autostereograms can be found in many postings
      to alt.3d (including a FAQ obtainable from and,
      there are also some books around which deal with the subject. Some
      information can be obtained on RDS from Bela Julesz's book
      "Foundations of Cyclopean Perceptions"; a more recent source of
      information is the paper by Thimbleby et al called "Displaying 3D
      images: Algorithms for SIRDS", available from Stuart Inglis
      (; also there is a short article called
      "Stereography and Autostereograms" by the author of this package which
      can be found, along with a gallery and URL links to other WWW pages on
      SIRDS, at  Further resources
      can be found at the main SIRDS at

      In this suite of programs, we start with a description of a volume of
      space using Cartesian coordinates to label the vertices of the objects
      within the space and lists of the polygonal faces which define each
      object.  The coordinate axes are defined as x - horizontal (right), y
      - vertical (upward) and z - perpendicular to the screen (toward the

      With this description, two buffers are built using a method described
      in the article mentioned above.

      There are two basic types of autostereograms, these differ in the way
      the image is viewed. The two possibilities are wide-eyed (WE) and
      cross-eyed (CE) viewing. For whatever reasons, some people find it
      much easier to look at SIRDS cross-eyed though the vast majority learn
      to see them wide-eyed.

      The parameters of the programs are :-
         VD = viewing distance from the screen or paper (300mm)
         ES = eye separation (65mm)
         OS = offset of coordinate origin into (or out of) screen or paper
      The background plane is set at the offset OS+OY, this can be changed
      with the -background option.

 (c)1994 by Peter Chang             - 1 -                           xpgs 2.5

 xpgs(6)                          Xpgs 2.5                           xpgs(6)
                                November 1994

      The default options are set to give a reasonable wide-eyed (WE) SIRDS
      of the objects on top of a background plane.

      A layout of the suite's programs and associated data follows

             3d datasets
              cvtopolyh     mkpolyh
                  |            |
                  |            |
                  |            |
            /-------------------------\     paint package
            |            |            |     ^
            |  (.polyh)  |  (.polyh)  |     | (.p?m)
            |            |            |     |
            v            v            v     v
          xss --------> xpgs -------> cvtoppm <------ mindimage
            |  (.xss)    |             |   |   (.rle)
            |            |      (.p?m) |   |
            |            |             v   |
            \-------------------> sisgen   \----------> vpgs
                       (.xss)        |        (.p?m)

      MindImage is a PC SIRDS generator, xv is the X11 graphics viewer. The
      data files are differentiated by their name extensions given in
      parentheses.  Although not shown on the diagram, xss, vpgs and xpgs
      can save an image in X11 bitmap (.xbm) format and vpgs and xpgs can
      also save an image as a Postscript (.ps) file.

      .polyh  We have incorporated one 3D data format into xpgs:

                 AVS polyh - list of vertices and list of polygonal faces
                 given by indexed points.

              (There is a slight difference with the inclusion of an
              optional comment line at the start of the file which begins
              with a hash "#".)

              Additional objects can be converted into this format using the
              cvtopolyh program, it is able to change X3d v2.0 .obj files,
              Wavefront .obj files and another format .3ds (I can't remember
              what program uses this). New objects defined by functions can

 (c)1994 by Peter Chang             - 2 -                           xpgs 2.5

 xpgs(6)                          Xpgs 2.5                           xpgs(6)
                                November 1994

              be made using mkpolyh.

              We have bundled some objects for you to try out - regular
              solids in polyh format and a couple of objects converted from
              X3d v2.0 objects and Wavefront objects.

              More objects can be found at
              or its mirrors.

      .rle    This is MindImage's data format using a basic run length
              encoding method with indexing.

      .p?m = .ppm and .pgm
              These are the colour and grey-scale portable pixmap formats
              from the PBM packages (NetPBM or PBMPlus).

      .xss    This is a simple description format of a scene made from
              multiple polyh objects.

      Xpgs is an X11 program that generates, animates and outputs SIRDS.  It
      takes an .xss or a .polyh file and optional switches as its command
      line arguments.

      All these options can be abbreviated to the least letters needed to
      make the chosen option distinct.  The default values are given in

      -display <display>
          sets the X display name. By default it is the local host or that
          one defined in the environment variable DISPLAY.

      -geometry <geometry>
          sets the X geometry. (770x476 or 720x445)

      -wait <delay>
          specifies the delay between frames in milliseconds used during
          animation. (300)

      -frames <1-24>
          gives the number of frames for xpgs to generate. (1)

          If xpgs was compiled with the XPGSUSEPM macro defined then the
          number of frames of animation possible depends on the X server
          memory allocation, ie. the number of big Pixmaps it can support.
          If your server can't handle a large number then either give xpgs a
          smaller number of frames, eg. "-f 3", or recompile xpgs without
          the -DXPGSUSEPM flag in the Makefile ( or descrip.mms).
          Note if you take the latter option then the animation may not be
          as fast as using Pixmaps, the performance depends on the X server.

 (c)1994 by Peter Chang             - 3 -                           xpgs 2.5

 xpgs(6)                          Xpgs 2.5                           xpgs(6)
                                November 1994

      -background <b>
          sets the background plane at z=b*OY. (-1.0)

          sets xpgs to cater for crosseyed viewing, by default it caters for
          wide-eyed viewing.

      -enlarge <ef>
          specifies the enlargement of depth effect in the final image.

      -mag <mf>
          sets the magnification of the scene. (1.0)

      -paper <wxh>
          specifies the size of array for Postscript output.

          turns off indicators in window (used to aid the viewing process).

      -zblines <zb>
          sets the number of lines that each z-buffer will use. (256)

          This limits the internal size of all z-buffers used in the program
          without affecting the size of the stereogram output. It should be
          used only when memory constraints are more important than speed
          considerations: the smaller the value is the slower the program
          will become.

      -DENSITY <0-255>
          sets the density of black dots in the SIRDS. (127)

      -GREY <1,2,4,8>
          sets the number of grey-scale bits used in Postscript output. (1)

          sets xpgs to the shimmer mode, to aid newbies.

          prints a summary of command line options and returns to shell.

      Once running, it will display a few parameters in the terminal window,
      create a empty graphics window and start to generate the SIRDS(s).
      Each frame will be shown in sequence as the program proceeds.  When
      finished, the program displays the "all done" message and enters the
      pause mode.

      With the mouse pointer within the boundaries of the graphics window,
      xpgs will respond to a set of keypresses.

 (c)1994 by Peter Chang             - 4 -                           xpgs 2.5

 xpgs(6)                          Xpgs 2.5                           xpgs(6)
                                November 1994

            q   quits the program.
            h   pops up a help window.
            a   changes the rotation axis randomly.
            i   re-initialise all of the points.
            p   toggles the pause mode on and off.
            r   reverses the sequence of frames.
      While paused:
            c   saves the current frame in .xss format.
            l   loads a new object.
            n   skips to the next frame.
            s   saves the current frame as a Postscript file.
            w   saves the current frame as a X11 bitmap.

      See xss(6) about mouse controls and popup dialogue windows.

      If you find any bugs, please report them to one of the authors listed

      cvtopolyh(6), cvtoppm(6), mkpolyh(6), sisgen(6), vpgs(6), xpgs(6) and

      Copyright 1994, 16th November and 14th February.
      By Peter Chang and Gareth Richards. All rights reserved.
      Version 2.5

      Permission to use, copy, modify, distribute, and sell this software
      and its documentation for any purpose is hereby granted without fee,
      provided that the above copyright notice appear in all copies and that
      both that copyright notice and this permission notice appear in
      supporting documentation, and that the name of the copyright holder
      not be used in advertising or publicity pertaining to distribution of
      the software without specific, written prior permission. The copyright
      holder makes no representations about the suitability of this software
      for any purpose. It is provided "as is" without express or implied

      The copyright holder disclaims all warranties with regard to this
      software, including all implied warranties of merchantability and
      fitness, in no event shall the copyright holder be liable for any
      special, indirect or consequential damages or any damages whatsoever
      resulting from loss of use, data or profits, whether in an action of
      contract, negligence or other tortious action, arising out of or in
      connection with the use or performance of this software.

 (c)1994 by Peter Chang             - 5 -                           xpgs 2.5