DIPlib Documentation - ©1995-2013 Quantitative Imaging Group, Delft University of Technology.

# StablePixelHeapNew

Create a new heap structure

## SYNOPSIS

`#include "dip_pixelqueue.h"`

dip_Error dip_StablePixelHeapNew ( heap, ndims, blocksize, order, resources )

## FUNCTION

This function allocates space for a new `dip_StablePixelHeap` structure. Memory allocated is tracked in `resources`. The heap is dimensioned to hold pixels from an `ndims`-dimensional image, and initially enough space is allocated for `blocksize` elements. The heap will be expanded as necessary when used.

The heap stores the coordinates, the value and the pointer to a pixel in an image. Note that the value does not need to equal the data pointed to by the pointer. `ndims` can be set to zero, in which case no coordinates are stored; this does not affect the function of the value and the pointer.

A heap is a priority queue data structure. Just like a queue, items can be added (pushed) and subtracted (popped). However, in the priority queue the item popped is always the higherst priority one: either the one with the highest-valued item (`order` is `DIP_GVSO_HIGH_FIRST`) or lowest-valued item (`order` is `DIP_GVSO_LOW_FIRST`). When various identically-valued items are stored on the heap, they will be extracted in the same order as they were insterted (FIFO - first in, first out). If this order is unimportant (such as for the `GrowRegionsWeighted` algorithm, use the more efficient `dip_PixelHeap` instead. See `PixelHeapNew` for information on the unstable heap structure.

## ARGUMENTS

Data type | Name | Description
`dip_StablePixelHeap *` | `heap` | The newly allocated heap structure
`dip_int` | `ndims` | Image dimensionality
`dip_int` | `blocksize` | Size of each allocation block
`dipf_GreyValueSortOrder` | `order` | Determines the heap's sort order
`dip_Resources` | `resources` | Resources tracking structure. See `ResourcesNew`

The `dipf_GreyValueSortOrder` enumeration consists of the following values:

Name | Description
`DIP_GVSO_HIGH_FIRST` | Process the pixels from high grey-value to low grey-value.
`DIP_GVSO_LOW_FIRST` | Process the pixels from low grey-value to high grey-value.

## IMPLEMENTATION

This data structure is implemented identically to `PixelHeapNew` (see that function's description for details), but an insertion order value is attached to each pixel pushed onto the heap. This is used to maintain stability.

## SEE ALSO

`PixelHeapNew`, `PixelQueueNew`, `StablePixelHeapFree`, `StablePixelHeapPush`, `StablePixelHeapPop`, `StablePixelHeapIsEmpty`