Ubuntu Manpage: VistaIOEdges - edge set representation

Provided by: libvistaio-dev_1.2.16-1_amd64

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]);

AUTHOR

       David Lowe <lowe@cs.ubc.ca>

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

LIST OF ROUTINES