Image-processing Library in C++

Chen Lujie July 2, 2012

Contents
1 Introduction 1.1 Features . . . . . 1.2 Source les . . . 1.3 Explicit template 1.4 Coding style . . . . . . . . . . . . . . . . . . . instantiation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 5 5 6 7 8 8 9 9 11 12 14 15 16 17 18 19 20 21 21 22 22 22 23 23 24 24 25 25 25 26 26 26 27 27 27 28 28 29 30

2 2D geometry classes and functions 2.1 CPt2D: 2D point class . . . . . . . . 2.2 CSize2D: 2D size class . . . . . . . . 2.3 CLine2D: 2D line segment class . . . 2.4 CRect: rectangle class . . . . . . . . 2.5 CRectRot: rotating rectangle class . 2.6 CFan: fan shape class . . . . . . . . 2.7 CCircle: circle class . . . . . . . . . . 2.8 CEllipse: ellipse class . . . . . . . . . 2.9 CPoly2D: 2D polygon class . . . . . 2.10 CLCSpl: a linear spline class . . . . 2.11 CNCSpl: a natural cubic spline class 2.12 Distance . . . . . . . . . . . . . . . . 2.13 Area2 . . . . . . . . . . . . . . . . . 2.14 Angle . . . . . . . . . . . . . . . . . 2.15 MidPoint . . . . . . . . . . . . . . . 2.16 Centroid . . . . . . . . . . . . . . . . 2.17 Intersect . . . . . . . . . . . . . . . . 2.18 CutLineInRect . . . . . . . . . . . . 2.19 BoundingRect . . . . . . . . . . . . . 2.20 PointInPolygon . . . . . . . . . . . . 2.21 ConvexHull . . . . . . . . . . . . . . 2.22 BoundingBox . . . . . . . . . . . . . 2.23 MinBoundingBox . . . . . . . . . . . 2.24 MinBoundingCircle . . . . . . . . . . 2.25 DelaunayTriangulation . . . . . . . . 2.26 FitLine . . . . . . . . . . . . . . . . 2.27 FitCircle . . . . . . . . . . . . . . . . 2.28 FitEllipse . . . . . . . . . . . . . . . 2.29 FitPolynomialCurve . . . . . . . . . 2.30 FitGauss . . . . . . . . . . . . . . . . 2.31 HoughLine . . . . . . . . . . . . . . 2.32 HoughCircle . . . . . . . . . . . . . . 2.33 GetLinePoints . . . . . . . . . . . . . 2.34 GetCirclePoints . . . . . . . . . . . .

3 2D image processing functions 3.1 ImgAssign . . . . . . . . . . . 3.2 ImgAssignBorder . . . . . . . 3.3 ImgCopy . . . . . . . . . . . . 3.4 ImgCopySubpixel . . . . . . . 3.5 ImgBlend . . . . . . . . . . . 3.6 ImgGradientX . . . . . . . . 3.7 ImgGradientY . . . . . . . . 3.8 ImgClamp . . . . . . . . . . . 3.9 ImgLinear . . . . . . . . . . . 3.10 ImgGamma . . . . . . . . . . 3.11 ImgMin . . . . . . . . . . . . 3.12 ImgMax . . . . . . . . . . . . 3.13 ImgMinMax . . . . . . . . . . 3.14 ImgMean . . . . . . . . . . . 3.15 ImgMedian . . . . . . . . . . 3.16 ImgVariance . . . . . . . . . . 3.17 ImgStdDev . . . . . . . . . . 3.18 ImgStatistics . . . . . . . . . 3.19 ImgFltMean . . . . . . . . . . 3.20 ImgFltMedian . . . . . . . . . 3.21 ImgFltVariance . . . . . . . . 3.22 ImgFltISEF . . . . . . . . . . 3.23 ImgConvX . . . . . . . . . . . 3.24 ImgConvY . . . . . . . . . . . 3.25 ImgConv . . . . . . . . . . . . 3.26 ImgResize . . . . . . . . . . . 3.27 ImgRotate . . . . . . . . . . . 3.28 ImgFlip . . . . . . . . . . . . 3.29 ImgFan . . . . . . . . . . . . 3.30 ImgRadial . . . . . . . . . . . 3.31 ImgMosaic . . . . . . . . . . . 3.32 ImgMatch . . . . . . . . . . . 3.33 ImgMatchSubpixel . . . . . . 3.34 ImgMotion . . . . . . . . . . 3.35 ImgDIC . . . . . . . . . . . . 3.36 ImgHistogram . . . . . . . . . 3.37 ImgHistoEqu . . . . . . . . . 3.38 ImgClampExtreme . . . . . . 3.39 ImgThre TwoPeak . . . . . . 3.40 ImgThre IterSel . . . . . . . . 3.41 ImgDilation . . . . . . . . . . 3.42 ImgErosion . . . . . . . . . . 3.43 ImgProjX . . . . . . . . . . . 3.44 ImgProjY . . . . . . . . . . . 3.45 ImgProjAny . . . . . . . . . . 3.46 ImgRadon . . . . . . . . . . . 3.47 ImgRadonVH . . . . . . . . . 3.48 ImgBackprojVH . . . . . . . 3.49 ImgIntegral . . . . . . . . . . 3.50 ImgLabeling . . . . . . . . . . 3.51 ImgFilling . . . . . . . . . . . 3.52 ImgThinning . . . . . . . . . 3.53 ImgCentroid . . . . . . . . . . 3.54 ImgBoundaryOrdered . . . . 3.55 ImgBoundaryUnordered . . . 3.56 ImgOuterCorners . . . . . . . 3.57 ImgConvexHull . . . . . . . . 3.58 ImgBoundingBox . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

31 31 31 32 32 32 32 33 33 33 34 34 35 35 35 35 35 35 35 36 36 37 37 37 38 38 39 39 40 40 41 42 42 43 43 44 45 46 46 46 47 47 47 48 48 48 49 49 50 50 51 51 52 52 53 53 53 54 54

3.59 3.60 3.61 3.62 3.63 3.64 3.65 3.66 3.67 3.68 3.69 3.70 3.71 3.72 3.73 3.74 3.75 3.76 3.77 3.78 3.79 3.80 3.81 3.82 3.83 3.84 3.85 3.86 3.87 3.88 3.89 3.90 3.91 3.92 3.93 3.94

ImgMinBoundingBox . . . ImgMinBoundingCircle . ImgMinBoundingPolygon ImgDistTrans . . . . . . . ImgWatershed . . . . . . ImgEdgeX . . . . . . . . . ImgEdgeY . . . . . . . . . ImgEdgeXSubpixel . . . . ImgEdgeYSubpixel . . . . ImgEdgeAny . . . . . . . ImgEdgeOnLine . . . . . ImgCannyEdge . . . . . . ImgShenCastanEdge . . . ImgFitPlane . . . . . . . . ImgFitPolynomialSurf . . ImgFitGauss . . . . . . . ImgFitImg . . . . . . . . . ImgLineData . . . . . . . ImgLineSum . . . . . . . ImgContour . . . . . . . . ImgMask . . . . . . . . . ImgMaskPolygon . . . . . ImgMandelbrot . . . . . . ImgPhaseShifting . . . . . ImgPhaseShifting Carre . ImgPhaseShifting 5Frame ImgPhaseUnw LToR . . . ImgPhaseUnw QualGui . ImgPhaseGradVar . . . . ImgFaceDetection . . . . . ImgSquareDetection . . . ImgBlackSquareGrid . . . ImgReadASCII . . . . . . ImgSaveASCII . . . . . . ImgReadRaw . . . . . . . ImgSaveRaw . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

54 55 55 55 55 56 57 57 57 57 58 59 59 59 60 60 61 61 61 61 62 62 63 63 64 64 65 65 65 66 66 66 67 68 68 68 69 69 69 70 71 72 73 73 74 74 74 75 75 75 75 75 75 76 76 77

4 3D geometry classes and functions 4.1 CPt3D: 3D point class . . . . . . . 4.2 CSize3D: 3D size class . . . . . . . 4.3 CLine3D: 3D line segment class . . 4.4 CCube: cube class . . . . . . . . . 4.5 CTri3D: 3D triangle class . . . . . 4.6 CPoly3D: 3D polygon class . . . . 4.7 CCylinder: cylinder class . . . . . 4.8 Distance . . . . . . . . . . . . . . . 4.9 Area . . . . . . . . . . . . . . . . . 4.10 Angle . . . . . . . . . . . . . . . . 4.11 MidPoint . . . . . . . . . . . . . . 4.12 Centroid . . . . . . . . . . . . . . . 4.13 Collinear . . . . . . . . . . . . . . . 4.14 NormalVector . . . . . . . . . . . . 4.15 Volume . . . . . . . . . . . . . . . 4.16 ConvexHull3D . . . . . . . . . . . 4.17 FitPlane . . . . . . . . . . . . . . . 4.18 FitPolynomialSurf . . . . . . . . . 4.19 FitGauss . . . . . . . . . . . . . . .

5 3D image processing functions 5.1 ImgAssign3D . . . . . . . . . 5.2 ImgCopy3D . . . . . . . . . . 5.3 ImgCopyXY 2D . . . . . . . 5.4 ImgCopyXZ 2D . . . . . . . . 5.5 ImgCopyYZ 2D . . . . . . . . 5.6 ImgCopy2D XY . . . . . . . 5.7 ImgCopy2D XZ . . . . . . . . 5.8 ImgCopy2D YZ . . . . . . . . 5.9 ImgLinear3D . . . . . . . . . 5.10 ImgMin3D . . . . . . . . . . . 5.11 ImgMax3D . . . . . . . . . . 5.12 ImgMinMax3D . . . . . . . . 5.13 ImgMean3D . . . . . . . . . . 5.14 ImgFltMean3D . . . . . . . . 5.15 ImgFltVariance3D . . . . . . 5.16 ImgConv3DZ . . . . . . . . . 5.17 ImgResize3D . . . . . . . . . 5.18 ImgRotate3D . . . . . . . . . 5.19 ImgFlip3D . . . . . . . . . . . 5.20 ImgMatch3D . . . . . . . . . 5.21 ImgMotion3D . . . . . . . . . 5.22 ImgLabeling3D . . . . . . . . 5.23 ImgFilling3D . . . . . . . . . 5.24 ImgDistTrans3D . . . . . . . 5.25 ImgWatershed3D . . . . . . . 5.26 ImgIsoSurface . . . . . . . . . 5.27 ImgReadRaw3D . . . . . . . 5.28 ImgSaveRaw3D . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

78 78 78 78 78 79 79 79 79 79 80 80 80 80 80 80 81 81 81 82 82 82 83 84 84 84 85 85 86

Introduction

C++, standard template library (STL), computer graphics, and image processing: each of the areas is a big topic by itself, while they are indeed interrelated. This note aims to explore the interrelationship and document an image processing library in C++. The note focuses on the input and output parameters of the library functions with some concise background information. Readers are encouraged to exam the source code where brief comments can be found explaining the implementation; however, code reading is not required for using the library. A complete package of the library les (*.h and *.cpp) may be requested from iiuugtt@gmail.com.

1.1

Features

There are a variety of image processing libraries available from the internet. The highlight of this library lies in the following features. Simplicity. The library does not rely on any particular image class so that you can keep your data structure unchanged. (Many image processing libraries dene their specic image class and data structure conversion is required, which may induce considerable processing overhead.) Flexibility. Based on C++ template mechanism, the library accepts all C++ build-in types as the image data, although certain functions are only valid to a subset of build-in types. If you have integer and oat image data to process, for example, all you need to do is to generate two explicit template instantiations of a library function. It is a standard C++ technique and will be discussed in detail in Section 1.3. Independency. Most of the image processing functions in the library are relatively independent. Combination of some functions may achieve sophisticated processing tasks. Portability. The library is written in ANSI C++. It can be compiled by many compilers, such as Visual Studio C++ and g++. Readability. Input and output of all functions are systemically organized. Following a few examples, you will be familiar with what to supply to a function and what can be expected from the output. Documentation is also attached in the source code, above each functions denition.

1.2

Source les

The source les of the library are listed in Table 1. To use the library, all .cpp les (ImgProc2D.cpp, ImgProc3D.cpp, Shape2D.cpp, Shape3D.cpp, Util.cpp, lubksb.cpp, ludcmp.cpp, pythag.cpp and svdcmp.cpp) should be compiled. Two header les ImgProc2D.h, and ImgProc3D.h should be included in whichever le that uses the library. The rest of the header les are included automatically in ImgProc2D.h, and ImgProc3D.h. It is important to know that the library classes and functions are dened in a CLJ namespace; and therefore after including ImgProc2D.h and / or ImgProc3D.h, you should write using namespace CLJ;. The following code shows an example. #include "PreCompiled.h" #if !USE_PRECOMPILED_HEADER #include <iostream> #include <vector> using namespace std; #endif #include "ImgProc2D.h" using namespace CLJ; int main() { int w = 256, h = 512; vector<float> vI2D1(w*h), vI2D2(w*h); ImgAssign(&vI2D1[0], w, h, CRect<int>(0,0,w,h), 50.f); ImgAssign(&vI2D2[0], w, h, CRect<int>(0,0,w,h), 100.f); cout<<"ImgAssign done.\n"; ImgCopy(&vI2D1[0], w, h, CRect<int>(20,20,w-10,h-10), &vI2D2[0], w, h, CRect<int>(10,10,w-20,h-20)); cout<<"ImgCopy done.\n";

return 0; } Main les ImgPro2D.cpp and .h ImgPro3D.cpp and .h Shape2D.cpp and .h Shape3D.cpp and .h Support les PreCompiled.h Util.cpp and .h nr.h nrtypes nr.h nrutil nr.h lubksb.cpp ludcmp.cpp pythag.cpp svdcmp.cpp Description 2D image processing functions 3D image processing functions 2D geometry classes and functions 3D geometry classes and functions Description precompiled header le utility functions source and header le header le of all Numerical Recipes functions data types dened in Numerical Recipes utilities of Numerical Recipes a Numerical Recipes function a Numerical Recipes function a Numerical Recipes function a Numerical Recipes function

Table 1: Source les of the library.

There is a header le, PreCompiled.h, included at the rst line of all .cpp les. It denes the ASSERT(...) macro used by the library for error reporting. If DEBUG is dened, ASSERT(...) macro is the same as the C++ library function assert(...); otherwise, it does nothing. In PreCompiled.h, some C++ library headers are conditionally included by #define USE_PRECOMPILED_HEADER 1 (use precompilation) or #define USE_PRECOMPILED_HEADER 0 (not use precompilation). If you use the precompilation feature of your C++ compiler, then make PreCompiled.h as the precompiled header of all your .cpp les. (Include PreCompiled.h at the rst line of all your .cpp les.) Create a new le called PreCompiled.cpp, which contains just one line of code. #include "PreCompiled.h" Make PreCompiled.cpp as the precompiled source le of your project. This procedure is standard to making use of precompilation, which should be obvious to people who are familiar with compiler settings. However, if you are confused, you may simply #define USE_PRECOMPILED_HEADER 0

1.3

Explicit template instantiation

An issue associated with using template functions and template classes is explicit template instantiation. Basically, if you want to use a template function or a template class in a particular data type (for example: oat), there should be an explicit template function or class instantiation of that type (oat). The librarys explicit template instantiation is put at the end of each cpp le, where you can nd some code like: // Code in Shape2D.cpp template class CPt2D<int>; template class CPt2D<float>; template class CRect<int>; template class CRect<float>; // Code in ImgProc2D.cpp template void ImgAssign<unsigned char> (unsigned char *pImg, int w, int h, const CRect<int> &rcROI, unsigned char value); template void ImgCopy<char, float> (const char *pSrc, int w1, int h1, const CRect<int> &rcROI1, float *pDst, int w2, int h2, const CRect<int> &rcROI2); template void ImgCopy<unsigned char, float> 6

(const unsigned char *pSrc, int w1, int h1, const CRect<int> &rcROI1, float *pDst, int w2, int h2, const CRect<int> &rcROI2); If you need a build-in data type of a specic class or function that has not been instantiated, you can add an instantiation following the above coding style; otherwise you will get compiler errors.

1.4

Coding style

Clear and easy-to-follow coding styles and naming conventions are used in the library. 1. A pointer variable is prexed by p. 2. A one- or two-letter prex, such as uc, c, n, and d, indicates the data type. 3. General purpose integer variables are usually dened as x, y, z, i, j et al. Example 1 (naming conventions) char *pcName = Mary; unsigned char ucRed = 24; int nCount; oat fRatio = 1.f; double dRadius = 30; Example 2 (loop through an image) int x, y, w = 100, h = 50; oat *pfImg = new oat[w*h]; for(y=0; y<h; ++y) for(x=0; x<w; ++x) pfImg[y*w+x] = 3.f;

2D geometry classes and functions

The coordinate system of the library (see Fig. 1) follows the most widely used convention in computer graphics. The origin (0,0) is located at the left-top corner of an image (or a window, or the computer screen). The positive X axis extends horizontally to the right and the positive Y axis extends vertically downward. An anticlockwise angle with respect to the X axis is dened as positive.
0 100 200 Y 0 100 200 X

Figure 1: Coordinate system of the image processing library.

2.1

CPt2D: 2D point class

template <class T> class CPt2D { public: T x, y; CPt2D<T>() : x(0), y(0) { } CPt2D<T>(const CPt2D<T> &pt) CPt2D<T>(T tx, T ty) CPt2D<T>& operator = (const CPt2D<T>& operator += (const CPt2D<T>& operator -= (const CPt2D<T> operator + (const CPt2D<T> operator - (const bool operator == (const bool operator != (const

: x(pt.x), y(pt.y) { } : x(tx), y(ty) { } CPt2D<T> &pt); CPt2D<T> &pt); CPt2D<T> &pt); CPt2D<T> &pt) const; CPt2D<T> &pt) const; CPt2D<T> &pt) const; CPt2D<T> &pt) const;

void SetPoint(T tx, T ty) { x = tx; y = ty; } void Rotate(const CPt2D<T> &ptRot, double dAngle); }; Variable x y Function operator = operator + = operator = operator + operator operator == operator != Function SetPoint Rotate Description x coordinate of the point y coordinate of the point Description Assignment operator *this = *this + pt *this = *this pt Return *this + pt Return *this pt Check if *this is equal to pt Check if *this is not equal to pt Description Set the x and y coordinates of the point Rotate the point with respect to a point

2.2

CSize2D: 2D size class

template <class T> class CSize2D { public: T cx, cy; CSize2D<T>() : cx(0), cy(0) { } CSize2D<T>(const CSize2D<T> &size) : cx(size.cx), cy(size.cy) { } CSize2D<T>(T tcx, T tcy) : cx(tcx), cy(tcy) { } CSize2D<T>& operator = (const CSize2D<T> &size); CSize2D<T>& operator += (const CSize2D<T> &size); CSize2D<T>& operator -= (const CSize2D<T> &size); CSize2D<T> operator + (const CSize2D<T> &size) const; CSize2D<T> operator - (const CSize2D<T> &size) const; bool operator == (const CSize2D<T> &size) const; bool operator != (const CSize2D<T> &size) const; void SetSize(T tcx, T tcy) { cx = tcx; cy = tcy; } }; Variable cx cy Function operator = operator + = operator = operator + operator operator == operator != Description size in x direction size in y direction Description Assignment operator *this = *this + size *this = *this size Return *this + size Return *this size Check if *this is equal to size Check if *this is not equal to size

2.3

CLine2D: 2D line segment class

template <class T> class CLine2D { public: CLine2D<T>() : m_ptStart(0,0), m_ptEnd(0,0) { } CLine2D<T>(const CLine2D<T> &line); CLine2D<T>(const CPt2D<T> &ptStart, const CPt2D<T> &ptEnd); CLine2D<T>(T x1, T y1, T x2, T y2); CLine2D<T>& operator = (const CLine2D<T> &line); bool operator == (const CLine2D<T> &line) const; bool operator != (const CLine2D<T> &line) const; CPt2D<T> CPt2D<T> CPt2D<T> CRect<T> double double void void void void void void void Start() const; End() const; Center() const; BoundingRect() const; Angle() const; Length() const; SetLine (T x1, T y1, T x2, T y2); SetLine (const CPt2D<T> &ptStart, const CPt2D<T> &ptEnd); SetStart (T x, T y); SetEnd (T x, T y); SetStart (const CPt2D<T> &pt); SetEnd (const CPt2D<T> &pt); SetCenter (const CPt2D<T> &pt);

void void void void void double double bool bool bool

SetAngle (const CPt2D<T> &ptRot, double dAngle); SetLength (double dLength, int nFix); Offset (T x, T y); Offset (const CPt2D<T> &ptOffset); Rotate (const CPt2D<T> &ptRot, double dAngle); DistToPt (double x, double y) const; DistToPt (const CPt2D<T> &pt) const; GetY (T x, T *pY) const; GetPointAt(double dDist, CPt2D<T> *ppt) const; LineEqu (double *pdA, double *pdB, double *pdC) const;

private: CPt2D<T> m_ptStart, m_ptEnd; // start and end point }; Function operator = operator == operator != Function Start End Center BoundingRect Angle Length SetLine SetStart SetEnd SetCenter SetAngle Description Assignment operator Check if *this is equal to line Check if *this is not equal to line Description Get the start point of the line Get the end point of the line Get the center of the line Get the bounding box of the line Get the angle formed by the line and the positive X axis Get the length of the line Set the start and the end points of the line Set the start point of the line Set the end point of the line Set the center of the line Set the angle of the line The line is rotated with respect to ptRot to the specied angle, formed by the line and the positive X axis. Oset the position of the line Rotate the line with respect to a point Get the distance from a point to the line If the line segment is a point (the start and end points are the same), return the distance from an input point to the lines end point. If the line segments start and end points are dierent, return the distance from an input point to the line, which is derived from the line segment. Set the length of the line. To modify the line length, one can x the start point, the end point, or the center. nFix species which point to x. The angle of the line is always xed. If the start point and the end point are the same, the line will be extended in the x direction only. the new length of the line, which should be >= 0. 0: the start point of the line is xed; 1: the center of the line is xed; 2: the end point of the line is xed. Given a points x coordinate on the line, get its corresponding y coordinate. input x coordinate output y coordinate true: y coordinate found; false: cannot nd y coordinate.

Oset Rotate DistToPt

SetLength

dLength nFix

GetY x pY Return

10

GetPointAt

dDist ppt Return LineEqu

Get a point on the line that has a specied distance from the star point. Take the start point as a reference, dDist > 0 indicates the point is at the same side as the end point; while dDist < 0 indicates the point is at the opposite side of the end point. the distance of the point from the start point. the point found true: point found; false: cannot nd such a point. Based on the line segment, retrieve a line equation in the form: A*x + B*y = C. This line equation encompasses all possible situations. Another choice is: cos(angle)*x + sin(angle)*y = R. However, it involves relatively slow trigonometric computation, so it is not used. parameter A of the line equation parameter B of the line equation parameter C of the line equation true: line function found; false: line function not exist.

pdA pdB pdC Return

0 100 200 Y

100

200

start point angle end point

Figure 2: An example of a 2D line segment.

2.4

CRect: rectangle class

template <class T> class CRect { public: T left, top, right, bottom; CRect<T>() : left(0), top(0), right(0), bottom(0) { } CRect<T>(const CRect<T> &rect); CRect<T>(const CPt2D<T> &ptLeftTop, const CSize2D<T> &size); CRect<T>(const CPt2D<T> &ptLeftTop, const CPt2D<T> &ptRightBottom); CRect<T>(T l, T t, T r, T b); CRect<T>& operator = (const CRect<T>& rect); CRect<T>& operator &= (const CRect<T>& rect); CRect<T>& operator |= (const CRect<T>& rect); CRect<T> operator & (const CRect<T>& rect) const; CRect<T> operator | (const CRect<T>& rect) const; bool operator == (const CRect<T>& rect) const; bool operator != (const CRect<T>& rect) const; bool IsEmpty(); T Width(); T Height(); CSize2D<T> Size(); CPt2D<T> Center(); CPt2D<T> LeftTop(); CPt2D<T> RightTop(); CPt2D<T> LeftBottom(); CPt2D<T> RightBottom(); void SetRect(T l, T t, T r, T b); 11

void void void void void void bool bool bool void };

Inflate(T l, T t, T r, Deflate(T l, T t, T r, Inflate(T x, T y); Deflate(T x, T y); Offset (T x, T y); Offset (const CPt2D<T> PtIn (T x, T y) PtIn (const CPt2D<T> RectIn (const CRect<T> Normalize();

T b); T b);

&pt); const; &pt) const; &rc) const;

Variable left top right bottom Function operator = operator &= operator |= operator & operator | operator == operator != Function IsEmpty Width Height Size Center LeftTop RightTop LeftBottom RightBottom Function SetRect Inate

Description left bound of the rectangle top bound of the rectangle right bound of the rectangle bottom bound of the rectangle Description Assignment operator *this = Intersect of two rectangles *this = Union of two rectangles Return intersect of two rectangles Return union of two rectangles Check if *this is equal to rect Check if *this is not equal to rect Description Check if it is an empty rectangle. A rectangle is empty if its width or height is <= 0. Get the width (right lef t) of the rectangle Get the height (bottom top) of the rectangle Get the size of the rectangle Return the center of the rectangle Return the left-top point of the rectangle Return the right-top point of the rectangle Return the left-bottom point of the rectangle Return the right-bottom point of the rectangle Description Set the left, top, right and bottom value of the rectangle Inate the rectangle by l, t, r, b on the left, top, right, and bottom sides respectively. Inate the rectangle by x on the left and right sides and by y on the top and bottom sides respectively. Deate the rectangle by l, t, r, b on the left, top, right, and bottom sides respectively. Deate the rectangle by x on the left and right sides and by y on the top and bottom sides respectively. Oset the position of the rectangle Check if a point is inside the rectangle. A point is side a rectangle, if pt.x [lef t, right) AND pt.y [top, bottom), Check if a rectangle is completely inside or on *this. Make sure the rectangle has positive width and height. If lef t > right, swap left and right. If top > bottom, swap top and bottom.

Deate

Oset PtIn RectIn Normalize

2.5

CRectRot: rotating rectangle class

template <class T> class CRectRot { 12

0 100

100

200 top

left 200 Y bottom

right

Figure 3: An example of a rectangle.

public: CRectRot<T>() : m_ptCenter(0,0), m_width(0), m_height(0), m_dAngle(0) { } CRectRot<T>(const CRectRot &rectRot); CRectRot<T>(T x, T y, T width, T height, double dAngle = 0); CRectRot<T>(const CPt2D<T> &ptCenter, T width, T height, double dAngle = 0); CRectRot<T>(const CPt2D<T> &ptCenter, CSize2D<T> size, double dAngle = 0); CRectRot<T>(const CRect<T> &rect, double dAngle = 0); CRectRot<T>& operator = (const CRectRot &rectRot); T T CPt2D<T> double void void void void void CRect<T> void void void void int int void private: CPt2D<T> T T double }; Width() const; Height() const; Center() const; Angle() const; SetWidth (T width); SetHeight(T height); SetAngle (double dAngle); SetCenter(const CPt2D<T> &ptCenter); Corner(CPt2D<T> ppt[4]) const; BoundingRect() const; Inflate(T w, T h); Deflate(T w, T h); Offset (T x, T y); Offset (const CPt2D<T> &ptOffset); PtIn (T x, T y); const; PtIn (const CPt2D<T> &pt) const; Rotate (const CPt2D<T> &ptRot, double dAngle);

m_ptCenter; m_width; m_height; m_dAngle;

// // // //

center of the width of the height of the anticlockwise

rectangle rectangle rectangle angle (radius) of the rectangle

Function operator = Width Height Center Angle SetWidth SetHeight SetCenter SetAngle Corner

Description Assignment operator Get the width of the rectangle Get the height of the rectangle Get the center of the rectangle Get the angle of the rectangle, anticlockwise in radius Set the width of the rectangle Set the height of the rectangle Set the center of the rectangle Set the angle of the rectangle, anticlockwise in radius Get 4 corner points of the rectangle continued on next page

13

BoundingRect Inate Deate Oset PtIn Rotate

Get the bounding box of the rectangle Increasing the width and height by w and h respectively. Decreasing the width and height by w and h respectively. Oset the position of the rectangle Check if a point is inside the rectangle Rotate the rectangle with respect to a point

0 100 200 Y

100

200
wi dth

angle

Figure 4: An example of a rotating rectangle.

t igh he

center

2.6

CFan: fan shape class

template <class T> class CFan { public: CFan<T>() : m_ptCenter(0,0), m_Radius(0), m_dFanAngle(0), m_dStartAngle(0) { } CFan<T>(const CFan &fan); CFan<T>(const CPt2D<T> &ptCenter, T radius, double dFanAngle, double dStartAngle); CFan<T>(T x, T y, T radius, double dFanAngle, double dStartAngle); CFan<T>& operator = (const CFan &fan); CPt2D<T> T double double CPt2D<T> CPt2D<T> void void void void void void CRect<T> void void int int void private: CPt2D<T> T double double }; Center() const; Radius() const; FanAngle() const; StartAngle() const; StartPoint() const; EndPoint() const; SetCenter(const CPt2D<T> &ptCenter); SetRadius(T radius); SetFanAngle (double dAngle); SetStartAngle(double dAngle); SetStartPoint(const CPt2D<T> &pt); SetEndPoint (const CPt2D<T> &pt); BoundingRect() const; Offset(T x, T y); Offset(const CPt2D<T> &ptOffset); PtIn (T x, T y); const; PtIn (const CPt2D<T> &pt) const; Rotate(const CPt2D<T> &ptRot, double dAngle);

m_ptCenter; m_Radius; m_dFanAngle; m_dStartAngle;

// // // //

center of the radius of the anticlockwise anticlockwise

fan fan angle (radius) of the fan start angle (radius)

14

Function operator = Center Radius FanAngle StartAngle StartPoint EndPoint SetCenter SetRadius SetFanAngle SetStartAngle SetStartPoint SetEndPoint BoundingRect Oset PtIn Rotate

Description Assignment operator Get the center of the fan, which is the center of the full circle. Get the radius of the fan Get the angle of the fan, anticlockwise in radius Get the start angle of the fan, anticlockwise in radius Get the start point of the fan Get the end point of the fan Set the center of the fan Set the radius of the fan Set the angle of the fan, anticlockwise in radius Set the start angle of the fan, anticlockwise in radius Set the start point of the fan Set the end point of the fan Get the bounding box of the fan Oset the position of the fan Check if a point is inside the fan Rotate the fan with respect to a point
0 100 end point
ra

0 100

200

X start point

fan angle start angle

di us

200 Y

center

Figure 5: An example of a fan.

2.7

CCircle: circle class

template <class T> class CCircle { public: CCircle<T>() : m_ptCenter(0,0), m_Radius(0) { } CCircle<T>(const CCircle<T> &circle); CCircle<T>(const CPt2D<T> &ptCenter, T radius) CCircle<T>(T x, T y, T radius) CCircle<T>& operator = (const CCircle<T> &circle); CPt2D<T> T void void CRect<T> void void int int void Center() const Radius() const SetCenter(const CPt2D<T> &pt) SetRadius(T radius) BoundingRect() const; Offset(T x, T y); Offset(const CPt2D<T> &ptOffset); PtIn (T x, T y) const; PtIn (const CPt2D<T> &pt) const; Rotate(const CPt2D<T> &ptRot, double dAngle);

private: CPt2D<T> m_ptCenter; // center of the circle T m_Radius; // radius of the circle };

15

Function operator = Center Radius SetCenter SetRadius BoundingRect Oset PtIn Rotate

Description Assignment operator Get the center of the circle Get the radius of the circle Set the center of the circle Set the radius of the circle Get the bounding box of the circle Oset the position of the circle Check if a point is inside the circle Rotate the circle with respect to a point
0 100 200 X

0 100 200 Y

radius

center

Figure 6: An example of a circle.

2.8

CEllipse: ellipse class

template <class T> class CEllipse { public: CEllipse<T>() : m_ptCenter(0,0), m_width(0), m_height(0), m_dAngle(0) { } CEllipse<T>(const CEllipse &ellipse); CEllipse<T>(T x, T y, T width, T height, double dAngle = 0); CEllipse<T>(const CPt2D<T> &ptCenter, T width, T height, double dAngle = 0); CEllipse<T>(const CPt2D<T> &ptCenter, CSize2D<T> size, double dAngle = 0); CEllipse<T>& operator = (const CEllipse &ellipse); T T CPt2D<T> double void void void void double CRect<T> void void int int void bool private: CPt2D<T> T T double }; Width() const; Height() const; Center() const; Angle() const; SetWidth (T width); SetHeight(T height); SetAngle (double dAngle); SetCenter(const CPt2D<T> &ptCenter); DistToFoci(const CPt2D<T> &pt) const; BoundingRect() const; Offset(T x, T y); Offset(const CPt2D<T> &ptOffset); PtIn (T x, T y); const; PtIn (const CPt2D<T> &pt) const; Rotate(const CPt2D<T> &ptRot, double dAngle); SetEqu(const double pdCoe[5]);

m_ptCenter; m_width; m_height; m_dAngle;

// // // //

center of the width of the height of the anticlockwise

ellipse ellipse ellipse angle (radius) of the ellipse

16

Function operator = Width Height Center Angle SetWidth SetHeight SetCenter SetAngle DistToFoci BoundingRect Oset PtIn Rotate SetEqu pdCoe Return

Description Assignment operator Get the width of the ellipse Get the height of the ellipse Get the center of the ellipse Get the angle of the ellipse, anticlockwise in radius Set the width of the ellipse Set the height of the ellipse Set the center of the ellipse Set the angle of the ellipse, anticlockwise in radius Get the distance of a point to the two foci of the ellipse Get the bounding box of the ellipse Oset the position of the ellipse Check if a point is inside the ellipse Rotate the ellipse with respect to a point Set the ellipse based on an equation Ellipse equation: Ax2 + Bxy + Cy 2 + Dx + Ey = 1 parameters, A, B, C, D and E, of the ellipse equation true: succeeded; false: the input equation is not an ellipse equation and no change is made.

0 100 200 Y

100

200
wi dth

angle

Figure 7: An example of an ellipse.

he igh t

center

2.9

CPoly2D: 2D polygon class

template <class T> class CPoly2D { public: CPoly2D<T>() { } CPoly2D<T>(const CPoly2D<T> &poly); CPoly2D<T>(const vector<CPt2D<T> > &vpt) CPoly2D<T>(int nCount, const CPt2D<T> &pt); CPoly2D<T>(const CPt2D<T> *ppt, int nCount) CPoly2D<T>& operator = (const CPoly2D<T> &poly); int int const CPt2D<T>& void void void void void void CPt2D<T> CRect<T> void Assign(const vector<CPt2D<T> > &vpt); Count() const; Vertex(int idx) const; AddVertex ( const CPt2D<T> &pt); SetVertex (int idx, const CPt2D<T> &pt); InsertVertex(int idx, const CPt2D<T> &pt); RemoveVertex(int idx); RemoveNearbyVertices(double dDist); Clear(); Center() const; BoundingRect() const; Offset(T x, T y);

17

void int int void

Offset(const CPt2D<T> &ptOffset); PtIn (T x, T y) const; PtIn (const CPt2D<T> &pt) const; Rotate(const CPt2D<T> &ptRot, double dAngle);

private: vector<CPt2D<T> > m_vpt; // vertices of the polygon }; Function operator = Count Vertex AddVertex SetVertex InsertVertex RemoveVertex RemoveNearbyVertices Clear Center BoundingRect Oset PtIn Rotate Description Assignment operator Get the number of vertices of the polygon Get the idx-th vertex of the polygon Add a vertex at the end of the vertex list Set the idx-th vertex value Insert a vertex at idx position of the vertex list Remove the idx-th vertex from the vertex list Remove vertices too close together, which makes sure that the length of each edge is >= dDist. Remove all vertices of the polygon Get the centroid of the polygon Get the bounding box of the polygon Oset the position of the polygon Check if a point is inside the polygon Rotate the polygon with respect to a point
0 100 v1 v6 200 Y v2 v3 v5 v4 200 v0 X

0 100

Figure 8: An example of a polygon.

2.10

CLCSpl: a linear spline class

template <class T> class CLSpl { public: CLSpl<T>() { } CLSpl<T>(const CLSpl<T> &lspl); CLSpl<T>(const vector<CPt2D<T> > &vpt); CLSpl<T>(const CPt2D<T> *ppt, int nCount); CLSpl<T>& operator = (const CLSpl<T> &lspl); int const CPt2D<T>& void void void void void CPt2D<T> CPt2D<T> void Count() const; Knot(int idx) const; AddKnot ( const CPt2D<T> &pt); SetKnot (int idx, const CPt2D<T> &pt); InsertKnot(int idx, const CPt2D<T> &pt); RemoveKnot(int idx); Clear(); Center() const; BoundingRect() const; Offset(T x, T y); 18

void void

Offset(const CPt2D<T> &ptOffset); Rotate(const CPt2D<T> &ptRot, double dAngle);

private: vector<CPt2D<T> > m_vpt; // knots of the spline }; Function operator = Count Knot AddKnot SetKnot RemoveKnot Clear Center Oset Rotate Description Assignment operator Get the number of knots of the spline Get the idx-th knot of the spline Add a knot to the knot list Set the idx-th knot value Remove the idx-th knot from the knot list Remove all knots of the spline Get the centroid of all knots Oset the position of all knots Rotate the spline with respect to a point

0 100 200 Y

100 k0 k4

200 k1 k5 k2 k3

Figure 9: An example of a linear spline.

2.11

CNCSpl: a natural cubic spline class

template <class T> class CNCSpl { public: CNCSpl<T>() { } CNCSpl<T>(const CNCSpl<T> &ncspl); CNCSpl<T>& operator = (const CNCSpl<T> &ncspl); int CPt2D<T> void void void void void CPt2D<T> void void void bool }; Count() const; Knot(int idx) const; AddKnot ( const CPt2D<T> &pt); SetKnot (int idx, const CPt2D<T> &pt); InsertKnot(int idx, const CPt2D<T> &pt); RemoveKnot(int idx); Clear(); Center() const; Offset(T x, T y); Offset(const CPt2D<T> &ptOffset); Rotate(const CPt2D<T> &ptRot, double dAngle); GetPointAt(int nSec, double dFra, CPt2D<T> *ppt) const; Description Assignment operator Get the number of knots of the spline continued on next page

Function operator = Count

19

Knot AddKnot SetKnot RemoveKnot Clear Center Oset Rotate GetPointAt nSec dFra

Get the idx-th knot of the spline Add a knot to the knot list Set the idx-th knot value Remove the idx-th knot from the knot list Remove all knots of the spline Get the centroid of all knots Oset the position of all knots Rotate the spline with respect to a point Get a point at a specied place on the spline the index of the section of the spline For example: i is the section between knot i and knot i+1. fractional distance [0, 1] from the point to the start point of the section in x direction. For example: assume i-th section is chosen; fFraction = 0, returns the start point (x[i], y[i]). fFraction = 1, returns the end point (x[i+1], y[i+1]). fFraction = 0.3, returns the point (0.7*x[i]+0.3*x[i+1], y). y is calculated from the spline. dFra can also be set < 0 or > 1. In these cases, the points x coordinate is < x[i] or > x[i+1]. stores output point if found true: point found; false: spline is not valid or nSec out of range, in that case ppt is unchanged.
0 k0 100 k1 k5 200 Y k4 k3 200 k6 k7 k2 X

ppt Return

0 100

Figure 10: An example of a natural cubic spline.

2.12

Distance

template <class T> double Distance (const CPt2D<T> &pt1, const CPt2D<T> &pt2); Description pt1 pt2 Return Get the distance between two points 1st input point 2nd input point the distance between the two points
0 100 200 X

0 100 200 Y

distan
pt1

ce
pt2

Figure 11: An example of the Distance function. Distance between two points. template <class T> double Distance (const CPt2D<T> &pt, double dA, double dB, double dC); 20

Description pt dA, dB, dC Return

Get the distance between a point and a line The line equation is A*x + B*y = C. input point parameters of the line the distance between the point and the line
0 0 line pt 200 Y
dista nce

100

200

100

Figure 12: An example of the Distance function. Distance between a point and a line.

2.13

Area2

template <class T> double Area2 (const CPt2D<T> &pt1, const CPt2D<T> &pt2, const CPt2D<T> &pt3); Description pt1 pt2 pt3 Return Get twice the area enclosed by three points 1st input point 2nd input point 3rd input point twice the area enclosed by three points Use double type to prevent overow. area > 0 indicates pt1, pt2, pt3 are clockwise. area < 0 indicates pt1, pt2, pt3 are anticlockwise. area = 0 indicates three points are on the same line.
0 100 200 pt2 100 pt3 200 Y pt1 200 Y pt3 100 pt1 X 0 100 200 pt2 X

(a)

(b)

Figure 13: An example of the Area2 function. (a) Positive area. (b) Negative area.

2.14

Angle

template <class T> double Angle (const CPt2D<T> &pt1, const CPt2D<T> &pt2, const CPt2D<T> &pt3); Description pt1 pt2 pt3 Return Get the angle in (, ], formed by pt2, pt1, pt3 1st input point (vertex of the angle) 2nd input point 3rd input point the angle formed by pt2, pt1, pt3 angle > 0 indicates pt1, pt2, pt3 are clockwise. angle < 0 indicates pt1, pt2, pt3 are anticlockwise. angle = 0 or indicates three points are on the same line.

21

0 100

100

200 pt3

0 100 pt1

100

200 pt2

pt1 200 Y pt3

200 Y pt2

(a)

(b)

Figure 14: An example of the Angle function. (a) Positive angle. (b) Negative angle.

2.15

MidPoint

template <class T> CPt2D<T> MidPoint (const CPt2D<T> &pt1, const CPt2D<T> &pt2); Description pt1 pt2 Return Get the midpoint of two points 1st input point 2nd input point the midpoint

2.16

Centroid

template <class T> CPt2D<T> Centroid (const CPt2D<T> *ppt, int nCount); Description ppt nCount Return Get the centroid of a set of points an array of points the number of points the centroid of the input points

2.17

Intersect

template <class T> bool Intersect (const CLine2D<T> &line1, const CLine2D<T> &line2, CPt2D<double> *ppt); Description line1 line2 ppt Return Get the intersect of two line segments 1st input line segment 2nd input line segment store point of intersection, if found; otherwise, its value is unchanged. true: intersect found; false: no intersect.

bool Intersect (double dA1, double dB1, double dC1, (double dA2, double dB2, double dC2, CPt2D<double> *ppt); Description dA1, dB1, dC1 dA2, dB2, dC2 ppt Return Get the intersect of two lines Line equation: A*x + B*y = C parameters of the 1st input line parameters of the 2nd input line store point of intersection, if found; otherwise, its value is unchanged. true: intersect found; false: no intersect.

template <class T> bool Intersect (const CLine2D<T> &line1, double dA2, double dB2, double dC2, CPt2D<double> *ppt);

22

Description line1 dA2, dB2, dC2 ppt Return

0

Get the intersect of a line segment with a line Line equation: A*x + B*y = C the line segment parameters of the line store point of intersection of two lines, if found. One of the line is derived from the line segment. If return true, the point is also on the line segment. true: intersect found; false: no intersect.
100 200 X 0 100 200 X

0 100 200 Y

0 100 200 Y

(a)

(b)

Figure 15: An example of the Intersect function. (a) Two line segments intersect. (b) Two line segments do not intersect.

2.18

CutLineInRect

template <class T> bool CutLineInRect (const CRect<T> &rect, double dA, double dB, double dC, CLine2D<T> *pLine); Description Cut a line within a rectangle A line is cut to t inside a rect, which means a points x is within [left, right] and y within [top, bottom]. If you do not want to include the right and bottom borders, you may use the integer version of the function. rectangle to intersect with the line line equation: A*x + B*y = C return the cut line if it exists; otherwise its value is unchanged. true: the line is cut in the rect; false: the line does not intersect with the rect.

rect dA, dB, dC pLine Return

bool CutLineInRect(const CRect<int> &rect, CLine2D<int> *pLine); Description Cut a line segment within a rectangle A line segment is cut to t inside a rect, which means a points x is within [left, right) and y within [top, bottom). Note that the right and bottom border are not inside. rectangle to intersect with the line segment the line segment to be cut. It also returns the cut line if it exists; otherwise its value is unchanged. true: the line segment is cut or is already in the rect; false: the line segment is outside the rect and no intersect.

rect pLine Return

2.19

BoundingRect

template <class T> CRect<T> BoundingRect (const CPt2D<T> *pptVtx, int nCount);

23

0 100 200 Y

100

200

0 100 200 Y

100

200

(a)

(b)

Figure 16: An example of the CutLineInRect function. (a) Before applying CutLineInRect(...). (b) After applying CutLineInRect(...).

Description ppt nCount Return

Note

Get the bounding rectangle of a set of points an array of points the number of points The bounding rectangle, whose left and right equal to the min and max x coordinates of the points; and top and bottom equal to the min and max y coordinates of the points. Right and bottom of bounding rect is equal but not larger than the max of x or y coordinates.

2.20

PointInPolygon

template <class T> int PointInPolygon (const CPt2D<T> *ppt, int nCount, T x, T y); Description Check if a point is inside, on, or outside a polygon. Reference: Computational geometry in C 7.4, Joseph ORourke. Ray-crossing algorithm. (Winding number algo is slower.) polygon vertices the number of vertices point to be tested 0: outside, 1: strictly inside, 2: on one of the edges but not on a vertex, 3: on one of the vertices.
0 100 pt1 100 pt2 200 Y pt3 200 X pt4

ppt nCount x, y Return

Figure 17: An example of the PointInPolygon function. pt1 is outside the polygon; pt2 is strictly inside; pt3 is on one of the edges but not on a vertex; pt4 is on one of the vertices.

2.21

ConvexHull

template <class T> int ConvexHull (const vector<CPt2D<T> > &vPos, vector<int> *pvIdx);

24

Description Precondition vPos pvIdx Return

Get convex hull points index see ConvexHull(vector<CPt2D<T> >*, vector<CPt2D<T> >*) input point set indices of convex hull points in vPos (clockwise order) the number of convex hull points

template <class T> int ConvexHull (vector<CPt2D<T> > *pvPos, vector<CPt2D<T> > *pvCH); Description Get the convex hull points in clockwise order Reference Computational geometry in C by Joseph ORourke. The rst point of vPos must be the topmost of all points, meaning that it has the smallest y coordinate. If there are more than one topmost points, the rst point should be the leftmost of them, with the smallest x coordinate. input points (the array will be modied) a vector pointer that stores the found convex hull points the number of convex hull points

pvPos pvCH Return

2.22

BoundingBox

template <class T> bool BoundingBox (const vector<CPt2D<T> > &vPos, double dAngle, CPt2D<double> *pptCenter, CSize2D<double> *pSize); Description vPos dAngle pptCenter pSize Return Get the xed-angle bounding box of a set of points input object points angle of the bounding box (radius, anticlockwise) center of the box size of the box true: succeeded; false: failed.

2.23

MinBoundingBox

template <class T> bool MinBoundingBox (const vector<CPt2D<T> > *pvPos, CPt2D<double> *pptCenter, CSize2D<double> *pSize, double *pdAngle); Description Get the min bounding box of a set of points MinBoundingBox function is based on the rotating caliper algorithm. The output angle is anticlockwise; while some internal angles are clockwise. Since ConvexHull(...) outputs points in clockwise order, it is convenient to use clockwise angle internally. see ConvexHull(vector<CPt2D<T> >*, vector<CPt2D<T> >*) input points (the array will be modied) center of the box size of the box angle of the box (radius, anticlockwise) true: succeeded; false: failed.

Precondition pvPos pptCenter pSize pdAngle Return

2.24

MinBoundingCircle

template <class T> bool MinBoundingCircle (const vector<CPt2D<T> > *pvPos, CPt2D<double> *pptCenter, double *pdRadius); Description 1 2 Get the min bounding circle of a set of points Call the convex hull of the set of points H. Pick any side of H, say S. For each vertex of H other than those of S, compute the angle subtended by S. The minimum such angle, , occurs at vertex v. If 90 deg, done! (The circle is the diametric circle of S.) If < 90 deg, check the remaining vertices of the triangle formed by S and v. continued on next page

25

Precondition pvPos pptCenter pdRadius Return

If no vertices are obtuse, done! (The circle is determined by the vertices of S and the vertex v.) If one of the other angles of the triangle formed by S and v is obtuse, then set S to be the side opposite the obtuse angle and go to step 2. (The new S may not be a side on the convex hull.) see ConvexHull(vector<CPt2D<T> >*, vector<CPt2D<T> >*) input points (the array will be modied) center of the circle radius of the circle true: succeeded; false: failed.

2.25

DelaunayTriangulation

template <class T> int DelaunayTriangulation (const vector<CPt2D<T> > &vPos, vector<CLine2D<T> > *pvLine, vector<CPoly2D<T> > *pvPoly); Description Get the Delaunay triangulation of a set of points Reference Computational geometry in C by Joseph ORourke. Delaunay triangulation in 2D is based on convex hull in 3D. input point set edges of Delaunay triangles (input 0 to ignore) Delaunay triangles (input 0 to ignore). Each polygon contains only 3 vertices. the number of triangles

vPos pvLine pvPoly Return

(a)

(b)

(c)

(d)

(e)

Figure 18: Examples of the ConvexHull, BoundingBox, MinBoundingBox, MinBoundingCircle and DelaunayTriangulation functions. (a) Convex hull. (b) Bounding box at a xed angle of 15 deg. (c) Minimum-area bounding box. (d) Minimum-area bounding circle. (e) Delaunay triangulation.

2.26

FitLine

template <class T> bool FitLine (const CPt2D<T> *ppt, int nCount, double *pdKx, double *pdY0); Description Least squares tting of a line Line equation: y = kx x + y0 . Fitting is based on the y-direction error, not the perpendicular distance error. points to be tted (size must be nCount) size of ppt array parameter kx of the line equation parameter y0 of the line equation true: succeeded; false: failed.

ppt nCount pdKx pdY0 Return

2.27

FitCircle

template <class T> bool FitCircle (const CPt2D<T> *ppt, int nCount, CPt2D<double> *pptCenter, double *pdRadius);

26

Description

ppt nCount pptCenter pdRadius Return

Least squares tting of a circle Circle equation: (x a)2 + (y b)2 = R2 Internally t the modied equation: Ax + By + C = x2 + y 2 If a tted circle is found, circle parameters are stored in pptCenter, pdRadius; otherwise they are unchanged. points to be tted (size must be nCount) size of ppt array pointer to the center of the circle pointer to the radius of the circle true: succeeded; false: failed.

2.28

FitEllipse

template <class T> bool FitEllipse (const CPt2D<T> *ppt, int nCount, double pdCoe[5]); Description ppt nCount pdCoe Return Least squares tting of an ellipse Ellipse equation: Ax2 + Bxy + Cy 2 + Dx + Ey = 1 points to be tted (size must be nCount) size of ppt array coecients, A, B, C, D and E, of the ellipse equation true: succeeded; false: failed.

2.29

FitPolynomialCurve

template <class T> bool FitPolynomialCurve (const CPt2D<T> *ppt, int nCount, vector<double> *pvCoe, int N); Description Least squares tting of a polynomial curve Polynomial curve equation: y = C[0] + coe[1] x + C[2] x2 + ... + C[N ] xN points to be tted (size must be nCount) size of ppt array stored coecients. If succeed, its size is N+1. the order of the curve equation (should be >= 0) true: succeeded; false: failed.
400

ppt nCount pvCoe N Return

200

Input points 2nd order curve 3rd order curve 4th order curve 5th order curve

Y
-200 0 10 20 30 40 50 60 70 80 90 100

Figure 19: An example of the FitPolynomialCurve function.

2.30

FitGauss

template <class T> bool FitGuass (const CPt2D<T> *ppt, int nCount, double *pdA, double *pdB, double *pdC);

27

Description

ppt nCount pdA pdB pdC Return

Least squares tting of a Gaussian function 2 Gaussian function: y = Ae(xB) /(2C) . Fitting is based on a linear least squares method: the y coordinate of all points is converted to ln(y), which requires that y > 0. points to be tted (size must be nCount) size of ppt array parameter A of the Gaussian equation parameter B of the Gaussian equation parameter C of the Gaussian equation true: succeeded; false: failed.

40

Input points FitGauss

Y
20 0

20

40

60

80

100

Figure 20: An example of the FitGauss function.

2.31

HoughLine

template <class T> int HoughLine (const CPt2D<T> *ppt, int nCount, double dRMin, double dRMax, int nRSec, double dAngleMin, double dAngleMax, int nAngleSec, double *pdR, double *pdAngle); Description Hough transform line detection Detect one line with maximum hough parameter. Line equation: R = x*cos(angle) + y*sin(angle) Resolution of R is (dRMax-dRMin)/nRSec. Resolution of angle is (dAngleMax-dAngleMin)/nAngleSec. points to be analyzed (size must be nCount) size of ppt array minimum boundary of R [dRMin, dRMax) maximum boundary of R [dRMin, dRMax) the number of sections in [dRMin, dRMax) minimum boundary of angle [dAngleMin, dAngleMax) maximum boundary of angle [dAngleMin, dAngleMax) the number of sections in [dAngleMin, dAngleMax) found R of the line equation found angle (in radius) of the line equation 0: line not found; >0 line found (return the number of points on the line).

ppt nCount dRMin dRMax nRSec dAngleMin dAngleMax nAngleSec pdR pdAngle Return

2.32

HoughCircle

template <class T> int HoughCircle (const CPt2D<T> *ppt, int nCount, double dXMin, double dXMax, int nXSec, double dYMin, double dYMax, int nYSec, double dRMin, double dRMax, int nRSec, CPt2D<double> *pptCenter, double *pdR); 28

Description

ppt nCount dXMin dXMax dYMin dYMax dRMin dRMax nXSec nYSec nRSec pptCenter pdR Return

Hough transform circle detection Detect one circle with maximum hough parameter. Circle equation: R = (x x0)2 + (y y0)2 Resolution of center x is (dXMax-dXMin)/nXSec. Resolution of center y is (dYMax-dYMin)/nYSec. Resolution of radius is (dRMax-dRMin)/nRSec. points to be analyzed (size must be nCount) size of ppt array minimum boundary of the circle center x coordinate maximum boundary of the circle center x coordinate minimum boundary of the circle center y coordinate maximum boundary of the circle center y coordinate minimum boundary of R [dRMin, dRMax) maximum boundary of R [dRMin, dRMax) the number of sections in [dXMin, dXMax) the number of sections in [dYMin, dYMax) the number of sections in [dRMin, dRMax) found circle center found circle radius 0: circle not found; >0 circle found (return the number of points on the circle).

60 50 40 Input points FitCircle HoughCircle

0 0

Input points FitLine HoughLine 20 40 60 80 100

Y
20 0

20

40

60

80

100

(a)

(b)

Figure 21: Examples of the FitLine, HoughLine, FitCircle and HoughCircle functions. (a) FitLine and HoughLine. (b) FitCircle and HoughCircle.

2.33

GetLinePoints

int GetLinePoints (const CRect<int> &rcROI, const CPt2D<int> &ptStart, const CPt2D<int> &ptEnd, vector<CPt2D<int> > *pvPos); Description rcROI ptStart ptEnd pvPos Return Get points on a line within a bounding rect bounding rect (only get points inside the rect) start point of the line end point of the line store points on the line the number of pixels on the line

int GetLinePoints (const CPt2D<int> &ptStart, const CPt2D<int> &ptEnd, vector<CPt2D<int> > *pvPos); Description ptStart ptEnd pvPos Return Bresenhams line algorithm start point of the line end point of the line store points on the line the number of pixels on the line 29

2.34

GetCirclePoints

int GetCirclePoints (const CPt2D<int> &ptCenter, int nRadius, vector<CPt2D<int> > *pvPos); Description ptCenter nRadius pvPos Return Bresenhams circle algorithm center of the circle radius of the circle store points on the circle the number of pixels on the circle

30

2D image processing functions

Type T* Name pImg Description Pointer to a continuous memory space which must be equal to or larger than w*h*sizeof(T) bytes. The y-th row, x-th column element can be retrieved by *(pImg+y*w+x) or pImg[y*w+x]. Pointer to the source image Pointer to the destination image Image width and height Region of interest. Only image data within the ROI will be used or modied. Pixels whose value==ObjID are treated as object points; otherwise background.

Some parameters are common to most functions. They are listed in Table 2.

T* T* int CRect<int>& T

pSrc pDst w, h rcROI ObjID

Table 2: Common parameters of 2D image processing functions.

3.1

ImgAssign

template <class T> void ImgAssign (T *pImg, int w, int h, const CRect<int> &rcROI, T value); Description Parameters value Assign image data in an ROI to the input value See Table 2 for common parameters the value to be assigned to the image data

3.2

ImgAssignBorder

template <class T> void ImgAssignBorder (T *pImg, int w, int h, const CRect<int> &rcROI, T value, int nLeft, int nTop, int nRight, int nBottom); Description Assign image data on the border of an ROI to the input value Pixels within the distance are assigned to the input value. The modied region is a rectangular ring. See Table 2 for common parameters distance toward the center on the left border distance toward the center on the top border distance toward the center on the right border distance toward the center on the bottom border

Parameters nLeft nTop nRight nBottom

ROI

ROI

(a)

(b)

(c)

Figure 22: Examples of the ImgAssign and ImgAssignBorder functions. (a) Original image. (b) The ROI is assigned with value 220. (c) The border of the ROI is assigned with value 220. Left border: 7 pixels, top: 10 pixels, right: 5 pixels, bottom: 3 pixels.

31

3.3

ImgCopy

template <class T1, class T2> void ImgCopy (const T1 *pSrc, int w1, int h1, const CRect<int> &rcROI1, T2 *pDst, int w2, int h2, const CRect<int> &rcROI2); Description Parameters Copy image data from source image ROI1 to destination image ROI2 Width and height of ROI1 and ROI2 must be the same. See Table 2 for common parameters

ROI1 ROI2

(a)

(b)

(c)

Figure 23: An example of the ImgCopy function. (a) Source image ROI1 is copied to (b) destination image ROI2. (c) Resultant image after ImgCopy.

3.4

ImgCopySubpixel

template <class T1, class T2> void ImgCopySubpixel (const T1 *pSrc, int w1, int h1, const CRect<int> &rcROI1, T2 *pDst, int w2, int h2, const CRect<int> &rcROI2, const CPt2D<float> &ptOffset); Description Copy image data at subpixel accuracy Copy image ROI1 oset by ptOset to ROI2. Each subpixel in ROI1 is linearly interpolated from interger pixels. Width and height of ROI1 and ROI2 must be the same. See Table 2 for common parameters subpixel oset of ROI1

Parameters ptOset

3.5

ImgBlend

template <class T1, class T2> void ImgBlend (const T1 *pImg1, int w1, int h1, const CRect<int> &rcROI1, T2 *pImg2, int w2, int h2, const CRect<int> &rcROI2, double dCoe1, double dCoe2); Description Parameters dCoe1 dCoe2 Blend img1 into img2 Blending equation: img2 = dCoe1*img1 + dCoe2*img2. See Table 2 for common parameters coecient multiplied to each pixel in ROI1 coecient multiplied to each pixel in ROI2

3.6

ImgGradientX

template <class T1, class T2> void ImgGradientX (const T1 *pSrc, int w1, int h1, const CRect<int> &rcROI1, T2 *pDst, int w2, int h2, const CRect<int> &rcROI2, int nGradLen);

32

am S
(a) Description

le p
(b) (c)

Figure 24: An example of the ImgBlend function. (a) Image 1. (b) Image 2. (c) The resultant image of blending image 1 into image 2.

Parameters nGradLen

1D gradient in the x direction Take the image data gradient in the x direction. If the gradient length is 2, the x gradient pDst[x] = pSrc[x+1] - pSrc[x-1], meaning the gap between the two pixels used to calculate a gradient point is 2. See Table 2 for common parameters length of the gradient operator

3.7

ImgGradientY

template <class T1, class T2> void ImgGradientY (const T1 *pSrc, int w1, int h1, const CRect<int> &rcROI1, T2 *pDst, int w2, int h2, const CRect<int> &rcROI2, int nGradLen); Description 1D gradient in the y direction Take the image data gradient in the y direction. If the gradient length is 2, the y gradient pDst[y*w+x] = pSrc[(y+1)*w+x] - pSrc[(y-1)*w+x], meaning the gap between the two pixels used to calculate a gradient point is 2. See Table 2 for common parameters length of the gradient operator

Parameters nGradLen

3.8

ImgClamp

template <class T> void ImgClamp (T *pImg, int w, int h, const CRect<int> &rcROI, T toMin, T toMax); Description Parameters toMin toMax Clamp image data to the range [toMin, toMax] See Table 2 for common parameters minimum bound to clamp the image data maximum bound to clamp the image data

3.9

ImgLinear

template <class T1, class T2> void ImgLinear (const T1 *pSrc, int w1, int h1, const CRect<int> &rcROI1, T2 *pDst, int w2, int h2, const CRect<int> &rcROI2, T1 fromMin, T1 fromMax, T2 toMin, T2 toMax); Description Linear translate Src data in the range [fromMin, fromMax] to Dst data to the range [toMin, toMax]. Linear translation parameters a and b is determined by: a * fromMin + b = toMin; a * fromMax + b = toMax; continued on next page

33

Parameters fromMin fromMax toMin toMax

Data points in Src that are < fromMin or > fromMax will be translate to toMin and toMax. pSrc and pDst may point to the same image buer, if ROI1 and ROI2 are the same. See Table 2 for common parameters source minimum bound source maximum bound destination minimum bound destination maximum bound

(a)

(b)

(c)

Figure 25: Examples of the ImgClamp and ImgLinear functions. (a) Source image. (b) Image data are clamped to [50, 200]. (c) Image data are linearly translated to [50, 200].

3.10

ImgGamma

template <class T1, class T2> void ImgGamma (const T1 *pSrc, int w1, int h1, const CRect<int> &rcROI1, T2 *pDst, int w2, int h2, const CRect<int> &rcROI2, double dGamma); Description Apply gamma transform Gamma transform equation: y = xgamma , where x [0, 1]. This function rst maps all data from [min, max] to [0, 1]; then applies gamma transform; and nally maps the data back to [min, max]. pSrc and pDst may point to the same image buer, if ROI1 and ROI2 are the same. See Table 2 for common parameters gamma value

Parameters dGamma

(a)

(b)

(c)

Figure 26: Examples of the ImgGamma function. (a) Source image. (b) The image after transformed by gamma = 0.7. (c) The image after transformed by gamma = 1.5.

3.11

ImgMin

template <class T> T ImgMin (const T *pImg, int w, int h, const CRect<int> &rcROI); Description Parameters Return Get the minimum value of an ROI See Table 2 for common parameters the minimum value of an ROI 34

3.12

ImgMax

template <class T> T ImgMax (const T *pImg, int w, int h, const CRect<int> &rcROI); Description Parameters Return Get the maximum value of an ROI See Table 2 for common parameters the maximum value of an ROI

3.13

ImgMinMax

template <class T> void ImgMinMax (const T *pImg, int w, int h, const CRect<int> &rcROI, T *pMin, T *pMax); Description Parameters pMin pMax Get the minimum and maximum value of an ROI See Table 2 for common parameters return the minimum value of an ROI return the maximum value of an ROI

3.14

ImgMean

template <class T> T ImgMean (const T *pImg, int w, int h, const CRect<int> &rcROI); Description Parameters Return Get the mean value of an ROI See Table 2 for common parameters the mean value of an ROI

3.15

ImgMedian

template <class T> T ImgMedian (const T *pImg, int w, int h, const CRect<int> &rcROI); Description Parameters Return Get the median value of an ROI See Table 2 for common parameters the median value of an ROI

3.16

ImgVariance

template <class T> double Variance (const T *pImg, int w, int h, const CRect<int> &rcROI); Description Parameters Return Get the variance of an ROI See Table 2 for common parameters the variance of an ROI

3.17

ImgStdDev

template <class T> double ImgStdDev (const T *pImg, int w, int h, const CRect<int> &rcROI); Description Parameters Return Get the standard deviation of an ROI See Table 2 for common parameters the standard deviation of an ROI

3.18

ImgStatistics

template <class T> void ImgStatistics (const T *pImg, int w, int h, const CRect<int> &rcROI); T *pMin, T *pMax, T *pMean, double *pdStdDev);

35

Description Parameters pMin pMax pMean pdStdDev

Get statistics of an ROI See Table 2 for common parameters return the minimum value of an ROI return the maximum value of an ROI return the mean value of an ROI return the standard deviation of an ROI

3.19

ImgFltMean
T> void ImgFltMean int w1, int h1, const CRect<int> &rcROI1, int w2, int h2, const CRect<int> &rcROI2, nKerH); Mean lter, kernel certer equal to kernel mean Half-lter-length data at the ROI boundary are ltered with reduced sized kernel. See Table 2 for common parameters lter kernel width lter kernel height nKerW*nKerH = 3*3 or 7*5

template <class (const T *pSrc, T *pDst, int nKerW, int Description

Parameters nKerW nKerH Example

template <class T1, class T2, class T3> void ImgFltMean (const T1 *pImg, int w1, int h1, const CRect<int> &rcROI1, const T2 *pWei, int w2, int h2, const CRect<int> &rcROI2, T3 *pDst, int w3, int h3, const CRect<int> &rcROI3, int nKerW, int nKerH); Description Parameters pWei Weighted mean lter See Table 2 for common parameters weighting. (rcROI1, rcROI2 and rcROI3 must be the same size)

3.20

ImgFltMedian
T> void ImgFltMedian int w1, int h1, const CRect<int> &rcROI1, int w2, int h2, const CRect<int> &rcROI2, nKerH); Median lter, kernel certer equal to kernel median Half-lter-length data at the ROI boundary are ltered with reduced sized kernel. See Table 2 for common parameters lter kernel width lter kernel height nKerW*nKerH = 3*3 or 7*5

template <class (const T *pSrc, T *pDst, int nKerW, int Description

Parameters nKerW nKerH Example

(a)

(b)

(c)

Figure 27: Examples of the ImgFltMean and ImgFltMedian functions. (a) Source image. (b) The image after ltered by ImgFltMean (3 by 3 kernel). (c) The image after ltered by ImgFltMedian (3 by 3 kernel).

36

3.21

ImgFltVariance

template <class T1, class T2> void ImgFltVariance (const T1 *pSrc, int w1, int h1, const CRect<int> &rcROI1, T2 *pDst, int w2, int h2, const CRect<int> &rcROI2, int nKerW, int nKerH); Description Variance lter, kernel certer equal to kernel variance Half-lter-length data at the ROI boundary are ltered with reduced sized kernel. See Table 2 for common parameters lter kernel width lter kernel height nKerW*nKerH = 3*3 or 7*5

Parameters nKerW nKerH Example

(a)

(b)

Figure 28: An example of the ImgFltVariance function. (a) Source image. (b) The image after ltered by ImgFltVariance (3 by 3 kernel). Dark pixels indicate high variance; bright pixels indicate low variance.

3.22

ImgFltISEF

template <class T> void ImgFltISEF (T *pImg, int w, int h, const CRect<int> &rcROI, double dStrength); Description Parameters dStrength Innite symmetric exponential lter See Table 2 for common parameters ISEF lter strength [0, 1) (larger, smoother)

(a)

(b)

(c)

Figure 29: Examples of the ImgFltISEF function. (a) Source image. (b) The image after ltered by 0.5 lter strength. (c) The image after ltered by 0.8 lter strength.

3.23

ImgConvX

template <class T1, class T2> void ImgConvX (T1 *pImg, int w, int h, const CRect<int> &rcROI, const T2 *pMask, int nLen);

37

Description

Parameters pMask nLen

1D convolution in x direction Convolution is applied on each row (x direction). Half-lter-length data at the ROI boundary are unchanged. The mask data array size must satisfy nLen+(nLen-1)/2 ROI.Width(); otherwise nothing is done. See Table 2 for common parameters pointer to the convolution mask data array mask array size

3.24

ImgConvY

template <class T1, class T2> void ImgConvY (T1 *pImg, int w, int h, const CRect<int> &rcROI, const T2 *pMask, int nLen); Description 1D convolution in y direction Convolution is applied on each column (y direction). Half-lter-length data at the ROI boundary are unchanged. The mask data array size must satisfy nLen+(nLen-1)/2 ROI.Height(); otherwise nothing is done. See Table 2 for common parameters pointer to the convolution mask data array mask array size

Parameters pMask nLen

(a)

(b)

(c)

Figure 30: Examples of the ImgConvX and ImgConvY functions. (a) Source image. (b) The resultant image processed by ImgConvX. (c) The resultant image processed by ImgConvY. The convolution mask image is pMask[5] = {0.2, 0.2, 0.2, 0.2, 0.2}.

3.25

ImgConv

template <class T1, class T2> void ImgConv (const T1 *pSrc, int w1, int h1, const CRect<int> &rcROI1, T1 *pDst, int w2, int h2, const CRect<int> &rcROI2, const T2 *pMask, int nKerW, int nKerH); Description Parameters pMask nKerW nKerH Example 1 2D convolution Half-lter-length data at the ROI boundary are unchanged. See Table 2 for common parameters pointer to the convolution mask image mask image width mask image height Sobel convolution mask pMask[0] = -1, pMask[1] = 0, pMask[2] = 1 pMask[3] = -2, pMask[4] = 0, pMask[5] = 2 pMask[6] = -1, pMask[7] = 0, pMask[8] = 1 Sharpening convolution mask pMask[0] = -0.2, pMask[1] = -0.5, pMask[2] = -0.2 pMask[3] = -0.5, pMask[4] = +3.8, pMask[5] = -0.5 continued on next page

Example 2

38

pMask[6] = -0.2, pMask[1] = -0.5, pMask[2] = -0.2

(a)

(b)

(c)

Figure 31: Examples of the ImgConv function. (a) Source image. (b) Image produced by Sobel convolution mask. Dark pixels indicate high values; bright pixels indicate low values. (c) Image produced by the sharpening convolution mask.

3.26

ImgResize

template <class T1, class T2> void ImgResize (const T1 *pSrc, int w1, int h1, const CRect<int> &rcROI1, T2 *pDst, int w2, int h2, const CRect<int> &rcROI2, int nAlgo); Description Resize ROI1 of Src and copy to ROI2 of Dst If linear (nAlgo: 1) or spline (nAlgo: 24) is used, minication is always a downsampling process based on averaging. Magnication is done by the specied method. If nearest neighbour (nAlgo: 0) is used, both minication and magnication are based on nearest neighbour. See Table 2 for common parameters interpolation algorithm 0: nearest neighbour interpolation, 1: linear interpolation, 2: cubic B-spline interpolation. 3: Catmull-Rom spline interpolation. 4: natural cubic spline interpolation.

Parameters nAlgo

ROI1 ROI2

(a)

(b)

(c)

Figure 32: An example of the ImgResize function. (a) Source image. (b) Destination image. (c) Resized ROI1 is copied to ROI2.

3.27

ImgRotate

template <class T1, class T2> void ImgRotate (const T1 *pSrc, int w1, int h1, const CRect<int> &rcROI1, T2 *pDst, int w2, int h2, const CRect<int> &rcROI2, int nAngle, bool bLinear);

39

200

100

Source pixels Nearest neighbour Linear interpolation Cubic B-spline Catmull-Rom spline Natural cubic spline 10 20 30 Pixel 40 50 60 70

Intensity

Figure 33: An example of dierent algorithms of the ImgResize function.

Description 1 2

Parameters nAngle bLinear

Rotate ROI1 of Src and copy to ROI2 of Dst Rotation center is the center of ROI1. When copied to ROI2, the rotation center is matched with the center of ROI2. If nAngle is not a multiple of 9000 (90 deg). The rotated points in ROI1 that do not fall in ROI2 are ignored. Those points in ROI2 that do not have counterpart in ROI1 are unchanged. Hence, there is no prerequisite on the size of ROI1 and ROI2. If nAngle is a multiple of 9000 (90 deg), the size of ROI1 and ROI2 must be related accordingly. If the rotation angle is 0 or 180 deg, the size of ROI1 and ROI2 must be the same. If the rotation angle is 90 or 270 deg, the width and height of ROI1 and ROI2 must be exchanged. See Table 2 for common parameters anti-clock wise angle of rotation in 0.01 degree true for linear interpolation, false for nearest neighbour interpolation.

ROI2

ROI1
(a) (b) (c)

Figure 34: An example of the ImgRotate function. (a) Source image. (b) Destination image. (c) Rotated ROI1 is copied to ROI2.

3.28

ImgFlip

template <class T> void ImgFlip (T *pImg, int w, int h, const CRect<int> &rcROI, bool bLeftRight); Description Parameters bLeftRight Flip the image data in an ROI See Table 2 for common parameters true: left-right ip, false: top-bottom ip.

3.29

ImgFan

template <class T1, class T2> void ImgFan (const T1 *pSrc, int w1, int h1, const CRect<int> &rcROI1, 40

(a)

(b)

(c)

Figure 35: An example of the ImgFlip function. (a) Source image. (b) Image is ipped left to right. (c) Image is ipped top to bottom.

T2 *pDst, int w2, int h2, const CRect<int> &rcROI2, double dAngle, double dTopRadius, double dBottomRadius, bool bLinear); Description Parameters dAngle dTopRadius dBottomRadius bLinear Create a fan-shaped image Empty region around the fan shape is unchanged. See Table 2 for common parameters angle in radius of the fan shape (0, TWOPI] radius of the top line in the source ROI radius of the bottom line in the source ROI true for linear interpolation, false for nearest neighbour interpolation.

(a)

(b)

Figure 36: An example of the ImgFan function. (a) Source image. (b) Fan-shaped image.

3.30

ImgRadial

template <class T1, class T2> void ImgRadial (const T1 *pSrc, int w1, int h1, const CRect<int> &rcROI1, T2 *pDst, int w2, int h2, const CRect<int> &rcROI2, const CPt2D<double> &ptCen, double dK); Description Create a radially distorted image ROI1 is radially distorted around ptCen based on equation 2 x2 = ptCen.x + (1 + KR1 )(x1 ptCen.x) 2 y2 = ptCen.y + (1 + KR1 )(y1 ptCen.y), where (x1 , y1 ) and (x2 , y2 ) is a pixel in ROI1 and ROI2 respectively, 2 R1 = (x1 ptCen.x)2 + (y1 ptCen.y)2 . The distorted data are copied to ROI2. Pixels in ROI2 that do not have a counterpart in ROI1 are set to 0. Linear interpolation is used. See Table 2 for common parameters center of radial distortion in CRect(0,0,w1,h1) coordinate radial distortion coecient

Parameters ptCen dK

41

(a)

(b)

(c)

Figure 37: An example of the ImgRadial function. (a) Source image. (b) Barrel distortion. (c) Pincushion distortion.

3.31

ImgMosaic

template <class T> void ImgMosaic (T *pImg, int w, int h, const CRect<int> &rcROI, int nKerW, int nKerH); Description Parameters nKerW nKerH Create mosaic eect See Table 2 for common parameters mosaic kernel width mosaic kernel height

ROI

(a)

(b)

Figure 38: An example of the ImgMosaic function. (a) Source image. (b) The image data in the ROI are mosaicked.

3.32

ImgMatch

template <class T> void ImgMatch (const T *pMother, int w1, int h1, const CRect<int> &rcROI1, const T *pChild, int w2, int h2, const CRect<int> &rcROI2, int nDSX, int nDSY, CPt2D<int> *pptMatch, double *pdCorr); Description Search for ROI2 of pChild in ROI1 of pMother ROI1.Width() must be >= ROI2.Width() ROI1.Height() must be >= ROI2.Height() Initially, ROI2 is matched to windows in ROI1 separated by nDSX and nDSY in the x and y directions. After the best-match window is found; nDSX and nDSY are halved. Then ROI2 is matched to 9 windows, a 3 by 3 grid centered on the bestmatch window. The windows are separated by nDSX and nDSY. After a new best-match window is found, nDSX and nDSY are further halved. Go back to 2 until both nDSX and nDSY equal to 1 pixel. See Table 2 for common parameters initial downsampling gap in x direction continued on next page

3 Parameters nDSX

42

nDSY

pptMatch pdCorr

initial downsampling gap in y direction The downsampling gaps are used in shifting ROI1 across ROI2 and in accessing the pixels in ROI1 and ROI2, the best-match point in ROI1 coordinate (left-top corner of the matched rect) normalized correlation coecient, in [-1,1]
pptMatch

ROI1

ROI2

(a)

(b)

Figure 39: An example of the ImgMatch function. (a) Mother image. (b) Child image. (c) Matched position of the child image in the mother image.

3.33

ImgMatchSubpixel

template <class T> void ImgMatchSubpixel (const T *pMother, int w1, int h1, const CRect<int> &rcROI1, const T *pChild, int w2, int h2, const CRect<int> &rcROI2, int nLevel, CPt2D<float> *pptMatch, double *pdCorr); Description Image matching at subpixel accuracy Subpixel search for ROI2 of pChild in ROI1 of pMother. The matching window is given by ROI2. ROI1 species the limit of the search region. Data matching is performed at several levels of increasing subpixel accruacy. At each level, 3 by 3 windows are searched. The best match is used as the center window of the next level search, See Table 2 for common parameters subpixel level (1: 0.5 pixel, 2: 0.25 pixel, etc) At input, it represents the initial oset (eg. matching point at pixel accuracy). At output, it is the best match (left-top corner) of ROI2 in ROI1 at subpixel accuracy. normalized correlation coecient, in [-1,1]

Parameters nLevel pptMatch

pdCorr

3.34

ImgMotion

template <class T> void ImgMotion (const T *pImg1, int w1, int h1, const CRect<int> &rcROI1, const T *pImg2, int w2, int h2, const CRect<int> &rcROI2, int nCoarW, int nCoarH, int nCoarX, int nCoarY, int nCoarDSX, int nCoarDSY, int nFineW, int nFineH, int nFineX, int nFineY, int nFineDSX, int nFineDSY, int &nWinX, int &nWinY, vector<CPt2D<int> > *pvptCenter, vector<CPt2D<int> > *pvptDisp, vector<double> *pvCorr); Description Pixel ow or motion estimation Estimate the pixel motion from ROI1 in pImg1 to ROI2 in pImg2. ROI1 and ROI2 must be the same size. There are two levels of search: a coarse search based on a few coarse windows and a quality-guided ne search on all ne windows. Results of the coarse search are used as the initial guess for the ne search. continued on next page

43

3 Parameters nCoarW nCoarH nCoarX nCoarY nCoarDSX nCoarDSY nFineW nFineH nFineX nFineY nFineDSX nFineDSY nWinX nWinY pvptCenter pvptDisp pvCorr

A large coarse search window and search distance may be used to obtain robust initial estimates, and a small ne search window and search distance to obtain a high resolution. The downsampling gap at each level is set independently. See ImgMatch(...) for details of the downsampling gap. Results are stored in pvptCenter, pvptDisp, pvCorr, which are arrays of the same size: nWinX * nWinY (at output). See Table 2 for common parameters coarse search window width coarse search window height coarse search distance in x direction coarse search distance in y direction coarse search downsampling gap in x direction coarse search downsampling gap in y direction ne search window width ne search window height ne search distance in x direction ne search distance in y direction ne search downsampling gap in x direction ne search downsampling gap in y direction input desired number of ne search windows in x direction output actual number of ne search windows in x direction input desired number of ne search windows in y direction output actual number of ne search windows in y direction center of ne search windows in pImg1 displacement of ne windows from pImg1 to pImg2 This includes the global shift from ROI1 to ROI2. correlation coecient of each ne window

Coarse window

Fine window

Pixel

Figure 40: Illustration of the dual level search of the ImgMotion function.

3.35

ImgDIC

template <class T> void ImgDIC (const T *pImg1, int w1, int h1, const CRect<int> &rcROI1, const T *pImg2, int w2, int h2, const CRect<int> &rcROI2, int nSpeckleSize, int &nWinX, int &nWinY, vector<CPt2D<int> > *pvptCenter, vector<float> *pvDispX, vector<float> *pvDispY, vector<float> *pvCorr);

44

(a)

(b)

Figure 41: An example of the ImgMotion function. (a) Image 1. (b) Image 2. (c) Local motion vectors from image 1 to image 2.

Description

Parameters nSpeckleSize nWinX nWinY pvptCenter pvDispX pvDispY pvCorr

Digital image correlation Calculate subpixel displacement from ROI1 to ROI2. It relies on ImgMotion(..) to calculate integer pixel displacement and then applies linear interpolation to obtain subpixel accuracy. Search parameters of ImgMotion(..) are estimated by the ROI size. See Table 2 for common parameters average speckle size. It is used to estimate the search window size. input desired number of ne search windows in x direction output actual number of ne search windows in x direction input desired number of ne search windows in y direction output actual number of ne search windows in y direction center of ne search windows in pImg1 displacement in the x direction displacement in the y direction the correlation coecient of each window

3.36

ImgHistogram

template <class T> void ImgHistogram (const T *pImg, int w, int h, const CRect<int> &rcROI, T tMin, T tMax, int *pnHisto, int nLevel); Description Parameters tMin tMax pnHisto nLevel Get histogram of the image data in an ROI See Table 2 for common parameters minimum bound. Pixles < tMin contribute to pnHisto[0]. maximum bound. Pixels > tMax contribute to pnHisto[nLevel-1]. store histogram in nLevel entries. Each entry records the number of pixels falling into a specic range. Its size must be nLevel. level of histogram. The larger the nLevel, the ner is the resolution of the histogram.
1.5

Percentage %

ROI

0.5

20

40

60

80

100

120

140

160

180

200

220

Intensity

(a)

(b)

Figure 42: An example of the ImgHistogram function. (a) Source image. (b) Histogram of the ROI.

45

3.37

ImgHistoEqu

template <class T> void ImgHistoEqu (T *pImg, int w, int h, const CRect<int> &rcROI, T tMin, T tMax, int nLevel); Description Parameters tMin tMax nLevel Equalize histogram of the image data in an ROI See Table 2 for common parameters minimum bound. Pixles < tMin contribute to pnHisto[0]. maximum bound. Pixels > tMax contribute to pnHisto[nLevel-1]. level of histogram. The larger the nLevel, the ner is the resolution of the histogram equalization.
1.4 1.2

Percentage %

1 0.8 0.6 0.4 0.2 0

ROI

50

100

150

200

250

Intensity

(a)
1.4 1.2

(b)
Percentage %
1 0.8 0.6 0.4 0.2 0

50

100

150

200

250

Intensity

(c)

(d)

Figure 43: An example of the ImgHistoEqu function. (a) Source image ROI. (b) Histogram of the source image ROI. (c) Histogram-equalized ROI. (d) Histogram of the equalized ROI.

3.38

ImgClampExtreme

template <class T> void ImgClampExtreme (T *pImg, int w, int h, const CRect<int> &rcROI, double dPerMin, double dPerMax, T *pMin = 0, T *pMax = 0); Description Clamp extreme values in an ROI The biggest value of the bottom perMin percent data is set as the minimum bound. The smallest value of the top perMax percent is set as the maximum bound. Image data that fall below the minimum bound or above the maximum are clamped to the bounds, respectively. See Table 2 for common parameters percentage of minimum to be clamped. Should be in [0, 1]. percentage of maximum to be clamped. Should be in [0, 1]. the minimum value of the ROI after processing (input 0 to ignore) the maximum value of the ROI after processing (input 0 to ignore)

Parameters dPerMin dPerMax pMin pMax

3.39

ImgThre TwoPeak

template <class T> T ImgThre_TwoPeak (const T *pImg, int w, int h, const CRect<int> &rcROI);

46

Description

Parameters Return

Get threshold of an ROI based on the two peaks method First, histogram of the ROI is computed. Then two peaks are located. The threshold is the mid value of the two peak values. Locate the max peak is straightforward. The 2nd peak is the max multiplication of the histogram values by the square of the distance from the rst peak. This helps not to choose a pseudo-peak near the max (1st) peak. See Table 2 for common parameters threshold of an ROI

3.40

ImgThre IterSel

template <class T> T ImgThre_IterSel (const T *pImg, int w, int h, const CRect<int> &rcROI); Description Get threshold of an ROI based on the iterative selection method Take an initial guess of the threshold. Compute mean of all pixels below the threshold and the mean of all pixels above the threshold. The new threshold is (Tb+Ta)/2. Continue this process until there is no change in the threshold value. See Table 2 for common parameters threshold of an ROI

Parameters Return

(a)

(b)

(c)

Figure 44: Examples of the ImgThre TwoPeak and ImgThre IterSel functions. (a) Source image. (b) Threshold obtained by the two-peak method. (c) Threshold obtained by the iterative selection method.

3.41

ImgDilation
ImgDilation int h1, const CRect<int> &rcROI1, int h2, const CRect<int> &rcROI2, int nCount);

template <class T> void (const T *pSrc, int w1, T *pDst, int w2, const CPt2D<int> *ppt, Description

Parameters ppt nCount Example

Morphology dilation Dilation is applied to intensity data rather than binary data. The input relative position array is used as structuring elements. A destination pixel is set to the max value (in ImgDilation) or min value (in ImgErosion) of the source pixels located by the relative positions. If a destnation pixels all relative positions are outside the source region, it is set to the source regions global min (in ImgDilation) or max (in ImgErosion) value. See Table 2 for common parameters relative position array (size must be nCount) the size of ppt Dilate in 135 deg: ppt[0]=(-1,-1); [1]=(1,1);

3.42

ImgErosion
ImgErosion int h1, const CRect<int> &rcROI1, int h2, const CRect<int> &rcROI2, int nCount); 47

template <class T> void (const T *pSrc, int w1, T *pDst, int w2, const CPt2D<int> *ppt,

Description

Parameters ppt nCount Example

Morphology erosion Erosion is applied to intensity data rather than binary data. The input relative position array is used as structuring elements. A destination pixel is set to the max value (in ImgDilation) or min value (in ImgErosion) of the source pixels located by the relative positions. If a destnation pixels all relative positions are outside the source region, it is set to the source regions global min (in ImgDilation) or max (in ImgErosion) value. See Table 2 for common parameters relative position array (size must be nCount) the size of ppt Dilate in 135 deg: ppt[0]=(-1,-1); [1]=(1,1);

(a)

(b)

(c)

Figure 45: Examples of the ImgDilation and ImgErosion functions. (a) Source image. (b) Image dilation. (c) Image erosion.

3.43

ImgProjX

template <class T> void ImgProjX (const T *pImg, int w, int h, const CRect<int> &rcROI, T *pProj); Description Parameters pProj Example Get x direction projection of an ROI See Table 2 for common parameters average of values along x direction. Its size must be >= ROI.Height(). Its index increases with y. 3, 5, 234, 90 | pvDst: 336/4 7, 23, 34, 29 | 93/4 12, 21, 9, 32 | 74/4

3.44

ImgProjY

template <class T> void ImgProjY (const T *pImg, int w, int h, const CRect<int> &rcROI, T *pProj); Description Parameters pProj Example Get y direction projection of an ROI See Table 2 for common parameters average of values along y direction. Its size must be >= ROI.Width(). Its index increases with x. 3, 5, 234, 90 7, 23, 34, 29 12, 21, 9, 32 -----------------------pvDst: 22/3, 49/3, 277/3, 151/3

3.45

ImgProjAny

template <class T> void ImgProjAny (const T *pImg, int w, int h, const CRect<int> &rcROI, 48

170 150

130

Intensity

110

ROI
90 70 0 200 400 600 800 1000 1200

Intensity

120

70

20

200

400

600

800

1000

1200

1400

1600

Pixel

Pixel

(a)

(b)

(c)

Figure 46: Examples of the ImgProjX and ImgProjY functions. (a) Source image. (b) Intensity projection of the ROI in the x direction. (c) Intensity projection of the ROI in the y direction.

const CLine2D<int> &lnStart, const CLine2D<int> &lnEnd, T *pProj, int nLine); Description Get the projection of an arbitrary-shaped region The arbitrary-shaped region is specied by 2 lines. The projection sweeps from lnStart to lnEnd with nLine projection lines. If a line is outside the ROI, its projection value will be set to 0. See Table 2 for common parameters the start projection line the end projection line (lnStart and lnEnd may intersect) store average value of each projection line. Its size must be nLine. the number of projection lines
180 160

Parameters lnStart lnEnd pProj nLine

tart

ptE

140

ptS

Intensity

nd

120 100 80 60 40

20

40

60

80

100

Pixel

(a)

(b)

Figure 47: An example of the ImgProjAny function. (a) Source image with start and end projection lines. (b) Intensity projection of the ROI.

3.46

ImgRadon

template <class T1, class T2> void ImgRadon (const T1 *pSrc, int w1, int h1, const CRect<int> &rcROI1, T2 *pDst, int w2, int h2, const CRect<int> &rcROI2, double dStartAngle, double dStepInc); Description Radon transform Radon transform is the integral of an image over straight lines. Parallel geometry is assumed. The projection width is ROI2.Width() and the number of angles is ROI2.Height(). The projection at each angle is stored in a line in ROI2. See Table 2 for common parameters the start angle of projection the angular increase at each step

Parameters dStartAngle dStepInc

3.47

ImgRadonVH

template <class T1, class T2, class Pred> void ImgRadonVH (const T1 *pSrc, int w1, int h1, const CRect<int> &rcROI1, 49

(a)

(b)

(c)

Figure 48: An example of the ImgRadon function. (a) Source image. (b) Radon transformed image. (c) Inverse Radon trasformed image by ltered backprojection.

T2 *pDst, int w2, int h2, const CRect<int> &rcROI2, Pred pred, double dStartAngle, double dStepInc, T2 tObj); Description Radon transform for visual hull This function mimics non-penetrating light projection on objects. It is different from X-ray penetration of objects, modeled in ImgRadon(..). Parallel geometry is assumed. The projection width is ROI2.Width() and the number of angles is ROI2.Height(). The projection at each angle is stored in a line in ROI2. See Table 2 for common parameters Pixels == 0 are denitely background, == tObj are denitely objects, in between are edge points. if pred(pSrc[y*w+x]) is true, point (x,y) is considered an object point. the start angle of projection the angular increase at each step value in pDst to indicate object pixels

Parameters pDst pred dStartAngle dStepInc tObj

3.48

ImgBackprojVH

template <class T1, class T2, class Pred> void ImgBackprojVH (const T1 *pSrc, int w1, int h1, const CRect<int> &rcROI1, T2 *pDst, int w2, int h2, const CRect<int> &rcROI2, Pred pred, double *pdAngle, T2 tObj); Description Backprojection for visual hull Backprojection for visual hull (VH) is an erosive process in contrast to the accumulative process in the ltered backprojection for computed tomography (CT). At the start, all pixels in the backprojected eld are set as objects. A background projection datum sets the pixels in the backprojected line to be background while an object datum does not change the backprojected eld. Each line of ROI1 is the CP Radon transform projection at an angle (given by pdAngle). The size of pdAngle should be the same as ROI1.Height(). See Table 2 for common parameters Pixels == 0 are denitely background, == tObj are denitely objects, in between are edge points. if pred(pSrc[y*w+x]) is true, point (x,y) is considered an object point. angle of each projection line value in pDst to indicate object pixels

Parameters pDst pred pdAngle tObj

3.49

ImgIntegral

template <class T1, class T2> void ImgIntegral (const T1 *pSrc, int w1, int h1, const CRect<int> &rcROI1, T2 *pSum, int w2, int h2, const CRect<int> &rcROI2); template <class T1, class T2> void ImgIntegral (const T1 *pSrc, int w1, int h1, const CRect<int> &rcROI1, 50

T2 *pSum, int w2, int h2, const CRect<int> &rcROI2, T2 *pSum2, int w3, int h3, const CRect<int> &rcROI3); Description Calculate two integral images The rst version calculates the summation and the second version calculates both the summation and the summation of square. Each pixel in pSum (pSum2) is the summation (summation of square) of all pSrcs pixels in the left-top region with respect to and including that pixel. See Table 2 for common parameters

Parameters

3.50

ImgLabeling

template <class T1, class T2, class Pred> int ImgLabeling (const T1 *pSrc, int w1, int h1, const CRect<int> &rcROI1, T2 *pDst, int w2, int h2, const CRect<int> &rcROI2, Pred pred, int nConnectivity, int nMinArea = 0, int nMaxArea = 0, vector<CRect<int> > *pvRect = 0, vector<int> *pvArea = 0); Description Parameters pred nConnectivity Connectivity labeling algorithm See Table 2 for common parameters if pred(pSrc[y*w+x]) is true, the point (x,y) is considered an object point. Euclidean connectivity of an object. 0: 4-neighbour labeling algorithm, 1: 8-neighbour labeling algorithm, >1: pixels within this distance are one object. Object fewer than nMinArea pixels are discarded. Object larger than nMaxArea pixels are discarded. bounding rectangle of each object (input 0 to ignore) It is with respect to ROI2. To obtain a bounding rect with respect to ROI1, each rect should be oset r1.LeftTop()-r2.LeftTop(). number of points of each object (input 0 to ignore) the number of objects found The 1st object can be found by checking if(pDst[y*w+x]==1). The 1st objects bounding rect is (*pvRect)[0]. The 3rd objects number of points is (*pvArea)[2].

nMinArea nMaxArea pvRect

pvArea Return Example

(a)

(b)

(c)

Figure 49: An example of the ImgLabeling function. (a) Source image. Dark pixels are to be labeled. (b) Labeled image. Each color represents an object and the background is white. (c) Labeled image with nMinArea = 150, Objects fewer than 150 pixels are discarded.

3.51

ImgFilling

template <class T, class Pred> void ImgFilling (T *pImg, int w, int h, const CRect<int> &rcROI, T value, Pred pred, CPt2D<int> ptSeed, int nConnectivity);

51

Description Parameters value pred

ptSeed nConnectivity

Fill a region bounded by a predicate condition See Table 2 for common parameters value to ll with if pred(pImg[y*w+x],value) is true, the point (x,y) is considered boundary. Only three predicates are valid: equal to, greater equal, less equal. Other predicates such as greater or less may cause dead loop, so they should be strictly prohibited. initial seed point for lling Euclidean connectivity of a lling region. 0: 4-neighbour lling algorithm, 1: 8-neighbour lling algorithm, >1: pixels within this distance are lled.

Seed

(a)

(b)

Figure 50: An example of the ImgFilling function. (a) Source image. The point is the seed of lling. (b) Filled image. Filling value: 200. pred (boundary condition): less equal. Connectivity: 4-neighbour lling algorithm.

3.52

ImgThinning

template <class T> void ImgThinning (T *pImg, int w, int h, const CRect<int> &rcROI, T ObjID, T NonObjID); Description Parameters NonObjID Thinning algorithm See Table 2 for common parameters Pixels with value==NonObjID are treated as background.

(a)

(b)

Figure 51: An example of the ImgThinning function. (a) Source image. (b) Thinned image.

3.53

ImgCentroid

template <class T> bool ImgCentroid (const T *pImg, int w, int h, const CRect<int> &rcROI, T ObjID, double *pdXCen, double *pdYCen);

52

Description Parameters pdXCen pdYCen Return

Get the centroid of an object See Table 2 for common parameters x coordinate of the center, if found. y coordinate of the center, if found. true: the centroid of an object is found; otherwise, false.

3.54

ImgBoundaryOrdered

template <class T> int ImgBoundaryOrdered (const T *pImg, int w, int h, const CRect<int> &rcROI, T ObjID, vector<CPt2D<int> > *pvPos); Description Parameters pvPos Return Get clockwise ordered boundary points, based on 8-neighbour connectivity. Holes are not detected as boundary. See Table 2 for common parameters a vector pointer that stores the found boundary points the number of boundary points

3.55

ImgBoundaryUnordered

template <class T> int ImgBoundaryUnordered (const T *pImg, int w, int h, const CRect<int> &rcROI, T ObjID, vector<CPt2D<int> > *pvPos); Description Parameters pvPos Return Get unordered boundary points, based on 8-neighbour connectivity. Holes are detected as boundary. See Table 2 for common parameters a vector pointer that stores the found boundary points the number of boundary points

(a)

(b)

(c)

Figure 52: Examples of the ImgBoundaryOrdered and ImgBoundaryUnordered functions. (a) Source image. (b) Ordered boundary. Holes are ignored. (c) Unordered boundary. Holes are detected.

3.56

ImgOuterCorners

template <class T> int ImgOuterCorners (const T *pImg, int w, int h, const CRect<int> &rcROI, T ObjID, vector<CPt2D<int> > *pvPos); Description Parameters pvPos Return Get the outer corner points of an object Outer corner points are used to calculate the convex hull. See Table 2 for common parameters stores the outer corner points, in clockwise order. the number of outer corner points

53

(a)

(b)

Figure 53: An example of the ImgOuterCorners function. (a) Source image. Dark pixels are considered as objects for detecting corner points. (b) Corner points of each object. Note that inner corners of a hole are not treated as corner points.

3.57

ImgConvexHull

template <class T> int ImgConvexHull (const T *pImg, int w, int h, const CRect<int> &rcROI, T ObjID, vector<CPt2D<int> > *pvCH); Description Parameters pvCH Return Get the convex hull points in clockwise order See Table 2 for common parameters output convex hull points (in clockwise order) the number of convex hull points

(a)

(b)

Figure 54: An example of the ImgConvexHull function. (a) Source image. Dark pixels are considered as objects for detecting convex hulls. (b) Convex hulls of each object.

3.58

ImgBoundingBox

template <class T> bool ImgBoundingBox (const T *pImg, int w, int h, const CRect<int> &rcROI, T ObjID, double dAngle, CPt2D<double> *pptCenter, CSize2D<double> *pSize); Description Parameters dAngle pptCenter pSize Return Get the xed-angle bounding box of an object See Table 2 for common parameters angle of the bounding box (radius, anticlockwise) center of the box size of the box true: succeeded; false: failed (no object points).

3.59

ImgMinBoundingBox

template <class T> bool ImgMinBoundingBox (const T *pImg, int w, int h, const CRect<int> &rcROI, T ObjID, CPt2D<double> *pptCenter, CSize2D<double> *pSize, double *pdAngle); Description Parameters pptCenter pSize pdAngle Return Get the minimum bounding box of an object See Table 2 for common parameters center of the box size of the box angle of the box (radius, anticlockwise) true: succeeded; false: failed (no object points). 54

3.60

ImgMinBoundingCircle

template <class T> bool ImgMinBoundingCircle (const T *pImg, int w, int h, const CRect<int> &rcROI, T ObjID, CPt2D<double> *pptCenter, double *pdRadius); Description Parameters pptCenter pdRadius Return Get the minimum bounding circle of an object See Table 2 for common parameters center of the circle radius of the circle true: succeeded; false: failed (no object points).

3.61

ImgMinBoundingPolygon

template <class T> bool ImgMinBoundingPolygon (const T *pImg, int w, int h, const CRect<int> &rcROI, T ObjID, vector<CPt2D<int> > *pvPos); Description Get the minimum bounding polygon of an object Such polygon diers from a complete list of boundary points in that it removes points on any straight line parallel to X or Y axis. Only end points of a line are kept as the polygon vertices. See Table 2 for common parameters stores the polygon vertices, in clockwise order. the number of polygon vertices

Parameters pvPos Return

(a)

(b)

(c)

(d)

Figure 55: Examples of the ImgBoundingBox, ImgMinBoundingBox, ImgMinBoundingCircle, and ImgMinBoundingPolygon functions. (a) Bounding box at a xed angle of 27 deg. (b) Minimum area bounding box. (c) Minimum area bounding circle. (d) Minimum area bounding polygon.

3.62

ImgDistTrans

template <class T> void ImgDistTrans (const T *pSrc, int w1, int h1, const CRect<int> &rcROI1, unsigned long *pnDst, int w2, int h2, const CRect<int> &rcROI2, T threshold); Description Parameters pnDst threshold Distance transform algorithm Reference Euclidean Distance Mapping by P. Danielsson. See Table 2 for common parameters a background pixel is set to 0; an object pixel is set to the square of the Euclidean distance to its nearest background pixel. pixels >= threshold in pSrc are objects; pixels < threshold in pSrc are background.

3.63

ImgWatershed

template <class T1, class T2> int ImgWatershed (const T1 *pSrc, int w1, int h1, const CRect<int> &rcROI1, T2 *pDst, int w2, int h2, const CRect<int> &rcROI2, int nDist, int nMinPts);

55

Description

1 2 3 4 Parameters nDist

nMinPts Return

Watershed algorithm for segmentation This function assumes the input pSrc a distance map, for example, obtained from ImgDistTrans(...). It outputs an object map similar to that produced by ImgLabeling(...). In the object map, previously connected regions are segmented. Local maxima are located for each object. The rst-pass propagation estimates the number of points grown by each maxima within each object. Maxima whose number of points are < nMinPts are discarded. The second-pass propagation nishes the segmentation. See Table 2 for common parameters the distance for merging local maxima. 0: 4-neighbour merging, 1: 8-neighbour merging, >1: local maxima within this distance are merged. threshold of the number of points grown by a maximum. Both parameters are used to reduce over-segmentation. The number of segmented objects, if succeeded; otherwise -1.

255 128 0
(a) (b) (c) Figure 56: Examples of the ImgDistTrans and ImgWatershed functions. (a) Source image. (b) Distance transformed image. (c) Watershed segmented image.

3.64

ImgEdgeX

template <class T> int ImgEdgeX (T *pImg, int w, int h, const CRect<int> &rcROI, T tThre, int nEdgeType, int nHalfFltLen, int nIndex, int nDSY, vector<CPt2D<int> > *pvptEdge); Description 1D edge detection in x direction (description applicable to y direction) 1D edge detection based on the contrast of image data along x or y direction. The scan of edge point in x direction is left-to-right; the scan in y direction is top-to-bottom. At each point, nHalfFltLen species how many data to check to the left and right (x direction) or to the top and bottom (y direction) of a point. The average intensity of the two sections are calculated. If their dierence is >= tThre, the center point is considered as an edge point. nHalfFltLen-1 pixels boundary of the ROI is not scanned. There are two types of edges: positive and negative. In the direction of scan (x direction: left-to-right, y direction: top-to-bottom), a positive edge indicates the data values are increasing; while a negative edge indicates decreasing. One or multiple edge points at each line can be output to vptEdge. If nIndex is non-zero, one edge point is selected. For example, 1 means the rst edge point, 2: the second, etc; -1 means the last, -2: the second last, etc. If nIndex is 0, all edge points are output. continued on next page

56

Parameters tThre nEdgeType nHalfFltLen nIndex nDSY pvptEdge Return

If two edge points of the same type are found within 2*nHalfFltLen pixels, only the one with larger contrast is output because they are likely to be part of a steep edge. See Table 2 for common parameters edge contrast threshold edge type (-1: negative, 1: positive, 0: both) half-lter-length at each side of a point 1-based index of the edge point to be output downsampling gap in y direction (eg. If 1, each line, or if 2, every other line is scanned.) store output edge points. Some line may not have any edge point. the number of edge points found

3.65

ImgEdgeY

template <class T> int ImgEdgeY (T *pImg, int w, int h, const CRect<int> &rcROI, T tThre, int nEdgeType, int nHalfFltLen, int nIndex, int nDSX, vector<CPt2D<int> > *pvptEdge); Description Parameters nDSX 1D edge detection in y direction (see ImgEdgeX for details) See Table 2 for common parameters downsampling gap in x direction (eg. If 1, each row, or if 2, every other row is scanned.)

3.66

ImgEdgeXSubpixel

template <class T> int ImgEdgeXSubpixel (T *pImg, int w, int h, const CRect<int> &rcROI, T tThre, int nEdgeType, int nHalfFltLen, int nIndex, int nDSY, vector<CPt2D<double> > *pvptEdge); Description 1D edge detection in x direction at subpixel accuracy All the parameters and the return value are the same as those of ImgEdgeX except for pvptEdge, whose x coord is at subpixel accuracy and y coord is still in integer pixel.

3.67

ImgEdgeYSubpixel

template <class T> int ImgEdgeYSubpixel (T *pImg, int w, int h, const CRect<int> &rcROI, T tThre, int nEdgeType, int nHalfFltLen, int nIndex, int nDSX, vector<CPt2D<double> > *pvptEdge); Description 1D edge detection in y direction at subpixel accuracy All the parameters and the return value are the same as those of ImgEdgeY except for pvptEdge, whose y coord is at subpixel accuracy and x coord is still in integer pixel.

3.68

ImgEdgeAny

template <class T> int ImgEdgeAny (T *pImg, int w, int h, const CRect<int> &rcROI, const CLine2D<int> &lnGuide, T tThre, int nEdgeType, int nScanLen, int nHalfFltLen, int nNumScan, vector<CPt2D<double> > *pvptEdge, vector<CLine2D<int> > *pvlnScan = 0); Description 1 Detect 1D edge based on a guiding line Multiple scan lines are generated perpendicular to the guiding line. Their direction is determined by lnGuide: lnGuide.Start() lnGuide.End() lnScan.Start() is anti-clockwise and lnGuide.Start() lnGuide.End() lnScan.End() is clockwise. continued on next page 57

2 3 4 Parameters lnGuide tThre nEdgeType nScanLen nHalfFltLen nNumScan pvptEdge pvlnScan Return

In the direction of lnScan, a positive edge indicates increasing data values; while a negative edge indicates decreasing data values. On each scan line, the maximum contrast (strongest) edge point is output, if its contrast is larger than tThre. Edge contrast is the dierence of the average intensity of the nHalfFltLen pixels before and after an edge point. See Table 2 for common parameters a guiding line for searching for edge points edge contrast threshold edge type (-1: negative, 1: positive, 0: both) scan length for an edge point half-lter-length at each side of a point the number of scan lines on the guiding line store output edge points at subpixel accuracy scan lines (input 0 to ignore) the number of edge points found

3.69

ImgEdgeOnLine

template <class T> int ImgEdgeOnLine (T *pImg, int w, int h, const CRect<int> &rcROI, const CLine2D<int> &lnScan, T tThre, int nEdgeType, int nHalfFltLen, vector<CPt2D<int> > *pvptEdge); Description Detect 1D edge on a line Scan from lnScan.Start() to lnScan.End() for edge points. In the direction of lnScan, a positive edge indicates the data values are increasing; while a negative edge indicates decreasing. All edge points with contrast >= tThre are output to pvptEdge but if two edge points of the same type are found within 2*nHalfFltLen pixels, only the one with larger contrast is output because they are likely to be part of a steep edge. Edge contrast is the dierence of the average intensity of the nHalfFltLen pixels before and after an edge point. See Table 2 for common parameters scan line for edge points edge contrast threshold edge type (-1: negative, 1: positive, 0: both) scan length for an edge point half-lter-length at each side of a point store output edge points the number of edge points found

Parameters lnScan tThre nEdgeType nScanLen nHalfFltLen pvptEdge Return

scan lines

edge points
(a)

guiding line

edge points
(b)

scan line

Figure 57: Examples of the ImgEdgeAny and ImgEdgeOnLine functions. (a) ImgEdgeAny and (b) ImgEdgeOnLine function.

58

3.70

ImgCannyEdge

template <class T> void ImgCannyEdge (T *pImg, int w, int h, const CRect<int> &rcROI, T lowThre, T highThre, int nFltLen); Description Canny edge detection algorithm The edge magnitude (gradient in the x and y directions) at each pixel is calculated and non-local-maximum pixels are set to 0. Then, a hysteresis thresholding procedure is applied to extract the edge pixels. Pixels lowThre and connected to any pixel highThre are thresholded as edge (set to 1). Those that are < lowThre or < highThre but not connected to any pixel > highThre are set to 0. See Table 2 for common parameters low threshold for hysteresis thresholding high threshold for hysteresis thresholding Gaussian lter length (3) If highThre > lowThre, pImg stores edge (1) and non-edge (0). If highThre lowThre, pImg stores edge magnitude.

Parameters lowThre highThre nFltLen

3.71

ImgShenCastanEdge

template <class T> void ImgShenCastanEdge (T *pImg, int w, int h, const CRect<int> &rcROI, T lowThre, T highThre, double dStrength, int nWinSize); Description Parameters lowThre highThre dStrength nWinSize Shen and Castan edge detection algorithm See Table 2 for common parameters low threshold for hysteresis thresholding high threshold for hysteresis thresholding ISEF lter strength [0, 0.9] window size for calculating the edge contrast If highThre > lowThre, pImg stores edge (1) and non-edge (0). If highThre lowThre, pImg stores edge magnitude.

(a)

(b)

(c)

Figure 58: Examples of the ImgCannyEdge and ImgShenCastanEdge functions. (a) Source image. (b) Canny edge. (c) ShenCastan edge.

3.72

ImgFitPlane

template <class T> bool ImgFitPlane (const T *pImg, int w, int h, const CRect<int> &rcROI, double *pdKx, double *pdKy, double *pdZ0); Description Parameters pdKx pdKy pdZ0 Return Fit a plane to image data of an ROI Plane equation z(x,y) = Kx*x + Ky*y + Z0 See Table 2 for common parameters Kx of the plane equation, if succeed; or undened. Ky of the plane equation, if succeed; or undened. Z0 of the plane equation, if succeed; or undened. true: succeeded; false: failed. 59

template <class T1, class T2> bool ImgFitPlane (const T1 *pImg, int w1, int h1, const CRect<int> &rcROI1, const T2 *pWei, int w2, int h2, const CRect<int> &rcROI2, double *pdKx, double *pdKy, double *pdZ0); Description Parameters pWei Fit a plane to weighted image data See Table 2 for common parameters weighting. (rcROI1, rcROI2 must be the same size)

3.73

ImgFitPolynomialSurf

template <class T> bool ImgFitPolynomialSurf (const T *pImg, int w, int h, const CRect<int> &rcROI, int N, vector<double> *pvCoe, vector<int> *pvPowOfX, vector<int> *pvPowOfY); Description Fit a polynomial surface to the image data in an ROI Polynomial surface equation: z(x,y) = +C0 + C1 x + C3 x2 + C6 x3 + ... + C? xN +C2 y + C4 xy + C7 x2 y + ... +C5 y 2 + C8 xy 2 + ... +... + ... + ... +C(N +1)(N +2)/21 y N See Table 2 for common parameters the order of the surface equation (should be >= 0) store coecients, if succeed; or undened. store power of x of each term, if succeed; or undened. store power of y of each term, if succeed; or undened. After processing, the size of pvCoe, pvPowOfX and pvPowOfY will be (N+1)(N+2)/2 and their elements are ordered according to the index of C in the equation. true: succeeded; false: failed.

Parameters N pvCoe pvPowOfX pvPowOfY

Return

template <class T1, class T2> bool ImgFitPolynomialSurf (const T1 *pImg, int w1, int h1, const CRect<int> &rcROI1, const T2 *pWei, int w2, int h2, const CRect<int> &rcROI2, int N, vector<double> *pvCoe, vector<int> *pvPowOfX, vector<int> *pvPowOfY); Description Parameters pWei Weight version of ImgFitPolynomialSurf See Table 2 for common parameters weighting. (rcROI1, rcROI2 must be the same size)

3.74

ImgFitGauss

template <class T> bool ImgFitGauss (const T *pImg, int w, int h, const CRect<int> &rcROI, T threshold, double pdCoe[5]); Description Fit a 2D Gaussian function to image data of an ROI 2 2 Gaussian function: z = Ae(xB) /(2C)(yD) /(2E) . Fitting is based on a linear least squares method: the z coord of all points is converted to ln(z), which requires that the image data > 0. See Table 2 for common parameters image data < threshold are not used for tting. The threshold must be > 0 because of logarithm. parameters of the Gaussian function pdCoe[0], pdCoe[1], ... pdCoe[4] are A, B, ... E respectively. true: succeeded; false: failed.

Parameters threshold pdCoe Return

60

3.75

ImgFitImg

template <class T> bool ImgFitImg (const T1 *pImg1, int w1, int h1, const CRect<int> &rcROI1, const T2 *pImg2, int w2, int h2, const CRect<int> &rcROI2, int N, vector<double> *pvCoe); Description Fit a plane to image data of an ROI Let pImg1 and pImg2 be x and y respectively, the tting equation is y = C0 + C1 x + C2 x2 + ... + CN xN . The least squares method is applied to each pair of pixels in pImg1 and pImg2 to nd the coecients. See Table 2 for common parameters the order of the polynomial equation (should be >= 0) store coecients, if succeed; or undened. true: succeeded; false: failed.

Parameters N pvCoe Return

3.76

ImgLineData

template <class T> int ImgLineData (const T *pImg, int w, int h, const CRect<int> &rcROI, const CPt2D<int> &ptStart, const CPt2D<int> &ptEnd, vector<T> *pvDst, vector<CPt2D<int> > *pvPos = 0); Description Parameters ptStart ptEnd pvDst pvPos Return Get the image data falling on a line A point on the line is round o to integer sample accuracy. See Table 2 for common parameters start point of the line end point of the line store image data falling on the line store points on the line (input 0 to ignore) the number of pixels on the line

3.77

ImgLineSum

template <class T> int ImgLineSum (const T *pImg, int w, int h, const CRect<int> &rcROI, const CPt2D<int> &ptStart, const CPt2D<int> &ptEnd, double *pdSum); Description Get the sum of a lines data A point on the line is kept with subsample accuracy and obtains its datum by bilinear interpolation. See Table 2 for common parameters start point of the line end point of the line sum of the lines data the number of pixels on the line

Parameters ptStart ptEnd pdSum Return

3.78

ImgContour

template <class T1, class T2> void ImgContour (const T1 *pSrc, int w, int h, const CRect<int> &rcROI, T2 *pDst, int nContourLine); Description 1 2 3 Parameters pDst nContourLine Get contour lines of the image data in an ROI Compute each contour lines value. For each pixel, check which contour line is the nearest. Compare the pixels 4-way neighbours value. If the contour lines value is in between, then the pixel is a contour point. See Table 2 for common parameters image of contour object. size must be w*h. value = i represent the ith contour. background is 0. number of contour lines to extract

61

(a)

(b)

Figure 59: An example of the ImgContour function. (a) Source image. (b) Contours of intensity. Each gray scale represents a level of intensity.

3.79

ImgMask

template <class T1, class T2> void ImgMask (const T1 *pMask, int w1, int h1, const CRect<int> &rcROI1, T2 *pImg, int w2, int h2, const CRect<int> &rcROI2, T2 value); Description Set image data based on a mask image Pixels of pImg are set to the mask value, if the corresponding pixels in the mask image are <= 0. ROI1 and ROI2 must be the same size. See Table 2 for common parameters the mask value

Parameters value

3.80

ImgMaskPolygon

template <class T> void ImgMaskPolygon (T *pImg, int w, int h, const CRect<int> &rcROI, const CPt2D<int> *ppt, int nCount, T value, bool bMaskInner); Description Mask a polygon region The function rst creates an internal image mask by lling; then uses the mask to remove inner or outer image data. This strategy only works on simple polygons (no two non-adjacent edges intersect). If the ROI cuts the polygon into separate regions, only one of these regions will be masked. The main advantage of this function is speed. It is much faster than explicitly checking if each pixel in the ROI is in or out of the polygon region. See Table 2 for common parameters an array of polygon corners (size must be nCount) the number of polygon corners the value to ll the polygon region indicate if mask inner or outer of the polygon

Parameters ppt nCount value bMaskInner

(a)

(b)

Figure 60: An example of the ImgMaskPolygon function. (a) Source image. (b) A polygon region is masked with value 255.

62

3.81

ImgMandelbrot

template <class T> int ImgMandelbrot (T *pImg, int w, int h, const CRect<int> &rcROI, double dX1, double dY1, double dX2, double dY2, int nMaxIteration); Description Parameters pImg dX1 dY1 dX2 dY2 nMaxIteration Return Create a Mandelbrot pattern See Table 2 for common parameters output Mandelbrot image. Pixel value contains how many iterations used to decide that the point is in or out of the Mandelbrot set. minimum bound of the Mandelbrot set in the x direction minimum bound of the Mandelbrot set in the y direction maximum bound of the Mandelbrot set in the x direction maximum bound of the Mandelbrot set in the y direction maximum iterations to be applied the min iterations used among all points to reach a decision that whether a point is in or out of the Mandelbrot set

ROI

ROI

(a)

(b)

(c)

Figure 61: An example of the ImgMandelbrot function. (a) Large scale Mandelbrot image. dX1 = -2.05, dY1 = -1.3, dX2 = 0.7, dY2 = 1.3. (b) Zoom into the ROI shown in (a). (c) Zoom into the ROI shown in (b). The colors of the images are created by applying an intensity-to-color map.

3.82

ImgPhaseShifting
ImgPhaseShifting CRect<int> &rcROI1, CRect<int> &rcROI2, ImgPhaseShifting CRect<int> &rcROI1, CRect<int> &rcROI2, CRect<int> &rcROI3, CRect<int> &rcROI4,

template <class T1, class T2> void (T1 **ppSrc, int w1, int h1, const T2 *pPhase, int w2, int h2, const const T2 *pPS, int nStep); template <class T1, class T2> void (T1 **ppSrc, int w1, int h1, const T2 *pPhase, int w2, int h2, const T2 *pBK, int w3, int h3, const T2 *pCon, int w4, int h4, const const T2 *pPS, int nStep); Description

Parameters ppSrc pPhase pBK pCon pPS nStep

General phase-shifting algorithm The general phase-shifting algorithm takes an arbitrary number of (3) phase-shifted images to compute a wrapped phase image. The phase-shift angle of each image may also be arbitrary. All input images share the same ROI. T1 can be any integer or oat type. T2 must be oat or double to store the phase angles [, ]. See Table 2 for common parameters pointer to an array of images (array size = nStep) output wrapped phase image output background image output contrast image phase-shift value at each step (array size = nStep) the number of phase-shifting steps (at least 3)

63

(a)

(b)

(c)

(d)

(e)

(f)

Figure 62: An example of the ImgPhaseShifting function. (a) (b) (c) Three phase-shifted images. Although they look similar, the fringe pattern in each image shifts a constant phase angle. (d) Wrapped phase image. (e) Background intensity image. (f) Fringe contrast image.

3.83

ImgPhaseShifting Carre

template <class T1, class T2> T2 ImgPhaseShifting_Carre (T1 *ppSrc[4], int w1, int h1, const CRect<int> &rcROI1, T2 *pPhase, int w2, int h2, const CRect<int> &rcROI2); template <class T1, class T2> void ImgPhaseShifting_Carre (T1 **ppSrc[4], int w1, int h1, const CRect<int> &rcROI1, T2 *pPhase, int w2, int h2, const CRect<int> &rcROI2, T2 *pBK, int w3, int h3, const CRect<int> &rcROI3, T2 *pCon, int w4, int h4, const CRect<int> &rcROI4); Description Carr phase-shifting algorithm e Carr algorithm takes four images with a constant unknown phase shift. All e input images share the same ROI. T1 can be any integer or oat type. T2 must be oat or double to store the phase angles [, ]. See Table 2 for common parameters pointer to an array of images (array size = 4) output wrapped phase image output background image output contrast image the estimated constant phase shift at each step

Parameters ppSrc pPhase pBK pCon Return

3.84

ImgPhaseShifting 5Frame

template <class T1, class T2> T2 ImgPhaseShifting_5Frame (T1 *ppSrc[5], int w1, int h1, const CRect<int> &rcROI1, T2 *pPhase, int w2, int h2, const CRect<int> &rcROI2); template <class T1, class T2> void ImgPhaseShifting_5Frame (T1 **ppSrc[5], int w1, int h1, const CRect<int> &rcROI1, T2 *pPhase, int w2, int h2, const CRect<int> &rcROI2, T2 *pBK, int w3, int h3, const CRect<int> &rcROI3, T2 *pCon, int w4, int h4, const CRect<int> &rcROI4);

64

Description

Parameters ppSrc pPhase pBK pCon Return

5-frame phase-shifting algorithm This algorithm takes ve images with a constant unknown phase shift. All input images share the same ROI. T1 can be any integer or oat type. T2 must be oat or double to store the phase angles [, ]. See Table 2 for common parameters pointer to an array of images (array size = 5) output wrapped phase image output background image output contrast image the estimated constant phase shift at each step

3.85

ImgPhaseUnw LToR

template <class T> void ImgPhaseUnw_LToR (const T *pWph, int w1, int h1, const CRect<int> &rcROI1, T *pUnw, int w2, int h2, const CRect<int> &rcROI2); Description Parameters pWph pUnw Left-to-right phase unwrapping algorithm See Table 2 for common parameters input wrapped phase output unwrapped phase

(a)

(b)

Figure 63: An example of the ImgPhaseUnw LToR function. Wrapped phase image is as shown in Fig. 62(d). (a) Unwrapped phase image. (b) A linear carrier phase component is removed from the unwrapped phase image.

3.86

ImgPhaseUnw QualGui
<class T> void ImgPhaseUnw_QualGui *pWph, int w1, int h1, const CRect<int> &rcROI1, *pQual, int w2, int h2, const CRect<int> &rcROI2, *pUnw, int w3, int h3, const CRect<int> &rcROI3); Quality-guided phase unwrapping algorithm See Table 2 for common parameters input wrapped phase input quality map output unwrapped phase

template (const T T T

Description Parameters pWph pQual pUnw

3.87

ImgPhaseGradVar

template <class T> void ImgPhaseGradVar (const T *pPhase, int w1, int h1, const CRect<int> &rcROI1, T *pGradVar, int w2, int h2, const CRect<int> &rcROI2); Description Parameters pPhase pGradVar Get phase-gradient-variance image See Table 2 for common parameters input phase output the inverse of phase gradient variance 65

(a)

(b)

Figure 64: An example of the ImgPhaseUnw QualGui function. Wrapped phase image is as shown in Fig. 62(d). (a) Unwrapped phase image. (b) A linear carrier phase component is removed from the unwrapped phase image.

3.88

ImgFaceDetection

template <class T1, class T2> void ImgFaceDetection (const T1 *pImg, int w, int h, const CRect<int> &rcROI, T1 tContrast, int nMinFaceW, int nMaxFaceW, vector<T2> *pvSum, vector<T2> *pvSum2, vector<CLine2D<int> > *pvlnEye, vector<CRect<int> > *pvrcFace = 0); Description Parameters tContrast nMinFaceW nMaxFaceW pvlnEye pvrcFace pvSum pvSum2 Face detection algorithm See Table 2 for common parameters min contrast of a valid face region minimum possible face width in pixel maximum possible face width in pixel line from the left to the right eye ball of each detected face region of each detected face (For debugging purpose, input 0 to ignore.) summation of left-top region pixels summation of left-top region pixels square pvSum and pvSum2 are used internally. Their memory space are allocated only if necessary. the number of faces detected

Return

3.89

ImgSquareDetection

template <class T1, class T2> void ImgSquareDetection (const T1 *pImg, int w, int h, const CRect<int> &rcROI, T1 tContrast, int nMinSqu, int nMaxSqu, vector<T2> *pvSum, vector<CRect<int> > *pvRect); Description Detect black squares in an image Any square smaller than 6 pixels in width or larger than the image width or height/1.4 is ignored. See Table 2 for common parameters min contrast of a valid square region minimum possible square size in pixel maximum possible square size in pixel summation of left-top region pixels. pvSum is used internally. Its memory space are allocated only if necessary. region of each detected square the number of squares detected

Parameters tContrast nMinSqu nMaxSqu pvSum pvRect Return

3.90

ImgBlackSquareGrid

template <class T1, class T2> bool ImgBlackSquareGrid (const T1 *pImg, int w, int h, const CRect<int> &rcROI, T1 tContrast, int nMinSqu, int nMaxSqu, vector<T2> *pvSum, vector<CPt2D<double> > *pvptCor, int *pnCx, int *pnCy, 66

vector<CRect<int> > *pvRect = 0, vector<CPt2D<int> > *pvptEdge = 0, vector<CLine2D<int> > *pvlnEdge = 0, bool bRough = false); Description Detect a black square grid in an image In camera calibration, a black-square-grid pattern is often used. This function detects the corners of all the squares. Detect squares using ImgSquareDetection(..). Estimate corner locations by intersecting lines with outer squares. The lines are derived from the center of the four squares at the grid corner. Rene corner locations of each square by intersecting edge lines, which are tted to a squares edge points. See Table 2 for common parameters min contrast of a valid square region minimum possible square size in pixel maximum possible square size in pixel summation of left-top region pixels. pvSum is used internally. Its memory space are allocated only if necessary. the corner points of black square grid detected the number of square corners in each row. It is twice the number of squares in each row. the number of square corners in each column. It is twice the number of squares in each column. rough location of each square (input 0 to ignore) edge points on each square (input 0 to ignore) edge lines of each square (input 0 to ignore) indicate if search for rough corners only true: a black square grid is detected; false: squares are too small or the number of squares is not identical in each row or column.

1 2 3 Parameters tContrast nMinSqu nMaxSqu pvSum pvptCor pnCx pnCy pvRect pvptEdge pvlnEdge bRough Return

(a)

(b)

(c)

Figure 65: Examples of the ImgSquareDetection and ImgBlackSquareGrid functions. (a) ImgSquareDetection. (b) ImgBlackSquareGrid with bRough set to true. (c) ImgBlackSquareGrid with bRough set to false (retrieve rened corners).

3.91

ImgReadASCII

template <class T> bool ImgReadASCII (const char *pcFileName, vector<T> *pvImg, int *pW, int *pH); Description Parameters pcFileName pvImg pW pH Return Read image data from ASCII les Applicable to integer, oat ...; Not to char, unsigned char. See Table 2 for common parameters le name output image container image width image height true: succeeded; otherwise, false.

67

3.92

ImgSaveASCII

template <class T> bool ImgSaveASCII (const T *pImg, int w, int h, const CRect<int> &rcROI, const char *pcFileName); Description Save image data to an ASCII le Int, oat type will be saved as in numbers. char, unsigned char will be saved as characters, which may be undesired. So, if you want to save char value, convert it to int rst. See Table 2 for common parameters le name true: succeeded; otherwise, false.

Parameters pcFileName Return

3.93

ImgReadRaw

template <class T> bool ImgReadRaw (T *pImg, int w, int h, const CRect<int> &rcROI, const char *pcFileName, int nOffset); Description Read image data from a binary le The raw image data must match the data type T. The size of the data to be read is ROI.Width()*ROI.Height(). If the le cannot be opened, the input buer are unchanged. See Table 2 for common parameters le name oset in bytes from the beginning of the le, where raw image data start to be read. true: succeeded; otherwise, false.

Parameters pcFileName nOset Return

3.94

ImgSaveRaw

template <class T> bool ImgSaveRaw (const T *pImg, int w, int h, const CRect<int> &rcROI, const char *pcFileName, bool bAppend = false); Description Parameters pcFileName bAppend Return Save raw image data as a binary le See Table 2 for common parameters le name whether append to the end of the le or create a new le. If pcFileName does not exist, a new le will be created. true: succeeded; otherwise, false.

68

4
4.1

3D geometry classes and functions

CPt3D: 3D point class

template <class T> class CPt3D { public: T x, y, z; CPt3D<T>() : x(0), y(0), z(0) { } CPt3D<T>(const CPt3D<T> &pt) : x(pt.x), y(pt.y), z(pt.z) { } CPt3D<T>(T tx, T ty, T tz) : x(tx), y(ty), z(tz) { } CPt3D<T>& operator = (const CPt3D<T> &pt); CPt3D<T>& operator += (const CPt3D<T> &pt); CPt3D<T>& operator -= (const CPt3D<T> &pt); CPt3D<T> operator + (const CPt3D<T> &pt) const; CPt3D<T> operator - (const CPt3D<T> &pt) const; bool operator == (const CPt3D<T> &pt) const; bool operator != (const CPt3D<T> &pt) const; void SetPoint(T tx, T ty, T tz) { x = tx; y = ty; z = tz; } void Rotate(const CLine3D<T> &lnAxis, double dAngle); }; template <class T> CPt3D<T> operator * (T val, const CPt3D<T> &pt); template <class T> CPt3D<T> operator * (const CPt3D<T> &pt, T val); Variable x y z Function operator = operator + = operator = operator + operator operator == operator != operator * Function SetPoint Rotate Description x coordinate of the point y coordinate of the point z coordinate of the point Description Assignment operator *this = *this + pt *this = *this pt Return *this + pt Return *this pt Check if *this is equal to pt Check if *this is not equal to pt Each x, y, z coordinate multiples a value Description Set the x, y and z coordinates of the point Rotate the point with respect to an arbitrary line

4.2

CSize3D: 3D size class

template <class T> class CSize3D { public: T cx, cy, cz; CSize3D<T>() : cx(0), cy(0), cz(0) { } CSize3D<T>(const CSize3D<T> &size); CSize3D<T>(T tcx, T tcy, T tcz) : cx(tcx), cy(tcy), cz(tcz) { } CSize3D<T>& operator = (const CSize3D<T> &size); 69

CSize3D<T>& CSize3D<T>& CSize3D<T> CSize3D<T> bool bool

operator operator operator operator operator operator

+= -= + == !=

(const (const (const (const (const (const

CSize3D<T> CSize3D<T> CSize3D<T> CSize3D<T> CSize3D<T> CSize3D<T>

&size); &size); &size) const; &size) const; &size) const; &size) const;

void SetSize(T tcx, T tcy, T tcz) { cx = tcx; cy = tcy; cz = tcz; } }; Variable cx cy cz Function operator = operator + = operator = operator + operator operator == operator != Description size in x direction size in y direction size in z direction Description Assignment operator *this = *this + size *this = *this size Return *this + size Return *this size Check if *this is equal to size Check if *this is not equal to size

4.3

CLine3D: 3D line segment class

template <class T> class CLine3D { public: CLine3D<T>() : m_ptStart(0,0,0), m_ptEnd(0,0,0) { } CLine3D<T>(const CLine3D<T> &line); CLine3D<T>(T x1, T y1, T z1, T x2, T y2, T z2); CLine3D<T>(const CPt3D<T> &ptStart, const CPt3D<T> &ptEnd); CLine3D<T>& operator = (const CLine3D<T> &line); bool operator == (const CLine3D<T> &line) const; bool operator != (const CLine3D<T> &line) const; CPt3D<T> CPt3D<T> CPt3D<T> double void void void void void void bool bool Start() const; End() const; Center() const; Length() const; SetLine (const CPt3D<T> &ptStart, const CPt3D<T> &ptEnd); SetStart (const CPt3D<T> &pt); SetEnd (const CPt3D<T> &pt); SetCenter (const CPt3D<T> &pt); Offset (T x, T y, T z); Offset (const CPt3D<T> &ptOffset); GetPointAt(double dDist, CPt3D<T> *ppt) const; IntersectPlane(const CPt3D<T> &ptVec, const CPt3D<T> &ptArb, CPt3D<T> *ppt);

private: CPt3D<T> m_ptStart, m_ptEnd; // Start and end point }; Function operator = operator == operator != Description Assignment operator Check if *this is equal to line Check if *this is not equal to line

70

Function Start End Center Length SetLine SetStart SetEnd SetCenter Oset GetPointAt

Description Get the start point of the line Get the end point of the line Get the center of the line Get the length of the line Set the start and the end points of the line Set the start point of the line Set the end point of the line Set the center of the line Oset the position of the line Get a point on the line that has a specied distance from the star point. Take the start point as a reference, dDist > 0 indicates the point is at the same side as the end point; while dDist < 0 indicates the point is at the opposite side of the end point. the distance of the point from the start point. the point found true: point found; false: cannot nd such a point. Get the intersect of the line segment with a plane normal vector of the plane an arbitrary point on the plane store intersection point if found true: intersect found; false: no intersect.

dDist ppt Return IntersectPlane ptVec ptArb ppt Return

4.4

CCube: cube class

template <class T> class CCube { public: T left, top, front, right, bottom, back; CCube<T>() : left(0), top(0), front(0), right(0), bottom(0), back(0) { } CCube<T>(const CCube<T> &cube); CCube<T>(T lt, T tp, T ft, T rt, T bm, T bk); CCube<T>(const CRect<T>& rect, T ft, T bk); CCube<T>& operator = (const CCube<T> &cube); CCube<T>& operator &= (const CCube<T> &cube); CCube<T>& operator |= (const CCube<T> &cube); CCube<T> operator & (const CCube<T> &cube) const; CCube<T> operator | (const CCube<T> &cube) const; bool operator == (const CCube<T> &cube) const; bool operator != (const CCube<T> &cube) const; bool T T T CSize3D<T> CPt3D<T> CPt3D<T> void void void void void void void bool IsEmpty() const; Width() const; Height() const; Depth() const; Size() const; Center() const; LeftTopFront() const; SetCube(T lt, T tp, T ft, T rt, T bm, T bk); Inflate(T lt, T tp, T ft, T rt, T bm, T bk); Deflate(T lt, T tp, T ft, T rt, T bm, T bk); Inflate(T x, T y, T z); Deflate(T x, T y, T z); Offset (T x, T y, T z); Offset (const CPt3D<T> &ptOffset); PtIn (T x, T y, T z) const;

71

bool }; Variable left top front right bottom back

PtIn

(const CPt3D<T>& pt) const; Description left bound of the cube top bound of the cube front bound of the cube right bound of the cube bottom bound of the cube back bound of the cube Description Assignment operator *this = Intersect of two cubes *this = Union of two cubes Return intersect of two cubes Return union of two cubes Check if *this is equal to cube Check if *this is not equal to cube Description Check if it is an empty cube. A cube is empty if its width, height or depth is <= 0. Get the width (right lef t) of the cube Get the height (bottom top) of the cube Get the depth (back f ront) of the cube Get the size of the cube Return the center of the cube Return the left-top-front point of the cube Description Set the left, top, front, right, bottom and back value of the cube Inate the cube by lt, tp, ft, rt, bm, bk on the left, top, front, right, bottom and back sides respectively. Inate the cube by x on the left and right sides, by y on the top and bottom sides, and by z on the front and back sides respectively. Deate the cube by lt, tp, ft, rt, bm, bk on the left, top, front, right, bottom and back side respectively. Deate the cube by x on the left and right sides, by y on the top and bottom sides, and by z on the front and back sides respectively. Oset the position of the cube Check if a point is inside the cube. A point is side a cube, if pt.x [lef t, right) AND pt.y [top, bottom) AND pt.z [f ront, back),

Function operator = operator &= operator |= operator & operator | operator == operator != Function IsEmpty Width Height Depth Size Center LeftTopFront Function SetCube Inate

Deate

Oset PtIn

4.5

CTri3D: 3D triangle class

template <class T> class CTri3D { public: CTri3D<T>() { } CTri3D<T>(const CTri3D<T> &triangle); CTri3D<T>& operator = (const CTri3D<T> &triangle); CPt3D<T> operator [] (int idx) const { return m_ppt[idx]; } CPt3D<T>& operator [] (int idx) { return m_ppt[idx]; } const CPt3D<T>& Vertex(int idx) const; void SetVertex(int idx, const CPt3D<T> &pt); void ReverseVertexSequence(); private: 72

CPt3D<T> m_ppt[3]; }; Function operator = operator [ ] Description Assignment operator Get vertex operator. Valid index is 0, 1, and 2. The 1st operator [ ] is for retrieving a vertex value. The 2nd operator [ ] is for setting a vertex value. Get a vertex value. Valid index is 0, 1, and 2. Set a vertex value. Valid index is 0, 1, and 2. Reverse vertex sequence. Example: Old sequence: tri[0] = pt1, tri[1] = pt2, tri[2] = pt3. New sequence: tri[0] = pt3, tri[1] = pt2, tri[2] = pt1.

Vertex SetVertex ReverseVertexSequence

4.6

CPoly3D: 3D polygon class

template <class T> class CPoly3D { public: CPoly3D<T>() { } CPoly3D<T>(const CPoly3D<T> &poly); CPoly3D<T>(int nCount, const CPt3D<T> &pt); CPoly3D<T>& operator = (const CPoly3D<T> &poly); int Count() const { return int(m_vpt.size()); } const CPt3D<T>& Vertex(int idx) const; void AddVertex( const CPt3D<T> &pt); void SetVertex(int idx, const CPt3D<T> &pt); void Clear() { m_vpt.clear(); } void ReverseVertexSequence(); private: vector<CPt3D<T> > m_vpt; }; Function operator = Count Vertex AddVertex SetVertex Clear ReverseVertexSequence Description Assignment operator Get the number of vertices of the polygon Get the idx-th vertex of the polygon Add a vertex at the end of the vertex list Set the idx-th vertex value Remove all vertices of the polygon Reverse vertex sequence

4.7

CCylinder: cylinder class

template <class T> class CCylinder { public: CCylinder<T>() : m_Radius(0) { } CCylinder<T>(const CCylinder<T> &cylinder); CCylinder<T>(const CLine3D<T> &lnCenter, T radius); CCylinder<T>& operator = (const CCylinder<T> &cylinder); CLine3D<T> T void void void CenterLine() const { return m_lnCenter; } Radius() const { return m_Radius; } SetCenterLine(const CLine3D<T> &lnCenter); SetRadius(T radius) { m_Radius = radius; } SetCylinder(const CLine3D<T> &lnCenter, T radius);

73

private: CLine3D<T> m_lnCenter; // center line of the cylinder T m_Radius; // radius of the cylinder }; Function operator = CenterLine Radius SetCenterLine SetRadius SetCylinder Description Assignment operator Get the center line of the cylinder Get the radius of the cylinder Set the center line of the cylinder Set the radius of the cylinder Set the center line and radius of the cylinder

40

radius

20

center line
0 60 40 20 0 0

-20

-40 60

40

20

Figure 66: An example of a cylinder.

4.8

Distance

template <class T> double Distance (const CPt3D<T> &pt1, const CPt3D<T> &pt2); Description pt1 pt2 Return Get the distance between two points 1st input point 2nd input point the distance between the two points

4.9

Area

template <class T> double Area (const CPt3D<T> &pt1, const CPt3D<T> &pt2, const CPt3D<T> &pt3); Description pt1, pt2, pt3 Return Get the area enclosed by three points input points the area enclosed by three points

4.10

Angle

template <class T> double Angle (const CPt3D<T> &pt1, const CPt3D<T> &pt2, const CPt3D<T> &pt3); Description pt1 pt2 pt3 Return Get the angle in [0, ], formed by pt2, pt1, pt3 1st input point (vertex of the angle) 2nd input point 3rd input point the angle formed by pt2, pt1, pt3

74

4.11

MidPoint

template <class T> CPt3D<T> MidPoint (const CPt3D<T> &pt1, const CPt3D<T> &pt2); Description pt1 pt2 Return Get the midpoint of two points 1st input point 2nd input point the midpoint

4.12

Centroid

template <class T> CPt3D<T> Centroid (const CPt3D<T> *ppt, int nCount); Description ppt nCount Return Get the centroid of a set of points an array of points the number of points the centroid of the input points

4.13

Collinear

template <class T> bool Collinear (const CPt3D<T> &pt1, const CPt3D<T> &pt2, const CPt3D<T> &pt3); Description pt1, pt2, pt3 Return Check collinearity of three points input points true: collinear; otherwise, false.

4.14

NormalVector

template <class T> CPt3D<T> NormalVector (const CPt3D<T> &pt1, const CPt3D<T> &pt2, const CPt3D<T> &pt3); Description Get normal vector of a plane Three points denes a plane. This function returns the normal vector of the plane. If the input points are collinear, the return value is (0,0,0). input points true: collinear; otherwise, false.

pt1, pt2, pt3 Return

4.15

Volume

template <class T> double Volume (const CPt3D<T> &pt0, const CPt3D<T> &pt1, const CPt3D<T> &pt2, const CPt3D<T> &pt3); Description Get the volume of a tetrahedron The tetrahedrons four vertices are given by pt0, ... pt3. If right-hand rule applies (Four ngers curve in the order of pt1, pt2, pt3; and the thumb points to pt0.), the volume is positive; otherwise the volume is negative. tetrahedrons 4 vertices volume of the tetrahedron Internal volume computation is based on double; therefore, for integer data type, it is better to determine the volume sign by testing if the volume is > 0.5 or < -0.5 rather than > 0 or < 0. This helps to prevent oat precision errors.

pt0, ... pt3 Return Note

4.16

ConvexHull3D

template <class T> bool ConvexHull3D (vector<CPt3D<T> > *pvptIn, vector<CPt3D<T> > *pvptOut, vector<CLine3D<T> > *pvLine, vector<CPoly3D<T> > *pvPoly, bool bTriFace);

75

Description

pvptIn pvptOut pvLine pvPoly bTriFace

Return

Get the 3D convex hull of a set of points Reference Computational geometry in C by Joseph ORourke. Based on the book, the convex hull is composed of triangles. I add a postprocessing step to output polygon faces of the hull. ConstructPolygon(..) is for this purpose. Due to volume computation required by the function, large input value may render the computation go out of range. I roughly tested that 1024 is a very safe bound. You can try higher value but be careful. input point set; (modied during processing) output convex hull vertexes (input 0 to ignore) output convex hull edges (input 0 to ignore) output convex hull polygon faces (must NOT be 0) if true, output triangular faces that may be coplanar. This is used for DelaunayTriangulation. if false, output non-coplanar polygon faces. true: succeeded; false: failed (points are coplanar).

40

Z
20 0 100 50

0 0

20

40

60

80

100

Figure 67: An example of the ConvexHull3D function.

4.17

FitPlane

template <class T1, class T2> bool FitPlane (const CPt3D<T1> *ppt, const T2 *pWei, int nCount, double *pdKx, double *pdKy, double *pdZ0); Description ppt pWei nCount pdKx pdKy pdZ0 Return Least squares tting of a plane Plane equation z(x,y) = Kx*x + Ky*y + Z0 points to be tted (size must be nCount) weighting factor array (input 0 to ignore) size of ppt array and weighting array parameter Kx of the plane equation, if succeed; or undened. parameter Ky of the plane equation, if succeed; or undened. parameter Z0 of the plane equation, if succeed; or undened. true: succeeded; false: failed.

4.18

FitPolynomialSurf

template <class T1, class T2> bool FitPolynomialSurf (const CPt3D<T1> *ppt, const T2 *pWei, int nCount, int N, vector<double> *pvCoe, vector<int> *pvPowOfX, vector<int> *pvPowOfY); Description Least squares tting of a polynomial surface Polynomial surface equation: z(x,y) = +C0 + C1 x + C3 x2 + C6 x3 + ... + C? xN +C2 y + C4 xy + C7 x2 y + ... continued on next page

76

ppt pWei N pvCoe pvPowOfX pvPowOfY

Return

+C5 y 2 + C8 xy 2 + ... +... + ... + ... +C(N +1)(N +2)/21 y N points to be tted (size must be nCount) weighting factor array (input 0 to ignore) the order of the surface equation (should be >= 0) store coecients, if succeed; or undened. store power of x of each term, if succeed; or undened. store power of y of each term, if succeed; or undened. After processing, the size of pvCoe, pvPowOfX and pvPowOfY will be (N+1)(N+2)/2 and their elements are ordered according to the index of C in the equation. true: succeeded; false: failed.

4000

100

2000

50 0 0 50 50 100 0 50

X
100 0

100 100

80

60

40

20

(a)

(b)

Figure 68: Examples of the (a) FitPlane and the (b) FitPolynomialSurf functions.

4.19

FitGauss

template <class T> bool FitGauss (const CPt3D<T> *ppt, int nCount, double pdCoe[5]); Description Least squares tting of a 2D Gaussian function 2 2 Gaussian function: z = Ae(xB) /(2C)(yD) /(2E) . Fitting is based on a linear least squares method: the z coordinate of all points is converted to ln(z), which requires that z > 0. points to be tted (size must be nCount) size of ppt array parameters of the Gaussian function pdCoe[0], pdCoe[1], ... pdCoe[4] are A, B, ... E respectively. true: succeeded; false: failed.

ppt nCount pdCoe Return

40

Z
20 0 100 50

0 0

20

40

60

80

100

Figure 69: An example of the 2D FitGauss function.

77

3D image processing functions

Type T* Name pImg Description Pointer to a continuous memory space which must be equal to or larger than w*h*d*sizeof(T) bytes. The z-th frame, y-th row, x-th column element can be retrieved by *(pImg+(z*h+y)*w+x) or pImg[(z*h+y)*w+x]. Pointer to the source image Pointer to the destination image Image width, height and depth Region of interest. Only image data within the ROI will be used or modied.

Some parameters are common to most functions. They are listed in Table 3.

T* T* int CCube<int>&

pSrc pDst w, h, d cbROI

Table 3: Common parameters of 3D image processing functions.

5.1

ImgAssign3D

template <class T> void ImgAssign3D (T *pImg, int w, int h, int d, const CCube<int> &cbROI, T value); Description Parameters value Assign image data in an ROI to the input value See Table 3 for common parameters the value to be assigned to the image data

5.2

ImgCopy3D

template <class T1, class T2> void ImgCopy3D (const T1 *pSrc, int w1, int h1, int d1, const CCube<int> &cbROI1, T2 *pDst, int w2, int h2, int d2, const CCube<int> &cbROI2); Description Parameters Copy image data from source image ROI1 to destination image ROI2 Width, height and depth of ROI1 and ROI2 must be the same. See Table 3 for common parameters

5.3

ImgCopyXY 2D

template <class T1, class T2> void ImgCopyXY_2D (const T1 *pSrc, int w1, int h1, int d1, const CRect<int> &rcROI1, int z, T2 *pDst, int w2, int h2, const CRect<int> &rcROI2); Description Parameters z Copy ROI1 in a X-Y slice of a 3D image to ROI2 in a 2D image See Tables 2 and 3 for common parameters z-direction index of the X-Y slice in the 3D image

5.4

ImgCopyXZ 2D

template <class T1, class T2> void ImgCopyXZ_2D (const T1 *pSrc, int w1, int h1, int d1, const CRect<int> &rcROI1, int y, T2 *pDst, int w2, int h2, const CRect<int> &rcROI2); Description Parameters y Copy ROI1 in a X-Z slice of a 3D image to ROI2 in a 2D image See Table 2 and 3 for common parameters y-direction index of the X-Z slice in the 3D image

78

5.5

ImgCopyYZ 2D

template <class T1, class T2> void ImgCopyYZ_2D (const T1 *pSrc, int w1, int h1, int d1, const CRect<int> &rcROI1, int x, T2 *pDst, int w2, int h2, const CRect<int> &rcROI2); Description Parameters x Copy ROI1 in a Y-Z slice of a 3D image to ROI2 in a 2D image See Table 2 and 3 for common parameters x-direction index of the Y-Z slice in the 3D image

5.6

ImgCopy2D XY

template <class T1, class T2> void ImgCopy2D_XY (const T1 *pSrc, int w1, int h1, const CRect<int> &rcROI1, T2 *pDst, int w2, int h2, int d2, const CRect<int> &rcROI2, int z); Description Parameters z Copy ROI1 in a 2D image to ROI2 in a X-Y slice of a 3D image See Tables 2 and 3 for common parameters z-direction index of the X-Y slice in the 3D image

5.7

ImgCopy2D XZ

template <class T1, class T2> void ImgCopy2D_XZ (const T1 *pSrc, int w1, int h1, const CRect<int> &rcROI1, T2 *pDst, int w2, int h2, int d2, const CRect<int> &rcROI2, int y); Description Parameters y Copy ROI1 in a 2D image to ROI2 in a X-Z slice of a 3D image See Tables 2 and 3 for common parameters y-direction index of the X-Z slice in the 3D image

5.8

ImgCopy2D YZ

template <class T1, class T2> void ImgCopy2D_YZ (const T1 *pSrc, int w1, int h1, const CRect<int> &rcROI1, T2 *pDst, int w2, int h2, int d2, const CRect<int> &rcROI2, int x); Description Parameters x Copy ROI1 in a 2D image to ROI2 in a Y-Z slice of a 3D image See Tables 2 and 3 for common parameters x-direction index of the Y-Z slice in the 3D image

5.9

ImgLinear3D

template <class T1, class T2> void ImgLinear3D (const T1 *pSrc, int w1, int h1, int d1, const CCube<int> &cbROI1, T2 *pDst, int w2, int h2, int d2, const CCube<int> &cbROI2, T1 fromMin, T1 fromMax, T2 toMin, T2 toMax); Description Linear translate Src data in the range [fromMin, fromMax] to Dst data to the range [toMin, toMax]. Linear translation parameters a and b is determined by: a * fromMin + b = toMin; a * fromMax + b = toMax; Data points in Src that are < fromMin or > fromMax will be translate to toMin and toMax. pSrc and pDst may point to the same image buer, if ROI1 and ROI2 are the same. See Table 3 for common parameters source minimum bound source maximum bound destination minimum bound destination maximum bound

Parameters fromMin fromMax toMin toMax

79

5.10

ImgMin3D

template <class T> T ImgMin3D (const T *pImg, int w, int h, int d, const CCube<int> &cbROI); Description Parameters Return Get the minimum value of an ROI See Table 3 for common parameters the minimum value of an ROI

5.11

ImgMax3D

template <class T> T ImgMax3D (const T *pImg, int w, int h, int d, const CCube<int> &cbROI); Description Parameters Return Get the maximum value of an ROI See Table 3 for common parameters the maximum value of an ROI

5.12

ImgMinMax3D

template <class T> void ImgMinMax3D (const T *pImg, int w, int h, int d, const CCube<int> &cbROI, T *pMin, T *pMax); Description Parameters pMin pMax Get the minimum and maximum value of an ROI See Table 3 for common parameters return the minimum value of an ROI return the maximum value of an ROI

5.13

ImgMean3D

template <class T> T ImgMean3D (const T *pImg, int w, int h, int d, const CCube<int> &cbROI); Description Parameters Return Get the mean value of an ROI See Table 3 for common parameters the mean value of an ROI

5.14

ImgFltMean3D
T> void ImgFltMean3D int w1, int h1, int d1, const CCube<int> &cbROI1, int w2, int h2, int d2, const CCube<int> &cbROI2, nKerH, int nKerD); Mean lter, kernel certer equal to kernel mean Half-lter-length data at the ROI boundary are ltered with reduced sized kernel. See Table 3 for common parameters lter kernel width lter kernel height lter kernel depth nKerW*nKerH*nKerD = 3*3*3 or 7*5*3

template <class (const T *pSrc, T *pDst, int nKerW, int Description

Parameters nKerW nKerH nKerD Example

5.15

ImgFltVariance3D

template <class T1, class T2> void ImgFltVariance3D (const T1 *pSrc, int w1, int h1, int d1, const CCube<int> &cbROI1, T2 *pDst, int w2, int h2, int d2, const CCube<int> &cbROI2, int nKerW, int nKerH, int nKerD);

80

Description

Parameters nKerW nKerH nKerD Example

Variance lter, kernel certer equal to kernel variance Half-lter-length data at the ROI boundary are ltered with reduced sized kernel. See Table 2 for common parameters lter kernel width lter kernel height lter kernel depth nKerW*nKerH = 3*3 or 7*5

5.16

ImgConv3DZ

template <class T1, class T2> void ImgConv3DZ (T1 *pImg, int w, int h, int d, const CCube<int> &cbROI, const T2 *pMask, int nLen); Description 1D convolution in z direction Convolution is applied on each trace (z direction). Half-lter-length data at the ROI boundary are unchanged. The mask data array size must satisfy nLen+(nLen-1)/2 ROI.Depth(); otherwise nothing is done. See Table 3 for common parameters pointer to the convolution mask data array mask array size

Parameters pMask nLen

5.17

ImgResize3D

template <class T1, class T2> void ImgResize3D (const T1 *pSrc, int w1, int h1, int d1, const CCube<int> &cbROI1, T2 *pDst, int w2, int h2, int d2, const CCube<int> &cbROI2, int nAlgo); Description Resize ROI1 of Src and copy to ROI2 of Dst If linear (nAlgo: 1) or spline (nAlgo: 24) is used, minication is always a downsampling process based on averaging. Magnication is done by the specied method. If nearest neighbour (nAlgo: 0) is used, both minication and magnication are based on nearest neighbour. See Table 3 for common parameters interpolation algorithm 0: nearest neighbour interpolation, 1: linear interpolation, 2: cubic B-spline interpolation, 3: Catmull-Rom spline interpolation, 4: natural cubic spline interpolation.

Parameters nAlgo

5.18

ImgRotate3D

template <class T1, class T2> void ImgRotate3D (const T1 *pSrc, int w1, int h1, int d1, const CCube<int> &cbROI1, T2 *pDst, int w2, int h2, int d2, const CCube<int> &cbROI2, int nAxis, int nAngle); Description Rotate ROI1 of Src and copy to ROI2 of Dst The size of ROI1 and ROI2 must satisfy certain relationship based on the angle of rotation. See Table 3 for common parameters with respect to which axis to rotate. 0: X axis (points to the right), 1: Y axis (points to the bottom), 2: Z axis (points outside the screen). anti-clock wise angle (right-hand rule) of rotation in degree. Only multiples of 90-degree are accepted.

Parameters nAxis nAngle

81

5.19

ImgFlip3D

template <class T> void ImgFlip3D (T *pImg, int w, int h, int d, const CCube<int> &cbROI, int nDirection); Description Parameters nDirection Flip the image data in an ROI See Table 3 for common parameters 0: left-right ipped, 1: top-bottom ipped, 2: front-back ipped.

5.20

ImgMatch3D

template <class T> void ImgMatch3D (const T *pMother, int w1, int h1, int d1, const CCube<int> &cbROI1, const T *pChild, int w2, int h2, int d2, const CCube<int> &cbROI2, int nDSX, int nDSY, int nDSZ, CPt3D<int> *pptMatch, double *pdCorr); Description Search for ROI2 of pChild in ROI1 of pMother ROI1.Width() must be >= ROI2.Width() ROI1.Height() must be >= ROI2.Height() ROI1.Depth() must be >= ROI2.Depth() Initially, ROI2 is matched to windows in ROI1 separated by nDSX, nDSY and nDSZ in the x, y and z directions. After the best-match window is found; nDSX, nDSY and nDSZ are halved. Then ROI2 is matched to 27 windows, a 3*3*3 grid centered on the bestmatch window. The windows are separated by nDSX, nDSY and nDSZ. After a new best-match window is found, nDSX, nDSY and nDSZ are further halved. Go back to 2 until nDSX, nDSY and nDSZ equal to 1 pixel. See Table 3 for common parameters initial downsampling gap in x direction initial downsampling gap in y direction initial downsampling gap in z direction The downsampling gaps are used in shifting ROI1 across ROI2 and in accessing the pixels in ROI1 and ROI2, the best-match point in ROI1 coordinate (left-top-front corner of the matched cube) normalized correlation coecient, in [-1,1]

3 Parameters nDSX nDSY nDSZ

pptMatch pdCorr

5.21

ImgMotion3D

template <class T> void ImgMotion3D (const T *pImg1, int w1, int h1, int d1, const CCube<int> &cbROI1, const T *pImg2, int w2, int h2, int d2, const CCube<int> &cbROI2, int nCoarW, int nCoarH, int nCoarD, int nCoarX, int nCoarY, int nCoarZ, int nCoarDSX, int nCoarDSY, int nCoarDSZ, int nFineW, int nFineH, int nFineD, int nFineX, int nFineY, int nFineZ, int nFineDSX, int nFineDSY, int nFineDSZ, int &nWinX, int &nWinY, int &nWinZ, vector<CPt3D<int> > *pvptCenter, vector<CPt3D<int> > *pvptDisp, vector<double> *pvCorr); Description Pixel ow or motion estimation Estimate the pixel motion from ROI1 in pImg1 to ROI2 in pImg2. ROI1 and ROI2 must be the same size. continued on next page

82

3 Parameters nCoarW nCoarH nCoarD nCoarX nCoarY nCoarZ nCoarDSX nCoarDSY nCoarDSZ nFineW nFineH nFineD nFineX nFineY nFineZ nFineDSX nFineDSY nFineDSZ nWinX nWinY nWinZ pvptCenter pvptDisp pvCorr

There are two levels of search: a coarse search based on a few coarse windows and a quality-guided ne search on all ne windows. Results of the coarse search are used as the initial guess for the ne search. A large coarse search window and search distance may be used to obtain robust initial estimates, and a small ne search window and search distance to obtain a high resolution. The downsampling gap at each level is set independently. See ImgMatch3D(...) for details of the downsampling gap. Results are stored in pvptCenter, pvptDisp, pvCorr, which are arrays of the same size: nWinX * nWinY * nWinZ (at output). See Table 3 for common parameters coarse search window width coarse search window height coarse search window depth coarse search distance in x direction coarse search distance in y direction coarse search distance in z direction coarse search downsampling gap in x direction coarse search downsampling gap in y direction coarse search downsampling gap in z direction ne search window width ne search window height ne search window depth ne search distance in x direction ne search distance in y direction ne search distance in z direction ne search downsampling gap in x direction ne search downsampling gap in y direction ne search downsampling gap in z direction input desired number of ne search windows in x direction output actual number of ne search windows in x direction input desired number of ne search windows in y direction output actual number of ne search windows in y direction input desired number of ne search windows in z direction output actual number of ne search windows in z direction center of ne search windows in pImg1 displacement of ne windows from pImg1 to pImg2. This includes the global shift from ROI1 to ROI2 correlation coecient of each ne window

5.22

ImgLabeling3D

template <class T1, class T2, class Pred> int ImgLabeling3D (const T1 *pSrc, int w1, int h1, int d1, const CCube<int> &cbROI1, T2 *pDst, int w2, int h2, int d2, const CCube<int> &cbROI2, Pred pred, int nConnectivity, int nMinVol = 0, int nMaxVol = 0, vector<CCube<int> > *pvCube = 0, vector<int> *pvVol = 0); Description Parameters pred nConnectivity Connectivity labeling algorithm See Table 3 for common parameters if pred(pSrc[(z*h+y)*w+x]) is true, the point (x,y,z) is considered an object point. Euclidean connectivity of an object. 0: 6-neighbour labeling algorithm, 1: 26-neighbour labeling algorithm, >1: pixels within this distance are one object. Object fewer than nMinVol pixels are discarded. Object larger than nMaxVol pixels are discarded. continued on next page

nMinVol nMaxVol

83

pvCube

pvVol Return Example

bounding cube of each object (input 0 to ignore) It is with respect to ROI2. To obtain a bounding cube with respect to ROI1, each cube should be oset cb1.LeftTopFront()-cb2.LeftTopFront(). number of points of each object (input 0 to ignore) the number of objects found The 1st object can be found by checking if(pDst[(z*h+y)*w+x]==1). The 1st objects bounding cube is (*pvCube)[0]. The 3rd objects number of points is (*pvVol)[2].

5.23

ImgFilling3D

template <class T, class Pred> void ImgFilling3D (T *pImg, int w, int h, int d, const CCube<int> &cbROI, T value, Pred pred, CPt3D<int> ptSeed, int nConnectivity); Description Parameters value pred Fill a region bounded by a predicate condition See Table 3 for common parameters value to ll with if pred(pImg[(z*h+y)*w+x],value) is true, the point (x,y,z) is considered boundary. Only three predicates are valid: equal to, greater equal, less equal. Other predicates such as greater or less may cause dead loop, so they should be strictly prohibited. initial seed point for lling Euclidean connectivity of a lling region. 0: 6-neighbour lling algorithm, 1: 26-neighbour lling algorithm, >1: pixels within this distance are lled.

ptSeed nConnectivity

5.24

ImgDistTrans3D

template <class T> void ImgDistTrans3D (const T *pSrc, int w1, int h1, int d1, const CCube<int> &cbROI1, unsigned long *pnDst, int w2, int h2, int d2, const CCube<int> &cbROI2, double dZSpacing, T threshold); Description Parameters pnDst dZSpacing threshold Distance transform algorithm Reference Euclidean Distance Mapping by P. Danielsson. See Table 3 for common parameters a background pixel is set to 0; an object pixel is set to the square of the Euclidean distance to its nearest background pixel. frame spacing in z direction. The pixel spacing in the x and y directions is assumed to be 1. pixels >= threshold in pSrc are objects; pixels < threshold in pSrc are background.

5.25

ImgWatershed3D

template <class T1, class T2> int ImgWatershed3D (const T1 *pSrc, int w1, int h1, int d1, const CCube<int> &cbROI1, T2 *pDst, int w2, int h2, int d2, const CCube<int> &cbROI2, int nDist, int nMinPts); Description Watershed algorithm for segmentation This function assumes the input pSrc a distance map, for example, obtained from ImgDistTrans3D(...). It outputs an object map similar to that produced by ImgLabeling3D(...). In the object map, connected regions are segmented. continued on next page

84

1 2 3 4 Parameters nDist

nMinPts Return

Local maxima are located for each object. The rst-pass propagation estimates the number of points grown by each maxima within each object. Maxima whose number of points are < nMinPts are discarded. The second-pass propagation nishes the segmentation. See Table 3 for common parameters the distance for merging local maxima. 0: 6-neighbour merging, 1: 26-neighbour merging, >1: local maxima within this distance are merged. threshold of the number of points grown by a maximum. Both parameters are used to reduce over-segmentation. The number of segmented objects, if succeeded; otherwise -1.

5.26

ImgIsoSurface

template <class T1, class T2> int IsoSurface (const T *pImg, int w, int h, int d, const CCube<int> &cbROI, T threshold, int nFltSize, vector<CTri3D<float> > *pvTri); Description Extract isosurface from 3D data Reference Regularised marching tetrahedra: improved iso-surface extraction by Graham Treece et al. Binarize the 3D data based on the input threshold. The 3D data are best to have the same pixel spacing in x, y and z directions but it is not a requirement. Compute a distance map, which represents the distance of each voxel to the object boundary. A distance code 22-31-38 is used. (Voxel width: 22. Diagonal: 31. Double diagonal: 38.) Voxels inside the object are > 0 and those outside are < 0. Refer to the paper Distance transformations in arbitrary dimensions by Gunilla Borgefors for basic ideas. Smooth the distance map, if nFltSize is > 1. Use body-centered cube layout (partitioned by tetrahedra) to extract isosurface. See Table 3 for common parameters threshold for the object region lter kernel size (ignored if <= 1) output triangles of the isosurface the number of triangles on the isosurface

3 4 Parameters threshold nFltSize pvTri3D Return

180

160

140

Z
120 100 80 100 150

100 150

Figure 70: An example of the ImgIsoSurface function. Isosurface of a sphere.

5.27

ImgReadRaw3D

template <class T> bool ImgReadRaw3D (T *pImg, int w, int h, int d, const CCube<int> &cbROI, const char *pcFileName, int nOffset);

85

Description

Parameters pcFileName nOset Return

Read image data from a binary le The raw image data must match the data type T. The size of the data to be read is ROI.Width()*ROI.Height()*ROI.Depth(). If the le cannot be opened, the input buer are unchanged. See Table 3 for common parameters le name oset in bytes from the beginning of the le, where raw image data start to be read. true: succeeded; otherwise, false.

5.28

ImgSaveRaw3D

template <class T> bool ImgSaveRaw3D (const T *pImg, int w, int h, int d, const CCube<int> &cbROI, const char *pcFileName, bool bAppend = false); Description Parameters pcFileName bAppend Return Save raw image data as a binary le See Table 3 for common parameters le name whether append to the end of the le or create a new le. If pcFileName does not exist, a new le will be created. true: succeeded; otherwise, false.

86