5.9. PclTools

Summary:	Filters and methods for pointClouds and polygonMeshes
Type:	Algorithm
License:	licensed under LGPL
Platforms:	Windows, Linux
Author:	M. Gronle, ITO, University Stuttgart

5.9.1. Overview

This plugin contains methods for filtering, transforming, saving and loading point clouds and polygon meshes. Most methods are wrappers for functions provided by the open source project PointCloudLibrary (pcl). The function calls are usually implemented for the cloud types supported by the itom classes itom.pointCloud and itom.polygonMesh (XYZ,XYZI,XYZRGBA,XYZNormals…).

This library uses also methods from the current pcl version 1.7.1, however also compiles with older versions. In this case some methods are not compiled.

This plugin also covers the methods for loading and saving point clouds and polygon meshes to common formats like pcd, ply, stl, obj… Once the plugin is loaded itom in general is also able to load and save such structures using the methods provided by this plugin.

These filters are defined in the plugin:

5.9.2. Filters

Detailed overview about all defined filters:

itom.algorithms.loadPointCloud(pointCloud, filename[, type])

loads pointCloud from hard drive and returns it (format pcd(binary or ascii), ply(binary or ascii))

Parameters

pointCloud (itom.pointCloud) – loaded pointcloud
filename (str) – complete filename (type is read by suffix)
type (str, optional) – type (‘xyz’, ‘pcd’,’ply’,’auto’ [default, check suffix of filename])

itom.algorithms.loadPolygonMesh(polygonMesh, filename[, type])

loads polygonMesh from hard drive and returns it (format obj[default], ply, vtk, stl)

Parameters

polygonMesh (itom.polygonMesh) – loaded polygon mesh
filename (str) – complete filename (type is read by suffix
type (str, optional) – type (‘obj’,’vtk’,’stl’,’ply’, ‘auto’ [default, check suffix of filename])

itom.algorithms.meshTransformAffine(meshIn, meshOut, transform)

Applies an affine coordinate transform to all points of the input mesh.

The transformed points are saved in ‘meshOut’ (inplace possible). The transformation matrix has to be a 4x4 homogeneous transformation matrix given by a 4x4 real dataObject (uint8, int8, uint16, int16, uint32, int32 or float32 allowed). Every point P_in in the input mesh is transformed by P_out = transform * P_in. Independent on the type of the transformation matrix, the matrix multiplication is done with float32 precision.

Parameters

meshIn (itom.polygonMesh) – The affine transform is applied to the points in this polygonal mesh
meshOut (itom.polygonMesh) – Resulting, transformed polygon mesh (inplace possible)
transform (itom.dataObject) – 4x4 homogeneous transformation matrix (uint8, int8, uint16, int16, uint32, int32, float32, float64)

itom.algorithms.pclCropBox(pointCloudIn, pointCloudOut[, minValue, maxValue, translation, rotation, negative])

pclCropBox is a filter that allows the user to filter all the data inside of a given box.

Indicate the minimum and maximum values in x,y and z direction for the box and optionally tranlate and rotate the box to adjust its position and orientation. The rotation vector are the euler angles rx, ry and rz.

Parameters

pointCloudIn (itom.pointCloud) – Valid input point cloud
pointCloudOut (itom.pointCloud) – Output point cloud with removed NaN values
minValue (Sequence[float], optional) –
minimum values (x,y,z) (default: FLT_MIN)

3 values required, Value range: [-3.40282e+38, 3.40282e+38], Default: [-3.40282e+38, -3.40282e+38, -3.40282e+38]
maxValue (Sequence[float], optional) –
maximum values (x,y,z) (default: FLT_MAX)

3 values required, Value range: [-3.40282e+38, 3.40282e+38], Default: [3.40282e+38, 3.40282e+38, 3.40282e+38]
translation (Sequence[float], optional) –
translation of box (dx,dy,dz) (default: zero values)

3 values required, Value range: [-3.40282e+38, 3.40282e+38], Default: [0, 0, 0]
rotation (Sequence[float], optional) –
euler rotation angles (in rad) of box (rx,ry,rz) (default: zero values)

3 values required, Value range: [-3.40282e+38, 3.40282e+38], Default: [0, 0, 0]
negative (int, optional) –
1: values inside of range will be deleted, else 0 [default]

Value range: [0, 1], Default: 0

itom.algorithms.pclCylinderClipper3D(pointCloudIn, pointCloudOut, point, orientation, radius)

clips points from the point cloud that lie outside a given cylindrical tube.

Parameters

pointCloudIn (itom.pointCloud) – Valid input point cloud
pointCloudOut (itom.pointCloud) – Output point cloud
point (Sequence[float]) – point on axis of cylinder
orientation (Sequence[float]) – orientation vector of cylinder
radius (Sequence[float]) – array with [min,max] radius

itom.algorithms.pclDistanceToModel(pointCloudIn, pointCloudOut, modelType[, point, orientationVector, radius])

Calculates the distances of points of a point cloud to a given model.

Possible types are:

SACMODEL_SPHERE = 4, SACMODEL_CYLINDER = 5,

Not supported yet:

SACMODEL_PLANE = 0, SACMODEL_LINE = 1, SACMODEL_CIRCLE2D = 2, SACMODEL_CIRCLE3D = 3, SACMODEL_CONE = 6, SACMODEL_TORUS = 7, SACMODEL_PARALLEL_LINE = 8, SACMODEL_PERPENDICULAR_PLANE = 9, SACMODEL_PARALLEL_LINES = 10, SACMODEL_NORMAL_PLANE = 11, SACMODEL_NORMAL_SPHERE = 12, SACMODEL_REGISTRATION = 13, SACMODEL_REGISTRATION_2D = 14, SACMODEL_PARALLEL_PLANE = 15, SACMODEL_NORMAL_PARALLEL_PLANE = 16, SACMODEL_STICK = 17

Parameters

pointCloudIn (itom.pointCloud) – Input point cloud with normal values
pointCloudOut (itom.pointCloud) – Output point cloud with distances
modelType (int) –
Model type according to enum pcl::SacModel (sphere: 4, cylinder: 5)

Value range: [0, 10], Default: 0
point (Sequence[float], optional) – point on cylinder symmetrie axis
orientationVector (Sequence[float], optional) – symmetrie axis of cylinder
radius (float, optional) –
cylinder radius

Value range: [0, 3.40282e+38], Default: 0

itom.algorithms.pclDistanceToModelDObj(inObj, distanceObj, modelType, coefficients)

calculates the distance from points in a given data object to a model.

Parameters

inObj (itom.dataObject) – Input data object (real type)
distanceObj (itom.dataObject) – Output distance object (inplace allowed)
modelType (int) –
Model type according to enum pcl::SacModel (sphere: 4, cylinder: 5)

Value range: [0, 10], Default: 0
coefficients (Sequence[float]) – model coefficients (sphere: p_x, p_y, p_z, r; cylinder: p_x, p_y, p_z, v_x, v_y, v_z, r)

itom.algorithms.pclEstimateNormals(pointCloudIn, pointCloudOut[, kSearch, viewPoint])

estimates normal vectors to the given input point cloud and returns the normal-enhanced representation of the input point cloud

Parameters

pointCloudIn (itom.pointCloud) – Valid point cloud whose normals should be estimated
pointCloudOut (itom.pointCloud) – Output point cloud with estimated normals. The type corresponds to the normal-enhanced type of the input cloud.
kSearch (int, optional) –
the number of k nearest neighbors to use for the feature estimation [default: 50]

Value range: [3, 10000], Default: 50
viewPoint (Sequence[float], optional) – optional camera view point (if given it must have three entries [x,y,z], [default: not used])

itom.algorithms.pclFitCircle2D(pointCloudIn, radiusLimits[, normalDistanceWeight, maxIterations, distanceThreshold, optimizeParameters, probability])

fits a planar circle model to the given input point cloud using a RANSAC based approach

Parameters

pointCloudIn (itom.pointCloud) – Input point cloud with normal values
radiusLimits (Sequence[float]) – radius limits [min, max]
normalDistanceWeight (float, optional) –
Set the relative weight (between 0 and 1) to give to the angular distance (0 to pi/2) between point normals and the plane normal [default: 0.1]

Value range: [0, 1], Default: 0.1
maxIterations (int, optional) –
maximum number of RANSAC iterations [default: 10000]

Value range: [1, 1000000], Default: 10000
distanceThreshold (float, optional) –
distanceThreshold of pcl [default: 0.05]

Value range: [0, 1e+06], Default: 0.05
optimizeParameters (int, optional) –
if 1: nonlinear optimization over all parameters is run (Careful: radius may exceed the given boundaries and then the resulting, considered indices become empty.)

Value range: [0, 1], Default: 0
probability (float, optional) –
the probability of choosing at least one sample free from outliers. [default: 0.99]

Value range: [0, 1], Default: 0.99

Returns

point - resulting center point (xy) of circle

Return type

Sequence[float]

Returns

radius - resulting fitted radius of circle

Return type

float

Returns

inliers - number of points considered after filtering outliers (due to RANSAC principle)

Return type

int

itom.algorithms.pclFitCircle3D(pointCloudIn, radiusLimits[, normalDistanceWeight, maxIterations, distanceThreshold, optimizeParameters, probability])

fits a 3D-circle model to the given input point cloud using a RANSAC based approach

Parameters

pointCloudIn (itom.pointCloud) – Input point cloud with normal values
radiusLimits (Sequence[float]) – radius limits [min, max]
normalDistanceWeight (float, optional) –
Set the relative weight (between 0 and 1) to give to the angular distance (0 to pi/2) between point normals and the plane normal [default: 0.1]

Value range: [0, 1], Default: 0.1
maxIterations (int, optional) –
maximum number of RANSAC iterations [default: 10000]

Value range: [1, 1000000], Default: 10000
distanceThreshold (float, optional) –
distanceThreshold of pcl [default: 0.05]

Value range: [0, 1e+06], Default: 0.05
optimizeParameters (int, optional) –
if 1: nonlinear optimization over all parameters is run (Careful: radius may exceed the given boundaries and then the resulting, considered indices become empty.)

Value range: [0, 1], Default: 0
probability (float, optional) –
the probability of choosing at least one sample free from outliers. [default: 0.99]

Value range: [0, 1], Default: 0.99

Returns

point - resulting center point of the circle

Return type

Sequence[float]

Returns

orientationVector - resulting normal vector

Return type

Sequence[float]

Returns

radius - resulting fitted radius of the circle

Return type

float

Returns

inliers - number of points considered after filtering outliers (due to RANSAC principle)

Return type

int

itom.algorithms.pclFitCone(pointCloudIn, angularLimits[, normalDistanceWeight, maxIterations, distanceThreshold, optimizeParameters, probability])

fits a conical model to the given input point cloud using a RANSAC based approach (must have normals defined)

Parameters

pointCloudIn (itom.pointCloud) – Input point cloud with normal values
angularLimits (Sequence[float]) – opening angle limits in radiant [min, max]
normalDistanceWeight (float, optional) –
Set the relative weight (between 0 and 1) to give to the angular distance (0 to pi/2) between point normals and the plane normal [default: 0.1]

Value range: [0, 1], Default: 0.1
maxIterations (int, optional) –
maximum number of RANSAC iterations [default: 10000]

Value range: [1, 1000000], Default: 10000
distanceThreshold (float, optional) –
distanceThreshold of pcl [default: 0.05]

Value range: [0, 1e+06], Default: 0.05
optimizeParameters (int, optional) –
if 1: nonlinear optimization over all parameters is run (Careful: radius may exceed the given boundaries and then the resulting, considered indices become empty.)

Value range: [0, 1], Default: 0
probability (float, optional) –
the probability of choosing at least one sample free from outliers. [default: 0.99]

Value range: [0, 1], Default: 0.99

Returns

point - resulting point on the line

Return type

Sequence[float]

Returns

orientationVector - resulting oriantation vector

Return type

Sequence[float]

Returns

openingAgle - resulting opening angle in radiant

Return type

float

Returns

inliers - number of points considered after filtering outliers (due to RANSAC principle)

Return type

int

itom.algorithms.pclFitCylinder(pointCloudIn, radiusLimits[, normalDistanceWeight, maxIterations, distanceThreshold, optimizeParameters, probability])

fits a cylindrical model to the given input point cloud using a RANSAC based approach (must have normals defined).

Parameters

pointCloudIn (itom.pointCloud) – Input point cloud with normal values
radiusLimits (Sequence[float]) – radius limits [min, max]
normalDistanceWeight (float, optional) –
Set the relative weight (between 0 and 1) to give to the angular distance (0 to pi/2) between point normals and the plane normal [default: 0.1]

Value range: [0, 1], Default: 0.1
maxIterations (int, optional) –
maximum number of RANSAC iterations [default: 10000]

Value range: [1, 1000000], Default: 10000
distanceThreshold (float, optional) –
distanceThreshold of pcl [default: 0.05]

Value range: [0, 1e+06], Default: 0.05
optimizeParameters (int, optional) –
if 1: nonlinear optimization over al 7 parameters is run (Careful: radius may exceed the given boundaries and then the resulting, considered indices become empty.)

Value range: [0, 1], Default: 0
probability (float, optional) –
the probability of choosing at least one sample free from outliers. [default: 0.99]

Value range: [0, 1], Default: 0.99

Returns

point - point on axis of symmetry of cylinder

Return type

Sequence[float]

Returns

orientationVector - axis of symmetry of cylinder

Return type

Sequence[float]

Returns

radius - fitted radius of cylinder

Return type

float

Returns

inliers - number of points considered after filtering outliers (due to RANSAC principle)

Return type

int

itom.algorithms.pclFitLine(pointCloudIn[, normalDistanceWeight, maxIterations, distanceThreshold, optimizeParameters, probability])

fits a line model to the given input point cloud using a RANSAC based approach

Parameters

pointCloudIn (itom.pointCloud) – Input point cloud with normal values
normalDistanceWeight (float, optional) –
Set the relative weight (between 0 and 1) to give to the angular distance (0 to pi/2) between point normals and the plane normal [default: 0.1]

Value range: [0, 1], Default: 0.1
maxIterations (int, optional) –
maximum number of RANSAC iterations [default: 10000]

Value range: [1, 1000000], Default: 10000
distanceThreshold (float, optional) –
distanceThreshold of pcl [default: 0.05]

Value range: [0, 1e+06], Default: 0.05
optimizeParameters (int, optional) –
if 1: nonlinear optimization over all parameters is run (Careful: radius may exceed the given boundaries and then the resulting, considered indices become empty.)

Value range: [0, 1], Default: 0
probability (float, optional) –
the probability of choosing at least one sample free from outliers. [default: 0.99]

Value range: [0, 1], Default: 0.99

Returns

point - resulting point on the line

Return type

Sequence[float]

Returns

orientationVector - resulting oriantation vector

Return type

Sequence[float]

Returns

inliers - number of points considered after filtering outliers (due to RANSAC principle)

Return type

int

itom.algorithms.pclFitModel(pointCloudIn, modelType[, radiusLimits, axis, maxAngle, normalDistanceWeight, maxIterations, distanceThreshold, optimizeParameters, probability])

fits a geometric model to the given input point cloud using a RANSAC based approach.

The method used for this fit is from the sample consensus module of point cloud library. (See http://docs.pointclouds.org/1.7.0/group__sample__consensus.html).

The following models are available:

Plane (0). Hessian Normal Form (n_vec * pt + d = 0). Coefficients:

n_x
n_y
n_z
d

Line (1). Output is the line vector (v) and one point (p) on the line. Coefficients:

p_x
p_y
p_z
v_x
v_y
v_z

Circle 2D (2). Output is the center point (p) of the circle and its radius (r) - (Fit in X, Y direction only). Coefficients:

p_x
p_y
r

Circle 3D (3). Output is the normal vector (v), the center point (p) of the circle and the circle radius (r). Coefficients:

p_x
p_y
p_z
r
v_x
v_y
v_z

Sphere (4). Output is the center point (p) and the radius (r). Coefficients:

p_x
p_y
p_z
r

Cylinder (5)*. Output is the orientation vector (v), one point (p) on the line and the cylinder radius (r). Coefficients:

p_x
p_y
p_z
v_x
v_y
v_z
r

Cone (6)*. Output is the orientation vector (v), the tip point (p) and the opening angle in rad. Coefficients:

p_x
p_y
p_z
v_x
v_y
v_z
angle

Models with * need an input cloud where normal vectors are defined.

Parameters

pointCloudIn (itom.pointCloud) – Input point cloud with normal values
modelType (int) –
Model type according to enum pcl::SacModel

Value range: [0, 10], Default: 0
radiusLimits (Sequence[float], optional) – radius limits [min, max]
axis (Sequence[float], optional) – (normal-)axis to fit to [x, y, z]
maxAngle (float, optional) –
maximum divergence between (normal-)axis and model orientation in radiant

Value range: [0, 3.14159], Default: 3.14159
normalDistanceWeight (float, optional) –
Set the relative weight (between 0 and 1) to give to the angular distance (0 to pi/2) between point normals and the plane normal [default: 0.1]

Value range: [0, 1], Default: 0.1
maxIterations (int, optional) –
maximum number of RANSAC iterations [default: 10000]

Value range: [1, 1000000], Default: 10000
distanceThreshold (float, optional) –
distanceThreshold of pcl [default: 0.05]

Value range: [0, 1e+06], Default: 0.05
optimizeParameters (int, optional) –
if 1: A nonlinear optimization over all 7 parameters is applied (Careful: radius may exceed the given boundaries and then the resulting, considered indices become empty.)

Value range: [0, 1], Default: 0
probability (float, optional) –
the probability of choosing at least one sample free from outliers. [default: 0.99]

Value range: [0, 1], Default: 0.99

Returns

coefficientsModel - Vector with the model coefficients according to model definition.

Return type

Sequence[float]

Returns

inliers - number of points considered after filtering outliers (due to RANSAC principle)

Return type

int

itom.algorithms.pclFitModelDObj(dataObjIn, modelType, randomSamples[, radiusLimits, axis, maxAngle, normalDistanceWeight, maxIterations, distanceThreshold, optimizeParameters, probability])

fits a geometric model to the given input data object using a RANSAC based approach.

The input data object is transformed to a point cloud where the values are the Z coordinates, the X and Y coordinates are calculated using a meshgrid based on the axis scales and offsets.

The method used for this fit is from the sample consensus module of point cloud library. (See http://docs.pointclouds.org/1.7.0/group__sample__consensus.html).

The following models are available:

Plane (0). Hessian Normal Form (n_vec * pt + d = 0). Coefficients:

n_x
n_y
n_z
d

Line (1). Output is the line vector (v) and one point (p) on the line. Coefficients:

p_x
p_y
p_z
v_x
v_y
v_z

Circle 2D (2). Output is the center point (p) of the circle and its radius (r) - (Fit in X, Y direction only). Coefficients:

p_x
p_y
r

Circle 3D (3). Output is the normal vector (v), the center point (p) of the circle and the circle radius (r). Coefficients:

p_x
p_y
p_z
r
v_x
v_y
v_z

Sphere (4). Output is the center point (p) and the radius (r). Coefficients:

p_x
p_y
p_z
r

Cylinder (5). Output is the orientation vector (v), one point (p) on the line and the cylinder radius (r). Coefficients:

p_x
p_y
p_z
v_x
v_y
v_z
r

Cone (6). Output is the orientation vector (v), the tip point (p) and the opening angle in rad. Coefficients:

p_x
p_y
p_z
v_x
v_y
v_z
angle

Parameters

dataObjIn (itom.dataObject) – Input data object
modelType (int) –
Model type according to enum pcl::SacModel

Value range: [0, 10], Default: 0
randomSamples (int) –
Number of random samples. If this number is in the range [256,65355], randomly selected values from the data object are taken into account for the fit, else all values are used for the ransac fit

Value range: [256, 65356], Default: 65356
radiusLimits (Sequence[float], optional) – radius limits [min, max]
axis (Sequence[float], optional) – (normal-)axis to fit to [x, y, z]
maxAngle (float, optional) –
maximum divergence between (normal-)axis and model orientation in radiant

Value range: [0, 3.14159], Default: 3.14159
normalDistanceWeight (float, optional) –
Set the relative weight (between 0 and 1) to give to the angular distance (0 to pi/2) between point normals and the plane normal [default: 0.1]

Value range: [0, 1], Default: 0.1
maxIterations (int, optional) –
maximum number of RANSAC iterations [default: 10000]

Value range: [1, 1000000], Default: 10000
distanceThreshold (float, optional) –
distanceThreshold of pcl [default: 0.05]

Value range: [0, 1e+06], Default: 0.05
optimizeParameters (int, optional) –
if 1: A nonlinear optimization over all 7 parameters is applied (Careful: radius may exceed the given boundaries and then the resulting, considered indices become empty.)

Value range: [0, 1], Default: 0
probability (float, optional) –
the probability of choosing at least one sample free from outliers. [default: 0.99]

Value range: [0, 1], Default: 0.99

Returns

coefficientsModel - Vector with the model coefficients according to model definition.

Return type

Sequence[float]

Returns

inliers - number of points considered after filtering outliers (due to RANSAC principle)

Return type

int

itom.algorithms.pclFitPlane(pointCloudIn[, normalDistanceWeight, maxIterations, distanceThreshold, optimizeParameters, probability])

fits a plane model to the given input point cloud using a RANSAC based approach

Parameters

pointCloudIn (itom.pointCloud) – Input point cloud with normal values
normalDistanceWeight (float, optional) –
Set the relative weight (between 0 and 1) to give to the angular distance (0 to pi/2) between point normals and the plane normal [default: 0.1]

Value range: [0, 1], Default: 0.1
maxIterations (int, optional) –
maximum number of RANSAC iterations [default: 10000]

Value range: [1, 1000000], Default: 10000
distanceThreshold (float, optional) –
distanceThreshold of pcl [default: 0.05]

Value range: [0, 1e+06], Default: 0.05
optimizeParameters (int, optional) –
if 1: nonlinear optimization over all parameters is run (Careful: radius may exceed the given boundaries and then the resulting, considered indices become empty.)

Value range: [0, 1], Default: 0
probability (float, optional) –
the probability of choosing at least one sample free from outliers. [default: 0.99]

Value range: [0, 1], Default: 0.99

Returns

orientationVector - resulting normal vector

Return type

Sequence[float]

Returns

value - resulting last value of Hesse Form

Return type

float

Returns

inliers - number of points considered after filtering outliers (due to RANSAC principle)

Return type

int

itom.algorithms.pclFitSphere(pointCloudIn, radiusLimits[, normalDistanceWeight, maxIterations, distanceThreshold, optimizeParameters, probability])

fits a spherical model to the given input point cloud using a RANSAC based approach

Parameters

pointCloudIn (itom.pointCloud) – Input point cloud with normal values
radiusLimits (Sequence[float]) – radius limits [min, max]
normalDistanceWeight (float, optional) –
Set the relative weight (between 0 and 1) to give to the angular distance (0 to pi/2) between point normals and the plane normal [default: 0.1]

Value range: [0, 1], Default: 0.1
maxIterations (int, optional) –
maximum number of RANSAC iterations [default: 10000]

Value range: [1, 1000000], Default: 10000
distanceThreshold (float, optional) –
distanceThreshold of pcl [default: 0.05]

Value range: [0, 1e+06], Default: 0.05
optimizeParameters (int, optional) –
if 1: nonlinear optimization over al 7 parameters is run (Careful: radius may exceed the given boundaries and then the resulting, considered indices become empty.)

Value range: [0, 1], Default: 0
probability (float, optional) –
the probability of choosing at least one sample free from outliers. [default: 0.99]

Value range: [0, 1], Default: 0.99

Returns

point - resulting center point of spehre

Return type

Sequence[float]

Returns

radius - resulting fitted radius of sphere

Return type

float

Returns

inliers - number of points considered after filtering outliers (due to RANSAC principle)

Return type

int

itom.algorithms.pclFitTrimmedBSpline(pointCloudIn[, meshOut, order, refinement, iterations, meshResolution, filename, surfaceFitParams, CurveFitParams])

This filter fits a trimmed B-spline to a point cloud. This filter is mainly derived from the example at http://pointclouds.org/documentation/tutorials/bspline_fitting.php.

After the fit, you can either obtain the result as a polygonMesh that is discretized from the resulting B-spline or the fitted B-spline can be saved in the OpenNURBS format (3dm) to the harddrive.

Parameters

pointCloudIn (itom.pointCloud) – Input point cloud with normal values
meshOut (itom.polygonMesh, optional) – fitted mesh
order (int, optional) –
polynomial order of the B-spline surface

Value range: [1, 100], Default: 3
refinement (int, optional) –
number of refinement iterations, where for each iteration control-points are inserted, approximately doubling the control points in each parametric direction of the B-spline surface

Value range: [0, 100], Default: 1
iterations (int, optional) –
number of iterations that are performed after refinement is completed

Value range: [0, 100], Default: 1
meshResolution (int, optional) –
the number of vertices in each parametric direction, used for triangulation of the B-spline surface

Value range: [1, 10000], Default: 256
filename (str, optional) – filename of a *.3dm OpenNURBS file. If given, the B-spline surface and curve are saved as two layers in the file
surfaceFitParams (Sequence[float], optional) –
parameters for the B-spline surface fitting (interior_smoothness, interior_weight, boundary_smoothness, boundary_weight)

4 values required, Value range: [0, inf], Default: [0.2, 1, 0.2, 0]
CurveFitParams (Sequence[float], optional) –
parameters for the B-spline curve fitting (addCPsAccuracy, addCPsIteration (int), maxCPs (int), accuracy, iterations (int), closest_point_resolution (int), closest_point_weight, closest_point_sigma2, interior_sigma2, smooth_concavity, smoothness)

11 values required, Value range: [0, inf], Default: [0.05, 3, 200, 0.001, …, 0.1, 1e-05, 1, 1]

itom.algorithms.pclGetHistogram(pointCloudIn, fieldName, minValue, maxValue, steps, histogram[, uniformDistribution])

returns the histogram of the specific field.

Parameters

pointCloudIn (itom.pointCloud) – Valid input point cloud
fieldName (str) – field name, whose values are used for the calculation of the histogram
minValue (float) –
lower boundary of the uniformly distributed histogram

Value range: [0, 3.40282e+38], Default: 4095
maxValue (float) –
upper boundary of the uniformly distributed histogram

Value range: [0, 3.40282e+38], Default: 4095
steps (int) –
number of discrete fields in the histogram

Value range: [1, inf], Default: 4096
histogram (itom.dataObject) – The histogram is a int32 data object with size [1 x steps].
uniformDistribution (itom.dataObject, optional) – provide a dataObject if you want to access the uniform percentage distribution. The resulting data object is of type float32 and has the size [1 x 100]. The value at index j gives the histogram value, where j% of the values lies below that value.

itom.algorithms.pclGetMinMax3D(pointCloudIn)

get the minimum and maximum values on each of the 3 (x-y-z) dimensions in a given pointcloud.

Parameters: pointCloudIn (itom.pointCloud) – Valid input point cloud
Returns: minXYZ - minimum (x,y,z) values
Return type: Sequence[float]
Returns: maxXYZ - maximum (x,y,z) values
Return type: Sequence[float]

itom.algorithms.pclGetNormalsAtCogFromMesh(mesh, cloudWithNormals[, indices])

calculates a point cloud with normal information which contains the normal at each triangle of the given polygonal mesh centered at the center of gravity of the triangle. Use indices to filter only certain triangles.

Parameters

mesh (itom.polygonMesh) – Valid polygonal mesh
cloudWithNormals (itom.pointCloud) – output point cloud with the same point type than contained in the mesh but including normal vectors.
indices (Sequence[int], optional) – Optional list with indices that should be considered.

itom.algorithms.pclGetPercentageThreshold(pointCloudIn, fieldName, percentage[, sortedValues])

returns the threshold value at the percentage value in the sorted values of the specific field.

Parameters

pointCloudIn (itom.pointCloud) – Valid input point cloud
fieldName (str) – field name, whose values are used for the determination of the threshold value.
percentage (float) –
percentage value [0.0,100.0]

Value range: [0, 100], Default: 50
sortedValues (itom.dataObject, optional) – provide a dataObject if you want to access the sorted values of ‘fieldName’. The output is then a float32 data object of size [1 x n], where n is the number of valid values in the specific field.

Returns

threshold - threshold value (NaN if point cloud was empty or invalid)

Return type

float

itom.algorithms.pclMeshTriangulation(meshIn, meshOut)

calculates polygon mesh with triangles only. This is based on the ear-clipping algorithm, the complexity is n^3 and it does not handle holes.

Parameters

meshIn (itom.polygonMesh) – Valid polygon mesh
meshOut (itom.polygonMesh) – output polygon mesh

itom.algorithms.pclOrganizedFastMesh(organizedCloud, meshOut[, triangulationType, trianglePixelSizeRows, trianglePixelSizeColumns, storeShadowFaces])

creates a triangle based, polygonial mesh from an organized point cloud. The triangles are always spanned between neighboured points of the organized cloud.

Parameters

organizedCloud (itom.pointCloud) – Valid, organized point cloud
meshOut (itom.polygonMesh) – output polygonal mesh
triangulationType (str, optional) –
‘TRIANGLE_RIGHT_CUT’: _always_ cuts a quad from top left to bottom right (default), ‘TRIANGLE_LEFT_CUT’: _always_ cuts a quad from top right to bottom left, ‘TRIANGLE_ADAPTIVE_CUT’: cuts where possible and prefers larger differences in z direction, ‘QUAD_MESH’: create a simple quad mesh

Match: [“TRIANGLE_RIGHT_CUT”, “TRIANGLE_LEFT_CUT”, “TRIANGLE_ADAPTIVE_CUT”, “QUAD_MESH”], Default: “TRIANGLE_RIGHT_CUT”
trianglePixelSizeRows (int, optional) –
Set the edge length (in pixels) used for iterating over rows when constructing the fixed mesh. Default: 1, neighboring pixels are connected

Value range: [1, 1000000], Default: 1
trianglePixelSizeColumns (int, optional) –
Set the edge length (in pixels) used for iterating over columns when constructing the fixed mesh. Default: 1, neighboring pixels are connected

Value range: [1, 1000000], Default: 1
storeShadowFaces (int, optional) –
Store shadowed faces or not (default: 1, yes).

Value range: [0, 1], Default: 1

itom.algorithms.pclPCA(pointCloudIn[, eigenVectors])

determines PCA of point Cloud.

Parameters

pointCloudIn (itom.pointCloud) – Valid input point cloud
eigenVectors (itom.dataObject, optional) – results in 3x3 float32 data object with three eigen-vectors

Returns

mean - mean value

Return type

Sequence[float]

Returns

eigenValues - eigen values

Return type

Sequence[float]

itom.algorithms.pclPassThrough(pointCloudIn, pointCloudOut, fieldName[, minValue, maxValue, negative])

filters a point cloud by giving boundary values to a specific dimension (outside or inside of this field).

Parameters

pointCloudIn (itom.pointCloud) – Valid input point cloud
pointCloudOut (itom.pointCloud) – Output point cloud with removed NaN values
fieldName (str) – valid field name to filter ‘x’,’y’,z’,’intensity’…
minValue (float, optional) –
minimum value (default: -FLT_MAX)

Value range: [-3.40282e+38, 3.40282e+38], Default: -3.40282e+38
maxValue (float, optional) –
maximum value (default: FLT_MAX)

Value range: [-3.40282e+38, 3.40282e+38], Default: 3.40282e+38
negative (int, optional) –
1: values inside of range will be deleted, else 0 [default]

Value range: [0, 1], Default: 0

itom.algorithms.pclPolygonMeshFromIndices(meshIn, meshOut, indices)

get sub-mesh from given mesh by the indices of the polygons.

Parameters

meshIn (itom.polygonMesh) – Valid polygon mesh
meshOut (itom.polygonMesh) – output polygon mesh
indices (Sequence[int]) – vector with indices of polygons that will be copied into output mesh

itom.algorithms.pclProjectOnModel(pointCloudIn, pointCloudOut, modelType[, point, orientationVector, radius])

Projects points onto a given model.

Parameters

pointCloudIn (itom.pointCloud) – Input point cloud with normal values
pointCloudOut (itom.pointCloud) – Output point cloud with distances
modelType (int) –
Model type according to enum pcl::SacModel

Value range: [0, 10], Default: 0
point (Sequence[float], optional) – point on cylinder symmetrie axis
orientationVector (Sequence[float], optional) – symmetrie axis of cylinder
radius (float, optional) –
cylinder radius

Value range: [-3.40282e+38, 3.40282e+38], Default: 0

itom.algorithms.pclRandomSample(pointCloudIn, pointCloudOut, nrOfPoints)

randomly reduces the point cloud to a given number of points.

Parameters

pointCloudIn (itom.pointCloud) – Valid input point cloud
pointCloudOut (itom.pointCloud) – Output point cloud with removed NaN values
nrOfPoints (int) –
number of randomly picked points.

Value range: [1, inf], Default: 10000

itom.algorithms.pclRemoveNaN(pointCloudIn, pointCloudOut)

removes NaN values from input point cloud (input and output can be the same).

Parameters

pointCloudIn (itom.pointCloud) – Valid input point cloud
pointCloudOut (itom.pointCloud) – Output point cloud with removed NaN values

itom.algorithms.pclSampleToDataObject(organizedCloud, disperityMap, width, height[, intensityMap, curvatureMap])

Uses copy an organized and dense pointcloud to an dataObject.

Parameters

organizedCloud (itom.pointCloud) – Valid, organized point cloud
disperityMap (itom.dataObject) – Output dataObject with z-Values
width (int) –
Output dataObject with z-Values

Value range: [1, inf], Default: 1280
height (int) –
Output dataObject with z-Values

Value range: [1, inf], Default: 1024
intensityMap (itom.dataObject, optional) – Output dataObject with intensity-Values
curvatureMap (itom.dataObject, optional) – Output dataObject with curvature-Values

itom.algorithms.pclSimplifyMesh(meshIn, meshOut)

Used SimplificationRemoveUnusedVertices from the PCL to simplify a pcl mesh.

Parameters

meshIn (itom.polygonMesh) – Valid, organized point cloud
meshOut (itom.polygonMesh) – output polygonal mesh

Returns

inliers - number of deleted elements

Return type

int

itom.algorithms.pclStatisticalOutlierRemoval(pointCloudIn, pointCloudOut, meanK, stdDevMulThresh[, negative, keepOrganized])

uses point neighborhood statistics to filter outlier data.

Parameters

pointCloudIn (itom.pointCloud) – Valid input point cloud
pointCloudOut (itom.pointCloud) – Output point cloud with removed NaN values
meanK (int) –
number of nearest neighbors to use for mean distance estimation

Value range: [1, 1000000], Default: 8
stdDevMulThresh (float) –
standard deviation multiplier for the distance threshold calculation

Value range: [0, 1e+06], Default: 1
negative (int, optional) –
0: the regular filter conditions are applied [default], 1: the inverted conditions are applied

Value range: [0, 1], Default: 0
keepOrganized (int, optional) –
filtered points should be kept and set to NaN [1] or removed (potentially breaking organized structure) [default: 0]

Value range: [0, 1], Default: 0

itom.algorithms.pclSurfaceByMarchingCubes(cloud, meshOut[, algorithmType, isoLevel, gridResolution, percentageExtendGrid, distIgnore, offSurfaceEpsilon])

The marching cubes surface reconstruction algorithm.

There are two algorithms implemented:

MarchingCubesHoppe:
using a signed distance function based on the distance from tangent planes, proposed by Hoppe et. al.in:

Hoppe H., DeRose T., Duchamp T., MC - Donald J., Stuetzle W., “Surface reconstruction from unorganized points”, SIGGRAPH ‘92
MarchingCubesRBF:
The marching cubes surface reconstruction algorithm, using a signed distance function based on radial basis functions.Partially based on:

Carr J.C., Beatson R.K., Cherrie J.B., Mitchell T.J., Fright W.R., McCallum B.C. and Evans T.R., “Reconstruction and representation of 3D objects with radial basis functions” SIGGRAPH ‘01

Parameters

cloud (itom.pointCloud) – Input point cloud with normal vector information.
meshOut (itom.polygonMesh) – Output polygonal mesh
algorithmType (int, optional) –
0: MarchingCubesHoppe, 1: MarchingCubesRBF

Value range: [0, 1], Default: 0
isoLevel (float, optional) –
the iso level of the surface to be extracted.

Value range: [-100000, 100000], Default: 0
gridResolution (Sequence[int], optional) –
The grid resolution in x, y, and z (default: 32 each)

3 values required, All values allowed, Default: [32, 32, 32]
percentageExtendGrid (float, optional) –
parameter that defines how much free space should be left inside the grid between the bounding box of the point cloud and the grid limits, as a percentage of the bounding box.

Value range: [-100000, 100000], Default: 0
distIgnore (float, optional) –
Method that sets the distance for ignoring voxels which are far from point cloud. If the distance is negative, then the distance functions would be calculated in all voxels; otherwise, only voxels with distance lower than dist_ignore would be involved in marching cube. Default value is - 1.0. Set to negative if all voxels are to be involved. Only used for algorithmType = MarchingCubesHoppe (0).

Value range: [-1, 100000], Default: -1
offSurfaceEpsilon (float, optional) –
Set the off - surface points displacement value. Only used for algorithmType = MarchingCubesRBF (1)

Value range: [-100000, 100000], Default: 0.1

itom.algorithms.pclSurfaceByPoisson(cloud, meshOut[, treeDepth, minTreeDepth, isoDivide, solverDivide])

Uses pcl::Poisson-filter to reduce a mesh / estimate the surface of an object.

Parameters

cloud (itom.pointCloud) – Input point cloud with normal vector information.
meshOut (itom.polygonMesh) – Output polygonal mesh
treeDepth (int, optional) –
Maximum depth of the octTree to reconstruct. Be careful: High values might require a lot of memory and processing time.

Value range: [1, 100], Default: 8
minTreeDepth (int, optional) –
The minimum depth.

Value range: [1, 100], Default: 5
isoDivide (int, optional) –
Set the depth at which a block iso-surface extractor should be used to extract the iso-surface. This parameter must be >= minTreeDepth.

Using this parameter helps reduce the memory overhead at the cost of a small increase in extraction time. (In practice, we have found that for reconstructions of depth 9 or higher a subdivide depth of 7 or 8 can greatly reduce the memory usage.)

Value range: [1, 100], Default: 8
solverDivide (int, optional) –
Get the depth at which a block Gauss-Seidel solver is used to solve the Laplacian equation. This parameter must be >= minTreeDepth.

Using this parameter helps reduce the memory overhead at the cost of a small increase in extraction time. (In practice, we have found that for reconstructions of depth 9 or higher a subdivide depth of 7 or 8 can greatly reduce the memory usage.)

Value range: [1, 100], Default: 8

itom.algorithms.pclTransformAffine(pointCloudIn, pointCloudOut, transform)

Applies an affine coordinate transform to the input pointCloud

The transformed point cloud is saved in ‘pointCloudOut’ (inplace possible). The transformation matrix has to be a 4x4 homogeneous transformation matrix given by a 4x4 real dataObject (uint8, int8, uint16, int16, uint32, int32 or float32 allowed). Every point P_in in the input cloud is transformed by P_out = transform * P_in. Independent on the type of the transformation matrix, the matrix multiplication is done with float32 precision.

Parameters

pointCloudIn (itom.pointCloud) – The affine transform is applied to this point cloud
pointCloudOut (itom.pointCloud) – Resulting, transformed point cloud (inplace possible)
transform (itom.dataObject) – 4x4 homogeneous transformation matrix (uint8, int8, uint16, int16, uint32, int32, float32, float64)

itom.algorithms.pclTrimmedICP(pointCloudTarget, pointCloudSource, numSourcePointsToUse, transform)

No description

Parameters

pointCloudTarget (itom.pointCloud) – Valid target point cloud of type XYZ
pointCloudSource (itom.pointCloud) – Point cloud of same type than target cloud. This cloud is registered to the target.
numSourcePointsToUse (int) –
gives the number of closest source points taken into account for registration. By closest source points we mean the source points closest to the target. These points are computed anew at each iteration.

Value range: [0, inf], Default: 100
transform (itom.dataObject) – is the estimated rigid transform. IMPORTANT: this matrix is also taken as the initial guess for the alignment. If there is no guess, set the matrix to identity!

itom.algorithms.pclVoxelGrid(pointCloudIn, pointCloudOut, leafSize[, downsampleAllData, fieldName, fieldMin, fieldMax, negative])

downsamples a point cloud using a voxelized gripd approach.

Parameters

pointCloudIn (itom.pointCloud) – Valid input point cloud
pointCloudOut (itom.pointCloud) – Output point cloud with removed NaN values
leafSize (Sequence[float]) – voxel grid leaf size [lx,ly,lz] (3 elements necessary)
downsampleAllData (int, optional) –
1: downsample all fields, 0: only xyz [default]

Value range: [0, 1], Default: 0
fieldName (str, optional) – field name, whose value is filtered between ‘fieldMin’ and ‘fieldMax’ or ‘’ if no field filtering should be applied [default]
fieldMin (float, optional) –
minimum field filtering value (default: FLT_MIN)

Value range: [1.17549e-38, 3.40282e+38], Default: 1.17549e-38
fieldMax (float, optional) –
maximum field filtering value (default: FLT_MAX)

Value range: [1.17549e-38, 3.40282e+38], Default: 3.40282e+38
negative (int, optional) –
0 [default]: values inside of field range will be deleted, else 1

Value range: [0, 1], Default: 0

itom.algorithms.savePointCloud(pointCloud, filename[, mode, type])

saves pointCloud to hard drive (format pcd(binary or ascii), ply(binary or ascii), vtk(ascii), xyz(ascii))

Parameters

pointCloud (itom.pointCloud) – point cloud to save
filename (str) – complete filename (type is either read by suffix of filename or by parameter ‘type’
mode (str, optional) – mode (b=binary (default) or t=ascii, for type ‘pcd’ and ‘ply’ only)
type (str, optional) – type (‘pcd’ [default],’ply’,’vtk’,’xyz’)

itom.algorithms.savePolygonMesh(polygonMesh, filename[, type, binary, precision])

saves polygonMesh to hard drive (format obj[default], ply, vtk, stl)

Parameters

polygonMesh (itom.polygonMesh) – polygon mesh to save
filename (str) – complete filename (type is either read by suffix of filename or by parameter ‘type’)
type (str, optional) – type (‘obj’ [default],’ply’,’vtk’,’stl’)
binary (int, optional) –
If 1 (default), the file is written as binary file, else ascii. If type is ‘obj’, the file is always an ascii file. (This option is only considered for PCL > 1.8.0).

Value range: [0, 1], Default: 1
precision (int, optional) –
Precision (default: 5), only valid for ‘obj’-file types.

Value range: [0, 16], Default: 5

itom.algorithms.saveVTKImageData(dataObject, filename[, mode, scalarFieldName, scalarThreshold])

saves a 2D or 3D uint8 or uint16 data object to a VTK imageData volume image

This file format allows displaying volume data from the given 3D data object for instance using ParaView.

Parameters

dataObject (itom.dataObject) – data object to save (two or three dimensional, uint8 or uint16)
filename (str) – complete filename, ending .vti will be appended if not available
mode (str, optional) –
mode (b=binary (default) or t=ascii)

Match: [“b”, “t”], Default: “b”
scalarFieldName (str, optional) – name of scalar field, e.g. ‘scalars’ (zero values will be transparent), ‘ImageScalars’ (zero values will be displayed)…
scalarThreshold (int, optional) –
values <= threshold will be set to 0 (transparent values for scalar field name ‘scalars’)

Value range: [0, 65535], Default: 0

5.9.3. Changelog

itom setup 1.2.0: This plugin has been compiled using the PCL 1.6.0
itom setup 2.0.0: This plugin has been compiled using the PCL 1.8.0
itom setup 2.1.0: This plugin has been compiled using the PCL 1.8.0
itom setup 2.2.0: This plugin has been compiled using the PCL 1.8.0
itom setup 3.0.0: This plugin has been compiled using the PCL 1.8.0
itom setup 3.1.0: This plugin has been compiled using the PCL 1.8.0
itom setup 3.2.1: This plugin has been compiled using the PCL 1.8.0
itom setup 4.0.0: This plugin has been compiled using the PCL 1.8.0
itom setup 4.1.0: This plugin has been compiled using the PCL 1.8.0