Committer: ckloss <ckloss@fluid38.(none)>

On branch master
 Initial commit for lpp, version 2011-10-11

doc/raster.txt

@@ -0,0 +1,151 @@
+"Pizza.py WWW Site"_pws - "Pizza.py Documentation"_pd - "Pizza.py Tools"_pc :c
+
+:link(pws,http://www.cs.sandia.gov/~sjplimp/pizza.html)
+:link(pd,Manual.html)
+:link(pc,Section_tools.html)
+
+:line
+
+raster tool :h3
+
+[Purpose:]
+
+3d visualization via Raster3d program.
+
+[Description:]
+
+The raster tool is a wrapper on the
+"Raster3d"_http://www.bmsc.washington.edu/raster3d/raster3d.html
+visualization program.  Raster3d is open source software and runs on
+many platforms.
+
+The raster constructor takes a data object containing atom or mesh
+snapshots as an argument ("dump"_dump.html, "data"_data.html,
+"cdata"_cdata.html, "mdump"_mdump.html).
+
+The show() method runs Raster3d on the selected atoms or triangles of
+snapshot N and displays the resulting image stored as image.png.  The
+all() method loops thru all selected snapshots and runs Raster3d on
+each one.  The resulting image files are saved to image0000.png,
+image0001.png, etc.  The prefix "image" can be changed via the file
+setting.
+
+The bg(), size(), rotate(), trans(), zoom(), box(), label(), and
+nolabel() methods control various aspects of the images produced.
+Without the trans() and zoom() settings, the Raster3d image should
+roughly fill the window and be centered.
+
+Additional movie effects can be produced using the pan() and select()
+methods.  The pan() method specifies an initial and final viewpoint
+that is applied to the images produced by the all() method.  For
+intermediate images, the view parameters will be interpolated between
+their initial and final values.  The pan() method can thus be used to
+rotate a single image or fly-by the simulation as it animates.  The
+select() method performs additional atom selection for each image of
+the all() sequence.  An image-dependent %g variable can be used in the
+select() string.  The select() method can thus be used to slice thru
+the data set.
+
+The acol(), arad(), bcol(), brad(), and tcol() methods change
+attributes of the atoms, bonds, and triangles displayed.  Each atom or
+bond returned from the data object has an integer "type" from 1 to N.
+The type is used to index into a list of RGB colors or radii for atoms
+and bond thickness.  The adef(), bdef(), and tdef() methods setup
+default mappings of types to colors/radii.  The other methods enable
+specific assignments to be made.  The interpolation option (e.g. many
+types assigned to a few colors), enables a smooth rainbow of colors to
+be assigned to a range of types.  Note that the "dump"_dump.html tool
+allows any vector to be returned as an atom "type" via its atype
+setting.  Thus displayed colors can be keyed to atom velocity or other
+properties.
+
+Colors are specified with a string, e.g. "red".  There are 140
+pre-defined colors from "this WWW page"_colortable which can be
+examined by importing the "colors" variable from "vizinfo".  New
+colors can be defined by assigning a nickname of your choice to an RGB
+triplet, as described below.
+
+:link(colortable,http://www.oreilly.com/catalog/wdnut/excerpt/color_names.html)
+
+[Usage:]
+
+r = raster(d)               create Raster3d wrapper for data in d :pre
+
+  d = atom snapshot object (dump, data) :pre
+
+r.bg("black")               set background color (def = "black")
+r.size(N)		    set image size to NxN
+r.size(N,M)		    set image size to NxM
+r.rotate(60,135)            view from z theta and azimuthal phi (def = 60,30)
+r.shift(x,y)                translate by x,y pixels in view window (def = 0,0)
+r.zoom(0.5)                 scale image by factor (def = 1)
+r.box(0/1/2)                0/1/2 = none/variable/fixed box
+r.box(0/1/2,"green")        set box color
+r.box(0/1/2,"red",4)        set box edge thickness
+r.file = "image"            file prefix for created images (def = "image") :pre
+
+r.show(N)                   show image of snapshot at timestep N :pre
+
+r.all()                     make images of all selected snapshots
+r.all(P)                    images of all, start file label at P
+r.all(N,M,P)                make M images of snapshot N, start label at P :pre
+
+r.pan(60,135,1.0,40,135,1.5)    pan during all() operation
+r.pan()                         no pan during all() (default) :pre
+
+  args = z theta, azimuthal phi, zoom factor at beginning and end
+  values at each step are interpolated between beginning and end values :pre
+
+r.select = "$x > %g*3.0"    string to pass to d.aselect.test() during all()
+r.select = ""               no extra aselect (default) :pre
+
+  %g varies from 0.0 to 1.0 from beginning to end of all() :pre
+
+r.label(x,y,"h",size,"red","This is a label")    add label to each image
+r.nolabel()                                      delete all labels :pre
+
+  x,y coords = -0.5 to 0.5, "h" or "t" for Helvetica or Times font
+  size = fontsize (e.g. 10), "red" = color of text :pre
+
+r.acol(2,"green")		   set atom colors by atom type (1-N)
+r.acol(\[2,4\],\["red","blue"\])	   1st arg = one type or list of types
+r.acol(0,"blue")	           2nd arg = one color or list of colors
+r.acol(range(20),\["red","blue"\])   if list lengths unequal, interpolate
+r.acol(range(10),"loop")           assign colors in loop, randomly ordered :pre
+
+  if 1st arg is 0, set all types to 2nd arg
+  if list of types has a 0 (e.g. range(10)), +1 is added to each value
+  interpolate means colors blend smoothly from one value to the next :pre
+
+r.arad(\[1,2\],\[0.5,0.3\])            set atom radii, same rules as acol() :pre
+
+r.bcol()			   set bond color, same args as acol()
+r.brad()			   set bond thickness, same args as arad() :pre
+
+r.tcol()			   set triangle color, same args as acol()
+r.tfill()			   set triangle fill, 0 fill, 1 line, 2 both :pre
+
+r.lcol()                           set line color, same args as acol()
+r.lrad()                           set line thickness, same args as arad() :pre
+
+r.adef()                           set atom/bond/tri/line properties to default
+r.bdef()			   default = "loop" for colors, 0.45 for radii
+r.tdef()  			   default = 0.25 for bond/line thickness
+r.ldef()  			   default = 0 fill :pre
+
+  by default 100 types are assigned
+  if atom/bond/tri/line has type > # defined properties, is an error :pre
+
+from vizinfo import colors         access color list
+print colors                       list defined color names and RGB values
+colors\["nickname"\] = \[R,G,B\]       set new RGB values from 0 to 255 :pre
+
+  140 pre-defined colors: red, green, blue, purple, yellow, black, white, etc :pre
+
+[Related tools:]
+
+"dump"_dump.html, "gl"_gl.html, "rasmol"_rasmol.html, "svg"_svg.html
+
+[Prerequisites:]
+
+The Raster3d render and label3d programs.