source: branches/inundation-numpy-branch/pmesh/documentation/mesh_gen_SRS.txt @ 6689

Pmesh Software Requirements Specification
By Duncan Gray

$Revision: 1.29 $
$Date: 2004/08/13 08:31:15 $

INTRODUCTION

The software, called pmesh, will produce a triangulation based on
initial vertices and boundaries.  The produced triangulation can be
used by an evolution code to solve storm surge problems using the Finite
Volume Method.


The requirements in this document describe the software features
needed to produce triangulations useful for Geohazards.

OVERALL DESCRIPTION 

Pmesh is a graphical user interface (GUI) for triangle (a mesh
generating program developed by J. R. Shewchuk) which is a mesh
generation program. It will allow vertices (points) and segments
(straight lines between the vertices) to be added to a canvas.



Pmesh will let the user select various modes. The initial
allowable modes will be vertex or segment.  The mode describes what sort
of object is added or selected in response to mouse clicks.  When
changing modes any prior selected objects become deselected.
 
In general the left mouse button will add an object and the right mouse
button will select an object.  A selected object can de deleted by
pressing the delete key.  Additionaly, by pressing the middle mouse
button (scroll bar) the attributes of a selected object can be edited.

The graphical objects are of two types; user or generated.  User
objects are vertices and segments inputted by the user.  These are
used by triangle when generating a mesh.

 The generated objects are vertices, segments and triangles of the
triangulation.  Only the triangles are graphically displayed.
Generated objects can not be modified by the user. To modify the
generated triangulation edit the user objects and generate a new
trianglulation.


DEFINITIONS

Segments are edges whose presence in the triangulation is constraints.
Segments can be used to define the boundaries of a problem.

A triangulation is the triangles, vertices and segments generated by
triangle.

A mesh is all the triangle elements .e.g. the vertices, segments and
triangulation.

A Planar Straight Line Graph (PSLG) is a set of vertices and segments.
Segments are simply edges, whose endpoints are vertices in the PSLG.
Segments may join each other only at their endpoints and must not intersect.


REQUIREMENT SECTION

Introduction

Each requirement has a priority (e.g. P1), with 1 being the highest
and 10 the lowest.  The priority number is given at the end of each
requirement.

IMPLIMENTED

Requirements

- When a mesh is loaded  all of the mesh will fit in the application
  window - P1 DONE
  
- If some of the mesh is not visible scroll bars are used to make
  the canvas visible - P1 DONE

- Have ability to zoom in by *2 on the mesh and zoom out, by
  *0.5. -P1 DONE 
 
- add user vertices, positioning by mouse - P1 DONE
                     , positioning by entering x,y values - P1 DONE

- add user segments, vertices selection by mouse - P1 DONE

- be able to select a user vertex. -P2 DONE

- be able to select a user segment. -P2 DONE

- to be able to delete selected user objects. -P2 DONE

- be able to delete an entire mesh. - P2 DONE
  
- To be able to load and save meshes as a python pickled object. -P2 DONE

- access to triangle mesh generator,
          user can select min angle, max area - P1 DONE
          user can select rough number of triangles to generate - P3
          DONE
          
- The screen should reflect the current generated triangulation -P2 DONE

- Have 'Zoom' button that positions all of the mesh in the viewing
  window - P3 DONE  

- Be able to automatically generate segments that bound all of the
user vertices, but not a convex hull bound.  Specifically, be able to
apply an alpha shape around a set of vertices. - P3 - DONE
 
- specify a region by selecting a point bounded by segments. - P30 - DONE

- specify an attribute to a region. - P30 - DONE

- specify a hole in the mesh by selecting a point bounded by
  segments. - P30 - DONE


- write an ascii file that outputs - P30 - DONE
# of vertices
[x,y]
# of triangles
[vert1 #, vert2 #, vert3 #, adjoining triangle 1, adjoining triangle
2, adjoining triangle 3, attributes of region ]
if there is no adjoining triangle, give -1 as the adjoining triangle.


- specify how much vertex attribute information can be added to the mesh. -P40
  - eg one attribute per vertex, two attributes per vertex
- specify the default attribute vertex value - P40

- edit segment attribute.  Can only select integers -P40 - DONE


- load the following user vertex file layout 
  - First row {"Lat", "Long", "Depth"}
  - Subsiquent rows x y positions with 1 attribute
  - Initially, load the file type, ditching the attribute info - P3 DONE
  - Use the attribute info - P60 - DONE

- Have an ascii export/import file format, that fully specifies a mesh 
  - Add more output to the current export, so a mesh is fully specified
  - Add an import of the exported format   - P60 - Done
  
- Print out the triangulation as a postscript file - P80 - DONE

- Be able to tag boundaries with strings. - DONE
 
- Have a warning prompt when saving a mesh where the generated mesh is
  different from the user mesh - eg boundary tags that aren't carried
  thru. Warning ~"Mesh not generated after changes.  Generate mesh?  "
  - cancel, don't gen, don't save.  Yes - generate mesh, go to save
  screen.  No - goto save screen.  To implement this need to know when
  the user has done a change, and the mesh hasn't been generated.  If
  there is no generated mesh do not prompt. - DONE

access to triangle mesh generator,
          user can select  max area in region - P80 - DONE
 
- .xya file, which has vertex information, will have headers naming
the attributes in the first row.  The headers will be strings
representing a label for the attribute information.  This information
will be space deliminated.  There will be no ordering imposed.  The
name, column index mapping will be in the .tsh file.
      - x and y headings are manitory. - not done, requirements changed
      - Missing fields will cause an error during loading of the xya file.

 
 NOT IMPLIMENTED
- show file name in title bar
 
- Have a divide all max areas by value x function. - P80

- triang.genMesh - get triangle compiled automatically. 

- able to specify a 'circular' region by specifying center, radius and
  number of number of segments. (The functionality is there as a hack.
   need to add gui etc.) - P100
   
- Display mouse point position [x,y] - P60

- Calculate total area enclosed (maybe a buton?) -P80
          (this requirement GUI aspect needs to be fleshed out with Chris)
          
- Load in a segment attribute to boundary mapping.  ie segment
  attribute is 'seen' as a boundary, such as a 0 flux boundary and
  this is interanally represented as an interger, as defined by the
  mapping. - P100 
  
- Select segment attribute from an enumerated list of boundaries. - P100
  
- Select segment attribute from an enumerated list of boundaries and
  can also input values of constants described in the boundary. - P100

- Select objects  - Be able to select multiple objects.  Eg select
  many segments and mark with one attribute -P100

- Be able to select objects by "mouse dragging" a rectangle. (A
  rectangle whos size and position is controlled by the mouse)
  Everything within the rectangle is selected.
  
- Move user vertices  - can initially be  done by
  adding/deleting vertices and segments. -P100 [should we have this feature?]

- specify a maximum area for each triangle, based on current mesh
  (this is refinement of the current mesh) - P100

- able to specify a 'circular' region by specifying center, radius and
  number of number of segments. - P100
  
-Log window.  Have a separate window that displays log information.
This window can be turned on or off. - P100

- Log information of the generation mesh process.  - P100
  - max area
  - minimum angle
  [Other information to be determined ] 

- reduce mesh generation crashing by only mesh generating if all of the
vertices are bounded by segments. - P100

- Set the initial mesh co-ordinate to origin (0,0) at canvas bottom left and
  (100,100)at canvas top right.

- Have info with the mesh, such as #of triangles, min angle, max area
          (this requirement GUI aspect needs to be fleshed out with Chris)
          
- Put postscript/clear/close buttons as a menu, not at the bottom of
  pmesh
  
- assume the scale is metres, important for the programs using the
mesh.  Maybe in add vertex have the scale?

- be able to add two .tsh files together.

- run triangle as a seperate thread, so if it's not converging it can
be stopped. - P100
 
-  
__________________
 
The information below describe the various colours for drawn objects,
given the objects state.
User Vertex, not selected  - small black rectangle (to represent a point)
             selected      - small red rectangle
             selected when adding a segment - small orange rectangle
User Segment, not selected  - blue line
             selected      - red line
             
Computer Vertices and Segments will not be drawn
Computer Triangle,  not selected  - green triangle 
             selected      - red triangle (can be selected to add max
             area value when refining triangulations)
_________________________


DEVELOPMENT

The pmesh software will be developed using an iterative approach, with
it being "released" several times and each release having increased
functionality. The first iteration will be a minimal system.
Requirements to be delivered in each iteration are described below.

Currently four iterations are planned.
Each requirement is associated with an iteration, via the requirement's
priority, represented by a P number. P1, P2, P3 etc.

 
1st iteration P1 & P2 - basic framework, loading and saving of meshes
2nd iteration P3      - specifying  # of triangles in mesh
3rd iteration P30     - specify holes, regions and having attributes
                        for regions  
4rd iteration P40     - attribute and boundary manipulation
                         
5th iteration P60     - increased GUI functionality

6th iteration P80     - region selection, selection of different max
                         triangle areas based on region, segments
                        automatically added
Future iterations P100    
__________________________

NOTES

How to speed things up.
Use numericpy to build the data structures and then pass them straight
to the triangle.o (This is assuming the numericpy data structures are
in a c format.) - Don't lose the OO structure though. 

preallocate lists, instead of calling c repeditively
_______
Questions
What format will the initial data in? Chris is going to find an inital
format, from previous work.

How will data be taken in future? ie do we have datasets that we will
convert or will we hand generate initial data sets?
 
What s/w package takes care of the boundary conditions?
[this seems to be an open issue still.]

Things to work out with Chris and Steve: 
How can the quality of the meshes be tested? Chris believes triangle
diagnostices should provide this information.

Will we need this?
  -L  Do not use diametral lenses to determine whether subsegments are
        encroached; use diametral circles instead (as in Ruppert's
        algorithm).  Use this switch if you want all triangles in the mesh
        to be Delaunay, and not just constrained Delaunay; or if you want
        to ensure that all Voronoi vertices lie within the triangulation.
        (Applications such as some finite volume methods may have this
        requirement.)  This switch may increase the number of vertices in
        the mesh to meet these constraints.
 ________________________________________________________________

REQUIREMENT ISSUES

 - if a vertex with attribute info is moved, the attribute info does
 not change.  This will not reflect the actual environment. Option
 1)The user can enter correct attribute data
  
 2) the s/w can interpolate, based on the original vertex data.
 
 Currently suggesting option 1 - Duncan and Chris.
 
CVS INFORMATION FOR THIS FILE
$Source: /var/lib/cvs/pmesh/documentation/mesh_gen_SRS.txt,v $