Woolz Image Processing  Version 1.7.0
WlzBinaryOps

## Modules

WlzScalarBinaryOp

## Files

file  Wlz2DContains.c
Takes a WLZ_2D_DOMAINOBJ, calls WlzLabel to split the domain and returns the one containing point(x,y).

file  WlzIntersect2.c
Calculates the intersection between two domain objects.

file  WlzIntersect3d.c
Intersection (set intersection) routines for domain objects.

file  WlzIntersectN.c
Intersection of N woolz domain objects.

file  WlzLabel.c
Segments a domain object into disconnected regions.

file  WlzLabel3D.c
3D labeling (segmention).

file  WlzRegConCalc.c
Computes region connected calculus spatial classifications.

file  WlzSplitObj.c
Functions to split a single object into component objects.

file  WlzUnion2.c
Convenience function to calculate the union of two domain objects.

file  WlzUnion3d.c
Computes the set union of 3D objects.

file  WlzUnionN.c
Computes the set union of N objects.

## Functions

WlzObjectWlz2DContains (WlzObject *obj, double x, double y, WlzErrorNum *dstErr)
Takes a WLZ_2D_DOMAINOBJ, calls WlzLabel to split the domain and returns the one containing point(x,y). More...

WlzObjectWlzIntersect2 (WlzObject *obj1, WlzObject *obj2, WlzErrorNum *dstErr)
Calculate the set intersection between two domain objects. This is a convenience routine calling WlzIntersectN with uvt=0. Input objects must be domain objects of the same type (2D or 3D) and non-NULL. Type WLZ_EMPTY_OBJ is legal, clearly an empty domain will be returned. More...

WlzObjectWlzIntersect3d (WlzObject **objs, int n, int uvt, WlzErrorNum *wlzErr)
Calculate the intersection betweena a list of 3D objects. Should not be used directly but is intended as a static procedure called from WlzIntersectN(). More...

WlzObjectWlzIntersectN (int n, WlzObject **objs, int uvt, WlzErrorNum *dstErr)
Calculate the intersection of a set of objects. If uvt=0 calculate domain only, uvt=1 calculate the mmean grey-value at each point. Input objects must be all non-NULL and domain objects of the same type i.e. either 2D or 3D otherwise an error is returned. More...

WlzErrorNum WlzLabel (WlzObject *obj, int *mm, WlzObject ***dstArrayObjs, int maxNumObjs, int ignlns, WlzConnectType connect)
Segments a domain into connected parts. Connectivity is defined by the connect parameter and can be 4- or 8-connected for 2D objects and 6-, 18- or 26-connected for 3D objects. Note this version requires that there is sufficient space in the objects array defined by maxNumObjs and this is not extended. This should be changed in future so that the array is extended as required. More...

WlzObjectWlzLabel3D (WlzObject *gObj, int maxObj, int ignLn, WlzConnectType con, WlzErrorNum *dstErr)
Labels (segments) a 3D domain object into connected component objects using their connectivity. More...

WlzRCCClass WlzRegConCalcRCC (WlzObject *obj0, WlzObject *obj1, int noEnc, int noOst, int maxOstDist, int *dstStatCnt, double **dstStatAry, WlzErrorNum *dstErr)
The given pair of spatial domain objects are classified using a RCC with optional enclosure and offset classifications. More...

WlzErrorNum WlzSplitObj (WlzObject *refObj, WlzObject *ppObj, int bWidth, double bgdFrac, double sigma, WlzCompThreshType compThrMethod, int nReqComp, int *dstNComp, WlzObject ***dstComp)
Splits the reference object into component objects cliped from the reference object, with the bounding box of each of the component objects determined using the pre-processed object. The component objects are returned in size order. More...

WlzErrorNum WlzSplitMontageObj (WlzObject *mObj, WlzPixelV gapV, double tol, int bWidth, WlzLong minArea, int maxComp, int *dstNComp, WlzObject ***dstComp)
Splits the given montage object into component objects clipped from the montage object. The montage object must be composed of component images embedded in a background, with little variation in the background values. More...

WlzObjectWlzUnion2 (WlzObject *obj1, WlzObject *obj2, WlzErrorNum *dstErr)
Convenience procedure to calculate the union of two woolz domain objects. This calls WlzUnnionN() with uvt=0. Objects must be of the same type. More...

WlzObjectWlzUnion3d (int n, WlzObject **objs, int uvt, WlzErrorNum *dstErr)
Private routine used by WlzUnionN() for 3D objects. More...

WlzObjectWlzUnionN (int n, WlzObject **objs, int uvt, WlzErrorNum *dstErr)
Calculate the set union of an array of domain objects. Domians only unless uvt non-zero in which case make an average grey table. Note background values are used in the averaging process. All objects must be domain objects of the same type (2D or 3D) unless WLZ_EMPTY_OBJ, NULL input objects are an error. More...

## Function Documentation

 WlzObject* Wlz2DContains ( WlzObject * obj, double x, double y, WlzErrorNum * dstErr )

Takes a WLZ_2D_DOMAINOBJ, calls WlzLabel to split the domain and returns the one containing point(x,y).

Returns
Object containing the point (x,y).
Parameters
 obj Given WLZ_2D_DOMAINOBJ object. x Column coordinate. y Line coordinate. dstErr Destination error code pointer, may be NULL.
 WlzObject* WlzIntersect2 ( WlzObject * obj1, WlzObject * obj2, WlzErrorNum * dstErr )

Calculate the set intersection between two domain objects. This is a convenience routine calling WlzIntersectN with uvt=0. Input objects must be domain objects of the same type (2D or 3D) and non-NULL. Type WLZ_EMPTY_OBJ is legal, clearly an empty domain will be returned.

Returns
Intersection object with NULL value table
Parameters
 obj1 first input object obj2 second input object dstErr error return.
Source:
WlzIntersect2.c

References WlzIntersectN().

 WlzObject* WlzIntersect3d ( WlzObject ** objs, int n, int uvt, WlzErrorNum * wlzErr )

Calculate the intersection betweena a list of 3D objects. Should not be used directly but is intended as a static procedure called from WlzIntersectN().

Returns
The intersection object with new value table as required. Empty intersection is returned as a WLZ_EMPTY_OBJ, NULL on error
Parameters
 objs list of objects to be included in the intersection n number of input objects uvt copy grey values flag, 0 do not copy, 1 copy. wlzErr error return.
Source:
WlzIntersect3d.c

Referenced by WlzIntersectN().

 WlzObject* WlzIntersectN ( int n, WlzObject ** objs, int uvt, WlzErrorNum * dstErr )

Calculate the intersection of a set of objects. If uvt=0 calculate domain only, uvt=1 calculate the mmean grey-value at each point. Input objects must be all non-NULL and domain objects of the same type i.e. either 2D or 3D otherwise an error is returned.

Returns
Intersection object with grey-table as required, if the intersection is empty returns WLZ_EMPTY_OBJ, NULL on error.
Parameters
 n number of input objects objs input object array uvt grey-table copy flag (1 - copy, 0 - no copy) dstErr error return.
Source:
WlzIntersectN.c
 WlzErrorNum WlzLabel ( WlzObject * obj, int * mm, WlzObject *** dstArrayObjs, int maxNumObjs, int ignlns, WlzConnectType connect )

Segments a domain into connected parts. Connectivity is defined by the connect parameter and can be 4- or 8-connected for 2D objects and 6-, 18- or 26-connected for 3D objects. Note this version requires that there is sufficient space in the objects array defined by maxNumObjs and this is not extended. This should be changed in future so that the array is extended as required.

Returns
Woolz error code.
Parameters
 obj Input object to be segmented. mm Number of objects for return. dstArrayObjs Object array for, allocated in this funtion. maxNumObjs Maximum number of object to return (determines the size of the array). ignlns Ignore objects with num lines <= ignlns. connect Connectivity to determine connected regions.
 WlzObject* WlzLabel3D ( WlzObject * gObj, int maxObj, int ignLn, WlzConnectType con, WlzErrorNum * dstErr )

Labels (segments) a 3D domain object into connected component objects using their connectivity.

Returns
A compund array object containing the labeled object components of the given object.
Parameters
 gObj Given object to be labeled. maxObj Maximum number of objects to be found in any plane. ignLn Ignore objects within a plane which have $$\geq$$ the given number of lines. con The connectivity to use in 3D. dstErr Destination error pointer, may be NULL.

Referenced by WlzLabel().

 WlzRCCClass WlzRegConCalcRCC ( WlzObject * obj0, WlzObject * obj1, int noEnc, int noOst, int maxOstDist, int * dstStatCnt, double ** dstStatAry, WlzErrorNum * dstErr )

The given pair of spatial domain objects are classified using a RCC with optional enclosure and offset classifications.

Returns
RCC classification of the given objects, ie object 0 is a returned classification of object 1.

For an explanation of RCC8 classifications see the type definition WlzRCCClass and the paper: D.A. Randell, etal, "Discrete Mereotopology for Spatial Reasoning in Automated Histological Image Analysis", PAMI 35(3) 2013. The RCC8 has been extended to include both tangential and non-tangential surrounds.

The RCC classification is performed using simple combinations of the Woolz union, intersection, exclusive or, dilation, fill and convex hull operators on an ordered pair of spatial domains( $$\Omega_0$$ and $$\Omega_1$$):

\begin{eqnarray*} C_0 &\leftarrow& \Omega_0 \cap \Omega_1 \neq \emptyset \\ C_1 &\leftarrow& \Omega_0^+ \cap \Omega_1 \neq \emptyset \\ C_2 &\leftarrow& (\Omega_0 \oplus \Omega_1) \neq \emptyset \\ C_3 &\leftarrow& (\Omega_0 \cup \Omega_1) \oplus \Omega_1 \neq \emptyset \\ C_4 &\leftarrow& (\Omega_0^+ \cup \Omega_1) \oplus \Omega_1 \neq \emptyset \\ C_5 &\leftarrow& (\Omega_0 \cup \Omega_1) \oplus \Omega_0 \neq \emptyset \\ C_6 &\leftarrow& (\Omega_0 \cup \Omega_1^+) \oplus \Omega_0 \neq \emptyset \\ C_7 &\leftarrow& (\Omega_0^{\bullet} \cup \Omega_1) \oplus \Omega_0^{\bullet} \neq \emptyset \\ C_8 &\leftarrow& (\Omega_0 \cup \Omega_1^{\bullet}) \oplus \Omega_1^{\bullet} \neq \emptyset \\ C_9 &\leftarrow& 2|\Omega_0 \cap \Omega_1^{\circ}| \ge |\Omega_0| \\ C_{10} &\leftarrow& 2|\Omega_0^{\circ} \cap \Omega_1| \ge |\Omega_1| \end{eqnarray*}

where are the $$\cup$$, $$\cap$$ and $$\oplus$$ are the set union (logical or), intersection (logical and) and xor (logical exclusive or) operators; $$\Omega^+$$ indicates the dilation of $$\Omega$$, $$\Omega^{\circ}$$ the convex hull of $$\Omega$$, $$\Omega^{\bullet}$$ indicates $$\Omega$$ filled and $$|\Omega|$$ the cardinality (area or volume) of $$\Omega$$. The decision tree for the classification excluding enclosure and offset is:

$C_0 \left\{ \begin{array}{ll} 0 & C_1 \left\{ \begin{array}{ll} 0 & C_7 \left\{ \begin{array}{ll} 0 & NTSURI \\ & \\ & \\ 1 & C_8 \left\{ \begin{array}{ll} 0 & NTSUR \\ & \\ 1 & DC \end{array} \right. \\ \end{array} \right. \\ & \\ & \\ 1 & C_7 \left\{ \begin{array}{ll} 0 & TSURI \\ & \\ & \\ 1 & C_8 \left\{ \begin{array}{ll} 0 & TSUR \\ & \\ 1 & EC \end{array} \right. \\ \end{array} \right. \\ \end{array} \right. \\ & \\ & \\ 1 & C_2 \left\{ \begin{array}{ll} 0 & EQ \\ & \\ & \\ 1 & C_3 \left\{ \begin{array}{ll} 0 & C_4 \left\{ \begin{array}{ll} 0 & NTPP \\ & \\ 1 & TPP \end{array} \right. \\ & \\ & \\ 1 & C_5 \left\{ \begin{array}{ll} 0 & C_6 \left\{ \begin{array}{ll} 0 & NTPPI \\ & \\ 1 & TPPI \end{array} \right. \\ & \\ 1 & PO \end{array} \right. \\ \end{array} \right. \\ \end{array} \right. \\ \end{array} \right.$

The statistics are computed for each classification as below:

 RCC Normalised Volume $$EMPTY(\Omega_0,\Omega_1)$$ 0.0 $$DC(\Omega_0,\Omega_1)$$ 0.0 $$EC(\Omega_0,\Omega_1)$$ 0.0 $$EQ(\Omega_0,\Omega_1)$$ 1.0 $$PO(\Omega_0,\Omega_1)$$ $$|\Omega_0 \cap \Omega_1|/ |\Omega_0 \cup \Omega_1|$$ $$TPP(\Omega_0,\Omega_1)$$ $$|\Omega_0|/|\Omega_0 \cup \Omega_1|$$ $$NTPP(\Omega_0,\Omega_1)$$ $$|\Omega_0|/|\Omega_0 \cup \Omega_1|$$ $$TPPI(\Omega_0,\Omega_1)$$ $$|\Omega_1|/|\Omega_0 \cup \Omega_1|$$ $$NTPPI(\Omega_0,\Omega_1)$$ $$|\Omega_1|/|\Omega_0 \cup \Omega_1|$$ $$TSUR(\Omega_0,\Omega_1)$$ $$|\Omega_0|/|\Omega_0 \cup \Omega_1|$$ $$TSURI(\Omega_0,\Omega_1)$$ $$|\Omega_1|/|\Omega_0 \cup \Omega_1|$$ $$NTSUR(\Omega_0,\Omega_1)$$ $$|\Omega_0|/|\Omega_0 \cup \Omega_1|$$ $$NTSURI(\Omega_0,\Omega_1)$$ $$|\Omega_1|/|\Omega_0 \cup \Omega_1|$$ $$ENC(\Omega_0,\Omega_1)$$ $$|\Omega_0 \cap \Omega_1^{\circ}|/|\Omega_0|$$ $$ENCI(\Omega_0,\Omega_1)$$ $$|\Omega_0^{\circ} \cap \Omega_1|/|\Omega_1|$$ $$OST(\Omega_0,\Omega_1)$$ $$q_1/(q_1 + q_2 - q_0)$$

Many of the objects that are computed during the classification are done so using a lazy evaluation with the functions WlzRCCMakeC() and WlzRCCMakeT().

Enclosure and offset are somwhat more expensive to compute than the other classifications, for this reason and because they are not strictly part of a RCC they can be avoided by setting the noEnc or noOst flags.

Enclosure will be computed if the noEnc has not been set and the classification is not one of WLZ_RCC_EQ, WLZ_RCC_TSUR, WLZ_RCC_TSURI, WLZ_RCC_NTSUR or WLZ_RCC_NTSURI. Enclosure is computed using:

$|\Omega_0 \cap \Omega_1^{\circ}|/|\Omega_0|$

for $$\Omega_0$$ to be encloded by $$\Omega_1$$ then at least half of $$\Omega_0$$ must intersect the convex hull of $$\Omega_1$$.

Offset will be computed if the noOst parameter has not been set and the classification is not WLZ_RCC_EQ. Offset is computed within a restricted domain in which all pixels/voxels are equidistant for the domains of the given objects:

$\Omega_e = (\Omega_0 \cup \Omega_1)^\circ \cap \Omega_0^{+d_{max}} \cap \Omega_1^{+d_{max}} \cap \Omega(D(\Omega_0) = D(\Omega_1))$

where $$D(\Omega)$$ is the distance transform of the domain $$\Omega$$. Within $$\Omega_e$$ the first, second and third quantiles ( $$q_0$$, $$q_1$$ and $$q_2$$) of the distances $$D(\Omega_0)$$ (or equivalently $$D(\Omega_1)$$) are computed. The ratio of the median to the median plus interquartile range is then computed and the domains are classified as offset if this ratio is greater than or equal to one half:

$\frac{q_1}{q_1 + q_2 - q_0} \geq 0.5$

Parameters
 obj0 First given spatial domain object. obj1 Second given spatial domain object. noEnc Don't include enclosure if non-zero. noOst Don't include offset if non-zero. maxOstDist Maximum distance for offset, not used if noOst is non-zero. dstStatCnt Destination pointer for the number of elements returned in the array of statistics (see above), may be NULL. Ignored if dstStatAry is NULL. dstStatAry Destination pointer for an array of statistics (see above), may be NULL. If an array is returned it should be freed using AlcFree(). dstErr Destination error pointer, may be NULL.
 WlzErrorNum WlzSplitObj ( WlzObject * refObj, WlzObject * ppObj, int bWidth, double bgdFrac, double sigma, WlzCompThreshType compThrMethod, int nReqComp, int * dstNComp, WlzObject *** dstComp )

Splits the reference object into component objects cliped from the reference object, with the bounding box of each of the component objects determined using the pre-processed object. The component objects are returned in size order.

Returns
Woolz error code.
Parameters
 refObj Reference object. ppObj Pre-processed object which is normalised to values in the range 0 - 255 as WlzUByte greys. bWidth Border width. bgdFrac Minimum fraction of values which are background values, with range [0.0+ - 1.0-]. sigma Histogram smoothing parameter used by WlzHistogramCnvGauss(). compThrMethod Method for computing threshold, used in call to WlzCompThresholdVT(). nReqComp Number of required components. dstNComp Destination pointer for the number of components extracted, must not be NULL. dstComp Destination pointer for the extracted components, must not be NULL.
 WlzErrorNum WlzSplitMontageObj ( WlzObject * mObj, WlzPixelV gapV, double tol, int bWidth, WlzLong minArea, int maxComp, int * dstNComp, WlzObject *** dstComp )

Splits the given montage object into component objects clipped from the montage object. The montage object must be composed of component images embedded in a background, with little variation in the background values.

Returns
Woolz error code.
Parameters
 mObj Montage object, which must be either a WLZ_2D_DOMAINOBJ or a WLZ_3D_DOMAINOBJ with values. gapV Value for the uniform background. Must be either WLZ_GREY_INT or WLZ_GREY_RGBA. tol Tolerance (fraction) for the variation in background values. bWidth Additional boundary width added to detected images before they are clipped. minArea Minimum area for a valid component image, must be greater than zero. maxComp Maximum number of components. dstNComp Destination pointer for the number of components extracted, must not be NULL. dstComp Destination pointer for the extracted components, must not be NULL.
 WlzObject* WlzUnion2 ( WlzObject * obj1, WlzObject * obj2, WlzErrorNum * dstErr )

Convenience procedure to calculate the union of two woolz domain objects. This calls WlzUnnionN() with uvt=0. Objects must be of the same type.

Returns
Union object pointer.
Source:
WlzUnion2.c
Parameters
 obj1 First inout object. obj2 Second input object. dstErr errro return.

References WlzUnionN().

 WlzObject* WlzUnion3d ( int n, WlzObject ** objs, int uvt, WlzErrorNum * dstErr )

Private routine used by WlzUnionN() for 3D objects.

Returns
Union object pointer.
Parameters
 n number of input objects objs object array uvt grey-table copy flag dstErr error return
Source:
WlzUnion3d.c

Referenced by WlzUnionN().

 WlzObject* WlzUnionN ( int n, WlzObject ** objs, int uvt, WlzErrorNum * dstErr )

Calculate the set union of an array of domain objects. Domians only unless uvt non-zero in which case make an average grey table. Note background values are used in the averaging process. All objects must be domain objects of the same type (2D or 3D) unless WLZ_EMPTY_OBJ, NULL input objects are an error.

This function may modify the order of the objects in the array it is passed if the array contains empty objects.

Returns
Union of the array of object.
Parameters
 n number of input objects objs input object array uvt grey-table copy flag, copy if non-zero. dstErr error return.
Source:
WlzUnionN.c