Me¶

class Me(*args, **kwargs)¶

Bases: pybind11_object

This class defines predetermined masks for sites and holds moving edges tracking parameters.

JSON serialization

Since ViSP 3.6.0, if ViSP is build with soft_tool_json 3rd-party we introduce JSON serialization capabilities for vpMe . The following sample code shows how to save moving-edges settings in a file named ` me.json ` and reload the values from this JSON file.

#include <visp3/me/vpMe.h>

int main()
{
#if defined(VISP_HAVE_NLOHMANN_JSON)
  std::string filename = "me.json";
  {
    vpMe me;
    me.setLikelihoodThresholdType(vpMe::NORMALIZED_THRESHOLD);
    me.setThreshold(20);    // Value in range [0 ; 255]
    me.setThresholdMarginRatio(-1.); // Deactivate automatic thresholding
    me.setMinThreshold(-1.); // Deactivate automatic thresholding
    me.setMaskNumber(180);
    me.setMaskSign(0);
    me.setMu1(0.5);
    me.setMu2(0.5);
    me.setNbTotalSample(0);
    me.setPointsToTrack(200);
    me.setRange(5);
    me.setStrip(2);

    std::ofstream file(filename);
    const nlohmann::json j = me;
    file << j;
    file.close();
  }
  {
    std::ifstream file(filename);
    const nlohmann::json j = nlohmann::json::parse(file);
    vpMe me;
    me = j;
    file.close();
    std::cout << "Read moving-edges settings from " << filename << ":" << std::endl;
    me.print();
  }
#endif
}

If you build and execute the sample code, it will produce the following output:

Read moving-edges settings from me.json:

Moving edges settings

 Size of the convolution masks....5x5 pixels
 Number of masks..................180
 Query range +/- J................5 pixels
 Likelihood threshold type........normalized
 Likelihood threshold.............20
 Likelihood margin ratio..........unused
 Minimum likelihood threshold.....unused
 Contrast tolerance +/-...........50% and 50%
 Sample step......................10 pixels
 Strip............................2 pixels
 Min sample step..................4 pixels

The content of the ` me.json ` file is the following:

$ cat me.json
{"maskSign":0,"maskSize":5,"minSampleStep":4.0,"mu":[0.5,0.5],"nMask":180,"ntotalSample":0,"pointsToTrack":200,
 "range":5,"sampleStep":10.0,"strip":2,"threshold":20.0,"thresholdMarginRatio":-1.0,"minThreshold":-1.0,"thresholdType":"normalized"}

Overloaded function.

__init__(self: visp._visp.me.Me) -> None

Default constructor.

__init__(self: visp._visp.me.Me, me: visp._visp.me.Me) -> None

Copy constructor.

Methods

`__init__`	Overloaded function.
`checkSamplestep`	Check sample step wrt min value.
`getAngleStep`	Return the angle step.
`getLikelihoodThresholdType`	Return the selected choice for the likelihood threshold.
`getMaskNumber`	Return the number of mask applied to determine the object contour.
`getMaskSign`	Return the mask sign.
`getMaskSize`	Return the actual mask size (in pixel) used to compute the image gradient and determine the object contour.
`getMinSampleStep`	Get the minimum allowed sample step.
`getMinThreshold`	Return the minimum contrast threshold of the vpMeSite that can be used when using the automatic threshold computation.
`getMu1`	Get the minimum image contrast allowed to detect a contour.
`getMu2`	Get the maximum image contrast allowed to detect a contour.
`getNbTotalSample`	Get how many discretized points are used to track the feature.
`getPointsToTrack`	Return the number of points to track.
`getRange`	Return the seek range on both sides of the reference pixel.
`getSampleStep`	Get the minimum distance in pixel between two discretized points.
`getStrip`	Get the number of pixels that are ignored around the image borders.
`getThreshold`	Return the likelihood threshold used to determine if the moving edge is valid or not.
`getThresholdMarginRatio`	Return the ratio of the initial contrast to use to initialize the contrast threshold of the vpMeSite .
`getUseAutomaticThreshold`	Indicates if the contrast threshold of the vpMeSite is automatically computed.
`initMask`	Initialise the array of matrices with the defined size and the number of matrices to create.
`print`	Print using std::cout moving edges settings.
`setAngleStep`	Set the angle step.
`setLikelihoodThresholdType`
`setMaskNumber`	Set the number of mask applied to determine the object contour.
`setMaskSign`	Set the mask sign.
`setMaskSize`	Set the mask size (in pixel) used to compute the image gradient and determine the object contour.
`setMinSampleStep`	Set the minimum allowed sample step.
`setMinThreshold`	Set the minimum value of the contrast threshold of the vpMeSite .
`setMu1`	Set the minimum image contrast allowed to detect a contour.
`setMu2`	Set the maximum image contrast allowed to detect a contour.
`setNbTotalSample`	Set how many discretized points are used to track the feature.
`setPointsToTrack`	Set the number of points to track.
`setRange`	Set the seek range on both sides of the reference pixel.
`setSampleStep`	Set the minimum distance in pixel between two discretized points.
`setStrip`	Set the number of pixels that are ignored around the image borders.
`setThreshold`	Set the likelihood threshold used to determined if the moving edge is valid or not.
`setThresholdMarginRatio`	Set the the ratio of the initial contrast to use to initialize the contrast threshold of the vpMeSite .

Inherited Methods

Operators

`__doc__`
`__init__`	Overloaded function.
`__module__`

Attributes

`NORMALIZED_THRESHOLD`
`OLD_THRESHOLD`
`__annotations__`

class LikelihoodThresholdType(self, value: int)¶

Bases: pybind11_object

Type of likelihood threshold to use.

Values:

OLD_THRESHOLD: Old likelihood ratio threshold (to be avoided).
NORMALIZED_THRESHOLD: Easy-to-use normalized likelihood threshold corresponding to the minimal luminance contrast to consider with values in [0 ; 255].

__and__(self, other: object) → object¶

__eq__(self, other: object) → bool¶

__ge__(self, other: object) → bool¶

__getstate__(self) → int¶

__gt__(self, other: object) → bool¶

__hash__(self) → int¶

__index__(self) → int¶

__init__(self, value: int)¶

__int__(self) → int¶

__invert__(self) → object¶

__le__(self, other: object) → bool¶

__lt__(self, other: object) → bool¶

__ne__(self, other: object) → bool¶

__or__(self, other: object) → object¶

__rand__(self, other: object) → object¶

__ror__(self, other: object) → object¶

__rxor__(self, other: object) → object¶

__setstate__(self, state: int) → None¶

__xor__(self, other: object) → object¶

property name : str¶

__init__(*args, **kwargs)¶

Overloaded function.

__init__(self: visp._visp.me.Me) -> None

Default constructor.

__init__(self: visp._visp.me.Me, me: visp._visp.me.Me) -> None

Copy constructor.

checkSamplestep(self, sample_step: float) → float¶

Check sample step wrt min value.

Parameters:

sample_step: float¶: When this value is lower than the min sample step value, it is modified to the min sample step value.

Returns:

A tuple containing:

sample_step: When this value is lower than the min sample step value, it is modified to the min sample step value.

getAngleStep(self) → int¶

Return the angle step.

Returns:: Value of angle step.

getLikelihoodThresholdType(self) → visp._visp.me.Me.LikelihoodThresholdType¶

Return the selected choice for the likelihood threshold.

Note

See setLikelihoodThresholdType() , setThreshold() , getThreshold()

Returns:: The likelihood threshold type to consider.

getMaskNumber(self) → int¶

Return the number of mask applied to determine the object contour. The number of mask determines the precision of the normal of the edge for every sample. If precision is 2deg, then there are 360/2 = 180 masks.

Returns:: the current number of mask.

getMaskSign(self) → int¶

Return the mask sign.

Returns:: Value of mask_sign.

getMaskSize(self) → int¶

Return the actual mask size (in pixel) used to compute the image gradient and determine the object contour. The mask size defines the size of the convolution mask used to detect an edge.

Returns:: the current mask size.

getMinSampleStep(self) → float¶

Get the minimum allowed sample step. Useful to specify a lower bound when the sample step is changed.

Returns:: Value of min sample step.

getMinThreshold(self) → float¶

Return the minimum contrast threshold of the ** vpMeSite ** that can be used when using the automatic threshold computation.

Note

See setThresholdMarginRatio() , getThresholdMarginRatio() , setMinThreshold() , getLikelihoodThresholdType() , setLikelihoodThresholdType()

Returns:: Value of the minimum contrast threshold.

getMu1(self) → float¶

Get the minimum image contrast allowed to detect a contour.

Returns:: Value of mu1.

getMu2(self) → float¶

Get the maximum image contrast allowed to detect a contour.

Returns:: Value of mu2.

getNbTotalSample(self) → int¶

Get how many discretized points are used to track the feature.

Returns:: Value of ntotal_sample.

getPointsToTrack(self) → int¶

Return the number of points to track.

Returns:: Value of points_to_track.

getRange(self) → int¶

Return the seek range on both sides of the reference pixel.

Returns:: Value of range.

getSampleStep(self) → float¶

Get the minimum distance in pixel between two discretized points.

Returns:: Value of sample_step.

getStrip(self) → int¶

Get the number of pixels that are ignored around the image borders.

Returns:: the value of strip.

getThreshold(self) → float¶

Return the likelihood threshold used to determine if the moving edge is valid or not.

Note

See setThreshold() , getLikelihoodThresholdType() , setLikelihoodThresholdType()

Returns:: Value of the likelihood threshold.

getThresholdMarginRatio(self) → float¶

Return the ratio of the initial contrast to use to initialize the contrast threshold of the ** vpMeSite ** .

Note

See setThresholdMarginRatio() , setMinThreshold() , getMinThreshold() , getLikelihoodThresholdType() , setLikelihoodThresholdType()

Returns:: Value of the likelihood threshold ratio, between 0 and 1.

getUseAutomaticThreshold(self) → bool¶

Indicates if the contrast threshold of the vpMeSite is automatically computed.

Returns:: true The contrast threshold of the vpMeSite is automatically computed.false The vpMe::m_threshold is used as a global threshold.

initMask(self) → None¶: Initialise the array of matrices with the defined size and the number of matrices to create.

print(self) → None¶: Print using std::cout moving edges settings.

setAngleStep(self, anglestep: int) → None¶

Set the angle step.

Parameters:

anglestep: int¶: New angle step value.

setLikelihoodThresholdType(self, likelihood_threshold_type: visp._visp.me.Me.LikelihoodThresholdType) → None¶

setMaskNumber(self, mask_number: int) → None¶

Set the number of mask applied to determine the object contour. The number of mask determines the precision of the normal of the edge for every sample. If precision is 2deg, then there are 360/2 = 180 masks.

Parameters:

mask_number: int¶: The number of mask.

setMaskSign(self, mask_sign: int) → None¶

Set the mask sign.

Parameters:

mask_sign: int¶: New mask sign.

setMaskSize(self, mask_size: int) → None¶

Set the mask size (in pixel) used to compute the image gradient and determine the object contour. The mask size defines the size of the convolution mask used to detect an edge.

Parameters:

mask_size: int¶: New mask size.

setMinSampleStep(self, min_samplestep: float) → None¶

Set the minimum allowed sample step. Useful to specify a lower bound when the sample step is changed.

Parameters:

min_samplestep: float¶: New minimum sample step.

setMinThreshold(self, minThreshold: float) → None¶

Set the minimum value of the contrast threshold of the ** vpMeSite ** .

Note

See getMinThreshold() , setThresholdMarginRatio() , getThresholdMarginRatio() , getLikelihoodThresholdType() , setLikelihoodThresholdType()

Parameters:

minThreshold: float¶: Minimum value of the contrast threshold.

setMu1(self, mu_1: float) → None¶

Set the minimum image contrast allowed to detect a contour.

Parameters:

mu_1: float¶: new mu1.

setMu2(self, mu_2: float) → None¶

Set the maximum image contrast allowed to detect a contour.

Parameters:

mu_2: float¶: New mu2.

setNbTotalSample(self, ntotal_sample: int) → None¶

Set how many discretized points are used to track the feature.

Parameters:

ntotal_sample: int¶: New total number of sample.

setPointsToTrack(self, points_to_track: int) → None¶

Set the number of points to track.

Warning

This method is useful only for the vpMeNurbsTracker.

Parameters:

points_to_track: int¶: New number of points to track.

setRange(self, range: int) → None¶

Set the seek range on both sides of the reference pixel.

Parameters:

range: int¶: New range.

setSampleStep(self, sample_step: float) → None¶

Set the minimum distance in pixel between two discretized points.

Parameters:

sample_step: float¶: New sample_step.

setStrip(self, strip: int) → None¶

Set the number of pixels that are ignored around the image borders.

Parameters:

strip: int¶: New strip.

setThreshold(self, threshold: float) → None¶

Set the likelihood threshold used to determined if the moving edge is valid or not.

vpMe me;
me.setLikelihoodThresholdType(NORMALIZED_THRESHOLD);
me.setThreshold(20); // Value in range [0 ; 255]
me.setThresholdMarginRatio(-1.); // Deactivate automatic thresholding
me.setMinThreshold(-1.); // Deactivate automatic thresholding

When the likelihood threshold type is set by default to OLD_THRESHOLD like in the next example, values of the likelihood threshold depends on the minimal luminance contrast to consider and the mask size that can be set using setMaskSize() and retrieved using getMaskSize() .

vpMe me;                // By default the constructor set the threshold type to OLD_THRESHOLD
me.setThreshold(10000); // Value that depends on the minimal luminance contrast to consider and the mask size.
me.setThresholdMarginRatio(-1.); // Deactivate automatic thresholding
me.setMinThreshold(-1.); // Deactivate automatic thresholding

The previous sample code is similar to the next one:

vpMe me;
me.setLikelihoodThresholdType(OLD_THRESHOLD);
me.setThreshold(10000); // Value that depends on the minimal luminance contrast to consider and the mask size.
me.setThresholdMarginRatio(-1.); // Deactivate automatic thresholding
me.setMinThreshold(-1.); // Deactivate automatic thresholding

Note

See getThreshold() , getLikelihoodThresholdType()

Parameters:

threshold: float¶: Threshold to consider. Two different cases need to be considered depending on the likelihood threshold type that can be set using setLikelihoodThresholdType() or get using getLikelihoodThresholdType() . The default likelihood threshold type is set to OLD_THRESHOLD to keep compatibility with ViSP previous releases, but it is recommended to use rather the NORMALIZED_THRESHOLD type like in the following sample code. When doing so, the threshold is more easy to set since it corresponds to the minimal luminance contrast to consider with values in range [0 ; 255].

setThresholdMarginRatio(self, thresholdMarginRatio: float) → None¶

Set the the ratio of the initial contrast to use to initialize the contrast threshold of the ** vpMeSite ** .

Note

See getThresholdMarginRatio() , setMinThreshold() , getMinThreshold() , getLikelihoodThresholdType() , setLikelihoodThresholdType()

Parameters:

thresholdMarginRatio: float¶: Value of the likelihood threshold ratio, between 0 and 1.