Law's 3D Texture Energy MeasuresSee full documentation

image =	lawTexture3dImg (inImg3d)
image =	lawTexture3dImg (inImg3d,inKernelTypes,inPreProcParams,inPostProcParams)

Detailed Description

Apply Law's texture 3D filter on an image.

Law's texture filter generates texture features to quantify the perceived 3D textures of an image. It's a natural extension of Law's 2D Texture Energy Measures for 3D textures.

Law's texture 3D filter involves the following steps:

• pre-process phasis: subtract mean neighborhood intensity from each pixel of input image to obtain a zero-mean image and thus to remove effects of illumination. By default, the algorithm subtracts the mean of a cube neighborhood of size 15x15x15, but, depending on the provided pre-process parameters, the user has also the possibility to change the size of the cube neighborhood, or to subtract a gaussian smoothed neighborhood instead).

• filter the neighborhood by applying convolutions with the 63 5x5x5 Law's masks; Law's masks are built from the matrix multiplication of the 4 1D kernels described in Law's 2D Texture Energy Measures documentation along each one of the X, Y and Z axis.

  The 15 5x5 Law's masks are named :

  All these masks are zero-sum masks.

  Note: as would be a simple smoothing and would not bring any texture information, it is not computed.

• Compute the 63 energy images by either, depending on specified post-process parameters:
  • for each filtered voxel, averaging the absolute values across a cube neigborhood of a given size around voxel (this is the default mode, with a default kernel half-size of 7),
  • for each filtered voxel, averaging the values of filtered images across a cube neigborhood of a given size around voxel,
  • for each filtered voxel, smoothing the absolute values of neighborhood with a gaussian kernel,
  • for each filtered pixel, smoothing the values of neighborhood with a gaussian kernel,
  • for each filtered pixel, computed the variance of a cube neighborhood around voxel.

• Compute the 19 final energy maps, in order:

  • 
  • 
  • 
  • 
  • 
  • 
  • 
  • 
  • 
  • 
  • 
  • 
  • 
  • 
  • 
  • 
  • 
  • 
  • 

  For each one of these 19 final energy maps, each t-uple is replaced with the average of the t elements.

Resulting energy maps are concatenated in the output sequence image in the order specified above. Most of the time, only a subset of the 19 energy maps are interesting. By the way, by default, the algorithm only computes the subset. The user also has the possibility to specify his own subset by appropriately initializing a ipsdk::imaproc::attr::LawTextureKernel3dTypes data-item and passing it as argument of lawTexture3dImg function. Then only the maps of this subset will be calculated by the algorithm and returned to the user.

Example of Python code :

Example imports

import PyIPSDK
import PyIPSDK.IPSDKIPLStats as stats

Code Example

    # load input image from file
    inImg = PyIPSDK.loadTiffImageFile(inputImgPath, PyIPSDK.eTiffDirectoryMode.eTDM_Volume);

    # scenario 1: compute the Law's 3D texture energy measures with default parameters:
    # - pre-process phasis: subtract local mean (cube neighborhood of size 15x15x15)
    # - post-process phasis: compute energy maps using a local mean on absolute values (cube neighborhood of size 15x15x15)
    # - get the subset of 3 energy maps {E5E5E5, S5S5S5, R5R5R5}
    outImg = stats.lawTexture3dImg(inImg)

    # extract E5E5 energy map from output image; this is the firstimage in temporal sequence
    outImgE5E5E5 = PyIPSDK.extractVolume(0, 0, outImg)

    # scenario 2: compute the Law's 3D texture energy measures with customized parameters:
    # - pre-process phasis: subtract value resulting from local gaussian smoothing with (gaussianStdDev=0.7, gaussianRatio=0.991)
    # - post-process phasis: compute, for each pixel local variance on a cube neighborhood of size 17x17x17 (17 = 2*8 + 1)
    # - get the following subset of energy maps: {S5S5S5, S5S5R5, S5R5R5, R5R5R5}
    preProcParams = PyIPSDK.createGaussianLawTexPreProcParams(0.7, PyIPSDK.createGaussianCoverage(0.991, 2))
    postProcParams = PyIPSDK.createVarianceLawTexPostProcParams(8)
    kernelTypes = PyIPSDK.createLawTextureKernel3dTypes()

    # by default, only the flags {E5E5E5, S5S5S5, R5R5R5} are set to true, so reset E5E5E5 flag and set S5S5R5 and S5R5R5 flags
    kernelTypes.flagE5E5E5 = False
    kernelTypes.flagS5S5R5 = True
    kernelTypes.flagS5R5R5 = True

    outImg = stats.lawTexture3dImg(inImg, kernelTypes, preProcParams, postProcParams);

    # extract S5S5S5 energy map from output image (this is the first of 4 images in temporal sequence)
    outImgS5S5S5 = PyIPSDK.extractVolume(0, 0, outImg)

    # extract S5S5R5 energy map from output image (this is the second image in temporal sequence)
    outImgS5S5R5 = PyIPSDK.extractVolume(0, 1, outImg)

    # extract S5R5R5 energy map from output image (this is the third image in temporal sequence)
    outImgS5R5R5 = PyIPSDK.extractVolume(0, 2, outImg)

    # extract R5R5R5 energy map from output image (this is the third image in temporal sequence)
    outImgR5R5S5 = PyIPSDK.extractVolume(0, 3, outImg)

Example of C++ code :

Example informations

Header file

#include <IPSDKIPL/IPSDKIPLStats/Processor/LawTexture3dImg/LawTexture3dImg.h>

Code Example

    // load input image from file
    ImagePtr pInImg = loadTiffImageFile(inputImgPath, eTiffDirectoryMode::eTDM_Volume);

    // scenario 1: compute the Law's 3D texture energy measures with default parameters:
    // - pre-process phasis: subtract local mean (cube neighborhood of size 15x15x15)
    // - post-process phasis: compute energy maps using a local mean on absolute values (cube neighborhood of size 15x15x15)
    // - get the subset of 3 energy maps {E5E5E5, S5S5S5, R5R5R5}
    {
        ImagePtr pOutImg = stats::lawTexture3dImg(pInImg);

        // extract E5E5 energy map from output image; this is the firstimage in temporal sequence
        ImagePtr pOutImgE5E5E5;
        image::SubImageExtractor::extractVolume(0, 0, *pOutImg, pOutImgE5E5E5);
    }

    // scenario 2: compute the Law's 3D texture energy measures with customized parameters:
    // - pre-process phasis: subtract value resulting from local gaussian smoothing with (gaussianStdDev=0.7, gaussianRatio=0.991)
    // - post-process phasis: compute, for each pixel local variance on a cube neighborhood of size 17x17x17 (17 = 2*8 + 1)
    // - get the following subset of energy maps: {S5S5S5, S5S5R5, S5R5R5, R5R5R5}
    {
        attr::LawTexPreProcParamsPtr pPreProcParams = attr::createGaussianLawTexPreProcParams(0.7f, *createGaussianCoverage(0.991f, 2));
        attr::LawTexPostProcParamsPtr pPostProcParams = attr::createVarianceLawTexPostProcParams(8);
        attr::LawTextureKernel3dTypesPtr pKernelTypes = attr::createLawTextureKernel3dTypes();

        // by default, only the flags {E5E5E5, S5S5S5, R5R5R5} are set to true, so reset E5E5E5 flag and set S5S5R5 and S5R5R5 flags
        pKernelTypes->setValue<LawTextureKernel3dTypes::FlagE5E5E5>(false);
        pKernelTypes->setValue<LawTextureKernel3dTypes::FlagS5S5R5>(true);
        pKernelTypes->setValue<LawTextureKernel3dTypes::FlagS5R5R5>(true);

        ImagePtr pOutImg = stats::lawTexture3dImg(pInImg, pKernelTypes, pPreProcParams, pPostProcParams);

        // extract S5S5S5 energy map from output image (this is the first of 4 images in temporal sequence)
        ImagePtr pOutImgS5S5S5;
        image::SubImageExtractor::extractVolume(0, 0, *pOutImg, pOutImgS5S5S5);

        // extract S5S5R5 energy map from output image (this is the second image in temporal sequence)
        ImagePtr pOutImgS5S5R5;
        image::SubImageExtractor::extractVolume(0, 1, *pOutImg, pOutImgS5S5R5);

        // extract S5R5R5 energy map from output image (this is the third image in temporal sequence)
        ImagePtr pOutImgS5R5R5;
        image::SubImageExtractor::extractVolume(0, 2, *pOutImg, pOutImgS5R5R5);

        // extract R5R5R5 energy map from output image (this is the third image in temporal sequence)
        ImagePtr pOutImgR5R5S5;
        image::SubImageExtractor::extractVolume(0, 3, *pOutImg, pOutImgR5R5S5);
    }