NAME

cxPyrActivePrev - flag as active/inactive the elements at the next higher pyramid layer
#include <cx/Pyramid.h>

char *cxPyrActivePrev(cxPyramid *pyr, long curLayer, long dstLayer, char *flg, cxPyrPrevType switch)
integer function cxPyrActivePrev( pyr, curLayer, dstLayer, flg, switch)
integer pyr
integer curLayer
integer dstLayer
character*1 flg(*)
integer switch
pyr
Input pyramid structure for which computations are to be performed.
curLayer
Input layer of currently active elements (1-based value).
dstLayer
Input layer of next active elements (1-based value).
flg
Input byte array indicating which elements are currently active in layer curLayer.
switch
Input selection of how to compute active status of an element from its connections.
Returns a pointer to a byte array indicating (with non-zero value) which elements are active in layer dstLayer, given that the flg elements are active in layer curLayer. Returns a NULL if its input is malformed, if an allocation error occurs, or if the destination layer is in a compressed region. cxPyrActivePrev accepts a byte vector of indicators showing which elements are active in the pyramid pyr at a given layer, and from this information computes which predecessor elements are active at the higher layer dstLayer. If dstLayer is less than curLayer, the routine returns a NULL pointer.

An element at the higher level may be considered active if any or all of the flg entries are non-zero, if the bitwise and or or of the flg entries are non-zero, or if the flg entries indicate a plane-crossing, depending on the value of the switch argument.

Position i of the returned byte array holds the result of the computation specified in switch, which may be a Boolean operand (0 or 1), a bitwise operand (a char containing 0s and 1s), or a plane-crossing operand.

The switch argument may take as its value one of the cxPyrPrevType enumerated values, which are defined as

  cx_pyramid_prev_logical_and
  cx_pyramid_prev_logical_or
  cx_pyramid_prev_identical_on
  cx_pyramid_prev_intersect
  cx_pyramid_prev_bitwise_and
  cx_pyramid_prev_bitwise_or
If switch is one of the logical (Boolean) or bitwise enumerations, the ith byte in the output vector gives the result of the respective computation over all flg entries comprising the ith element. For instance, if element i at dstLayer refers to elements j, k, and l at curLayer and if switch has value cx_pyramid_prev_logical_or, then the ith output byte is non-zero if any of flg[j], flg[k], or flg[l] is non-zero.

The remaining two enumerations are used to detect plane crossings within a pyramid. These operations make use of the auxilliary macro definitions

  PLANE_FALSE     = 0
  PLANE_ON        = 1
  PLANE_PLUS      = 2
  PLANE_MINUS     = 4
Given flg inputs within this set and a switch of cx_pyramid_prev_identical_on, an element at the next higher layer is given the flag PLANE_TRUE if all of its subordinate elements are flagged as PLANE_PLUS or PLANE_ON, or if all of its subordinate elements are flagged as PLANE_MINUS or PLANE_ON. Otherwise, an element at the next higher layer is given the flag PLANE_FALSE, which indicates that some of its subordinate elements are flagged as PLANE_FALSE or that its subordinate elements contain both PLANE_PLUS and PLANE_MINUS flags.

Given flg inputs within this set and a switch of cx_pyramid_prev_intersect, an element at the next higher layer is given the flag PLANE_FALSE if any of its subordinate elements is flagged as PLANE_FALSE, if all of its subordinate elements are flagged as PLANE_PLUS, or if all of its subordinate elements are flagged as PLANE_MINUS. Otherwise, an element at the next higher layer is given the flag PLANE_ON, which indicates that some of its subordinate elements are flagged as PLANE_ON or that its subordinate elements contain both PLANE_PLUS and PLANE_MINUS flags.

cxPyrActivePrev is useful in circumstances where a subset of the elements at a given level are to be manipulated, and the caller wishes to identify their containing elements to manipulate at a higher level. This is the approved way of determining which pyramid elements should be manipulated or displayed in any pyramid-based module (the alternative method of displaying all elements available at a given level may not be correct).

The returned indicator array is considered to be owned by the caller of cxPyrActivePrev and should be freed (with free(3C)) after use.

This routine is used extensively in the ClipPyr, CropPyr, and CullPyr modules. It could form the basis of any other pyramid module in which elements are kept or excluded on the basis of their constituent vertex locations or values.

cxPyramid(3E), cxPyrActive(3E), ClipPyr(1E), CropPyr(1E), CullPyr(1E).
Last modified: Mon Nov 6 16:33:42 GMT 2000
[ Documentation Home ]
© The Numerical Algorithms Group Ltd, Oxford UK. 1999

Website Feedback

If you would like a response from NAG please provide your e-mail address below.

(If you're a human, don't change the following field)
Your first name.
CAPTCHA
This question is for testing whether you are a human visitor and to prevent automated spam submissions.
Image CAPTCHA
Enter the characters shown in the image.