#include <vpCannyEdgeDetection.h>

Public Member Functions
Detection methods
vpImage< unsigned char >	detect (const vpImage< vpRGBa > &I_color)
template<typename ArithmeticType, bool useFullScale>
vpImage< unsigned char >	detect (const vpImage< vpHSV< ArithmeticType, useFullScale > > &Ihsv)
vpImage< unsigned char >	detect (const vpImage< unsigned char > &I)
Setters
void	setFilteringAndGradientType (const vpImageFilter::vpCannyFilteringAndGradientType &type)
void	setGradients (const vpImage< float > &dIx, const vpImage< float > &dIy)
void	setCannyThresholds (const float &lowerThresh, const float &upperThresh)
void	setCannyThresholdsRatio (const float &lowerThreshRatio, const float &upperThreshRatio)
void	setGaussianFilterParameters (const int &kernelSize, const float &stdev)
void	setGradientFilterAperture (const unsigned int &apertureSize)
void	setMask (const vpImage< bool > *p_mask)
void	setMinimumStackSize (const rlim_t &requiredStackSize)
void	setNbThread (const int &maxNbThread)
void	setStoreEdgePoints (const bool &storeEdgePoints)

Getters
const std::vector< vpImagePoint > &	getEdgePointsList () const
rlim_t	getMinimumStackSize () const
const vpImage< float > &	getGIx () const
const vpImage< float > &	getGIy () const
const vpImage< unsigned char > &	getEdgeMap () const

Constructors and initialization
	vpCannyEdgeDetection ()
	vpCannyEdgeDetection (const int &gaussianKernelSize, const float &gaussianStdev, const unsigned int &sobelAperture, const float &lowerThreshold=-1.f, const float &upperThreshold=-1.f, const float &lowerThresholdRatio=0.6f, const float &upperThresholdRatio=0.8f, const vpImageFilter::vpCannyFilteringAndGradientType &filteringType=vpImageFilter::CANNY_GBLUR_SOBEL_FILTERING, const bool &storeEdgePoints=false, const int &nbThread=-1)
void	reinit ()
	vpCannyEdgeDetection (const std::string &jsonPath)
void	initFromJSON (const std::string &jsonPath)
void	from_json (const nlohmann::json &j, vpCannyEdgeDetection &detector)
void	to_json (nlohmann::json &j, const vpCannyEdgeDetection &detector)

Detailed Description

Class that implements the Canny's edge detector. It is possible to use a boolean mask to ignore some pixels of the input gray-scale image.

Warning: If the stack size is not sufficient, a SEGFAULT can occur on some images which are really over-exposed.

Note: The maximum stack on MacOS seems to be 65532000 bytes, see https://stackoverflow.com/a/13261334

Examples: tutorial-canny-hsv.cpp, tutorial-canny.cpp, and tutorial-compare-auto-gamma.cpp.

Definition at line 66 of file vpCannyEdgeDetection.h.

Constructor & Destructor Documentation

◆ vpCannyEdgeDetection() [1/3]

BEGIN_VISP_NAMESPACE vpCannyEdgeDetection::vpCannyEdgeDetection ( )

Default constructor of the vpCannyEdgeDetection class. The thresholds used during the hysteresis thresholding step are set to be automatically computed.

Definition at line 68 of file vpCannyEdgeDetection.cpp.

References reinit().

Referenced by from_json, and to_json.

◆ vpCannyEdgeDetection() [2/3]

vpCannyEdgeDetection::vpCannyEdgeDetection	(	const int &	gaussianKernelSize,
		const float &	gaussianStdev,
		const unsigned int &	sobelAperture,
		const float &	lowerThreshold = -1.f,
		const float &	upperThreshold = -1.f,
		const float &	lowerThresholdRatio = 0.6f,
		const float &	upperThresholdRatio = 0.8f,
		const vpImageFilter::vpCannyFilteringAndGradientType &	filteringType = vpImageFilter::CANNY_GBLUR_SOBEL_FILTERING,
		const bool &	storeEdgePoints = false,
		const int &	nbThread = -1 )

Construct a new vpCannyEdgeDetection object that uses Gaussian blur + Sobel operators to compute the edge map.

Parameters

[in]	gaussianKernelSize	: The size of the Gaussian filter kernel. Must be odd.
[in]	gaussianStdev	: The standard deviation of the Gaussian filter.
[in]	sobelAperture	: The size of the Sobel filters kernel. Must be odd.
[in]	lowerThreshold	: The lower threshold of the hysteresis thresholding step. If negative, will be computed from the upper threshold.
[in]	upperThreshold	: The upper threshold of the hysteresis thresholding step. If negative, will be computed from the histogram of the absolute gradient.
[in]	lowerThresholdRatio	: If the thresholds must be computed,the lower threshold will be equal to the upper threshold times lowerThresholdRatio .
[in]	upperThresholdRatio	: If the thresholds must be computed,the upper threshold will be equal to the value such as the number of pixels of the image times upperThresholdRatio have an absolute gradient lower than the upper threshold.
[in]	filteringType	: The filtering and gradient operators to apply to the image before the edge detection operation.
[in]	storeEdgePoints	: If true, the list of edge-points will be available using
[in]	nbThread	: Number of thread to use. -1 to let the program choose. vpCannyEdgeDetection::getEdgePointsList().

Definition at line 87 of file vpCannyEdgeDetection.cpp.

References reinit().

◆ vpCannyEdgeDetection() [3/3]

vpCannyEdgeDetection::vpCannyEdgeDetection ( const std::string & jsonPath )

Construct a new vpCannyEdgeDetection object.

Parameters

[in] jsonPath : The path towards the JSON file to use to initialize the vpCannyEdgeDetection object.

Definition at line 136 of file vpCannyEdgeDetection.cpp.

References initFromJSON().

Member Function Documentation

◆ detect() [1/3]

vpImage< unsigned char > vpCannyEdgeDetection::detect ( const vpImage< unsigned char > & I )

Detect the edges in a gray-scale image.

Warning: If the stack size is not sufficient, a SEGFAULT can occur on some images which are really over-exposed.

Parameters

[in] I : A gray-scale image, in ViSP format.

Returns: vpImage<unsigned char> 255 means an edge, 0 means not an edge.

Definition at line 246 of file vpCannyEdgeDetection.cpp.

References vpImageFilter::computeCannyThreshold().

Referenced by visp.python.rbt.xfeat.XFeatTrackingBackend.XFeatTrackingBackend::process_frame().

◆ detect() [2/3]

template<typename ArithmeticType, bool useFullScale>

vpImage< unsigned char > vpCannyEdgeDetection::detect ( const vpImage< vpHSV< ArithmeticType, useFullScale > > & Ihsv )

inline

Definition at line 182 of file vpCannyEdgeDetection.h.

References vpImageFilter::computeCannyThreshold(), vpImageFilter::gaussianBlur(), and vpImageFilter::gradientFilter().

Referenced by visp.python.rbt.xfeat.XFeatTrackingBackend.XFeatTrackingBackend::process_frame().

◆ detect() [3/3]

vpImage< unsigned char > vpCannyEdgeDetection::detect ( const vpImage< vpRGBa > & I_color )

Detect the edges in an image. Convert the color image into a gray-scale image.

Warning: If the stack size is not sufficient, a SEGFAULT can occur on some images which are really over-exposed.

Parameters

[in] I_color : An RGB image, in ViSP format.

Returns: vpImage<unsigned char> 255 means an edge, 0 means not an edge.

Examples: tutorial-canny.cpp, and tutorial-compare-auto-gamma.cpp.

Definition at line 238 of file vpCannyEdgeDetection.cpp.

References vpImageConvert::convert(), and detect().

Referenced by vpImageFilter::canny(), detect(), and visp.python.rbt.xfeat.XFeatTrackingBackend.XFeatTrackingBackend::process_frame().

◆ getEdgeMap()

const vpImage< unsigned char > & vpCannyEdgeDetection::getEdgeMap ( ) const

inline

Get the final edge-map.

Returns: const vpImage<float>& The edge-map

Definition at line 444 of file vpCannyEdgeDetection.h.

◆ getEdgePointsList()

const std::vector< vpImagePoint > & vpCannyEdgeDetection::getEdgePointsList ( ) const

inline

Get the list of edge-points that have been detected.

Returns: std::vector<vpImagePoint> The edge-points list.

Examples: tutorial-canny.cpp.

Definition at line 390 of file vpCannyEdgeDetection.h.

References vpException::fatalError.

◆ getGIx()

const vpImage< float > & vpCannyEdgeDetection::getGIx ( ) const

inline

Get the horizontal gradient.

Returns: const vpImage<float>& GIx

Definition at line 424 of file vpCannyEdgeDetection.h.

◆ getGIy()

const vpImage< float > & vpCannyEdgeDetection::getGIy ( ) const

inline

Get the vertical gradient.

Returns: const vpImage<float>& GIy

Definition at line 434 of file vpCannyEdgeDetection.h.

◆ getMinimumStackSize()

rlim_t vpCannyEdgeDetection::getMinimumStackSize ( ) const

inline

Get the minimum stack size used by the algorithm.

Note: On Windows, the minimum stack size is defined at compilation time and cannot be changed during runtime.

Returns: rlim_t The minimum stack size.

Definition at line 407 of file vpCannyEdgeDetection.h.

◆ initFromJSON()

void vpCannyEdgeDetection::initFromJSON ( const std::string & jsonPath )

Initialize all the algorithm parameters using the JSON file whose path is jsonPath. Throw a vpException error if the file does not exist.

Parameters

[in] jsonPath : The path towards the JSON configuration file.

Definition at line 145 of file vpCannyEdgeDetection.cpp.

References from_json, vpException::ioError, and reinit().

Referenced by vpCannyEdgeDetection().

◆ reinit()

void vpCannyEdgeDetection::reinit ( )

Reinitialize the detector:

compute the number of threads to use if applicable
initialize the Gaussian filters
initialize the derivative filters
forget the mask (but do not alter the memory)
forget GIx and GIy (but do not alter the memory)
delete previous results

Definition at line 114 of file vpCannyEdgeDetection.cpp.

References setNbThread().

Referenced by from_json, initFromJSON(), vpCannyEdgeDetection(), and vpCannyEdgeDetection().

◆ setCannyThresholds()

void vpCannyEdgeDetection::setCannyThresholds	(	const float &	lowerThresh,
		const float &	upperThresh )

inline

Set the lower and upper Canny Thresholds used to qualify the edge point candidates. Edge point candidates whose gradient is between these two values is kept only if it linked somehow to a strong edge point.

Parameters

[in]	lowerThresh	: The lower threshold: each point whose gradient is below this threshold is discarded. When lower threshold value is negative, Canny recommendation is applied to have the lower threshold 3 times lower than the upper threshold.
[in]	upperThresh	: The upper threshold: each point whose gradient is greater than this threshold is said to be a strong edge point and is kept.

Definition at line 260 of file vpCannyEdgeDetection.h.

◆ setCannyThresholdsRatio()

void vpCannyEdgeDetection::setCannyThresholdsRatio	(	const float &	lowerThreshRatio,
		const float &	upperThreshRatio )

inline

Set the lower and upper Canny Thresholds ratio that are used to compute them automatically. To ask to compute automatically the thresholds, you must set the lower and upper thresholds with negative values using the appropriate setter.

See also: vpCannyEdgeDetection::setCannyThresholds(const float&, const float&)

Parameters

[in]	lowerThreshRatio	: The lower threshold ratio: if the thresholds are computed automatically, the lower threshold will be equal to the upper threshold multiplied by lowerThreshRatio.
[in]	upperThreshRatio	: The upper threshold ratio: if the thresholds are computed automatically, the upper threshold will be set such as upperThreshRatio times the number of pixels of the image have their absolute gradient lower then the upper threshold.

Definition at line 278 of file vpCannyEdgeDetection.h.

◆ setFilteringAndGradientType()

void vpCannyEdgeDetection::setFilteringAndGradientType ( const vpImageFilter::vpCannyFilteringAndGradientType & type )

inline

Set the Filtering And Gradient operators to apply to the image before the edge detection operation.

Parameters

[in] type The operators to apply.

Definition at line 230 of file vpCannyEdgeDetection.h.

◆ setGaussianFilterParameters()

void vpCannyEdgeDetection::setGaussianFilterParameters	(	const int &	kernelSize,
		const float &	stdev )

inline

Set the Gaussian Filters kernel size and standard deviation and initialize the aforementioned filters.

Parameters

[in]	kernelSize	: The size of the Gaussian filters kernel.
[in]	stdev	: The standard deviation of the Gaussian filters used to blur and compute the gradient of the image.

Definition at line 292 of file vpCannyEdgeDetection.h.

◆ setGradientFilterAperture()

void vpCannyEdgeDetection::setGradientFilterAperture ( const unsigned int & apertureSize )

inline

Set the parameters of the gradient filter (Sobel or Scharr) kernel size filters.

Parameters

[in] apertureSize The size of the gradient filters kernel. Must be an odd value.

Definition at line 304 of file vpCannyEdgeDetection.h.

◆ setGradients()

void vpCannyEdgeDetection::setGradients	(	const vpImage< float > &	dIx,
		const vpImage< float > &	dIy )

inline

Set the Gradients of the image that will be processed.

Parameters

[in]	dIx	: Gradient along the horizontal axis of the image.
[in]	dIy	: Gradient along the vertical axis of the image.

Examples: tutorial-canny.cpp, and tutorial-compare-auto-gamma.cpp.

Definition at line 242 of file vpCannyEdgeDetection.h.

Referenced by vpImageFilter::canny().

◆ setMask()

void vpCannyEdgeDetection::setMask ( const vpImage< bool > * p_mask )

inline

Set a mask to ignore pixels for which the mask is false.

Warning: The mask must be reset manually by the user (either for another mask or set to nullptr ) before computing the edge-map of another image.

Parameters

p_mask If different of nullptr , a mask of booleans where true indicates that a pixel must be considered and false that the pixel should be ignored.

Definition at line 320 of file vpCannyEdgeDetection.h.

Referenced by vpImageFilter::canny().

◆ setMinimumStackSize()

void vpCannyEdgeDetection::setMinimumStackSize ( const rlim_t & requiredStackSize )

inline

Set the minimum stack size, expressed in bytes, due to the recursive algorithm. If not called, the stack size is left at its default value when running the Canny edge detection algorithm.

Note: The stack size is changed back to its original value after before leaving the detect() function.; On Windows, the minimum stack size is defined at compilation time and cannot be changed during runtime.; The maximum stack on MacOS seems to be 65532000 bytes, see https://stackoverflow.com/a/13261334

Warning: If the stack size is not sufficient, a SEGFAULT can occur on some images which are really over-exposed.

Parameters

[in] requiredStackSize The required stack size, in bytes.

Definition at line 341 of file vpCannyEdgeDetection.h.

◆ setNbThread()

void vpCannyEdgeDetection::setNbThread ( const int & maxNbThread )

inline

Examples: tutorial-canny.cpp.

Definition at line 357 of file vpCannyEdgeDetection.h.

Referenced by reinit().

◆ setStoreEdgePoints()

void vpCannyEdgeDetection::setStoreEdgePoints ( const bool & storeEdgePoints )

inline

If set to true, the list of the detected edge-points will be available calling the method vpCannyEdgeDetection::getEdgePointsList().

Parameters

[in] storeEdgePoints The new desired status.

Definition at line 377 of file vpCannyEdgeDetection.h.

◆ from_json

void from_json	(	const nlohmann::json &	j,
		vpCannyEdgeDetection &	detector )

friend

Read the detector configuration from JSON. All values are optional and if an argument is not present, the default value defined in the constructor is kept.

Parameters

[in]	j	: The JSON object, resulting from the parsing of a JSON file.
[out]	detector	: The detector that will be initialized from the JSON data.

Definition at line 586 of file vpCannyEdgeDetection.h.

References from_json, reinit(), vpCannyEdgeDetection(), vpImageFilter::vpCannyFiltAndGradTypeFromStr(), and vpImageFilter::vpCannyFiltAndGradTypeToStr().

Referenced by from_json, and initFromJSON().

◆ to_json

void to_json	(	nlohmann::json &	j,
		const vpCannyEdgeDetection &	detector )

friend

Parse a vpCannyEdgeDetection object into JSON format.

Parameters

[out]	j	: A JSON parser object.
[in]	detector	: The vpCannyEdgeDetection object that must be parsed into JSON format.

Definition at line 602 of file vpCannyEdgeDetection.h.

References to_json, vpCannyEdgeDetection(), and vpImageFilter::vpCannyFiltAndGradTypeToStr().

Referenced by to_json.

Public Member Functions

Getters

Constructors and initialization

Detailed Description

Constructor & Destructor Documentation

◆ vpCannyEdgeDetection() [1/3]

◆ vpCannyEdgeDetection() [2/3]

◆ vpCannyEdgeDetection() [3/3]

Member Function Documentation

◆ detect() [1/3]

◆ detect() [2/3]

◆ detect() [3/3]

◆ getEdgeMap()

◆ getEdgePointsList()

◆ getGIx()

◆ getGIy()

◆ getMinimumStackSize()

◆ initFromJSON()

◆ reinit()

◆ setCannyThresholds()

◆ setCannyThresholdsRatio()

◆ setFilteringAndGradientType()

◆ setGaussianFilterParameters()

◆ setGradientFilterAperture()

◆ setGradients()

◆ setMask()

◆ setMinimumStackSize()

◆ setNbThread()

◆ setStoreEdgePoints()

Friends And Related Symbol Documentation

◆ from_json

◆ to_json