---
name: "VistaIOEdges"
section: "3"
platform: "linux"
package: "libvistaio-dev"
version: "1.2.19-3+b2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/VistaIOEdges"
---

# VistaIOEdges(3)

edge set representation

## 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)](/VistaIOReadFile/3.md), [**VistaIOWriteFile**(3)](/VistaIOWriteFile/3.md), and  [**VistaIOGetAttr**(3)](/VistaIOGetAttr/3.md).

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)](/VistaIOattribute/3.md)

## 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.**