image = formula3dImg (inImageFormula3d,formulaInOptImages)

Detailed Description

algorithm allowing to generate a 3d image using a formula string

This algorithm allows to generate an image from a formula string. It can be used into several cases such as:

gather a multi step processing in a single function call,
image custom masking,
image filtering with custom kernel,
image complex arithmetic formula application.

A detailled description of image formula framework can be found at Image Formula.

The used image border policy during processing is controlled by parameter $InOptConvolBorder3d$ (see Border policy for more details).

Input images management

All input are optional for this algorithm, each input is associated to a string image identifier (see ipsdk::image::tools::eFormulaImageId):

$InOptImg3d1 \Leftrightarrow I1$
$InOptImg3d2 \Leftrightarrow I2$
$InOptImg3d3 \Leftrightarrow I3$
$InOptBinImg3d1 \Leftrightarrow B1$
$InOptBinImg3d2 \Leftrightarrow B2$
$InOptBinImg3d3 \Leftrightarrow B3$
$InOptLabImg3d1 \Leftrightarrow L1$
$InOptLabImg3d2 \Leftrightarrow L2$
$InOptLabImg3d3 \Leftrightarrow L3$

Shape of all provided images must be the same.

All referenced input images must be provided for processing (if for example $L2$ appears in formula string, the user should provide $InOptLabImg2$ input image).

Input images $InOptImg1$ , $InOptImg2$ and $InOptImg3$ are generic input images associated to an arithmetic (eImageFormulaResultType::eMFRT_Arithmetic) result type. These images must share same image buffer type.

Input images $InOptBinImg1$ , $InOptBinImg2$ and $InOptBinImg3$ are binary input images associated to a logical (eImageFormulaResultType::eMFRT_Logic) result type. These images must be associated to a binary image buffer type (eImageBufferType::eIBT_Binary).

Input images $InOptLabImg1$ , $InOptLabImg2$ and $InOptLabImg3$ are label input images associated to an arithmetic (eImageFormulaResultType::eMFRT_Arithmetic) result type. These images must share same image buffer type (eImageBufferType::eIBT_Label16 or eImageBufferType::eIBT_Label32).

Input images management

If the output image is provided, its shape must be the same as input optional images (if any) and its image buffer type must complies with formula result type (see Result type):

the output image buffer type is free if formula result type is arithmetic,
the output image buffer type must be binary if formula result type is logic.

If the output image is not provided, its shape is determined using the input optional images shape. If no input optional images are requested for formula processing, the user can provide $InOptImg1$ image as a model for output shape. In case where the output image is not provided, the output image will be set to floating point in case of arithmetic formula result type and to binary in case of logical formula result type.

Processing samples

Mask operations

Following codes allow to use an image formula to generate a circular centered mask image:

Python code :
outBinImg = arithm.formula3dImg("if(sqrt((x-cx)*(x-cx)+(y-cy)*(y-cy)+(z-cz)*(z-cz))<=30, True, False)", InOptImg3d1=inImg)
C++ code :
FormulaInOptImages inOptImages;
inOptImages._pInOptImg1 = pInImg;
ImagePtr pOutBinImg = arithm::formula3dImg("if(sqrt((x-cx)*(x-cx)+(y-cy)*(y-cy)+(z-cz)*(z-cz))<=30, True, False)", inOptImages);
In this case, the input image is only used as a model for output image shape. The output image buffer type is set to binary since this formula string is associated to a logical result type.

Other samples

Please refers to Processing samples for additional presentation of image formula applications in 2d case.

Example of Python code :

Example imports

import PyIPSDK
import PyIPSDK.IPSDKIPLArithmetic as arithm
import PyIPSDK.IPSDKIPLBinarization as bin
import PyIPSDK.IPSDKIPLAdvancedMorphology as advmorpho
import PyIPSDK.IPSDKIPLIntensityTransform as itrans
import PyIPSDK.IPSDKIPLUtility as util

Code Example

    # opening input images
    inImg1 = PyIPSDK.loadTiffImageFile(inImg1Path)
    inImg2 = PyIPSDK.loadTiffImageFile(inImg2Path)
    inImg3 = itrans.equalize3dImg(inImg2, PyIPSDK.createRange(50, 200))
    inImg4 = PyIPSDK.loadTiffImageFile(inImg4Path)
    inBinImg1 = bin.thresholdImg(inImg4, 50000, 65535);
    inLabImg1 = advmorpho.connectedComponent3dImg(inBinImg1)
    
    # we draw a binary sphere, its inverse and a grey sphere
    outBinImg1_1 = arithm.formula3dImg("if((x-cx)*(x-cx)+(y-cy)*(y-cy)+(z-cz)*(z-cz)<=10, True, False)", InOptImg3d1=inImg1)
    outBinImg1_2 = arithm.formula3dImg("if((x-cx)*(x-cx)+(y-cy)*(y-cy)+(z-cz)*(z-cz)<=10, False, True)", InOptImg3d1=inImg1)
    outGreyImg1_1 = arithm.formula3dImg("if((x-cx)*(x-cx)+(y-cy)*(y-cy)+(z-cz)*(z-cz)<=10, 200, 100)", InOptImg3d1=inImg1)
    # we smooth input image using a mean filter with a rectangular kernel
    # and a median filter with a spherical kernel
    # Default output type for arithmetical results is floating point
    # In second case we force output image and so its type to unsigned char
    outGreyImg2_1 = arithm.formula3dImg("mean(rect(I1, 3, 2, 1))", InOptImg3d1=inImg1)
    outGreyImg2_2 = util.copyImg(inImg1)
    arithm.formula3dImg("mean(rect(I1, 3, 2, 1))", InOptImg3d1=inImg1,
                        InOptConvolBorder3d=PyIPSDK.mirorBorder3d(), OutImg=outGreyImg2_2)
    outGreyImg2_3 = util.copyImg(inImg1)
    arithm.formula3dImg("median(sphere(I1, 2))", InOptImg3d1=inImg1, OutImg=outGreyImg2_3)
    # we use statistics on an image to filter values on an other one
    outGreyImg3_1 = arithm.formula3dImg("if(I1<GLMean(I2)-1.5*GLStdDev(I2), GLMean(I2)-1.5*GLStdDev(I2), if(I1>GLMean(I2)+1.5*GLStdDev(I2), GLMean(I2)+1.5*GLStdDev(I2), I1))",
                                        InOptImg3d1=inImg2, InOptImg3d2=inImg3)
    outGreyImg3_2 = arithm.formula3dImg("lut(I1<GLMean(I2)-1.5*GLStdDev(I2):GLMean(I2)-1.5*GLStdDev(I2), I1>GLMean(I2)+1.5*GLStdDev(I2):GLMean(I2)+1.5*GLStdDev(I2); I1)",
                                        InOptImg3d1=inImg2, InOptImg3d2=inImg3)
    # we use a label image to mask an input image and retrieve only grey levels
    # associated to given particules label
    outGreyImg4_1 = arithm.formula3dImg("if(L1>50 && L1<100, I1, 0)",
                                        InOptImg3d1=inImg4,
                                        InOptLabImg3d1=inLabImg1)
                                        
    # we use image offsets to compute a "cross like" mean smoothing operation
    outGreyImg5_1 = arithm.formula3dImg("mean(I1, I1(-1, 0, 0), I1(0, 1, 0), I1(0, -1, 0), I1(0, 1, 0), I1(0, 0, -1), I1(0, 0, 1))", InOptImg3d1=inImg1)

Example of C++ code :

Example informations

Header file

#include <IPSDKIPL/IPSDKIPLArithmetic/Processor/Formula3dImg/Formula3dImg.h>

Code Example

    // we draw a binary sphere, its inverse and a grey sphere
    FormulaInOptImages inOptImages1;
    inOptImages1._pInOptImg1 = pInImg1;
    ImagePtr pOutBinImg1_1 = formula3dImg("If((x-cx)*(x-cx)+(y-cy)*(y-cy)+(z-cz)*(z-cz)<=10, True, False)", inOptImages1);
    ImagePtr pOutBinImg1_2 = formula3dImg("If((x-cx)*(x-cx)+(y-cy)*(y-cy)+(z-cz)*(z-cz)<=10, False, True)", inOptImages1);
    ImagePtr pOutGreyImg1_1 = formula3dImg("If((x-cx)*(x-cx)+(y-cy)*(y-cy)+(z-cz)*(z-cz)<=10, 200, 100)", inOptImages1);
    // we smooth input image using a mean filter with a rectangular kernel
    // and a median filter with a spherical kernel
    // Default output type for arithmetical results is floating point
    // In second case we repeate this operation with a custom border policy
    // In third case we force output image and so its type to unsigned char
    FormulaInOptImages inOptImages2;
    inOptImages2._pInOptImg1 = pInImg1;
    ImagePtr pOutGreyImg2_1 = formula3dImg("mean(rect(I1, 3, 2, 1))", inOptImages2);
    ImagePtr pOutGreyImg2_2 = copyImg(pInImg1);
    formula3dImg("mean(rect(I1, 3, 2, 1))", inOptImages2, mirorBorder3d(), pOutGreyImg2_2);
    ImagePtr pOutGreyImg2_3 = copyImg(pInImg1);
    formula3dImg("median(sphere(I1, 2))", inOptImages2, pOutGreyImg2_3);
    // we use statistics on an image to filter values on an other one
    FormulaInOptImages inOptImages3;
    inOptImages3._pInOptImg1 = pInImg2;
    inOptImages3._pInOptImg2 = pInImg3;
    ImagePtr pOutGreyImg3_1 = formula3dImg("If(I1<GLMean(I2)-1.5*GLStdDev(I2), GLMean(I2)-1.5*GLStdDev(I2), If(I1>GLMean(I2)+1.5*GLStdDev(I2), GLMean(I2)+1.5*GLStdDev(I2), I1))", inOptImages3);
    ImagePtr pOutGreyImg3_2 = formula3dImg("lut(I1<GLMean(I2)-1.5*GLStdDev(I2):GLMean(I2)-1.5*GLStdDev(I2), I1>GLMean(I2)+1.5*GLStdDev(I2):GLMean(I2)+1.5*GLStdDev(I2); I1)", inOptImages3);
    // we use a label image to mask an input image and retrieve only grey levels
    // associated to given particules label
    FormulaInOptImages inOptImages4;
    inOptImages4._pInOptImg1 = pInImg4;
    inOptImages4._pInOptLabImg1 = pInLabImg1;
    ImagePtr pOutGreyImg4_1 = formula3dImg("If(L1>50 && L1<100, I1, 0)", inOptImages4);
    // we use image offsets to compute a "cross like" mean smoothing operation
    FormulaInOptImages inOptImages5;
    inOptImages5._pInOptImg1 = pInImg1;
    ImagePtr pOutGreyImg5_1 = formula3dImg("mean(I1, I1(-1, 0, 0), I1(0, 1, 0), I1(0, -1, 0), I1(0, 1, 0), I1(0, 0, -1), I1(0, 0, 1))", inOptImages5);