[chimera-dev] _surface module

[Thomas Goddard]

Hi Karin,

  Yes, I did change Chimera Surface_Model to only support triangulated
surfaces, eliminating the quadrilateral surfaces.  I'm amazed that you
found the quadrilateral capability.  The new code does allow displaying
quadrilaterals in a different way -- and in fact can display pentagons,
hexagons and other shapes with the additions made to Chimera 1.2255.
I eliminated the old quadrilateral support when I added these new features
because the code was too complex and I did not expect anyone was using it.

  The new Surface_Model only allows surface specifications with triangles.
If you have quadrilaterals it is easy to turn it into triangles.  For a
quadrilateral with vertices 1, 2, 3, 4 just make two triangles with vertices
1, 2, 3 and 1, 3, 4.  The new Surface_Model allows hiding any triangle
edges when displaying with mesh style.  When you divide the quadrilateral
into 2 triangles you can hide the introduced quadrilateral diagonal.

  Below is an example of making a cube with 6 faces in the old (1.2199)
and new (1.2255) ways.  At the end there is a routine to turn quadrilateral
lists into triangle lists and an edge mask.

  The new Surface_Model allows displaying meshes with pentagons or hexagons,
or any arbitrary set of triangle edges, for example

	http://www.cgl.ucsf.edu/chimera/experimental/hkcage/cage.html

Also I added a new "square mesh" option to the Chimera volume viewer
dialog that shows contour meshes where just the intersection of the
grid planes perpendicular to x, y and z axes with the contour surface
are shown.  This is the kind of mesh the program O uses.

  I hope the new Surface_Model interface is not too troublesome to use.
The new edge masking capability makes it more powerful, but also more
complex.

	Tom

-----
Python code quads.py follows:

# -----------------------------------------------------------------------------
# Create a cube surface model using quadrilaterals with Chimera 1.2199.
#
def cube_old_style():

  from _surface import Surface_Model
  s = Surface_Model()

  # Cube corner xyz positions.
  vlist = ((0,0,0), (0,0,1), (0,1,0), (0,1,1),
           (1,0,0), (1,0,1), (1,1,0), (1,1,1))

  # 4-tuples of vertex list indices.
  qlist = ((0,4,5,1), (0,2,6,4), (0,1,3,2), (7,3,1,5), (7,6,2,3), (7,5,4,6))

  from Numeric import array, Float32
  vlist_f32 = array(vlist, Float32)     # add_group() requires Float32 vertices

  rgba = (1,1,1,1)      # white
  
  g = s.add_group(vlist_f32, qlist, rgba)
  g.set_display_style(g.Mesh)

  from chimera import openModels
  openModels.add([s])   # Add model to list of open models.

# -----------------------------------------------------------------------------
# Create a cube surface model using triangles with Chimera 1.2255.
#
def cube_new_style():

  from _surface import Surface_Model
  s = Surface_Model()

  # Cube corner xyz positions.
  vlist = ((0,0,0), (0,0,1), (0,1,0), (0,1,1),
           (1,0,0), (1,0,1), (1,1,0), (1,1,1))

  # 3-tuples of vertex indices specify triangles, 2 for each of 6 cube faces.
  tlist = ((0,4,5), (5,1,0), (0,2,6), (6,4,0),
           (0,1,3), (3,2,0), (7,3,1), (1,5,7),
           (7,6,2), (2,3,7), (7,5,4), (4,6,7))
  
  # Bit mask: 8 = show triangle
  #           4 = show triangle edge from vertex 0 to vertex 1
  #           2 = show triangle edge from vertex 1 to vertex 2
  #           1 = show triangle edge from vertex 2 to vertex 0
  b = 8 + 2 + 1
  hide_diagonals = (b,b,b,b,b,b,b,b,b,b,b,b)

  from Numeric import array, Float32
  vlist_f32 = array(vlist, Float32)     # add_group() requires Float32 vertices

  rgba = (1,1,1,1)      # white

  g = s.add_group(vlist_f32, tlist, rgba)
  g.set_display_style(g.Mesh)
  g.set_triangle_and_edge_mask(hide_diagonals)

  from chimera import openModels
  openModels.add([s])   # Add model to list of open models.

# -----------------------------------------------------------------------------
# Convert quadrilaterals to triangles with appropriate edge mask.
#
def quadrilaterals_to_triangles(qlist):

  tlist = []
  for v0,v1,v2,v3 in qlist:
    tlist.append((v0,v1,v2))
    tlist.append((v2,v3,v0))

  emask = 8 + 2 + 1
  edge_mask = [emask] * len(tlist)

  return tlist, edge_mask