Index: inundation/pmesh/documentation/mesh_gen_SRS.txt
===================================================================
--- inundation/pmesh/documentation/mesh_gen_SRS.txt	(revision 3474)
+++ 	(revision )
@@ -1,331 +1,0 @@
-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 $
Index: inundation/pmesh/documentation/pmesh_pre_TRAC_issues.txt
===================================================================
--- inundation/pmesh/documentation/pmesh_pre_TRAC_issues.txt	(revision 3474)
+++ 	(revision )
@@ -1,311 +1,0 @@
-CURRENT PMESH ISSUES
-
-OPEN - issues that have not beeen resolved
- 
-Issue: On the cluster, if storm_surge/pmesh is in the pythonpath (and
-not storm_surge?), pmesh.mesh fails by trying to load pmesh
-visualisation stuff.  Pmesh shouldn't be trying to load anyhow.
-
-Issue: crash if file>filter alpha boundary if there is no alpha
-boundary.
-
-Issue: Add export seg outline file back into pmesh
-
-Issue: triangles_to_polySet (outlining the current set) sometimes
-duplicates vertices.  Now that is fixed, but segments that overlap (ie
-one big line that gets little ones drawn on it) break triangle.
-
-Suggested action: make a dictionary of Hough transforms (parametric
-lines i.e. angle, x-intercept) of the segments. Check any that take up
-the same space. Fix overlapping lines.
-
-Issue: Red mesh selected for refinement seems to be 'behind' the green
-mesh after selecting all then clearing the selection.
-Importance: low
-Suggested Action: Fixed BUT now it draws the greens behind the reds.
-It is much less obvious now though.
-The only way to fix it for good is to colour in the triangles - that
-is the only way to guarantee you know what each triangle is.
-
-
-Issue:  Ole thought that the regional mesh max areas were incorrect
-when a .tsh file was loaded.  Maybe it was that the overall max area
-is not saved.  It's hard coded in MeshGenDialog.
-Importance: Medium
-Suggested Action: Fix when .tsh goes NETCDF
-
-Issue: Catch error if .tsh file is a bad format.
-suggestion: quick and dirty try - except
-Importance: Medium
-
-Issue (new feature): Have visualisation of verts be turned on and
-off.  This will speed things up.
-Importance: low
-
-Issue (new feature): Hve .tsh as a netscf fie, instead of an ascii
-file.
-Importance: Medium
-
-Issue: When a file is saved as and then saved later, sometimes the
-file name is not known.   Is it that 'clear' is removing the name
-(which it should). 
-
-Issue:A .tsh file loaded into pmesh after smoothing will not have the
-outline info, since this is removed when smoothing.  If this is a
-problem, refactor loadASCII so it can write the outline as well.
-Suggested Action: Document use
-
-Issue:vertices at the bottom of the canvas can be hard to visualise,
-since you don't know if all vertices are on the screen.  
-Suggested Action: have a 5% border
-Importance: low to not do
-
-Issue: The mesh produced by triangle isn't of high quality near a low
-angle formed by two user segments.
-Reason:triangle
-Tried:  Tried the triangle flags L,i,V (for info).  Using box.poly on
-nautilus.  Couldn't get a better quality mesh.
-
-Issue: Get the naming right for mesh/triangulation/user/generated.
-How about "outline + triangulation = mesh"
-Importance: Medium -low
-
-Issue: S/W - too many methods with the same name on differnent classes
-eg editWindow.  Makes things confusing. 
-Importance: low
-
-Issue: Normalise seems broken - what is it doing to the attributes?.  
-Suggested Action: remove!
-
-Bug: Calling 'Generate Mesh' on empty document or If there are no
-enclosed regions will cause trianglulation to crash pmesh.
-Importance: low - not do, but document
-Suggested Action: Catch them (with try) and do nothing
-notes:   Fixing the 'Generate Mesh' crash is a P3 requirement.
-
-The zoom in/out is jittery
-
-The initial mesh window coordinates are in the fourth quadrant.
-
-Deleting a selected object is done with the scroll bar, not the 
-delete key. 
-
-Issue: triangle calculates incorrect attribute values, some of the time.
-Importance: Medium
-Suggested Action: Preprocess data to smoth it out.
-
-Issue: pmesh can not be automatically installed in windows and linux,
-triangle doesn't compile easily.
-Installs best in Linux.  
-Importance: Low
-Suggested Action: delve into setup more so it works with a variety of
-compilers.
-
-Issue: two vertices can be ontop of one another
-Importance: Low
-Suggested Action: See how it goes when used.  The cost of checking
-probably doesn't outwiegh the benifit.
-action taken: When loading an xya file duplicate vertices are removed. 
-
-
-Issue: When calculating mesh, have the pointer turn into an hour glass
-Importance: Low
-
-****************
-CLOSED - issues that have  beeen resolved
-************
-Issue: If some triangles have tags and others don't then the data
-structure (a list of lists) is dificult to use in Numeric.
-Solution -  use a list structure, instead of list of lists 
-Closed -  used a list structure, instead of list of lists 
- 
-Issue (Ole): I couldn't get pmesh to write mesh in the .msh format
-Importance: Mid
-Suggested action: Either 
-    1:  Equip scripted mesh generation with functionality for tagging
-    2:  Allow pmesh to store as msh
-    3:  Have a tsh2msh converter
-Closed: Couldn't be reproduced. suggested action 2 has already been
-implemented.  More investigation required before calling an issue an issue..
-
-Issue: After selecting all for refinement then clearing the selection
-segments (blue lines) can not be selected.
-Importance: High
-Suggested Action:Fixed
-Reason: 
-
-Issue: Refined triangles don't have the correct region information.
-Importance: High
-Suggested Action: Fixed
-Reason: I don't think 'refine' fixes triangle attributes
-
-
-Issue: Pmesh won't save a refined mesh.
-Importance: High
-Reason: Refine_triangle.getNewVertex was not appending to mesh.meshVertices,
-        nor was it assigning an index to the vertex.
-
-Issue When starting generate mesh, the cursor doesn't start in the
-first box.
-Importance: Low
-Action: fixed
-
-Issue: Why is triangle att's set as a list and returned as a list of
-lists, when loading from a .tsh file?  Note: a change of this might
-also affect the 'triangle' glue code.
-Note: This also happens to triangle atts! (?)
-action: triangle att's set as a list of lists
-
-Issue:Implememt the following with mesh gen minimum angle, 0 - 32
-nothing;32-40 warning message, may not converge; 40 - error message 
-Importance: Low
-Action: done
-
-Issue: Middle magnifying glass icon does not describe what it will do.
-Importance: Low Low
-action: too unimportant to do
-
-Issue:  Maybe triangle doesn't normalise meshes away from the origin,
-resulting in round-off error.
-Importance: Low Low
-Suggested Action: closed since this didn;t seem to be a problem.
-
-Issue:hull.exe generates files that it doesn't clean up eg called
-s1f8, se4, etc. These seem to turn up in a root directory
-Importance: Low
-
-Issue: Hull.exe (alpha shape) - gives an assertion error if points are
-too close together?.  
-Importance: Low
-Suggested Action: when using the results from hull.exe, check if it
-has given any results and throw a friendly message if there are no results.
-
-Issue: When adding segments, vertices are hard to select (with the mouse).
-
-Issue: Calling autoSegment when not in the pmesh directory will not
-work, since it calls the hull.exe, assuming it's in the current dir 
-Importance: medium
-Suggested Action: Have the current dir change to the pmesh dir , run
-hull, then change back
-action: contractor is making alpha shape in python
-
-Issue: In the shallow_water functions for pmesh, make the
-volume.interpolate_cons_quantitie call more automatic
-
-Issue: Need tests for pmesh functions in  shallow_water.py
-
-Issue: If there is a large scale grid, how many triangles can be
-generated?  with a normalised grid there's a limit of 22674.
-Using a 100 * 100 domain, a max triangle area of 0.01 produced
-1,048,576 triangles.
-
-Issue: Internal boudaries get an empty string as tag (per default?)
-Background: The notion of defaiults values for internal boundaries was removed, but this one seems to have taken its place. The following hack will 
-remove the tag: 
-  #for b in domain.boundary.keys():
-  #    if domain.boundary[b] == '':
-  #        del domain.boundary[b]
-  #
-  #domain = Domain(domain.coordinates, domain.triangles, domain.boundary)
-Importance: high
-
-
-Issue: The default region button cannot be selected after loading a file.
-Reason: Unknown.  
-Importance: Low
-
-Issue: The vertices were being sorted when loading .xya files
-Time to complete : 5hrs
-Issue: In load ascii all text reading of lines using find must ltrim
-beforehand
-
-Issue: pmesh -when loading/saving the dir should be the dir where the
-file lives.  Not always the current dir. 
-
-Issue: Tags for specifying boundary conditions should be arbitrary
-Background: Domain has the functionality for using arbitrary keys
-when associating boundary objects to boundary values.
-Triangle, which pmesh is based on, uses integers only.
-It would be nice to have mnemonic names for boundaries throughout.
-Importance: Mid
-Status: Unresolved
-
-Issue: Calling save the first time seemingly does nothing
-Importance: Low
-Suggested Action: Call save_as when save is clicked the first time.
-
-
-Bug: Calling Zoom functions on empty document 
-causes an AttributeError Exceptions.
-Importance: Medium
-Suggested Action: Catch them (with try) and do nothing
-notes: the zoom crash is not reproducable.  Fixing the 'Generate Mesh' crash
-is a P3 requirement.
-
-When doing mesh generation, no default values (min angle, max area)
-are shown. - Low priority for Chris
-
-
-Cursor shape changes when it shouldn't.
-
-Issue: Help message and status message are the same.  Remove one
-Importance: Low
-Suggested Action: Remove the status info
-
-
-Issue: Selecting nodes require that boundary is selected precisely.
-Importance: High
-Suggested Action: Allow click in interior of square.
-
-Bug: Entering negative value for area is allowed.
-Importance: Medium
-Suggested Action: Check input and return error message
-
-
-Issue: Minimum angle needs a specification of what interval is allowed.
-It seems to pick a default value if angle is out of bounds.
-Action: angles <0.0, >90.0 not allowed 
-
-Bug: Entering zero for area causes crash.
-Importance: Medium
-Suggested Action: Check input and return normal error message
-
-
-Issue: Re-generating grids goes slower and slower when repeated.
-Importance: Low
-Suggested Action: Check that old grid gets removed from memory.
-Action taken: cleaned up how visualised objects are handled
-
-
-Issue: nothing says what mode(seg or vertex) pmesh is in
-Importance: Low
-Action taken: Have the buttons stay 'down', to depict mode.
-
-  
-
-Issue: Meaning of 1 x zoom is not intuitive. 
-Related issue: Absolute scale should be reported in status bar
-Importance: Medium
- Action taken : Zoom x 1  gives a zoom corresponding 
-to the opening screen.
-
-Vertices and segments that have a triangle on top of them are hard to 
-select/see.  Ole suggested that there be the capability to view/hide the mesh.
- Action taken :put segs/vertices on top
-
-
-NOTES
-The arrow and postscript bottons currently do nothing.
-
-
------------------------------------------------
-NEW REQUIREMENTS
-
-Introduce 'eraser tool'. When selected left clicking any object will remove it.
-
-Allow generated grid to be cleared (or hidden).
-
-
-
-CVS INFORMATION FOR THIS FILE
-$Source: /var/lib/cvs/pmesh/documentation/issues.txt,v $
