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

# PixelHeapNew

Create a new heap structure

## SYNOPSIS

`#include "dip_pixelqueue.h"`

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

## FUNCTION

This function allocates space for a new `dip_PixelHeap` 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`). However, identically-valued items are stored on the heap in unpredictable order. If this order is important (such as for the `GrowRegions` algorithm with integer-valued pixels, use a `dip_StablePixelHeap` instead. See `StablePixelHeapNew` for information on the stable heap structure.

## ARGUMENTS

Data type | Name | Description
`dip_PixelHeap *` | `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

When the heap grows beyond its initial size, its capacity is doubled in size by reallocating the data blocks. However, when removing pixels from the queue, the heap is not shrunk. It is assumed that the `dip_PixelHeap` structure will be destroyed as soon as the algorithm using it terminates. Reducing the memory footprint of the heap therefore has no benefit.

## SEE ALSO

`StablePixelHeapNew`, `PixelQueueNew`, `PixelHeapFree`, `PixelHeapPush`, `PixelHeapPop`, `PixelHeapIsEmpty`