Changeset 3087

Timestamp:

Jun 5, 2006, 5:07:42 PM (19 years ago)

Author:

howard

Message:

Added material on geo_spatial data and alpha shapes to Appendix A

File:

• documentation/user_manual/anuga_user_manual.tex (modified) (2 diffs)

documentation/user_manual/anuga_user_manual.tex

@@ -1175 +1175 @@
 store and manipulate data associated with a mesh. The mesh is
 specified either by assigning the name of a meshfile to
-\code{source} or by 
+\code{source} or by
 \end{classdesc}
 
@@ -2196 +2196 @@
     default_attribute_name = None,
     file_name = None}
-
-
-
-Create instance from data points and associated attributes
-
-
-        data_points: x,y coordinates in metres. Type must be either a
-        sequence of 2-tuples or an Mx2 Numeric array of floats.
-
-        attributes: Associated values for each data point. The type
-        must be either a list or an array of length M or a dictionary
-        of lists (or arrays) of length M. In the latter case the keys
-        in the dictionary represent the attribute names, in the former
-        the attribute will get the default name 'attribute'.
-
-        geo_reference: Object representing the origin of the data
-        points. It contains UTM zone, easting and northing and data
-        points are assumed to be relative to this origin.
-        If geo_reference is None, the default geo ref object is used
-
-        default_attribute_name: Name of default attribute to be used with
-        get_attribute_values. The idea is that the dataset can be
-        equipped with information about which attribute to return.
-        If None, the default is the 'first'
-
-        file_name: Name of input NetCDF file or xya file. NetCDF file must
-        have dimensions "points" etc.
-        XYA file is a CVS file with lats(x), longs(y) and elevation(a).
-        first line must be attribute name eg elevation
-
+Module: \code{geospatial_data}
+
+This class is used to store a set of data points and associated
+attributes, allowing these to be manipulated by methods defined for
+the class.
+
+The data points are specified either by reading them from a NetCDF
+or XYA file, identified through the parameter \code{file_name}, or
+by providing their \code{x}- and \code{y}-coordinates in metres,
+either as a sequence of 2-tuples of floats or as an $M \times 2$
+Numeric array of floats, where $M$ is the number of points.
+Coordinates are interpreted relative to the origin specified by the
+object \code{geo_reference}, which contains data indicating the UTM
+zone, easting and northing. If \code{geo_reference} is not
+specified, a default is used.
+
+Attributes are specified through the parameter \code{attributes},
+set either to a list or array of length $M$ or to a dictionary whose
+keys are the attribute names and whose values are lists or arrays of
+length $M$. One of the attributes may be specified as the default
+attribute, by assigning its name to \code{default_attribute_name}.
+If no value is specified, the default attribute is taken to be the
+first one.
 \end{classdesc}
 
+
+\begin{funcdesc}{import_points_file}{delimiter = None, verbose = False}
+
+\end{funcdesc}
+
+
+\begin{funcdesc}{export_points_file}{ofile, absolute=False}
+
+\end{funcdesc}
+
+
+\begin{funcdesc}{get_data_points}{absolute = True}
+
+\end{funcdesc}
+
+
+\begin{funcdesc}{set_attributes}{attributes}
+
+\end{funcdesc}
+
+
+\begin{funcdesc}{get_attributes}{attribute_name = None}
+
+\end{funcdesc}
+
+
+\begin{funcdesc}{get_all_attributes}{}
+
+\end{funcdesc}
+
+
+\begin{funcdesc}{set_default_attribute_name}{default_attribute_name}
+
+\end{funcdesc}
+
+
+\begin{funcdesc}{set_geo_reference}{geo_reference}
+
+\end{funcdesc}
+
+
+\begin{funcdesc}{__add__}
+
+\end{funcdesc}
+
+
 \section{pmesh GUI}
 
 \section{alpha_shape}
-
-
-\section{utilities/numerical_tools} Do now.
+An \emph{alpha shape} is a shape created from a set of points in the
+plane, according to an algorithm. This shape is intended to capture
+the intuitive notion of the `shape formed by the points'. For a
+sufficiently simple set, the alpha shape reduces to the more precise
+notion of the convex hull, but in general an alpha shape can be much
+much more complex and may be far from convex.
+
+In the context of \anuga, an alpha shape is used to fit a polygonal
+boundary around a set of points when fitting a mesh to a region. The
+algorithm uses a parameter $\alpha$ that can be adjusted to make the
+resultant shape resemble the shape suggested by intuition more
+closely.
+
+The following paragraphs describe the class used to model an alpha
+shape and some of the more important methods and attributes
+associated with instances of this class.
+
+\begin{classdesc}{Alpha_Shape}{points, alpha = None}
+Module: \code{alpha_shape}
+
+To instantiate this class the user supplies the points from which
+the alpha shape is to be created (in the form of a list of 2-tuples
+\code{[[x1, y1],[x2, y2]}\ldots\code{]}, assigned to the parameter
+\code{points}) and, optionally, a value for the parameter $\alpha$.
+The alpha shape is then computed and details of the required
+boundary may be retrieved as attributes of the class instance.
+\end{classdesc}
+
+
+\begin{funcdesc}{alpha_shape_via_files}{point_file, boundary_file, alpha= None}
+Module: \code{alpha_shape}
+
+This function reads points from the specified file
+\code{point_file}, computes the associated alpha shape (either using
+the specified value for \code{alpha} or, if no value is specified,
+automatically setting it to a value judged to be optimal} and
+outputs the boundary to a file named \code{boundary_file}. This
+output file lists the coordinates \code{x, y} of each point in the
+boundary, using one line per point.
+\end{funcdesc}
+
+
+\begin{funcdesc}{set_boundary_type}{self,raw_boundary=True,
+                          remove_holes=False,
+                          smooth_indents=False,
+                          expand_pinch=False,
+                          boundary_points_fraction=0.2}
+Module: \code{alpha_shape}
+
+This function sets flags that govern the operation of the algorithm
+that computes the boundary, 
+        raw_boundary    Return raw boundary i.e. the regular edges of the
+                        alpha shape.
+        remove_holes    filter to remove small holes
+                        (small is defined by  boundary_points_fraction )
+        smooth_indents  remove sharp triangular indents in boundary
+        expand_pinch    test for pinch-off and correct
+                           i.e. a boundary vertex with more than two edges.
+\end{funcdesc}
+
+\section{utilities/numerical_tools}
+
+\begin{tabular}{|l l|}  \hline
+\code{angle(v1, v2=None)} & Angle between two-dimensional vectors
+\code{v1} and \code{v2}, in range $0$ to $2\pi$. If \code{v2} is
+omitted it is taken as the unit vector in the $x$-direction.\\
+
+\code{normal_vector(v)} & Normal vector to \code{v}\\
+
+\code{mean(x)} & Mean value of a vector\\
+
+\code{cov(x, y=None)} & Covariance of vectors \code{x} and \code{y}.
+If y is None, returns \code{cov(x, x)}\\
+
+\code{err(x, y=0, n=2, relative=True)} & Relative error of
+$\parallel$\code{x}$-$\code{y}$\parallel$ to
+$\parallel$\code{y}$\parallel$ (2-norm if \code{n} = 2 or Max norm
+if \code{n} = None). If denominator evaluates to zero or if \code{y}
+is omitted, absolute error is returned.\\
+
+\code{norm(x)} & 2-norm of \code{x}\\
+
+\code{corr(x, y=None)} & Correlation of \code{x} and \code{y}. If
+\code{y} is \code{None} returns autocorrelation of \code{x}.\\
+
+\code{ensure_numeric(A, typecode = None)} & Ensure that sequence is
+a Numeric array. If \code{A} is already a Numeric array it will be
+returned unaltered. Otherwise, an attempt is made to convert it to a
+Numeric array. This function is necessary as \code{array(A)} can
+cause memory overflow.\\
+
+\code{histogram(a, bins, relative=False)} & Standard histogram. If
+\code{relative} is \code{True}, values will be normalised against
+the total and thus represent frequencies rather than counts.\\
+
+\code{create_bins(data, number_of_bins = None)} & Safely create bins
+for use with histogram. If data contains only one point or is
+constant, one bin will be created. If \code{number_of_bins} is
+omitted, 10 bins will be created.\\  \hline
+
+\end{tabular}
+
 
 \begin{itemize}