Gauge3d Parameters and Tools#

Gauge3d Parameters#

enum visionflow::gauge3d::HeightFilterMode#

Method for filtering point to plane height values.

Values:

enumerator kDisableHeightFilter = 0#: Filter is disable.

enumerator kIncludeValuesInRange#: Filter points outside a given range.

enumerator kExcludeValuesInRange#: Filter points within a given range.

enum visionflow::gauge3d::PointSampleMode#

Method for sampling points from a 3D image centered around a given point.

Values:

enumerator kSinglePoint = 0#: Image pixel at specified coordinates.

enumerator kNeighborMean#: Average pixel value in a rectangle region around a given point.

enumerator kNeighborMedian#: Median pixel value in a rectangle region around a given point.

enum visionflow::gauge3d::PitDepthGaugeMode#

Specify the mode of calculate pit depth value.

Values:

enumerator kMaxDepth = 0#: gauge maximum pit depth value.

enumerator kMinDepth#: gauge minimum pit depth value.

enumerator kMeanDepth#: gauge average pit depth value.

Gauge Tools#

struct PlaneEstimated#

The return result of the fit_plane function and estimate_plane includes Plane, translation components in the x, y, and z directions and rotation components (in the order X-Y-Z) of plane pose, and the RMS (Root Mean Square).

Public Members

geo3d::Plane3f plane#: The estimated plane.

std::vector<double> translation_pose#: translation component in the xyz-direction.

std::vector<geometry::Radian> rotate_pose#: rotation component in the xyz-axis.

double rms = {}#: The root mean square of the vertical distance from the 3D points for plane fitting.

struct Height#

The return result of the height function includes maximum height, minimum height, mean and median of height from plane.

Public Members

double max_height = {}#: Maximum height from the plane.

double min_height = {}#: Minimum height from the plane.

double mean_height = {}#: Average height from the plane.

double median_height = {}#: Median height from the plane.

geometry::MultiPoint2i max_height_points#: image coordinates for maximum height.

geometry::MultiPoint2i min_height_points#: image coordinates for minimum height.

geometry::MultiPoint2i median_height_points#: image coordinates for median height.

struct Flatness#

The return result of the gauge flatness function includes maximum height, minimum height, image coordinates corresponding to max_height and min_height, flatness (maximum height subtract minimum height) from plane, the estimated or fitted planar equation, the translation components in the x, y, and z directions, and the rotation components (in the order X-Y-Z) of the planar pose.

Public Members

double max_height = {}#: Maximum height from the plane.

double min_height = {}#: Minimum height from the plane.

geometry::MultiPoint2i max_height_points#: image coordinates for maximum height.

geometry::MultiPoint2i min_height_points#: image coordinates for minimum height.

double flatness = {}#: Flatness of 3D points relative to the plane.

geo3d::Plane3f plane#: The estimated plane.

std::vector<double> translation_pose#: translation component in the xyz-direction.

std::vector<geometry::Radian> rotate_pose#: rotation component in the xyz-axis.

PlaneEstimated visionflow::gauge3d::fit_plane(const std::vector<geo3d::Point3f> &point_cloud, bool have_noise_point = false, float threshold = 0.1, size_t max_iterations = 1000)#

Fit a 3D plane from a 3D point set.

If the number of point is less than 3, an visionflow::excepts::InvalidArgument will be thrown.

The internal computational process is as follows:

If the number of input points is 3, or if have_noise_point is false, the internal process uses the least squares method to fit plane. This method is suitable for scenarios without outliers. After plane fitting, it returns. Otherwise, proceed to step 2.
Check if the input max_iteration is less than 1. If so, recalculate max_iteration using an adaptive method. Otherwise, no action is taken.
Iterate based on the parameter max_iteration: 3-1. Randomly select 4 non-collinear points to fit the plane. 3-2. Calculate the Euclidean distance between the input point set and the fitted plane. If the distance is greater than the input parameter threshold, the current point is considered an outlier; otherwise, it is considered an inlier. Record the number of inliers. 3-3. If the previously input max_iteration was invalid and an adaptive method was used to recalculate it, the number of max_iteration needs to be updated.

Record the plane with the highest number of inliers. Re-fit the plane based on the inliers from this iteration and return it.

Parameters:

point_cloud – Input point set.
have_noise_point – If false, the plane is fitted using the least squares method, which is suitable for scenarios without outliers; if true, the plane is fitted using the RANSAC method. It effectively removes noise (outliers), but is more time-consuming than least squares.
threshold – This parameter is effective when have_noise_point=true, and serves as the input parameter “threshold” in the calculation process described in step 3-2 above, used to determine inliers and outliers. Typically configured as 2 to 3 times the 3D camera’s imaging error.
max_iterations – This parameter takes effect when have_noise_point=true, corresponding to the “max_iteration” in steps 2 and 3 of the computational process described above. When estimating the number of iterations, assuming the number of input points is \( n \), and considering the worst-case scenario where the outlier ratio is close to 50% (inlier ratio \( w = 0.5 \)) with a confidence level set to \( p = 0.99 \),and since the RANSAC iteration calculation formula is \( k = \left\lceil \frac{\log(1-p)}{\log(1-w^n)} \right\rceil \), the final formula for determining the number of iterations is: \( k = \left\lceil \frac{\log(0.01)}{\log(1-0.5^n)} \right\rceil \).

Returns:

PlaneEstimated.

PlaneEstimated visionflow::gauge3d::estimate_plane(const img3d::Image3d &img, bool have_noise_point = false, float threshold = 0.1, size_t max_iterations = 1000, const geometry::MultiPolygon2f &roi = geometry::MultiPolygon2f())#

Estimate a 3D plane from points within 2D Region of Interest (ROI) on a 3D image. Please note that the detailed descriptions of parameters “have_noise_point”, “threshold”, and “max_iterations” can be found by referring to the gauge3d::fit_plane.

Parameters:

img – Input 3D image.
have_noise_point – When noise is present in the ROI area, it is recommended to set this parameter to true (estimate plane by least squares method); otherwise, set it to false (estimate plane by the RANSAC method).
threshold – It is effective when have_noise_point = true. Determines whether a 3D point is within the estimated plane when the distance is less than this threshold.
max_iterations – It is effective when have_noise_point = true. The maximum number of times to estimate a plane by randomly sampling subsets of points from the 3D image in 2D ROI.
roi – 2D Region of Interest. When the roi is empty, it will extract 3D points from the whole image to fit a plane. Any portion of the ROI that extends beyond the image boundaries will be disregarded during processing.

Returns:

PlaneEstimated.

Height visionflow::gauge3d::height(const img3d::Image3d &img, const geo3d::Plane3f &plane, float low_filter_ratio = 0.01, float high_filter_ratio = 0.01, float height_range_low = 10, float height_range_high = 100, HeightFilterMode height_filter_mode = HeightFilterMode::kDisableHeightFilter, const geometry::MultiPolygon2f &roi = geometry::MultiPolygon2f())#

Calculate the height form the 3D points in a given 2D ROI to the base plane.

The processing steps are as follows:

Convert the 3D image pixels within the 2D ROI region into 3D points. if the ROI is empty, convert the whole image.
Calculate the height from these 3D points to the plane.
If height_filter_mode = HeightFilterMode::kFilterInRange, filter out the height values within the range [height_range_low, height_range_high]. If height_filter_mode = HeightFilterMode::kFilterOutRange, filter out the height values within the ranges [0, height_range_low]and [height_range_high, +∞]. Otherwise, no filtering is applied;
Sort the filtered height values in ascending order and remove a proportion of values from the beginning and end of the sorted list based on the ratios low_filter_ratio and high_filter_ratio, respectively.
Calculate the maximum, minimum, mean, and median values of the remaining height values.

Parameters:

img – Input 3D image.
plane – Input base plane.
low_filter_ratio – Lower threshold for height value filtering ratio.
high_filter_ratio – Higher threshold for height value filtering ratio.
height_range_low – Lower bound of height range.
height_range_high – Higher bound of height range.
height_filter_mode – height filtering mode.
roi – 2D Region of Interest. If the roi is empty, extract the 3D points from the whole image and calculate the height from the points to the plane. Any portion of the ROI that extends beyond the image boundaries will be disregarded during processing.

Returns:

Height.

Flatness visionflow::gauge3d::flatness_by_fitted_plane(const img3d::Image3d &img, const geometry::MultiPoint2f &sample_points, const geometry::Size2f &sample_size = geometry::Size2f(5, 5), PointSampleMode sample_mode = PointSampleMode::kNeighborMedian, bool have_noise_point = false, float threshold = 0.1, size_t max_iterations = 1000)#

Gauging flatness by sampling 3D points around each point in a given point set to fit a plane, and then calculating the height values from these points to the plane. This method is fast but has lower accuracy, making it suitable for scenarios where speed is critical but high precision is not required.

The processing steps are as follows:

Traverse the given 2D sample_points, and for each point, take its coordinates in the image coordinate system as the center. Sample 3D point set according to the given sample_size.
Calculate the sampled point for each neighborhood based on the sample_mode.
Fit a plane based on these sampled points.
Calculate the height value of each sampled point to the fitted plane.
Find the maximum height value, the minimum height value, and the flatness.

Parameters:

img – Input 3D image.
sample_points – Set of sampling location coordinates.
sample_size – Sample points size.
sample_mode – When sample_mode=kSinglePoint, the pixel at the current location is sampled; sample_mode=kNeighborMean outputs the mean of the neighborhood pixels; sample_mode=kNeighborMedian outputs the median of the neighborhood pixels
have_noise_point – When noise is present in the ROI area, it is recommended to set this parameter to true (estimate plane by least squares method); otherwise, set it to false (estimate plane by the RANSAC method).
threshold – It is effective when fit_mode = FitMode::kRansac. Determines whether a 3D point is within the estimated plane when the distance is less than this threshold.
max_iterations – It is effective when fit_mode = FitMode::kRansac. The maximum number of times to fit a plane by randomly sampling subsets of points from the 3D image in 2D ROI. It is recommended that this value be greater than one-third of the ROI area.

Returns:

FlatnessCalculated.

Flatness visionflow::gauge3d::flatness_by_fitted_plane(const img3d::Image3d &img, float low_filter_ratio = 0.01, float high_filter_ratio = 0.01, bool have_noise_point = false, float threshold = 0.1, size_t max_iterations = 1000, const geometry::MultiPolygon2f &roi = geometry::MultiPolygon2f())#

To gauge flatness, 3D points are sampled within a given Region of Interest (ROI), a plane is fitted based on these points, and the height values from the points to this plane are calculated. This method is fast but has lower accuracy, making it suitable for scenarios where speed is critical but high precision is not required.

The processing steps are as follows:

Convert the 2D ROI region’s corresponding pixels in the 3D image into 3D points. if the ROI is empty, convert the whole image.
Fit a plane based on these 3D points.
Calculate the height values (vertical distances) of each 3D point to the fitted plane.
Sort these height values in ascending order, and remove the values at the head and tail according to the low_filter_ratio and high_filter_ratio.
Calculate the maximum height value, the minimum height value, the coordinates in the 3D image corresponding to these max and min height values, and compute the flatness.

Parameters:

img – Input 3D image.
low_filter_ratio – Lower threshold for height value filtering ratio.
high_filter_ratio – Higher threshold for height value filtering ratio.
have_noise_point – When noise is present in the ROI area, it is recommended to set this parameter to true (estimate plane by least squares method); otherwise, set it to false (estimate plane by the RANSAC method).
threshold – It is effective when have_noise_point = true. Determines whether a 3D point is within the estimated plane when the distance is less than this threshold.
max_iterations – It is effective when have_noise_point = true. The maximum number of times to estimate a plane by randomly sampling subsets of points from the 3D image in 2D ROI.
roi – The region of the sampled points. If the roi is empty, extract the 3D points from the whole image and calculate the flatness. Any portion of the ROI that extends beyond the image boundaries will be disregarded during processing.

double visionflow::gauge3d::pit_depth(const img3d::Image3d &img, const geometry::MultiPolygon2f &pit_region, float annulus_shift = 5, float annulus_width = 10, PitDepthGaugeMode pit_gauge_mode = PitDepthGaugeMode::kMeanDepth, float low_filter_ratio = 0.01, float high_filter_ratio = 0.01, bool have_noise_point = false, float threshold = 0.1, size_t max_iterations = 1000)#

Calculate the height form the 3D points in a given 2D ROI to the base plane.

the processing steps are as follows:

Dilate the pit_region outward by the width specified by the parameter annulus_shift.
Dilate the region outward again by the width specified by annulus_width.
Subtract the first dilated region from the second dilated region to obtain the region used for plane fitting.
Fit a plane based on the region calculated in the third step and the fitting type specified by the parameter fit_mode.
Calculate the depth values (distances) of the 3D points within the pit_region to the fitted plane.
Sort the depth values in ascending order.
Remove a proportion of values from the tail and head of the sorted list according to the ratios low_filter_ratio and high_filter_ratio, respectively.
Output the measured depth value based on the pit_gauge_mode.

Parameters:

img – Input 3D image.
pit_region – 2D Region of Interest.
annulus_shift – Outward dilation width along the pit_region.
annulus_width – The width of the second outward expansion after expanding outward based on annulus_shift.
pit_gauge_mode – the mode of calculate pit depth value.
low_filter_ratio – Lower threshold for height value filtering ratio.
high_filter_ratio – Higher threshold for height value filtering ratio.
have_noise_point – When noise is present in the ROI area, it is recommended to set this parameter to false (estimate plane by least squares method); otherwise, set it to true (estimate plane by the RANSAC method).
threshold – It is effective when have_noise_point = true. Determines whether a 3D point is within the estimated plane when the distance is less than this threshold.
max_iterations – It is effective when have_noise_point = true. The maximum number of times to estimate a plane by randomly sampling subsets of points from the 3D image in 2D ROI.

Returns:

HeightCalculated.