ImageDev

GradientOperator3d

Provides different algorithms to perform an edge detection based on the first derivative of a three-dimensional image.

Access to parameter description

This command is deprecated, it will be removed in ImageDev 2025.1.
You can use GradientVector3d or GradientMagnitude3d instead.

For an introduction: GradientOperator3d computes a first order derivative in each image axis direction. To minimize the effect of noise, the algorithm can be combined with a smoothing filter for computing the gradient. A smoothing scale parameter determines the smoothing intensity. If its value is large, noise is reduced but edges are less sharp and only the most significant edges are revealed. It is important to select the right coefficient to lower the noise just enough without defocusing the edges. Finally the algorithm optionally computes the magnitude of the gradient vectors either by selecting its maximum component or its Euclidean norm.
For color images the same algorithm is iterated on each color channel.

The following algorithms are provided to extract the edges of an image: Notices: References
[1] R.Deriche. "Using Canny's criteria to derive a recursively implemented optimal edge detector". International Journal of Computer Vision, vol.1, no 2, pp. 167-187, Jun. 1987.
[2] J.F.Canny. "A computational approach to edge detection." IEEE Transactions on Pattern Analysis and Machine Intelligence, vol.8, No 6, pp. 679-698, Nov. 1986.

See also

Function Syntax

This function returns a GradientOperator3dOutput structure containing outputImageX, outputImageY, outputImageZ and outputAmplitudeImage.
// Output structure of the gradientOperator3d function.
struct GradientOperator3dOutput
{
    /// The X-gradient output image.
    std::shared_ptr< iolink::ImageView > outputImageX;
    /// The Y-gradient output image.
    std::shared_ptr< iolink::ImageView > outputImageY;
    /// The Z-gradient output image.
    std::shared_ptr< iolink::ImageView > outputImageZ;
    /// The gradient amplitude output image.
    std::shared_ptr< iolink::ImageView > outputAmplitudeImage;
};

// Function prototype
GradientOperator3dOutput gradientOperator3d( std::shared_ptr< iolink::ImageView > inputImage, GradientOperator3d::GradientOperator gradientOperator, GradientOperator3d::GradientMode gradientMode, double smoothingFactor, std::shared_ptr< iolink::ImageView > outputImageX = NULL, std::shared_ptr< iolink::ImageView > outputImageY = NULL, std::shared_ptr< iolink::ImageView > outputImageZ = NULL, std::shared_ptr< iolink::ImageView > outputAmplitudeImage = NULL );
This function returns a tuple containing output_image_x, output_image_y, output_image_z and output_amplitude_image.
// Function prototype.
gradient_operator_3d( input_image,
                      gradient_operator = GradientOperator3d.GradientOperator.CANNY_DERICHE,
                      gradient_mode = GradientOperator3d.GradientMode.AMPLITUDE_MAXIMUM,
                      smoothing_factor = 60,
                      output_image_x = None,
                      output_image_y = None,
                      output_image_z = None,
                      output_amplitude_image = None )
This function returns a GradientOperator3dOutput structure containing outputImageX, outputImageY, outputImageZ and outputAmplitudeImage.
/// Output structure of the GradientOperator3d function.
public struct GradientOperator3dOutput
{
    /// The X-gradient output image.
    public IOLink.ImageView outputImageX;
    /// The Y-gradient output image.
    public IOLink.ImageView outputImageY;
    /// The Z-gradient output image.
    public IOLink.ImageView outputImageZ;
    /// The gradient amplitude output image.
    public IOLink.ImageView outputAmplitudeImage;
};

// Function prototype.
public static GradientOperator3dOutput
GradientOperator3d( IOLink.ImageView inputImage,
                    GradientOperator3d.GradientOperator gradientOperator = ImageDev.GradientOperator3d.GradientOperator.CANNY_DERICHE,
                    GradientOperator3d.GradientMode gradientMode = ImageDev.GradientOperator3d.GradientMode.AMPLITUDE_MAXIMUM,
                    double smoothingFactor = 60,
                    IOLink.ImageView outputImageX = null,
                    IOLink.ImageView outputImageY = null,
                    IOLink.ImageView outputImageZ = null,
                    IOLink.ImageView outputAmplitudeImage = null );

Class Syntax

Parameters

Class Name GradientOperator3d

Parameter Name Description Type Supported Values Default Value
input
inputImage
The input image. Image Binary, Label, Grayscale or Multispectral nullptr
input
gradientOperator
The gradient operator to apply.
CANNY_DERICHE The gradient is computed using the Canny-Deriche algorithm. Supported gradient output modes : AMPLITUDE_MAXIMUM, and X_Y_AND_Z_GRADIENTS.
CANNY The gradient is computed using the Canny algorithm. Supported gradient output modes : AMPLITUDE_MAXIMUM.
GAUSSIAN The gradient is computed using the Gaussian algorithm.
Supported gradient output modes : AMPLITUDE_MAXIMUM and X_Y_AND_Z_GRADIENTS.
PREWITT The gradient is computed using the Prewitt algorithm. Supported gradient output modes : AMPLITUDE_MAXIMUM and X_Y_AND_Z_GRADIENTS.
SOBEL The gradient is computed using the Sobel algorithm. Supported gradient output modes : AMPLITUDE_MAXIMUM and X_Y_AND_Z_GRADIENTS.
Enumeration CANNY_DERICHE
input
gradientMode
Select an output mode.
AMPLITUDE_MAXIMUM This option computes the gradient maximal amplitude. Only the outputAmplitudeImage output is set using this mode.
X_Y_AND_Z_GRADIENTS This option computes gradient in X, Y and Z directions. outputGradientXImage, outGradientYImage and outputGradientZImage outputs are set using this mode.
AMPLITUDE_EUCLIDEAN This option computes the Euclidean amplitude gradient. Only the outputAmplitudeImage output is set using this mode.
Enumeration AMPLITUDE_MAXIMUM
input
smoothingFactor
The smoothing factor defines the gradient sharpness. It is only used with Canny Deriche, and Gaussian operators. It has a totally different meaning depending on the selected gradient operator. Its value must be between 0 and 100.
  • Canny-Deriche: it is inversely proportional to Deriche alpha smoothing factor, in pixels. Low values provide sharp gradient. $SmoothingFactor=\frac{(5.3-\alpha)}{5}\times 100$
  • Gaussian: the Gaussian kernel standard deviation, in pixels. Low values provide sharp gradient.
  • Prewitt, Sobel, Canny: it is ignored.
  • Float64 ]0, 100] 60
    output
    outputImageX
    The X-gradient output image. Image nullptr
    output
    outputImageY
    The Y-gradient output image. Image nullptr
    output
    outputImageZ
    The Z-gradient output image. Image nullptr
    output
    outputAmplitudeImage
    The gradient amplitude output image. Image nullptr

    Object Examples

    auto foam = readVipImage( std::string( IMAGEDEVDATA_IMAGES_FOLDER ) + "foam.vip" );
    
    GradientOperator3d gradientOperator3dAlgo;
    gradientOperator3dAlgo.setInputImage( foam );
    gradientOperator3dAlgo.setGradientOperator( GradientOperator3d::GradientOperator::CANNY_DERICHE );
    gradientOperator3dAlgo.setGradientMode( GradientOperator3d::GradientMode::AMPLITUDE_MAXIMUM );
    gradientOperator3dAlgo.setSmoothingFactor( 60.0 );
    gradientOperator3dAlgo.execute();
    
    std::cout << "outputImageX:" << gradientOperator3dAlgo.outputImageX()->toString();
    std::cout << "outputImageY:" << gradientOperator3dAlgo.outputImageY()->toString();
    std::cout << "outputImageZ:" << gradientOperator3dAlgo.outputImageZ()->toString();
    std::cout << "outputAmplitudeImage:" << gradientOperator3dAlgo.outputAmplitudeImage()->toString();
    
    foam = imagedev.read_vip_image(imagedev_data.get_image_path("foam.vip"))
    
    gradient_operator_3d_algo = imagedev.GradientOperator3d()
    gradient_operator_3d_algo.input_image = foam
    gradient_operator_3d_algo.gradient_operator = imagedev.GradientOperator3d.CANNY_DERICHE
    gradient_operator_3d_algo.gradient_mode = imagedev.GradientOperator3d.AMPLITUDE_MAXIMUM
    gradient_operator_3d_algo.smoothing_factor = 60.0
    gradient_operator_3d_algo.execute()
    
    print( "output_image_x:", str( gradient_operator_3d_algo.output_image_x ) )
    print( "output_image_y:", str( gradient_operator_3d_algo.output_image_y ) )
    print( "output_image_z:", str( gradient_operator_3d_algo.output_image_z ) )
    print( "output_amplitude_image:", str( gradient_operator_3d_algo.output_amplitude_image ) )
    
    ImageView foam = Data.ReadVipImage( @"Data/images/foam.vip" );
    
    GradientOperator3d gradientOperator3dAlgo = new GradientOperator3d
    {
        inputImage = foam,
        gradientOperator = GradientOperator3d.GradientOperator.CANNY_DERICHE,
        gradientMode = GradientOperator3d.GradientMode.AMPLITUDE_MAXIMUM,
        smoothingFactor = 60.0
    };
    gradientOperator3dAlgo.Execute();
    
    Console.WriteLine( "outputImageX:" + gradientOperator3dAlgo.outputImageX.ToString() );
    Console.WriteLine( "outputImageY:" + gradientOperator3dAlgo.outputImageY.ToString() );
    Console.WriteLine( "outputImageZ:" + gradientOperator3dAlgo.outputImageZ.ToString() );
    Console.WriteLine( "outputAmplitudeImage:" + gradientOperator3dAlgo.outputAmplitudeImage.ToString() );
    

    Function Examples

    auto foam = readVipImage( std::string( IMAGEDEVDATA_IMAGES_FOLDER ) + "foam.vip" );
    
    auto result = gradientOperator3d( foam, GradientOperator3d::GradientOperator::CANNY_DERICHE, GradientOperator3d::GradientMode::AMPLITUDE_MAXIMUM, 60.0 );
    
    std::cout << "outputImageX:" << result.outputImageX->toString();
    std::cout << "outputImageY:" << result.outputImageY->toString();
    std::cout << "outputImageZ:" << result.outputImageZ->toString();
    std::cout << "outputAmplitudeImage:" << result.outputAmplitudeImage->toString();
    
    foam = imagedev.read_vip_image(imagedev_data.get_image_path("foam.vip"))
    
    result_output_image_x, result_output_image_y, result_output_image_z, result_output_amplitude_image = imagedev.gradient_operator_3d( foam, imagedev.GradientOperator3d.CANNY_DERICHE, imagedev.GradientOperator3d.AMPLITUDE_MAXIMUM, 60.0 )
    
    print( "output_image_x:", str( result_output_image_x ) )
    print( "output_image_y:", str( result_output_image_y ) )
    print( "output_image_z:", str( result_output_image_z ) )
    print( "output_amplitude_image:", str( result_output_amplitude_image ) )
    
    ImageView foam = Data.ReadVipImage( @"Data/images/foam.vip" );
    
    Processing.GradientOperator3dOutput result = Processing.GradientOperator3d( foam, GradientOperator3d.GradientOperator.CANNY_DERICHE, GradientOperator3d.GradientMode.AMPLITUDE_MAXIMUM, 60.0 );
    
    Console.WriteLine( "outputImageX:" + result.outputImageX.ToString() );
    Console.WriteLine( "outputImageY:" + result.outputImageY.ToString() );
    Console.WriteLine( "outputImageZ:" + result.outputImageZ.ToString() );
    Console.WriteLine( "outputAmplitudeImage:" + result.outputAmplitudeImage.ToString() );