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

Last change on this file since 6689 was 1219, checked in by duncan, 20 years ago

added comments

File size: 12.0 KB
Line 
1Pmesh Software Requirements Specification
2By Duncan Gray
3
4$Revision: 1.29 $
5$Date: 2004/08/13 08:31:15 $
6
7INTRODUCTION
8
9The software, called pmesh, will produce a triangulation based on
10initial vertices and boundaries.  The produced triangulation can be
11used by an evolution code to solve storm surge problems using the Finite
12Volume Method.
13
14
15The requirements in this document describe the software features
16needed to produce triangulations useful for Geohazards.
17
18OVERALL DESCRIPTION
19
20Pmesh is a graphical user interface (GUI) for triangle (a mesh
21generating program developed by J. R. Shewchuk) which is a mesh
22generation program. It will allow vertices (points) and segments
23(straight lines between the vertices) to be added to a canvas.
24
25
26
27Pmesh will let the user select various modes. The initial
28allowable modes will be vertex or segment.  The mode describes what sort
29of object is added or selected in response to mouse clicks.  When
30changing modes any prior selected objects become deselected.
31 
32In general the left mouse button will add an object and the right mouse
33button will select an object.  A selected object can de deleted by
34pressing the delete key.  Additionaly, by pressing the middle mouse
35button (scroll bar) the attributes of a selected object can be edited.
36
37The graphical objects are of two types; user or generated.  User
38objects are vertices and segments inputted by the user.  These are
39used by triangle when generating a mesh.
40
41 The generated objects are vertices, segments and triangles of the
42triangulation.  Only the triangles are graphically displayed.
43Generated objects can not be modified by the user. To modify the
44generated triangulation edit the user objects and generate a new
45trianglulation.
46
47
48DEFINITIONS
49
50Segments are edges whose presence in the triangulation is constraints.
51Segments can be used to define the boundaries of a problem.
52
53A triangulation is the triangles, vertices and segments generated by
54triangle.
55
56A mesh is all the triangle elements .e.g. the vertices, segments and
57triangulation.
58
59A Planar Straight Line Graph (PSLG) is a set of vertices and segments.
60Segments are simply edges, whose endpoints are vertices in the PSLG.
61Segments may join each other only at their endpoints and must not intersect.
62
63
64REQUIREMENT SECTION
65
66Introduction
67
68Each requirement has a priority (e.g. P1), with 1 being the highest
69and 10 the lowest.  The priority number is given at the end of each
70requirement.
71
72IMPLIMENTED
73
74Requirements
75
76- When a mesh is loaded  all of the mesh will fit in the application
77  window - P1 DONE
78 
79- If some of the mesh is not visible scroll bars are used to make
80  the canvas visible - P1 DONE
81
82- Have ability to zoom in by *2 on the mesh and zoom out, by
83  *0.5. -P1 DONE
84 
85- add user vertices, positioning by mouse - P1 DONE
86                     , positioning by entering x,y values - P1 DONE
87
88- add user segments, vertices selection by mouse - P1 DONE
89
90- be able to select a user vertex. -P2 DONE
91
92- be able to select a user segment. -P2 DONE
93
94- to be able to delete selected user objects. -P2 DONE
95
96- be able to delete an entire mesh. - P2 DONE
97 
98- To be able to load and save meshes as a python pickled object. -P2 DONE
99
100- access to triangle mesh generator,
101          user can select min angle, max area - P1 DONE
102          user can select rough number of triangles to generate - P3
103          DONE
104         
105- The screen should reflect the current generated triangulation -P2 DONE
106
107- Have 'Zoom' button that positions all of the mesh in the viewing
108  window - P3 DONE 
109
110- Be able to automatically generate segments that bound all of the
111user vertices, but not a convex hull bound.  Specifically, be able to
112apply an alpha shape around a set of vertices. - P3 - DONE
113 
114- specify a region by selecting a point bounded by segments. - P30 - DONE
115
116- specify an attribute to a region. - P30 - DONE
117
118- specify a hole in the mesh by selecting a point bounded by
119  segments. - P30 - DONE
120
121
122- write an ascii file that outputs - P30 - DONE
123# of vertices
124[x,y]
125# of triangles
126[vert1 #, vert2 #, vert3 #, adjoining triangle 1, adjoining triangle
1272, adjoining triangle 3, attributes of region ]
128if there is no adjoining triangle, give -1 as the adjoining triangle.
129
130
131- specify how much vertex attribute information can be added to the mesh. -P40
132  - eg one attribute per vertex, two attributes per vertex
133- specify the default attribute vertex value - P40
134
135- edit segment attribute.  Can only select integers -P40 - DONE
136
137
138- load the following user vertex file layout
139  - First row {"Lat", "Long", "Depth"}
140  - Subsiquent rows x y positions with 1 attribute
141  - Initially, load the file type, ditching the attribute info - P3 DONE
142  - Use the attribute info - P60 - DONE
143
144- Have an ascii export/import file format, that fully specifies a mesh
145  - Add more output to the current export, so a mesh is fully specified
146  - Add an import of the exported format   - P60 - Done
147 
148- Print out the triangulation as a postscript file - P80 - DONE
149
150- Be able to tag boundaries with strings. - DONE
151 
152- Have a warning prompt when saving a mesh where the generated mesh is
153  different from the user mesh - eg boundary tags that aren't carried
154  thru. Warning ~"Mesh not generated after changes.  Generate mesh?  "
155  - cancel, don't gen, don't save.  Yes - generate mesh, go to save
156  screen.  No - goto save screen.  To implement this need to know when
157  the user has done a change, and the mesh hasn't been generated.  If
158  there is no generated mesh do not prompt. - DONE
159
160access to triangle mesh generator,
161          user can select  max area in region - P80 - DONE
162 
163- .xya file, which has vertex information, will have headers naming
164the attributes in the first row.  The headers will be strings
165representing a label for the attribute information.  This information
166will be space deliminated.  There will be no ordering imposed.  The
167name, column index mapping will be in the .tsh file.
168      - x and y headings are manitory. - not done, requirements changed
169      - Missing fields will cause an error during loading of the xya file.
170
171 
172 NOT IMPLIMENTED
173- show file name in title bar
174 
175- Have a divide all max areas by value x function. - P80
176
177- triang.genMesh - get triangle compiled automatically.
178
179- able to specify a 'circular' region by specifying center, radius and
180  number of number of segments. (The functionality is there as a hack.
181   need to add gui etc.) - P100
182   
183- Display mouse point position [x,y] - P60
184
185- Calculate total area enclosed (maybe a buton?) -P80
186          (this requirement GUI aspect needs to be fleshed out with Chris)
187         
188- Load in a segment attribute to boundary mapping.  ie segment
189  attribute is 'seen' as a boundary, such as a 0 flux boundary and
190  this is interanally represented as an interger, as defined by the
191  mapping. - P100
192 
193- Select segment attribute from an enumerated list of boundaries. - P100
194 
195- Select segment attribute from an enumerated list of boundaries and
196  can also input values of constants described in the boundary. - P100
197
198- Select objects  - Be able to select multiple objects.  Eg select
199  many segments and mark with one attribute -P100
200
201- Be able to select objects by "mouse dragging" a rectangle. (A
202  rectangle whos size and position is controlled by the mouse)
203  Everything within the rectangle is selected.
204 
205- Move user vertices  - can initially be  done by
206  adding/deleting vertices and segments. -P100 [should we have this feature?]
207
208- specify a maximum area for each triangle, based on current mesh
209  (this is refinement of the current mesh) - P100
210
211- able to specify a 'circular' region by specifying center, radius and
212  number of number of segments. - P100
213 
214-Log window.  Have a separate window that displays log information.
215This window can be turned on or off. - P100
216
217- Log information of the generation mesh process.  - P100
218  - max area
219  - minimum angle
220  [Other information to be determined ]
221
222- reduce mesh generation crashing by only mesh generating if all of the
223vertices are bounded by segments. - P100
224
225- Set the initial mesh co-ordinate to origin (0,0) at canvas bottom left and
226  (100,100)at canvas top right.
227
228- Have info with the mesh, such as #of triangles, min angle, max area
229          (this requirement GUI aspect needs to be fleshed out with Chris)
230         
231- Put postscript/clear/close buttons as a menu, not at the bottom of
232  pmesh
233 
234- assume the scale is metres, important for the programs using the
235mesh.  Maybe in add vertex have the scale?
236
237- be able to add two .tsh files together.
238
239- run triangle as a seperate thread, so if it's not converging it can
240be stopped. - P100
241 
242
243__________________
244 
245The information below describe the various colours for drawn objects,
246given the objects state.
247User Vertex, not selected  - small black rectangle (to represent a point)
248             selected      - small red rectangle
249             selected when adding a segment - small orange rectangle
250User Segment, not selected  - blue line
251             selected      - red line
252             
253Computer Vertices and Segments will not be drawn
254Computer Triangle,  not selected  - green triangle
255             selected      - red triangle (can be selected to add max
256             area value when refining triangulations)
257_________________________
258
259
260DEVELOPMENT
261
262The pmesh software will be developed using an iterative approach, with
263it being "released" several times and each release having increased
264functionality. The first iteration will be a minimal system.
265Requirements to be delivered in each iteration are described below.
266
267Currently four iterations are planned.
268Each requirement is associated with an iteration, via the requirement's
269priority, represented by a P number. P1, P2, P3 etc.
270
271 
2721st iteration P1 & P2 - basic framework, loading and saving of meshes
2732nd iteration P3      - specifying  # of triangles in mesh
2743rd iteration P30     - specify holes, regions and having attributes
275                        for regions 
2764rd iteration P40     - attribute and boundary manipulation
277                         
2785th iteration P60     - increased GUI functionality
279
2806th iteration P80     - region selection, selection of different max
281                         triangle areas based on region, segments
282                        automatically added
283Future iterations P100   
284__________________________
285
286NOTES
287
288How to speed things up.
289Use numericpy to build the data structures and then pass them straight
290to the triangle.o (This is assuming the numericpy data structures are
291in a c format.) - Don't lose the OO structure though.
292
293preallocate lists, instead of calling c repeditively
294_______
295Questions
296What format will the initial data in? Chris is going to find an inital
297format, from previous work.
298
299How will data be taken in future? ie do we have datasets that we will
300convert or will we hand generate initial data sets?
301 
302What s/w package takes care of the boundary conditions?
303[this seems to be an open issue still.]
304
305Things to work out with Chris and Steve:
306How can the quality of the meshes be tested? Chris believes triangle
307diagnostices should provide this information.
308
309Will we need this?
310  -L  Do not use diametral lenses to determine whether subsegments are
311        encroached; use diametral circles instead (as in Ruppert's
312        algorithm).  Use this switch if you want all triangles in the mesh
313        to be Delaunay, and not just constrained Delaunay; or if you want
314        to ensure that all Voronoi vertices lie within the triangulation.
315        (Applications such as some finite volume methods may have this
316        requirement.)  This switch may increase the number of vertices in
317        the mesh to meet these constraints.
318 ________________________________________________________________
319
320REQUIREMENT ISSUES
321
322 - if a vertex with attribute info is moved, the attribute info does
323 not change.  This will not reflect the actual environment. Option
324 1)The user can enter correct attribute data
325 
326 2) the s/w can interpolate, based on the original vertex data.
327 
328 Currently suggesting option 1 - Duncan and Chris.
329 
330CVS INFORMATION FOR THIS FILE
331$Source: /var/lib/cvs/pmesh/documentation/mesh_gen_SRS.txt,v $
Note: See TracBrowser for help on using the repository browser.