image =	darkTopHat3dImg (inImg3d,inSEXYZ,inTopHatThreshold)
image =	darkTopHat3dImg (inImg3d,inSEXYZ,inTopHatThreshold,inOptBorderExtensionPolicy)
image =	lightTopHat3dImg (inImg3d,inSEXYZ,inTopHatThreshold)
image =	lightTopHat3dImg (inImg3d,inSEXYZ,inTopHatThreshold,inOptBorderExtensionPolicy)

Detailed Description

TopHat binary threshold on one 3d image.

Top-Hat transform is an operation which allows to extract small details from an image. This transformation is in this case associated to a thresholding operation to obtain a binary image. This algorithm can be customized to search for dark (black, which is the default) which is the default or light (white) small particules.

Top-Hat transformation, given a structuring element $ InSEXYZ $ , is associated to following formula :

Dark (black) top hat transform :
$T^D(InImg3d)_{InSEXYZ} = InImg3d \odot InSEXYZ - InImg3d$
Dark Top-Hat algorithm used a top-hat transform followed by a binarization step which can be illustrated as follow :
Light (white) top hat transform :
$T^L(InImg3d)_{InSEXYZ} = InImg3d - InImg3d \circledcirc InSEXYZ$
White Top-Hat algorithm used a top-hat transform followed by a binarization step which can be illustrated as follow :

Where $\odot$ and $\circledcirc$ are respectively a closing and an opening operation (see Opening 3d and Closing 3d).

Note: Behavior of this algorithm is specialized using specific morphological structuring elements (see 3d structuring elements for more informations about these shapes).
Please refer to Usage for examples of usage of different types of specific structuring elements during morphological operations.

An example of top-hat transform operation is illustrated in 2d case : see TopHat 2d.

See also: http://en.wikipedia.org/wiki/Top-hat_transform

Note

This algorithm is associated with three temporary working images ipsdk::imaproc::attr::OutOptWk1Img, ipsdk::imaproc::attr::OutOptWk2Img and ipsdk::imaproc::attr::OutWk1Img.

ipsdk::imaproc::attr::OutOptWk1Img will only be used if InOptBorderExtensionPolicy is set to ipsdk::imaproc::attr::eBorderExtensionPolicy::eBEP_Enable. This working temporary image can be provided by user or will be automatically allocated when requested.
The second one (ipsdk::imaproc::attr::OutOptWk2Img) is only used in special processing cases defined via ipsdk::imaproc::morpho::eSEProcessingCase enumerate. Such situation can be tested using ipsdk::imaproc::morpho::getSEProcessingCase function and associated image buffer type can be retrieved using ipsdk::imaproc::morpho::getSEWkImageBufferType. This working temporary image can be provided by user or will be automatically allocated when requested.
The third one (ipsdk::imaproc::attr::OutWk1Img) is systematically needed for internal processing. This working temporary image can be provided by user or will be automatically allocated.

Example of Python code :

Example imports

import PyIPSDK

import PyIPSDK.IPSDKIPLBinarization as bin

Code Example

    # opening of input images
    inImg = PyIPSDK.loadTiffImageFile(inputImgPath)
    
    # creation of used structuring element
    structuringElement = PyIPSDK.sphericalSEXYZInfo(5)
    
    # dark top hat 3d image computation
    outImg = bin.darkTopHat3dImg(inImg,  structuringElement,  20)

Example of C++ code :

Example informations

Header file

#include <IPSDKIPL/IPSDKIPLBinarization/Processor/TopHat3dImg/TopHat3dImg.h>

Code Example

    // create a 3x4x2 rectangular structuring element
    StructuringElementXYZInfoConstPtr pInSEXYZ = rectangularSEXYZInfo(3, 4, 2);
    // opening input image
    ImagePtr pInImg = loadTiffImageFile(inputImgPath);
    // compute dark tophat on input image
    ImagePtr pOutImgDark = darkTopHat3dImg(pInImg, pInSEXYZ, 30);