Provided by: libvistaio-dev_1.2.16-1_amd64 bug

NAME

       VistaIOEdges - edge set representation

SYNOPSIS

       #include <vistaio.h>

       VistaIOEdges edges;
       VistaIOEdge edge;

       VistaIOEdges VistaIOCreateEdges (int nrows, int ncolumns, int nedge_fields,
                 int npoint_fields)

       VistaIOEdge VistaIOAddEdge (VistaIOEdges edges, VistaIOFloat *edge_fields, int npoints,
                 VistaIOFloat *points, VistaIOBoolean closed, VistaIOBoolean copy)

       VistaIOEdges VistaIOCopyEdges (VistaIOEdges edges)

       void VistaIODestroyEdges (VistaIOEdges edges)

       int VistaIONEdgeFields (VistaIOEdges edges)

       int VistaIONPointFields (VistaIOEdges edges)

       int VistaIOEdgesNRows (VistaIOEdges edges)

       int VistaIOEdgesNColumns (VistaIOEdges edges)

       VistaIOAttrList VistaIOEdgesAttrList (VistaIOEdges edges)

       int VistaIONEdges (VistaIOEdges edges)

       VistaIOEdge VistaIOFirstEdge (VistaIOEdges edges)

       VistaIOEdge VistaIONextEdge (VistaIOEdge edge)

       VistaIOBoolean VistaIOEdgeExists (VistaIOEdge edge)

       VistaIOBoolean VistaIOEdgeClosed (VistaIOEdge edge)

       VistaIOFloat * VistaIOEdgeFields (VistaIOEdge edge)

       int VistaIOEdgeNPoints (VistaIOEdge edge)

       VistaIOFloat * VistaIOEdgePointArray (VistaIOEdge edge)

DESCRIPTION

   Introduction
       A  Vista  edge set is typically used to represent two-dimensional connected edge points or
       lines that have been extracted from images, but it can also be used to represent any  sets
       of vectors of floating point values.

       An  edge  set  in  memory is referred to by the C pointer type VistaIOEdges. In data files
       it's identified by the type name  edges,  and  in  memory,  by  the  VistaIORepnKind  code
       VistaIOEdgesRepn.  Since  it  is a standard object type with built-in support in the Vista
       library, edge sets can be read from data files, written to data files, and manipulated  as
       part  of  attribute lists by routines such as VistaIOReadFile(3), VistaIOWriteFile(3), and
       VistaIOGetAttr(3).

       A single edge, a member of an edge set, is referred to by the C pointer type VistaIOEdge.

   Data Structure
       The VistaIOEdges data structure heads a linked list of structures  each  representing  one
       edge.  An  edge  consists  of  an array of connected points along the edge, and each point
       contains a selected number of floating point values  specifying  its  location  and  other
       properties.  The  edge  itself  may  also  have a selected number of floating point fields
       attached to it. The VistaIOEdges data structure also specifies the  size  of  the  display
       region in which the edges are to be displayed.

       By  convention,  the first two values associated with each point give its x and y location
       within the display region, and the third value can be  used  to  represent  a  measure  of
       ``strength''  that  may  map  to  a  variable display intensity. The coordinate system for
       display of edges assumes that the origin is at  the  lower  left  corner  of  the  display
       region.  An application is free to assign other meanings to the various point values (they
       can be used to represent arbitrary floating point vectors), but then of course  they  will
       not be suitable for viewing with the standard display utilities.

   Accessing an Edge Set
       Vista  data  structures  are  accessed in an object-oriented style by macros and routines,
       with no need to know the details of the underlying C data  structures.  A  macro  that  is
       described as ``accessing'' an attribute can be used either as an rvalue (e.g, on the right
       hand side of an assignment operator) or as  an  lvalue  (on  the  left  hand  side  of  an
       assignment operator).

       VistaIOCreateEdges  initializes  and  returns  an  empty edge set.  The nrows and ncolumns
       arguments give the size of the display region (usually copied from the size of image  from
       which the edges were derived).  nedge_fields and npoint_fields give the number of floating
       point values that will be attached to each edge and point.

       VistaIOAddEdge adds a new edge to edges. npoints is the number of points in this edge. The
       field  values  for  each  of  the points is given sequentially in the floating point array
       points. The values for the fields attached to this edge are given in  edge_fields.  closed
       is TRUE if this edge is closed (i.e., the last point connects back to the first point). If
       copy is TRUE, then a new copy is made of the point and field data so  that  their  storage
       can be reused.

       VistaIOCopyEdges returns a copy of an edge set, made with newly-allocated storage.

       VistaIODestroyEdges  releases  the memory occupied by an edge set, including that occupied
       by all points and fields of each the edge.

       VistaIONEdgeFields returns the number of floating point fields that are attached  to  each
       edge.  This  number  is  established  when  the  edge set is first created and must not be
       changed later.

       VistaIONPointFields returns the number of floating point fields that are attached to  each
       point.  By  convention the first 2 fields are used to represent the x and y coordinates of
       the point. This number is established when the edge set is first created and must  not  be
       changed later.

       VistaIOEdgesNRows  accesses  the  number  of rows in the image from which the edge set was
       derived (i.e., it specifies the height of the display region).

       VistaIOEdgesNColumns accesses the number of columns in the image from which the  edge  set
       was derived (i.e., it specifies the width of the display region).

       VistaIOEdgesAttrList accesses the attribute list associated with an edge set.

       VistaIONEdges returns the number of edges currently in an edge set.

   Accessing an Individual Edge
       VistaIOFirstEdge returns the first edge in the linked list of edge records associated with
       an edge set.

       VistaIONextEdge returns the next edge in a set of edges.  (The  edges  are  chained  in  a
       linked list.)

       VistaIOEdgeExists returns FALSE if the edge pointer, edge, does not point to an edge. This
       is used to detect the end of the linked list when traversing through an edge set.

       VistaIOEdgeClosed returns TRUE if the edge, edge, is closed (i.e., its last point connects
       back to its first point).

       VistaIOEdgeFields returns the array of floating point values for the fields attached to an
       edge.

       VistaIOEdgeNPoints returns the number of points in an edge.

       VistaIOEdgePointArray returns a two-dimensional array, in  which  the  first  dimensionthe
       points and the second indexes each point fields.

   VistaIOEdges Representation in a Vista Data File
       attribute-name: edges {
              nedges: nedges
              npoints: npoints
              nedge_fields: nedge-fields
              npoint_fields: npoint-fields
              nrows: nrows
              ncolumns: ncolumns
              data: data-offset
              length: data-length
              other attributes
       }

       The  attributes  listed  above are the same as those accessed by the corresponding macros,
       with the exception of npoints which refers to the total number of points in all  edges  in
       this edge set.

       The  binary  data  is  simply a sequence of 32-bit floating point numbers in IEEE standard
       format. Data is present for each edge, in sequence. The first value for an edge  specifies
       the  number  of  points,  n,  in  the  edge;  it is negated if the edge is closed. This is
       followed by nedge_fields edge field values, then n vectors of  npoint_fields  point  field
       values.

EXAMPLES

       This code fragment iterates over the edges in an edge set and over the points in each edge
       while printing the first field of each point:

              for (e = VistaIOFirstEdge(edges); VistaIOEdgeExists(e); e = VistaIONextEdge(e))
                     for (i = 0; i < VistaIOEdgeNPoints(e); i++)
                            printf("%f ", (float) VistaIOEdgePointArray(e)[i][0]);

SEE ALSO

       VistaIOattribute(3)

AUTHOR

       David Lowe <lowe@cs.ubc.ca>

       Adaption to vistaio: Gert Wollny <gw.fossdev@gmail.com>

LIST OF ROUTINES

       The following table summarizes other Vista library routines that  operate  on  edge  sets.
       Each routine is documented elsewhere, by a section 3 man page named for the routine.

         VistaIOReadEdges
                        Read sets of edges from a Vista data file.

         VistaIOWriteEdges
                        Write sets of edges to a Vista data file.

         VistaIOLinkImage
                        Create an edge set by linking connected, non-zero image pixels.