Create a new heap structure
#include "dip_pixelqueue.h"
dip_Error dip_StablePixelHeapNew ( heap, ndims, blocksize, order, resources )
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.
| 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. |
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.
PixelHeapNew, PixelQueueNew, StablePixelHeapFree, StablePixelHeapPush, StablePixelHeapPop, StablePixelHeapIsEmpty