
                             STRUVIR
                     = STRUPLO (91) to VRML
                  beta-4 test version  April, 1998
                          By A. Le Bail
                        See the tutorial at :
         http://fluo.univ-lemans.fr:8001/vrml/struvir.html
 ======================================================================
                      HYSTORY of this version
                      +++++++++++++++++++++++
          STRUPLO is the R.X. Fischer free structure drawing
             program recognizing tetrahedra and octahedra
            R.X. Fischer, J. Appl. Cryst. 18 (1985) 258-262
          Augmented by A. Le Lirzin, 1989 (COLO, PRES, BZRR)
               for the recognition of other polyhedra
     and by D. Kassner, 1990 (RES, NRES in PARA, incorporation of
     Burzlaff routine in SPGR, logic of VIEW and ROTA, addressing
        in SHAD, reorganization of COMMON-block structure).

 Received at MSU 17Aug92, via Tim McCarthy from Giaquinta at MIT.
    M.S.U. writeup by Donald L. Ward from the original by W. H. Baur.
        
 Received at Laboratoire des Fluorures March 1996, via D.L. Ward
    by A. Le Bail
    HPGL and VRML capabilities added.

 Version enhanced with output for Povray by Mark Koennecke, July, 1996.
    See his comments at the end of this file.

 New version compiled with Digital Visual Fortran - April 1998
 This version compatible with the VRML 2 viewer Cosmo Player 2

======================================================================
INTRODUCTION

       STRUVIR
             is a converter of STRUPLO (R.X. Fischer) data files
             into VRML (Virtual Reality Modeling Language) .wrl
             files for 3D visualization. (Netscape+Live3D or
             VRweb, or any Internet browser equipped with a
             VRML plug-in, or any standalone VRML viewer enabling
             two-sided lighting of faces...).

             IMPORTANT: Your old datafiles working for STRUPL91
             work for STRUVIR too ! There has been no change on
             entries apart the file should be a .dat instead of
             a .inp file. All the previous STRUPLO capabilities
             in preparing output files for drawing structures are 
             available for HPGL and POSTSCRIPT. An output for
             POVRAY differenciated the beta 3 version from the 
             beta 2 (thanks to Mark Koennecke). The beta 4 has
             some bugs corrected (for instance spheres were not
             drawn if polyhedra had not been found - this has
             been corrected).

             STRUVIR is built from a STRUPLO basis modified without
             permission, following the Academic tradition which
             allows not reinventing the wheel each day. In this
             case, the wheels are the STRUPLO polyhedra recognition
             algorithm, thanks to R.X. Fischer and A. Le Lirzin, and
             VRML of course. So my job was only to combine them.
             Were the changes sufficient for changing the name ?
             You may decide : STRU for STRUCTURE in STRUPLO and
             VIR for VIRTUAL in VRML. The VRML part is working
             better than the PS/HPGL drawing part in most cases.
             The latter part may crash when the former do the job.

       Hardware
             The current version is 32 bits and works on MS WINDOWS 95
             and probably (but not tested) on MS WINDOWS NT.
             Note that the FORTRAN 77 source is available and should
             compile on any machine. This is a project of CCP14 to
             include STRUVIR in its program base.

       How to (MS WINDOWS 95)
           Install : unzip struvir.zip

           Run :
             Double-click on STRUVIR.EXE and follow the instructions :
                 give the data file name without the .dat extension
                 and decide if you really want the drawing.

       Entry
             A conventional STRUPLO (91) file (*.dat).
             Many such files are delivered with the package.

       Output files
             If name.dat was your entry file prepared as below for
             a STRUPLO typical file, then STRUVIR will create :

             struvir.imp    ASCII file containing some useful
                            informations like distances and angles.
                            It will be necessary to edit this file
                            in order to verify if distances choosen
                            for finding polyhedra are correct.
             po.wrl         the VRML file for polyhedra 3D view.
                            Actually, are recognized polyhedra having
                            3 to 12 vertices.
                            Spheres may be obtained by the STRUPLO
                            CIRC option. They are all with a 0.5
                            Angstrom radius.
             wi.wrl         the VRML file for wireframe 3D view.
             struvir.hgl    a 2D HPGL (HP7475) drawing that you
                            may see with a HPGL viewer or insert
                            into MS WORD 2 or 6 using the convenient
                            image format (HGL). From MS WORD, you
                            may also export the drawing to the
                            clipboard and get it with Paintbrush as
                            a .bmp file, export to Lview31 and change
                            to a .gif or a .jpg.... etc..
             struplo.xyz    the entry file for the PSPLOT program
                            creating struplo.ps for Postscript
                            output
             struplo.pov    the entry file for Povray 

    COLORS
             You may play with colors at two independent levels
             for the HPGL/PS outputs and VRML/Povray outputs.

       VRML/Povray: Twenty colors are available. The choice is made by
             playing on the atom name order.

             The following example has 3 different kind of atoms
             CO (Co), S and O. They will be attributed colors number
             1, 2 and 3 respectively. If polyhedra (octa or tetra)
             are recognized around CO, they will be drawn with
             color attributed to CO (not the color attributed to O).
             Changing colors is possible by changing the atoms order.

  TITL COSO4 H2O  C2/C
  CELL   6.963 7.580 7.470 90. 116.30 90.
  SPGR C 2/C
  FORM 4
  VIEW 0 1 0
  XYZR -0.25 2.25 -0.25 2.25 -0.25 2.25
  OCTA 90 20 2.05 0.25
  TETR 109. 20. 1.5 0.2
  PARA 1 1 1 1 1 1 1 2.6
  END
  CO 1         0.25     0.25     0.0                       Color 1
  S  1         0.0      0.093    0.25                      Color 2
  O  1         0.203    -.017    0.362                     Color 3
  O  2         0.021    0.196    0.104                     Color 3
  O  3         0.0      0.615    0.25                      Color 3


       For instance if you want SO4 tetrahedra drawn with color 4,
       and CoO6 octahedra with color 5, this is possible by : 

  OA 1         0.203    -.017    0.362                     Color 1
  OB 2         0.021    0.196    0.104                     Color 2
  OC 3         0.0      0.615    0.25                      Color 3
  S  1         0.0      0.093    0.25                      Color 4
  CO 1         0.25     0.25     0.0                       Color 5

      Compare the results from files CSO4H.DAT and CSO4H2.DAT

      It will be difficult, but not impossible to play with more
      than 5 colors with this example.


      And the 20 colors (care no more) are :

                            R       G       B
     1  Blue sky            0.0     1.0     1.0
     2  Green light         0.5     1.5     0.0
     3  Red pyrope          1.0     0.1     0.5
     4  Yellow              1.0     1.0     0.0
     5  Blue grey           0.6     0.6     1.0
     6  Orange              1.0     0.6     0.0
     7  Purple              0.5     0.0     0.5
     8  Brown               0.5     0.3     0.0
     9  Blue-green-dark     0.0     0.5     0.5
    10  Red                 1.0     0.0     0.0
    11  Green               0.0     1.0     0.0
    12  Blue                0.0     0.0     1.0
    13  Pink                1.0     0.0     1.0
    14  Red dark            0.5     0.0     0.0
    15  Green dark          0.0     0.5     0.0
    16  Blue night          0.0     0.0     0.5
    17  Red wine            0.5     0.05    0.25
    18  White               1.0     1.0     1.0
    19  Grey                0.5     0.5     0.5
    20  Black               0.      0.0     0.0

 Colors for HPGL and PS output are those defined in the
 STRUPLO 91 manual below.

  TO DO
       Implementation of more efficient capabilities will be done
       only if there is some interest from users. The .exe was
       created by MSVC++2.00 from the C source obtained by applying
       f2c to the FORTRAN source (using libi77.lib, libf77.lib and
       f2c.h). Sources may be obtained for free. So why not to
       improve the program by yourself and to propose your
       version as a freeware with sources (you may not like colors
       I have selected, for instance...).

       Interesting changes could be :
             -automatic recognition of other coordinations >12
             -different sizes for spheres as it is possible for circles
             -ball and stick and other rendering
             -optimization of VRML 1 enabling more viewers to show
                 something
             -introducing VRML 2
             -allowing labelling
             -making a better manual in HTML
             -.....
                            

       Possibly there could be different kinds of problems. The  .dat
       files delivered with STRUVIR.ZIP have been tested and visualized
       successfully with the VRweb and Live3D viewers. This
       is unsufficient for claiming bug absence. Particularly, the
       coherency of shading according to light sources has not been
       checked : the drawing is sometimes 'bizarre' as stated by some
       pre-beta testers. Viewers like Cosmo Player from SGI and the
       Microsoft VRML Add-in will not give good results essentially
       because the STRUVIR VRML output is not well optimized. Only
       those viewers enabling two-sided face lighting in VRML 1 should
       be used. Also, you may find that 'flat shading' renders better the
       VRML STRUVIR files than 'smooth shading'.

       At least, respect the limits : 1000 polyhedra, 6000 atoms, 20
       colors, 150 atoms around one atom in distance calculation...
       Non respect may lead to crash in some cases although the
       program should stop by itself with an explanation for the
       user.


       BUGS CORRECTION

          March, 01 1996 : was not possible to obtain more
             spheres than atoms involved in polyhedra.
          March, 27 1996 : Live3D under Windows 95 loaded the
             .wrl files then Netscape 2.0 crashed ! Nothing such
             happened under Windows 3.11. A ",-1" was lacking
             somewhere.
          July, 11 1996 : A. J. Holland during his work for
             including executables of STRUVIR for various
             platforms in the CCP14 suite found that some data
             files produced crash on DEC ULTRIX, ALPHAVMS an
             VAXVMS only. The 2002 FORMAT in the subroutine
             WRITE produced sometimes lines exceeding 132
             characters.    
          July, 26 1996 : added one line in the documentation.
                      ALL CHARACTERS IN UPPERCASE
             Care to respect exactly the way the commands are
             defined in the documentation. Thanks to Mark Koennecke. 

       ADVICES FOR SOME UNSOLVED PROBLEMS
           In option CIRC, prefer small sizes like CIRC 0.03 CS
           instead of CIRC 0.30 CS (the hgl file will give Cs
           atoms as points but the .wrl files will be OK, 
           otherwise nothing may work because STRUPLO has problems
           -apparently- with superposed circles...).

           Sometimes polyhedra may appear uncomplete when the
           range selected by the XYZR option is small. There is
           a simple way to deal with this bug in VRML. The .wrl
           ASCII files may be edited and the uncomplete polyhedron
           may be easily recognized and deleted. Data concerning
           each polyhedron in po.wrl begin by a comment line
           like the following :

# POLYHEDRON   46  YB
Material{diffuseColor   .000 1.000 1.000
    specularColor 0.5 0.5 0.5
    shininess 0.2 }
Coordinate3{point[
        -.101   5.419   2.710,
        1.762   4.065   4.133,

        .......etc

 2, 6,-1,
 1, 7,-1,
 4, 7,-1 ]}
# POLYHEDRON  228  YB
Material{diffuseColor   .000 1.000 1.000

.....etc

# POLYHEDRON   39  YB

......etc                        SO you have just to delete
                                 the undesired polyhedron. 
                                 Numbers 46, 228, 39 etc are those
                                 easily found in the atom list
                                 in the output file struvir.imp


Have Fun and Good Luck,



A. Le Bail
Laboratoire des Fluorures
CNRS URA 449
Universite du Maine
72017 Le Mans Cedex
FRANCE
Email       armel@fluo.univ-lemans.fr
Home Page   http://fluo.univ-lemans.fr:8001/

======================================================================

                 Following is the STRUPLO 91 manual
                slightly modified to fit with STRUVIR:

======================================================================

        TABLE OF CONTENTS
                                                     page
           RUNNING THE PROGRAMS    . . . . . . . . .   1
           DETAILED INPUT DESCRIPTION  . . . . . . .   2
             A) INSTRUCTIONS   . . . . . . . . . . .   2
             B) ATOM PARAMETERS  . . . . . . . . . .   9
             C) EXAMPLES   . . . . . . . . . . . . .  10
             D) FILES AND I/O ASSIGNMENTS  . . . . .  34
        
        -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -

        RUNNING THE PC PROGRAMS

        To run STRUVIR, one first creates an initial name.dat data file 
        (see DETAILED INPUT DESCRIPTION, below) necessary to prepare
        specific drawing. The name.dat file should be on the same 
        directory as the executable STRUVIR.EXE.
     
        Then, either run STRUVIR with the command

           STRUVIR            if you are in a DOS box opened in the
                              appropriate directory
              or double click on STRUVIR.EXE from the file gestionnaire.
 
        Then you will be prompted to give the data filename 'name' without
        the .dat extension.
              
        STRUVIR then reads the name.dat file and creates the printable output
        file struvir.imp, the wireframe VRML file wi.wrl, the polyhedra
        VRML file po.wrl and the struplo.pov output for Povray. You will
        have the option to create or not the generic plot file struplo.xyz
        for PS output and the HPGL plot file struvir.hgl.


        Then, four possibilities are offered for drawing :

        1 - Open either the wi.wrl or po.wrl files by your
            favourite VRML viewer, play with the 3D view, select
            a 2D projection, save it by a sreen copy after having
            choosen the maximum monitor resolution (800x600 is
            sufficient for preparing the view, 1280x1024 or more
            is better for saving the choosen 2D projection). Then
            the saved sreen copy may be pasted inside your
            preferred graphics software for manipulation (Lview31
            and so on or better), stored as .gif or .jpg, etc.


        2 - Run PSPLOT with the command

           PSPLOT

        This reads the struplo.xyz file and creates the PostScript plot 
        file struplo.ps which can be printed by a PostScript printer to 
        produce the actual hard-copy drawing. For instance you may type
        in a DOS box:
           TYPE PSPLOT.PS > LPT1

        3 - Insert struvir.hgl in MS WORD2 or WORD6 as an image or in
        a HPGL viewer and print or save. You may select all and copy
        to the clipboard, then paste in Lview31 or any software you
        may want.

        4 - Use the struplo.pov file to create an artistic drawing by
            Povray.



        STRUVIR Instructions
        ---------------------
        (page 2)


        DETAILED INPUT DESCRIPTION

        The input of all data is in free format.   Numbers or symbols
        are separated by blanks, typed in any arbitrary column between 
        columns 5 and 80.   The first four columns of the instruction
        data are reserved for options specifying the type of instruction.
        Any text in the first four columns, other than the options listed
        here, will be ignored.   Numbers can be given as integer, 
        floating point, or floating comma numbers; all three types will
        be transformed to floating point numbers.   Atom parameters
        may be given in free format or fixed format as described below.

        WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING :

        ALL CHARACTERS IN UPPERCASE (ex: TITL, CELL, SPGR, SYMM, PARA ...)
        INCLUDING ATOM NAMES (ex: H, LI, BE, AL, CO... not h, Li, Be, Al, Co).
        INCLUDING SPACEGROUPS (ex: P M M M, C 2/C, F D 3 M...)

        TYPICAL EXAMPLE FILE :

        TITL COSO4 H2O  C2/C
        CELL   6.963 7.580 7.470 90. 116.30 90.
        SPGR C 2/C
        FORM 4
        VIEW 0 1 0
        XYZR -0.25 2.25 -0.25 2.25 -0.25 2.25
        OCTA 90 20 2.05 0.25
        TETR 109. 20. 1.5 0.2
        PARA 1 1 1 1 1 1 1 2.6
        END
        CO 1         0.25     0.25     0.0                      
        S  1         0.0      0.093    0.25                     
        O  1         0.203    -.017    0.362                     
        O  2         0.021    0.196    0.104                     
        O  3         0.0      0.615    0.25                      


        A) INSTRUCTIONS
        ---------------

        The sequence of instructions is arbitrary except that TITL and 
        END must be the first and last options, respectively, followed
        by the atom parameters.


        1. Heading comment

           Option : TITL text
           Default: TITL (blank)

             Up to 40 characters can be plotted as a heading.   TITL 
             must be the first option, even if the text is left blank.
             Subsequent lines, starting with TITL, are without action
             and can be used as comments.


        2. Output control (some are obsolete in STRUVIR : take the
                           default options, do not put any MODI line)

           Option : MODI D PA1 PA2  AR1  AR2  OR1 OR2
           Default: MODI 1  0   0  28.8 21.6   0    0   

           D -  selects the plotting device.   D is not used in the 
             STRUPLO version of June 86.   This can be modified by the 
             user in subroutine DRAW where D has the variable name ID.

           PA1 PA2 -  are length and width of the paper; these parameters
             are only needed for the PAGE call in the DISSPLA software.

           AR1 AR2 -  are length and width defining the plotting area.
             The plot will be scaled with regard to these parameters.

           OR1 OR2 -  are coordinates in cm (or inches) to translate the 
             plot.   This usually will cut off the plot, but might be 
             desired in special cases.

             In most cases this option can be omitted; default values
             can be changed in BLOCK DATA if necessary.   Only if the
             plot output will be sent to different devices (plotter, 
             laser printer, etc.) will parameter D need to be given.



        STRUVIR Instructions
        ---------------------
        (page 3)


        3. Plot specification

           Option : PARA A B C D E F G H   I  J
           Default: PARA 1 1 1 1 1 1 1 3.2 0 0.01

           A -   Scale factor

             The plot is scaled to the full width of the paper, leaving a
             margin for the heading.   The width of the paper is defined
             in AR1 and AR2 in BLOCK DATA, or as specified with option
             MODI.   Scale factors > 1 will cut off the drawing, but might
             be desired in special cases.

           B -   Index for center in origin

             = 0  no center in the origin
             = 1  centrosymmetric with center in the origin

           C -   Index for outlines of unit cell

             = 0  no outlines
             = 1  outlines are drawn

             The present version of the program does not check overlaps
             of the outlines with polyhedra or spheres.   It might be
             necessary to draw the outlines of the parallelepiped by 
             hand if the view direction is not parallel to one of the 
             crystallographic unit vectors.

           D -   Index for type of representation

             = 0  skeleton model

             This representation, often used for framework structures,
             shows only the connections between the centers of
             neighboring polyhedra.

             = 1  polyhedral representation

             Tetrahedra and octahedra are sought by the program within
             the limits given in options TETR and OCTA.   All polyhedra
             are hatched with equidistant lines parallel to that edge of
             the triangle which is opposite the vertex with the highest
             Z-coordinate.   In this way the density of hatching
             illustrates the inclination of a polyhedral face.

           E -   Index for tetrahedra

             = 0  no tetrahedra
             = 1  tetrahedra are sought and drawn within the values 
                  given in option TETR.   The default values correspond
                  to average Si-O distances.

           F -   Index for octahedra



        STRUVIR Instructions
        ---------------------
        (page 4)


             = 0  no octahedra
             = 1  octahedra are sought and drawn within the values
                  given in option OCTA.   The default values correspond
                  to average (Na,Ca)-O distances

             If lines are drawn belonging neither to tetrahedra nor 
             octahedra, the default parameters have to be changed in
             option TETR or OCTA.

           G -   Index for program execution

             = 0  only tables with atomic coordinates and distances and
                  angles are printed, no plot is produced.
             = 1  tables with atomic coordinates and distances and angles
                  are printed and a projection of the crystal structure
                  is drawn.

           H -   Maximum value for interatomic distances to be calculated

             If more than 100 distances up to the value H are calculated,
             the execution of the program will be terminated.   In this
             case the maximum distance should be given a lower value.

           I -   Retrace parameter NRES

             Outlines of polyhedra and circles are plotted 2*NRES+1 times
             with a distance given by RES (see J).

           J -   Retrace displacement RES

             This value is multiplied by the scale factor.


        4. Cell constants

           Option : CELL a  b  c  alpha beta  gamma
           Default: CELL 10 10 10  90    90    90

             The cell constants are expected in Angstroms and degrees.


        5. Space group symbol

           Option : SPGR space group symbol
           Default: SPGR P1-

             This is interpreted by Burzlaff's (Erlangen) symmetry
             interpretation routine.   The centricity parameter B of PARA
             is overridden.   The generated symmetry operations and
             Bravais translations can be found in the output file.

             WARNING: Any SYMM input, that is input after this, is added 
                      to the generated symmetry operations.



        STRUVIR Instructions
        ---------------------
        (page 5)


        6. Symmetry operators

           Option : SYMM symmetry operators
           Default: SYMM X,Y,Z

             To be used only if the choice of origin is different from 
             the one generated by the Burzlaff routine.

             Each line begining with SYMM contains several operators
             separated from each other by a semicolon.   The last symbol
             in a line must not be a semicolon.   Translations are given
             as fractions (1/2, 2/3 ...).   The identity operator x,y,z
             and centrosymmetric counterparts are not required.   The
             syntax is consistent with the syntax in International Tables
             for Crystallography.


        7. Format for atom parameters

           Option : FORM A
           Default: FORM 4

             A format index; note that in all cases the atom name is read
             in A2,I2.

             = 1  reads a SHELX parameter file (not instructions) 
                  including FVAR and interprets constraints.   This part
                  of the program has been taken from the 1983 version of
                  STRUPLO and could not be tested in the current form.
                  Check carefully for possible errors!
             = 2  Format (2A1,I2,26X,3F10.6) corresponding to the input
                  format of the atomic parameters in the least-squares 
                  program ORFLS.
             = 3  Format (2A1,I2,3F10.6)
             = 4  Free format
                  An atom name consisting of two letters is expected in 
                  the first two columns, followed by a sequence number and 
                  the X,Y,Z-coordinates.


        8. View direction

           Option : VIEW X1 X2 X3  Y1 Y2 Y3
           Default: VIEW  0  0  1   0  0  0

             VIEW can be used to specify a view direction.   X and Y are
             coordinate triples, where the vector defining the view direction
             is given by the difference X-Y: it points from Y to X.   If Y
             is not given, the zero vector 0,0,0 is assumed.   The space
             diagonal of a unit cell, for instance, would be defined by
             VIEW 1 1 1 .



        STRUVIR Instructions
        ---------------------
        (page 6)


             VIEW automatically performs a rotation around the view direction
             (Z-axis, see ROTA), that brings the longest projection of the
             edges of the view range (given by CELL and XYZR) parallel to the
             X-axis, thus resulting in a landscape format picture.


        9. Rotation

           Option : ROTA A B C
           Default: ROTA 0 0 0

           A -  are rotation angles around the orthogonal axes X,Y,Z,
           B -  with the origin in the lower left corner, X pointing 
           C -  right, Y pointing up, and Z sticking out.   The sense of 
                rotation is righthanded for X and Z and lefthanded for Y 
                as shown in the following graph.

                      y
                    |
                    |
                  <<<<<
                    |
                    |
                    |
                  <<<<       V
                    z ^______V_____x
                      ^      V
                             V

                     initially
                     Z is parallel to the crystallographic c-axis
                     Y is the trace of the crystallographic b-axis in the 
                       plane perpendicular to Z
                     X is parallel to Y x Z
                     but this is changed by VIEW and ROTA

             Multiple ROTA commands are accumulated.   This means each ROTA
             command is applied to the view of the structure, as it exists
             at this stage.

             If a VIEW instruction is given, rotations start from the
             directions given by that instruction.   VIEW always takes
             precedence over ROTA.

             WARNING: This is true, even if ROTA commands physically
                      precede the VIEW command.



        STRUVIR Instructions
        ---------------------
        (page 7)


       10. Filecodes

           Option : FILE  A   B   C
           Default: FILE  3   4   6

           A -  input file for all instructions
           B -  output file for coordinates, distance table
           C -  screen unit for some informational output

             Default values can be changed in BLOCK DATA for IO1, IO2, IO3.
             Note that a change in parameter A only affects those 
             instruction lines which follow after FILE.


       11. Range in X, Y, and Z directions

           Option : XYZR A1 A2 B1 B2 C1 C2 D1 D2 E1 E2 F1 F2
           Default: XYZR calculated by program

           All data given here refer to the unit vectors of the unit cell.
           A1 A2, B1 B2, C1 C2 are minimum and maximum range (X,Y,Z) for
           polyhedra, D1 D2, E1 E2, F1 F2 are the X,Y,Z components for 
           the range in which circles are to be drawn defined in CIRC.
           The range for the circles must lie within the range for the 
           polyhedra.   If only the range for the polyhedra is given, 
           this range will be taken also for the circles.


       12. Circle specifications

           Option : CIRC R N1 N2 N3 ...
           Default: no circles

           R -  Radius [A]
           N1 -  Atom names consisting of two letters corresponding to
           ...   the names of the atomic parameters.

             'CIRC 0.8 NA CA' draws sodium and calcium atoms as circles
             with radius 0.8 A.   The symbols listed in one line refer
             only to one radius which is always the first number in
             option CIRC.   Up to 10 different radii (= 10 options CIRC)
             are accepted.   If circles appear not to be drawn completely,
             change RES and NRES in PARA.


       13. Tetrahedra specifications

           Option : TETR   A   B   C    D
           Default: TETR 109  20  1.62  0.2

           A -  tetrahedral angle
           B -  angle tolerance
           C -  mean distance from central atom to coordinated atoms
           D -  tolerance for C



        STRUVIR Instructions
        ---------------------
        (page 8)


             Tetrahedra are sought and drawn with distances between central
             atom and vertices of C+-D [A] and angles between central atom
             and two vertices of A+-B [deg].


       14. Octahedra specifications

           Option : OCTA  A   B   C    D
           Default: OCTA 90  20  1.97  0.4

           A -  octahedral angle
           B -  angle tolerance
           C -  mean distance from central atom to coordinated atoms
           D -  tolerance for C

             Octahedra are sought and drawn with distances between central
             atom and vertices of C+-D [A] and angles between central atom
             and two vertices of A+-B [deg].


       15. Exclusion of atoms

           Option : OMIT A B C D ...
           Default: OMIT no atoms are excluded

           A B C D ... refer to the numbers in parentheses in the output
           list on unit 6.   If the numbers follow each other in direct
           sequence they may be given as A -B, where A and B are the 
           first and last numbers in this sequence.   With instruction 
             'OMIT 9 15 -18 23 26'
           atoms with sequence numbers 9, 15, 16, 17, 18, 23 and 26 are
           are excluded from the parameter list and will not be drawn.
           If an excluded atom belongs to a polyhedron the whole
           polyhedron will be omitted.


       16. Hatching polyhedra

           Option : SHAD NL  N1 N2 N3 ...
           Default: SHAD 9 1 -H(8)

           With this option the number of lines NL for the hatching of a
           polyhedral face can be chosen.   If NL is negative, all
           polyhedra are left blank.   NL from 0 to 20 gives the number
           of lines per face of the polyhedra N1 N2 N3 ...   These numbers
           refer to the numbers of the central atoms.   For explanation of
           the syntax, see 15.



        STRUVIR Instructions
        ---------------------
        (page 9)


       17. Color specifications (not applicable to VRML output)

           Option : COLO N1 C1 N2 C2 N3 C3 ...
           Default: COLO pen 1 (normally black)

           N1 -  Atom name consisting of two letters corresponding to the
                 name of the atomic parameters
           C1 -  Pen number corresponding to atom name N1
           ...

           "Pen" colors used by PSPLOT are: 1=black, 2=grey, 3=red,
           4=green, 5=blue, 6=magenta, 7=yellow, and 8=orange.


       18. Perspective distance

           Option : PERS D
           Default: PERS infinite distance (parallel projection)

           D -  distance from the origin to the observer's eye [A]


       19. Bizarre polyhedra, i.e., not tetrahedra nor octahedra

           Option : BZRR R N
           Default: BZRR no such polyhedra

           R -  radius of sphere within which neighboring atoms are 
                searched
           N -  Atom name consisting of two letters corresponding to the
                names of the atomic parameters

             A maximum of 5 BZRR instructions is allowed


       20. End of instruction list

           Option : END
           no default option


        B) ATOM PARAMETERS
        ------------------

           STRUPLO expects 5 values per atom

           a) atom name  (one or two letters in UPPERCASE :
                                       CO for Cobalt, not Co)
           b) atom label (any number < 100)
           c) fractional coordinates (X, Y, Z)

             Only the atoms in the asymmetric unit are required.

             The format for the atom parameters is specified by the 
             FORM option (see page 5).   The default is "free format".



        STRUVIR Instructions
        ---------------------
        (page 10)


        C) EXAMPLES
        -----------

        Many examples of the use of STRUVIR are stored in the
        STRUVIR.ZIP release. Most of them and more may be viewed
        at the URLs:
           http://fluo.univ-lemans.fr:8001/vrml/vrml.html
           http://fluo.univ-lemans.fr:8001/vrml/struvir.html
              
        Carefully examine the drawings and data files to better
        understand the various uses of the options in STRUVIR.

	-------------------------------------------------------------------
	-------------------------------------------------------------------
	-------------------------------------------------------------------
      Comments from Mark Koennecke about his Povray implementation
      in Struvir.


	-------------------------------------------------------------------
	I have added output for the Povray raytracer to Struvir. After
	running struvir there will be an file "struvir.pov" in your directory
	which contains your crystal structure ready to be rendered with
	povray. Please understand the limitations: struvir can provide
	you with a convenient way to get crystal structures into povray
	but cannot make a art of it. Creating artwork from struvir's
	output is up to you.  

	The file you will get contains:

	A set of declare statements, one for any of the 20 struvir colors
	each. Polyhedra use these declares as their texture information.
	The distribution of the textures on the polyhedra follows the same
	rules as colours in struvir. That is: if a polyhedron has color 1
	in struvir it has texture declare one in the file etc.
	This way you can modify the texture information of whole groups of
	polyhedra by just modifying those declare statements. Please note 
	that povray seems to be unable to cope with mutiple levels of
	declare. I.e. if you want to use one of povrays predefined textures
	you'll better copy the definition text from the include file 
        into the declare statement.

	After this you'll find a default light source and a default camera,
	looking down z, some distance from the crystal.

	Following this, the polyhedra are given. Each one as a union 
	consisting of several triangles. 

	At the end of the file all the spheres are given.

	Just a tip: if you want to move or scale your complete crystal 
	structure in you scene enclose the whole polyhedron and spheres bit
	with a union and specify the necessary transforms at the end. 

	Povray output is for povray-2.2 as at the time of writing povray-3.0
	is not yet available on a unix. I tested the povray stuff with most
	of the example .dat files provided by Armel and got reasonable
	pictures. However as usual:

	NO WARRANTIES OF ANY KIND ARE GIVEN. YOU ARE ON YOUR OWN WITH THIS.

	Warning: Neither struvir, nor povray are programs for the either
	crystallographically or computationally challenged!

				Enjoy
					Mark Koennecke
					Mark.Koennecke@psi.ch
 ======================================================================

 Finally povray-3.0 accepts the struplo.pov files too. (ALB).



