Purpose

Calculates distance to a given point according to various definitions of distance: euclidean=L2, L1, Linf, Lp, sum of distances to two points, distance using some user defined weighting matrix, distance along some directions (X/Y/Z or user given normal direction: 2D distance perpendicular to a line etc.

Alternative modes: octants relative to a split point or sum of dist to two points and anisotropic distance (e.g. distance to a line or plane using appropriate matrices: or normal projection direction*(pos-refPos) further some scaled tesxtures aligned at a given point

List of all available modes:

Distance: Euclidean distance to a selected point (or image center if that is selected as ref. point)

Quadrant: labels quadrants / octants centered at the selected point

DistAndQuad: combines distance and octants (was implemented to easily generate 2D histograms of GV per distance bin to a point per octant)

EllipticDistance: weighted distance computed using a quadratic form (note if the matrix is not positive it is not a distance in the mathematical sense):

value = fabs(scaleFac) * sqrt(fabs(
                v[0]*(v[0]*M[0][0]+v[1]*M[1][0]+v[2]*M[2][0]) +
                v[1]*(v[0]*M[0][1]+v[1]*M[1][1]+v[2]*M[2][1]) +
                v[2]*(v[0]*M[0][2]+v[1]*M[1][2]+v[2]*M[2][2])   ))

DistTo2Points: Sum of distance to 2 points

DistTo2PointsFloat: Sum of distance to 2 points computed in world coordinats (sould be identical to other (faster ? algorithm)

DistTo2PointsMinusPointDist: Sum of distance to 2 points minus the point distance (easier to parametrize)

L1Distance: L_1 distance to a point

LinfinityDistance: L_inf distance to a point

LpDistance: L_p distance to a point ( check any good 1 year analysis book for references)

NormalProjection: Using half voxel shift on voxel coordinates as we now use world coordinates:

normalLength = sqrt(wPos2X*wPos2X + wPos2Y*wPos2Y + wPos2Z*wPos2Z);
wp = inImg->mapVoxelToWorld(Vector3((pxDbl)+shift,(pyDbl)+shift,(pzDbl)+shift));
val =  ((wp.x - wPosX ) * (wPos2X )) +
       ((wp.y - wPosY ) * (wPos2Y )) +
       ((wp.z - wPosZ ) * (wPos2Z )) / normalLength;
VoxelCoordinateNormalProjection:
aims for same results as NormalProjection but using a implementation avoiding transforming all positions to world coordinates (about 4-5 times faster) by usage of 3 scale factors (one per dimension XYZ) and multiplications in place of divisions in inner loops.
DistToLine: distance to a line (normal given in the field other wise used for a 2nd point)
= sqrt ( 3D dist - NormalProjection^2)

XDistance: / YDistance: ZDistance: physical distance along one dimension only

Voxel#Distance with # in {X,Y,Z}: voxel count distance along one dimension only

VoxelCheckerBoard# with # in {3D, XY, XZ, YZ}: 3D resp 2D checkerboard with scale sized 0 / 1 cubes resp. stripes in the XY / XZ or YZ plane

Voxel2DSquaresXY: like 2D graph paper with square size = scale voxels

The binarize flag will automatically apply a threshold of the value scale to the result. For the modes with positive results only, a scale value < 0 will produce the inverted results of the results with abs(scale).

For modes with signed results (e.g. dist along X/Y/Z in mm or voxels resp. dist in mm in long a normal direction) such inversion makes no sense and e.g. with scale -10 you get the half plane with dist > -10 mm / voxles instead of the 20 mm / voxels shifted one obtained with scale = +10.

Usage

Simply connect an image to provide a reference geometry and select parameters for mode and point(s) and optional scaling / matrix parameters or indicate usage of (half voxel shifted) volume center as reference point.

Details

Note the some modes are rather slow e.g. due to numerous square root calls which are costly or WorldVoxelTransformations per output voxel. Consider using faster alternatives:

Some of the slower modes are:

Distance (3x slower then DistanceSquared)
X/Y/ZDistance (much slower than the related voxel X/Y/Z Distance which however only provide the same results the the mode with out voxel in the name for axial images )
EllipticDistance (uses a matrix multiplication per voxel)
DistTo2PointsFloat and DistTo2PointsMinusPointDist are much slower then DistTo2Points (which ist still slow as is uses 2 sqrt)

One might consider to add a really fast mode reporting ||v-x1||^2 + ||v-x2||^2 - ||x2-x1||^2 if a similar mode should become time critical in an application)

Table comparing the speed of all modes with some paraemters:

 ####### Table of times to compute full volumes  #######
 mode <Distance> from <item: Distance title:'Distance' int:0>
 <Distance>: scale:  1.0, binary=False;  t=   7.9 sec/GigaVx,  100.0% of (t_Distance)
 <Distance>: scale: -1.0, binary=False;  t=   8.7 sec/GigaVx,  100.0% of (t_Distance)
 <Distance>: scale:  0.1, binary=False;  t=   7.4 sec/GigaVx,  100.0% of (t_Distance)
 <Distance>: scale:  5.0, binary=False;  t=   7.0 sec/GigaVx,  100.0% of (t_Distance)
 <Distance>: scale:  5.0, binary=True;  t=   3.4 sec/GigaVx,   47.8% of (t_Distance) (fast mode)
 mode <DistanceSquared> from <item: DistanceSquared title:'Distance Squared' int:1>
 <DistanceSquared>: scale:  1.0, binary=False;  t=   2.9 sec/GigaVx,   41.5% of (t_Distance) (fast mode)
 <DistanceSquared>: scale: -1.0, binary=False;  t=   3.4 sec/GigaVx,   49.1% of (t_Distance) (fast mode)
 <DistanceSquared>: scale:  0.1, binary=False;  t=   3.0 sec/GigaVx,   42.6% of (t_Distance) (fast mode)
 <DistanceSquared>: scale:  5.0, binary=False;  t=   4.2 sec/GigaVx,   59.7% of (t_Distance)
 <DistanceSquared>: scale:  5.0, binary=True;  t=   2.8 sec/GigaVx,   40.0% of (t_Distance) (fast mode)
 mode <Quadrant> from <item: Quadrant title:'Quadrant' int:2>
 <Quadrant>: scale:  1.0, binary=False;  t=   3.1 sec/GigaVx,   44.3% of (t_Distance) (fast mode)
 <Quadrant>: scale: -1.0, binary=False;  t=   3.8 sec/GigaVx,   54.9% of (t_Distance)
 <Quadrant>: scale:  0.1, binary=False;  t=   3.6 sec/GigaVx,   50.9% of (t_Distance)
 <Quadrant>: scale:  5.0, binary=False;  t=   3.5 sec/GigaVx,   49.3% of (t_Distance) (fast mode)
 <Quadrant>: scale:  5.0, binary=True;  t=   5.3 sec/GigaVx,   75.6% of (t_Distance)
 mode <DistAndQuad> from <item: DistAndQuad title:'Dist And Quad' int:3>
 <DistAndQuad>: scale:  1.0, binary=False;  t=   8.1 sec/GigaVx,  115.2% of (t_Distance)
 <DistAndQuad>: scale: -1.0, binary=False;  t=   8.3 sec/GigaVx,  118.1% of (t_Distance)
 <DistAndQuad>: scale:  0.1, binary=False;  t=   9.0 sec/GigaVx,  128.7% of (t_Distance)
 <DistAndQuad>: scale:  5.0, binary=False;  t=   8.3 sec/GigaVx,  118.6% of (t_Distance)
 <DistAndQuad>: scale:  5.0, binary=True;  t=   8.7 sec/GigaVx,  124.0% of (t_Distance)
 mode <DistTo2Points> from <item: DistTo2Points title:'Dist To2Points' int:5>
 <DistTo2Points>: scale:  1.0, binary=False;  t=  12.9 sec/GigaVx,  184.7% of (t_Distance)
 <DistTo2Points>: scale: -1.0, binary=False;  t=  13.7 sec/GigaVx,  195.2% of (t_Distance)
 <DistTo2Points>: scale:  0.1, binary=False;  t=  12.8 sec/GigaVx,  182.0% of (t_Distance)
 <DistTo2Points>: scale:  5.0, binary=False;  t=  12.8 sec/GigaVx,  182.7% of (t_Distance)
 <DistTo2Points>: scale:  5.0, binary=True;  t=  13.3 sec/GigaVx,  189.3% of (t_Distance)
 mode <DistTo2PointsFloat> from <item: DistTo2PointsFloat title:'Dist To2Points Float' int:6>
 <DistTo2PointsFloat>: scale:  1.0, binary=False;  t=  92.8 sec/GigaVx,  1323.8% of (t_Distance) (slow mode)
 <DistTo2PointsFloat>: scale: -1.0, binary=False;  t=  94.6 sec/GigaVx,  1349.4% of (t_Distance) (slow mode)
 <DistTo2PointsFloat>: scale:  0.1, binary=False;  t=  92.1 sec/GigaVx,  1313.8% of (t_Distance) (slow mode)
 <DistTo2PointsFloat>: scale:  5.0, binary=False;  t=  92.5 sec/GigaVx,  1320.0% of (t_Distance) (slow mode)
 <DistTo2PointsFloat>: scale:  5.0, binary=True;  t=  93.1 sec/GigaVx,  1329.0% of (t_Distance) (slow mode)
 mode <DistTo2PointsMinusPointDist> from <item: DistTo2PointsMinusPointDist title:'Dist To2Points Minus Point Dist' int:9>
 <DistTo2PointsMinusPointDist>: scale:  1.0, binary=False;  t=  92.5 sec/GigaVx,  1319.4% of (t_Distance) (slow mode)
 <DistTo2PointsMinusPointDist>: scale: -1.0, binary=False;  t=  92.7 sec/GigaVx,  1322.8% of (t_Distance) (slow mode)
 <DistTo2PointsMinusPointDist>: scale:  0.1, binary=False;  t=  92.5 sec/GigaVx,  1319.4% of (t_Distance) (slow mode)
 <DistTo2PointsMinusPointDist>: scale:  5.0, binary=False;  t=  92.3 sec/GigaVx,  1317.6% of (t_Distance) (slow mode)
 <DistTo2PointsMinusPointDist>: scale:  5.0, binary=True;  t=  92.3 sec/GigaVx,  1317.6% of (t_Distance) (slow mode)
 mode <L1Distance> from <item: L1Distance title:'L1Distance' int:7>
 <L1Distance>: scale:  1.0, binary=False;  t=   3.7 sec/GigaVx,   52.3% of (t_Distance)
 <L1Distance>: scale: -1.0, binary=False;  t=   2.9 sec/GigaVx,   41.9% of (t_Distance) (fast mode)
 <L1Distance>: scale:  0.1, binary=False;  t=   3.4 sec/GigaVx,   48.2% of (t_Distance) (fast mode)
 <L1Distance>: scale:  5.0, binary=False;  t=   3.2 sec/GigaVx,   45.6% of (t_Distance) (fast mode)
 <L1Distance>: scale:  5.0, binary=True;  t=   3.2 sec/GigaVx,   45.0% of (t_Distance) (fast mode)
 mode <LinfinityDistance> from <item: LinfinityDistance title:'Linfinity Distance' int:8>
 <LinfinityDistance>: scale:  1.0, binary=False;  t=   4.1 sec/GigaVx,   58.8% of (t_Distance)
 <LinfinityDistance>: scale: -1.0, binary=False;  t=   5.1 sec/GigaVx,   73.0% of (t_Distance)
 <LinfinityDistance>: scale:  0.1, binary=False;  t=   3.8 sec/GigaVx,   54.0% of (t_Distance)
 <LinfinityDistance>: scale:  5.0, binary=False;  t=   4.1 sec/GigaVx,   58.1% of (t_Distance)
 <LinfinityDistance>: scale:  5.0, binary=True;  t=   3.7 sec/GigaVx,   52.2% of (t_Distance)
 mode <LpDistance> from <item: LpDistance title:'Lp Distance' int:19>
 <LpDistance>: scale:  1.0, binary=False;  t=  91.4 sec/GigaVx,  1304.7% of (t_Distance) (slow mode)
 <LpDistance>: scale: -1.0, binary=False;  t=  91.8 sec/GigaVx,  1310.4% of (t_Distance) (slow mode)
 <LpDistance>: scale:  0.1, binary=False;  t=  91.7 sec/GigaVx,  1308.8% of (t_Distance) (slow mode)
 <LpDistance>: scale:  5.0, binary=False;  t=  91.3 sec/GigaVx,  1303.0% of (t_Distance) (slow mode)
 <LpDistance>: scale:  5.0, binary=True;  t=  90.7 sec/GigaVx,  1293.7% of (t_Distance) (slow mode)
 mode <EllipticDistance> from <item: EllipticDistance title:'Elliptic Distance' int:4>
 <EllipticDistance>: scale:  1.0, binary=False;  t= 116.7 sec/GigaVx,  1664.8% of (t_Distance) (slow mode)
 <EllipticDistance>: scale: -1.0, binary=False;  t= 115.7 sec/GigaVx,  1650.8% of (t_Distance) (slow mode)
 <EllipticDistance>: scale:  0.1, binary=False;  t= 115.7 sec/GigaVx,  1651.5% of (t_Distance) (slow mode)
 <EllipticDistance>: scale:  5.0, binary=False;  t= 116.8 sec/GigaVx,  1667.2% of (t_Distance) (slow mode)
 <EllipticDistance>: scale:  5.0, binary=True;  t= 114.8 sec/GigaVx,  1638.7% of (t_Distance) (slow mode)
 mode <DistToLine> from <item: DistToLine title:'Dist To Line' int:18>
 <DistToLine>: scale:  1.0, binary=False;  t=  89.7 sec/GigaVx,  1279.5% of (t_Distance) (slow mode)
 <DistToLine>: scale: -1.0, binary=False;  t=  89.5 sec/GigaVx,  1277.7% of (t_Distance) (slow mode)
 <DistToLine>: scale:  0.1, binary=False;  t=  88.6 sec/GigaVx,  1264.8% of (t_Distance) (slow mode)
 <DistToLine>: scale:  5.0, binary=False;  t=  93.1 sec/GigaVx,  1328.6% of (t_Distance) (slow mode)
 <DistToLine>: scale:  5.0, binary=True;  t=  88.1 sec/GigaVx,  1257.0% of (t_Distance) (slow mode)
 mode <NormalProjection> from <item: NormalProjection title:'Normal Projection' int:10>
 <NormalProjection>: scale:  1.0, binary=False;  t=  76.5 sec/GigaVx,  1091.9% of (t_Distance) (slow mode)
 <NormalProjection>: scale: -1.0, binary=False;  t=  77.1 sec/GigaVx,  1099.8% of (t_Distance) (slow mode)
 <NormalProjection>: scale:  0.1, binary=False;  t=  76.5 sec/GigaVx,  1090.9% of (t_Distance) (slow mode)
 <NormalProjection>: scale:  5.0, binary=False;  t=  76.7 sec/GigaVx,  1094.5% of (t_Distance) (slow mode)
 <NormalProjection>: scale:  5.0, binary=True;  t=  75.6 sec/GigaVx,  1079.3% of (t_Distance) (slow mode)
 mode <VoxelCoordinateNormalProjection> from <item: VoxelCoordinateNormalProjection title:'Voxel Coordinate Normal Projection' int:17>
 <VoxelCoordinateNormalProjection>: scale:  1.0, binary=False;  t=   3.4 sec/GigaVx,   48.2% of (t_Distance) (fast mode)
 <VoxelCoordinateNormalProjection>: scale: -1.0, binary=False;  t=   3.0 sec/GigaVx,   42.7% of (t_Distance) (fast mode)
 <VoxelCoordinateNormalProjection>: scale:  0.1, binary=False;  t=   4.6 sec/GigaVx,   65.5% of (t_Distance)
 <VoxelCoordinateNormalProjection>: scale:  5.0, binary=False;  t=   3.0 sec/GigaVx,   42.2% of (t_Distance) (fast mode)
 <VoxelCoordinateNormalProjection>: scale:  5.0, binary=True;  t=   3.1 sec/GigaVx,   43.9% of (t_Distance) (fast mode)
 mode <XDistance> from <item: XDistance title:'XDistance' int:11>
 <XDistance>: scale:  1.0, binary=False;  t=  70.8 sec/GigaVx,  1010.3% of (t_Distance) (slow mode)
 <XDistance>: scale: -1.0, binary=False;  t=  70.7 sec/GigaVx,  1008.2% of (t_Distance) (slow mode)
 <XDistance>: scale:  0.1, binary=False;  t=  70.7 sec/GigaVx,  1009.1% of (t_Distance) (slow mode)
 <XDistance>: scale:  5.0, binary=False;  t=  71.3 sec/GigaVx,  1017.9% of (t_Distance) (slow mode)
 <XDistance>: scale:  5.0, binary=True;  t=  70.3 sec/GigaVx,  1003.6% of (t_Distance) (slow mode)
 mode <YDistance> from <item: YDistance title:'YDistance' int:12>
 <YDistance>: scale:  1.0, binary=False;  t=  70.8 sec/GigaVx,  1009.6% of (t_Distance) (slow mode)
 <YDistance>: scale: -1.0, binary=False;  t=  71.8 sec/GigaVx,  1024.6% of (t_Distance) (slow mode)
 <YDistance>: scale:  0.1, binary=False;  t=  71.0 sec/GigaVx,  1013.7% of (t_Distance) (slow mode)
 <YDistance>: scale:  5.0, binary=False;  t=  71.7 sec/GigaVx,  1022.9% of (t_Distance) (slow mode)
 <YDistance>: scale:  5.0, binary=True;  t=  70.3 sec/GigaVx,  1003.5% of (t_Distance) (slow mode)
 mode <ZDistance> from <item: ZDistance title:'ZDistance' int:13>
 <ZDistance>: scale:  1.0, binary=False;  t=  71.1 sec/GigaVx,  1014.4% of (t_Distance) (slow mode)
 <ZDistance>: scale: -1.0, binary=False;  t=  72.6 sec/GigaVx,  1036.0% of (t_Distance) (slow mode)
 <ZDistance>: scale:  0.1, binary=False;  t=  71.5 sec/GigaVx,  1020.1% of (t_Distance) (slow mode)
 <ZDistance>: scale:  5.0, binary=False;  t=  71.4 sec/GigaVx,  1018.4% of (t_Distance) (slow mode)
 <ZDistance>: scale:  5.0, binary=True;  t=  69.8 sec/GigaVx,  996.4% of (t_Distance) (slow mode)
 mode <voxelXDistance> from <item: voxelXDistance title:'voxel XDistance' int:14>
 <voxelXDistance>: scale:  1.0, binary=False;  t=   3.3 sec/GigaVx,   46.5% of (t_Distance) (fast mode)
 <voxelXDistance>: scale: -1.0, binary=False;  t=   3.0 sec/GigaVx,   42.6% of (t_Distance) (fast mode)
 <voxelXDistance>: scale:  0.1, binary=False;  t=   4.5 sec/GigaVx,   64.0% of (t_Distance)
 <voxelXDistance>: scale:  5.0, binary=False;  t=   2.9 sec/GigaVx,   42.0% of (t_Distance) (fast mode)
 <voxelXDistance>: scale:  5.0, binary=True;  t=   3.0 sec/GigaVx,   42.6% of (t_Distance) (fast mode)
 mode <voxelYDistance> from <item: voxelYDistance title:'voxel YDistance' int:15>
 <voxelYDistance>: scale:  1.0, binary=False;  t=   2.4 sec/GigaVx,   34.5% of (t_Distance) (fast mode)
 <voxelYDistance>: scale: -1.0, binary=False;  t=   3.0 sec/GigaVx,   42.3% of (t_Distance) (fast mode)
 <voxelYDistance>: scale:  0.1, binary=False;  t=   2.5 sec/GigaVx,   35.1% of (t_Distance) (fast mode)
 <voxelYDistance>: scale:  5.0, binary=False;  t=   2.5 sec/GigaVx,   35.7% of (t_Distance) (fast mode)
 <voxelYDistance>: scale:  5.0, binary=True;  t=   2.8 sec/GigaVx,   40.1% of (t_Distance) (fast mode)
 mode <voxelZDistance> from <item: voxelZDistance title:'voxel ZDistance' int:16>
 <voxelZDistance>: scale:  1.0, binary=False;  t=   2.6 sec/GigaVx,   37.4% of (t_Distance) (fast mode)
 <voxelZDistance>: scale: -1.0, binary=False;  t=   2.3 sec/GigaVx,   33.4% of (t_Distance) (fast mode)
 <voxelZDistance>: scale:  0.1, binary=False;  t=   2.4 sec/GigaVx,   34.7% of (t_Distance) (fast mode)
 <voxelZDistance>: scale:  5.0, binary=False;  t=   2.8 sec/GigaVx,   40.2% of (t_Distance) (fast mode)
 <voxelZDistance>: scale:  5.0, binary=True;  t=   4.0 sec/GigaVx,   57.7% of (t_Distance)
 mode <VoxelCheckerBoard3D> from <item: VoxelCheckerBoard3D title:'Voxel Checker Board3D' int:20>
 <VoxelCheckerBoard3D>: scale:  1.0, binary=False;  t=   7.7 sec/GigaVx,  109.3% of (t_Distance)
 <VoxelCheckerBoard3D>: scale: -1.0, binary=False;  t=   8.0 sec/GigaVx,  114.5% of (t_Distance)
 <VoxelCheckerBoard3D>: scale:  0.1, binary=False;  t=   7.3 sec/GigaVx,  104.0% of (t_Distance)
 <VoxelCheckerBoard3D>: scale:  5.0, binary=False;  t=   7.6 sec/GigaVx,  109.1% of (t_Distance)
 <VoxelCheckerBoard3D>: scale:  5.0, binary=True;  t=   7.4 sec/GigaVx,  105.3% of (t_Distance)
 mode <VoxelCheckerBoardXY> from <item: VoxelCheckerBoardXY title:'Voxel Checker Board XY' int:21>
 <VoxelCheckerBoardXY>: scale:  1.0, binary=False;  t=   7.6 sec/GigaVx,  108.1% of (t_Distance)
 <VoxelCheckerBoardXY>: scale: -1.0, binary=False;  t=   7.5 sec/GigaVx,  106.7% of (t_Distance)
 <VoxelCheckerBoardXY>: scale:  0.1, binary=False;  t=   7.5 sec/GigaVx,  106.8% of (t_Distance)
 <VoxelCheckerBoardXY>: scale:  5.0, binary=False;  t=   7.2 sec/GigaVx,  102.3% of (t_Distance)
 <VoxelCheckerBoardXY>: scale:  5.0, binary=True;  t=   8.7 sec/GigaVx,  124.6% of (t_Distance)
 mode <VoxelCheckerBoardXZ> from <item: VoxelCheckerBoardXZ title:'Voxel Checker Board XZ' int:22>
 <VoxelCheckerBoardXZ>: scale:  1.0, binary=False;  t=   7.1 sec/GigaVx,  101.5% of (t_Distance)
 <VoxelCheckerBoardXZ>: scale: -1.0, binary=False;  t=   7.3 sec/GigaVx,  104.0% of (t_Distance)
 <VoxelCheckerBoardXZ>: scale:  0.1, binary=False;  t=   7.3 sec/GigaVx,  103.5% of (t_Distance)
 <VoxelCheckerBoardXZ>: scale:  5.0, binary=False;  t=   7.0 sec/GigaVx,   99.4% of (t_Distance)
 <VoxelCheckerBoardXZ>: scale:  5.0, binary=True;  t=   6.9 sec/GigaVx,   99.0% of (t_Distance)
 mode <VoxelCheckerBoardYZ> from <item: VoxelCheckerBoardYZ title:'Voxel Checker Board YZ' int:23>
 <VoxelCheckerBoardYZ>: scale:  1.0, binary=False;  t=   2.4 sec/GigaVx,   34.3% of (t_Distance) (fast mode)
 <VoxelCheckerBoardYZ>: scale: -1.0, binary=False;  t=   2.2 sec/GigaVx,   30.9% of (t_Distance) (fast mode)
 <VoxelCheckerBoardYZ>: scale:  0.1, binary=False;  t=   2.4 sec/GigaVx,   34.5% of (t_Distance) (fast mode)
 <VoxelCheckerBoardYZ>: scale:  5.0, binary=False;  t=   2.2 sec/GigaVx,   31.4% of (t_Distance) (fast mode)
 <VoxelCheckerBoardYZ>: scale:  5.0, binary=True;  t=   2.2 sec/GigaVx,   32.0% of (t_Distance) (fast mode)
 mode <VoxelCheckerBoardDiagXY> from <item: VoxelCheckerBoardDiagXY title:'Voxel Checker Board Diag XY' int:25>
 <VoxelCheckerBoardDiagXY>: scale:  1.0, binary=False;  t=  11.8 sec/GigaVx,  167.8% of (t_Distance)
 <VoxelCheckerBoardDiagXY>: scale: -1.0, binary=False;  t=  11.9 sec/GigaVx,  170.3% of (t_Distance)
 <VoxelCheckerBoardDiagXY>: scale:  0.1, binary=False;  t=  11.4 sec/GigaVx,  163.0% of (t_Distance)
 <VoxelCheckerBoardDiagXY>: scale:  5.0, binary=False;  t=  13.3 sec/GigaVx,  189.3% of (t_Distance)
 <VoxelCheckerBoardDiagXY>: scale:  5.0, binary=True;  t=  13.5 sec/GigaVx,  192.3% of (t_Distance)
 mode <VoxelCheckerBoardDiagXYZ> from <item: VoxelCheckerBoardDiagXYZ title:'Voxel Checker Board Diag XYZ' int:26>
 <VoxelCheckerBoardDiagXYZ>: scale:  1.0, binary=False;  t=  20.9 sec/GigaVx,  298.0% of (t_Distance)
 <VoxelCheckerBoardDiagXYZ>: scale: -1.0, binary=False;  t=  21.2 sec/GigaVx,  302.7% of (t_Distance) (slow mode)
 <VoxelCheckerBoardDiagXYZ>: scale:  0.1, binary=False;  t=  20.9 sec/GigaVx,  297.9% of (t_Distance)
 <VoxelCheckerBoardDiagXYZ>: scale:  5.0, binary=False;  t=  23.8 sec/GigaVx,  339.1% of (t_Distance) (slow mode)
 <VoxelCheckerBoardDiagXYZ>: scale:  5.0, binary=True;  t=  23.9 sec/GigaVx,  341.3% of (t_Distance) (slow mode)
 mode <Voxel2DSquaresXY> from <item: Voxel2DSquaresXY title:'Voxel2DSquares XY' int:24>
 <Voxel2DSquaresXY>: scale:  1.0, binary=False;  t=  12.0 sec/GigaVx,  171.8% of (t_Distance)
 <Voxel2DSquaresXY>: scale: -1.0, binary=False;  t=  12.2 sec/GigaVx,  173.6% of (t_Distance)
 <Voxel2DSquaresXY>: scale:  0.1, binary=False;  t=  12.3 sec/GigaVx,  175.8% of (t_Distance)
 <Voxel2DSquaresXY>: scale:  5.0, binary=False;  t=  12.4 sec/GigaVx,  177.4% of (t_Distance)
 <Voxel2DSquaresXY>: scale:  5.0, binary=True;  t=  12.4 sec/GigaVx,  176.4% of (t_Distance)
 mode <DodecaederDist> from <item: DodecaederDist title:'Dodecaeder Dist' int:27>
 <DodecaederDist>: scale:  1.0, binary=False;  t=  10.0 sec/GigaVx,  142.8% of (t_Distance)
 <DodecaederDist>: scale: -1.0, binary=False;  t=  10.2 sec/GigaVx,  146.2% of (t_Distance)
 <DodecaederDist>: scale:  0.1, binary=False;  t=  10.0 sec/GigaVx,  142.6% of (t_Distance)
 <DodecaederDist>: scale:  5.0, binary=False;  t=  10.0 sec/GigaVx,  142.4% of (t_Distance)
 <DodecaederDist>: scale:  5.0, binary=True;  t=   7.4 sec/GigaVx,  106.0% of (t_Distance)


(fast mode): a recomended mode (or binarized version of Distance) if speed matters

Note that some fast modes use voxel grid based implementation avoiding WorldVoxel transformations which might yield unexpected results for oblique data

(slow mode) : use with care or only on small data

(timing results were obtained Jun 2017 on a workstation notebook which was state of the art in 2015)

Windows

Default Panel

../../../Modules/ML/MLDistanceTransform/mhelp/Images/Screenshots/DistToPoint._default.png

Input Fields

input0

name: input0, type: Image

Image with reference geometry.

Output Fields

output0

name: output0, type: Image

Image with selected data type and same geometry as input with values depended on the selected mode and parameters.

Parameter Fields

Field Index

2. Point / Normal: Vector3 OutType: Enum
Add half voxel shift: Bool QuadScale: Float
Binarize: Bool Scale: Float
Lp Norm Order: Float Use center: Bool
Mask Value: Float  
Matrix: Matrix  
Mode: Enum  
Origin: Vector3  

Visible Fields

Origin

name: pos, type: Vector3, default: 0 0 0

Reference position / origin position of coordinate system used in computations.

2. Point / Normal

name: pos2, type: Vector3, default: 0 0 0

Optional 2nd point only used in dist to 2 points mode or normal direction in the modes requiring a direction.

Use center

name: useCenter, type: Bool, default: FALSE

Check this to use the volume center as reference position and set as value for the origin parameter.

Add half voxel shift

name: addHalfVoxelShift, type: Bool, default: FALSE

Add 0.5 to dim/2 as voxel coordinate of the center but only if dim > 1. Motivation: e.g. for defining filters for FFT filtering (c.f FFTBandPassFilter). Note: The stated center coordinate will be in world coordinates.

Binarize

name: binary, type: Bool, default: FALSE

Check this to get binary output (i.e. a mask with point were dist is less then scale). Binary modes were added as often this module was used in combination with a threshold to compute a neighborhood mask, which is now possible in one step.

Scale

name: distScale, type: Float, default: 1

Scaling factor in distance computations (c.f. mode). E.g. set to 1000 resp. 0.1 to use micrometers / cm instead of mm as unit.

QuadScale

name: quadrantScale, type: Float, default: 100

Scaling factor for quadrant labels. E.g. use 1000 to represent distances up to 999 mm and quadrant labels in a single image.

Quadscale is further uses as foreground value in the texture modes added in 2017 eg. VoxelCheckerBoardXY/XZ/YZ/3D.

Lp Norm Order

name: LpNormOrder, type: Float, default: 3

Used only when computing the Lp-Distance:

root(sum_i=XYZ (pos.i-ref.i)^p, p)

Which is a proper distance for p in [1-inf). Smaller values of P are admissible nevertheless

Mask Value

name: maskValue, type: Float, default: 1

In binary mode this value will be the fill value used for voxels with distance smaller than distScale resp. larger than -distScale in case discScale < 0.

Matrix

name: matrix, type: Matrix, default: 1 0 0 0, 0 1 0 0, 0 0 1 0, 0 0 0 1

Matrix used in elliptic distance only (c.f. mode). Useful e.g to define the distance to on of the axes or to a diagonal or some plane in the image volume.

OutType

name: outType, type: Enum, default: Int

Choose output data type (not dependent on input)

Values:

Title Name Description
Int Int Use int16 as output (CAVE: leads to quantization effects in typical images with voxel sizes in the order of 1 mm when scaling is 1).
Float Float Use float as output to avoid quantization effects.

Mode

name: mode, type: Enum, default: Distance

The following modes are available (let (x0,y0,z0) be the reference point):

Values:

Title Name Description
Distance Distance

Distance: For each voxel the euclidean distance to the reference point is computed:

scale * sqrt((x-x0)^2+(y-y0)^2+(z-z0)^2).
Quadrant Quadrant
Quadrant: The image is divided into eight quadrants by translating the coordinate
axes to the reference point. Each voxel of the output image contains the index (0..7) of its quadrant, multiplied with quadrantScale.
Dist And Quad DistAndQuad

DistAndQuad: The sum of the Distance and Quadrant results.

In binary mode a label image with labels quadScale*[0,8] is produced, where 8*quadScale is used in regions more than dist away from the reference position and the intersection of the octants with that sphere are filled with values as they would in the Quadrant mode.

This is intended to generate histograms in sections of a sphere cut in eight symmetric parts by canonical planes near some point and the stuff further away using JointHistogram.
Elliptic Distance EllipticDistance

For each voxel the elliptic distance to the reference point is computed using the given matrix M:

dist := scale * sqrt(abs( (x-x0,y-y0,z-z0) * M * (x-x0,y-y0,z-z0)^t))

If M is positive or negative definite, the iso-lines of the distance are ellipsoids.

Note that M is given as a 4x4 matrix (via a MatrixField) but the fourth row and column are ignored.
Dist To2Points DistTo2Points The (scaled) sum of two distances is used in order to compute elliptical masks from given focal points (possibly obsolete mode to be replaced by DistTo2PointsFloat). Internal computation is done in voxel coordinates which for lager volumes might be faster than the solution using voxel to world converstion for all points. Thus this mode is kept. It may have issues when the world matrix is not orthogonal (be careful e.g. with sheared CT data using non zero gantry tilt).
Dist To2Points Float DistTo2PointsFloat Alternative implementation using mapToWorld in the inner loop instead of direction dependent scaling factors to compensate for anisotropic geometry (probably more accurate / only correct mode in cases with non orthogonal world matrix but maybe slower).
L1Distance L1Distance Use L1 definition of distance to a point instead of euclidean distance. Note: Results are computed in physical units [mm] but for speed reasons along grid aligned with voxel coordinates. Results might be unexpected ( not the mathematical ones) for scans with oblique world coordinate systems.
Linfinity Distance LinfinityDistance Use L-infinity definition of distance to a point instead of euclidean distance.
Dist To2Points Minus Point Dist DistTo2PointsMinusPointDist See DistTo2Points mode but with distance of the points subtracted, to ensure minimum value is 0.
Normal Projection NormalProjection

normal projection mode: Values = direction*(pos-refPos)

with direction := (pos2 vector) / length(pos2 vector)
XDistance XDistance Distance along X direction in world coordinate system from first point.
YDistance YDistance Distance along Y direction in world coordinate system from first point.
ZDistance ZDistance Distance along Z direction in world coordinate system from first point.
Dist To Line DistToLine Distance from a line in direction of 2nd point / normal through the first point.
Lp Distance LpDistance

Computing the LpDistance:

root(sum_i=XYZ (pos.i-ref.i)^p, p)

Which is a proper distance for p in [1-inf). Smaller values of P are admissible nevertheless
voxel XDistance voxelXDistance Distance along X direction in voxel coordinate system from first point
voxel YDistance voxelYDistance Distance along Y direction in voxel coordinate system from first point
voxel ZDistance voxelZDistance Distance along Z direction in voxel coordinate system from first point
Voxel Coordinate Normal Projection VoxelCoordinateNormalProjection

Distance along a normal direction (stated in world coordinates) computed using a faster algorithm using only the voxel coordinate system from the first point (stated in world coordinates).:

val = (sign(scale) / normalLength) * (
    scaleX * (pxDbl - vPosX)*wPos2X
  + scaleY * (pyDbl - vPosY)*wPos2Y
  + scaleZ * (pzDbl - vPosZ)*wPos2Z )
scale_i := fabs(scale)*voxelSize[i]

Results ought to be identical to the NormalProjectionMode at least for images with world coordinates aligned with the voxel coordinates. Results are not tested to be precise for all sorts of oblique scans. Computation is substantially fast then the NormaProjection mode due to avoiding worldVoxel Coordinate transformations per position.
Voxel2DSquares XY Voxel2DSquaresXY Squared paper patterne in XY planes with scale in voxels defined by the Scale. Image values are 0 and QuadScale. A scale < 0 will invert the pattern.
Voxel Checker Board3D VoxelCheckerBoard3D Checkboard in 3D with cubes of scale in voxles given by Scale. Image values are 0 and QuadScale. A scale < 0 will invert the pattern.
Voxel Checker Board XY VoxelCheckerBoardXY Checkboard in XY planes with scale in voxels defined by the Scale.
Voxel Checker Board XZ VoxelCheckerBoardXZ Checkboard in XZ planes = vertical stripes in XY with scale in voxels defined by the Scale.
Voxel Checker Board YZ VoxelCheckerBoardYZ Checkboard in XZ planes = horizontal stripes in XY with scale in voxels defined by the Scale.
Voxel Checker Board Diag XY VoxelCheckerBoardDiagXY 45 deg. tilted checkboard in XY planes with scale in voxels defined by the Scale.
Voxel Checker Board Diag XYZ VoxelCheckerBoardDiagXYZ 3D texture with scale in voxels given by Scale. Image features a dense packing of regular octahedera and tetrahedera.
Distance Squared DistanceSquared  
Dodecaeder Dist DodecaederDist