Histogram3DInterpolationPolynomial¶

MLModule
¶
Purpose¶
The module Histogram3DInterpolationPolynomial
computes (an approximation to) a histogram of a multivariate interpolation polynomial with values in a threedimensional space (represented as three scalarvalued multivariate polynomials).
Be sure not to confuse the dimension of the preimage space (which is arbitrarily high here as for all the * InterpolationPolynomial modules) with the dimension of the image space (which is 3 here but only 1 for most other * InterpolationPolynomial modules). Since the modules that create multivariate interpolation polynomials do not support that, we need three polynomials as input.
Input Fields¶
Connect here the polynomials to be examined. The module only works if all three inputs are fed.
However, if you want to compute a histogram of a 1D or 2D valued polynomial, connect a zero polynomial to the other inputs (using the TensorInterpolationPolynomial
module with Nodes=Values=0). However, this workaround will most probably not work with the 'sophisticated algorithm', see below.
A Histogram3DInterpolationPolynomial
module might be included in the project later to serve this purpose.
Parameter Fields¶
Field Index¶
Bounding Box Polynomial 1 : String 
Image Voxel Size : Vector3 
Bounding Box Polynomial 2 : String 
Manual Bounding Box : String 
Bounding Box Polynomial 3 : String 
Manual Image Bounding Box : String 
Bounding Box Selection : Enum 
Maximal Summand to Avoid Cancellation : Double 
Compute on demand : Bool 
Project to bounding box : Bool 
Convert meters : Bool 
Simplify polynomials : Bool 
Epsilon to Avoid Division by Zero : Double 
Use manual image bounding box : Bool 
Histogram Accuracy : Integer 
Use sophisticated algorithm : Bool 
Visible Fields¶
Bounding Box Polynomial 1¶

name:
autoBBox1
, type:
String
, persistent:
no
¶ Shows the generic bounding box of the first polynomial.
It can also be obtained with an
EvaluateInterpolationPolynomial
module. This is a bounding box in the preimage space.
Bounding Box Polynomial 2¶

name:
autoBBox2
, type:
String
, persistent:
no
¶ Shows the generic bounding box of the second polynomial.
It can also be obtained with an
EvaluateInterpolationPolynomial
module. This is a bounding box in the preimage space.
Bounding Box Polynomial 3¶

name:
autoBBox3
, type:
String
, persistent:
no
¶ Shows the generic bounding box of the third polynomial.
It can also be obtained with an
EvaluateInterpolationPolynomial
module. This is a bounding box in the preimage space.
Bounding Box Selection¶

name:
bBoxSelection
, type:
Enum
, default:
Union
¶ Sets whether the generic bounding box of one of the three polynomials or (the convex hull of) their union or a manually entered bounding box is used.
The module needs a bounding box in the preimage space. The polynomial is restricted to this set before the histogram is computed. Since this set is compact, the range of the polynomial will then also be compact, hence bounded. (The range of the polynomial on this set is also referred as the bounding box in image space.)
Values:
Title  Name 

Manual  Manual 
Polynomial 1  Polynomial 1 
Polynomial 2  Polynomial 2 
Polynomial 3  Polynomial 3 
Union  Union 
Manual Bounding Box¶

name:
manBBox
, type:
String
¶ Sets a preimage bounding box manually.
To be used, the
Bounding Box Selection
needs to be set to Manual.
Use manual image bounding box¶

name:
useManImageBBox
, type:
Bool
, default:
TRUE
¶ If checked, an image bounding box can be entered manually.
Manual Image Bounding Box¶

name:
manImageBBox
, type:
String
¶ Sets an image bounding box and it determines the size of the output ML image.
If
Use manual image bounding box
is set to false, the generic bounding box is used here, which is defined as the (cuboid shaped hull of) the compact set of values that the polynomial takes on the selected preimage space bounding box.However, using this automatic value is slower than entering a manual bounding box. Hence it is recommended to enable this switch and enter a sensible manual bounding box.
The behavior of the module in the case that the manual bounding box is too small can be influenced using the
Project to bounding box
field, but not for the 'sophisticated algorithm'.
Use sophisticated algorithm¶

name:
sophisticatedAlgorithm
, type:
Bool
, default:
FALSE
¶ If checked, a different algorithm is used to compute the histogram.
This algorithm is similar to the one employed in the (onedimensional)
HistogramInterpolationPolynomial
module, however the advantage is not so clear for this case. The sophisticated algorithm is supposed to give better results for the sameHistogram Accuracy
but, on the other hand, will be considerably slower. Which of the two algorithms gives the better result with comparable computational effort, may depend on the concrete example.Note that some of the fields below only matter for one of the two algorithms: The
Epsilon to Avoid Division by Zero
andMaximal Summand to Avoid Cancellation
fields only matters for the sophisticated algorithm, theProject to bounding box
field only matters for the standard algorithm.
Histogram Accuracy¶

name:
accuracy
, type:
Integer
, default:
20
, minimum:
2
¶ Sets the number of points per space dimension in which the preimage bounding box is scanned.
The higher the number, the better is the approximation of the histogram, but the slower is the computation.
Image Voxel Size¶

name:
voxelSize
, type:
Vector3
, default:
1 1 1
¶ Sets the voxel size of the output ML image and thus also the quality of the histogram.
This does not influence the performance so much as the
Histogram Accuracy
field.
Convert meters¶

name:
convertMeters
, type:
Bool
, default:
TRUE
¶ If checked, the module will assume that the polynomials' values have the unit of meters and should be converted to millimeters in the ML image (as is usual for the ML).
In this case, the
Image Voxel Size
is interpreted as millimeters as well, whereas theManual Image Bounding Box
is interpreted as meters. If you find this too confusing, disable this field, so that no conversions are performed.
Compute on demand¶

name:
computeOnDemand
, type:
Bool
, default:
FALSE
¶ If checked, the module computes on demand.
It is wellknown that the ML uses a pagebased image processing technique. However, for this module, this is in general unsuited since it would reduce the performance. Hence, this module usually computes the complete output ML image as soon as the first page is requested. However, if you configure the module to yield a very large output image, this could lead to a memory shortage. In this case, you can enable this field. It will solve the memory problem but slow down the computation considerably.
Project to bounding box¶

name:
projectToBBox
, type:
Bool
, default:
TRUE
¶ Sets the behavior of the module in the case that the manually chosen image bounding box is too small.
If disabled, the histogram is just cut off, resulting in an image that does not integrate to one (as it otherwise does). If enabled (which is the default), the values that lie outside are projected to the nearest point inside. The image will then always integrate to one, but where appropriate have noticeably high values on the boundary of the ROI.
This field does not work if the field
Use sophisticated algorithm
is enabled; the histogram is then always cut off.
Epsilon to Avoid Division by Zero¶

name:
eps
, type:
Double
, default:
1e10
, minimum:
0
¶ Sets an epsilon value to avoid a division by zero.
In the computation procedure, some divisions have to be performed where the denominator might be zero. This corresponds to the fact that a histogram can have infinitely high peaks. To avoid problems, the (small) value entered in this field is added to the denominator before the division. The smaller the number, the better is the approximation of the histogram. 0 is allowed but not recommended, except possibly if you are sure that the polynomial has no critical points within the specified bounding box.
This field only matters if the field
Use sophisticated algorithm
is enabled.
Maximal Summand to Avoid Cancellation¶

name:
maxSummand
, type:
Double
, default:
1000000
, minimum:
0
¶ Sets a maximal summand value to avoid cancellation problems.
If the histogram has large peaks, the sophisticated algorithm in its current implementation suffers from some cancellation problem. This will result in large, cuboid shaped areas of the image being filled with strange, wrong values. A workaround is to limit the value of each summand using this field. This changes the height of the peaks, of course, but for most applications this is not important.
If the value is too large, the mentioned cancellation problem occurs. If the value is too small, it affects also the histogram values away from the peaks. A good choice is to use about 100 or 1000 times the largest histogram value away from the peaks.
This field only matters if the field
Use sophisticated algorithm
is enabled.
Simplify polynomials¶

name:
simplifyPolynomials
, type:
Bool
, default:
FALSE
¶ If checked, the polynomials will be simplified first.
The same procedure is used by the module
SimplifyInterpolationPolynomial
.This may either speed up or slow down the computation, depending on the polynomial and on the settings.
Note that simplifying a polynomial destroys the bounding box information, but that does not matter since this module evaluates the bounding boxes before simplifying.