OpenCV Reference Manual

v2.2

December, 2010
2
Contents

I C API Reference 43

1 core. The Core Functionality 45

1.1 Basic Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
CvPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
CvPoint2D32f . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
CvPoint3D32f . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
CvPoint2D64f . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
CvPoint3D64f . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
CvSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
CvSize2D32f . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
CvRect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
CvScalar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
CvTermCriteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
CvMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
CvMatND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
CvSparseMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
IplImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
CvArr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
1.2 Operations on Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
cv::AbsDiff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
cv::AbsDiffS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
cv::Add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
cv::AddS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
cv::AddWeighted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
cv::And . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
cv::AndS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
cv::Avg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
cv::AvgSdv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
cv::CalcCovarMatrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

3
4 CONTENTS

cv::CartToPolar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
cv::Cbrt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
cv::ClearND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
cv::CloneImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
cv::CloneMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
cv::CloneMatND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
cv::CloneSparseMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
cv::Cmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
cv::CmpS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
cv::ConvertScale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
cv::ConvertScaleAbs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
cv::CvtScaleAbs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
cv::Copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
cv::CountNonZero . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
cv::CreateData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
cv::CreateImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
cv::CreateImageHeader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
cv::CreateMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
cv::CreateMatHeader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
cv::CreateMatND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
cv::CreateMatNDHeader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
cv::CreateSparseMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
cv::CrossProduct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
CvtPixToPlane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
cv::DCT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
cv::DFT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
cv::DecRefData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
cv::Det . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
cv::Div . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
cv::DotProduct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
cv::EigenVV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
cv::Exp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
cv::FastArctan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
cv::Flip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
cv::GEMM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
cv::Get?D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
cv::GetCol(s) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
cv::GetDiag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
cvGetDims, cvGetDimSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
cv::GetElemType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
CONTENTS 5

cv::GetImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
cv::GetImageCOI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
cv::GetImageROI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
cv::GetMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
cv::GetNextSparseNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
cv::GetOptimalDFTSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
cv::GetRawData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
cv::GetReal1D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
cv::GetReal2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
cv::GetReal3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
cv::GetRealND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
cv::GetRow(s) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
cv::GetSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
cv::GetSubRect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
cv::InRange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
cv::InRangeS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
cv::IncRefData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
cv::InitImageHeader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
cv::InitMatHeader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
cv::InitMatNDHeader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
cv::InitSparseMatIterator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
cv::InvSqrt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
cv::Inv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
cv::Invert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
cv::IsInf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
cv::IsNaN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
cv::LUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
cv::Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
cv::Mahalanobis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
cv::Mat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
cv::Max . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
cv::MaxS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
cv::Merge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
cv::Min . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
cv::MinMaxLoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
cv::MinS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Mirror . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
cv::MixChannels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
MulAddS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
cv::Mul . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
6 CONTENTS

cv::MulSpectrums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
cv::MulTransposed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
cv::Norm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
cv::Not . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
cv::Or . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
cv::OrS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
cv::PerspectiveTransform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
cv::PolarToCart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
cv::Pow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
cv::Ptr?D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
cv::RNG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
cv::RandArr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
cv::RandInt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
cv::RandReal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
cv::Reduce . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
cv::ReleaseData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
cv::ReleaseImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
cv::ReleaseImageHeader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
cv::ReleaseMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
cv::ReleaseMatND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
cv::ReleaseSparseMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
cv::Repeat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
cv::ResetImageROI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
cv::Reshape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
cv::ReshapeMatND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
cvRound, cvFloor, cvCeil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
cv::ScaleAdd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
cv::Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
cv::Set?D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
cv::SetData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
cv::SetIdentity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
cv::SetImageCOI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
cv::SetImageROI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
cv::SetReal?D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
cv::SetZero . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
cv::Solve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
cv::SolveCubic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
cv::Split . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
cv::Sqrt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
cv::Sub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
CONTENTS 7

cv::SubRS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
cv::SubS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
cv::Sum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
cv::SVBkSb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
cv::SVD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
cv::Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
cv::Transform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
cv::Transpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
cv::Xor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
cv::XorS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
cv::mGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
cv::mSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
1.3 Dynamic Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
CvMemStorage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
CvMemBlock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
CvMemStoragePos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
CvSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
CvSeqBlock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
CvSlice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
CvSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
CvGraph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
CvGraphScanner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
CV TREE NODE FIELDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
CvTreeNodeIterator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
cv::ClearGraph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
cv::ClearMemStorage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
cv::ClearSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
cv::ClearSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
cv::CloneGraph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
cv::CloneSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
cv::CreateChildMemStorage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
cv::CreateGraph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
cv::CreateGraphScanner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
cv::CreateMemStorage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
cv::CreateSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
cv::CreateSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
cv::CvtSeqToArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
cv::EndWriteSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
cv::FindGraphEdge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
cv::FindGraphEdgeByPtr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
8 CONTENTS

cv::FlushSeqWriter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
cv::GetGraphVtx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
cv::GetSeqElem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
cv::GetSeqReaderPos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
cv::GetSetElem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
cv::GraphAddEdge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
cv::GraphAddEdgeByPtr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
cv::GraphAddVtx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
cv::GraphEdgeIdx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
cv::GraphRemoveEdge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
cv::GraphRemoveEdgeByPtr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
cv::GraphRemoveVtx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
cv::GraphRemoveVtxByPtr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
cv::GraphVtxDegree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
cv::GraphVtxDegreeByPtr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
cv::GraphVtxIdx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
cv::InitTreeNodeIterator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
cv::InsertNodeIntoTree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
cv::MakeSeqHeaderForArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
cv::MemStorageAlloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
cv::MemStorageAllocString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
cv::NextGraphItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
cv::NextTreeNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
cv::PrevTreeNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
cv::ReleaseGraphScanner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
cv::ReleaseMemStorage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
cv::RestoreMemStoragePos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
cv::SaveMemStoragePos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
cv::SeqElemIdx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
cv::SeqInsert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
cv::SeqInsertSlice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
cv::SeqInvert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
cv::SeqPop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
cv::SeqPopFront . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
cv::SeqPopMulti . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
cv::SeqPush . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
cv::SeqPushFront . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
cv::SeqPushMulti . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
cv::SeqRemove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
cv::SeqRemoveSlice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
CONTENTS 9

cv::SeqSearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
cv::SeqSlice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
cv::SeqSort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
cv::SetAdd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
cv::SetNew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
cv::SetRemove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
cv::SetRemoveByPtr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
cv::SetSeqBlockSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
cv::SetSeqReaderPos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
cv::StartAppendToSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
cv::StartReadSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
cv::StartWriteSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
cv::TreeToNodeSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
1.4 Drawing Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
cv::Circle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
cv::ClipLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
cv::DrawContours . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
cv::Ellipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
cv::EllipseBox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
cv::FillConvexPoly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
cv::FillPoly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
cv::GetTextSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
cv::InitFont . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
cv::InitLineIterator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
cv::Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
cv::PolyLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
cv::PutText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
cv::Rectangle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
CV RGB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
1.5 XML/YAML Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
CvFileStorage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
CvFileNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
CvAttrList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
CvTypeInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
cv::Clone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
cv::EndWriteStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
cv::FindType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
cv::FirstType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
cv::GetFileNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
cv::GetFileNodeByName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
10 CONTENTS

cv::GetFileNodeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
cv::GetHashedKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
cv::GetRootFileNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
cv::Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
cv::OpenFileStorage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
cv::Read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
cv::ReadByName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
cv::ReadInt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
cv::ReadIntByName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
cv::ReadRawData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
cv::ReadRawDataSlice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
cv::ReadReal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
cv::ReadRealByName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
cv::ReadString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
cv::ReadStringByName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
cv::RegisterType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
cv::Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
cv::ReleaseFileStorage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
cv::Save . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
cv::StartNextStream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
cv::StartReadRawData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
cv::StartWriteStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
cv::TypeOf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
cv::UnregisterType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
cv::Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
cv::WriteComment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
cv::WriteFileNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
cv::WriteInt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
cv::WriteRawData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
cv::WriteReal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
cv::WriteString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
1.6 Clustering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
cv::KMeans2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
cv::SeqPartition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
1.7 Utility and System Functions and Macros . . . . . . . . . . . . . . . . . . . . . . . . 235
Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Example: Use of Error Handling Macros . . . . . . . . . . . . . . . . . . . . . . . . . 237
cv::GetErrStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
cv::SetErrStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
cv::GetErrMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
CONTENTS 11

cv::SetErrMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
cv::Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
cv::ErrorStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
cv::RedirectError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
cvNulDevReport cvStdErrReport cvGuiBoxReport . . . . . . . . . . . . . . . . . . . 242
cv::Alloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
cv::Free . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
cv::GetTickCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
cv::GetTickFrequency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
cv::RegisterModule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
cv::GetModuleInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
cv::UseOptimized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
cv::SetMemoryManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
cv::SetIPLAllocators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

2 imgproc. Image Processing 249

2.1 Histograms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
CvHistogram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
cv::CalcBackProject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
cv::CalcBackProjectPatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
cv::CalcHist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
cv::CalcProbDensity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
cv::ClearHist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
cv::CompareHist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
cv::CopyHist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
cv::CreateHist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
cv::GetHistValue*D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
cv::GetMinMaxHistValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
cv::MakeHistHeaderForArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
cv::NormalizeHist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
cv::QueryHistValue*D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
cv::ReleaseHist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
cv::SetHistBinRanges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
cv::ThreshHist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
2.2 Image Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
IplConvKernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
cv::CopyMakeBorder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
cv::CreateStructuringElementEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
cv::Dilate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
cv::Erode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
12 CONTENTS

cv::Filter2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
cv::Laplace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
cv::MorphologyEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
cv::PyrDown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
cv::ReleaseStructuringElement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
cv::Smooth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
cv::Sobel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
2.3 Geometric Image Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
cv::GetRotationMatrix2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
cv::GetAffineTransform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
cv::GetPerspectiveTransform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
cv::GetQuadrangleSubPix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
cv::GetRectSubPix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
cv::LogPolar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
cv::Remap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
cv::Resize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
cv::WarpAffine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
cv::WarpPerspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
2.4 Miscellaneous Image Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . 283
cv::AdaptiveThreshold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
cv::CvtColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
cv::DistTransform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
CvConnectedComp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
cv::FloodFill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
cv::Inpaint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
cv::Integral . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
cv::PyrMeanShiftFiltering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
cv::PyrSegmentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
cv::Threshold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
2.5 Structural Analysis and Shape Descriptors . . . . . . . . . . . . . . . . . . . . . . . . 299
cv::ApproxChains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
cv::ApproxPoly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
cv::ArcLength . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
cv::BoundingRect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
cv::BoxPoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
cv::CalcPGH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
cv::CalcEMD2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
cv::CheckContourConvexity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
CvConvexityDefect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
cv::ContourArea . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
CONTENTS 13

cv::ContourFromContourTree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
cv::ConvexHull2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
cv::ConvexityDefects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
cv::CreateContourTree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
cv::EndFindContours . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
cv::FindContours . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
cv::FindNextContour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
cv::FitEllipse2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
cv::FitLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
cv::GetCentralMoment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
cv::GetHuMoments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
cv::GetNormalizedCentralMoment . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
cv::GetSpatialMoment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
cv::MatchContourTrees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
cv::MatchShapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
cv::MinAreaRect2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
cv::MinEnclosingCircle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
cv::Moments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
cv::PointPolygonTest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
cv::PointSeqFromMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
cv::ReadChainPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
cv::StartFindContours . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
cv::StartReadChainPoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
cv::SubstituteContour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
2.6 Planar Subdivisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
CvSubdiv2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
CvQuadEdge2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
CvSubdiv2DPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
cv::CalcSubdivVoronoi2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
cv::ClearSubdivVoronoi2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
cv::CreateSubdivDelaunay2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
cv::FindNearestPoint2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
cv::Subdiv2DEdgeDst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
cv::Subdiv2DGetEdge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
cv::Subdiv2DNextEdge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
cv::Subdiv2DLocate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
cv::Subdiv2DRotateEdge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
cv::SubdivDelaunay2DInsert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
2.7 Motion Analysis and Object Tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
cv::Acc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
14 CONTENTS

cv::MultiplyAcc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
cv::RunningAvg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
cv::SquareAcc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
2.8 Feature Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
cv::Canny . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
cv::CornerEigenValsAndVecs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
cv::CornerHarris . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
cv::CornerMinEigenVal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
cv::FindCornerSubPix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
cv::GoodFeaturesToTrack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
cv::HoughLines2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
cv::PreCornerDetect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
cv::SampleLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
2.9 Object Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
cv::MatchTemplate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350

3 features2d. Feature Detection and Descriptor Extraction 353

3.1 Feature detection and description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
cv::ExtractSURF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
cv::GetStarKeypoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

4 flann. Clustering and Search in Multi-Dimensional Spaces 359

4.1 Fast Approximate Nearest Neighbor Search . . . . . . . . . . . . . . . . . . . . . . . 359

5 objdetect. Object Detection 361

5.1 Cascade Classification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
Haar Feature-based Cascade Classifier for Object Detection . . . . . . . . . . . . . 361
CvHaarFeature, CvHaarClassifier, CvHaarStageClassifier, CvHaarClassifierCascade 362
cv::LoadHaarClassifierCascade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
cv::HaarDetectObjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
cv::SetImagesForHaarClassifierCascade . . . . . . . . . . . . . . . . . . . . . . . . 368
cv::ReleaseHaarClassifierCascade . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
cv::RunHaarClassifierCascade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369

6 video. Video Analysis 371

6.1 Motion Analysis and Object Tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
cv::CalcGlobalOrientation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
cv::CalcMotionGradient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
cv::CalcOpticalFlowBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
cv::CalcOpticalFlowHS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
CONTENTS 15

cv::CalcOpticalFlowLK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
cv::CalcOpticalFlowPyrLK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
cv::CamShift . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
CvConDensation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
cv::CreateConDensation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
cv::ConDensInitSampleSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
CvKalman . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
cv::CreateKalman . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
cv::KalmanCorrect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
cv::KalmanPredict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
KalmanUpdateByMeasurement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
KalmanUpdateByTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
cv::MeanShift . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
cv::ReleaseConDensation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
cv::ReleaseKalman . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
cv::SegmentMotion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
cv::SnakeImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
cv::UpdateMotionHistory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389

7 highgui. High-level GUI and Media I/O 391

7.1 User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
cv::ConvertImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
cv::CreateTrackbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
cv::DestroyAllWindows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
cv::DestroyWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
cv::GetTrackbarPos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
cv::GetWindowHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
cv::GetWindowName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
cv::InitSystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
cv::MoveWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
cv::NamedWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
cv::ResizeWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
cv::SetMouseCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
cv::SetTrackbarPos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
cv::ShowImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
cv::WaitKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
7.2 Reading and Writing Images and Video . . . . . . . . . . . . . . . . . . . . . . . . . 400
cv::LoadImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
cv::LoadImageM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
cv::SaveImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
16 CONTENTS

CvCapture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
cv::CaptureFromCAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
cv::CaptureFromFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
cv::GetCaptureProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
cv::GrabFrame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
cv::QueryFrame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
cv::ReleaseCapture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
cv::RetrieveFrame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
cv::SetCaptureProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
cv::CreateVideoWriter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
cv::ReleaseVideoWriter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
cv::WriteFrame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
7.3 Qt new functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
cv::SetWindowProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
cv::GetWindowProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
cv::FontQt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
cv::AddText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
cv::DisplayOverlay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
cv::DisplayStatusBar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
cv::CreateOpenGLCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
cv::SaveWindowParameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
cv::LoadWindowParameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
cv::CreateButton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417

8 calib3d. Camera Calibration, Pose Estimation and Stereo 419

8.1 Camera Calibration and 3d Reconstruction . . . . . . . . . . . . . . . . . . . . . . . 419
cv::CalcImageHomography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
cv::CalibrateCamera2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
cv::ComputeCorrespondEpilines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
cv::ConvertPointsHomogeneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
cv::CreatePOSITObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
cv::CreateStereoBMState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
cv::CreateStereoGCState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
CvStereoBMState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
CvStereoGCState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
cv::DecomposeProjectionMatrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
cv::DrawChessboardCorners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
cv::FindChessboardCorners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
cv::FindExtrinsicCameraParams2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
cv::FindFundamentalMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
CONTENTS 17

cv::FindHomography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436
cv::FindStereoCorrespondenceBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
cv::FindStereoCorrespondenceGC . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
cv::GetOptimalNewCameraMatrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
cv::InitIntrinsicParams2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442
cv::InitUndistortMap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
cv::InitUndistortRectifyMap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
cv::POSIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
cv::ProjectPoints2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
cv::ReprojectImageTo3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
cv::RQDecomp3x3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
cv::ReleasePOSITObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
cv::ReleaseStereoBMState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
cv::ReleaseStereoGCState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
cv::Rodrigues2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
cv::StereoCalibrate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
cv::StereoRectify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
cv::StereoRectifyUncalibrated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
cv::Undistort2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458
cv::UndistortPoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459

9 ml. Machine Learning 461

II C++ API Reference 463

10 Introduction 465
10.1 C++ Cheatsheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
10.2 Namespace cv and Function Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
10.3 Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
10.4 Memory Management Part II. Automatic Data Allocation . . . . . . . . . . . . . . . . 471
10.5 Algebraic Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473
10.6 Fast Element Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473
10.7 Saturation Arithmetics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
10.8 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
10.9 Threading and Reenterability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475

11 core. The Core Functionality 477

11.1 Basic Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
DataType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
18 CONTENTS

Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479
Point3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
Rect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482
RotatedRect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
TermCriteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
Matx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485
Vec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486
Scalar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
Range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
Ptr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
Mat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491
Matrix Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496
cv::Mat::Mat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
cv::Mat::Mat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
cv::Mat::operator = . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
cv::Mat::operator MatExpr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500
cv::Mat::row . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500
cv::Mat::col . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501
cv::Mat::rowRange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502
cv::Mat::colRange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502
cv::Mat::diag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502
cv::Mat::clone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503
cv::Mat::copyTo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503
cv::Mat::convertTo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504
cv::Mat::assignTo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505
cv::Mat::setTo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505
cv::Mat::reshape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505
cv::Mat::t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506
cv::Mat::inv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506
cv::Mat::mul . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507
cv::Mat::cross . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508
cv::Mat::dot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508
cv::Mat::zeros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508
cv::Mat::ones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509
cv::Mat::eye . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510
cv::Mat::create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510
cv::Mat::addref . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511
cv::Mat::release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
cv::Mat::resize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
CONTENTS 19

Mat::push back . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513

Mat::pop back . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513
cv::Mat::locateROI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513
cv::Mat::adjustROI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514
cv::Mat::operator() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515
cv::Mat::operator CvMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515
cv::Mat::operator IplImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516
cv::Mat::total . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516
cv::Mat::isContinuous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516
cv::Mat::elemSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518
cv::Mat::elemSize1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518
cv::Mat::type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519
cv::Mat::depth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519
cv::Mat::channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520
cv::Mat::step1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520
cv::Mat::size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520
cv::Mat::empty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521
cv::Mat::ptr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521
cv::Mat::at . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521
cv::Mat::begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522
cv::Mat::end . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523
Mat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524
NAryMatIterator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525
SparseMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
SparseMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532
11.2 Operations on Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
cv::abs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
cv::absdiff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
cv::add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535
cv::addWeighted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536
bitwise and . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537
bitwise not . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538
bitwise or . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539
bitwise xor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540
cv::calcCovarMatrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541
cv::cartToPolar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
cv::checkRange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543
cv::compare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544
cv::completeSymm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545
cv::convertScaleAbs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545
20 CONTENTS

cv::countNonZero . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546
cv::cubeRoot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547
cv::cvarrToMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547
cv::dct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549
cv::dft . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 550
cv::divide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554
cv::determinant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555
cv::eigen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556
cv::exp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556
cv::extractImageCOI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557
cv::fastAtan2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558
cv::flip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558
cv::gemm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559
cv::getConvertElem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560
cv::getOptimalDFTSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561
cv::idct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561
cv::idft . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562
cv::inRange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562
cv::invert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563
cv::log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564
cv::LUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564
cv::magnitude . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565
cv::Mahalanobis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566
cv::max . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566
cv::mean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567
cv::meanStdDev . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568
cv::merge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569
cv::min . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569
cv::minMaxLoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 570
cv::mixChannels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571
cv::mulSpectrums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573
cv::multiply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574
cv::mulTransposed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574
cv::norm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575
cv::normalize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576
cv::PCA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578
cv::PCA::PCA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579
cv::PCA::operator () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580
cv::PCA::project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581
cv::PCA::backProject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581
CONTENTS 21

cv::perspectiveTransform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582
cv::phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583
cv::polarToCart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584
cv::pow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584
RNG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585
cv::RNG::RNG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586
cv::RNG::next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587
cv::RNG::operator T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587
cv::RNG::operator () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587
cv::RNG::uniform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588
cv::RNG::gaussian . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589
cv::RNG::fill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589
cv::randu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590
cv::randn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590
cv::randShuffle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591
cv::reduce . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592
cv::repeat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592
saturate cast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593
cv::scaleAdd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594
cv::setIdentity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595
cv::solve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595
cv::solveCubic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596
cv::solvePoly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597
cv::sort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597
cv::sortIdx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598
cv::split . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599
cv::sqrt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599
cv::subtract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600
cv::SVD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601
cv::SVD::SVD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602
cv::SVD::operator () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603
cv::SVD::solveZ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603
cv::SVD::backSubst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604
cv::sum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604
cv::theRNG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605
cv::trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605
cv::transform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606
cv::transpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607
11.3 Dynamic Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607
11.4 Drawing Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607
22 CONTENTS

cv::circle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608
cv::clipLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608
cv::ellipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609
cv::ellipse2Poly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 610
cv::fillConvexPoly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611
cv::fillPoly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612
cv::getTextSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612
cv::line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613
cv::LineIterator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614
cv::rectangle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615
cv::polylines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616
cv::putText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617
11.5 XML/YAML Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617
cv::FileStorage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617
cv::FileNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619
cv::FileNodeIterator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620
11.6 Clustering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620
cv::kmeans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620
cv::partition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622
11.7 Utility and System Functions and Macros . . . . . . . . . . . . . . . . . . . . . . . . 622
cv::alignPtr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622
cv::alignSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623
cv::allocate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623
cv::deallocate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623
CV Assert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624
cv::error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624
cv::Exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625
cv::fastMalloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625
cv::fastFree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626
cv::format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626
cv::getNumThreads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627
cv::getThreadNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627
cv::getTickCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627
cv::getTickFrequency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628
cv::setNumThreads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628

12 imgproc. Image Processing 629

12.1 Histograms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629
cv::calcHist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629
cv::calcBackProject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632
CONTENTS 23

cv::compareHist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633
cv::equalizeHist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634
12.2 Image Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635
cv::BaseColumnFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636
cv::BaseFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636
cv::BaseRowFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637
cv::FilterEngine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638
cv::bilateralFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643
cv::blur . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644
cv::borderInterpolate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644
cv::boxFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645
cv::buildPyramid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646
cv::copyMakeBorder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646
cv::createBoxFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648
cv::createDerivFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649
cv::createGaussianFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649
cv::createLinearFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650
cv::createMorphologyFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651
cv::createSeparableLinearFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
cv::dilate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653
cv::erode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654
cv::filter2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655
cv::GaussianBlur . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656
cv::getDerivKernels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657
cv::getGaussianKernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658
cv::getKernelType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658
cv::getStructuringElement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659
cv::medianBlur . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660
cv::morphologyEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660
cv::Laplacian . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661
cv::pyrDown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662
cv::pyrUp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663
cv::sepFilter2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664
cv::Sobel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665
cv::Scharr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666
12.3 Geometric Image Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667
cv::convertMaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 668
cv::getAffineTransform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669
cv::getPerspectiveTransform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669
cv::getRectSubPix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670
24 CONTENTS

cv::getRotationMatrix2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
cv::invertAffineTransform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
cv::remap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672
cv::resize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673
cv::warpAffine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 674
cv::warpPerspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675
12.4 Miscellaneous Image Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . 676
cv::adaptiveThreshold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676
cv::cvtColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677
cv::distanceTransform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683
cv::floodFill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684
cv::inpaint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 686
cv::integral . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687
cv::threshold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688
cv::watershed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 690
cv::grabCut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691
12.5 Structural Analysis and Shape Descriptors . . . . . . . . . . . . . . . . . . . . . . . . 692
cv::moments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692
cv::HuMoments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693
cv::findContours . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694
cv::drawContours . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696
cv::approxPolyDP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697
cv::arcLength . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698
cv::boundingRect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699
cv::estimateRigidTransform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699
cv::estimateAffine3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 700
cv::contourArea . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 700
cv::convexHull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 701
cv::fitEllipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702
cv::fitLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702
cv::isContourConvex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 704
cv::minAreaRect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 704
cv::minEnclosingCircle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705
cv::matchShapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705
cv::pointPolygonTest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706
12.6 Planar Subdivisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707
12.7 Motion Analysis and Object Tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . 707
cv::accumulate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707
cv::accumulateSquare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708
cv::accumulateProduct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709
CONTENTS 25

cv::accumulateWeighted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709
12.8 Feature Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710
cv::Canny . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710
cv::cornerEigenValsAndVecs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711
cv::cornerHarris . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712
cv::cornerMinEigenVal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712
cv::cornerSubPix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713
cv::goodFeaturesToTrack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714
cv::HoughCircles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716
cv::HoughLines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718
cv::HoughLinesP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719
cv::preCornerDetect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721
12.9 Object Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722
cv::matchTemplate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722

13 features2d. Feature Detection and Descriptor Extraction 725

13.1 Feature detection and description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
cv::FAST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
cv::MSER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
cv::StarDetector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
cv::SIFT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727
cv::SURF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
cv::RandomizedTree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
cv::RandomizedTree::train . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 731
cv::RandomizedTree::read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732
cv::RandomizedTree::write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732
cv::RandomizedTree::applyQuantization . . . . . . . . . . . . . . . . . . . . . . . . . 733
cv::RTreeNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733
cv::RTreeClassifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733
cv::RTreeClassifier::train . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 735
cv::RTreeClassifier::getSignature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 736
cv::RTreeClassifier::getSparseSignature . . . . . . . . . . . . . . . . . . . . . . . . . 736
cv::RTreeClassifier::countNonZeroElements . . . . . . . . . . . . . . . . . . . . . . . 737
cv::RTreeClassifier::read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737
cv::RTreeClassifier::write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737
cv::RTreeClassifier::setQuantization . . . . . . . . . . . . . . . . . . . . . . . . . . . 738
13.2 Common Interfaces of Feature Detectors . . . . . . . . . . . . . . . . . . . . . . . . 740
cv::KeyPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740
cv::FeatureDetector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741
cv::FeatureDetector::detect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 742
26 CONTENTS

cv::FeatureDetector::read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743
cv::FeatureDetector::write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743
cv::FeatureDetector::create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743
cv::FastFeatureDetector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 744
cv::GoodFeaturesToTrackDetector . . . . . . . . . . . . . . . . . . . . . . . . . . . . 744
cv::MserFeatureDetector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745
cv::StarFeatureDetector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745
cv::SiftFeatureDetector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746
cv::SurfFeatureDetector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746
cv::GridAdaptedFeatureDetector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 747
cv::PyramidAdaptedFeatureDetector . . . . . . . . . . . . . . . . . . . . . . . . . . . 747
cv::DynamicAdaptedFeatureDetector . . . . . . . . . . . . . . . . . . . . . . . . . . . 747
cv::DynamicAdaptedFeatureDetector::DynamicAdaptedFeatureDetector . . . . . . . 748
cv::AdjusterAdapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749
cv::AdjusterAdapter::tooFew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749
cv::AdjusterAdapter::tooMany . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750
cv::AdjusterAdapter::good . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750
cv::FastAdjuster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 751
cv::StarAdjuster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 751
cv::SurfAdjuster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 751
13.3 Common Interfaces of Descriptor Extractors . . . . . . . . . . . . . . . . . . . . . . . 751
cv::DescriptorExtractor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752
cv::DescriptorExtractor::compute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752
cv::DescriptorExtractor::read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753
cv::DescriptorExtractor::write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753
cv::DescriptorExtractor::create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754
cv::SiftDescriptorExtractor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754
cv::SurfDescriptorExtractor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755
cv::CalonderDescriptorExtractor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755
cv::OpponentColorDescriptorExtractor . . . . . . . . . . . . . . . . . . . . . . . . . . 755
cv::BriefDescriptorExtractor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756
13.4 Common Interfaces of Descriptor Matchers . . . . . . . . . . . . . . . . . . . . . . . 756
cv::DMatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757
cv::DescriptorMatcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757
cv::DescriptorMatcher::add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758
cv::DescriptorMatcher::getTrainDescriptors . . . . . . . . . . . . . . . . . . . . . . . 759
cv::DescriptorMatcher::clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759
cv::DescriptorMatcher::empty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759
cv::DescriptorMatcher::isMaskSupported . . . . . . . . . . . . . . . . . . . . . . . . 759
cv::DescriptorMatcher::train . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760
CONTENTS 27

cv::DescriptorMatcher::match . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760
cv::DescriptorMatcher::knnMatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 761
cv::DescriptorMatcher::radiusMatch . . . . . . . . . . . . . . . . . . . . . . . . . . . 762
cv::DescriptorMatcher::clone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762
cv::DescriptorMatcher::create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763
cv::BruteForceMatcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763
cv::FlannBasedMatcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765
13.5 Common Interfaces of Generic Descriptor Matchers . . . . . . . . . . . . . . . . . . 765
cv::GenericDescriptorMatcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 766
cv::GenericDescriptorMatcher::add . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767
cv::GenericDescriptorMatcher::getTrainImages . . . . . . . . . . . . . . . . . . . . . 768
cv::GenericDescriptorMatcher::getTrainKeypoints . . . . . . . . . . . . . . . . . . . . 768
cv::GenericDescriptorMatcher::clear . . . . . . . . . . . . . . . . . . . . . . . . . . . 768
cv::GenericDescriptorMatcher::train . . . . . . . . . . . . . . . . . . . . . . . . . . . 768
cv::GenericDescriptorMatcher::isMaskSupported . . . . . . . . . . . . . . . . . . . . 768
cv::GenericDescriptorMatcher::classify . . . . . . . . . . . . . . . . . . . . . . . . . . 768
cv::GenericDescriptorMatcher::match . . . . . . . . . . . . . . . . . . . . . . . . . . 769
cv::GenericDescriptorMatcher::knnMatch . . . . . . . . . . . . . . . . . . . . . . . . 770
cv::GenericDescriptorMatcher::radiusMatch . . . . . . . . . . . . . . . . . . . . . . . 771
cv::GenericDescriptorMatcher::read . . . . . . . . . . . . . . . . . . . . . . . . . . . 771
cv::GenericDescriptorMatcher::write . . . . . . . . . . . . . . . . . . . . . . . . . . . 772
cv::GenericDescriptorMatcher::clone . . . . . . . . . . . . . . . . . . . . . . . . . . . 772
cv::OneWayDescriptorMatcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 772
cv::FernDescriptorMatcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773
cv::VectorDescriptorMatcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775
13.6 Drawing Function of Keypoints and Matches . . . . . . . . . . . . . . . . . . . . . . . 775
cv::drawMatches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775
cv::drawKeypoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777
13.7 Object Categorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 778
cv::BOWTrainer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 778
cv::BOWTrainer::add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 778
cv::BOWTrainer::getDescriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
cv::BOWTrainer::descripotorsCount . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
cv::BOWTrainer::cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
cv::BOWKMeansTrainer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
cv::BOWImgDescriptorExtractor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 780
cv::BOWImgDescriptorExtractor::BOWImgDescriptorExtractor . . . . . . . . . . . . . 781
cv::BOWImgDescriptorExtractor::setVocabulary . . . . . . . . . . . . . . . . . . . . . 781
cv::BOWImgDescriptorExtractor::getVocabulary . . . . . . . . . . . . . . . . . . . . . 781
cv::BOWImgDescriptorExtractor::compute . . . . . . . . . . . . . . . . . . . . . . . . 782
28 CONTENTS

cv::BOWImgDescriptorExtractor::descriptorSize . . . . . . . . . . . . . . . . . . . . . 782
cv::BOWImgDescriptorExtractor::descriptorType . . . . . . . . . . . . . . . . . . . . 782

14 flann. Clustering and Search in Multi-Dimensional Spaces 783

14.1 Fast Approximate Nearest Neighbor Search . . . . . . . . . . . . . . . . . . . . . . . 783
cv::flann::Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 783
cvflann::Index < T >::Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 784
cv::flann::Index < T >::knnSearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787
cv::flann::Index < T >::radiusSearch . . . . . . . . . . . . . . . . . . . . . . . . . . . 788
cv::flann::Index < T >::save . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789
cv::flann::Index < T >::getIndexParameters . . . . . . . . . . . . . . . . . . . . . . . 789
14.2 Clustering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789
cv::cv::flann::hierarchicalClustering¡ET,DT¿ . . . . . . . . . . . . . . . . . . . . . . . 789

15 objdetect. Object Detection 791

15.1 Cascade Classification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791
cv::FeatureEvaluator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791
cv::FeatureEvaluator::read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791
cv::FeatureEvaluator::clone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792
cv::FeatureEvaluator::getFeatureType . . . . . . . . . . . . . . . . . . . . . . . . . . 792
cv::FeatureEvaluator::setImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792
cv::FeatureEvaluator::setWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793
cv::FeatureEvaluator::calcOrd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793
cv::FeatureEvaluator::calcCat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793
cv::FeatureEvaluator::create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 794
cv::CascadeClassifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 794
cv::CascadeClassifier::CascadeClassifier . . . . . . . . . . . . . . . . . . . . . . . . 795
cv::CascadeClassifier::empty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796
cv::CascadeClassifier::load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796
cv::CascadeClassifier::read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796
cv::CascadeClassifier::detectMultiScale . . . . . . . . . . . . . . . . . . . . . . . . . 796
cv::CascadeClassifier::setImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797
cv::CascadeClassifier::runAt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797
cv::groupRectangles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 798

16 video. Video Analysis 799

16.1 Motion Analysis and Object Tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . 799
cv::calcOpticalFlowPyrLK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799
cv::calcOpticalFlowFarneback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800
cv::updateMotionHistory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 801
CONTENTS 29

cv::calcMotionGradient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 802
cv::calcGlobalOrientation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803
cv::CamShift . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803
cv::meanShift . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 804
cv::KalmanFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 805

17 highgui. High-level GUI and Media I/O 807

17.1 User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807
cv::createTrackbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807
cv::getTrackbarPos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 808
cv::imshow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809
cv::namedWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809
cv::setTrackbarPos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 811
cv::waitKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 811
17.2 Reading and Writing Images and Video . . . . . . . . . . . . . . . . . . . . . . . . . 812
cv::imdecode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 812
cv::imencode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 812
cv::imread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 813
cv::imwrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 814
cv::VideoCapture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 815
cv::VideoCapture::VideoCapture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 816
cv::VideoCapture::get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 817
cv::VideoCapture::set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 818
cv::VideoWriter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 819
17.3 Qt new functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 820
cv::setWindowProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821
cv::getWindowProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 822
cv::fontQt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 823
cv::addText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 824
cv::displayOverlay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 824
cv::displayStatusBar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 825
cv::createOpenGLCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 825
cv::saveWindowParameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 827
cv::loadWindowParameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 827
cv::createButton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 827

18 calib3d. Camera Calibration, Pose Estimation and Stereo 829

18.1 Camera Calibration and 3d Reconstruction . . . . . . . . . . . . . . . . . . . . . . . 829
cv::calibrateCamera . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 831
cv::calibrationMatrixValues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 833
30 CONTENTS

cv::composeRT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 834
cv::computeCorrespondEpilines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835
cv::convertPointsHomogeneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 836
cv::decomposeProjectionMatrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 836
cv::drawChessboardCorners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837
cv::findChessboardCorners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 838
cv::solvePnP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 839
cv::findFundamentalMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 840
cv::findHomography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 842
cv::getDefaultNewCameraMatrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 844
cv::getOptimalNewCameraMatrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 845
cv::initCameraMatrix2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 845
cv::initUndistortRectifyMap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 846
cv::matMulDeriv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 848
cv::projectPoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 848
cv::reprojectImageTo3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 850
cv::RQDecomp3x3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 851
cv::Rodrigues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 851
cv::StereoBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 852
cv::StereoSGBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 853
cv::StereoSGBM::StereoSGBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 854
cv::StereoSGBM::operator () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 855
cv::stereoCalibrate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 856
cv::stereoRectify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 858
cv::stereoRectifyUncalibrated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862
cv::undistort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863
cv::undistortPoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863

19 ml. Machine Learning 867

19.1 Statistical Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 867
cv::CvStatModel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 867
CvStatModel::CvStatModel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 868
CvStatModel::CvStatModel(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 868
CvStatModel:: CvStatModel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869
CvStatModel::clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869
CvStatModel::save . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869
CvStatModel::load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 870
CvStatModel::write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 870
CvStatModel::read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 870
CvStatModel::train . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 871
CONTENTS 31

CvStatModel::predict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872
19.2 Normal Bayes Classifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872
cv::CvNormalBayesClassifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 873
CvNormalBayesClassifier::train . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 873
CvNormalBayesClassifier::predict . . . . . . . . . . . . . . . . . . . . . . . . . . . . 874
19.3 K Nearest Neighbors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 874
cv::CvKNearest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 874
CvKNearest::train . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 875
CvKNearest::find nearest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 876
19.4 Support Vector Machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 878
cv::CvSVM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 879
cv::CvSVMParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 880
CvSVM::train . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 881
CvSVM::train auto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 881
CvSVM::get default grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 882
CvSVM::get params . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 883
CvSVM::get support vector* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 883
19.5 Decision Trees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 884
Predicting with Decision Trees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 884
Training Decision Trees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 884
Variable importance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885
cv::CvDTreeSplit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885
cv::CvDTreeNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886
cv::CvDTreeParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886
cv::CvDTreeTrainData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 887
cv::CvDTree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 890
CvDTree::train . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 892
CvDTree::predict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 892
19.6 Boosting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 893
cv::CvBoostParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 895
cv::CvBoostTree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 895
cv::CvBoost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 896
CvBoost::train . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 897
CvBoost::predict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 898
CvBoost::prune . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 898
CvBoost::get weak predictors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 898
19.7 Random Trees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 899
cv::CvRTParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 900
cv::CvRTrees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 900
CvRTrees::train . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 901
32 CONTENTS

CvRTrees::predict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 902
CvRTrees::get var importance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 902
CvRTrees::get proximity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 903
19.8 Expectation-Maximization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 906
cv::CvEMParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 907
cv::CvEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 908
CvEM::train . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 909
19.9 Neural Networks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 912
cv::CvANN MLP TrainParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 915
cv::CvANN MLP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 916
CvANN MLP::create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 918
CvANN MLP::train . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 918

III Python API Reference 921

20 Introduction 923
20.1 Cookbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 923
Convert an image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 923
Resize an image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 924
Compute the Laplacian . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 924
Using GoodFeaturesToTrack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 924
Using GetSubRect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 924
Using CreateMat, and accessing an element . . . . . . . . . . . . . . . . . . . . . . 925
ROS image message to OpenCV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 925
PIL Image to OpenCV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 925
OpenCV to PIL Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 925
NumPy and OpenCV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 926
OpenCV to pygame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 926
OpenCV and OpenEXR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 927

21 core. The Core Functionality 929

21.1 Basic Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929
CvPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929
CvPoint2D32f . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929
CvPoint3D32f . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929
CvPoint2D64f . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929
CvPoint3D64f . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929
CvSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 930
CvSize2D32f . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 930
CONTENTS 33

CvRect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 930
CvScalar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 930
CvTermCriteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 930
CvMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 931
CvMatND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 931
IplImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 931
CvArr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 932
21.2 Operations on Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 932
cv::AbsDiff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 932
cv::AbsDiffS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 933
cv::Add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 933
cv::AddS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 934
cv::AddWeighted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 934
cv::And . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 935
cv::AndS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 935
cv::Avg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 936
cv::AvgSdv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 936
cv::CalcCovarMatrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 937
cv::CartToPolar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 938
cv::Cbrt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 939
cv::ClearND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 939
cv::CloneImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 940
cv::CloneMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 940
cv::CloneMatND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 940
cv::Cmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 940
cv::CmpS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 941
cv::Convert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 942
cv::ConvertScale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 943
cv::ConvertScaleAbs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 943
cv::CvtScaleAbs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 944
cv::Copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 944
cv::CountNonZero . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945
cv::CreateData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945
cv::CreateImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 946
cv::CreateImageHeader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 946
cv::CreateMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 947
cv::CreateMatHeader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 947
cv::CreateMatND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 947
cv::CreateMatNDHeader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 948
cv::CrossProduct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 948
34 CONTENTS

CvtPixToPlane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 949
cv::DCT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 949
cv::DFT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 950
cv::Det . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 952
cv::Div . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 952
cv::DotProduct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 953
cv::EigenVV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 953
cv::Exp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 954
cv::FastArctan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 954
cv::Flip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 955
cv::fromarray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 956
cv::GEMM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 957
cv::Get1D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 957
cv::Get2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 958
cv::Get3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 958
cv::GetND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 959
cv::GetCol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 959
cv::GetCols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 959
cv::GetDiag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 960
cv::GetDims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 960
cv::GetElemType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 961
cv::GetImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 961
cv::GetImageCOI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 961
cv::GetImageROI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 962
cv::GetMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 962
cv::GetOptimalDFTSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 963
cv::GetReal1D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 963
cv::GetReal2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 964
cv::GetReal3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 964
cv::GetRealND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 965
cv::GetRow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 965
cv::GetRows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 965
cv::GetSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 966
cv::GetSubRect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 966
cv::InRange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 967
cv::InRangeS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 967
cv::InvSqrt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 968
cv::Inv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 968
cv::Invert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 969
cv::IsInf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 969
CONTENTS 35

cv::IsNaN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 970
cv::LUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 970
cv::Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 971
cv::Mahalanobis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 971
cv::Max . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 972
cv::MaxS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 972
cv::Merge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 973
cv::Min . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 973
cv::MinMaxLoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 974
cv::MinS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 974
Mirror . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 975
cv::MixChannels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 975
MulAddS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 976
cv::Mul . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 976
cv::MulSpectrums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 976
cv::MulTransposed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 977
cv::Norm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 978
cv::Not . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979
cv::Or . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979
cv::OrS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980
cv::PerspectiveTransform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980
cv::PolarToCart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981
cv::Pow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 982
cv::RNG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 982
cv::RandArr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 983
cv::RandInt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 983
cv::RandReal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 984
cv::Reduce . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 984
cv::Repeat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 985
cv::ResetImageROI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 985
cv::Reshape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 986
cv::ReshapeMatND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 986
cv::Round . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 987
cv::Floor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 987
cv::Ceil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 988
cv::ScaleAdd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 988
cv::Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 988
cv::Set1D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 989
cv::Set2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 989
cv::Set3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 990
36 CONTENTS

cv::SetND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 990
cv::SetData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 991
cv::SetIdentity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 991
cv::SetImageCOI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 992
cv::SetImageROI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 992
cv::SetReal1D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 993
cv::SetReal2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 993
cv::SetReal3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 993
cv::SetRealND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 994
cv::SetZero . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 994
cv::Solve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 995
cv::SolveCubic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 995
cv::Split . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 996
cv::Sqrt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997
cv::Sub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997
cv::SubRS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997
cv::SubS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 998
cv::Sum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 999
cv::SVBkSb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 999
cv::SVD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1000
cv::Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1001
cv::Transform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1002
cv::Transpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1002
cv::Xor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1003
cv::XorS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1003
cv::mGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1004
cv::mSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1004
21.3 Dynamic Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1005
CvMemStorage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1005
CvSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1005
CvSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1006
cv::CloneSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1006
cv::CreateMemStorage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1006
cv::SeqInvert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1007
cv::SeqRemove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1007
cv::SeqRemoveSlice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1007
21.4 Drawing Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1008
cv::Circle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1008
cv::ClipLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009
cv::DrawContours . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009
CONTENTS 37

cv::Ellipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1010
cv::EllipseBox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1011
cv::FillConvexPoly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1012
cv::FillPoly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1012
cv::GetTextSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1013
cv::InitFont . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1013
cv::InitLineIterator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1014
cv::Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1015
cv::PolyLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1016
cv::PutText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1017
cv::Rectangle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1017
CV RGB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1018
21.5 XML/YAML Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1018
cv::Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1018
cv::Save . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1019
21.6 Clustering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1019
cv::KMeans2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1019
21.7 Utility and System Functions and Macros . . . . . . . . . . . . . . . . . . . . . . . . 1020
Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1020
cv::GetTickCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1020
cv::GetTickFrequency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1021

22 imgproc. Image Processing 1023

22.1 Histograms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1023
CvHistogram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1023
cv::CalcBackProject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1023
cv::CalcBackProjectPatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1024
cv::CalcHist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1025
cv::CalcProbDensity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1027
cv::ClearHist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1027
cv::CompareHist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1028
cv::CreateHist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1029
cv::GetMinMaxHistValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1030
cv::NormalizeHist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1031
QueryHistValue 1D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1031
QueryHistValue 2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1031
QueryHistValue 3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1032
QueryHistValue nD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1032
cv::ThreshHist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1032
22.2 Image Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1033
38 CONTENTS

IplConvKernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1033
cv::CopyMakeBorder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1033
cv::CreateStructuringElementEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1034
cv::Dilate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1035
cv::Erode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1036
cv::Filter2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1036
cv::Laplace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1037
cv::MorphologyEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1038
cv::PyrDown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1039
cv::Smooth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1039
cv::Sobel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1041
22.3 Geometric Image Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1042
cv::GetRotationMatrix2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1043
cv::GetAffineTransform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1044
cv::GetPerspectiveTransform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1044
cv::GetQuadrangleSubPix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1045
cv::GetRectSubPix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1046
cv::LogPolar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1046
cv::Remap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1047
cv::Resize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1048
cv::WarpAffine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1048
cv::WarpPerspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1049
22.4 Miscellaneous Image Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . 1050
cv::AdaptiveThreshold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1050
cv::CvtColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1052
cv::DistTransform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1056
CvConnectedComp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1058
cv::FloodFill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1058
cv::Inpaint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1060
cv::Integral . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1061
cv::PyrMeanShiftFiltering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1062
cv::PyrSegmentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1063
cv::Threshold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1064
22.5 Structural Analysis and Shape Descriptors . . . . . . . . . . . . . . . . . . . . . . . . 1066
cv::ApproxChains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1066
cv::ApproxPoly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1066
cv::ArcLength . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1067
cv::BoundingRect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1068
cv::BoxPoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1068
cv::CalcPGH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1069
CONTENTS 39

cv::CalcEMD2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1069
cv::CheckContourConvexity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1070
CvConvexityDefect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1071
cv::ContourArea . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1071
cv::ContourFromContourTree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1072
cv::ConvexHull2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1073
cv::ConvexityDefects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1073
cv::CreateContourTree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1074
cv::FindContours . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1074
cv::FitEllipse2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1076
cv::FitLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1076
cv::GetCentralMoment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1077
cv::GetHuMoments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1078
cv::GetNormalizedCentralMoment . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1079
cv::GetSpatialMoment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1079
cv::MatchContourTrees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1080
cv::MatchShapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1080
cv::MinAreaRect2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1081
cv::MinEnclosingCircle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1082
cv::Moments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1083
cv::PointPolygonTest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1083
22.6 Planar Subdivisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1084
CvSubdiv2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1084
CvSubdiv2DPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1085
cv::CalcSubdivVoronoi2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1085
cv::ClearSubdivVoronoi2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1086
cv::CreateSubdivDelaunay2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1086
cv::FindNearestPoint2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1086
cv::Subdiv2DEdgeDst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1087
cv::Subdiv2DGetEdge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1087
cv::Subdiv2DNextEdge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1088
cv::Subdiv2DLocate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1089
cv::Subdiv2DRotateEdge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1090
cv::SubdivDelaunay2DInsert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1091
22.7 Motion Analysis and Object Tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . 1091
cv::Acc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1091
cv::MultiplyAcc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1092
cv::RunningAvg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1092
cv::SquareAcc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1093
22.8 Feature Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1093
40 CONTENTS

cv::Canny . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1093
cv::CornerEigenValsAndVecs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1094
cv::CornerHarris . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1094
cv::CornerMinEigenVal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1095
cv::FindCornerSubPix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1096
cv::GoodFeaturesToTrack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1097
cv::HoughLines2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1098
cv::PreCornerDetect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1099
22.9 Object Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1100
cv::MatchTemplate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1100

23 features2d. Feature Detection and Descriptor Extraction 1103

23.1 Feature detection and description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1103
CvSURFPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1103
cv::ExtractSURF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1104
cv::GetStarKeypoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1105

24 flann. Clustering and Search in Multi-Dimensional Spaces 1107

24.1 Fast Approximate Nearest Neighbor Search . . . . . . . . . . . . . . . . . . . . . . . 1107

25 objdetect. Object Detection 1109

25.1 Cascade Classification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1109
Haar Feature-based Cascade Classifier for Object Detection . . . . . . . . . . . . . 1109
cv::HaarDetectObjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1110

26 video. Video Analysis 1113

26.1 Motion Analysis and Object Tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . 1113
cv::CalcGlobalOrientation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1113
cv::CalcMotionGradient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1114
cv::CalcOpticalFlowBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1115
cv::CalcOpticalFlowHS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1115
cv::CalcOpticalFlowLK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1116
cv::CalcOpticalFlowPyrLK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1117
cv::CamShift . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1118
CvKalman . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1119
cv::CreateKalman . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1120
cv::KalmanCorrect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1120
cv::KalmanPredict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1121
KalmanUpdateByMeasurement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1122
KalmanUpdateByTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1122
CONTENTS 41

cv::MeanShift . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1122
cv::SegmentMotion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1122
cv::SnakeImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1123
cv::UpdateMotionHistory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1124

27 highgui. High-level GUI and Media I/O 1125

27.1 User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1125
cv::CreateTrackbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1125
cv::DestroyAllWindows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1126
cv::DestroyWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1126
cv::GetTrackbarPos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1127
cv::MoveWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1127
cv::NamedWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1128
cv::ResizeWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1129
cv::SetMouseCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1129
cv::SetTrackbarPos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1130
cv::ShowImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1131
cv::WaitKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1131
27.2 Reading and Writing Images and Video . . . . . . . . . . . . . . . . . . . . . . . . . 1132
cv::LoadImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1132
cv::LoadImageM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1133
cv::SaveImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1134
CvCapture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1134
cv::CaptureFromCAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1134
cv::CaptureFromFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1135
cv::GetCaptureProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1135
cv::GrabFrame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1136
cv::QueryFrame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1137
cv::RetrieveFrame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1137
cv::SetCaptureProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1137
cv::CreateVideoWriter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1139
cv::WriteFrame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1139

28 calib3d. Camera Calibration, Pose Estimation and Stereo 1141

28.1 Camera Calibration and 3d Reconstruction . . . . . . . . . . . . . . . . . . . . . . . 1141
cv::CalibrateCamera2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1143
cv::ComputeCorrespondEpilines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1145
cv::ConvertPointsHomogeneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1146
cv::CreatePOSITObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1146
cv::CreateStereoBMState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1147
42 CONTENTS

cv::CreateStereoGCState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1147
CvStereoBMState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1148
CvStereoGCState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1149
cv::DecomposeProjectionMatrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1150
cv::DrawChessboardCorners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1151
cv::FindChessboardCorners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1151
cv::FindExtrinsicCameraParams2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1153
cv::FindFundamentalMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1153
cv::FindHomography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1155
cv::FindStereoCorrespondenceBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1156
cv::FindStereoCorrespondenceGC . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1157
cv::GetOptimalNewCameraMatrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1159
cv::InitIntrinsicParams2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1160
cv::InitUndistortMap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1161
cv::InitUndistortRectifyMap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1161
cv::POSIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1163
cv::ProjectPoints2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1164
cv::ReprojectImageTo3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1165
cv::RQDecomp3x3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1166
cv::Rodrigues2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1166
cv::StereoCalibrate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1167
cv::StereoRectify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1170
cv::StereoRectifyUncalibrated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1173
cv::Undistort2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1174
cv::UndistortPoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1175

29 ml. Machine Learning 1177

Bibliography 1177

Index 1180
 Part I

C API Reference

43
Chapter 1

core. The Core Functionality

1.1 Basic Structures

CvPoint (view/add comments)

2D point with integer coordinates (usually zero-based).
typedef struct CvPoint
{
int x;
int y;
}
CvPoint;

x x-coordinate

y y-coordinate

/* Constructor */
inline CvPoint cvPoint( int x, int y );

/* Conversion from CvPoint2D32f */

inline CvPoint cvPointFrom32f( CvPoint2D32f point );

CvPoint2D32f (view/add comments)

2D point with floating-point coordinates

45
46 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

typedef struct CvPoint2D32f

{
float x;
float y;
}
CvPoint2D32f;

x x-coordinate

y y-coordinate

/* Constructor */
inline CvPoint2D32f cvPoint2D32f( double x, double y );

/* Conversion from CvPoint */

inline CvPoint2D32f cvPointTo32f( CvPoint point );

CvPoint3D32f (view/add comments)

3D point with floating-point coordinates
typedef struct CvPoint3D32f
{
float x;
float y;
float z;
}
CvPoint3D32f;

x x-coordinate

y y-coordinate

z z-coordinate

/* Constructor */
inline CvPoint3D32f cvPoint3D32f( double x, double y, double z );
1.1. BASIC STRUCTURES 47

CvPoint2D64f (view/add comments)

2D point with double precision floating-point coordinates
typedef struct CvPoint2D64f
{
double x;
double y;
}
CvPoint2D64f;

x x-coordinate

y y-coordinate

/* Constructor */
inline CvPoint2D64f cvPoint2D64f( double x, double y );

/* Conversion from CvPoint */

inline CvPoint2D64f cvPointTo64f( CvPoint point );

CvPoint3D64f (view/add comments)

3D point with double precision floating-point coordinates
typedef struct CvPoint3D64f
{
double x;
double y;
double z;
}
CvPoint3D64f;

x x-coordinate

y y-coordinate

z z-coordinate

/* Constructor */
inline CvPoint3D64f cvPoint3D64f( double x, double y, double z );
48 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

CvSize (view/add comments)

Pixel-accurate size of a rectangle.
typedef struct CvSize
{
int width;
int height;
}
CvSize;

width Width of the rectangle

height Height of the rectangle

/* Constructor */
inline CvSize cvSize( int width, int height );

CvSize2D32f (view/add comments)

Sub-pixel accurate size of a rectangle.
typedef struct CvSize2D32f
{
float width;
float height;
}
CvSize2D32f;

width Width of the rectangle

height Height of the rectangle

/* Constructor */
inline CvSize2D32f cvSize2D32f( double width, double height );

CvRect (view/add comments)

Offset (usually the top-left corner) and size of a rectangle.
1.1. BASIC STRUCTURES 49

typedef struct CvRect

{
int x;
int y;
int width;
int height;
}
CvRect;

x x-coordinate of the top-left corner

y y-coordinate of the top-left corner (bottom-left for Windows bitmaps)
width Width of the rectangle
height Height of the rectangle

/* Constructor */
inline CvRect cvRect( int x, int y, int width, int height );

CvScalar (view/add comments)

A container for 1-,2-,3- or 4-tuples of doubles.
typedef struct CvScalar
{
double val[4];
}
CvScalar;

/* Constructor:
initializes val[0] with val0, val[1] with val1, etc.
*/
inline CvScalar cvScalar( double val0, double val1=0,
double val2=0, double val3=0 );
/* Constructor:
initializes all of val[0]...val[3] with val0123
*/
inline CvScalar cvScalarAll( double val0123 );

/* Constructor:
initializes val[0] with val0, and all of val[1]...val[3] with zeros
*/
inline CvScalar cvRealScalar( double val0 );
50 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

CvTermCriteria (view/add comments)

Termination criteria for iterative algorithms.
#define CV_TERMCRIT_ITER 1
#define CV_TERMCRIT_NUMBER CV_TERMCRIT_ITER
#define CV_TERMCRIT_EPS 2

typedef struct CvTermCriteria

{
int type;
int max_iter;
double epsilon;
}
CvTermCriteria;

type A combination of CV TERMCRIT ITER and CV TERMCRIT EPS

max iter Maximum number of iterations

epsilon Required accuracy

/* Constructor */
inline CvTermCriteria cvTermCriteria( int type, int max_iter, double epsilon );

/* Check and transform a CvTermCriteria so that

type=CV_TERMCRIT_ITER+CV_TERMCRIT_EPS
and both max_iter and epsilon are valid */
CvTermCriteria cvCheckTermCriteria( CvTermCriteria criteria,
double default_eps,
int default_max_iters );

CvMat (view/add comments)

A multi-channel matrix.
typedef struct CvMat
{
int type;
int step;

int* refcount;

union
1.1. BASIC STRUCTURES 51

{
uchar* ptr;
short* s;
int* i;
float* fl;
double* db;
} data;

#ifdef __cplusplus
union
{
int rows;
int height;
};

union
{
int cols;
int width;
};
#else
int rows;
int cols;
#endif

} CvMat;

type A CvMat signature (CV MAT MAGIC VAL) containing the type of elements and flags

step Full row length in bytes

refcount Underlying data reference counter

data Pointers to the actual matrix data

rows Number of rows

cols Number of columns

Matrices are stored row by row. All of the rows are aligned by 4 bytes.

CvMatND (view/add comments)

Multi-dimensional dense multi-channel array.
52 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

typedef struct CvMatND

{
int type;
int dims;

int* refcount;

union
{
uchar* ptr;
short* s;
int* i;
float* fl;
double* db;
} data;

struct
{
int size;
int step;
}
dim[CV_MAX_DIM];

} CvMatND;

type A CvMatND signature (CV MATND MAGIC VAL), combining the type of elements and flags

dims The number of array dimensions

refcount Underlying data reference counter

data Pointers to the actual matrix data

dim For each dimension, the pair (number of elements, distance between elements in bytes)

CvSparseMat (view/add comments)

Multi-dimensional sparse multi-channel array.
typedef struct CvSparseMat
{
int type;
int dims;
int* refcount;
1.1. BASIC STRUCTURES 53

struct CvSet* heap;

void** hashtable;
int hashsize;
int total;
int valoffset;
int idxoffset;
int size[CV_MAX_DIM];

} CvSparseMat;

type A CvSparseMat signature (CV SPARSE MAT MAGIC VAL), combining the type of elements
and flags.

dims Number of dimensions

refcount Underlying reference counter. Not used.

heap A pool of hash table nodes

hashtable The hash table. Each entry is a list of nodes.

hashsize Size of the hash table

total Total number of sparse array nodes

valoffset The value offset of the array nodes, in bytes

idxoffset The index offset of the array nodes, in bytes

size Array of dimension sizes

IplImage (view/add comments)

IPL image header
typedef struct _IplImage
{
int nSize;
int ID;
int nChannels;
int alphaChannel;
int depth;
char colorModel[4];
char channelSeq[4];
54 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

int dataOrder;
int origin;
int align;
int width;
int height;
struct _IplROI *roi;
struct _IplImage *maskROI;
void *imageId;
struct _IplTileInfo *tileInfo;
int imageSize;
char *imageData;
int widthStep;
int BorderMode[4];
int BorderConst[4];
char *imageDataOrigin;
}
IplImage;

nSize sizeof(IplImage)

ID Version, always equals 0

nChannels Number of channels. Most OpenCV functions support 1-4 channels.

alphaChannel Ignored by OpenCV

depth Channel depth in bits + the optional sign bit (IPL DEPTH SIGN). The supported depths
are:

IPL DEPTH 8U Unsigned 8-bit integer

IPL DEPTH 8S Signed 8-bit integer
IPL DEPTH 16U Unsigned 16-bit integer
IPL DEPTH 16S Signed 16-bit integer
IPL DEPTH 32S Signed 32-bit integer
IPL DEPTH 32F Single-precision floating point
IPL DEPTH 64F Double-precision floating point

colorModel Ignored by OpenCV. The OpenCV function CvtColor requires the source and des-
tination color spaces as parameters.

channelSeq Ignored by OpenCV

1.1. BASIC STRUCTURES 55

dataOrder 0 = IPL DATA ORDER PIXEL - interleaved color channels, 1 - separate color chan-
nels. CreateImage only creates images with interleaved channels. For example, the usual
layout of a color image is: b00 g00 r00 b10 g10 r10 ...

origin 0 - top-left origin, 1 - bottom-left origin (Windows bitmap style)

align Alignment of image rows (4 or 8). OpenCV ignores this and uses widthStep instead.

width Image width in pixels

height Image height in pixels

roi Region Of Interest (ROI). If not NULL, only this image region will be processed.

maskROI Must be NULL in OpenCV

imageId Must be NULL in OpenCV

tileInfo Must be NULL in OpenCV

imageSize Image data size in bytes. For interleaved data, this equals image->height·image->widthStep

imageData A pointer to the aligned image data

widthStep The size of an aligned image row, in bytes

BorderMode Border completion mode, ignored by OpenCV

BorderConst Border completion mode, ignored by OpenCV

imageDataOrigin A pointer to the origin of the image data (not necessarily aligned). This is
used for image deallocation.

The IplImage structure was inherited from the Intel Image Processing Library, in which the
format is native. OpenCV only supports a subset of possible IplImage formats, as outlined in the
parameter list above.
In addition to the above restrictions, OpenCV handles ROIs differently. OpenCV functions
require that the image size or ROI size of all source and destination images match exactly. On
the other hand, the Intel Image Processing Library processes the area of intersection between the
source and destination images (or ROIs), allowing them to vary independently.
56 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

CvArr (view/add comments)

Arbitrary array
typedef void CvArr;
The metatype CvArr is used only as a function parameter to specify that the function accepts
arrays of multiple types, such as IplImage*, CvMat* or even CvSeq* sometimes. The particular
array type is determined at runtime by analyzing the first 4 bytes of the header.

1.2 Operations on Arrays

cvAbsDiff (view/add comments)

Calculates absolute difference between two arrays.

void cvAbsDiff(const CvArr* src1, const CvArr* src2, CvArr* dst);

src1 The first source array

src2 The second source array

dst The destination array

The function calculates absolute difference between two arrays.

dst(i)c = |src1(I)c − src2(I)c |

All the arrays must have the same data type and the same size (or ROI size).

cvAbsDiffS (view/add comments)

Calculates absolute difference between an array and a scalar.

void cvAbsDiffS(const CvArr* src, CvArr* dst, CvScalar value);

1.2. OPERATIONS ON ARRAYS 57

#define cvAbs(src, dst) cvAbsDiffS(src, dst, cvScalarAll(0))

src The source array

dst The destination array

value The scalar

The function calculates absolute difference between an array and a scalar.

dst(i)c = |src(I)c − valuec |

All the arrays must have the same data type and the same size (or ROI size).

cvAdd (view/add comments)

Computes the per-element sum of two arrays.

void cvAdd(const CvArr* src1, const CvArr* src2, CvArr* dst, const
CvArr* mask=NULL);

src1 The first source array

src2 The second source array

dst The destination array

mask Operation mask, 8-bit single channel array; specifies elements of the destination array to
be changed

The function adds one array to another:

dst(I)=src1(I)+src2(I) if mask(I)!=0
All the arrays must have the same type, except the mask, and the same size (or ROI size). For
types that have limited range this operation is saturating.

cvAddS (view/add comments)

Computes the sum of an array and a scalar.
58 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

void cvAddS(const CvArr* src, CvScalar value, CvArr* dst, const CvArr*
mask=NULL);

src The source array

value Added scalar

dst The destination array

mask Operation mask, 8-bit single channel array; specifies elements of the destination array to
be changed

The function adds a scalar value to every element in the source array src1 and stores the
result in dst. For types that have limited range this operation is saturating.
dst(I)=src(I)+value if mask(I)!=0

All the arrays must have the same type, except the mask, and the same size (or ROI size).

cvAddWeighted (view/add comments)

Computes the weighted sum of two arrays.

void cvAddWeighted(const CvArr* src1, double alpha, const CvArr* src2,

double beta, double gamma, CvArr* dst);

src1 The first source array

alpha Weight for the first array elements

src2 The second source array

beta Weight for the second array elements

dst The destination array

gamma Scalar, added to each sum

1.2. OPERATIONS ON ARRAYS 59

The function calculates the weighted sum of two arrays as follows:

dst(I)=src1(I)*alpha+src2(I)*beta+gamma
All the arrays must have the same type and the same size (or ROI size). For types that have
limited range this operation is saturating.

cvAnd (view/add comments)

Calculates per-element bit-wise conjunction of two arrays.

void cvAnd(const CvArr* src1, const CvArr* src2, CvArr* dst, const
CvArr* mask=NULL);

src1 The first source array

src2 The second source array

dst The destination array

mask Operation mask, 8-bit single channel array; specifies elements of the destination array to
be changed

The function calculates per-element bit-wise logical conjunction of two arrays:

dst(I)=src1(I)&src2(I) if mask(I)!=0
In the case of floating-point arrays their bit representations are used for the operation. All the
arrays must have the same type, except the mask, and the same size.

cvAndS (view/add comments)

Calculates per-element bit-wise conjunction of an array and a scalar.

void cvAndS(const CvArr* src, CvScalar value, CvArr* dst, const CvArr*
mask=NULL);

src The source array

60 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

value Scalar to use in the operation

dst The destination array
mask Operation mask, 8-bit single channel array; specifies elements of the destination array to
be changed
The function calculates per-element bit-wise conjunction of an array and a scalar:
dst(I)=src(I)&value if mask(I)!=0
Prior to the actual operation, the scalar is converted to the same type as that of the array(s). In
the case of floating-point arrays their bit representations are used for the operation. All the arrays
must have the same type, except the mask, and the same size.
The following sample demonstrates how to calculate the absolute value of floating-point array
elements by clearing the most-significant bit:
float a[] = { -1, 2, -3, 4, -5, 6, -7, 8, -9 };
CvMat A = cvMat(3, 3, CV\_32F, &a);
int i, absMask = 0x7fffffff;
cvAndS(&A, cvRealScalar(*(float*)&absMask), &A, 0);
for(i = 0; i < 9; i++ )
printf("%.1f ", a[i]);
The code should print:
1.0 2.0 3.0 4.0 5.0 6.0 7.0 8.0 9.0

cvAvg (view/add comments)

Calculates average (mean) of array elements.

CvScalar cvAvg(const CvArr* arr, const CvArr* mask=NULL);

arr The array

mask The optional operation mask
The function calculates the average value M of array elements, independently for each channel:
P
N = PI (mask(I) 6= 0)
I, mask(I)6=0 arr(I)c
Mc = N
If the array is IplImage and COI is set, the function processes the selected channel only and
stores the average to the first scalar component S0 .
1.2. OPERATIONS ON ARRAYS 61

cvAvgSdv (view/add comments)

Calculates average (mean) of array elements.

void cvAvgSdv(const CvArr* arr, CvScalar* mean, CvScalar* stdDev, const

CvArr* mask=NULL);

arr The array

mean Pointer to the output mean value, may be NULL if it is not needed

stdDev Pointer to the output standard deviation

mask The optional operation mask

The function calculates the average value and standard deviation of array elements, indepen-
dently for each channel:
P
N = I (mask(I) 6= 0)
meanc = N1
P
q I,Pmask(I)6=0 arr(I)c
stdDevc = N1 I, mask(I)6=0 (arr(I)c − meanc )
2

If the array is IplImage and COI is set, the function processes the selected channel only and
stores the average and standard deviation to the first components of the output scalars (mean0
and stdDev0 ).

cvCalcCovarMatrix (view/add comments)

Calculates covariance matrix of a set of vectors.

void cvCalcCovarMatrix(
const CvArr** vects,
int count,
CvArr* covMat,
CvArr* avg,
int flags);
62 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

vects The input vectors, all of which must have the same type and the same size. The vectors
do not have to be 1D, they can be 2D (e.g., images) and so forth

count The number of input vectors

covMat The output covariance matrix that should be floating-point and square

avg The input or output (depending on the flags) array - the mean (average) vector of the input
vectors

flags The operation flags, a combination of the following values

CV COVAR SCRAMBLED The output covariance matrix is calculated as:

scale ∗ [vects[0] − avg, vects[1] − avg, ...]T · [vects[0] − avg, vects[1] − avg, ...]

, that is, the covariance matrix is count × count. Such an unusual covariance matrix
is used for fast PCA of a set of very large vectors (see, for example, the EigenFaces
technique for face recognition). Eigenvalues of this ”scrambled” matrix will match the
eigenvalues of the true covariance matrix and the ”true” eigenvectors can be easily
calculated from the eigenvectors of the ”scrambled” covariance matrix.
CV COVAR NORMAL The output covariance matrix is calculated as:

scale ∗ [vects[0] − avg, vects[1] − avg, ...] · [vects[0] − avg, vects[1] − avg, ...]T

, that is, covMat will be a covariance matrix with the same linear size as the total
number of elements in each input vector. One and only one of CV COVAR SCRAMBLED
and CV COVAR NORMAL must be specified
CV COVAR USE AVG If the flag is specified, the function does not calculate avg from the
input vectors, but, instead, uses the passed avg vector. This is useful if avg has been
already calculated somehow, or if the covariance matrix is calculated by parts - in this
case, avg is not a mean vector of the input sub-set of vectors, but rather the mean
vector of the whole set.
CV COVAR SCALE If the flag is specified, the covariance matrix is scaled. In the ”normal”
mode scale is ’1./count’; in the ”scrambled” mode scale is the reciprocal of the total
number of elements in each input vector. By default (if the flag is not specified) the
covariance matrix is not scaled (’scale=1’).
CV COVAR ROWS Means that all the input vectors are stored as rows of a single matrix,
vects[0]. count is ignored in this case, and avg should be a single-row vector of an
appropriate size.
1.2. OPERATIONS ON ARRAYS 63

CV COVAR COLS Means that all the input vectors are stored as columns of a single matrix,
vects[0]. count is ignored in this case, and avg should be a single-column vector
of an appropriate size.

The function calculates the covariance matrix and, optionally, the mean vector of the set of input
vectors. The function can be used for PCA, for comparing vectors using Mahalanobis distance and
so forth.

cvCartToPolar (view/add comments)

Calculates the magnitude and/or angle of 2d vectors.

void cvCartToPolar(
const CvArr* x,
const CvArr* y,
CvArr* magnitude,
CvArr* angle=NULL,
int angleInDegrees=0);

x The array of x-coordinates

y The array of y-coordinates

magnitude The destination array of magnitudes, may be set to NULL if it is not needed

angle The destination array of angles, may be set to NULL if it is not needed. The angles are
measured in radians (0 to 2π) or in degrees (0 to 360 degrees).

angleInDegrees The flag indicating whether the angles are measured in radians, which is de-
fault mode, or in degrees

The function calculates either the magnitude, angle, or both of every 2d vector (x(I),y(I)):

magnitude(I)=sqrt(x(I)ˆ2ˆ+y(I)ˆ2ˆ ),
angle(I)=atan(y(I)/x(I) )

The angles are calculated with 0.1 degree accuracy. For the (0,0) point, the angle is set to 0.
64 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

cvCbrt (view/add comments)

Calculates the cubic root

float cvCbrt(float value);

value The input floating-point value

The function calculates the cubic root of the argument, and normally it is faster than pow(value,1./3).
In addition, negative arguments are handled properly. Special values (±∞, NaN) are not handled.

cvClearND (view/add comments)

Clears a specific array element.

void cvClearND(CvArr* arr, int* idx);

arr Input array

idx Array of the element indices

The function cvClearND clears (sets to zero) a specific element of a dense array or deletes the
element of a sparse array. If the sparse array element does not exists, the function does nothing.

cvCloneImage (view/add comments)

Makes a full copy of an image, including the header, data, and ROI.

IplImage* cvCloneImage(const IplImage* image);

image The original image

The returned IplImage* points to the image copy.

1.2. OPERATIONS ON ARRAYS 65

cvCloneMat (view/add comments)

Creates a full matrix copy.

CvMat* cvCloneMat(const CvMat* mat);

mat Matrix to be copied

Creates a full copy of a matrix and returns a pointer to the copy.

cvCloneMatND (view/add comments)

Creates full copy of a multi-dimensional array and returns a pointer to the copy.

CvMatND* cvCloneMatND(const CvMatND* mat);

mat Input array

cvCloneSparseMat (view/add comments)

Creates full copy of sparse array.

CvSparseMat* cvCloneSparseMat(const CvSparseMat* mat);

mat Input array

The function creates a copy of the input array and returns pointer to the copy.

cvCmp (view/add comments)

Performs per-element comparison of two arrays.
66 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

void cvCmp(const CvArr* src1, const CvArr* src2, CvArr* dst, int
cmpOp);

src1 The first source array

src2 The second source array. Both source arrays must have a single channel.

dst The destination array, must have 8u or 8s type

cmpOp The flag specifying the relation between the elements to be checked

CV CMP EQ src1(I) ”equal to” value

CV CMP GT src1(I) ”greater than” value
CV CMP GE src1(I) ”greater or equal” value
CV CMP LT src1(I) ”less than” value
CV CMP LE src1(I) ”less or equal” value
CV CMP NE src1(I) ”not equal” value

The function compares the corresponding elements of two arrays and fills the destination mask
array:
dst(I)=src1(I) op src2(I),
dst(I) is set to 0xff (all 1-bits) if the specific relation between the elements is true and 0
otherwise. All the arrays must have the same type, except the destination, and the same size (or
ROI size)

cvCmpS (view/add comments)

Performs per-element comparison of an array and a scalar.

void cvCmpS(const CvArr* src, double value, CvArr* dst, int cmpOp);

src The source array, must have a single channel

value The scalar value to compare each array element with

1.2. OPERATIONS ON ARRAYS 67

dst The destination array, must have 8u or 8s type

cmpOp The flag specifying the relation between the elements to be checked

CV CMP EQ src1(I) ”equal to” value

CV CMP GT src1(I) ”greater than” value
CV CMP GE src1(I) ”greater or equal” value
CV CMP LT src1(I) ”less than” value
CV CMP LE src1(I) ”less or equal” value
CV CMP NE src1(I) ”not equal” value

The function compares the corresponding elements of an array and a scalar and fills the des-
tination mask array:
dst(I)=src(I) op scalar
where op is =, >, ≥, <, ≤ or 6=.
dst(I) is set to 0xff (all 1-bits) if the specific relation between the elements is true and 0
otherwise. All the arrays must have the same size (or ROI size).

cvConvertScale (view/add comments)

Converts one array to another with optional linear transformation.

void cvConvertScale(const CvArr* src, CvArr* dst, double scale=1,

double shift=0);

#define cvCvtScale cvConvertScale

#define cvScale cvConvertScale
#define cvConvert(src, dst ) cvConvertScale((src), (dst), 1, 0 )

src Source array

dst Destination array

scale Scale factor

shift Value added to the scaled source array elements

68 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

The function has several different purposes, and thus has several different names. It copies
one array to another with optional scaling, which is performed first, and/or optional type conversion,
performed after:

dst(I) = scalesrc(I) + (shift0 , shift1 , ...)

All the channels of multi-channel arrays are processed independently.

The type of conversion is done with rounding and saturation, that is if the result of scaling +
conversion can not be represented exactly by a value of the destination array element type, it is
set to the nearest representable value on the real axis.
In the case of scale=1, shift=0 no prescaling is done. This is a specially optimized case
and it has the appropriate cvConvert name. If source and destination array types have equal
types, this is also a special case that can be used to scale and shift a matrix or an image and that
is caled cvScale.

cvConvertScaleAbs (view/add comments)

Converts input array elements to another 8-bit unsigned integer with optional linear transformation.

void cvConvertScaleAbs(const CvArr* src, CvArr* dst, double scale=1,

double shift=0);

src Source array

dst Destination array (should have 8u depth)

scale ScaleAbs factor

shift Value added to the scaled source array elements

The function is similar to cvConvertScale, but it stores absolute values of the conversion
results:

dst(I) = |scalesrc(I) + (shift0 , shift1 , ...)|

The function supports only destination arrays of 8u (8-bit unsigned integers) type; for other
types the function can be emulated by a combination of cvConvertScale and cvAbs functions.
1.2. OPERATIONS ON ARRAYS 69

cvCvtScaleAbs (view/add comments)

Converts input array elements to another 8-bit unsigned integer with optional linear transformation.

void cvCvtScaleAbs(const CvArr* src, CvArr* dst, double scale=1, double

shift=0);

src Source array

dst Destination array (should have 8u depth)

scale ScaleAbs factor

shift Value added to the scaled source array elements

The function is similar to cvConvertScale, but it stores absolute values of the conversion
results:

dst(I) = |scalesrc(I) + (shift0 , shift1 , ...)|

The function supports only destination arrays of 8u (8-bit unsigned integers) type; for other
types the function can be emulated by a combination of cvConvertScale and cvAbs functions.

cvCopy (view/add comments)

Copies one array to another.

void cvCopy(const CvArr* src, CvArr* dst, const CvArr* mask=NULL);

src The source array

dst The destination array

mask Operation mask, 8-bit single channel array; specifies elements of the destination array to
be changed
70 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

The function copies selected elements from an input array to an output array:

dst(I) = src(I) if mask(I) 6= 0.

If any of the passed arrays is of IplImage type, then its ROI and COI fields are used. Both
arrays must have the same type, the same number of dimensions, and the same size. The function
can also copy sparse arrays (mask is not supported in this case).

cvCountNonZero (view/add comments)

Counts non-zero array elements.

int cvCountNonZero(const CvArr* arr);

arr The array must be a single-channel array or a multi-channel image with COI set

The function returns the number of non-zero elements in arr:

X
(arr(I) 6= 0)
I

In the case of IplImage both ROI and COI are supported.

cvCreateData (view/add comments)

Allocates array data

void cvCreateData(CvArr* arr);

arr Array header

The function allocates image, matrix or multi-dimensional array data. Note that in the case
of matrix types OpenCV allocation functions are used and in the case of IplImage they are used
unless CV TURN ON IPL COMPATIBILITY was called. In the latter case IPL functions are used
to allocate the data.
1.2. OPERATIONS ON ARRAYS 71

cvCreateImage (view/add comments)

Creates an image header and allocates the image data.

IplImage* cvCreateImage(CvSize size, int depth, int channels);

size Image width and height

depth Bit depth of image elements. See IplImage for valid depths.
channels Number of channels per pixel. See IplImage for details. This function only creates
images with interleaved channels.
This call is a shortened form of
header = cvCreateImageHeader(size, depth, channels);
cvCreateData(header);

cvCreateImageHeader (view/add comments)

Creates an image header but does not allocate the image data.

IplImage* cvCreateImageHeader(CvSize size, int depth, int channels);

size Image width and height

depth Image depth (see cvCreateImage)
channels Number of channels (see cvCreateImage)
This call is an analogue of
hdr=iplCreateImageHeader(channels, 0, depth,
channels == 1 ? "GRAY" : "RGB",
channels == 1 ? "GRAY" : channels == 3 ? "BGR" :
channels == 4 ? "BGRA" : "",
IPL_DATA_ORDER_PIXEL, IPL_ORIGIN_TL, 4,
[Link], [Link],
0,0,0,0);
but it does not use IPL functions by default (see the CV TURN ON IPL COMPATIBILITY macro).
72 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

cvCreateMat (view/add comments)

Creates a matrix header and allocates the matrix data.

CvMat* cvCreateMat(
int rows,
int cols,
int type);

rows Number of rows in the matrix

cols Number of columns in the matrix

type The type of the matrix elements in the form CV <bit depth><S|U|F>C<number of
channels>, where S=signed, U=unsigned, F=float. For example, CV 8UC1 means the
elements are 8-bit unsigned and the there is 1 channel, and CV 32SC2 means the elements
are 32-bit signed and there are 2 channels.

This is the concise form for:

CvMat* mat = cvCreateMatHeader(rows, cols, type);
cvCreateData(mat);

cvCreateMatHeader (view/add comments)

Creates a matrix header but does not allocate the matrix data.

CvMat* cvCreateMatHeader(
int rows,
int cols,
int type);

rows Number of rows in the matrix

cols Number of columns in the matrix

1.2. OPERATIONS ON ARRAYS 73

type Type of the matrix elements, see cvCreateMat

The function allocates a new matrix header and returns a pointer to it. The matrix data can
then be allocated using cvCreateData or set explicitly to user-allocated data via cvSetData.

cvCreateMatND (view/add comments)

Creates the header and allocates the data for a multi-dimensional dense array.

CvMatND* cvCreateMatND(
int dims,
const int* sizes,
int type);

dims Number of array dimensions. This must not exceed CV MAX DIM (32 by default, but can
be changed at build time).

sizes Array of dimension sizes.

type Type of array elements, see cvCreateMat.

This is a short form for:

CvMatND* mat = cvCreateMatNDHeader(dims, sizes, type);
cvCreateData(mat);

cvCreateMatNDHeader (view/add comments)

Creates a new matrix header but does not allocate the matrix data.

CvMatND* cvCreateMatNDHeader(
int dims,
const int* sizes,
int type);

dims Number of array dimensions

74 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

sizes Array of dimension sizes

type Type of array elements, see cvCreateMat

The function allocates a header for a multi-dimensional dense array. The array data can further
be allocated using cvCreateData or set explicitly to user-allocated data via cvSetData.

cvCreateSparseMat (view/add comments)

Creates sparse array.

CvSparseMat* cvCreateSparseMat(int dims, const int* sizes, int type);

dims Number of array dimensions. In contrast to the dense matrix, the number of dimensions is
practically unlimited (up to 216 ).

sizes Array of dimension sizes

type Type of array elements. The same as for CvMat

The function allocates a multi-dimensional sparse array. Initially the array contain no elements,
that is cvGet or cvGetReal returns zero for every index.

cvCrossProduct (view/add comments)

Calculates the cross product of two 3D vectors.

void cvCrossProduct(const CvArr* src1, const CvArr* src2, CvArr* dst);

src1 The first source vector

src2 The second source vector

dst The destination vector

1.2. OPERATIONS ON ARRAYS 75

The function calculates the cross product of two 3D vectors:

dst = src1 × src2

or:
dst1 = src12 src23 − src13 src22
dst2 = src13 src21 − src11 src23
dst3 = src11 src22 − src12 src21

CvtPixToPlane
Synonym for Split .

cvDCT (view/add comments)

Performs a forward or inverse Discrete Cosine transform of a 1D or 2D floating-point array.

void cvDCT(const CvArr* src, CvArr* dst, int flags);

src Source array, real 1D or 2D array

dst Destination array of the same size and same type as the source
flags Transformation flags, a combination of the following values
CV DXT FORWARD do a forward 1D or 2D transform.
CV DXT INVERSE do an inverse 1D or 2D transform.
CV DXT ROWS do a forward or inverse transform of every individual row of the input matrix.
This flag allows user to transform multiple vectors simultaneously and can be used to
decrease the overhead (which is sometimes several times larger than the processing
itself), to do 3D and higher-dimensional transforms and so forth.

The function performs a forward or inverse transform of a 1D or 2D floating-point array:

Forward Cosine transform of 1D vector of N elements:

Y = C (N ) · X

where  
π(2k + 1)j
q
(N )
Cjk = αj /N cos
2N
76 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

and α0 = 1, αj = 2 for j > 0.

Inverse Cosine transform of 1D vector of N elements:
 −1  T
X = C (N ) · Y = C (N ) · Y

T
(since C (N ) is orthogonal matrix, C (N ) · C (N ) = I)
Forward Cosine transform of 2D M × N matrix:
 T
Y = C (N ) · X · C (N )

Inverse Cosine transform of 2D vector of M × N elements:

 T
X = C (N ) · X · C (N )

cvDFT (view/add comments)

Performs a forward or inverse Discrete Fourier transform of a 1D or 2D floating-point array.

void cvDFT(const CvArr* src, CvArr* dst, int flags, int nonzeroRows=0);

src Source array, real or complex

dst Destination array of the same size and same type as the source

flags Transformation flags, a combination of the following values

CV DXT FORWARD do a forward 1D or 2D transform. The result is not scaled.

CV DXT INVERSE do an inverse 1D or 2D transform. The result is not scaled. CV DXT FORWARD
and CV DXT INVERSE are mutually exclusive, of course.
CV DXT SCALE scale the result: divide it by the number of array elements. Usually, it is
combined with CV DXT INVERSE, and one may use a shortcut CV DXT INV SCALE.
CV DXT ROWS do a forward or inverse transform of every individual row of the input matrix.
This flag allows the user to transform multiple vectors simultaneously and can be used
to decrease the overhead (which is sometimes several times larger than the processing
itself), to do 3D and higher-dimensional transforms and so forth.
CV DXT INVERSE SCALE same as CV DXT INVERSE + CV DXT SCALE
1.2. OPERATIONS ON ARRAYS 77

nonzeroRows Number of nonzero rows in the source array (in the case of a forward 2d trans-
form), or a number of rows of interest in the destination array (in the case of an inverse 2d
transform). If the value is negative, zero, or greater than the total number of rows, it is ig-
nored. The parameter can be used to speed up 2d convolution/correlation when computing
via DFT. See the example below.

The function performs a forward or inverse transform of a 1D or 2D floating-point array:

Forward Fourier transform of 1D vector of N elements:
(N )
y = F (N ) · x, whereFjk = exp(−i · 2π · j · k/N )

,
i = sqrt(−1)

Inverse Fourier transform of 1D vector of N elements:

x0 = (F (N ) )−1 · y = conj(F ( N )) · yx = (1/N ) · x

Forward Fourier transform of 2D vector of M × N elements:

Y = F (M ) · X · F (N )

Inverse Fourier transform of 2D vector of M × N elements:

X 0 = conj(F (M ) ) · Y · conj(F (N ) )X = (1/(M · N )) · X 0

In the case of real (single-channel) data, the packed format, borrowed from IPL, is used to
represent the result of a forward Fourier transform or input for an inverse Fourier transform:

ReY0,0 ReY0,1 ImY0,1 ReY0,2 ImY0,2 · · · ReY0,N/2−1 ImY0,N/2−1 ReY0,N/2

 
 ReY1,0
 ReY1,1 ImY1,1 ReY1,2 ImY1,2 · · · ReY1,N/2−1 ImY1,N/2−1 ReY1,N/2  
 ImY1,0
 ReY2,1 ImY2,1 ReY2,2 ImY2,2 · · · ReY2,N/2−1 ImY2,N/2−1 ImY1,N/2  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
 
 ReYM/2−1,0 ReYM −3,1 ImYM −3,1 . . . . . . . . . . . . . . . . . . . . ReYM −3,N/2−1 ImYM −3,N/2−1 ReYM/2−1,N/2 
 
ImY ReYM −2,1 ImYM −2,1 . . . . . . . . . . . . . . . . . . . . ReY ImY ImY 
M/2−1,0 M −2,N/2−1 M −2,N/2−1 M/2−1,N/2
ReYM/2,0 ReYM −1,1 ImYM −1,1 . . . . . . . . . . . . . . . . . . . . ReYM −1,N/2−1 ImYM −1,N/2−1 ReYM/2,N/2

Note: the last column is present if N is even, the last row is present if M is even. In the case of
1D real transform the result looks like the first row of the above matrix.
Here is the example of how to compute 2D convolution using DFT.
78 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

CvMat* A = cvCreateMat(M1, N1, CVg32F);

CvMat* B = cvCreateMat(M2, N2, A->type);

// it is also possible to have only abs(M2-M1)+1 times abs(N2-N1)+1

// part of the full convolution result
CvMat* conv = cvCreateMat(A->rows + B->rows - 1, A->cols + B->cols - 1,
A->type);

// initialize A and B
...

int dftgM = cvGetOptimalDFTSize(A->rows + B->rows - 1);

int dftgN = cvGetOptimalDFTSize(A->cols + B->cols - 1);

CvMat* dftgA = cvCreateMat(dft\_M, dft\_N, A->type);

CvMat* dftgB = cvCreateMat(dft\_M, dft\_N, B->type);
CvMat tmp;

// copy A to dftgA and pad dft\_A with zeros

cvGetSubRect(dftgA, &tmp, cvRect(0,0,A->cols,A->rows));
cvCopy(A, &tmp);
cvGetSubRect(dftgA, &tmp, cvRect(A->cols,0,dft\_A->cols - A->cols,A->rows));
cvZero(&tmp);
// no need to pad bottom part of dftgA with zeros because of
// use nonzerogrows parameter in cvDFT() call below

cvDFT(dftgA, dft\_A, CV\_DXT\_FORWARD, A->rows);

// repeat the same with the second array

cvGetSubRect(dftgB, &tmp, cvRect(0,0,B->cols,B->rows));
cvCopy(B, &tmp);
cvGetSubRect(dftgB, &tmp, cvRect(B->cols,0,dft\_B->cols - B->cols,B->rows));
cvZero(&tmp);
// no need to pad bottom part of dftgB with zeros because of
// use nonzerogrows parameter in cvDFT() call below

cvDFT(dftgB, dft\_B, CV\_DXT\_FORWARD, B->rows);

cvMulSpectrums(dftgA, dft\_B, dft\_A, 0 /* or CV\_DXT\_MUL\_CONJ to get

correlation rather than convolution */);

cvDFT(dftgA, dft\_A, CV\_DXT\_INV\_SCALE, conv->rows); // calculate only

// the top part
cvGetSubRect(dftgA, &tmp, cvRect(0,0,conv->cols,conv->rows));
1.2. OPERATIONS ON ARRAYS 79

cvCopy(&tmp, conv);

cvDecRefData (view/add comments)

Decrements an array data reference counter.

void cvDecRefData(CvArr* arr);

arr Pointer to an array header

The function decrements the data reference counter in a CvMat or CvMatND if the reference
counter pointer is not NULL. If the counter reaches zero, the data is deallocated. In the current
implementation the reference counter is not NULL only if the data was allocated using the cvCre-
ateData function. The counter will be NULL in other cases such as: external data was assigned to
the header using cvSetData, the matrix header is part of a larger matrix or image, or the header
was converted from an image or n-dimensional matrix header.

cvDet (view/add comments)

Returns the determinant of a matrix.

double cvDet(const CvArr* mat);

mat The source matrix

The function returns the determinant of the square matrix mat. The direct method is used
for small matrices and Gaussian elimination is used for larger matrices. For symmetric positive-
determined matrices, it is also possible to run cvSVD with U = V = 0 and then calculate the
determinant as a product of the diagonal elements of W .

cvDiv (view/add comments)

Performs per-element division of two arrays.
80 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

void cvDiv(const CvArr* src1, const CvArr* src2, CvArr* dst, double
scale=1);

src1 The first source array. If the pointer is NULL, the array is assumed to be all 1’s.

src2 The second source array

dst The destination array

scale Optional scale factor

The function divides one array by another:


scale · src1(I)/src2(I) if src1 is not NULL
dst(I) =
scale/src2(I) otherwise
All the arrays must have the same type and the same size (or ROI size).

cvDotProduct (view/add comments)

Calculates the dot product of two arrays in Euclidian metrics.

double cvDotProduct(const CvArr* src1, const CvArr* src2);

src1 The first source array

src2 The second source array

The function calculates and returns the Euclidean dot product of two arrays.
X
src1 • src2 = (src1(I)src2(I))
I

In the case of multiple channel arrays, the results for all channels are accumulated. In par-
ticular, cvDotProduct(a,a) where a is a complex vector, will return ||a||2 . The function can
process multi-dimensional arrays, row by row, layer by layer, and so on.
1.2. OPERATIONS ON ARRAYS 81

cvEigenVV (view/add comments)

Computes eigenvalues and eigenvectors of a symmetric matrix.

void cvEigenVV(
CvArr* mat,
CvArr* evects,
CvArr* evals,
double eps=0,
int lowindex = -1,
int highindex = -1);

mat The input symmetric square matrix, modified during the processing

evects The output matrix of eigenvectors, stored as subsequent rows

evals The output vector of eigenvalues, stored in the descending order (order of eigenvalues
and eigenvectors is syncronized, of course)

eps Accuracy of diagonalization. Typically, DBL EPSILON (about 10−15 ) works well. THIS PA-
RAMETER IS CURRENTLY IGNORED.

lowindex Optional index of largest eigenvalue/-vector to calculate. (See below.)

highindex Optional index of smallest eigenvalue/-vector to calculate. (See below.)

The function computes the eigenvalues and eigenvectors of matrix A:

mat*evects(i,:)’ = evals(i)*evects(i,:)’ (in MATLAB notation)
If either low- or highindex is supplied the other is required, too. Indexing is 0-based. Example:
To calculate the largest eigenvector/-value set lowindex=highindex=0. To calculate all the
eigenvalues, leave lowindex=highindex=-1. For legacy reasons this function always returns
a square matrix the same size as the source matrix with eigenvectors and a vector the length
of the source matrix with eigenvalues. The selected eigenvectors/-values are always in the first
highindex - lowindex + 1 rows.
The contents of matrix A is destroyed by the function.
Currently the function is slower than cvSVD yet less accurate, so if A is known to be positively-
defined (for example, it is a covariance matrix)it is recommended to use cvSVD to find eigenvalues
and eigenvectors of A, especially if eigenvectors are not required.
82 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

cvExp (view/add comments)

Calculates the exponent of every array element.

void cvExp(const CvArr* src, CvArr* dst);

src The source array

dst The destination array, it should have double type or the same type as the source

The function calculates the exponent of every element of the input array:

dst[I] = esrc(I)
The maximum relative error is about 7 × 10−6 . Currently, the function converts denormalized
values to zeros on output.

cvFastArctan (view/add comments)

Calculates the angle of a 2D vector.

float cvFastArctan(float y, float x);

x x-coordinate of 2D vector

y y-coordinate of 2D vector

The function calculates the full-range angle of an input 2D vector. The angle is measured in
degrees and varies from 0 degrees to 360 degrees. The accuracy is about 0.1 degrees.

cvFlip (view/add comments)

Flip a 2D array around vertical, horizontal or both axes.
1.2. OPERATIONS ON ARRAYS 83

void cvFlip(const CvArr* src, CvArr* dst=NULL, int flipMode=0);

src Source array

dst Destination array. If dst = NULL the flipping is done in place.

flipMode Specifies how to flip the array: 0 means flipping around the x-axis, positive (e.g., 1)
means flipping around y-axis, and negative (e.g., -1) means flipping around both axes. See
also the discussion below for the formulas:

The function flips the array in one of three different ways (row and column indices are 0-based):

 src(rows(src) − i − 1, j) if flipMode = 0
dst(i, j) = src(i, cols(src) − j − 1) if flipMode > 0
src(rows(src) − i − 1, cols(src) − j − 1) if flipMode < 0


The example scenarios of function use are:

• vertical flipping of the image (flipMode = 0) to switch between top-left and bottom-left image
origin, which is a typical operation in video processing under Win32 systems.

• horizontal flipping of the image with subsequent horizontal shift and absolute difference cal-
culation to check for a vertical-axis symmetry (flipMode > 0)

• simultaneous horizontal and vertical flipping of the image with subsequent shift and absolute
difference calculation to check for a central symmetry (flipMode < 0)

• reversing the order of 1d point arrays (flipMode ¿ 0)

cvGEMM (view/add comments)

Performs generalized matrix multiplication.

void cvGEMM(
const CvArr* src1,
const CvArr* src2, double alpha,
const CvArr* src3,
double beta,
84 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

CvArr* dst,
int tABC=0);
#define cvMatMulAdd(src1, src2, src3, dst ) cvGEMM(src1, src2, 1, src3,
1, dst, 0 )
#define cvMatMul(src1, src2, dst ) cvMatMulAdd(src1, src2,
0, dst )

src1 The first source array

src2 The second source array
src3 The third source array (shift). Can be NULL, if there is no shift.
dst The destination array
tABC The operation flags that can be 0 or a combination of the following values
CV GEMM A T transpose src1
CV GEMM B T transpose src2
CV GEMM C T transpose src3
For example, CV GEMM A T+CV GEMM C T corresponds to
alpha src1T src2 + beta src3T

The function performs generalized matrix multiplication:

dst = alpha op(src1) op(src2) + beta op(src3) where op(X) is X or X T

All the matrices should have the same data type and coordinated sizes. Real or complex
floating-point matrices are supported.

cvGet?D (view/add comments)

Return a specific array element.

CvScalar cvGet1D(const CvArr* arr, int idx0); CvScalar cvGet2D(const

CvArr* arr, int idx0, int idx1); CvScalar cvGet3D(const CvArr* arr,
int idx0, int idx1, int idx2); CvScalar cvGetND(const CvArr* arr, int*
idx);
1.2. OPERATIONS ON ARRAYS 85

arr Input array

idx0 The first zero-based component of the element index

idx1 The second zero-based component of the element index

idx2 The third zero-based component of the element index

idx Array of the element indices

The functions return a specific array element. In the case of a sparse array the functions return
0 if the requested node does not exist (no new node is created by the functions).

cvGetCol(s) (view/add comments)

Returns array column or column span.

CvMat* cvGetCol(const CvArr* arr, CvMat* submat, int col);

CvMat* cvGetCols(const CvArr* arr, CvMat* submat, int startCol, int

endCol);

arr Input array

submat Pointer to the resulting sub-array header

col Zero-based index of the selected column

startCol Zero-based index of the starting column (inclusive) of the span

endCol Zero-based index of the ending column (exclusive) of the span

The functions GetCol and GetCols return the header, corresponding to a specified column
span of the input array. GetCol is a shortcut for cvGetCols:
cvGetCol(arr, submat, col); // ˜ cvGetCols(arr, submat, col, col + 1);
86 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

cvGetDiag (view/add comments)

Returns one of array diagonals.

CvMat* cvGetDiag(const CvArr* arr, CvMat* submat, int diag=0);

arr Input array

submat Pointer to the resulting sub-array header

diag Array diagonal. Zero corresponds to the main diagonal, -1 corresponds to the diagonal
above the main , 1 corresponds to the diagonal below the main, and so forth.

The function returns the header, corresponding to a specified diagonal of the input array.

cvGetDims, cvGetDimSize
Return number of array dimensions and their sizes or the size of a particular dimension.

int cvGetDims(const CvArr* arr, int* sizes=NULL);

int cvGetDimSize(const CvArr* arr, int index);

arr Input array

sizes Optional output vector of the array dimension sizes. For 2d arrays the number of rows
(height) goes first, number of columns (width) next.

index Zero-based dimension index (for matrices 0 means number of rows, 1 means number of
columns; for images 0 means height, 1 means width)
1.2. OPERATIONS ON ARRAYS 87

The function cvGetDims returns the array dimensionality and the array of dimension sizes.
In the case of IplImage or CvMat it always returns 2 regardless of number of image/matrix
rows. The function cvGetDimSize returns the particular dimension size (number of elements per
that dimension). For example, the following code calculates total number of array elements in two
ways:
// via cvGetDims()
int sizes[CV_MAX_DIM];
int i, total = 1;
int dims = cvGetDims(arr, size);
for(i = 0; i < dims; i++ )
total *= sizes[i];

// via cvGetDims() and cvGetDimSize()

int i, total = 1;
int dims = cvGetDims(arr);
for(i = 0; i < dims; i++ )
total *= cvGetDimsSize(arr, i);

cvGetElemType (view/add comments)

Returns type of array elements.

int cvGetElemType(const CvArr* arr);

arr Input array

The function returns type of the array elements as described in cvCreateMat discussion:
CV 8UC1 ... CV 64FC4.

cvGetImage (view/add comments)

Returns image header for arbitrary array.

IplImage* cvGetImage(const CvArr* arr, IplImage* imageHeader);

88 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

arr Input array

imageHeader Pointer to IplImage structure used as a temporary buffer

The function returns the image header for the input array that can be a matrix - CvMat , or an
image - IplImage*. In the case of an image the function simply returns the input pointer. In the
case of CvMat it initializes an imageHeader structure with the parameters of the input matrix.
Note that if we transform IplImage to CvMat and then transform CvMat back to IplImage, we
can get different headers if the ROI is set, and thus some IPL functions that calculate image stride
from its width and align may fail on the resultant image.

cvGetImageCOI (view/add comments)

Returns the index of the channel of interest.

int cvGetImageCOI(const IplImage* image);

image A pointer to the image header

Returns the channel of interest of in an IplImage. Returned values correspond to the coi in
cvSetImageCOI.

cvGetImageROI (view/add comments)

Returns the image ROI.

CvRect cvGetImageROI(const IplImage* image);

image A pointer to the image header

If there is no ROI set, cvRect(0,0,image->width,image->height) is returned.

1.2. OPERATIONS ON ARRAYS 89

cvGetMat (view/add comments)

Returns matrix header for arbitrary array.

CvMat* cvGetMat(const CvArr* arr, CvMat* header, int* coi=NULL, int

allowND=0);

arr Input array

header Pointer to CvMat structure used as a temporary buffer
coi Optional output parameter for storing COI
allowND If non-zero, the function accepts multi-dimensional dense arrays (CvMatND*) and re-
turns 2D (if CvMatND has two dimensions) or 1D matrix (when CvMatND has 1 dimension
or more than 2 dimensions). The array must be continuous.

The function returns a matrix header for the input array that can be a matrix -
CvMat , an image - IplImage or a multi-dimensional dense array - CvMatND (latter case is
allowed only if allowND != 0) . In the case of matrix the function simply returns the input pointer.
In the case of IplImage* or CvMatND it initializes the header structure with parameters of
the current image ROI and returns the pointer to this temporary structure. Because COI is not
supported by CvMat , it is returned separately.
The function provides an easy way to handle both types of arrays - IplImage and CvMat
- using the same code. Reverse transform from CvMat to IplImage can be done using the
cvGetImage function.
Input array must have underlying data allocated or attached, otherwise the function fails.
If the input array is IplImage with planar data layout and COI set, the function returns the
pointer to the selected plane and COI = 0. It enables per-plane processing of multi-channel images
with planar data layout using OpenCV functions.

cvGetNextSparseNode (view/add comments)

Returns the next sparse matrix element

CvSparseNode* cvGetNextSparseNode(CvSparseMatIterator* matIterator);

90 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

matIterator Sparse array iterator

The function moves iterator to the next sparse matrix element and returns pointer to it. In the
current version there is no any particular order of the elements, because they are stored in the
hash table. The sample below demonstrates how to iterate through the sparse matrix:
Using cvInitSparseMatIterator and cvGetNextSparseNode to calculate sum of floating-point
sparse array.
double sum;
int i, dims = cvGetDims(array);
CvSparseMatIterator mat_iterator;
CvSparseNode* node = cvInitSparseMatIterator(array, &mat_iterator);

for(; node != 0; node = cvGetNextSparseNode(&mat_iterator ))

{
/* get pointer to the element indices */
int* idx = CV_NODE_IDX(array, node);
/* get value of the element (assume that the type is CV_32FC1) */
float val = *(float*)CV_NODE_VAL(array, node);
printf("(");
for(i = 0; i < dims; i++ )
printf("%4d%s", idx[i], i < dims - 1 "," : "): ");
printf("%g\n", val);

sum += val;
}

printf("\nTotal sum = %g\n", sum);

cvGetOptimalDFTSize (view/add comments)

Returns optimal DFT size for a given vector size.

int cvGetOptimalDFTSize(int size0);

size0 Vector size

The function returns the minimum number N that is greater than or equal to size0, such that
the DFT of a vector of size N can be computed fast. In the current implementation N = 2p ×3q ×5r ,
for some p, q, r.
The function returns a negative number if size0 is too large (very close to INT MAX)
1.2. OPERATIONS ON ARRAYS 91

cvGetRawData (view/add comments)

Retrieves low-level information about the array.

void cvGetRawData(const CvArr* arr, uchar** data, int* step=NULL,

CvSize* roiSize=NULL);

arr Array header

data Output pointer to the whole image origin or ROI origin if ROI is set

step Output full row length in bytes

roiSize Output ROI size

The function fills output variables with low-level information about the array data. All output
parameters are optional, so some of the pointers may be set to NULL. If the array is IplImage
with ROI set, the parameters of ROI are returned.
The following example shows how to get access to array elements. GetRawData calculates
the absolute value of the elements in a single-channel, floating-point array.
float* data;
int step;

CvSize size;
int x, y;

cvGetRawData(array, (uchar**)&data, &step, &size);

step /= sizeof(data[0]);

for(y = 0; y < [Link]; y++, data += step )

for(x = 0; x < [Link]; x++ )
data[x] = (float)fabs(data[x]);

cvGetReal1D (view/add comments)

Return a specific element of single-channel 1D array.
92 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

double cvGetReal1D(const CvArr* arr, int idx0);

arr Input array. Must have a single channel.

idx0 The first zero-based component of the element index

Returns a specific element of a single-channel array. If the array has multiple channels, a
runtime error is raised. Note that cvGet function can be used safely for both single-channel and
multiple-channel arrays though they are a bit slower.
In the case of a sparse array the functions return 0 if the requested node does not exist (no
new node is created by the functions).

cvGetReal2D (view/add comments)

Return a specific element of single-channel 2D array.

double cvGetReal2D(const CvArr* arr, int idx0, int idx1);

arr Input array. Must have a single channel.

idx0 The first zero-based component of the element index

idx1 The second zero-based component of the element index

Returns a specific element of a single-channel array. If the array has multiple channels, a
runtime error is raised. Note that cvGet function can be used safely for both single-channel and
multiple-channel arrays though they are a bit slower.
In the case of a sparse array the functions return 0 if the requested node does not exist (no
new node is created by the functions).

cvGetReal3D (view/add comments)

Return a specific element of single-channel array.
1.2. OPERATIONS ON ARRAYS 93

double cvGetReal3D(const CvArr* arr, int idx0, int idx1, int idx2);

arr Input array. Must have a single channel.

idx0 The first zero-based component of the element index

idx1 The second zero-based component of the element index

idx2 The third zero-based component of the element index

Returns a specific element of a single-channel array. If the array has multiple channels, a
runtime error is raised. Note that cvGet function can be used safely for both single-channel and
multiple-channel arrays though they are a bit slower.
In the case of a sparse array the functions return 0 if the requested node does not exist (no
new node is created by the functions).

cvGetRealND (view/add comments)

Return a specific element of single-channel array.

double cvGetRealND(const CvArr* arr, int* idx)->float;

arr Input array. Must have a single channel.

idx Array of the element indices

Returns a specific element of a single-channel array. If the array has multiple channels, a
runtime error is raised. Note that cvGet function can be used safely for both single-channel and
multiple-channel arrays though they are a bit slower.
In the case of a sparse array the functions return 0 if the requested node does not exist (no
new node is created by the functions).
94 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

cvGetRow(s) (view/add comments)

Returns array row or row span.

CvMat* cvGetRow(const CvArr* arr, CvMat* submat, int row);

CvMat* cvGetRows(const CvArr* arr, CvMat* submat, int startRow, int

endRow, int deltaRow=1);

arr Input array

submat Pointer to the resulting sub-array header
row Zero-based index of the selected row
startRow Zero-based index of the starting row (inclusive) of the span
endRow Zero-based index of the ending row (exclusive) of the span
deltaRow Index step in the row span. That is, the function extracts every deltaRow-th row from
startRow and up to (but not including) endRow.
The functions return the header, corresponding to a specified row/row span of the input array.
Note that GetRow is a shortcut for cvGetRows:
cvGetRow(arr, submat, row ) ˜ cvGetRows(arr, submat, row, row + 1, 1);

cvGetSize (view/add comments)

Returns size of matrix or image ROI.

CvSize cvGetSize(const CvArr* arr);

arr array header

The function returns number of rows (CvSize::height) and number of columns (CvSize::width)
of the input matrix or image. In the case of image the size of ROI is returned.
1.2. OPERATIONS ON ARRAYS 95

cvGetSubRect (view/add comments)

Returns matrix header corresponding to the rectangular sub-array of input image or matrix.

CvMat* cvGetSubRect(const CvArr* arr, CvMat* submat, CvRect rect);

arr Input array

submat Pointer to the resultant sub-array header

rect Zero-based coordinates of the rectangle of interest

The function returns header, corresponding to a specified rectangle of the input array. In other
words, it allows the user to treat a rectangular part of input array as a stand-alone array. ROI is
taken into account by the function so the sub-array of ROI is actually extracted.

cvInRange (view/add comments)

Checks that array elements lie between the elements of two other arrays.

void cvInRange(const CvArr* src, const CvArr* lower, const CvArr*

upper, CvArr* dst);

src The first source array

lower The inclusive lower boundary array

upper The exclusive upper boundary array

dst The destination array, must have 8u or 8s type

The function does the range check for every element of the input array:

dst(I) = lower(I)0 <= src(I)0 < upper(I)0

For single-channel arrays,
96 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

dst(I) = lower(I)0 <= src(I)0 < upper(I)0 ∧ lower(I)1 <= src(I)1 < upper(I)1

For two-channel arrays and so forth,

dst(I) is set to 0xff (all 1-bits) if src(I) is within the range and 0 otherwise. All the arrays must
have the same type, except the destination, and the same size (or ROI size).

cvInRangeS (view/add comments)

Checks that array elements lie between two scalars.

void cvInRangeS(const CvArr* src, CvScalar lower, CvScalar upper,

CvArr* dst);

src The first source array

lower The inclusive lower boundary

upper The exclusive upper boundary

dst The destination array, must have 8u or 8s type

The function does the range check for every element of the input array:

dst(I) = lower0 <= src(I)0 < upper0

For single-channel arrays,

dst(I) = lower0 <= src(I)0 < upper0 ∧ lower1 <= src(I)1 < upper1
For two-channel arrays nd so forth,
’dst(I)’ is set to 0xff (all 1-bits) if ’src(I)’ is within the range and 0 otherwise. All the arrays must
have the same size (or ROI size).

cvIncRefData (view/add comments)

Increments array data reference counter.
1.2. OPERATIONS ON ARRAYS 97

int cvIncRefData(CvArr* arr);

arr Array header

The function increments CvMat or CvMatND data reference counter and returns the new
counter value if the reference counter pointer is not NULL, otherwise it returns zero.

cvInitImageHeader (view/add comments)

Initializes an image header that was previously allocated.

IplImage* cvInitImageHeader(
IplImage* image,
CvSize size,
int depth,
int channels,
int origin=0,
int align=4);

image Image header to initialize

size Image width and height

depth Image depth (see cvCreateImage)

channels Number of channels (see cvCreateImage)

origin Top-left IPL ORIGIN TL or bottom-left IPL ORIGIN BL

align Alignment for image rows, typically 4 or 8 bytes

The returned IplImage* points to the initialized header.

98 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

cvInitMatHeader (view/add comments)

Initializes a pre-allocated matrix header.

CvMat* cvInitMatHeader(
CvMat* mat,
int rows,
int cols,
int type,
void* data=NULL,
int step=CV AUTOSTEP);

mat A pointer to the matrix header to be initialized

rows Number of rows in the matrix

cols Number of columns in the matrix

type Type of the matrix elements, see cvCreateMat.

data Optional: data pointer assigned to the matrix header

step Optional: full row width in bytes of the assigned data. By default, the minimal possible step
is used which assumes there are no gaps between subsequent rows of the matrix.

This function is often used to process raw data with OpenCV matrix functions. For example,
the following code computes the matrix product of two matrices, stored as ordinary arrays:
double a[] = { 1, 2, 3, 4,
5, 6, 7, 8,
9, 10, 11, 12 };

double b[] = { 1, 5, 9,
2, 6, 10,
3, 7, 11,
4, 8, 12 };

double c[9];
CvMat Ma, Mb, Mc ;

cvInitMatHeader(&Ma, 3, 4, CV_64FC1, a);

1.2. OPERATIONS ON ARRAYS 99

cvInitMatHeader(&Mb, 4, 3, CV_64FC1, b);

cvInitMatHeader(&Mc, 3, 3, CV_64FC1, c);

cvMatMulAdd(&Ma, &Mb, 0, &Mc);

// the c array now contains the product of a (3x4) and b (4x3)

cvInitMatNDHeader (view/add comments)

Initializes a pre-allocated multi-dimensional array header.

CvMatND* cvInitMatNDHeader(
CvMatND* mat,
int dims,
const int* sizes,
int type,
void* data=NULL);

mat A pointer to the array header to be initialized

dims The number of array dimensions

sizes An array of dimension sizes

type Type of array elements, see cvCreateMat

data Optional data pointer assigned to the matrix header

cvInitSparseMatIterator (view/add comments)

Initializes sparse array elements iterator.

CvSparseNode* cvInitSparseMatIterator(const CvSparseMat* mat,

CvSparseMatIterator* matIterator);

mat Input array

100 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

matIterator Initialized iterator

The function initializes iterator of sparse array elements and returns pointer to the first element,
or NULL if the array is empty.

cvInvSqrt (view/add comments)

Calculates the inverse square root.

float cvInvSqrt(float value);

value The input floating-point value

The function calculates the inverse square root of the argument, and normally it is faster than
1./sqrt(value). If the argument is zero or negative, the result is not determined. Special
values (±∞ , NaN) are not handled.

cvInv (view/add comments)

Synonym for Invert

cvInvert (view/add comments)

Finds the inverse or pseudo-inverse of a matrix.

double cvInvert(const CvArr* src, CvArr* dst, int method=CV LU);

src The source matrix

dst The destination matrix

method Inversion method

CV LU Gaussian elimination with optimal pivot element chosen

CV SVD Singular value decomposition (SVD) method
1.2. OPERATIONS ON ARRAYS 101

CV SVD SYM SVD method for a symmetric positively-defined matrix

The function inverts matrix src1 and stores the result in src2.
In the case of LU method, the function returns the src1 determinant (src1 must be square). If
it is 0, the matrix is not inverted and src2 is filled with zeros.
In the case of SVD methods, the function returns the inversed condition of src1 (ratio of the
smallest singular value to the largest singular value) and 0 if src1 is all zeros. The SVD methods
calculate a pseudo-inverse matrix if src1 is singular.

cvIsInf (view/add comments)

Determines if the argument is Infinity.

int cvIsInf(double value);

value The input floating-point value

The function returns 1 if the argument is ±∞ (as defined by IEEE754 standard), 0 otherwise.

cvIsNaN (view/add comments)

Determines if the argument is Not A Number.

int cvIsNaN(double value);

value The input floating-point value

The function returns 1 if the argument is Not A Number (as defined by IEEE754 standard), 0
otherwise.

cvLUT (view/add comments)

Performs a look-up table transform of an array.
102 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

void cvLUT(const CvArr* src, CvArr* dst, const CvArr* lut);

src Source array of 8-bit elements

dst Destination array of a given depth and of the same number of channels as the source array
lut Look-up table of 256 elements; should have the same depth as the destination array. In the
case of multi-channel source and destination arrays, the table should either have a single-
channel (in this case the same table is used for all channels) or the same number of channels
as the source/destination array.

The function fills the destination array with values from the look-up table. Indices of the entries
are taken from the source array. That is, the function processes each element of src as follows:

dsti ← lutsrci +d
where

0 if src has depth CV 8U
d=
128 if src has depth CV 8S

cvLog (view/add comments)

Calculates the natural logarithm of every array element’s absolute value.

void cvLog(const CvArr* src, CvArr* dst);

src The source array

dst The destination array, it should have double type or the same type as the source

The function calculates the natural logarithm of the absolute value of every element of the input
array:

log |src(I) if src[I] 6= 0
dst[I] =
C otherwise
Where C is a large negative number (about -700 in the current implementation).
1.2. OPERATIONS ON ARRAYS 103

cvMahalanobis (view/add comments)

Calculates the Mahalanobis distance between two vectors.

double cvMahalanobis(
const CvArr* vec1,
const CvArr* vec2,
CvArr* mat);

vec1 The first 1D source vector

vec2 The second 1D source vector

mat The inverse covariance matrix

The function calculates and returns the weighted distance between two vectors:

sX
d(vec1, vec2) = icovar(i,j) · (vec1(I) − vec2(I)) · (vec1(j) − vec2(j))
i,j

The covariance matrix may be calculated using the cvCalcCovarMatrix function and further
inverted using the cvInvert function (CV SVD method is the prefered one because the matrix
might be singular).

cvMat (view/add comments)

Initializes matrix header (lightweight variant).

CvMat cvMat(
int rows,
int cols,
int type,
void* data=NULL);

rows Number of rows in the matrix

104 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

cols Number of columns in the matrix

type Type of the matrix elements - see cvCreateMat

data Optional data pointer assigned to the matrix header

Initializes a matrix header and assigns data to it. The matrix is filled row-wise (the first cols
elements of data form the first row of the matrix, etc.)
This function is a fast inline substitution for cvInitMatHeader. Namely, it is equivalent to:
CvMat mat;
cvInitMatHeader(&mat, rows, cols, type, data, CV\_AUTOSTEP);

cvMax (view/add comments)

Finds per-element maximum of two arrays.

void cvMax(const CvArr* src1, const CvArr* src2, CvArr* dst);

src1 The first source array

src2 The second source array

dst The destination array

The function calculates per-element maximum of two arrays:

dst(I) = max(src1(I), src2(I))

All the arrays must have a single channel, the same data type and the same size (or ROI size).

cvMaxS (view/add comments)

Finds per-element maximum of array and scalar.

void cvMaxS(const CvArr* src, double value, CvArr* dst);

1.2. OPERATIONS ON ARRAYS 105

src The first source array

value The scalar value

dst The destination array

The function calculates per-element maximum of array and scalar:

dst(I) = max(src(I), value)

All the arrays must have a single channel, the same data type and the same size (or ROI size).

cvMerge (view/add comments)

Composes a multi-channel array from several single-channel arrays or inserts a single channel
into the array.

void cvMerge(const CvArr* src0, const CvArr* src1, const CvArr* src2,
const CvArr* src3, CvArr* dst);

#define cvCvtPlaneToPix cvMerge

src0 Input channel 0

src1 Input channel 1

src2 Input channel 2

src3 Input channel 3

dst Destination array

The function is the opposite to cvSplit. If the destination array has N channels then if the first
N input channels are not NULL, they all are copied to the destination array; if only a single source
channel of the first N is not NULL, this particular channel is copied into the destination array;
otherwise an error is raised. The rest of the source channels (beyond the first N) must always
be NULL. For IplImage cvCopy with COI set can be also used to insert a single channel into the
image.
106 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

cvMin (view/add comments)

Finds per-element minimum of two arrays.

void cvMin(const CvArr* src1, const CvArr* src2, CvArr* dst);

src1 The first source array

src2 The second source array

dst The destination array

The function calculates per-element minimum of two arrays:

dst(I) = min(src1(I), src2(I))

All the arrays must have a single channel, the same data type and the same size (or ROI size).

cvMinMaxLoc (view/add comments)

Finds global minimum and maximum in array or subarray.

void cvMinMaxLoc(const CvArr* arr, double* minVal, double* maxVal,

CvPoint* minLoc=NULL, CvPoint* maxLoc=NULL, const CvArr* mask=NULL);

arr The source array, single-channel or multi-channel with COI set

minVal Pointer to returned minimum value

maxVal Pointer to returned maximum value

minLoc Pointer to returned minimum location

maxLoc Pointer to returned maximum location

mask The optional mask used to select a subarray

1.2. OPERATIONS ON ARRAYS 107

The function finds minimum and maximum element values and their positions. The extremums
are searched across the whole array, selected ROI (in the case of IplImage) or, if mask is not
NULL, in the specified array region. If the array has more than one channel, it must be IplImage
with COI set. In the case of multi-dimensional arrays, minLoc->x and maxLoc->x will contain
raw (linear) positions of the extremums.

cvMinS (view/add comments)

Finds per-element minimum of an array and a scalar.

void cvMinS(const CvArr* src, double value, CvArr* dst);

src The first source array

value The scalar value

dst The destination array

The function calculates minimum of an array and a scalar:

dst(I) = min(src(I), value)

All the arrays must have a single channel, the same data type and the same size (or ROI size).

Mirror
Synonym for Flip .

cvMixChannels (view/add comments)

Copies several channels from input arrays to certain channels of output arrays

void cvMixChannels(const CvArr** src, int srcCount,

CvArr** dst, int dstCount,
const int* fromTo, int pairCount);
108 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

src Input arrays

srcCount The number of input arrays.
dst Destination arrays
dstCount The number of output arrays.
fromTo The array of pairs of indices of the planes copied. fromTo[k*2] is the 0-based in-
dex of the input channel in src and fromTo[k*2+1] is the index of the output channel in
dst. Here the continuous channel numbering is used, that is, the first input image channels
are indexed from 0 to channels(src[0])-1, the second input image channels are in-
dexed from channels(src[0]) to channels(src[0]) + channels(src[1])-1 etc.,
and the same scheme is used for the output image channels. As a special case, when
fromTo[k*2] is negative, the corresponding output channel is filled with zero.
The function is a generalized form of cvcvSplit and cvMerge and some forms of CvtColor .
It can be used to change the order of the planes, add/remove alpha channel, extract or insert a
single plane or multiple planes etc.
As an example, this code splits a 4-channel RGBA image into a 3-channel BGR (i.e. with R
and B swapped) and separate alpha channel image:
CvMat* rgba = cvCreateMat(100, 100, CV_8UC4);
CvMat* bgr = cvCreateMat(rgba->rows, rgba->cols, CV_8UC3);
CvMat* alpha = cvCreateMat(rgba->rows, rgba->cols, CV_8UC1);
cvSet(rgba, cvScalar(1,2,3,4));

CvArr* out[] = { bgr, alpha };

int from_to[] = { 0,2, 1,1, 2,0, 3,3 };
cvMixChannels(&bgra, 1, out, 2, from_to, 4);

MulAddS
Synonym for ScaleAdd .

cvMul (view/add comments)

Calculates the per-element product of two arrays.

void cvMul(const CvArr* src1, const CvArr* src2, CvArr* dst, double
scale=1);
1.2. OPERATIONS ON ARRAYS 109

src1 The first source array

src2 The second source array

dst The destination array

scale Optional scale factor

The function calculates the per-element product of two arrays:

dst(I) = scale · src1(I) · src2(I)

All the arrays must have the same type and the same size (or ROI size). For types that have
limited range this operation is saturating.

cvMulSpectrums (view/add comments)

Performs per-element multiplication of two Fourier spectrums.

void cvMulSpectrums(
const CvArr* src1,
const CvArr* src2,
CvArr* dst,
int flags);

src1 The first source array

src2 The second source array

dst The destination array of the same type and the same size as the source arrays

flags A combination of the following values;

CV DXT ROWS treats each row of the arrays as a separate spectrum (see cvDFT parameters
description).
CV DXT MUL CONJ conjugate the second source array before the multiplication.

The function performs per-element multiplication of the two CCS-packed or complex matrices
that are results of a real or complex Fourier transform.
The function, together with cvDFT, may be used to calculate convolution of two arrays rapidly.
110 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

cvMulTransposed (view/add comments)

Calculates the product of an array and a transposed array.

void cvMulTransposed(const CvArr* src, CvArr* dst, int order, const

CvArr* delta=NULL, double scale=1.0);

src The source matrix

dst The destination matrix. Must be CV 32F or CV 64F.

order Order of multipliers

delta An optional array, subtracted from src before multiplication

scale An optional scaling

The function calculates the product of src and its transposition:

dst = scale(src − delta)(src − delta)T

if order = 0, and

dst = scale(src − delta)T (src − delta)

otherwise.

cvNorm (view/add comments)

Calculates absolute array norm, absolute difference norm, or relative difference norm.

double cvNorm(const CvArr* arr1, const CvArr* arr2=NULL, int

normType=CV L2, const CvArr* mask=NULL);

arr1 The first source image

arr2 The second source image. If it is NULL, the absolute norm of arr1 is calculated, otherwise
the absolute or relative norm of arr1-arr2 is calculated.
1.2. OPERATIONS ON ARRAYS 111

normType Type of norm, see the discussion

mask The optional operation mask

The function calculates the absolute norm of arr1 if arr2 is NULL:


 ||arr1||C = max
P I |arr1(I)| if normType = CV C
norm = ||arr1||L1 = p I |arr1(I)| if normType = CV L1
2
P
||arr1||L2 = if normType = CV L2

I arr1(I)

or the absolute difference norm if arr2 is not NULL:


 ||arr1 − arr2||C = max P I |arr1(I) − arr2(I)| if normType = CV C
norm = ||arr1 − arr2||L1 = p I |arr1(I) − arr2(I)| if normType = CV L1
2
P
||arr1 − arr2||L2 = I (arr1(I) − arr2(I)) if normType = CV L2


or the relative difference norm if arr2 is not NULL and (normType & CV RELATIVE) !=
0:

||arr1−arr2||C


 ||arr2||C if normType = CV RELATIVE C
||arr1−arr2||L1
norm = ||arr2||L1 if normType = CV RELATIVE L1
||arr1−arr2||L2

if normType = CV RELATIVE L2


||arr2||L2

The function returns the calculated norm. A multiple-channel array is treated as a single-
channel, that is, the results for all channels are combined.

cvNot (view/add comments)

Performs per-element bit-wise inversion of array elements.

void cvNot(const CvArr* src, CvArr* dst);

src The source array

dst The destination array

The function Not inverses every bit of every array element:

dst(I)=˜src(I)
112 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

cvOr (view/add comments)

Calculates per-element bit-wise disjunction of two arrays.

void cvOr(const CvArr* src1, const CvArr* src2, CvArr* dst, const
CvArr* mask=NULL);

src1 The first source array

src2 The second source array

dst The destination array

mask Operation mask, 8-bit single channel array; specifies elements of the destination array to
be changed

The function calculates per-element bit-wise disjunction of two arrays:

dst(I)=src1(I)|src2(I)
In the case of floating-point arrays their bit representations are used for the operation. All the
arrays must have the same type, except the mask, and the same size.

cvOrS (view/add comments)

Calculates a per-element bit-wise disjunction of an array and a scalar.

void cvOrS(const CvArr* src, CvScalar value, CvArr* dst, const CvArr*
mask=NULL);

src The source array

value Scalar to use in the operation

dst The destination array

mask Operation mask, 8-bit single channel array; specifies elements of the destination array to
be changed
1.2. OPERATIONS ON ARRAYS 113

The function OrS calculates per-element bit-wise disjunction of an array and a scalar:
dst(I)=src(I)|value if mask(I)!=0

Prior to the actual operation, the scalar is converted to the same type as that of the array(s). In
the case of floating-point arrays their bit representations are used for the operation. All the arrays
must have the same type, except the mask, and the same size.

cvPerspectiveTransform (view/add comments)

Performs perspective matrix transformation of a vector array.

void cvPerspectiveTransform(const CvArr* src, CvArr* dst, const CvMat*

mat);

src The source three-channel floating-point array

dst The destination three-channel floating-point array

mat 3 × 3 or 4 × 4 transformation matrix

The function transforms every element of src (by treating it as 2D or 3D vector) in the following
way:

(x, y, z) → (x0 /w, y 0 /w, z 0 /w)

where

(x0 , y 0 , z 0 , w0 ) = mat · x y z 1
 

and
w0 if w0 6= 0

w=
∞ otherwise

cvPolarToCart (view/add comments)

Calculates Cartesian coordinates of 2d vectors represented in polar form.
114 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

void cvPolarToCart(
const CvArr* magnitude,
const CvArr* angle,
CvArr* x,
CvArr* y,
int angleInDegrees=0);

magnitude The array of magnitudes. If it is NULL, the magnitudes are assumed to be all 1’s.

angle The array of angles, whether in radians or degrees

x The destination array of x-coordinates, may be set to NULL if it is not needed

y The destination array of y-coordinates, mau be set to NULL if it is not needed

angleInDegrees The flag indicating whether the angles are measured in radians, which is de-
fault mode, or in degrees

The function calculates either the x-coodinate, y-coordinate or both of every vector magnitude(I)*exp(angl
j=sqrt(-1):
x(I)=magnitude(I)*cos(angle(I)),
y(I)=magnitude(I)*sin(angle(I))

cvPow (view/add comments)

Raises every array element to a power.

void cvPow(
const CvArr* src,
CvArr* dst,
double power);

src The source array

dst The destination array, should be the same type as the source
1.2. OPERATIONS ON ARRAYS 115

power The exponent of power

The function raises every element of the input array to p:

src(I)p

if p is integer
dst[I] =
|src(I)p | otherwise
That is, for a non-integer power exponent the absolute values of input array elements are used.
However, it is possible to get true values for negative values using some extra operations, as the
following example, computing the cube root of array elements, shows:
CvSize size = cvGetSize(src);
CvMat* mask = cvCreateMat([Link], [Link], CV_8UC1);
cvCmpS(src, 0, mask, CV_CMP_LT); /* find negative elements */
cvPow(src, dst, 1./3);
cvSubRS(dst, cvScalarAll(0), dst, mask); /* negate the results of negative inputs */
cvReleaseMat(&mask);
For some values of power, such as integer values, 0.5, and -0.5, specialized faster algorithms
are used.

cvPtr?D (view/add comments)

Return pointer to a particular array element.

uchar* cvPtr1D(const CvArr* arr, int idx0, int* type=NULL);

uchar* cvPtr2D(const CvArr* arr, int idx0, int idx1, int* type=NULL);
uchar* cvPtr3D(const CvArr* arr, int idx0, int idx1, int idx2, int*
type=NULL);
uchar* cvPtrND(const CvArr* arr, int* idx, int* type=NULL, int
createNode=1, unsigned* precalcHashval=NULL);

arr Input array

idx0 The first zero-based component of the element index

idx1 The second zero-based component of the element index

idx2 The third zero-based component of the element index

idx Array of the element indices

116 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

type Optional output parameter: type of matrix elements

createNode Optional input parameter for sparse matrices. Non-zero value of the parameter
means that the requested element is created if it does not exist already.

precalcHashval Optional input parameter for sparse matrices. If the pointer is not NULL, the
function does not recalculate the node hash value, but takes it from the specified location. It
is useful for speeding up pair-wise operations (TODO: provide an example)

The functions return a pointer to a specific array element. Number of array dimension should
match to the number of indices passed to the function except for cvPtr1D function that can be
used for sequential access to 1D, 2D or nD dense arrays.
The functions can be used for sparse arrays as well - if the requested node does not exist they
create it and set it to zero.
All these as well as other functions accessing array elements ( cvGet, cvGetReal, cvSet,
cvSetReal) raise an error in case if the element index is out of range.

cvRNG (view/add comments)

Initializes a random number generator state.

CvRNG cvRNG(int64 seed=-1);

seed 64-bit value used to initiate a random sequence

The function initializes a random number generator and returns the state. The pointer to the
state can be then passed to the cvRandInt, cvRandReal and cvRandArr functions. In the current
implementation a multiply-with-carry generator is used.

cvRandArr (view/add comments)

Fills an array with random numbers and updates the RNG state.

void cvRandArr(
CvRNG* rng,
CvArr* arr,
1.2. OPERATIONS ON ARRAYS 117

int distType,
CvScalar param1,
CvScalar param2);

rng RNG state initialized by cvRNG

arr The destination array

distType Distribution type

CV RAND UNI uniform distribution

CV RAND NORMAL normal or Gaussian distribution

param1 The first parameter of the distribution. In the case of a uniform distribution it is the inclu-
sive lower boundary of the random numbers range. In the case of a normal distribution it is
the mean value of the random numbers.

param2 The second parameter of the distribution. In the case of a uniform distribution it is the
exclusive upper boundary of the random numbers range. In the case of a normal distribution
it is the standard deviation of the random numbers.

The function fills the destination array with uniformly or normally distributed random numbers.
In the example below, the function is used to add a few normally distributed floating-point
numbers to random locations within a 2d array.
/* let noisy_screen be the floating-point 2d array that is to be "crapped" */
CvRNG rng_state = cvRNG(0xffffffff);
int i, pointCount = 1000;
/* allocate the array of coordinates of points */
CvMat* locations = cvCreateMat(pointCount, 1, CV_32SC2);
/* arr of random point values */
CvMat* values = cvCreateMat(pointCount, 1, CV_32FC1);
CvSize size = cvGetSize(noisy_screen);

/* initialize the locations */

cvRandArr(&rng_state, locations, CV_RAND_UNI, cvScalar(0,0,0,0),
cvScalar([Link],[Link],0,0));

/* generate values */
cvRandArr(&rng_state, values, CV_RAND_NORMAL,
cvRealScalar(100), // average intensity
cvRealScalar(30) // deviation of the intensity
118 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

);

/* set the points */

for(i = 0; i < pointCount; i++ )
{
CvPoint pt = *(CvPoint*)cvPtr1D(locations, i, 0);
float value = *(float*)cvPtr1D(values, i, 0);
*((float*)cvPtr2D(noisy_screen, pt.y, pt.x, 0 )) += value;
}

/* not to forget to release the temporary arrays */

cvReleaseMat(&locations);
cvReleaseMat(&values);

/* RNG state does not need to be deallocated */

cvRandInt (view/add comments)

Returns a 32-bit unsigned integer and updates RNG.

unsigned cvRandInt(CvRNG* rng);

rng RNG state initialized by RandInit and, optionally, customized by RandSetRange (though,
the latter function does not affect the discussed function outcome)

The function returns a uniformly-distributed random 32-bit unsigned integer and updates the
RNG state. It is similar to the rand() function from the C runtime library, but it always generates a
32-bit number whereas rand() returns a number in between 0 and RAND MAX which is 216 or 232 ,
depending on the platform.
The function is useful for generating scalar random numbers, such as points, patch sizes, table
indices, etc., where integer numbers of a certain range can be generated using a modulo operation
and floating-point numbers can be generated by scaling from 0 to 1 or any other specific range.
Here is the example from the previous function discussion rewritten using cvRandInt:
/* the input and the task is the same as in the previous sample. */
CvRNG rnggstate = cvRNG(0xffffffff);
int i, pointCount = 1000;
/* ... - no arrays are allocated here */
CvSize size = cvGetSize(noisygscreen);
1.2. OPERATIONS ON ARRAYS 119

/* make a buffer for normally distributed numbers to reduce call overhead */

#define bufferSize 16
float normalValueBuffer[bufferSize];
CvMat normalValueMat = cvMat(bufferSize, 1, CVg32F, normalValueBuffer);
int valuesLeft = 0;

for(i = 0; i < pointCount; i++ )

{
CvPoint pt;
/* generate random point */
pt.x = cvRandInt(&rnggstate ) % [Link];
pt.y = cvRandInt(&rnggstate ) % [Link];

if(valuesLeft <= 0 )
{
/* fulfill the buffer with normally distributed numbers
if the buffer is empty */
cvRandArr(&rnggstate, &normalValueMat, CV\_RAND\_NORMAL,
cvRealScalar(100), cvRealScalar(30));
valuesLeft = bufferSize;
}
*((float*)cvPtr2D(noisygscreen, pt.y, pt.x, 0 ) =
normalValueBuffer[--valuesLeft];
}

/* there is no need to deallocate normalValueMat because we have

both the matrix header and the data on stack. It is a common and efficient
practice of working with small, fixed-size matrices */

cvRandReal (view/add comments)

Returns a floating-point random number and updates RNG.

double cvRandReal(CvRNG* rng);

rng RNG state initialized by cvRNG

The function returns a uniformly-distributed random floating-point number between 0 and 1 (1

is not included).
120 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

cvReduce (view/add comments)

Reduces a matrix to a vector.

void cvReduce(const CvArr* src, CvArr* dst, int dim = -1, int
op=CV REDUCE SUM);

src The input matrix.

dst The output single-row/single-column vector that accumulates somehow all the matrix rows/-
columns.

dim The dimension index along which the matrix is reduced. 0 means that the matrix is reduced
to a single row, 1 means that the matrix is reduced to a single column and -1 means that the
dimension is chosen automatically by analysing the dst size.

op The reduction operation. It can take of the following values:

CV REDUCE SUM The output is the sum of all of the matrix’s rows/columns.
CV REDUCE AVG The output is the mean vector of all of the matrix’s rows/columns.
CV REDUCE MAX The output is the maximum (column/row-wise) of all of the matrix’s rows/-
columns.
CV REDUCE MIN The output is the minimum (column/row-wise) of all of the matrix’s rows/-
columns.

The function reduces matrix to a vector by treating the matrix rows/columns as a set of 1D
vectors and performing the specified operation on the vectors until a single row/column is obtained.
For example, the function can be used to compute horizontal and vertical projections of an raster
image. In the case of CV REDUCE SUM and CV REDUCE AVG the output may have a larger element
bit-depth to preserve accuracy. And multi-channel arrays are also supported in these two reduction
modes.

cvReleaseData (view/add comments)

Releases array data.
1.2. OPERATIONS ON ARRAYS 121

void cvReleaseData(CvArr* arr);

arr Array header

The function releases the array data. In the case of CvMat or CvMatND it simply calls
cvDecRefData(), that is the function can not deallocate external data. See also the note to cvCre-
ateData.

cvReleaseImage (view/add comments)

Deallocates the image header and the image data.

void cvReleaseImage(IplImage** image);

image Double pointer to the image header

This call is a shortened form of

if(*image )
{
cvReleaseData(*image);
cvReleaseImageHeader(image);
}

cvReleaseImageHeader (view/add comments)

Deallocates an image header.

void cvReleaseImageHeader(IplImage** image);

image Double pointer to the image header

122 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

This call is an analogue of

if(image )
{
iplDeallocate(*image, IPL_IMAGE_HEADER | IPL_IMAGE_ROI);
*image = 0;
}
but it does not use IPL functions by default (see the CV TURN ON IPL COMPATIBILITY macro).

cvReleaseMat (view/add comments)

Deallocates a matrix.

void cvReleaseMat(CvMat** mat);

mat Double pointer to the matrix

The function decrements the matrix data reference counter and deallocates matrix header. If
the data reference counter is 0, it also deallocates the data.
if(*mat )
cvDecRefData(*mat);
cvFree((void**)mat);

cvReleaseMatND (view/add comments)

Deallocates a multi-dimensional array.

void cvReleaseMatND(CvMatND** mat);

mat Double pointer to the array

The function decrements the array data reference counter and releases the array header. If
the reference counter reaches 0, it also deallocates the data.
if(*mat )
cvDecRefData(*mat);
cvFree((void**)mat);
1.2. OPERATIONS ON ARRAYS 123

cvReleaseSparseMat (view/add comments)

Deallocates sparse array.

void cvReleaseSparseMat(CvSparseMat** mat);

mat Double pointer to the array

The function releases the sparse array and clears the array pointer upon exit.

cvRepeat (view/add comments)

Fill the destination array with repeated copies of the source array.

void cvRepeat(const CvArr* src, CvArr* dst);

src Source array, image or matrix

dst Destination array, image or matrix

The function fills the destination array with repeated copies of the source array:
dst(i,j)=src(i mod rows(src), j mod cols(src))
So the destination array may be as larger as well as smaller than the source array.

cvResetImageROI (view/add comments)

Resets the image ROI to include the entire image and releases the ROI structure.

void cvResetImageROI(IplImage* image);

image A pointer to the image header

124 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

This produces a similar result to the following , but in addition it releases the ROI structure.
cvSetImageROI(image, cvRect(0, 0, image->width, image->height ));
cvSetImageCOI(image, 0);

cvReshape (view/add comments)

Changes shape of matrix/image without copying data.

CvMat* cvReshape(const CvArr* arr, CvMat* header, int newCn, int

newRows=0);

arr Input array

header Output header to be filled

newCn New number of channels. ’newCn = 0’ means that the number of channels remains un-
changed.

newRows New number of rows. ’newRows = 0’ means that the number of rows remains un-
changed unless it needs to be changed according to newCn value.

The function initializes the CvMat header so that it points to the same data as the original array
but has a different shape - different number of channels, different number of rows, or both.
The following example code creates one image buffer and two image headers, the first is for a
320x240x3 image and the second is for a 960x240x1 image:
IplImage* color_img = cvCreateImage(cvSize(320,240), IPL_DEPTH_8U, 3);
CvMat gray_mat_hdr;
IplImage gray_img_hdr, *gray_img;
cvReshape(color_img, &gray_mat_hdr, 1);
gray_img = cvGetImage(&gray_mat_hdr, &gray_img_hdr);

And the next example converts a 3x3 matrix to a single 1x9 vector:
CvMat* mat = cvCreateMat(3, 3, CV_32F);
CvMat row_header, *row;
row = cvReshape(mat, &row_header, 0, 1);
1.2. OPERATIONS ON ARRAYS 125

cvReshapeMatND (view/add comments)

Changes the shape of a multi-dimensional array without copying the data.

CvArr* cvReshapeMatND(const CvArr* arr, int sizeofHeader, CvArr*

header, int newCn, int newDims, int* newSizes);

#define cvReshapeND(arr, header, newCn, newDims, newSizes ) \

cvReshapeMatND((arr), sizeof(*(header)), (header), \
(newCn), (newDims), (newSizes))

arr Input array

sizeofHeader Size of output header to distinguish between IplImage, CvMat and CvMatND
output headers

header Output header to be filled

newCn New number of channels. newCn = 0 means that the number of channels remains un-
changed.

newDims New number of dimensions. newDims = 0 means that the number of dimensions
remains the same.

newSizes Array of new dimension sizes. Only newDims − 1 values are used, because the total
number of elements must remain the same. Thus, if newDims = 1, newSizes array is not
used.

The function is an advanced version of cvReshape that can work with multi-dimensional ar-
rays as well (though it can work with ordinary images and matrices) and change the number of
dimensions.
Below are the two samples from the cvReshape description rewritten using cvReshape-
MatND:

IplImage* color_img = cvCreateImage(cvSize(320,240), IPL_DEPTH_8U, 3);

IplImage gray_img_hdr, *gray_img;
gray_img = (IplImage*)cvReshapeND(color_img, &gray_img_hdr, 1, 0, 0);

...
126 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

/* second example is modified to convert 2x2x2 array to 8x1 vector */

int size[] = { 2, 2, 2 };
CvMatND* mat = cvCreateMatND(3, size, CV_32F);
CvMat row_header, *row;
row = (CvMat*)cvReshapeND(mat, &row_header, 0, 1, 0);

cvRound, cvFloor, cvCeil (view/add comments)

Converts a floating-point number to an integer.

int cvRound(double value); int cvFloor(double value); int cvCeil(double

value);

value The input floating-point value

The functions convert the input floating-point number to an integer using one of the rounding
modes. Round returns the nearest integer value to the argument. Floor returns the maximum
integer value that is not larger than the argument. Ceil returns the minimum integer value that
is not smaller than the argument. On some architectures the functions work much faster than the
standard cast operations in C. If the absolute value of the argument is greater than 231 , the result
is not determined. Special values (±∞ , NaN) are not handled.

cvScaleAdd (view/add comments)

Calculates the sum of a scaled array and another array.

void cvScaleAdd(const CvArr* src1, CvScalar scale, const CvArr* src2,

CvArr* dst);

src1 The first source array

scale Scale factor for the first array

src2 The second source array

1.2. OPERATIONS ON ARRAYS 127

dst The destination array

The function calculates the sum of a scaled array and another array:

dst(I) = scale src1(I) + src2(I)

All array parameters should have the same type and the same size.

cvSet (view/add comments)

Sets every element of an array to a given value.

void cvSet(CvArr* arr, CvScalar value, const CvArr* mask=NULL);

arr The destination array

value Fill value

mask Operation mask, 8-bit single channel array; specifies elements of the destination array to
be changed

The function copies the scalar value to every selected element of the destination array:

arr(I) = value if mask(I) 6= 0

If array arr is of IplImage type, then is ROI used, but COI must not be set.

cvSet?D (view/add comments)

Change the particular array element.

void cvSet1D(CvArr* arr, int idx0, CvScalar value);

void cvSet2D(CvArr* arr, int idx0, int idx1, CvScalar value);
void cvSet3D(CvArr* arr, int idx0, int idx1, int idx2, CvScalar value);
void cvSetND(CvArr* arr, int* idx, CvScalar value);
128 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

arr Input array

idx0 The first zero-based component of the element index

idx1 The second zero-based component of the element index

idx2 The third zero-based component of the element index

idx Array of the element indices

value The assigned value

The functions assign the new value to a particular array element. In the case of a sparse array
the functions create the node if it does not exist yet.

cvSetData (view/add comments)

Assigns user data to the array header.

void cvSetData(CvArr* arr, void* data, int step);

arr Array header

data User data

step Full row length in bytes

The function assigns user data to the array header. Header should be initialized before using
cvCreate*Header, cvInit*Header or cvMat (in the case of matrix) function.

cvSetIdentity (view/add comments)

Initializes a scaled identity matrix.

void cvSetIdentity(CvArr* mat, CvScalar value=cvRealScalar(1));

mat The matrix to initialize (not necesserily square)

1.2. OPERATIONS ON ARRAYS 129

value The value to assign to the diagonal elements

The function initializes a scaled identity matrix:


value if i = j
arr(i, j) =
0 otherwise

cvSetImageCOI (view/add comments)

Sets the channel of interest in an IplImage.

void cvSetImageCOI(
IplImage* image,
int coi);

image A pointer to the image header

coi The channel of interest. 0 - all channels are selected, 1 - first channel is selected, etc. Note
that the channel indices become 1-based.

If the ROI is set to NULL and the coi is not 0, the ROI is allocated. Most OpenCV functions do
not support the COI setting, so to process an individual image/matrix channel one may copy (via
cvCopy or cvSplit) the channel to a separate image/matrix, process it and then copy the result
back (via cvCopy or cvMerge) if needed.

cvSetImageROI (view/add comments)

Sets an image Region Of Interest (ROI) for a given rectangle.

void cvSetImageROI(
IplImage* image,
CvRect rect);

image A pointer to the image header

130 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

rect The ROI rectangle

If the original image ROI was NULL and the rect is not the whole image, the ROI structure is
allocated.
Most OpenCV functions support the use of ROI and treat the image rectangle as a separate
image. For example, all of the pixel coordinates are counted from the top-left (or bottom-left)
corner of the ROI, not the original image.

cvSetReal?D (view/add comments)

Change a specific array element.

void cvSetReal1D(CvArr* arr, int idx0, double value);

void cvSetReal2D(CvArr* arr, int idx0, int idx1, double value);
void cvSetReal3D(CvArr* arr, int idx0, int idx1, int idx2, double
value);
void cvSetRealND(CvArr* arr, int* idx, double value);

arr Input array

idx0 The first zero-based component of the element index

idx1 The second zero-based component of the element index

idx2 The third zero-based component of the element index

idx Array of the element indices

value The assigned value

The functions assign a new value to a specific element of a single-channel array. If the array
has multiple channels, a runtime error is raised. Note that the cvSet*D function can be used safely
for both single-channel and multiple-channel arrays, though they are a bit slower.
In the case of a sparse array the functions create the node if it does not yet exist.

cvSetZero (view/add comments)

Clears the array.
1.2. OPERATIONS ON ARRAYS 131

void cvSetZero(CvArr* arr);

#define cvZero cvSetZero

arr Array to be cleared

The function clears the array. In the case of dense arrays (CvMat, CvMatND or IplImage),
cvZero(array) is equivalent to cvSet(array,cvScalarAll(0),0). In the case of sparse arrays all the
elements are removed.

cvSolve (view/add comments)

Solves a linear system or least-squares problem.

int cvSolve(const CvArr* src1, const CvArr* src2, CvArr* dst, int
method=CV LU);

A The source matrix

B The right-hand part of the linear system

X The output solution

method The solution (matrix inversion) method

CV LU Gaussian elimination with optimal pivot element chosen

CV SVD Singular value decomposition (SVD) method
CV SVD SYM SVD method for a symmetric positively-defined matrix.

The function solves a linear system or least-squares problem (the latter is possible with SVD
methods):

dst = argminX ||src1 X − src2||

If CV LU method is used, the function returns 1 if src1 is non-singular and 0 otherwise; in the
latter case dst is not valid.
132 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

cvSolveCubic (view/add comments)

Finds the real roots of a cubic equation.

void cvSolveCubic(const CvArr* coeffs, CvArr* roots);

coeffs The equation coefficients, an array of 3 or 4 elements

roots The output array of real roots which should have 3 elements

The function finds the real roots of a cubic equation:

If coeffs is a 4-element vector:

coeffs[0]x3 + coeffs[1]x2 + coeffs[2]x + coeffs[3] = 0

or if coeffs is 3-element vector:

x3 + coeffs[0]x2 + coeffs[1]x + coeffs[2] = 0

The function returns the number of real roots found. The roots are stored to root array, which
is padded with zeros if there is only one root.

cvSplit (view/add comments)

Divides multi-channel array into several single-channel arrays or extracts a single channel from
the array.

void cvSplit(const CvArr* src, CvArr* dst0, CvArr* dst1, CvArr* dst2,
CvArr* dst3);

src Source array

dst0 Destination channel 0

dst1 Destination channel 1

dst2 Destination channel 2

1.2. OPERATIONS ON ARRAYS 133

dst3 Destination channel 3

The function divides a multi-channel array into separate single-channel arrays. Two modes
are available for the operation. If the source array has N channels then if the first N destination
channels are not NULL, they all are extracted from the source array; if only a single destination
channel of the first N is not NULL, this particular channel is extracted; otherwise an error is raised.
The rest of the destination channels (beyond the first N) must always be NULL. For IplImage
cvCopy with COI set can be also used to extract a single channel from the image.

cvSqrt (view/add comments)

Calculates the square root.

float cvSqrt(float value);

value The input floating-point value

The function calculates the square root of the argument. If the argument is negative, the result
is not determined.

cvSub (view/add comments)

Computes the per-element difference between two arrays.

void cvSub(const CvArr* src1, const CvArr* src2, CvArr* dst, const
CvArr* mask=NULL);

src1 The first source array

src2 The second source array

dst The destination array

mask Operation mask, 8-bit single channel array; specifies elements of the destination array to
be changed
134 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

The function subtracts one array from another one:

dst(I)=src1(I)-src2(I) if mask(I)!=0
All the arrays must have the same type, except the mask, and the same size (or ROI size). For
types that have limited range this operation is saturating.

cvSubRS (view/add comments)

Computes the difference between a scalar and an array.

void cvSubRS(const CvArr* src, CvScalar value, CvArr* dst, const CvArr*
mask=NULL);

src The first source array

value Scalar to subtract from

dst The destination array

mask Operation mask, 8-bit single channel array; specifies elements of the destination array to
be changed

The function subtracts every element of source array from a scalar:

dst(I)=value-src(I) if mask(I)!=0
All the arrays must have the same type, except the mask, and the same size (or ROI size). For
types that have limited range this operation is saturating.

cvSubS (view/add comments)

Computes the difference between an array and a scalar.

void cvSubS(const CvArr* src, CvScalar value, CvArr* dst, const CvArr*
mask=NULL);

src The source array

1.2. OPERATIONS ON ARRAYS 135

value Subtracted scalar

dst The destination array

mask Operation mask, 8-bit single channel array; specifies elements of the destination array to
be changed

The function subtracts a scalar from every element of the source array:
dst(I)=src(I)-value if mask(I)!=0
All the arrays must have the same type, except the mask, and the same size (or ROI size). For
types that have limited range this operation is saturating.

cvSum (view/add comments)

Adds up array elements.

CvScalar cvSum(const CvArr* arr);

arr The array

The function calculates the sum S of array elements, independently for each channel:
X
arr(I)c
I

If the array is IplImage and COI is set, the function processes the selected channel only and
stores the sum to the first scalar component.

cvSVBkSb (view/add comments)

Performs singular value back substitution.

void cvSVBkSb(
const CvArr* W,
const CvArr* U,
const CvArr* V,
136 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

const CvArr* B,
CvArr* X,
int flags);

W Matrix or vector of singular values

U Left orthogonal matrix (tranposed, perhaps)

V Right orthogonal matrix (tranposed, perhaps)

B The matrix to multiply the pseudo-inverse of the original matrix A by. This is an optional param-
eter. If it is omitted then it is assumed to be an identity matrix of an appropriate size (so that
X will be the reconstructed pseudo-inverse of A).

X The destination matrix: result of back substitution

flags Operation flags, should match exactly to the flags passed to cvSVD

The function calculates back substitution for decomposed matrix A (see cvSVD description)
and matrix B:

X = VW−1 UT B

where
 P
−1 1/W(i,i) if W(i,i) >  i W(i,i)
W(i,i) =
0 otherwise

and  is a small number that depends on the matrix data type.

This function together with cvSVD is used inside cvInvert and cvSolve, and the possible
reason to use these (svd and bksb) ”low-level” function, is to avoid allocation of temporary matrices
inside the high-level counterparts (inv and solve).

cvSVD (view/add comments)

Performs singular value decomposition of a real floating-point matrix.
1.2. OPERATIONS ON ARRAYS 137

void cvSVD(
CvArr* A,
CvArr* W,
CvArr* U=NULL,
CvArr* V=NULL,
int flags=0);

A Source M × N matrix

W Resulting singular value diagonal matrix (M × N or min(M, N) × min(M, N)) or min(M, N) × 1 vector
of the singular values

U Optional left orthogonal matrix, M × min(M, N) (when CV SVD U T is not set), or min(M, N) × M
(when CV SVD U T is set), or M × M (regardless of CV SVD U T flag).

V Optional right orthogonal matrix, N × min(M, N) (when CV SVD V T is not set), or min(M, N) × N
(when CV SVD V T is set), or N × N (regardless of CV SVD V T flag).

flags Operation flags; can be 0 or a combination of the following values:

CV SVD MODIFY A enables modification of matrix A during the operation. It speeds up the
processing.
CV SVD U T means that the transposed matrix U is returned. Specifying the flag speeds up
the processing.
CV SVD V T means that the transposed matrix V is returned. Specifying the flag speeds up
the processing.

The function decomposes matrix A into the product of a diagonal matrix and two
orthogonal matrices:

A=UW VT
where W is a diagonal matrix of singular values that can be coded as a 1D vector of singular
values and U and V . All the singular values are non-negative and sorted (together with U and V
columns) in descending order.
An SVD algorithm is numerically robust and its typical applications include:

• accurate eigenvalue problem solution when matrix A is a square, symmetric, and positively
defined matrix, for example, when it is a covariance matrix. W in this case will be a vector/-
matrix of the eigenvalues, and U = V will be a matrix of the eigenvectors.
138 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

• accurate solution of a poor-conditioned linear system.

• least-squares solution of an overdetermined linear system. This and the preceeding is done
by using the cvSolve function with the CV SVD method.

• accurate calculation of different matrix characteristics such as the matrix rank (the number of
non-zero singular values), condition number (ratio of the largest singular value to the smallest
one), and determinant (absolute value of the determinant is equal to the product of singular
values).

cvTrace (view/add comments)

Returns the trace of a matrix.

CvScalar cvTrace(const CvArr* mat);

mat The source matrix

The function returns the sum of the diagonal elements of the matrix src1.
X
tr(mat) = mat(i, i)
i

cvTransform (view/add comments)

Performs matrix transformation of every array element.

void cvTransform(const CvArr* src, CvArr* dst, const CvMat* transmat,

const CvMat* shiftvec=NULL);

src The first source array

dst The destination array

transmat Transformation matrix

1.2. OPERATIONS ON ARRAYS 139

shiftvec Optional shift vector

The function performs matrix transformation of every element of array src and stores the
results in dst:

dst(I) = transmat · src(I) + shif tvec

That is, every element of an N-channel array src is considered as an N-element vector which
is transformed using a M × N matrix transmat and shift vector shiftvec into an element of
M-channel array dst. There is an option to embedd shiftvec into transmat. In this case
transmat should be a M × (N + 1) matrix and the rightmost column is treated as the shift vector.
Both source and destination arrays should have the same depth and the same size or selected
ROI size. transmat and shiftvec should be real floating-point matrices.
The function may be used for geometrical transformation of n dimensional point set, arbitrary
linear color space transformation, shuffling the channels and so forth.

cvTranspose (view/add comments)

Transposes a matrix.

void cvTranspose(const CvArr* src, CvArr* dst);

src The source matrix

dst The destination matrix

The function transposes matrix src1:

dst(i, j) = src(j, i)
Note that no complex conjugation is done in the case of a complex matrix. Conjugation should
be done separately: look at the sample code in cvXorS for an example.

cvXor (view/add comments)

Performs per-element bit-wise ”exclusive or” operation on two arrays.
140 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

void cvXor(const CvArr* src1, const CvArr* src2, CvArr* dst, const
CvArr* mask=NULL);

src1 The first source array

src2 The second source array

dst The destination array

mask Operation mask, 8-bit single channel array; specifies elements of the destination array to
be changed

The function calculates per-element bit-wise logical conjunction of two arrays:

dst(I)=src1(I)ˆsrc2(I) if mask(I)!=0
In the case of floating-point arrays their bit representations are used for the operation. All the
arrays must have the same type, except the mask, and the same size.

cvXorS (view/add comments)

Performs per-element bit-wise ”exclusive or” operation on an array and a scalar.

void cvXorS(const CvArr* src, CvScalar value, CvArr* dst, const CvArr*
mask=NULL);

src The source array

value Scalar to use in the operation

dst The destination array

mask Operation mask, 8-bit single channel array; specifies elements of the destination array to
be changed

The function XorS calculates per-element bit-wise conjunction of an array and a scalar:
dst(I)=src(I)ˆvalue if mask(I)!=0
1.2. OPERATIONS ON ARRAYS 141

Prior to the actual operation, the scalar is converted to the same type as that of the array(s). In
the case of floating-point arrays their bit representations are used for the operation. All the arrays
must have the same type, except the mask, and the same size
The following sample demonstrates how to conjugate complex vector by switching the most-
significant bit of imaging part:

float a[] = { 1, 0, 0, 1, -1, 0, 0, -1 }; /* 1, j, -1, -j */

CvMat A = cvMat(4, 1, CV\_32FC2, &a);
int i, negMask = 0x80000000;
cvXorS(&A, cvScalar(0, *(float*)&negMask, 0, 0 ), &A, 0);
for(i = 0; i < 4; i++ )
printf("(\%.1f, \%.1f) ", a[i*2], a[i*2+1]);

The code should print:

(1.0,0.0) (0.0,-1.0) (-1.0,0.0) (0.0,1.0)

cvmGet (view/add comments)

Returns the particular element of single-channel floating-point matrix.

double cvmGet(const CvMat* mat, int row, int col);

mat Input matrix

row The zero-based index of row

col The zero-based index of column

The function is a fast replacement for cvGetReal2D in the case of single-channel floating-point
matrices. It is faster because it is inline, it does fewer checks for array type and array element type,
and it checks for the row and column ranges only in debug mode.

cvmSet (view/add comments)

Returns a specific element of a single-channel floating-point matrix.
142 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

void cvmSet(CvMat* mat, int row, int col, double value);

mat The matrix

row The zero-based index of row

col The zero-based index of column

value The new value of the matrix element

The function is a fast replacement for cvSetReal2D in the case of single-channel floating-point
matrices. It is faster because it is inline, it does fewer checks for array type and array element type,
and it checks for the row and column ranges only in debug mode.

1.3 Dynamic Structures

CvMemStorage (view/add comments)

Growing memory storage.
typedef struct CvMemStorage
{
struct CvMemBlock* bottom;/* first allocated block */
struct CvMemBlock* top; /* the current memory block - top of the stack */
struct CvMemStorage* parent; /* borrows new blocks from */
int block\_size; /* block size */
int free\_space; /* free space in the \texttt{top} block (in bytes) */
} CvMemStorage;

Memory storage is a low-level structure used to store dynamicly growing data structures such
as sequences, contours, graphs, subdivisions, etc. It is organized as a list of memory blocks of
equal size - bottom field is the beginning of the list of blocks and top is the currently used block,
but not necessarily the last block of the list. All blocks between bottom and top, not including
the latter, are considered fully occupied; all blocks between top and the last block, not including
top, are considered free and top itself is partly ocupied - free space contains the number of
free bytes left in the end of top.
A new memory buffer that may be allocated explicitly by cvMemStorageAlloc function or im-
plicitly by higher-level functions, such as cvSeqPush, cvGraphAddEdge, etc., always starts in
the end of the current block if it fits there. After allocation, free space is decremented by the
1.3. DYNAMIC STRUCTURES 143

size of the allocated buffer plus some padding to keep the proper alignment. When the allocated
buffer does not fit into the available portion of top, the next storage block from the list is taken as
top and free space is reset to the whole block size prior to the allocation.
If there are no more free blocks, a new block is allocated (or borrowed from the parent, see
cvCreateChildMemStorage) and added to the end of list. Thus, the storage behaves as a stack
with bottom indicating bottom of the stack and the pair (top, free space) indicating top of the
stack. The stack top may be saved via cvSaveMemStoragePos, restored via cvRestoreMemStor-
agePos, or reset via cvClearStorage.

CvMemBlock (view/add comments)

Memory storage block.
typedef struct CvMemBlock
{
struct CvMemBlock* prev;
struct CvMemBlock* next;
} CvMemBlock;
The structure CvMemBlock represents a single block of memory storage. The actual data in
the memory blocks follows the header, that is, the ith byte of the memory block can be retrieved
with the expression ((char*)(mem block ptr+1))[i]. However, there is normally no need to
access the storage structure fields directly.

CvMemStoragePos (view/add comments)

Memory storage position.
typedef struct CvMemStoragePos
{
CvMemBlock* top;
int free\_space;
} CvMemStoragePos;
The structure described above stores the position of the stack top that can be saved via
cvSaveMemStoragePos and restored via cvRestoreMemStoragePos.

CvSeq (view/add comments)

Growable sequence of elements.

#define CV_SEQUENCE\_FIELDS() \
int flags; /* micsellaneous flags */ \
144 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

int header_size; /* size of sequence header */ \

struct CvSeq* h_prev; /* previous sequence */ \
struct CvSeq* h_next; /* next sequence */ \
struct CvSeq* v_prev; /* 2nd previous sequence */ \
struct CvSeq* v_next; /* 2nd next sequence */ \
int total; /* total number of elements */ \
int elem_size;/* size of sequence element in bytes */ \
char* block_max;/* maximal bound of the last block */ \
char* ptr; /* current write pointer */ \
int delta_elems; /* how many elements allocated when the sequence grows
(sequence granularity) */ \
CvMemStorage* storage; /* where the seq is stored */ \
CvSeqBlock* free_blocks; /* free blocks list */ \
CvSeqBlock* first; /* pointer to the first sequence block */

typedef struct CvSeq

{
CV_SEQUENCE_FIELDS()
} CvSeq;

The structure CvSeq is a base for all of OpenCV dynamic data structures.
Such an unusual definition via a helper macro simplifies the extension of the structure CvSeq
with additional parameters. To extend CvSeq the user may define a new structure and put user-
defined fields after all CvSeq fields that are included via the macro CV SEQUENCE FIELDS().
There are two types of sequences - dense and sparse. The base type for dense sequences is
CvSeq and such sequences are used to represent growable 1d arrays - vectors, stacks, queues,
and deques. They have no gaps in the middle - if an element is removed from the middle or
inserted into the middle of the sequence, the elements from the closer end are shifted. Sparse
sequences have CvSet as a base class and they are discussed later in more detail. They are
sequences of nodes; each may be either occupied or free as indicated by the node flag. Such
sequences are used for unordered data structures such as sets of elements, graphs, hash tables
and so forth.
The field header size contains the actual size of the sequence header and should be greater
than or equal to sizeof(CvSeq).
The fields h prev, h next, v prev, v next can be used to create hierarchical structures from
separate sequences. The fields h prev and h next point to the previous and the next sequences
on the same hierarchical level, while the fields v prev and v next point to the previous and the
next sequences in the vertical direction, that is, the parent and its first child. But these are just
names and the pointers can be used in a different way.
The field first points to the first sequence block, whose structure is described below.
The field total contains the actual number of dense sequence elements and number of allo-
cated nodes in a sparse sequence.
1.3. DYNAMIC STRUCTURES 145

The field flags contains the particular dynamic type signature (CV SEQ MAGIC VAL for dense
sequences and CV SET MAGIC VAL for sparse sequences) in the highest 16 bits and miscella-
neous information about the sequence. The lowest CV SEQ ELTYPE BITS bits contain the ID of
the element type. Most of sequence processing functions do not use element type but rather el-
ement size stored in elem size. If a sequence contains the numeric data for one of the CvMat
type then the element type matches to the corresponding CvMat element type, e.g., CV 32SC2
may be used for a sequence of 2D points, CV 32FC1 for sequences of floating-point values, etc. A
CV SEQ ELTYPE(seq header ptr) macro retrieves the type of sequence elements. Processing
functions that work with numerical sequences check that elem size is equal to that calculated
from the type element size. Besides CvMat compatible types, there are few extra element types
defined in the cvtypes.h header:
Standard Types of Sequence Elements

#define CV_SEQ_ELTYPE_POINT CV_32SC2 /* (x,y) */

#define CV_SEQ_ELTYPE_CODE CV_8UC1 /* freeman code: 0..7 */
#define CV_SEQ_ELTYPE_GENERIC 0 /* unspecified type of
sequence elements */
#define CV_SEQ_ELTYPE_PTR CV_USRTYPE1 /* =6 */
#define CV_SEQ_ELTYPE_PPOINT CV_SEQ_ELTYPE_PTR /* &elem: pointer to
element of other sequence */
#define CV_SEQ_ELTYPE_INDEX CV_32SC1 /* #elem: index of element of
some other sequence */
#define CV_SEQ_ELTYPE_GRAPH_EDGE CV_SEQ_ELTYPE_GENERIC /* &next_o,
&next_d, &vtx_o, &vtx_d */
#define CV_SEQ_ELTYPE_GRAPH_VERTEX CV_SEQ_ELTYPE_GENERIC /* first_edge,
&(x,y) */
#define CV_SEQ_ELTYPE_TRIAN_ATR CV_SEQ_ELTYPE_GENERIC /* vertex of the
binary tree */
#define CV_SEQ_ELTYPE_CONNECTED_COMP CV_SEQ_ELTYPE_GENERIC /* connected
component */
#define CV_SEQ_ELTYPE_POINT3D CV_32FC3 /* (x,y,z) */
The next CV SEQ KIND BITS bits specify the kind of sequence:
Standard Kinds of Sequences

/* generic (unspecified) kind of sequence */

#define CV_SEQ_KIND_GENERIC (0 << CV_SEQ_ELTYPE_BITS)

/* dense sequence suntypes */

#define CV_SEQ_KIND_CURVE (1 << CV_SEQ_ELTYPE_BITS)
#define CV_SEQ_KIND_BIN_TREE (2 << CV_SEQ_ELTYPE_BITS)

/* sparse sequence (or set) subtypes */

146 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

#define CV_SEQ_KIND_GRAPH (3 << CV_SEQ_ELTYPE_BITS)

#define CV_SEQ_KIND_SUBDIV2D (4 << CV_SEQ_ELTYPE_BITS)
The remaining bits are used to identify different features specific to certain sequence kinds and
element types. For example, curves made of points (CV SEQ KIND CURVE|CV SEQ ELTYPE POINT),
together with the flag CV SEQ FLAG CLOSED, belong to the type CV SEQ POLYGON or, if other flags
are used, to its subtype. Many contour processing functions check the type of the input sequence
and report an error if they do not support this type. The file cvtypes.h stores the complete list of
all supported predefined sequence types and helper macros designed to get the sequence type
of other properties. The definition of the building blocks of sequences can be found below.

CvSeqBlock (view/add comments)

Continuous sequence block.

typedef struct CvSeqBlock

{
struct CvSeqBlock* prev; /* previous sequence block */
struct CvSeqBlock* next; /* next sequence block */
int start_index; /* index of the first element in the block +
sequence->first->start_index */
int count; /* number of elements in the block */
char* data; /* pointer to the first element of the block */
} CvSeqBlock;
Sequence blocks make up a circular double-linked list, so the pointers prev and next are
never NULL and point to the previous and the next sequence blocks within the sequence. It means
that next of the last block is the first block and prev of the first block is the last block. The fields
startIndex and count help to track the block location within the sequence. For example, if
the sequence consists of 10 elements and splits into three blocks of 3, 5, and 2 elements, and
the first block has the parameter startIndex = 2, then pairs (startIndex, count) for the
sequence blocks are (2,3), (5, 5), and (10, 2) correspondingly. The parameter startIndex of the
first block is usually 0 unless some elements have been inserted at the beginning of the sequence.

CvSlice (view/add comments)

A sequence slice.
typedef struct CvSlice
{
int start_index;
int end_index;
} CvSlice;
1.3. DYNAMIC STRUCTURES 147

inline CvSlice cvSlice( int start, int end );

#define CV_WHOLE_SEQ_END_INDEX 0x3fffffff
#define CV_WHOLE_SEQ cvSlice(0, CV_WHOLE_SEQ_END_INDEX)

/* calculates the sequence slice length */

int cvSliceLength( CvSlice slice, const CvSeq* seq );

Some of functions that operate on sequences take a CvSlice slice parameter that is of-
ten set to the whole sequence (CV WHOLE SEQ) by default. Either of the startIndex and
endIndex may be negative or exceed the sequence length, startIndex is inclusive, and endIndex
is an exclusive boundary. If they are equal, the slice is considered empty (i.e., contains no ele-
ments). Because sequences are treated as circular structures, the slice may select a few elements
in the end of a sequence followed by a few elements at the beginning of the sequence. For ex-
ample, cvSlice(-2, 3) in the case of a 10-element sequence will select a 5-element slice,
containing the pre-last (8th), last (9th), the very first (0th), second (1th) and third (2nd) elements.
The functions normalize the slice argument in the following way: first, cvSliceLength is called to
determine the length of the slice, then, startIndex of the slice is normalized similarly to the ar-
gument of cvGetSeqElem (i.e., negative indices are allowed). The actual slice to process starts at
the normalized startIndex and lasts cvSliceLength elements (again, assuming the sequence
is a circular structure).
If a function does not accept a slice argument, but you want to process only a part of the
sequence, the sub-sequence may be extracted using the cvSeqSlice function, or stored into a
continuous buffer with CvtSeqToArray (optionally, followed by cvMakeSeqHeaderForArray).

CvSet (view/add comments)

Collection of nodes.
typedef struct CvSetElem
{
int flags; /* it is negative if the node is free and zero or positive otherwise */
struct CvSetElem* next_free; /* if the node is free, the field is a
pointer to next free node */
}
CvSetElem;

#define CV_SET_FIELDS() \
CV_SEQUENCE_FIELDS() /* inherits from [#CvSeq CvSeq] */ \
struct CvSetElem* free_elems; /* list of free nodes */

typedef struct CvSet

{
148 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

CV_SET_FIELDS()
} CvSet;

The structure CvSet is a base for OpenCV sparse data structures.

As follows from the above declaration, CvSet inherits from CvSeq and it adds the free elems
field, which is a list of free nodes, to it. Every set node, whether free or not, is an element of the
underlying sequence. While there are no restrictions on elements of dense sequences, the set
(and derived structures) elements must start with an integer field and be able to fit CvSetElem
structure, because these two fields (an integer followed by a pointer) are required for the orga-
nization of a node set with the list of free nodes. If a node is free, the flags field is negative
(the most-significant bit, or MSB, of the field is set), and the next free points to the next free
node (the first free node is referenced by the free elems field of CvSet ). And if a node is
occupied, the flags field is positive and contains the node index that may be retrieved using
the (set elem->flags & CV SET ELEM IDX MASK) expressions, the rest of the node content
is determined by the user. In particular, the occupied nodes are not linked as the free nodes
are, so the second field can be used for such a link as well as for some different purpose. The
macro CV IS SET ELEM(set elem ptr) can be used to determined whether the specified node
is occupied or not.
Initially the set and the list are empty. When a new node is requested from the set, it is taken
from the list of free nodes, which is then updated. If the list appears to be empty, a new sequence
block is allocated and all the nodes within the block are joined in the list of free nodes. Thus, the
total field of the set is the total number of nodes both occupied and free. When an occupied
node is released, it is added to the list of free nodes. The node released last will be occupied first.
In OpenCV CvSet is used for representing graphs ( CvGraph ), sparse multi-dimensional
arrays ( CvSparseMat ), and planar subdivisions CvSubdiv2D .

CvGraph (view/add comments)

Oriented or unoriented weighted graph.
#define CV_GRAPH_VERTEX_FIELDS() \
int flags; /* vertex flags */ \
struct CvGraphEdge* first; /* the first incident edge */

typedef struct CvGraphVtx

{
CV_GRAPH_VERTEX_FIELDS()
}
CvGraphVtx;

#define CV_GRAPH_EDGE_FIELDS() \
int flags; /* edge flags */ \
1.3. DYNAMIC STRUCTURES 149

float weight; /* edge weight */ \

struct CvGraphEdge* next[2]; /* the next edges in the incidence lists for staring (0) *
/* and ending (1) vertices */ \
struct CvGraphVtx* vtx[2]; /* the starting (0) and ending (1) vertices */

typedef struct CvGraphEdge

{
CV_GRAPH_EDGE_FIELDS()
}
CvGraphEdge;

#define CV_GRAPH_FIELDS() \
CV_SET_FIELDS() /* set of vertices */ \
CvSet* edges; /* set of edges */

typedef struct CvGraph

{
CV_GRAPH_FIELDS()
}
CvGraph;

The structure CvGraph is a base for graphs used in OpenCV.

The graph structure inherits from CvSet - which describes common graph properties and the
graph vertices, and contains another set as a member - which describes the graph edges.
The vertex, edge, and the graph header structures are declared using the same technique as
other extendible OpenCV structures - via macros, which simplify extension and customization of
the structures. While the vertex and edge structures do not inherit from CvSetElem explicitly,
they satisfy both conditions of the set elements: having an integer field in the beginning and fitting
within the CvSetElem structure. The flags fields are used as for indicating occupied vertices and
edges as well as for other purposes, for example, for graph traversal (see cvCreateGraphScanner
et al.), so it is better not to use them directly.
The graph is represented as a set of edges each of which has a list of incident edges. The
incidence lists for different vertices are interleaved to avoid information duplication as much as
posssible.
The graph may be oriented or unoriented. In the latter case there is no distiction between the
edge connecting vertex A with vertex B and the edge connecting vertex B with vertex A - only
one of them can exist in the graph at the same moment and it represents both A → B and B → A
edges.

CvGraphScanner (view/add comments)

Graph traversal state.
150 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

typedef struct CvGraphScanner

{
CvGraphVtx* vtx; /* current graph vertex (or current edge origin) */
CvGraphVtx* dst; /* current graph edge destination vertex */
CvGraphEdge* edge; /* current edge */

CvGraph* graph; /* the graph */

CvSeq* stack; /* the graph vertex stack */
int index; /* the lower bound of certainly visited vertices */
int mask; /* event mask */
}
CvGraphScanner;

The structure CvGraphScanner is used for depth-first graph traversal. See discussion of the
functions below.

CV TREE NODE FIELDS (view/add comments)

Helper macro for a tree node type declaration.
The macro CV TREE NODE FIELDS() is used to declare structures that can be organized
into hierarchical strucutures (trees), such as CvSeq - the basic type for all dynamic structures.
The trees created with nodes declared using this macro can be processed using the functions
described below in this section.

CvTreeNodeIterator (view/add comments)

Opens existing or creates new file storage.
typedef struct CvTreeNodeIterator
{
const void* node;
int level;
int max_level;
}
CvTreeNodeIterator;

#define CV_TREE_NODE_FIELDS(node_type) \
int flags; /* micsellaneous flags */ \
int header_size; /* size of sequence header */ \
struct node_type* h_prev; /* previous sequence */ \
struct node_type* h_next; /* next sequence */ \
struct node_type* v_prev; /* 2nd previous sequence */ \
struct node_type* v_next; /* 2nd next sequence */
1.3. DYNAMIC STRUCTURES 151

The structure CvTreeNodeIterator is used to traverse trees. Each tree node should start with
the certain fields which are defined by CV TREE NODE FIELDS(...) macro. In C++ terms, each
tree node should be a structure ”derived” from
struct _BaseTreeNode
{
CV_TREE_NODE_FIELDS(_BaseTreeNode);
}

CvSeq, CvSet, CvGraph and other dynamic structures derived from CvSeq comply with the
requirement.

cvClearGraph (view/add comments)

Clears a graph.

void cvClearGraph( CvGraph* graph );

graph Graph

The function removes all vertices and edges from a graph. The function has O(1) time com-
plexity.

cvClearMemStorage (view/add comments)

Clears memory storage.

void cvClearMemStorage( CvMemStorage* storage );

storage Memory storage

The function resets the top (free space boundary) of the storage to the very beginning. This
function does not deallocate any memory. If the storage has a parent, the function returns all
blocks to the parent.
152 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

cvClearSeq (view/add comments)

Clears a sequence.

void cvClearSeq( CvSeq* seq );

seq Sequence

The function removes all elements from a sequence. The function does not return the mem-
ory to the storage block, but this memory is reused later when new elements are added to the
sequence. The function has ’O(1)’ time complexity.

cvClearSet (view/add comments)

Clears a set.

void cvClearSet( CvSet* setHeader );

setHeader Cleared set

The function removes all elements from set. It has O(1) time complexity.

cvCloneGraph (view/add comments)

Clones a graph.

CvGraph* cvCloneGraph(
const CvGraph* graph,
CvMemStorage* storage );

graph The graph to copy

1.3. DYNAMIC STRUCTURES 153

storage Container for the copy

The function creates a full copy of the specified graph. If the graph vertices or edges have
pointers to some external data, it can still be shared between the copies. The vertex and edge
indices in the new graph may be different from the original because the function defragments the
vertex and edge sets.

cvCloneSeq (view/add comments)

Creates a copy of a sequence.

CvSeq* cvCloneSeq(
const CvSeq* seq,
CvMemStorage* storage=NULL );

seq Sequence

storage The destination storage block to hold the new sequence header and the copied data, if
any. If it is NULL, the function uses the storage block containing the input sequence.

The function makes a complete copy of the input sequence and returns it.
The call
cvCloneSeq( seq, storage )
is equivalent to
cvSeqSlice( seq, CV_WHOLE_SEQ, storage, 1 )

cvCreateChildMemStorage (view/add comments)

Creates child memory storage.

CvMemStorage* cvCreateChildMemStorage(CvMemStorage* parent);

parent Parent memory storage

154 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

The function creates a child memory storage that is similar to simple memory storage except
for the differences in the memory allocation/deallocation mechanism. When a child storage needs
a new block to add to the block list, it tries to get this block from the parent. The first unoccupied
parent block available is taken and excluded from the parent block list. If no blocks are available,
the parent either allocates a block or borrows one from its own parent, if any. In other words, the
chain, or a more complex structure, of memory storages where every storage is a child/parent of
another is possible. When a child storage is released or even cleared, it returns all blocks to the
parent. In other aspects, child storage is the same as simple storage.

Child storage is useful in the following situation. Imagine that the user needs to process dy-
namic data residing in a given storage area and put the result back to that same storage area.
With the simplest approach, when temporary data is resided in the same storage area as the input
and output data, the storage area will look as follows after processing:

Dynamic data processing without using child storage

That is, garbage appears in the middle of the storage. However, if one creates a child memory
storage at the beginning of processing, writes temporary data there, and releases the child storage
at the end, no garbage will appear in the source/destination storage:

Dynamic data processing using a child storage

1.3. DYNAMIC STRUCTURES 155

cvCreateGraph (view/add comments)

Creates an empty graph.

CvGraph* cvCreateGraph(
int graph flags,
int header size,
int vtx size,
int edge size,
CvMemStorage* storage );

graph flags Type of the created graph. Usually, it is either CV SEQ KIND GRAPH for generic
unoriented graphs and CV SEQ KIND GRAPH | CV GRAPH FLAG ORIENTED for generic ori-
ented graphs.

header size Graph header size; may not be less than sizeof(CvGraph)

vtx size Graph vertex size; the custom vertex structure must start with CvGraphVtx (use
CV GRAPH VERTEX FIELDS())

edge size Graph edge size; the custom edge structure must start with CvGraphEdge (use
CV GRAPH EDGE FIELDS())

storage The graph container

The function creates an empty graph and returns a pointer to it.

cvCreateGraphScanner (view/add comments)

Creates structure for depth-first graph traversal.

CvGraphScanner* cvCreateGraphScanner(
CvGraph* graph,
CvGraphVtx* vtx=NULL,
int mask=CV GRAPH ALL ITEMS );
156 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

graph Graph

vtx Initial vertex to start from. If NULL, the traversal starts from the first vertex (a vertex with the
minimal index in the sequence of vertices).

mask Event mask indicating which events are of interest to the user (where cvNextGraphItem
function returns control to the user) It can be CV GRAPH ALL ITEMS (all events are of inter-
est) or a combination of the following flags:

CV GRAPH VERTEX stop at the graph vertices visited for the first time
CV GRAPH TREE EDGE stop at tree edges (tree edge is the edge connecting the last vis-
ited vertex and the vertex to be visited next)
CV GRAPH BACK EDGE stop at back edges (back edge is an edge connecting the last vis-
ited vertex with some of its ancestors in the search tree)
CV GRAPH FORWARD EDGE stop at forward edges (forward edge is an edge conecting the
last visited vertex with some of its descendants in the search tree. The forward edges
are only possible during oriented graph traversal)
CV GRAPH CROSS EDGE stop at cross edges (cross edge is an edge connecting different
search trees or branches of the same tree. The cross edges are only possible during
oriented graph traversal)
CV GRAPH ANY EDGE stop at any edge (tree, back, forward, and cross edges)
CV GRAPH NEW TREE stop in the beginning of every new search tree. When the traversal
procedure visits all vertices and edges reachable from the initial vertex (the visited
vertices together with tree edges make up a tree), it searches for some unvisited vertex
in the graph and resumes the traversal process from that vertex. Before starting a new
tree (including the very first tree when cvNextGraphItem is called for the first time)
it generates a CV GRAPH NEW TREE event. For unoriented graphs, each search tree
corresponds to a connected component of the graph.
CV GRAPH BACKTRACKING stop at every already visited vertex during backtracking - return-
ing to already visited vertexes of the traversal tree.

The function creates a structure for depth-first graph traversal/search. The initialized structure
is used in the cvNextGraphItem function - the incremental traversal procedure.

cvCreateMemStorage (view/add comments)

Creates memory storage.
1.3. DYNAMIC STRUCTURES 157

CvMemStorage* cvCreateMemStorage( int blockSize=0 );

blockSize Size of the storage blocks in bytes. If it is 0, the block size is set to a default value -
currently it is about 64K.

The function creates an empty memory storage. See CvMemStorage description.

cvCreateSeq (view/add comments)

Creates a sequence.

CvSeq* cvCreateSeq(
int seqFlags,
int headerSize,
int elemSize,
CvMemStorage* storage);

seqFlags Flags of the created sequence. If the sequence is not passed to any function work-
ing with a specific type of sequences, the sequence value may be set to 0, otherwise the
appropriate type must be selected from the list of predefined sequence types.

headerSize Size of the sequence header; must be greater than or equal to sizeof(CvSeq).
If a specific type or its extension is indicated, this type must fit the base type header.

elemSize Size of the sequence elements in bytes. The size must be consistent with the se-
quence type. For example, for a sequence of points to be created, the element type
CV SEQ ELTYPE POINT should be specified and the parameter elemSize must be equal to
sizeof(CvPoint).

storage Sequence location

The function creates a sequence and returns the pointer to it. The function allocates the se-
quence header in the storage block as one continuous chunk and sets the structure fields flags,
elemSize, headerSize, and storage to passed values, sets delta elems to the default value
(that may be reassigned using the cvSetSeqBlockSize function), and clears other header fields,
including the space following the first sizeof(CvSeq) bytes.
158 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

cvCreateSet (view/add comments)

Creates an empty set.

CvSet* cvCreateSet(
int set flags,
int header size,
int elem size,
CvMemStorage* storage );

set flags Type of the created set

header size Set header size; may not be less than sizeof(CvSet)
elem size Set element size; may not be less than CvSetElem
storage Container for the set
The function creates an empty set with a specified header size and element size, and returns
the pointer to the set. This function is just a thin layer on top of cvCreateSeq.

cvCvtSeqToArray (view/add comments)

Copies a sequence to one continuous block of memory.

void* cvCvtSeqToArray(
const CvSeq* seq,
void* elements,
CvSlice slice=CV WHOLE SEQ );

seq Sequence
elements Pointer to the destination array that must be large enough. It should be a pointer to
data, not a matrix header.
slice The sequence portion to copy to the array
The function copies the entire sequence or subsequence to the specified buffer and returns
the pointer to the buffer.
1.3. DYNAMIC STRUCTURES 159

cvEndWriteSeq (view/add comments)

Finishes the process of writing a sequence.

CvSeq* cvEndWriteSeq( CvSeqWriter* writer );

writer Writer state

The function finishes the writing process and returns the pointer to the written sequence. The
function also truncates the last incomplete sequence block to return the remaining part of the
block to memory storage. After that, the sequence can be read and modified safely. See cvcvS-
tartWriteSeq and cvcvStartAppendToSeq

cvFindGraphEdge (view/add comments)

Finds an edge in a graph.

CvGraphEdge* cvFindGraphEdge( const CvGraph* graph, int start idx, int

end idx );

#define cvGraphFindEdge cvFindGraphEdge

graph Graph

start idx Index of the starting vertex of the edge

end idx Index of the ending vertex of the edge. For an unoriented graph, the order of the vertex
parameters does not matter.

The function finds the graph edge connecting two specified vertices and returns a pointer to it
or NULL if the edge does not exist.
160 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

cvFindGraphEdgeByPtr (view/add comments)

Finds an edge in a graph by using its pointer.

CvGraphEdge* cvFindGraphEdgeByPtr(
const CvGraph* graph,
const CvGraphVtx* startVtx,
const CvGraphVtx* endVtx );

#define cvGraphFindEdgeByPtr cvFindGraphEdgeByPtr

graph Graph

startVtx Pointer to the starting vertex of the edge

endVtx Pointer to the ending vertex of the edge. For an unoriented graph, the order of the vertex
parameters does not matter.

The function finds the graph edge connecting two specified vertices and returns pointer to it or
NULL if the edge does not exists.

cvFlushSeqWriter (view/add comments)

Updates sequence headers from the writer.

void cvFlushSeqWriter( CvSeqWriter* writer );

writer Writer state

The function is intended to enable the user to read sequence elements, whenever required,
during the writing process, e.g., in order to check specific conditions. The function updates the
sequence headers to make reading from the sequence possible. The writer is not closed, however,
so that the writing process can be continued at any time. If an algorithm requires frequent flushes,
consider using cvSeqPush instead.
1.3. DYNAMIC STRUCTURES 161

cvGetGraphVtx (view/add comments)

Finds a graph vertex by using its index.

CvGraphVtx* cvGetGraphVtx(
CvGraph* graph,
int vtx idx );

graph Graph
vtx idx Index of the vertex
The function finds the graph vertex by using its index and returns the pointer to it or NULL if
the vertex does not belong to the graph.

cvGetSeqElem (view/add comments)

Returns a pointer to a sequence element according to its index.

char* cvGetSeqElem( const CvSeq* seq, int index );

#define CV_GET_SEQ_ELEM( TYPE, seq, index ) (TYPE*)cvGetSeqElem( (CvSeq*)(seq), (index) )

seq Sequence
index Index of element
The function finds the element with the given index in the sequence and returns the pointer to
it. If the element is not found, the function returns 0. The function supports negative indices, where
-1 stands for the last sequence element, -2 stands for the one before last, etc. If the sequence
is most likely to consist of a single sequence block or the desired element is likely to be located
in the first block, then the macro CV GET SEQ ELEM( elemType, seq, index ) should be
used, where the parameter elemType is the type of sequence elements ( CvPoint for example),
the parameter seq is a sequence, and the parameter index is the index of the desired element.
The macro checks first whether the desired element belongs to the first block of the sequence and
returns it if it does; otherwise the macro calls the main function GetSeqElem. Negative indices
always cause the cvGetSeqElem call. The function has O(1) time complexity assuming that the
number of blocks is much smaller than the number of elements.
162 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

cvGetSeqReaderPos (view/add comments)

Returns the current reader position.

int cvGetSeqReaderPos( CvSeqReader* reader );

reader Reader state

The function returns the current reader position (within 0 ... reader->seq->total - 1).

cvGetSetElem (view/add comments)

Finds a set element by its index.

CvSetElem* cvGetSetElem(
const CvSet* setHeader,
int index );

setHeader Set

index Index of the set element within a sequence

The function finds a set element by its index. The function returns the pointer to it or 0 if the
index is invalid or the corresponding node is free. The function supports negative indices as it
uses cvGetSeqElem to locate the node.

cvGraphAddEdge (view/add comments)

Adds an edge to a graph.

int cvGraphAddEdge(
CvGraph* graph,
int start idx,
1.3. DYNAMIC STRUCTURES 163

int end idx,

const CvGraphEdge* edge=NULL,
CvGraphEdge** inserted edge=NULL );

graph Graph
start idx Index of the starting vertex of the edge
end idx Index of the ending vertex of the edge. For an unoriented graph, the order of the vertex
parameters does not matter.
edge Optional input parameter, initialization data for the edge
inserted edge Optional output parameter to contain the address of the inserted edge

The function connects two specified vertices. The function returns 1 if the edge has been
added successfully, 0 if the edge connecting the two vertices exists already and -1 if either of the
vertices was not found, the starting and the ending vertex are the same, or there is some other
critical situation. In the latter case (i.e., when the result is negative), the function also reports an
error by default.

cvGraphAddEdgeByPtr (view/add comments)

Adds an edge to a graph by using its pointer.

int cvGraphAddEdgeByPtr(
CvGraph* graph,
CvGraphVtx* start vtx,
CvGraphVtx* end vtx,
const CvGraphEdge* edge=NULL,
CvGraphEdge** inserted edge=NULL );

graph Graph
start vtx Pointer to the starting vertex of the edge
end vtx Pointer to the ending vertex of the edge. For an unoriented graph, the order of the vertex
parameters does not matter.
164 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

edge Optional input parameter, initialization data for the edge

inserted edge Optional output parameter to contain the address of the inserted edge within
the edge set
The function connects two specified vertices. The function returns 1 if the edge has been
added successfully, 0 if the edge connecting the two vertices exists already, and -1 if either of the
vertices was not found, the starting and the ending vertex are the same or there is some other
critical situation. In the latter case (i.e., when the result is negative), the function also reports an
error by default.

cvGraphAddVtx (view/add comments)

Adds a vertex to a graph.

int cvGraphAddVtx(
CvGraph* graph,
const CvGraphVtx* vtx=NULL,
CvGraphVtx** inserted vtx=NULL );

graph Graph
vtx Optional input argument used to initialize the added vertex (only user-defined fields beyond
sizeof(CvGraphVtx) are copied)
inserted vertex Optional output argument. If not NULL, the address of the new vertex is
written here.
The function adds a vertex to the graph and returns the vertex index.

cvGraphEdgeIdx (view/add comments)

Returns the index of a graph edge.

int cvGraphEdgeIdx(
CvGraph* graph,
CvGraphEdge* edge );
1.3. DYNAMIC STRUCTURES 165

graph Graph

edge Pointer to the graph edge

The function returns the index of a graph edge.

cvGraphRemoveEdge (view/add comments)

Removes an edge from a graph.

void cvGraphRemoveEdge(
CvGraph* graph,
int start idx,
int end idx );

graph Graph

start idx Index of the starting vertex of the edge

end idx Index of the ending vertex of the edge. For an unoriented graph, the order of the vertex
parameters does not matter.

The function removes the edge connecting two specified vertices. If the vertices are not con-
nected [in that order], the function does nothing.

cvGraphRemoveEdgeByPtr (view/add comments)

Removes an edge from a graph by using its pointer.

void cvGraphRemoveEdgeByPtr(
CvGraph* graph,
CvGraphVtx* start vtx,
CvGraphVtx* end vtx );

graph Graph
166 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

start vtx Pointer to the starting vertex of the edge

end vtx Pointer to the ending vertex of the edge. For an unoriented graph, the order of the vertex
parameters does not matter.

The function removes the edge connecting two specified vertices. If the vertices are not con-
nected [in that order], the function does nothing.

cvGraphRemoveVtx (view/add comments)

Removes a vertex from a graph.

int cvGraphRemoveVtx(
CvGraph* graph,
int index );

graph Graph

vtx idx Index of the removed vertex

The function removes a vertex from a graph together with all the edges incident to it. The
function reports an error if the input vertex does not belong to the graph. The return value is the
number of edges deleted, or -1 if the vertex does not belong to the graph.

cvGraphRemoveVtxByPtr (view/add comments)

Removes a vertex from a graph by using its pointer.

int cvGraphRemoveVtxByPtr(
CvGraph* graph,
CvGraphVtx* vtx );

graph Graph

vtx Pointer to the removed vertex

1.3. DYNAMIC STRUCTURES 167

The function removes a vertex from the graph by using its pointer together with all the edges
incident to it. The function reports an error if the vertex does not belong to the graph. The return
value is the number of edges deleted, or -1 if the vertex does not belong to the graph.

cvGraphVtxDegree (view/add comments)

Counts the number of edges indicent to the vertex.

int cvGraphVtxDegree( const CvGraph* graph, int vtxIdx );

graph Graph

vtxIdx Index of the graph vertex

The function returns the number of edges incident to the specified vertex, both incoming and
outgoing. To count the edges, the following code is used:
CvGraphEdge* edge = vertex->first; int count = 0;
while( edge )
{
edge = CV_NEXT_GRAPH_EDGE( edge, vertex );
count++;
}
The macro CV NEXT GRAPH EDGE( edge, vertex ) returns the edge incident to vertex
that follows after edge.

cvGraphVtxDegreeByPtr (view/add comments)

Finds an edge in a graph.

int cvGraphVtxDegreeByPtr(
const CvGraph* graph,
const CvGraphVtx* vtx );

graph Graph
168 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

vtx Pointer to the graph vertex

The function returns the number of edges incident to the specified vertex, both incoming and
outcoming.

cvGraphVtxIdx (view/add comments)

Returns the index of a graph vertex.

int cvGraphVtxIdx(
CvGraph* graph,
CvGraphVtx* vtx );

graph Graph
vtx Pointer to the graph vertex
The function returns the index of a graph vertex.

cvInitTreeNodeIterator (view/add comments)

Initializes the tree node iterator.

void cvInitTreeNodeIterator(
CvTreeNodeIterator* tree iterator,
const void* first,
int max level );

tree iterator Tree iterator initialized by the function

first The initial node to start traversing from
max level The maximal level of the tree (first node assumed to be at the first level) to traverse
up to. For example, 1 means that only nodes at the same level as first should be visited, 2
means that the nodes on the same level as first and their direct children should be visited,
and so forth.
The function initializes the tree iterator. The tree is traversed in depth-first order.
1.3. DYNAMIC STRUCTURES 169

cvInsertNodeIntoTree (view/add comments)

Adds a new node to a tree.

void cvInsertNodeIntoTree(
void* node,
void* parent,
void* frame );

node The inserted node

parent The parent node that is already in the tree

frame The top level node. If parent and frame are the same, the v prev field of node is set
to NULL rather than parent.

The function adds another node into tree. The function does not allocate any memory, it can
only modify links of the tree nodes.

cvMakeSeqHeaderForArray (view/add comments)

Constructs a sequence header for an array.

CvSeq* cvMakeSeqHeaderForArray(
int seq type,
int header size,
int elem size,
void* elements,
int total,
CvSeq* seq,
CvSeqBlock* block );

seq type Type of the created sequence

header size Size of the header of the sequence. Parameter sequence must point to the struc-
ture of that size or greater
170 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

elem size Size of the sequence elements

elements Elements that will form a sequence

total Total number of elements in the sequence. The number of array elements must be equal
to the value of this parameter.

seq Pointer to the local variable that is used as the sequence header

block Pointer to the local variable that is the header of the single sequence block

The function initializes a sequence header for an array. The sequence header as well as the
sequence block are allocated by the user (for example, on stack). No data is copied by the function.
The resultant sequence will consists of a single block and have NULL storage pointer; thus, it is
possible to read its elements, but the attempts to add elements to the sequence will raise an error
in most cases.

cvMemStorageAlloc (view/add comments)

Allocates a memory buffer in a storage block.

void* cvMemStorageAlloc(
CvMemStorage* storage,
size t size );

storage Memory storage

size Buffer size

The function allocates a memory buffer in a storage block. The buffer size must not exceed
the storage block size, otherwise a runtime error is raised. The buffer address is aligned by
CV STRUCT ALIGN=sizeof(double) (for the moment) bytes.

cvMemStorageAllocString (view/add comments)

Allocates a text string in a storage block.
1.3. DYNAMIC STRUCTURES 171

CvString cvMemStorageAllocString(CvMemStorage* storage, const char*

ptr, int len=-1);

typedef struct CvString

{
int len;
char* ptr;
}
CvString;

storage Memory storage

ptr The string

len Length of the string (not counting the ending NUL) . If the parameter is negative, the function
computes the length.

The function creates copy of the string in memory storage. It returns the structure that contains
user-passed or computed length of the string and pointer to the copied string.

cvNextGraphItem (view/add comments)

Executes one or more steps of the graph traversal procedure.

int cvNextGraphItem( CvGraphScanner* scanner );

scanner Graph traversal state. It is updated by this function.

The function traverses through the graph until an event of interest to the user (that is, an event,
specified in the mask in the cvCreateGraphScanner call) is met or the traversal is completed. In
the first case, it returns one of the events listed in the description of the mask parameter above
and with the next call it resumes the traversal. In the latter case, it returns CV GRAPH OVER (-1).
When the event is CV GRAPH VERTEX, CV GRAPH BACKTRACKING, or CV GRAPH NEW TREE, the
currently observed vertex is stored in scanner->vtx. And if the event is edge-related, the edge
itself is stored at scanner->edge, the previously visited vertex - at scanner->vtx and the
other ending vertex of the edge - at scanner->dst.
172 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

cvNextTreeNode (view/add comments)

Returns the currently observed node and moves the iterator toward the next node.

void* cvNextTreeNode( CvTreeNodeIterator* tree iterator );

tree iterator Tree iterator initialized by the function

The function returns the currently observed node and then updates the iterator - moving it
toward the next node. In other words, the function behavior is similar to the *p++ expression on a
typical C pointer or C++ collection iterator. The function returns NULL if there are no more nodes.

cvPrevTreeNode (view/add comments)

Returns the currently observed node and moves the iterator toward the previous node.

void* cvPrevTreeNode( CvTreeNodeIterator* tree iterator );

tree iterator Tree iterator initialized by the function

The function returns the currently observed node and then updates the iterator - moving it
toward the previous node. In other words, the function behavior is similar to the *p-- expression
on a typical C pointer or C++ collection iterator. The function returns NULL if there are no more
nodes.

cvReleaseGraphScanner (view/add comments)

Completes the graph traversal procedure.

void cvReleaseGraphScanner( CvGraphScanner** scanner );

scanner Double pointer to graph traverser

The function completes the graph traversal procedure and releases the traverser state.
1.3. DYNAMIC STRUCTURES 173

cvReleaseMemStorage (view/add comments)

Releases memory storage.

void cvReleaseMemStorage( CvMemStorage** storage );

storage Pointer to the released storage

The function deallocates all storage memory blocks or returns them to the parent, if any. Then
it deallocates the storage header and clears the pointer to the storage. All child storage associated
with a given parent storage block must be released before the parent storage block is released.

cvRestoreMemStoragePos (view/add comments)

Restores memory storage position.

void cvRestoreMemStoragePos(
CvMemStorage* storage,
CvMemStoragePos* pos);

storage Memory storage

pos New storage top position

The function restores the position of the storage top from the parameter pos. This function and
the function cvClearMemStorage are the only methods to release memory occupied in memory
blocks. Note again that there is no way to free memory in the middle of an occupied portion of a
storage block.

cvSaveMemStoragePos (view/add comments)

Saves memory storage position.
174 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

void cvSaveMemStoragePos(
const CvMemStorage* storage,
CvMemStoragePos* pos);

storage Memory storage

pos The output position of the storage top

The function saves the current position of the storage top to the parameter pos. The function
cvRestoreMemStoragePos can further retrieve this position.

cvSeqElemIdx (view/add comments)

Returns the index of a specific sequence element.

int cvSeqElemIdx(
const CvSeq* seq,
const void* element,
CvSeqBlock** block=NULL );

seq Sequence

element Pointer to the element within the sequence

block Optional argument. If the pointer is not NULL, the address of the sequence block that
contains the element is stored in this location.

The function returns the index of a sequence element or a negative number if the element is
not found.

cvSeqInsert (view/add comments)

Inserts an element in the middle of a sequence.
1.3. DYNAMIC STRUCTURES 175

char* cvSeqInsert(
CvSeq* seq,
int beforeIndex,
void* element=NULL );

seq Sequence

beforeIndex Index before which the element is inserted. Inserting before 0 (the minimal allowed
value of the parameter) is equal to cvSeqPushFront and inserting before seq->total (the
maximal allowed value of the parameter) is equal to cvSeqPush.

element Inserted element

The function shifts the sequence elements from the inserted position to the nearest end of the
sequence and copies the element content there if the pointer is not NULL. The function returns
a pointer to the inserted element.

cvSeqInsertSlice (view/add comments)

Inserts an array in the middle of a sequence.

void cvSeqInsertSlice(
CvSeq* seq,
int beforeIndex,
const CvArr* fromArr );

seq Sequence

slice The part of the sequence to remove

fromArr The array to take elements from

The function inserts all fromArr array elements at the specified position of the sequence. The
array fromArr can be a matrix or another sequence.
176 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

cvSeqInvert (view/add comments)

Reverses the order of sequence elements.

void cvSeqInvert( CvSeq* seq );

seq Sequence

The function reverses the sequence in-place - makes the first element go last, the last element
go first and so forth.

cvSeqPop (view/add comments)

Removes an element from the end of a sequence.

void cvSeqPop(
CvSeq* seq,
void* element=NULL );

seq Sequence

element Optional parameter . If the pointer is not zero, the function copies the removed element
to this location.

The function removes an element from a sequence. The function reports an error if the se-
quence is already empty. The function has O(1) complexity.

cvSeqPopFront (view/add comments)

Removes an element from the beginning of a sequence.
1.3. DYNAMIC STRUCTURES 177

void cvSeqPopFront(

CvSeq* seq,

void* element=NULL );

seq Sequence
element Optional parameter. If the pointer is not zero, the function copies the removed element
to this location.

The function removes an element from the beginning of a sequence. The function reports an
error if the sequence is already empty. The function has O(1) complexity.

cvSeqPopMulti (view/add comments)

Removes several elements from either end of a sequence.

void cvSeqPopMulti(
CvSeq* seq,
void* elements,
int count,
int in front=0 );

seq Sequence
elements Removed elements
count Number of elements to pop
in front The flags specifying which end of the modified sequence.
CV BACK the elements are added to the end of the sequence
CV FRONT the elements are added to the beginning of the sequence

The function removes several elements from either end of the sequence. If the number of
the elements to be removed exceeds the total number of elements in the sequence, the function
removes as many elements as possible.
178 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

cvSeqPush (view/add comments)

Adds an element to the end of a sequence.

char* cvSeqPush(
CvSeq* seq,
void* element=NULL );

seq Sequence

element Added element

The function adds an element to the end of a sequence and returns a pointer to the allo-
cated element. If the input element is NULL, the function simply allocates a space for one more
element.
The following code demonstrates how to create a new sequence using this function:
CvMemStorage* storage = cvCreateMemStorage(0);
CvSeq* seq = cvCreateSeq( CV_32SC1, /* sequence of integer elements */
sizeof(CvSeq), /* header size - no extra fields */
sizeof(int), /* element size */
storage /* the container storage */ );
int i;
for( i = 0; i < 100; i++ )
{
int* added = (int*)cvSeqPush( seq, &i );
printf( "%d is added\n", *added );
}

...
/* release memory storage in the end */
cvReleaseMemStorage( &storage );

The function has O(1) complexity, but there is a faster method for writing large sequences (see
cvStartWriteSeq and related functions).

cvSeqPushFront (view/add comments)

Adds an element to the beginning of a sequence.
1.3. DYNAMIC STRUCTURES 179

char* cvSeqPushFront( CvSeq* seq, void* element=NULL );

seq Sequence

element Added element

The function is similar to cvSeqPush but it adds the new element to the beginning of the
sequence. The function has O(1) complexity.

cvSeqPushMulti (view/add comments)

Pushes several elements to either end of a sequence.

void cvSeqPushMulti(
CvSeq* seq,
void* elements,
int count,
int in front=0 );

seq Sequence

elements Added elements

count Number of elements to push

in front The flags specifying which end of the modified sequence.

CV BACK the elements are added to the end of the sequence

CV FRONT the elements are added to the beginning of the sequence

The function adds several elements to either end of a sequence. The elements are added
to the sequence in the same order as they are arranged in the input array but they can fall into
different sequence blocks.
180 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

cvSeqRemove (view/add comments)

Removes an element from the middle of a sequence.

void cvSeqRemove(
CvSeq* seq,
int index );

seq Sequence

index Index of removed element

The function removes elements with the given index. If the index is out of range the function
reports an error. An attempt to remove an element from an empty sequence is a special case of
this situation. The function removes an element by shifting the sequence elements between the
nearest end of the sequence and the index-th position, not counting the latter.

cvSeqRemoveSlice (view/add comments)

Removes a sequence slice.

void cvSeqRemoveSlice( CvSeq* seq, CvSlice slice );

seq Sequence

slice The part of the sequence to remove

The function removes a slice from the sequence.

cvSeqSearch (view/add comments)

Searches for an element in a sequence.
1.3. DYNAMIC STRUCTURES 181

char* cvSeqSearch( CvSeq* seq, const void* elem, CvCmpFunc func, int
is sorted, int* elem idx, void* userdata=NULL );

seq The sequence

elem The element to look for

func The comparison function that returns negative, zero or positive value depending on the
relationships among the elements (see also cvSeqSort)

is sorted Whether the sequence is sorted or not

elem idx Output parameter; index of the found element

userdata The user parameter passed to the compasion function; helps to avoid global variables
in some cases

/* a < b ? -1 : a > b ? 1 : 0 */
typedef int (CV_CDECL* CvCmpFunc)(const void* a, const void* b, void* userdata);
The function searches for the element in the sequence. If the sequence is sorted, a binary
O(log(N)) search is used; otherwise, a simple linear search is used. If the element is not found,
the function returns a NULL pointer and the index is set to the number of sequence elements if a
linear search is used, or to the smallest index i, seq(i)>elem.

cvSeqSlice (view/add comments)

Makes a separate header for a sequence slice.

CvSeq* cvSeqSlice(
const CvSeq* seq,
CvSlice slice,
CvMemStorage* storage=NULL,
int copy data=0 );

seq Sequence
182 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

slice The part of the sequence to be extracted

storage The destination storage block to hold the new sequence header and the copied data, if
any. If it is NULL, the function uses the storage block containing the input sequence.

copy data The flag that indicates whether to copy the elements of the extracted slice (copy data!=0)
or not (copy data=0)

The function creates a sequence that represents the specified slice of the input sequence. The
new sequence either shares the elements with the original sequence or has its own copy of the
elements. So if one needs to process a part of sequence but the processing function does not
have a slice parameter, the required sub-sequence may be extracted using this function.

cvSeqSort (view/add comments)

Sorts sequence element using the specified comparison function.

void cvSeqSort( CvSeq* seq, CvCmpFunc func, void* userdata=NULL );

/* a < b ? -1 : a > b ? 1 : 0 */
typedef int (CV_CDECL* CvCmpFunc)(const void* a, const void* b, void* userdata);

seq The sequence to sort

func The comparison function that returns a negative, zero, or positive value depending on the
relationships among the elements (see the above declaration and the example below) - a
similar function is used by qsort from C runline except that in the latter, userdata is not
used

userdata The user parameter passed to the compasion function; helps to avoid global variables
in some cases

The function sorts the sequence in-place using the specified criteria. Below is an example of
using this function:
/* Sort 2d points in top-to-bottom left-to-right order */
static int cmp_func( const void* _a, const void* _b, void* userdata )
{
CvPoint* a = (CvPoint*)_a;
1.3. DYNAMIC STRUCTURES 183

CvPoint* b = (CvPoint*)_b;
int y_diff = a->y - b->y;
int x_diff = a->x - b->x;
return y_diff ? y_diff : x_diff;
}

...

CvMemStorage* storage = cvCreateMemStorage(0);

CvSeq* seq = cvCreateSeq( CV_32SC2, sizeof(CvSeq), sizeof(CvPoint), storage );
int i;

for( i = 0; i < 10; i++ )

{
CvPoint pt;
pt.x = rand() % 1000;
pt.y = rand() % 1000;
cvSeqPush( seq, &pt );
}

cvSeqSort( seq, cmp_func, 0 /* userdata is not used here */ );

/* print out the sorted sequence */

for( i = 0; i < seq->total; i++ )
{
CvPoint* pt = (CvPoint*)cvSeqElem( seq, i );
printf( "(%d,%d)\n", pt->x, pt->y );
}

cvReleaseMemStorage( &storage );

cvSetAdd (view/add comments)

Occupies a node in the set.

int cvSetAdd(
CvSet* setHeader,
CvSetElem* elem=NULL,
CvSetElem** inserted elem=NULL );
184 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

setHeader Set
elem Optional input argument, an inserted element. If not NULL, the function copies the data to
the allocated node (the MSB of the first integer field is cleared after copying).
inserted elem Optional output argument; the pointer to the allocated cell
The function allocates a new node, optionally copies input element data to it, and returns the
pointer and the index to the node. The index value is taken from the lower bits of the flags field
of the node. The function has O(1) complexity; however, there exists a faster function for allocating
set nodes (see cvSetNew).

cvSetNew (view/add comments)

Adds an element to a set (fast variant).

CvSetElem* cvSetNew( CvSet* setHeader );

setHeader Set
The function is an inline lightweight variant of cvSetAdd. It occupies a new node and returns
a pointer to it rather than an index.

cvSetRemove (view/add comments)

Removes an element from a set.

void cvSetRemove(
CvSet* setHeader,
int index );

setHeader Set
index Index of the removed element
The function removes an element with a specified index from the set. If the node at the spec-
ified location is not occupied, the function does nothing. The function has O(1) complexity; how-
ever, cvSetRemoveByPtr provides a quicker way to remove a set element if it is located already.
1.3. DYNAMIC STRUCTURES 185

cvSetRemoveByPtr (view/add comments)

Removes a set element based on its pointer.

void cvSetRemoveByPtr(
CvSet* setHeader,
void* elem );

setHeader Set

elem Removed element

The function is an inline lightweight variant of cvSetRemove that requires an element pointer.
The function does not check whether the node is occupied or not - the user should take care of
that.

cvSetSeqBlockSize (view/add comments)

Sets up sequence block size.

void cvSetSeqBlockSize(
CvSeq* seq,
int deltaElems );

seq Sequence

deltaElems Desirable sequence block size for elements

The function affects memory allocation granularity. When the free space in the sequence
buffers has run out, the function allocates the space for deltaElems sequence elements. If this
block immediately follows the one previously allocated, the two blocks are concatenated; other-
wise, a new sequence block is created. Therefore, the bigger the parameter is, the lower the
possible sequence fragmentation, but the more space in the storage block is wasted. When the
sequence is created, the parameter deltaElems is set to the default value of about 1K. The
function can be called any time after the sequence is created and affects future allocations. The
function can modify the passed value of the parameter to meet memory storage constraints.
186 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

cvSetSeqReaderPos (view/add comments)

Moves the reader to the specified position.

void cvSetSeqReaderPos(
CvSeqReader* reader,
int index,
int is relative=0 );

reader Reader state

index The destination position. If the positioning mode is used (see the next parameter), the
actual position will be index mod reader->seq->total.

is relative If it is not zero, then index is a relative to the current position

The function moves the read position to an absolute position or relative to the current position.

cvStartAppendToSeq (view/add comments)

Initializes the process of writing data to a sequence.

void cvStartAppendToSeq(
CvSeq* seq,
CvSeqWriter* writer );

seq Pointer to the sequence

writer Writer state; initialized by the function

The function initializes the process of writing data to a sequence. Written elements are added
to the end of the sequence by using the CV WRITE SEQ ELEM( written elem, writer )
macro. Note that during the writing process, other operations on the sequence may yield an
incorrect result or even corrupt the sequence (see description of cvFlushSeqWriter, which helps
to avoid some of these problems).
1.3. DYNAMIC STRUCTURES 187

cvStartReadSeq (view/add comments)

Initializes the process of sequential reading from a sequence.

void cvStartReadSeq(
const CvSeq* seq,
CvSeqReader* reader,
int reverse=0 );

seq Sequence

reader Reader state; initialized by the function

reverse Determines the direction of the sequence traversal. If reverse is 0, the reader is
positioned at the first sequence element; otherwise it is positioned at the last element.

The function initializes the reader state. After that, all the sequence elements from the first
one down to the last one can be read by subsequent calls of the macro CV READ SEQ ELEM(
read elem, reader ) in the case of forward reading and by using CV REV READ SEQ ELEM(
read elem, reader ) in the case of reverse reading. Both macros put the sequence element
to read elem and move the reading pointer toward the next element. A circular structure of
sequence blocks is used for the reading process, that is, after the last element has been read
by the macro CV READ SEQ ELEM, the first element is read when the macro is called again. The
same applies to CV REV READ SEQ ELEM. There is no function to finish the reading process, since
it neither changes the sequence nor creates any temporary buffers. The reader field ptr points to
the current element of the sequence that is to be read next. The code below demonstrates how to
use the sequence writer and reader.
CvMemStorage* storage = cvCreateMemStorage(0);
CvSeq* seq = cvCreateSeq( CV_32SC1, sizeof(CvSeq), sizeof(int), storage );
CvSeqWriter writer;
CvSeqReader reader;
int i;

cvStartAppendToSeq( seq, &writer );

for( i = 0; i < 10; i++ )
{
int val = rand()%100;
CV_WRITE_SEQ_ELEM( val, writer );
printf("%d is written\n", val );
188 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

}
cvEndWriteSeq( &writer );

cvStartReadSeq( seq, &reader, 0 );

for( i = 0; i < seq->total; i++ )
{
int val;
#if 1
CV_READ_SEQ_ELEM( val, reader );
printf("%d is read\n", val );
#else /* alternative way, that is prefferable if sequence elements are large,
or their size/type is unknown at compile time */
printf("%d is read\n", *(int*)[Link] );
CV_NEXT_SEQ_ELEM( seq->elem_size, reader );
#endif
}
...

cvReleaseStorage( &storage );

cvStartWriteSeq (view/add comments)

Creates a new sequence and initializes a writer for it.

void cvStartWriteSeq(
int seq flags,
int header size,
int elem size,
CvMemStorage* storage,
CvSeqWriter* writer );

seq flags Flags of the created sequence. If the sequence is not passed to any function working
with a specific type of sequences, the sequence value may be equal to 0; otherwise the
appropriate type must be selected from the list of predefined sequence types.

header size Size of the sequence header. The parameter value may not be less than sizeof(CvSeq).
If a certain type or extension is specified, it must fit within the base type header.
1.4. DRAWING FUNCTIONS 189

elem size Size of the sequence elements in bytes; must be consistent with the sequence type.
For example, if a sequence of points is created (element type CV SEQ ELTYPE POINT ),
then the parameter elem size must be equal to sizeof(CvPoint).

storage Sequence location

writer Writer state; initialized by the function

The function is a combination of cvCreateSeq and cvStartAppendToSeq. The pointer to the

created sequence is stored at writer->seq and is also returned by the cvEndWriteSeq function
that should be called at the end.

cvTreeToNodeSeq (view/add comments)

Gathers all node pointers to a single sequence.

CvSeq* cvTreeToNodeSeq(
const void* first,
int header size,
CvMemStorage* storage );

first The initial tree node

header size Header size of the created sequence (sizeof(CvSeq) is the most frequently used
value)

storage Container for the sequence

The function puts pointers of all nodes reacheable from first into a single sequence. The
pointers are written sequentially in the depth-first order.

1.4 Drawing Functions

Drawing functions work with matrices/images of arbitrary depth. The boundaries of the shapes
can be rendered with antialiasing (implemented only for 8-bit images for now). All the functions
include the parameter color that uses a rgb value (that may be constructed with CV RGB macro
or the cv function ) for color images and brightness for grayscale images. For color images the
190 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

order channel is normally Blue, Green, Red, this is what cv, cv and cv expect , so if you form a
color using cv, it should look like:

cvScalar(blue component, green component, red component[, alpha component])

If you are using your own image rendering and I/O functions, you can use any channel ordering,
the drawing functions process each channel independently and do not depend on the channel
order or even on the color space used. The whole image can be converted from BGR to RGB or
to a different color space using cv.
If a drawn figure is partially or completely outside the image, the drawing functions clip it.
Also, many drawing functions can handle pixel coordinates specified with sub-pixel accuracy, that
is, the coordinates can be passed as fixed-point numbers, encoded as integers. The number of
fractional bits is specified by the shift parameter and the real point coordinates are calculated as
Point(x, y) → Point2f(x∗2−shif t , y∗2−shif t ). This feature is especially effective wehn rendering
antialiased shapes.
Also, note that the functions do not support alpha-transparency - when the target image is
4-channnel, then the color[3] is simply copied to the repainted pixels. Thus, if you want to paint
semi-transparent shapes, you can paint them in a separate buffer and then blend it with the main
image.

cvCircle (view/add comments)

Draws a circle.

void cvCircle(
CvArr* img,
CvPoint center,
int radius,
CvScalar color,
int thickness=1,
int lineType=8,
int shift=0 );

img Image where the circle is drawn

center Center of the circle

radius Radius of the circle

1.4. DRAWING FUNCTIONS 191

color Circle color

thickness Thickness of the circle outline if positive, otherwise this indicates that a filled circle is
to be drawn

lineType Type of the circle boundary, see Line description

shift Number of fractional bits in the center coordinates and radius value

The function draws a simple or filled circle with a given center and radius.

cvClipLine (view/add comments)

Clips the line against the image rectangle.

int cvClipLine(
CvSize imgSize,
CvPoint* pt1,
CvPoint* pt2 );

imgSize Size of the image

pt1 First ending point of the line segment. It is modified by the function.

pt2 Second ending point of the line segment. It is modified by the function.

The function calculates a part of the line segment which is entirely within the image. It returns
0 if the line segment is completely outside the image and 1 otherwise.

cvDrawContours (view/add comments)

Draws contour outlines or interiors in an image.

void cvDrawContours(
CvArr *img,
CvSeq* contour,
CvScalar external color,
192 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

CvScalar hole color,

int max level,
int thickness=1,
int lineType=8 );

img Image where the contours are to be drawn. As with any other drawing function, the contours
are clipped with the ROI.

contour Pointer to the first contour

external color Color of the external contours

hole color Color of internal contours (holes)

max level Maximal level for drawn contours. If 0, only contour is drawn. If 1, the contour
and all contours following it on the same level are drawn. If 2, all contours following and all
contours one level below the contours are drawn, and so forth. If the value is negative, the
function does not draw the contours following after contour but draws the child contours of
contour up to the |max level| − 1 level.

thickness Thickness of lines the contours are drawn with. If it is negative (For example, =CV FILLED),
the contour interiors are drawn.

lineType Type of the contour segments, see Line description

The function draws contour outlines in the image if thickness ≥ 0 or fills the area bounded
by the contours if thickness < 0.
Example: Connected component detection via contour functions
#include "cv.h"
#include "highgui.h"

int main( int argc, char** argv )

{
IplImage* src;
// the first command line parameter must be file name of binary
// (black-n-white) image
if( argc == 2 && (src=cvLoadImage(argv[1], 0))!= 0)
{
IplImage* dst = cvCreateImage( cvGetSize(src), 8, 3 );
CvMemStorage* storage = cvCreateMemStorage(0);
CvSeq* contour = 0;
1.4. DRAWING FUNCTIONS 193

cvThreshold( src, src, 1, 255, CV_THRESH_BINARY );

cvNamedWindow( "Source", 1 );
cvShowImage( "Source", src );

cvFindContours( src, storage, &contour, sizeof(CvContour),

CV_RETR_CCOMP, CV_CHAIN_APPROX_SIMPLE );
cvZero( dst );

for( ; contour != 0; contour = contour->h_next )

{
CvScalar color = CV_RGB( rand()&255, rand()&255, rand()&255 );
/* replace CV_FILLED with 1 to see the outlines */
cvDrawContours( dst, contour, color, color, -1, CV_FILLED, 8 );
}

cvNamedWindow( "Components", 1 );
cvShowImage( "Components", dst );
cvWaitKey(0);
}
}

cvEllipse (view/add comments)

Draws a simple or thick elliptic arc or an fills ellipse sector.

void cvEllipse(
CvArr* img,
CvPoint center,
CvSize axes,
double angle,
double start angle,
double end angle,
CvScalar color,
int thickness=1,
int lineType=8,
int shift=0 );

img The image

194 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

center Center of the ellipse

axes Length of the ellipse axes

angle Rotation angle

start angle Starting angle of the elliptic arc

end angle Ending angle of the elliptic arc.

color Ellipse color

thickness Thickness of the ellipse arc outline if positive, otherwise this indicates that a filled
ellipse sector is to be drawn

lineType Type of the ellipse boundary, see Line description

shift Number of fractional bits in the center coordinates and axes’ values

The function draws a simple or thick elliptic arc or fills an ellipse sector. The arc is clipped by
the ROI rectangle. A piecewise-linear approximation is used for antialiased arcs and thick arcs.
All the angles are given in degrees. The picture below explains the meaning of the parameters.
Parameters of Elliptic Arc

cvEllipseBox (view/add comments)

Draws a simple or thick elliptic arc or fills an ellipse sector.
1.4. DRAWING FUNCTIONS 195

void cvEllipseBox(
CvArr* img,
CvBox2D box,
CvScalar color,
int thickness=1,
int lineType=8,
int shift=0 );

img Image

box The enclosing box of the ellipse drawn

thickness Thickness of the ellipse boundary

lineType Type of the ellipse boundary, see Line description

shift Number of fractional bits in the box vertex coordinates

The function draws a simple or thick ellipse outline, or fills an ellipse. The functions provides
a convenient way to draw an ellipse approximating some shape; that is what CamShift and
FitEllipse do. The ellipse drawn is clipped by ROI rectangle. A piecewise-linear approximation is
used for antialiased arcs and thick arcs.

cvFillConvexPoly (view/add comments)

Fills a convex polygon.

void cvFillConvexPoly(
CvArr* img,
CvPoint* pts,
int npts,
CvScalar color,
int lineType=8,
int shift=0 );

img Image
196 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

pts Array of pointers to a single polygon

npts Polygon vertex counter
color Polygon color
lineType Type of the polygon boundaries, see Line description
shift Number of fractional bits in the vertex coordinates
The function fills a convex polygon’s interior. This function is much faster than the function
cvFillPoly and can fill not only convex polygons but any monotonic polygon, i.e., a polygon
whose contour intersects every horizontal line (scan line) twice at the most.

cvFillPoly (view/add comments)

Fills a polygon’s interior.

void cvFillPoly(
CvArr* img,
CvPoint** pts,
int* npts,
int contours,
CvScalar color,
int lineType=8,
int shift=0 );

img Image
pts Array of pointers to polygons
npts Array of polygon vertex counters
contours Number of contours that bind the filled region
color Polygon color
lineType Type of the polygon boundaries, see Line description
shift Number of fractional bits in the vertex coordinates
The function fills an area bounded by several polygonal contours. The function fills complex
areas, for example, areas with holes, contour self-intersection, and so forth.
1.4. DRAWING FUNCTIONS 197

cvGetTextSize (view/add comments)

Retrieves the width and height of a text string.

void cvGetTextSize(
const char* textString,
const CvFont* font,
CvSize* textSize,
int* baseline );

font Pointer to the font structure

textString Input string

textSize Resultant size of the text string. Height of the text does not include the height of
character parts that are below the baseline.

baseline y-coordinate of the baseline relative to the bottom-most text point

The function calculates the dimensions of a rectangle to enclose a text string when a specified
font is used.

cvInitFont (view/add comments)

Initializes font structure.

void cvInitFont(
CvFont* font,
int fontFace,
double hscale,
double vscale,
double shear=0,
int thickness=1,
int lineType=8 );

font Pointer to the font structure initialized by the function

198 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

fontFace Font name identifier. Only a subset of Hershey fonts [Link]

utils/misc/[Link] are supported now:

CV FONT HERSHEY SIMPLEX normal size sans-serif font

CV FONT HERSHEY PLAIN small size sans-serif font
CV FONT HERSHEY DUPLEX normal size sans-serif font (more complex than
CV FONT HERSHEY SIMPLEX)
CV FONT HERSHEY COMPLEX normal size serif font
CV FONT HERSHEY TRIPLEX normal size serif font (more complex than CV FONT HERSHEY COMPLEX)
CV FONT HERSHEY COMPLEX SMALL smaller version of CV FONT HERSHEY COMPLEX
CV FONT HERSHEY SCRIPT SIMPLEX hand-writing style font
CV FONT HERSHEY SCRIPT COMPLEX more complex variant of CV FONT HERSHEY SCRIPT SIMPLEX

The parameter can be composited from one of the values above and an optional CV FONT ITALIC
flag, which indicates italic or oblique font.

hscale Horizontal scale. If equal to 1.0f, the characters have the original width depending on
the font type. If equal to 0.5f, the characters are of half the original width.

vscale Vertical scale. If equal to 1.0f, the characters have the original height depending on the
font type. If equal to 0.5f, the characters are of half the original height.

shear Approximate tangent of the character slope relative to the vertical line. A zero value means
a non-italic font, 1.0f means about a 45 degree slope, etc.

thickness Thickness of the text strokes

lineType Type of the strokes, see Line description

The function initializes the font structure that can be passed to text rendering functions.

cvInitLineIterator (view/add comments)

Initializes the line iterator.

int cvInitLineIterator(
const CvArr* image,
CvPoint pt1,
1.4. DRAWING FUNCTIONS 199

CvPoint pt2,
CvLineIterator* line iterator,
int connectivity=8,
int left to right=0 );

image Image to sample the line from

pt1 First ending point of the line segment

pt2 Second ending point of the line segment

line iterator Pointer to the line iterator state structure

connectivity The scanned line connectivity, 4 or 8.

left to right If (left to right = 0 ) then the line is scanned in the specified order, from
pt1 to pt2. If (left to right 6= 0) the line is scanned from left-most point to right-most.

The function initializes the line iterator and returns the number of pixels between the two end
points. Both points must be inside the image. After the iterator has been initialized, all the points
on the raster line that connects the two ending points may be retrieved by successive calls of
CV NEXT LINE POINT point.
The points on the line are calculated one by one using a 4-connected or 8-connected Bresen-
ham algorithm.
Example: Using line iterator to calculate the sum of pixel values along the color line.

CvScalar sum_line_pixels( IplImage* image, CvPoint pt1, CvPoint pt2 )

{
CvLineIterator iterator;
int blue_sum = 0, green_sum = 0, red_sum = 0;
int count = cvInitLineIterator( image, pt1, pt2, &iterator, 8, 0 );

for( int i = 0; i < count; i++ ){

blue_sum += [Link][0];
green_sum += [Link][1];
red_sum += [Link][2];
CV_NEXT_LINE_POINT(iterator);

/* print the pixel coordinates: demonstrates how to calculate the

coordinates */
{
200 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

int offset, x, y;
/* assume that ROI is not set, otherwise need to take it
into account. */
offset = [Link] - (uchar*)(image->imageData);
y = offset/image->widthStep;
x = (offset - y*image->widthStep)/(3*sizeof(uchar)
/* size of pixel */);
printf("(%d,%d)\n", x, y );
}
}
return cvScalar( blue_sum, green_sum, red_sum );
}

cvLine (view/add comments)

Draws a line segment connecting two points.

void cvLine(
CvArr* img,
CvPoint pt1,
CvPoint pt2,
CvScalar color,
int thickness=1,
int lineType=8,
int shift=0 );

img The image

pt1 First point of the line segment

pt2 Second point of the line segment

color Line color

thickness Line thickness

lineType Type of the line:

8 (or omitted) 8-connected line.

4 4-connected line.
1.4. DRAWING FUNCTIONS 201

CV AA antialiased line.

shift Number of fractional bits in the point coordinates

The function draws the line segment between pt1 and pt2 points in the image. The line
is clipped by the image or ROI rectangle. For non-antialiased lines with integer coordinates the
8-connected or 4-connected Bresenham algorithm is used. Thick lines are drawn with rounding
endings. Antialiased lines are drawn using Gaussian filtering. To specify the line color, the user
may use the macro CV RGB( r, g, b ).

cvPolyLine (view/add comments)

Draws simple or thick polygons.

void cvPolyLine(
CvArr* img,
CvPoint** pts,
int* npts,
int contours,
int is closed,
CvScalar color,
int thickness=1,
int lineType=8,
int shift=0 );

pts Array of pointers to polygons

npts Array of polygon vertex counters

contours Number of contours that bind the filled region

img Image

is closed Indicates whether the polylines must be drawn closed. If closed, the function draws
the line from the last vertex of every contour to the first vertex.

color Polyline color

thickness Thickness of the polyline edges

202 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

lineType Type of the line segments, see Line description

shift Number of fractional bits in the vertex coordinates

The function draws single or multiple polygonal curves.

cvPutText (view/add comments)

Draws a text string.

void cvPutText(
CvArr* img,
const char* text,
CvPoint org,
const CvFont* font,
CvScalar color );

img Input image

text String to print

org Coordinates of the bottom-left corner of the first letter

font Pointer to the font structure

color Text color

The function renders the text in the image with the specified font and color. The printed text is
clipped by the ROI rectangle. Symbols that do not belong to the specified font are replaced with
the symbol for a rectangle.

cvRectangle (view/add comments)

Draws a simple, thick, or filled rectangle.
1.4. DRAWING FUNCTIONS 203

void cvRectangle(
CvArr* img,
CvPoint pt1,
CvPoint pt2,
CvScalar color,
int thickness=1,
int lineType=8,
int shift=0 );

img Image

pt1 One of the rectangle’s vertices

pt2 Opposite rectangle vertex

color Line color (RGB) or brightness (grayscale image)

thickness Thickness of lines that make up the rectangle. Negative values, e.g., CV FILLED,
cause the function to draw a filled rectangle.

lineType Type of the line, see Line description

shift Number of fractional bits in the point coordinates

The function draws a rectangle with two opposite corners pt1 and pt2.

CV RGB (view/add comments)

Constructs a color value.

#define CV RGB( r, g, b ) cvScalar( (b), (g), (r) )

red Red component

grn Green component

blu Blue component

204 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

1.5 XML/YAML Persistence

CvFileStorage (view/add comments)

File Storage.
typedef struct CvFileStorage
{
... // hidden fields
} CvFileStorage;
The structure CvFileStorage is a ”black box” representation of the file storage associated
with a file on disk. Several functions that are described below take CvFileStorage as inputs
and allow theuser to save or to load hierarchical collections that consist of scalar values, standard
CXCore objects (such as matrices, sequences, graphs), and user-defined objects.
CXCore can read and write data in XML ([Link] or YAML ([Link]
formats. Below is an example of 3 × 3 floating-point identity matrix A, stored in XML and YAML
files using CXCore functions:
XML:

<?xml version="1.0">
<opencv_storage>
<A type_id="opencv-matrix">
<rows>3</rows>
<cols>3</cols>
<dt>f</dt>
<data>1. 0. 0. 0. 1. 0. 0. 0. 1.</data>
</A>
</opencv_storage>

YAML:

%YAML:1.0
A: !!opencv-matrix
rows: 3
cols: 3
dt: f
data: [ 1., 0., 0., 0., 1., 0., 0., 0., 1.]

As it can be seen from the examples, XML uses nested tags to represent hierarchy, while YAML
uses indentation for that purpose (similar to the Python programming language).
The same CXCore functions can read and write data in both formats; the particular format is
determined by the extension of the opened file, .xml for XML files and .yml or .yaml for YAML.
1.5. XML/YAML PERSISTENCE 205

CvFileNode (view/add comments)

File Storage Node.
/* file node type */
#define CV_NODE_NONE 0
#define CV_NODE_INT 1
#define CV_NODE_INTEGER CV_NODE_INT
#define CV_NODE_REAL 2
#define CV_NODE_FLOAT CV_NODE_REAL
#define CV_NODE_STR 3
#define CV_NODE_STRING CV_NODE_STR
#define CV_NODE_REF 4 /* not used */
#define CV_NODE_SEQ 5
#define CV_NODE_MAP 6
#define CV_NODE_TYPE_MASK 7

/* optional flags */
#define CV_NODE_USER 16
#define CV_NODE_EMPTY 32
#define CV_NODE_NAMED 64

#define CV_NODE_TYPE(tag) ((tag) & CV_NODE_TYPE_MASK)

#define CV_NODE_IS_INT(tag) (CV_NODE_TYPE(tag) == CV_NODE_INT)

#define CV_NODE_IS_REAL(tag) (CV_NODE_TYPE(tag) == CV_NODE_REAL)
#define CV_NODE_IS_STRING(tag) (CV_NODE_TYPE(tag) == CV_NODE_STRING)
#define CV_NODE_IS_SEQ(tag) (CV_NODE_TYPE(tag) == CV_NODE_SEQ)
#define CV_NODE_IS_MAP(tag) (CV_NODE_TYPE(tag) == CV_NODE_MAP)
#define CV_NODE_IS_COLLECTION(tag) (CV_NODE_TYPE(tag) >= CV_NODE_SEQ)
#define CV_NODE_IS_FLOW(tag) (((tag) & CV_NODE_FLOW) != 0)
#define CV_NODE_IS_EMPTY(tag) (((tag) & CV_NODE_EMPTY) != 0)
#define CV_NODE_IS_USER(tag) (((tag) & CV_NODE_USER) != 0)
#define CV_NODE_HAS_NAME(tag) (((tag) & CV_NODE_NAMED) != 0)

#define CV_NODE_SEQ_SIMPLE 256

#define CV_NODE_SEQ_IS_SIMPLE(seq) (((seq)->flags & CV_NODE_SEQ_SIMPLE) != 0)

typedef struct CvString

{
int len;
char* ptr;
}
CvString;
206 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

/* all the keys (names) of elements in the readed file storage

are stored in the hash to speed up the lookup operations */
typedef struct CvStringHashNode
{
unsigned hashval;
CvString str;
struct CvStringHashNode* next;
}
CvStringHashNode;

/* basic element of the file storage - scalar or collection */

typedef struct CvFileNode
{
int tag;
struct CvTypeInfo* info; /* type information
(only for user-defined object, for others it is 0) */
union
{
double f; /* scalar floating-point number */
int i; /* scalar integer number */
CvString str; /* text string */
CvSeq* seq; /* sequence (ordered collection of file nodes) */
struct CvMap* map; /* map (collection of named file nodes) */
} data;
}
CvFileNode;

The structure is used only for retrieving data from file storage (i.e., for loading data from the
file). When data is written to a file, it is done sequentially, with minimal buffering. No data is stored
in the file storage.

In opposite, when data is read from a file, the whole file is parsed and represented in memory
as a tree. Every node of the tree is represented by CvFileNode . The type of file node N can
be retrieved as CV NODE TYPE(N->tag). Some file nodes (leaves) are scalars: text strings,
integers, or floating-point numbers. Other file nodes are collections of file nodes, which can be
scalars or collections in their turn. There are two types of collections: sequences and maps (we
use YAML notation, however, the same is true for XML streams). Sequences (do not mix them
with CvSeq ) are ordered collections of unnamed file nodes; maps are unordered collections of
named file nodes. Thus, elements of sequences are accessed by index ( GetSeqElem ), while
elements of maps are accessed by name ( GetFileNodeByName ). The table below describes the
different types of file nodes:
1.5. XML/YAML PERSISTENCE 207

Type CV NODE TYPE(node->tag) Value

Integer CV NODE INT node->data.i
Floating-point CV NODE REAL node->data.f
Text string CV NODE STR node->[Link]
Sequence CV NODE SEQ node->[Link]
Map CV NODE MAP node->[Link] (see below)
There is no need to access the map field directly (by the way, CvMap is a hidden structure).
The elements of the map can be retrieved with the GetFileNodeByName function that takes a
pointer to the ”map” file node.
A user (custom) object is an instance of either one of the standard CxCore types, such as
CvMat , CvSeq etc., or any type registered with RegisterTypeInfo . Such an object is initially rep-
resented in a file as a map (as shown in XML and YAML example files above) after the file storage
has been opened and parsed. Then the object can be decoded (coverted to native representation)
by request - when a user calls the Read or ReadByName functions.

CvAttrList (view/add comments)

List of attributes.
typedef struct CvAttrList
{
const char** attr; /* NULL-terminated array of (attribute\_name,attribute\_value) pairs
struct CvAttrList* next; /* pointer to next chunk of the attributes list */
}
CvAttrList;

/* initializes CvAttrList structure */

inline CvAttrList cvAttrList( const char** attr=NULL, CvAttrList* next=NULL );

/* returns attribute value or 0 (NULL) if there is no such attribute */

const char* cvAttrValue( const CvAttrList* attr, const char* attr\_name );
In the current implementation, attributes are used to pass extra parameters when writing user
objects (see Write ). XML attributes inside tags are not supported, aside from the object type
specification (type id attribute).

CvTypeInfo (view/add comments)

Type information.
typedef int (CV_CDECL *CvIsInstanceFunc)( const void* structPtr );
typedef void (CV_CDECL *CvReleaseFunc)( void** structDblPtr );
typedef void* (CV_CDECL *CvReadFunc)( CvFileStorage* storage, CvFileNode* node );
208 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

typedef void (CV_CDECL *CvWriteFunc)( CvFileStorage* storage,

const char* name,
const void* structPtr,
CvAttrList attributes );
typedef void* (CV_CDECL *CvCloneFunc)( const void* structPtr );

typedef struct CvTypeInfo

{
int flags; /* not used */
int header_size; /* sizeof(CvTypeInfo) */
struct CvTypeInfo* prev; /* previous registered type in the list */
struct CvTypeInfo* next; /* next registered type in the list */
const char* type_name; /* type name, written to file storage */

/* methods */
CvIsInstanceFunc is_instance; /* checks if the passed object belongs to the type */
CvReleaseFunc release; /* releases object (memory etc.) */
CvReadFunc read; /* reads object from file storage */
CvWriteFunc write; /* writes object to file storage */
CvCloneFunc clone; /* creates a copy of the object */
}
CvTypeInfo;
The structure CvTypeInfo contains information about one of the standard or user-defined
types. Instances of the type may or may not contain a pointer to the corresponding CvTypeInfo
structure. In any case, there is a way to find the type info structure for a given object using the
TypeOf function. Aternatively, type info can be found by type name using FindType , which is used
when an object is read from file storage. The user can register a new type with RegisterType that
adds the type information structure into the beginning of the type list. Thus, it is possible to create
specialized types from generic standard types and override the basic methods.

cvClone (view/add comments)

Makes a clone of an object.

void* cvClone( const void* structPtr );

structPtr The object to clone

The function finds the type of a given object and calls clone with the passed object.
1.5. XML/YAML PERSISTENCE 209

cvEndWriteStruct (view/add comments)

Ends the writing of a structure.

void cvEndWriteStruct(CvFileStorage* fs);

fs File storage

The function finishes the currently written structure.

cvFindType (view/add comments)

Finds a type by its name.

CvTypeInfo* cvFindType(const char* typeName);

typeName Type name

The function finds a registered type by its name. It returns NULL if there is no type with the
specified name.

cvFirstType (view/add comments)

Returns the beginning of a type list.

CvTypeInfo* cvFirstType(void);

The function returns the first type in the list of registered types. Navigation through the list can
be done via the prev and next fields of the CvTypeInfo structure.
210 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

cvGetFileNode (view/add comments)

Finds a node in a map or file storage.

CvFileNode* cvGetFileNode(
CvFileStorage* fs,
CvFileNode* map,
const CvStringHashNode* key,
int createMissing=0 );

fs File storage

map The parent map. If it is NULL, the function searches a top-level node. If both map and key
are NULLs, the function returns the root file node - a map that contains top-level nodes.

key Unique pointer to the node name, retrieved with GetHashedKey

createMissing Flag that specifies whether an absent node should be added to the map

The function finds a file node. It is a faster version of GetFileNodeByName (see GetHashed-
Key discussion). Also, the function can insert a new node, if it is not in the map yet.

cvGetFileNodeByName (view/add comments)

Finds a node in a map or file storage.

CvFileNode* cvGetFileNodeByName(
const CvFileStorage* fs,
const CvFileNode* map,
const char* name);

fs File storage

map The parent map. If it is NULL, the function searches in all the top-level nodes (streams),
starting with the first one.
1.5. XML/YAML PERSISTENCE 211

name The file node name

The function finds a file node by name. The node is searched either in map or, if the pointer
is NULL, among the top-level file storage nodes. Using this function for maps and GetSeqElem
(or sequence reader) for sequences, it is possible to nagivate through the file storage. To speed
up multiple queries for a certain key (e.g., in the case of an array of structures) one may use a
combination of GetHashedKey and GetFileNode .

cvGetFileNodeName (view/add comments)

Returns the name of a file node.

const char* cvGetFileNodeName( const CvFileNode* node );

node File node

The function returns the name of a file node or NULL, if the file node does not have a name or
if node is NULL.

cvGetHashedKey (view/add comments)

Returns a unique pointer for a given name.

CvStringHashNode* cvGetHashedKey(
CvFileStorage* fs,
const char* name,
int len=-1,
int createMissing=0 );

fs File storage

name Literal node name

len Length of the name (if it is known apriori), or -1 if it needs to be calculated

createMissing Flag that specifies, whether an absent key should be added into the hash table
212 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

The function returns a unique pointer for each particular file node name. This pointer can be
then passed to the GetFileNode function that is faster than GetFileNodeByName because it
compares text strings by comparing pointers rather than the strings’ content.
Consider the following example where an array of points is encoded as a sequence of 2-entry
maps:

%YAML:1.0
points:
- { x: 10, y: 10 }
- { x: 20, y: 20 }
- { x: 30, y: 30 }
# ...
Then, it is possible to get hashed ”x” and ”y” pointers to speed up decoding of the points.

#include "cxcore.h"

int main( int argc, char** argv )

{
CvFileStorage* fs = cvOpenFileStorage( "[Link]", 0, CV\_STORAGE\_READ );
CvStringHashNode* x\_key = cvGetHashedNode( fs, "x", -1, 1 );
CvStringHashNode* y\_key = cvGetHashedNode( fs, "y", -1, 1 );
CvFileNode* points = cvGetFileNodeByName( fs, 0, "points" );

if( CV\_NODE\_IS\_SEQ(points->tag) )
{
CvSeq* seq = points->[Link];
int i, total = seq->total;
CvSeqReader reader;
cvStartReadSeq( seq, &reader, 0 );
for( i = 0; i < total; i++ )
{
CvFileNode* pt = (CvFileNode*)[Link];
#if 1 /* faster variant */
CvFileNode* xnode = cvGetFileNode( fs, pt, x\_key, 0 );
CvFileNode* ynode = cvGetFileNode( fs, pt, y\_key, 0 );
assert( xnode && CV\_NODE\_IS\_INT(xnode->tag) &&
ynode && CV\_NODE\_IS\_INT(ynode->tag));
int x = xnode->data.i; // or x = cvReadInt( xnode, 0 );
int y = ynode->data.i; // or y = cvReadInt( ynode, 0 );
#elif 1 /* slower variant; does not use x\_key & y\_key */
CvFileNode* xnode = cvGetFileNodeByName( fs, pt, "x" );
CvFileNode* ynode = cvGetFileNodeByName( fs, pt, "y" );
assert( xnode && CV\_NODE\_IS\_INT(xnode->tag) &&
1.5. XML/YAML PERSISTENCE 213

ynode && CV\_NODE\_IS\_INT(ynode->tag));

int x = xnode->data.i; // or x = cvReadInt( xnode, 0 );
int y = ynode->data.i; // or y = cvReadInt( ynode, 0 );
#else /* the slowest yet the easiest to use variant */
int x = cvReadIntByName( fs, pt, "x", 0 /* default value */ );
int y = cvReadIntByName( fs, pt, "y", 0 /* default value */ );
#endif
CV\_NEXT\_SEQ\_ELEM( seq->elem\_size, reader );
printf("%d: (%d, %d)\n", i, x, y );
}
}
cvReleaseFileStorage( &fs );
return 0;
}

Please note that whatever method of accessing a map you are using, it is still much slower
than using plain sequences; for example, in the above example, it is more efficient to encode the
points as pairs of integers in a single numeric sequence.

cvGetRootFileNode (view/add comments)

Retrieves one of the top-level nodes of the file storage.

CvFileNode* cvGetRootFileNode(
const CvFileStorage* fs,
int stream index=0 );

fs File storage

stream index Zero-based index of the stream. See StartNextStream . In most cases, there is
only one stream in the file; however, there can be several.

The function returns one of the top-level file nodes. The top-level nodes do not have a name,
they correspond to the streams that are stored one after another in the file storage. If the index
is out of range, the function returns a NULL pointer, so all the top-level nodes may be iterated by
subsequent calls to the function with stream index=0,1,..., until the NULL pointer is returned.
This function may be used as a base for recursive traversal of the file storage.
214 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

cvLoad (view/add comments)

Loads an object from a file.

void* cvLoad(
const char* filename,
CvMemStorage* storage=NULL,
const char* name=NULL,
const char** realName=NULL );

filename File name

storage Memory storage for dynamic structures, such as CvSeq or CvGraph . It is not used
for matrices or images.

name Optional object name. If it is NULL, the first top-level object in the storage will be loaded.

realName Optional output parameter that will contain the name of the loaded object (useful if
name=NULL)

The function loads an object from a file. It provides a simple interface to cvRead. After the
object is loaded, the file storage is closed and all the temporary buffers are deleted. Thus, to load
a dynamic structure, such as a sequence, contour, or graph, one should pass a valid memory
storage destination to the function.

cvOpenFileStorage (view/add comments)

Opens file storage for reading or writing data.

CvFileStorage* cvOpenFileStorage(
const char* filename,
CvMemStorage* memstorage,
int flags);

filename Name of the file associated with the storage

1.5. XML/YAML PERSISTENCE 215

memstorage Memory storage used for temporary data and for storing dynamic structures, such
as CvSeq or CvGraph . If it is NULL, a temporary memory storage is created and used.

flags Can be one of the following:

CV STORAGE READ the storage is open for reading

CV STORAGE WRITE the storage is open for writing

The function opens file storage for reading or writing data. In the latter case, a new file is
created or an existing file is rewritten. The type of the read or written file is determined by the
filename extension: .xml for XML and .yml or .yaml for YAML. The function returns a pointer to
the CvFileStorage structure.

cvRead (view/add comments)

Decodes an object and returns a pointer to it.

void* cvRead(
CvFileStorage* fs,
CvFileNode* node,
CvAttrList* attributes=NULL );

fs File storage

node The root object node

attributes Unused parameter

The function decodes a user object (creates an object in a native representation from the file
storage subtree) and returns it. The object to be decoded must be an instance of a registered type
that supports the read method (see CvTypeInfo ). The type of the object is determined by the
type name that is encoded in the file. If the object is a dynamic structure, it is created either in
memory storage and passed to OpenFileStorage or, if a NULL pointer was passed, in temporary
memory storage, which is released when ReleaseFileStorage is called. Otherwise, if the object is
not a dynamic structure, it is created in a heap and should be released with a specialized function
or by using the generic Release .
216 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

cvReadByName (view/add comments)

Finds an object by name and decodes it.

void* cvReadByName(
CvFileStorage* fs,
const CvFileNode* map,
const char* name,
CvAttrList* attributes=NULL );

fs File storage
map The parent map. If it is NULL, the function searches a top-level node.
name The node name
attributes Unused parameter

The function is a simple superposition of GetFileNodeByName and Read .

cvReadInt (view/add comments)

Retrieves an integer value from a file node.

int cvReadInt(
const CvFileNode* node,
int defaultValue=0 );

node File node

defaultValue The value that is returned if node is NULL

The function returns an integer that is represented by the file node. If the file node is NULL,
the defaultValue is returned (thus, it is convenient to call the function right after GetFileNode
without checking for a NULL pointer). If the file node has type CV NODE INT, then node->data.i
is returned. If the file node has type CV NODE REAL, then node->data.f is converted to an
integer and returned. Otherwise the result is not determined.
1.5. XML/YAML PERSISTENCE 217

cvReadIntByName (view/add comments)

Finds a file node and returns its value.

int cvReadIntByName(
const CvFileStorage* fs,
const CvFileNode* map,
const char* name,
int defaultValue=0 );

fs File storage
map The parent map. If it is NULL, the function searches a top-level node.
name The node name
defaultValue The value that is returned if the file node is not found
The function is a simple superposition of GetFileNodeByName and ReadInt .

cvReadRawData (view/add comments)

Reads multiple numbers.

void cvReadRawData(
const CvFileStorage* fs,
const CvFileNode* src,
void* dst,
const char* dt);

fs File storage
src The file node (a sequence) to read numbers from
dst Pointer to the destination array
dt Specification of each array element. It has the same format as in WriteRawData .
The function reads elements from a file node that represents a sequence of scalars.
218 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

cvReadRawDataSlice (view/add comments)

Initializes file node sequence reader.

void cvReadRawDataSlice(
const CvFileStorage* fs,
CvSeqReader* reader,
int count,
void* dst,
const char* dt );

fs File storage

reader The sequence reader. Initialize it with StartReadRawData .

count The number of elements to read

dst Pointer to the destination array

dt Specification of each array element. It has the same format as in WriteRawData .

The function reads one or more elements from the file node, representing a sequence, to a
user-specified array. The total number of read sequence elements is a product of total and
the number of components in each array element. For example, if dt=2if, the function will read
total × 3 sequence elements. As with any sequence, some parts of the file node sequence may
be skipped or read repeatedly by repositioning the reader using SetSeqReaderPos .

cvReadReal (view/add comments)

Retrieves a floating-point value from a file node.

double cvReadReal(
const CvFileNode* node,
double defaultValue=0. );

node File node

1.5. XML/YAML PERSISTENCE 219

defaultValue The value that is returned if node is NULL

The function returns a floating-point value that is represented by the file node. If the file node
is NULL, the defaultValue is returned (thus, it is convenient to call the function right after
GetFileNode without checking for a NULL pointer). If the file node has type CV NODE REAL,
then node->data.f is returned. If the file node has type CV NODE INT, then node->data.f is
converted to floating-point and returned. Otherwise the result is not determined.

cvReadRealByName (view/add comments)

Finds a file node and returns its value.

double cvReadRealByName(
const CvFileStorage* fs,
const CvFileNode* map,
const char* name,
double defaultValue=0.);

fs File storage

map The parent map. If it is NULL, the function searches a top-level node.

name The node name

defaultValue The value that is returned if the file node is not found

The function is a simple superposition of GetFileNodeByName and ReadReal .

cvReadString (view/add comments)

Retrieves a text string from a file node.

const char* cvReadString(

const CvFileNode* node,
const char* defaultValue=NULL );
220 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

node File node

defaultValue The value that is returned if node is NULL
The function returns a text string that is represented by the file node. If the file node is
NULL, the defaultValue is returned (thus, it is convenient to call the function right after Get-
FileNode without checking for a NULL pointer). If the file node has type CV NODE STR, then
node->[Link] is returned. Otherwise the result is not determined.

cvReadStringByName (view/add comments)

Finds a file node by its name and returns its value.

const char* cvReadStringByName(

const CvFileStorage* fs,
const CvFileNode* map,
const char* name,
const char* defaultValue=NULL );

fs File storage
map The parent map. If it is NULL, the function searches a top-level node.
name The node name
defaultValue The value that is returned if the file node is not found
The function is a simple superposition of GetFileNodeByName and ReadString .

cvRegisterType (view/add comments)

Registers a new type.

void cvRegisterType(const CvTypeInfo* info);

info Type info structure

The function registers a new type, which is described by info. The function creates a copy of
the structure, so the user should delete it after calling the function.
1.5. XML/YAML PERSISTENCE 221

cvRelease (view/add comments)

Releases an object.

void cvRelease( void** structPtr );

structPtr Double pointer to the object

The function finds the type of a given object and calls release with the double pointer.

cvReleaseFileStorage (view/add comments)

Releases file storage.

void cvReleaseFileStorage(CvFileStorage** fs);

fs Double pointer to the released file storage

The function closes the file associated with the storage and releases all the temporary struc-
tures. It must be called after all I/O operations with the storage are finished.

cvSave (view/add comments)

Saves an object to a file.

void cvSave(
const char* filename,
const void* structPtr,
const char* name=NULL,
const char* comment=NULL,
CvAttrList attributes=cvAttrList());
222 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

filename File name

structPtr Object to save
name Optional object name. If it is NULL, the name will be formed from filename.
comment Optional comment to put in the beginning of the file
attributes Optional attributes passed to Write
The function saves an object to a file. It provides a simple interface to Write .

cvStartNextStream (view/add comments)

Starts the next stream.

void cvStartNextStream(CvFileStorage* fs);

fs File storage
The function starts the next stream in file storage. Both YAML and XML support multiple
”streams.” This is useful for concatenating files or for resuming the writing process.

cvStartReadRawData (view/add comments)

Initializes the file node sequence reader.

void cvStartReadRawData(
const CvFileStorage* fs,
const CvFileNode* src,
CvSeqReader* reader);

fs File storage
src The file node (a sequence) to read numbers from
reader Pointer to the sequence reader
The function initializes the sequence reader to read data from a file node. The initialized reader
can be then passed to ReadRawDataSlice .
1.5. XML/YAML PERSISTENCE 223

cvStartWriteStruct (view/add comments)

Starts writing a new structure.

void cvStartWriteStruct( CvFileStorage* fs,

const char* name,
int struct flags,
const char* typeName=NULL,
CvAttrList attributes=cvAttrList(
));

fs File storage
name Name of the written structure. The structure can be accessed by this name when the
storage is read.
struct flags A combination one of the following values:
CV NODE SEQ the written structure is a sequence (see discussion of CvFileStorage ), that
is, its elements do not have a name.
CV NODE MAP the written structure is a map (see discussion of CvFileStorage ), that is, all
its elements have names.
One and only one of the two above flags must be specified
CV NODE FLOW the optional flag that makes sense only for YAML streams. It means that the
structure is written as a flow (not as a block), which is more compact. It is recommended to
use this flag for structures or arrays whose elements are all scalars.
typeName Optional parameter - the object type name. In case of XML it is written as a type id
attribute of the structure opening tag. In the case of YAML it is written after a colon following
the structure name (see the example in CvFileStorage description). Mainly it is used with
user objects. When the storage is read, the encoded type name is used to determine the
object type (see CvTypeInfo and FindTypeInfo ).
attributes This parameter is not used in the current implementation
The function starts writing a compound structure (collection) that can be a sequence or a
map. After all the structure fields, which can be scalars or structures, are written, EndWriteStruct
should be called. The function can be used to group some objects or to implement the write
function for a some user object (see CvTypeInfo ).
224 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

cvTypeOf (view/add comments)

Returns the type of an object.

CvTypeInfo* cvTypeOf( const void* structPtr );

structPtr The object pointer

The function finds the type of a given object. It iterates through the list of registered types and
calls the is instance function/method for every type info structure with that object until one of
them returns non-zero or until the whole list has been traversed. In the latter case, the function
returns NULL.

cvUnregisterType (view/add comments)

Unregisters the type.

void cvUnregisterType( const char* typeName );

typeName Name of an unregistered type

The function unregisters a type with a specified name. If the name is unknown, it is possible to
locate the type info by an instance of the type using TypeOf or by iterating the type list, starting
from FirstType , and then calling cvUnregisterType(info->typeName).

cvWrite (view/add comments)

Writes a user object.

void cvWrite( CvFileStorage* fs,

const char* name,
const void* ptr,
CvAttrList attributes=cvAttrList(
) );
1.5. XML/YAML PERSISTENCE 225

fs File storage

name Name of the written object. Should be NULL if and only if the parent structure is a sequence.

ptr Pointer to the object

attributes The attributes of the object. They are specific for each particular type (see the
dicsussion below).

The function writes an object to file storage. First, the appropriate type info is found using
TypeOf . Then, the write method associated with the type info is called.
Attributes are used to customize the writing procedure. The standard types support the follow-
ing attributes (all the *dt attributes have the same format as in WriteRawData ):

1. CvSeq

header dt description of user fields of the sequence header that follow CvSeq, or CvChain
(if the sequence is a Freeman chain) or CvContour (if the sequence is a contour or point
sequence)
dt description of the sequence elements.
recursive if the attribute is present and is not equal to ”0” or ”false”, the whole tree of
sequences (contours) is stored.

2. Cvgraph

header dt description of user fields of the graph header that follows CvGraph;
vertex dt description of user fields of graph vertices
edge dt description of user fields of graph edges (note that the edge weight is always
written, so there is no need to specify it explicitly)

Below is the code that creates the YAML file shown in the CvFileStorage description:
#include "cxcore.h"

int main( int argc, char** argv )

{
CvMat* mat = cvCreateMat( 3, 3, CV\_32F );
CvFileStorage* fs = cvOpenFileStorage( "[Link]", 0, CV\_STORAGE\_WRITE );

cvSetIdentity( mat );
cvWrite( fs, "A", mat, cvAttrList(0,0) );

cvReleaseFileStorage( &fs );
226 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

cvReleaseMat( &mat );
return 0;
}

cvWriteComment (view/add comments)

Writes a comment.

void cvWriteComment(
CvFileStorage* fs,
const char* comment,
int eolComment);

fs File storage

comment The written comment, single-line or multi-line

eolComment If non-zero, the function tries to put the comment at the end of current line. If the
flag is zero, if the comment is multi-line, or if it does not fit at the end of the current line, the
comment starts a new line.

The function writes a comment into file storage. The comments are skipped when the storage
is read, so they may be used only for debugging or descriptive purposes.

cvWriteFileNode (view/add comments)

Writes a file node to another file storage.

void cvWriteFileNode(
CvFileStorage* fs,
const char* new node name,
const CvFileNode* node,
int embed );

fs Destination file storage

1.5. XML/YAML PERSISTENCE 227

new file node New name of the file node in the destination file storage. To keep the existing
name, use cvGetFileNodeName

node The written node

embed If the written node is a collection and this parameter is not zero, no extra level of hiararchy
is created. Instead, all the elements of node are written into the currently written structure.
Of course, map elements may be written only to a map, and sequence elements may be
written only to a sequence.

The function writes a copy of a file node to file storage. Possible applications of the function
are merging several file storages into one and conversion between XML and YAML formats.

cvWriteInt (view/add comments)

Writes an integer value.

void cvWriteInt(
CvFileStorage* fs,
const char* name,
int value);

fs File storage

name Name of the written value. Should be NULL if and only if the parent structure is a sequence.

value The written value

The function writes a single integer value (with or without a name) to the file storage.

cvWriteRawData (view/add comments)

Writes multiple numbers.
228 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

void cvWriteRawData(
CvFileStorage* fs,
const void* src,
int len,
const char* dt );

fs File storage

src Pointer to the written array

len Number of the array elements to write

dt Specification of each array element that has the following format

([count]{’u’|’c’|’w’|’s’|’i’|’f’|’d’})... where the characters correspond to
fundamental C types:

u 8-bit unsigned number

c 8-bit signed number
w 16-bit unsigned number
s 16-bit signed number
i 32-bit signed number
f single precision floating-point number
d double precision floating-point number
r pointer, 32 lower bits of which are written as a signed integer. The type can be used to
store structures with links between the elements. count is the optional counter of val-
ues of a given type. For example, 2if means that each array element is a structure of 2
integers, followed by a single-precision floating-point number. The equivalent notations
of the above specification are ’iif’, ’2i1f’ and so forth. Other examples: u means that
the array consists of bytes, and 2d means the array consists of pairs of doubles.

The function writes an array, whose elements consist of single or multiple numbers. The func-
tion call can be replaced with a loop containing a few WriteInt and WriteReal calls, but a single
call is more efficient. Note that because none of the elements have a name, they should be written
to a sequence rather than a map.
1.5. XML/YAML PERSISTENCE 229

cvWriteReal (view/add comments)

Writes a floating-point value.

void cvWriteReal(
CvFileStorage* fs,
const char* name,
double value );

fs File storage

name Name of the written value. Should be NULL if and only if the parent structure is a sequence.

value The written value

The function writes a single floating-point value (with or without a name) to file storage. Special
values are encoded as follows: NaN (Not A Number) as .NaN, ±∞ as +.Inf (-.Inf).
The following example shows how to use the low-level writing functions to store custom struc-
tures, such as termination criteria, without registering a new type.
void write_termcriteria( CvFileStorage* fs, const char* struct_name,
CvTermCriteria* termcrit )
{
cvStartWriteStruct( fs, struct_name, CV_NODE_MAP, NULL, cvAttrList(0,0));
cvWriteComment( fs, "termination criteria", 1 ); // just a description
if( termcrit->type & CV_TERMCRIT_ITER )
cvWriteInteger( fs, "max_iterations", termcrit->max_iter );
if( termcrit->type & CV_TERMCRIT_EPS )
cvWriteReal( fs, "accuracy", termcrit->epsilon );
cvEndWriteStruct( fs );
}

cvWriteString (view/add comments)

Writes a text string.
230 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

void cvWriteString(
CvFileStorage* fs,
const char* name,
const char* str,
int quote=0 );

fs File storage

name Name of the written string . Should be NULL if and only if the parent structure is a sequence.

str The written text string

quote If non-zero, the written string is put in quotes, regardless of whether they are required.
Otherwise, if the flag is zero, quotes are used only when they are required (e.g. when the
string starts with a digit or contains spaces).

The function writes a text string to file storage.

1.6 Clustering

cvKMeans2 (view/add comments)

Splits set of vectors by a given number of clusters.

int cvKMeans2(const CvArr* samples, int nclusters,

CvArr* labels, CvTermCriteria termcrit,
int attempts=1, CvRNG* rng=0,
int flags=0, CvArr* centers=0,
double* compactness=0);

samples Floating-point matrix of input samples, one row per sample

nclusters Number of clusters to split the set by

labels Output integer vector storing cluster indices for every sample
1.6. CLUSTERING 231

termcrit Specifies maximum number of iterations and/or accuracy (distance the centers can
move by between subsequent iterations)

attempts How many times the algorithm is executed using different initial labelings. The algo-
rithm returns labels that yield the best compactness (see the last function parameter)

rng Optional external random number generator; can be used to fully control the function be-
haviour

flags Can be 0 or CV KMEANS USE INITIAL LABELS. The latter value means that during the
first (and possibly the only) attempt, the function uses the user-supplied labels as the initial
approximation instead of generating random labels. For the second and further attempts,
the function will use randomly generated labels in any case

centers The optional output array of the cluster centers

compactness The optional output parameter, which is computed as i ||samplesi −centerslabelsi ||2
P
after every attempt; the best (minimum) value is chosen and the corresponding labels are re-
turned by the function. Basically, the user can use only the core of the function, set the num-
ber of attempts to 1, initialize labels each time using a custom algorithm (flags=CV KMEAN USE INITIAL L
and, based on the output compactness or any other criteria, choose the best clustering.

The function cvKMeans2 implements a k-means algorithm that finds the centers of nclusters
clusters and groups the input samples around the clusters. On output, labelsi contains a cluster
index for samples stored in the i-th row of the samples matrix.
#include "cxcore.h"
#include "highgui.h"

void main( int argc, char** argv )

{
#define MAX_CLUSTERS 5
CvScalar color_tab[MAX_CLUSTERS];
IplImage* img = cvCreateImage( cvSize( 500, 500 ), 8, 3 );
CvRNG rng = cvRNG(0xffffffff);

color_tab[0] = CV_RGB(255,0,0);
color_tab[1] = CV_RGB(0,255,0);
color_tab[2] = CV_RGB(100,100,255);
color_tab[3] = CV_RGB(255,0,255);
color_tab[4] = CV_RGB(255,255,0);

cvNamedWindow( "clusters", 1 );
232 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

for(;;)
{
int k, cluster_count = cvRandInt(&rng)%MAX_CLUSTERS + 1;
int i, sample_count = cvRandInt(&rng)%1000 + 1;
CvMat* points = cvCreateMat( sample_count, 1, CV_32FC2 );
CvMat* clusters = cvCreateMat( sample_count, 1, CV_32SC1 );

/* generate random sample from multigaussian distribution */

for( k = 0; k < cluster_count; k++ )
{
CvPoint center;
CvMat point_chunk;
center.x = cvRandInt(&rng)%img->width;
center.y = cvRandInt(&rng)%img->height;
cvGetRows( points,
&point_chunk,
k*sample_count/cluster_count,
(k == (cluster_count - 1)) ?
sample_count :
(k+1)*sample_count/cluster_count );
cvRandArr( &rng, &point_chunk, CV_RAND_NORMAL,
cvScalar(center.x,center.y,0,0),
cvScalar(img->width/6, img->height/6,0,0) );
}

/* shuffle samples */
for( i = 0; i < sample_count/2; i++ )
{
CvPoint2D32f* pt1 =
(CvPoint2D32f*)points->[Link] + cvRandInt(&rng)%sample_count;
CvPoint2D32f* pt2 =
(CvPoint2D32f*)points->[Link] + cvRandInt(&rng)%sample_count;
CvPoint2D32f temp;
CV_SWAP( *pt1, *pt2, temp );
}

cvKMeans2( points, cluster_count, clusters,

cvTermCriteria( CV_TERMCRIT_EPS+CV_TERMCRIT_ITER, 10, 1.0 ));

cvZero( img );

for( i = 0; i < sample_count; i++ )

{
CvPoint2D32f pt = ((CvPoint2D32f*)points->[Link])[i];
int cluster_idx = clusters->data.i[i];
1.6. CLUSTERING 233

cvCircle( img,
cvPointFrom32f(pt),
2,
color_tab[cluster_idx],
CV_FILLED );
}

cvReleaseMat( &points );
cvReleaseMat( &clusters );

cvShowImage( "clusters", img );

int key = cvWaitKey(0);

if( key == 27 )
break;
}
}

cvSeqPartition (view/add comments)

Splits a sequence into equivalency classes.

int cvSeqPartition(
const CvSeq* seq,
CvMemStorage* storage,
CvSeq** labels,
CvCmpFunc is equal,
void* userdata );

seq The sequence to partition

storage The storage block to store the sequence of equivalency classes. If it is NULL, the
function uses seq->storage for output labels
labels Ouput parameter. Double pointer to the sequence of 0-based labels of input sequence
elements
is equal The relation function that should return non-zero if the two particular sequence ele-
ments are from the same class, and zero otherwise. The partitioning algorithm uses transi-
tive closure of the relation function as an equivalency critria
234 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

userdata Pointer that is transparently passed to the is equal function

typedef int (CV_CDECL* CvCmpFunc)(const void* a, const void* b, void* userdata);

The function cvSeqPartition implements a quadratic algorithm for splitting a set into one
or more equivalancy classes. The function returns the number of equivalency classes.

#include "cxcore.h"
#include "highgui.h"
#include <stdio.h>

CvSeq* point_seq = 0;
IplImage* canvas = 0;
CvScalar* colors = 0;
int pos = 10;

int is_equal( const void* _a, const void* _b, void* userdata )
{
CvPoint a = *(const CvPoint*)_a;
CvPoint b = *(const CvPoint*)_b;
double threshold = *(double*)userdata;
return (double)((a.x - b.x)*(a.x - b.x) + (a.y - b.y)*(a.y - b.y)) <=
threshold;
}

void on_track( int pos )

{
CvSeq* labels = 0;
double threshold = pos*pos;
int i, class_count = cvSeqPartition( point_seq,
0,
&labels,
is_equal,
&threshold );
printf("%4d classes\n", class_count );
cvZero( canvas );

for( i = 0; i < labels->total; i++ )

{
CvPoint pt = *(CvPoint*)cvGetSeqElem( point_seq, i );
CvScalar color = colors[*(int*)cvGetSeqElem( labels, i )];
cvCircle( canvas, pt, 1, color, -1 );
}
1.7. UTILITY AND SYSTEM FUNCTIONS AND MACROS 235

cvShowImage( "points", canvas );

}

int main( int argc, char** argv )

{
CvMemStorage* storage = cvCreateMemStorage(0);
point_seq = cvCreateSeq( CV_32SC2,
sizeof(CvSeq),
sizeof(CvPoint),
storage );
CvRNG rng = cvRNG(0xffffffff);

int width = 500, height = 500;

int i, count = 1000;
canvas = cvCreateImage( cvSize(width,height), 8, 3 );

colors = (CvScalar*)cvAlloc( count*sizeof(colors[0]) );

for( i = 0; i < count; i++ )
{
CvPoint pt;
int icolor;
pt.x = cvRandInt( &rng ) % width;
pt.y = cvRandInt( &rng ) % height;
cvSeqPush( point_seq, &pt );
icolor = cvRandInt( &rng ) | 0x00404040;
colors[i] = CV_RGB(icolor & 255,
(icolor >> 8)&255,
(icolor >> 16)&255);
}

cvNamedWindow( "points", 1 );
cvCreateTrackbar( "threshold", "points", &pos, 50, on_track );
on_track(pos);
cvWaitKey(0);
return 0;
}

1.7 Utility and System Functions and Macros

Error Handling
Error handling in OpenCV is similar to IPL (Image Processing Library). In the case of an error,
functions do not return the error code. Instead, they raise an error using CV ERROR macro that
236 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

calls cvError that, in its turn, sets the error status with cvSetErrStatus and calls a standard or user-
defined error handler (that can display a message box, write to log, etc., see cvRedirectError).
There is a global variable, one per each program thread, that contains current error status (an
integer value). The status can be retrieved with the cvGetErrStatus function.
There are three modes of error handling (see cvSetErrMode and cvGetErrMode):

• Leaf. The program is terminated after the error handler is called. This is the default value.
It is useful for debugging, as the error is signalled immediately after it occurs. However, for
production systems, other two methods may be preferable as they provide more control.

• Parent. The program is not terminated, but the error handler is called. The stack is unwound
(it is done w/o using a C++ exception mechanism). The user may check error code after
calling the CxCore function with cvGetErrStatus and react.

• Silent. Similar to Parent mode, but no error handler is called.

Actually, the semantics of the Leaf and Parent modes are implemented by error handlers
and the above description is true for them. cvGuiBoxReport behaves slightly differently, and
some custom error handlers may implement quite different semantics.
Macros for raising an error, checking for errors, etc.

/* special macros for enclosing processing statements within a function and separating
them from prologue (resource initialization) and epilogue (guaranteed resource release)
#define __BEGIN__ {
#define __END__ goto exit; exit: ; }
/* proceeds to "resource release" stage */
#define EXIT goto exit

/* Declares locally the function name for CV_ERROR() use */

#define CV_FUNCNAME( Name ) \
static char cvFuncName[] = Name

/* Raises an error within the current context */

#define CV_ERROR( Code, Msg ) \
{ \
cvError( (Code), cvFuncName, Msg, __FILE__, __LINE__ ); \
EXIT; \
}

/* Checks status after calling CXCORE function */

#define CV_CHECK() \
{ \
if( cvGetErrStatus() < 0 ) \
1.7. UTILITY AND SYSTEM FUNCTIONS AND MACROS 237

CV_ERROR( CV_StsBackTrace, "Inner function failed." ); \

}

/* Provies shorthand for CXCORE function call and CV_CHECK() */

#define CV_CALL( Statement ) \
{ \
Statement; \
CV_CHECK(); \
}

/* Checks some condition in both debug and release configurations */

#define CV_ASSERT( Condition ) \
{ \
if( !(Condition) ) \
CV_ERROR( CV_StsInternal, "Assertion: " #Condition " failed" ); \
}

/* these macros are similar to their CV_... counterparts, but they

do not need exit label nor cvFuncName to be defined */
#define OPENCV_ERROR(status,func_name,err_msg) ...
#define OPENCV_ERRCHK(func_name,err_msg) ...
#define OPENCV_ASSERT(condition,func_name,err_msg) ...
#define OPENCV_CALL(statement) ...

Instead of a discussion, below is a documented example of a typical CXCORE function and an

example of the function use.

Example: Use of Error Handling Macros

#include "cxcore.h"
#include <stdio.h>

void cvResizeDCT( CvMat* input_array, CvMat* output_array )

{
CvMat* temp_array = 0; // declare pointer that should be released anyway.

CV_FUNCNAME( "cvResizeDCT" ); // declare cvFuncName

__BEGIN__; // start processing. There may be some declarations just after

// this macro, but they could not be accessed from the epilogue.

if( !CV_IS_MAT(input_array) || !CV_IS_MAT(output_array) )

// use CV_ERROR() to raise an error
238 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

CV_ERROR( CV_StsBadArg,
"input_array or output_array are not valid matrices" );

// some restrictions that are going to be removed later, may be checked

// with CV_ASSERT()
CV_ASSERT( input_array->rows == 1 && output_array->rows == 1 );

// use CV_CALL for safe function call

CV_CALL( temp_array = cvCreateMat( input_array->rows,
MAX(input_array->cols,
output_array->cols),
input_array->type ));

if( output_array->cols > input_array->cols )

CV_CALL( cvZero( temp_array ));

temp_array->cols = input_array->cols;
CV_CALL( cvDCT( input_array, temp_array, CV_DXT_FORWARD ));
temp_array->cols = output_array->cols;
CV_CALL( cvDCT( temp_array, output_array, CV_DXT_INVERSE ));
CV_CALL( cvScale( output_array,
output_array,
1./sqrt((double)input_array->cols*output_array->cols), 0 ));

__END__; // finish processing. Epilogue follows after the macro.

// release temp_array. If temp_array has not been allocated

// before an error occured, cvReleaseMat
// takes care of it and does nothing in this case.
cvReleaseMat( &temp_array );
}

int main( int argc, char** argv )

{
CvMat* src = cvCreateMat( 1, 512, CV_32F );
#if 1 /* no errors */
CvMat* dst = cvCreateMat( 1, 256, CV_32F );
#else
CvMat* dst = 0; /* test error processing mechanism */
#endif
cvSet( src, cvRealScalar(1.), 0 );
#if 0 /* change 0 to 1 to suppress error handler invocation */
cvSetErrMode( CV_ErrModeSilent );
#endif
cvResizeDCT( src, dst ); // if some error occurs, the message
1.7. UTILITY AND SYSTEM FUNCTIONS AND MACROS 239

// box will popup, or a message will be

// written to log, or some user-defined
// processing will be done
if( cvGetErrStatus() < 0 )
printf("Some error occured" );
else
printf("Everything is OK" );
return 0;
}

cvGetErrStatus (view/add comments)

Returns the current error status.

int cvGetErrStatus( void );

The function returns the current error status - the value set with the last cvSetErrStatus call.
Note that in Leaf mode, the program terminates immediately after an error occurs, so to always
gain control after the function call, one should call cvSetErrMode and set the Parent or Silent
error mode.

cvSetErrStatus (view/add comments)

Sets the error status.

void cvSetErrStatus( int status );

status The error status

The function sets the error status to the specified value. Mostly, the function is used to reset
the error status (set to it CV StsOk) to recover after an error. In other cases it is more natural to
call cvError or CV ERROR.

cvGetErrMode (view/add comments)

Returns the current error mode.
240 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

int cvGetErrMode(void);

The function returns the current error mode - the value set with the last cvSetErrMode call.

cvSetErrMode (view/add comments)

Sets the error mode.
#define CV_ErrModeLeaf 0
#define CV_ErrModeParent 1
#define CV_ErrModeSilent 2

int cvSetErrMode( int mode );

mode The error mode

The function sets the specified error mode. For descriptions of different error modes, see the
beginning of the error section.

cvError (view/add comments)

Raises an error.

int cvError(
int status,
const char* func name,
const char* err msg,
const char* filename,
int line );

status The error status

func name Name of the function where the error occured

1.7. UTILITY AND SYSTEM FUNCTIONS AND MACROS 241

err msg Additional information/diagnostics about the error

filename Name of the file where the error occured

line Line number, where the error occured

The function sets the error status to the specified value (via cvSetErrStatus) and, if the error
mode is not Silent, calls the error handler.

cvErrorStr (view/add comments)

Returns textual description of an error status code.

const char* cvErrorStr( int status );

status The error status

The function returns the textual description for the specified error status code. In the case of
unknown status, the function returns a NULL pointer.

cvRedirectError (view/add comments)

Sets a new error handler.

CvErrorCallback cvRedirectError(
CvErrorCallback error handler,
void* userdata=NULL,
void** prevUserdata=NULL );

error handler The new error handler

userdata Arbitrary pointer that is transparently passed to the error handler

prevUserdata Pointer to the previously assigned user data pointer

242 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

typedef int (CV_CDECL *CvErrorCallback)( int status, const char* func_name,

const char* err_msg, const char* file_name, int line );

The function sets a new error handler that can be one of the standard handlers or a custom
handler that has a specific interface. The handler takes the same parameters as the cvError
function. If the handler returns a non-zero value, the program is terminated; otherwise, it continues.
The error handler may check the current error mode with cvGetErrMode to make a decision.

cvNulDevReport cvStdErrReport cvGuiBoxReport (view/add comments)

Provide standard error handling.

int cvNulDevReport( int status, const char* func name, const char*
err msg, const char* file name, int line, void* userdata );

int cvStdErrReport( int status, const char* func name, const

char* err msg, const char* file name, int line, void* userdata );

int cvGuiBoxReport( int status, const char* func name, const

char* err msg, const char* file name, int line, void* userdata );

status The error status

func name Name of the function where the error occured

err msg Additional information/diagnostics about the error

filename Name of the file where the error occured

line Line number, where the error occured

userdata Pointer to the user data. Ignored by the standard handlers

The functions cvNullDevReport, cvStdErrReport, and cvGuiBoxReport provide stan-

dard error handling. cvGuiBoxReport is the default error handler on Win32 systems, cvStdErrReport
is the default on other systems. cvGuiBoxReport pops up a message box with the error descrip-
tion and suggest a few options. Below is an example message box that may be recieved with the
sample code above, if one introduces an error as described in the sample.
1.7. UTILITY AND SYSTEM FUNCTIONS AND MACROS 243

Error Message Box

If the error handler is set to cvStdErrReport, the above message will be printed to standard
error output and the program will be terminated or continued, depending on the current error mode.
Error Message printed to Standard Error Output (in Leaf mode)
OpenCV ERROR: Bad argument (input_array or output_array are not valid matrices)
in function cvResizeDCT, D:\User\VP\Projects\avl\_proba\[Link](75)
Terminating the application...

cvAlloc (view/add comments)

Allocates a memory buffer.

void* cvAlloc( size t size );

size Buffer size in bytes

The function allocates size bytes and returns a pointer to the allocated buffer. In the case
of an error the function reports an error and returns a NULL pointer. By default, cvAlloc calls
icvAlloc which itself calls malloc. However it is possible to assign user-defined memory allo-
cation/deallocation functions using the cvSetMemoryManager function.

cvFree (view/add comments)

Deallocates a memory buffer.

void cvFree( void** ptr );

244 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

ptr Double pointer to released buffer

The function deallocates a memory buffer allocated by cvAlloc. It clears the pointer to buffer
upon exit, which is why the double pointer is used. If the *buffer is already NULL, the function
does nothing.

cvGetTickCount (view/add comments)

Returns the number of ticks.

int64 cvGetTickCount( void );

The function returns number of the ticks starting from some platform-dependent event (number
of CPU ticks from the startup, number of milliseconds from 1970th year, etc.). The function is useful
for accurate measurement of a function/user-code execution time. To convert the number of ticks
to time units, use cvGetTickFrequency.

cvGetTickFrequency (view/add comments)

Returns the number of ticks per microsecond.

double cvGetTickFrequency( void );

The function returns the number of ticks per microsecond. Thus, the quotient of cvGetTick-
Count and cvGetTickFrequency will give the number of microseconds starting from the platform-
dependent event.

cvRegisterModule (view/add comments)

Registers another module.
typedef struct CvPluginFuncInfo
{
void** func_addr;
void* default_func_addr;
const char* func_names;
1.7. UTILITY AND SYSTEM FUNCTIONS AND MACROS 245

int search_modules;
int loaded_from;
}
CvPluginFuncInfo;

typedef struct CvModuleInfo

{
struct CvModuleInfo* next;
const char* name;
const char* version;
CvPluginFuncInfo* func_tab;
}
CvModuleInfo;

int cvRegisterModule( const CvModuleInfo* moduleInfo );

moduleInfo Information about the module

The function adds a module to the list of registered modules. After the module is registered,
information about it can be retrieved using the cvGetModuleInfo function. Also, the registered
module makes full use of optimized plugins (IPP, MKL, ...), supported by CXCORE. CXCORE it-
self, CV (computer vision), CVAUX (auxilary computer vision), and HIGHGUI (visualization and
image/video acquisition) are examples of modules. Registration is usually done when the shared
library is loaded. See cxcore/src/[Link] and cv/src/[Link] for de-
tails about how registration is done and look at cxcore/src/[Link], cxcore/src/ cxipp.h
on how IPP and MKL are connected to the modules.

cvGetModuleInfo (view/add comments)

Retrieves information about registered module(s) and plugins.

void cvGetModuleInfo(
const char* moduleName,
const char** version,
const char** loadedAddonPlugins);
246 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

moduleName Name of the module of interest, or NULL, which means all the modules
version The output parameter. Information about the module(s), including version
loadedAddonPlugins The list of names and versions of the optimized plugins that CXCORE
was able to find and load
The function returns information about one or all of the registered modules. The returned
information is stored inside the libraries, so the user should not deallocate or modify the returned
text strings.

cvUseOptimized (view/add comments)

Switches between optimized/non-optimized modes.

int cvUseOptimized( int onoff );

onoff Use optimized (6= 0) or not (= 0)

The function switches between the mode, where only pure C implementations from cxcore,
OpenCV, etc. are used, and the mode, where IPP and MKL functions are used if available. When
cvUseOptimized(0) is called, all the optimized libraries are unloaded. The function may be
useful for debugging, IPP and MKL upgrading on the fly, online speed comparisons, etc. It returns
the number of optimized functions loaded. Note that by default, the optimized plugins are loaded,
so it is not necessary to call cvUseOptimized(1) in the beginning of the program (actually, it
will only increase the startup time).

cvSetMemoryManager (view/add comments)

Accesses custom/default memory managing functions.
typedef void* (CV_CDECL *CvAllocFunc)(size_t size, void* userdata);
typedef int (CV_CDECL *CvFreeFunc)(void* pptr, void* userdata);

void cvSetMemoryManager(
CvAllocFunc allocFunc=NULL,
CvFreeFunc freeFunc=NULL,
void* userdata=NULL );
1.7. UTILITY AND SYSTEM FUNCTIONS AND MACROS 247

allocFunc Allocation function; the interface is similar to malloc, except that userdata may be
used to determine the context

freeFunc Deallocation function; the interface is similar to free

userdata User data that is transparently passed to the custom functions

The function sets user-defined memory managment functions (substitutes for malloc and
free) that will be called by cvAlloc, cvFree and higher-level functions (e.g., cvCreateImage).
Note that the function should be called when there is data allocated using cvAlloc. Also, to
avoid infinite recursive calls, it is not allowed to call cvAlloc and cvFree from the custom alloca-
tion/deallocation functions.
If the alloc func and free func pointers are NULL, the default memory managing functions
are restored.

cvSetIPLAllocators (view/add comments)

Switches to IPL functions for image allocation/deallocation.
typedef IplImage* (CV_STDCALL* Cv_iplCreateImageHeader)
(int,int,int,char*,char*,int,int,int,int,int,
IplROI*,IplImage*,void*,IplTileInfo*);
typedef void (CV_STDCALL* Cv_iplAllocateImageData)(IplImage*,int,int);
typedef void (CV_STDCALL* Cv_iplDeallocate)(IplImage*,int);
typedef IplROI* (CV_STDCALL* Cv_iplCreateROI)(int,int,int,int,int);
typedef IplImage* (CV_STDCALL* Cv_iplCloneImage)(const IplImage*);

#define CV_TURN_ON_IPL_COMPATIBILITY() \
cvSetIPLAllocators( iplCreateImageHeader, iplAllocateImage, \
iplDeallocate, iplCreateROI, iplCloneImage )

void cvSetIPLAllocators(
Cv iplCreateImageHeader create header,
Cv iplAllocateImageData allocate data,
Cv iplDeallocate deallocate,
Cv iplCreateROI create roi,
Cv iplCloneImage clone image );

create header Pointer to iplCreateImageHeader

248 CHAPTER 1. CORE. THE CORE FUNCTIONALITY

allocate data Pointer to iplAllocateImage

deallocate Pointer to iplDeallocate

create roi Pointer to iplCreateROI

clone image Pointer to iplCloneImage

The function causes CXCORE to use IPL functions for image allocation/deallocation opera-
tions. For convenience, there is the wrapping macro CV TURN ON IPL COMPATIBILITY. The
function is useful for applications where IPL and CXCORE/OpenCV are used together and still
there are calls to iplCreateImageHeader, etc. The function is not necessary if IPL is called
only for data processing and all the allocation/deallocation is done by CXCORE, or if all the allo-
cation/deallocation is done by IPL and some of OpenCV functions are used to process the data.
Chapter 2

imgproc. Image Processing

2.1 Histograms

CvHistogram (view/add comments)

Multi-dimensional histogram.
typedef struct CvHistogram
{
int type;
CvArr* bins;
float thresh[CV_MAX_DIM][2]; /* for uniform histograms */
float** thresh2; /* for non-uniform histograms */
CvMatND mat; /* embedded matrix header for array histograms */
}
CvHistogram;

cvCalcBackProject (view/add comments)

Calculates the back projection.

void cvCalcBackProject(
IplImage** image,
CvArr* back project,
const CvHistogram* hist );

249
250 CHAPTER 2. IMGPROC. IMAGE PROCESSING

image Source images (though you may pass CvMat** as well)

back project Destination back projection image of the same type as the source images

hist Histogram

The function calculates the back project of the histogram. For each tuple of pixels at the
same position of all input single-channel images the function puts the value of the histogram bin,
corresponding to the tuple in the destination image. In terms of statistics, the value of each output
image pixel is the probability of the observed tuple given the distribution (histogram). For example,
to find a red object in the picture, one may do the following:

1. Calculate a hue histogram for the red object assuming the image contains only this object.
The histogram is likely to have a strong maximum, corresponding to red color.

2. Calculate back projection of a hue plane of input image where the object is searched, using
the histogram. Threshold the image.

3. Find connected components in the resulting picture and choose the right component using
some additional criteria, for example, the largest connected component.

That is the approximate algorithm of Camshift color object tracker, except for the 3rd step,
instead of which CAMSHIFT algorithm is used to locate the object on the back projection given
the previous object position.

cvCalcBackProjectPatch (view/add comments)

Locates a template within an image by using a histogram comparison.

void cvCalcBackProjectPatch(
IplImage** images,
CvArr* dst,
CvSize patch size,
CvHistogram* hist,
int method,
double factor );

images Source images (though, you may pass CvMat** as well)

2.1. HISTOGRAMS 251

dst Destination image

patch size Size of the patch slid though the source image

hist Histogram

method Comparison method, passed to cvCompareHist (see description of that function)

factor Normalization factor for histograms, will affect the normalization scale of the destination
image, pass 1 if unsure

The function calculates the back projection by comparing histograms of the source image
patches with the given histogram. Taking measurement results from some image at each location
over ROI creates an array image. These results might be one or more of hue, x derivative, y
derivative, Laplacian filter, oriented Gabor filter, etc. Each measurement output is collected into
its own separate image. The image image array is a collection of these measurement images. A
multi-dimensional histogram hist is constructed by sampling from the image image array. The
final histogram is normalized. The hist histogram has as many dimensions as the number of
elements in image array.
Each new image is measured and then converted into an image image array over a cho-
sen ROI. Histograms are taken from this image image in an area covered by a ”patch” with an
anchor at center as shown in the picture below. The histogram is normalized using the param-
eter norm factor so that it may be compared with hist. The calculated histogram is com-
pared to the model histogram; hist uses The function cvCompareHist with the comparison
method=method). The resulting output is placed at the location corresponding to the patch an-
chor in the probability image dst. This process is repeated as the patch is slid over the ROI.
Iterative histogram update by subtracting trailing pixels covered by the patch and adding newly
covered pixels to the histogram can save a lot of operations, though it is not implemented yet.
Back Project Calculation by Patches
252 CHAPTER 2. IMGPROC. IMAGE PROCESSING

cvCalcHist (view/add comments)

Calculates the histogram of image(s).

void cvCalcHist(
IplImage** image,
CvHistogram* hist,
int accumulate=0,
const CvArr* mask=NULL );

image Source images (though you may pass CvMat** as well)

hist Pointer to the histogram

accumulate Accumulation flag. If it is set, the histogram is not cleared in the beginning. This
feature allows user to compute a single histogram from several images, or to update the
histogram online

mask The operation mask, determines what pixels of the source images are counted

The function calculates the histogram of one or more single-channel images. The elements
of a tuple that is used to increment a histogram bin are taken at the same location from the
corresponding input images.
#include <cv.h>
#include <highgui.h>

int main( int argc, char** argv )

{
IplImage* src;
if( argc == 2 && (src=cvLoadImage(argv[1], 1))!= 0)
{
IplImage* h_plane = cvCreateImage( cvGetSize(src), 8, 1 );
IplImage* s_plane = cvCreateImage( cvGetSize(src), 8, 1 );
IplImage* v_plane = cvCreateImage( cvGetSize(src), 8, 1 );
IplImage* planes[] = { h_plane, s_plane };
IplImage* hsv = cvCreateImage( cvGetSize(src), 8, 3 );
int h_bins = 30, s_bins = 32;
int hist_size[] = {h_bins, s_bins};
/* hue varies from 0 (˜0 deg red) to 180 (˜360 deg red again) */
float h_ranges[] = { 0, 180 };
2.1. HISTOGRAMS 253

/* saturation varies from 0 (black-gray-white) to

255 (pure spectrum color) */
float s_ranges[] = { 0, 255 };
float* ranges[] = { h_ranges, s_ranges };
int scale = 10;
IplImage* hist_img =
cvCreateImage( cvSize(h_bins*scale,s_bins*scale), 8, 3 );
CvHistogram* hist;
float max_value = 0;
int h, s;

cvCvtColor( src, hsv, CV_BGR2HSV );

cvCvtPixToPlane( hsv, h_plane, s_plane, v_plane, 0 );
hist = cvCreateHist( 2, hist_size, CV_HIST_ARRAY, ranges, 1 );
cvCalcHist( planes, hist, 0, 0 );
cvGetMinMaxHistValue( hist, 0, &max_value, 0, 0 );
cvZero( hist_img );

for( h = 0; h < h_bins; h++ )

{
for( s = 0; s < s_bins; s++ )
{
float bin_val = cvQueryHistValue\_2D( hist, h, s );
int intensity = cvRound(bin_val*255/max_value);
cvRectangle( hist_img, cvPoint( h*scale, s*scale ),
cvPoint( (h+1)*scale - 1, (s+1)*scale - 1),
CV_RGB(intensity,intensity,intensity),
CV_FILLED );
}
}

cvNamedWindow( "Source", 1 );
cvShowImage( "Source", src );

cvNamedWindow( "H-S Histogram", 1 );

cvShowImage( "H-S Histogram", hist_img );

cvWaitKey(0);
}
}

cvCalcProbDensity (view/add comments)

Divides one histogram by another.
254 CHAPTER 2. IMGPROC. IMAGE PROCESSING

void cvCalcProbDensity(
const CvHistogram* hist1,
const CvHistogram* hist2,
CvHistogram* dst hist,
double scale=255 );

hist1 first histogram (the divisor)

hist2 second histogram

dst hist destination histogram

scale scale factor for the destination histogram

The function calculates the object probability density from the two histograms as:

 0
 if hist1(I) = 0
dist hist(I) = scale if hist1(I) 6= 0 and hist2(I) > hist1(I)
 hist2(I)·scale

if hist1(I) 6= 0 and hist2(I) ≤ hist1(I)
hist1(I)

So the destination histogram bins are within less than scale.

cvClearHist (view/add comments)

Clears the histogram.

void cvClearHist( CvHistogram* hist );

hist Histogram

The function sets all of the histogram bins to 0 in the case of a dense histogram and removes
all histogram bins in the case of a sparse array.
2.1. HISTOGRAMS 255

cvCompareHist (view/add comments)

Compares two dense histograms.

double cvCompareHist(
const CvHistogram* hist1,
const CvHistogram* hist2,
int method );

hist1 The first dense histogram

hist2 The second dense histogram

method Comparison method, one of the following:

CV COMP CORREL Correlation

CV COMP CHISQR Chi-Square
CV COMP INTERSECT Intersection
CV COMP BHATTACHARYYA Bhattacharyya distance

The function compares two dense histograms using the specified method (H1 denotes the first
histogram, H2 the second):

Correlation (method=CV COMP CORREL)

0 0
P
I (H1 (I) · H2 (I))
d(H1 , H2 ) = pP 0 0
2 2
P
I (H1 (I) ) · I (H2 (I) )

where
Hk (I) − 1
Hk0 (I) = P
N · J Hk (J)
where N is the number of histogram bins.

Chi-Square (method=CV COMP CHISQR)

X (H1 (I) − H2 (I))2
d(H1 , H2 ) =
H1 (I) + H2 (I)
I
256 CHAPTER 2. IMGPROC. IMAGE PROCESSING

Intersection (method=CV COMP INTERSECT)

X
d(H1 , H2 ) = min(H1 (I), H2 (I))
I

Bhattacharyya distance (method=CV COMP BHATTACHARYYA)

v p
u
u X H1 (I) · H2 (I)
d(H1 , H2 ) = t1 − pP P
I I H1 (I) · I H2 (I)

The function returns d(H1 , H2 ).

Note: the method CV COMP BHATTACHARYYA only works with normalized histograms.
To compare a sparse histogram or more general sparse configurations of weighted points,
consider using the cvCalcEMD2 function.

cvCopyHist (view/add comments)

Copies a histogram.

void cvCopyHist( const CvHistogram* src, CvHistogram** dst );

src Source histogram

dst Pointer to destination histogram

The function makes a copy of the histogram. If the second histogram pointer *dst is NULL, a
new histogram of the same size as src is created. Otherwise, both histograms must have equal
types and sizes. Then the function copies the source histogram’s bin values to the destination
histogram and sets the same bin value ranges as in src.

cvCreateHist (view/add comments)

Creates a histogram.
2.1. HISTOGRAMS 257

CvHistogram* cvCreateHist(
int dims,
int* sizes,
int type,
float** ranges=NULL,
int uniform=1 );

dims Number of histogram dimensions

sizes Array of the histogram dimension sizes

type Histogram representation format: CV HIST ARRAY means that the histogram data is rep-
resented as a multi-dimensional dense array CvMatND; CV HIST SPARSE means that his-
togram data is represented as a multi-dimensional sparse array CvSparseMat

ranges Array of ranges for the histogram bins. Its meaning depends on the uniform param-
eter value. The ranges are used for when the histogram is calculated or backprojected to
determine which histogram bin corresponds to which value/tuple of values from the input
image(s)

uniform Uniformity flag; if not 0, the histogram has evenly spaced bins and for every 0 <= i <
cDims ranges[i] is an array of two numbers: lower and upper boundaries for the i-th his-
togram dimension. The whole range [lower,upper] is then split into dims[i] equal parts to
determine the i-th input tuple value ranges for every histogram bin. And if uniform=0,
then i-th element of ranges array contains dims[i]+1 elements: lower0 , upper0 , lower1 , upper1 =
lower2 , ...upperdims[i]−1 where lowerj and upperj are lower and upper boundaries of
i-th input tuple value for j-th bin, respectively. In either case, the input values that are
beyond the specified range for a histogram bin are not counted by cvCalcHist and filled with
0 by cvCalcBackProject

The function creates a histogram of the specified size and returns a pointer to the created
histogram. If the array ranges is 0, the histogram bin ranges must be specified later via the
function cvSetHistBinRanges. Though cvCalcHist and cvCalcBackProject may process 8-bit
images without setting bin ranges, they assume thy are equally spaced in 0 to 255 bins.

cvGetHistValue*D (view/add comments)

Returns a pointer to the histogram bin.
258 CHAPTER 2. IMGPROC. IMAGE PROCESSING

float cvGetHistValue 1D(hist, idx0)

float cvGetHistValue 2D(hist, idx0, idx1)
float cvGetHistValue 3D(hist, idx0, idx1, idx2)
float cvGetHistValue nD(hist, idx)

hist Histogram

idx0, idx1, idx2, idx3 Indices of the bin

idx Array of indices

#define cvGetHistValue_1D( hist, idx0 )

((float*)(cvPtr1D( (hist)->bins, (idx0), 0 ))
#define cvGetHistValue_2D( hist, idx0, idx1 )
((float*)(cvPtr2D( (hist)->bins, (idx0), (idx1), 0 )))
#define cvGetHistValue_3D( hist, idx0, idx1, idx2 )
((float*)(cvPtr3D( (hist)->bins, (idx0), (idx1), (idx2), 0 )))
#define cvGetHistValue_nD( hist, idx )
((float*)(cvPtrND( (hist)->bins, (idx), 0 )))

The macros GetHistValue return a pointer to the specified bin of the 1D, 2D, 3D or N-D
histogram. In the case of a sparse histogram the function creates a new bin and sets it to 0,
unless it exists already.

cvGetMinMaxHistValue (view/add comments)

Finds the minimum and maximum histogram bins.

void cvGetMinMaxHistValue(
const CvHistogram* hist,
float* min value,
float* max value,
int* min idx=NULL,
int* max idx=NULL );
2.1. HISTOGRAMS 259

hist Histogram
min value Pointer to the minimum value of the histogram
max value Pointer to the maximum value of the histogram
min idx Pointer to the array of coordinates for the minimum
max idx Pointer to the array of coordinates for the maximum

The function finds the minimum and maximum histogram bins and their positions. All of output
arguments are optional. Among several extremas with the same value the ones with the minimum
index (in lexicographical order) are returned. In the case of several maximums or minimums, the
earliest in lexicographical order (extrema locations) is returned.

cvMakeHistHeaderForArray (view/add comments)

Makes a histogram out of an array.

CvHistogram* cvMakeHistHeaderForArray(
int dims,
int* sizes,
CvHistogram* hist,
float* data,
float** ranges=NULL,
int uniform=1 );

dims Number of histogram dimensions

sizes Array of the histogram dimension sizes
hist The histogram header initialized by the function
data Array that will be used to store histogram bins
ranges Histogram bin ranges, see cvCreateHist
uniform Uniformity flag, see cvCreateHist

The function initializes the histogram, whose header and bins are allocated by th user. cvRe-
leaseHist does not need to be called afterwards. Only dense histograms can be initialized this
way. The function returns hist.
260 CHAPTER 2. IMGPROC. IMAGE PROCESSING

cvNormalizeHist (view/add comments)

Normalizes the histogram.

void cvNormalizeHist( CvHistogram* hist, double factor );

hist Pointer to the histogram

factor Normalization factor

The function normalizes the histogram bins by scaling them, such that the sum of the bins
becomes equal to factor.

cvQueryHistValue*D (view/add comments)

Queries the value of the histogram bin.

float QueryHistValue 1D(CvHistogram hist, int idx0)

hist Histogram

idx0, idx1, idx2, idx3 Indices of the bin

idx Array of indices

#define cvQueryHistValue\_1D( hist, idx0 ) \

cvGetReal1D( (hist)->bins, (idx0) )
#define cvQueryHistValue\_2D( hist, idx0, idx1 ) \
cvGetReal2D( (hist)->bins, (idx0), (idx1) )
#define cvQueryHistValue\_3D( hist, idx0, idx1, idx2 ) \
cvGetReal3D( (hist)->bins, (idx0), (idx1), (idx2) )
#define cvQueryHistValue\_nD( hist, idx ) \
cvGetRealND( (hist)->bins, (idx) )
The macros return the value of the specified bin of the 1D, 2D, 3D or N-D histogram. In the
case of a sparse histogram the function returns 0, if the bin is not present in the histogram no new
bin is created.
2.1. HISTOGRAMS 261

cvReleaseHist (view/add comments)

Releases the histogram.

void cvReleaseHist( CvHistogram** hist );

hist Double pointer to the released histogram

The function releases the histogram (header and the data). The pointer to the histogram is
cleared by the function. If *hist pointer is already NULL, the function does nothing.

cvSetHistBinRanges (view/add comments)

Sets the bounds of the histogram bins.

void cvSetHistBinRanges(
CvHistogram* hist,
float** ranges,
int uniform=1 );

hist Histogram

ranges Array of bin ranges arrays, see cvCreateHist

uniform Uniformity flag, see cvCreateHist

The function is a stand-alone function for setting bin ranges in the histogram. For a more
detailed description of the parameters ranges and uniform see the cvCalcHist function, that
can initialize the ranges as well. Ranges for the histogram bins must be set before the histogram
is calculated or the backproject of the histogram is calculated.

cvThreshHist (view/add comments)

Thresholds the histogram.
262 CHAPTER 2. IMGPROC. IMAGE PROCESSING

void cvThreshHist( CvHistogram* hist, double threshold );

hist Pointer to the histogram

threshold Threshold level

The function clears histogram bins that are below the specified threshold.

2.2 Image Filtering

Functions and classes described in this section are used to perform various linear or non-linear
filtering operations on 2D images (represented as cv’s), that is, for each pixel location (x, y) in the
source image some its (normally rectangular) neighborhood is considered and used to compute
the response. In case of a linear filter it is a weighted sum of pixel values, in case of morphological
operations it is the minimum or maximum etc. The computed response is stored to the destination
image at the same location (x, y). It means, that the output image will be of the same size as the
input image. Normally, the functions supports multi-channel arrays, in which case every channel is
processed independently, therefore the output image will also have the same number of channels
as the input one.
Another common feature of the functions and classes described in this section is that, unlike
simple arithmetic functions, they need to extrapolate values of some non-existing pixels. For ex-
ample, if we want to smooth an image using a Gaussian 3 × 3 filter, then during the processing of
the left-most pixels in each row we need pixels to the left of them, i.e. outside of the image. We
can let those pixels be the same as the left-most image pixels (i.e. use ”replicated border” extrapo-
lation method), or assume that all the non-existing pixels are zeros (”contant border” extrapolation
method) etc.

IplConvKernel (view/add comments)

An IplConvKernel is a rectangular convolution kernel, created by function CreateStructuringEle-
mentEx .

cvCopyMakeBorder (view/add comments)

Copies an image and makes a border around it.
2.2. IMAGE FILTERING 263

void cvCopyMakeBorder(
const CvArr* src,
CvArr* dst,
CvPoint offset,
int bordertype,
CvScalar value=cvScalarAll(0) );

src The source image

dst The destination image

offset Coordinates of the top-left corner (or bottom-left in the case of images with bottom-left
origin) of the destination image rectangle where the source image (or its ROI) is copied. Size
of the rectanlge matches the source image size/ROI size

bordertype Type of the border to create around the copied source image rectangle; types in-
clude:

IPL BORDER CONSTANT border is filled with the fixed value, passed as last parameter of
the function.
IPL BORDER REPLICATE the pixels from the top and bottom rows, the left-most and right-
most columns are replicated to fill the border.

(The other two border types from IPL, IPL BORDER REFLECT and IPL BORDER WRAP, are
currently unsupported)

value Value of the border pixels if bordertype is IPL BORDER CONSTANT

The function copies the source 2D array into the interior of the destination array and makes
a border of the specified type around the copied area. The function is useful when one needs to
emulate border type that is different from the one embedded into a specific algorithm implementa-
tion. For example, morphological functions, as well as most of other filtering functions in OpenCV,
internally use replication border type, while the user may need a zero border or a border, filled with
1’s or 255’s.

cvCreateStructuringElementEx (view/add comments)

Creates a structuring element.
264 CHAPTER 2. IMGPROC. IMAGE PROCESSING

IplConvKernel* cvCreateStructuringElementEx(
int cols,
int rows,
int anchorX,
int anchorY,
int shape,
int* values=NULL );

cols Number of columns in the structuring element

rows Number of rows in the structuring element

anchorX Relative horizontal offset of the anchor point

anchorY Relative vertical offset of the anchor point

shape Shape of the structuring element; may have the following values:

CV SHAPE RECT a rectangular element

CV SHAPE CROSS a cross-shaped element
CV SHAPE ELLIPSE an elliptic element
CV SHAPE CUSTOM a user-defined element. In this case the parameter values specifies
the mask, that is, which neighbors of the pixel must be considered

values Pointer to the structuring element data, a plane array, representing row-by-row scanning
of the element matrix. Non-zero values indicate points that belong to the element. If the
pointer is NULL, then all values are considered non-zero, that is, the element is of a rectan-
gular shape. This parameter is considered only if the shape is CV SHAPE CUSTOM

The function CreateStructuringElementEx allocates and fills the structure IplConvKernel,

which can be used as a structuring element in the morphological operations.

cvDilate (view/add comments)

Dilates an image by using a specific structuring element.
2.2. IMAGE FILTERING 265

void cvDilate(
const CvArr* src,
CvArr* dst,
IplConvKernel* element=NULL,
int iterations=1 );

src Source image

dst Destination image

element Structuring element used for dilation. If it is NULL, a 3 × 3 rectangular structuring

element is used

iterations Number of times dilation is applied

The function dilates the source image using the specified structuring element that determines
the shape of a pixel neighborhood over which the maximum is taken:

max src(x + x0 , y + y 0 )
(x0 ,y 0 ) in element

The function supports the in-place mode. Dilation can be applied several (iterations) times.
For color images, each channel is processed independently.

cvErode (view/add comments)

Erodes an image by using a specific structuring element.

void cvErode(
const CvArr* src,
CvArr* dst,
IplConvKernel* element=NULL,
int iterations=1);

src Source image

dst Destination image

266 CHAPTER 2. IMGPROC. IMAGE PROCESSING

element Structuring element used for erosion. If it is NULL, a 3 × 3 rectangular structuring

element is used

iterations Number of times erosion is applied

The function erodes the source image using the specified structuring element that determines
the shape of a pixel neighborhood over which the minimum is taken:

min src(x + x0 , y + y 0 )
(x0 ,y 0 ) in element

The function supports the in-place mode. Erosion can be applied several (iterations) times.
For color images, each channel is processed independently.

cvFilter2D (view/add comments)

Convolves an image with the kernel.

void cvFilter2D(
const CvArr* src,
CvArr* dst,
const CvMat* kernel,
CvPoint anchor=cvPoint(-1,-1));

src The source image

dst The destination image

kernel Convolution kernel, a single-channel floating point matrix. If you want to apply different
kernels to different channels, split the image into separate color planes using cvSplit and
process them individually

anchor The anchor of the kernel that indicates the relative position of a filtered point within the
kernel. The anchor shoud lie within the kernel. The special default value (-1,-1) means that
it is at the kernel center

The function applies an arbitrary linear filter to the image. In-place operation is supported.
When the aperture is partially outside the image, the function interpolates outlier pixel values from
the nearest pixels that are inside the image.
2.2. IMAGE FILTERING 267

cvLaplace (view/add comments)

Calculates the Laplacian of an image.

void cvLaplace(
const CvArr* src,
CvArr* dst,
int apertureSize=3);

src Source image

dst Destination image

apertureSize Aperture size (it has the same meaning as cvSobel)

The function calculates the Laplacian of the source image by adding up the second x and y
derivatives calculated using the Sobel operator:

d2 src d2 src
dst(x, y) = +
dx2 dy 2

Setting apertureSize = 1 gives the fastest variant that is equal to convolving the image with
the following kernel:
 
0 1 0
1 −4 1
0 1 0

Similar to the cvSobel function, no scaling is done and the same combinations of input and
output formats are supported.

cvMorphologyEx (view/add comments)

Performs advanced morphological transformations.
268 CHAPTER 2. IMGPROC. IMAGE PROCESSING

void cvMorphologyEx(
const CvArr* src,
CvArr* dst,
CvArr* temp,
IplConvKernel* element,
int operation,
int iterations=1 );

src Source image

dst Destination image

temp Temporary image, required in some cases

element Structuring element

operation Type of morphological operation, one of the following:

CV MOP OPEN opening

CV MOP CLOSE closing
CV MOP GRADIENT morphological gradient
CV MOP TOPHAT ”top hat”
CV MOP BLACKHAT ”black hat”

iterations Number of times erosion and dilation are applied

The function can perform advanced morphological transformations using erosion and dilation
as basic operations.
Opening:

dst = open(src, element) = dilate(erode(src, element), element)

Closing:

dst = close(src, element) = erode(dilate(src, element), element)

Morphological gradient:

dst = morph grad(src, element) = dilate(src, element) − erode(src, element)

2.2. IMAGE FILTERING 269

”Top hat”:

dst = tophat(src, element) = src − open(src, element)

”Black hat”:

dst = blackhat(src, element) = close(src, element) − src

The temporary image temp is required for a morphological gradient and, in the case of in-place
operation, for ”top hat” and ”black hat”.

cvPyrDown (view/add comments)

Downsamples an image.

void cvPyrDown(
const CvArr* src,
CvArr* dst,
int filter=CV GAUSSIAN 5x5 );

src The source image

dst The destination image, should have a half as large width and height than the source

filter Type of the filter used for convolution; only CV GAUSSIAN 5x5 is currently supported

The function performs the downsampling step of the Gaussian pyramid decomposition. First it
convolves the source image with the specified filter and then downsamples the image by rejecting
even rows and columns.

cvReleaseStructuringElement (view/add comments)

Deletes a structuring element.

void cvReleaseStructuringElement( IplConvKernel** element );

270 CHAPTER 2. IMGPROC. IMAGE PROCESSING

element Pointer to the deleted structuring element

The function releases the structure IplConvKernel that is no longer needed. If *element
is NULL, the function has no effect.

cvSmooth (view/add comments)

Smooths the image in one of several ways.

void cvSmooth(
const CvArr* src,
CvArr* dst,
int smoothtype=CV GAUSSIAN,
int param1=3,
int param2=0,
double param3=0,
double param4=0);

src The source image

dst The destination image

smoothtype Type of the smoothing:

CV BLUR NO SCALE linear convolution with param1 × param2 box kernel (all 1’s). If you
want to smooth different pixels with different-size box kernels, you can use the integral
image that is computed using cvIntegral
CV BLUR linear convolution with param1 × param2 box kernel (all 1’s) with subsequent
scaling by 1/(param1 · param2)
CV GAUSSIAN linear convolution with a param1 × param2 Gaussian kernel
CV MEDIAN median filter with a param1 × param1 square aperture
CV BILATERAL bilateral filter with a param1×param1 square aperture, color sigma=param3
and spatial sigma=param4. If param1=0, the aperture square side is set to cvRound(param4*1.5)*
Information about bilateral filtering can be found at [Link]
CVonline/LOCAL_COPIES/MANDUCHI1/Bilateral_Filtering.html

param1 The first parameter of the smoothing operation, the aperture width. Must be a positive
odd number (1, 3, 5, ...)
2.2. IMAGE FILTERING 271

param2 The second parameter of the smoothing operation, the aperture height. Ignored by
CV MEDIAN and CV BILATERAL methods. In the case of simple scaled/non-scaled and
Gaussian blur if param2 is zero, it is set to param1. Otherwise it must be a positive odd
number.

param3 In the case of a Gaussian parameter this parameter may specify Gaussian σ (standard
deviation). If it is zero, it is calculated from the kernel size:

param1 for horizontal kernel

σ = 0.3(n/2 − 1) + 0.8 where n =
param2 for vertical kernel

Using standard sigma for small kernels (3 × 3 to 7 × 7) gives better speed. If param3 is not
zero, while param1 and param2 are zeros, the kernel size is calculated from the sigma (to
provide accurate enough operation).

The function smooths an image using one of several methods. Every of the methods has some
features and restrictions listed below
Blur with no scaling works with single-channel images only and supports accumulation of 8-bit
to 16-bit format (similar to cvSobel and cvLaplace) and 32-bit floating point to 32-bit floating-point
format.
Simple blur and Gaussian blur support 1- or 3-channel, 8-bit and 32-bit floating point images.
These two methods can process images in-place.
Median and bilateral filters work with 1- or 3-channel 8-bit images and can not process images
in-place.

cvSobel (view/add comments)

Calculates the first, second, third or mixed image derivatives using an extended Sobel operator.

void cvSobel(
const CvArr* src,
CvArr* dst,
int xorder,
int yorder,
int apertureSize=3 );

src Source image of type CvArr*

272 CHAPTER 2. IMGPROC. IMAGE PROCESSING

dst Destination image

xorder Order of the derivative x

yorder Order of the derivative y

apertureSize Size of the extended Sobel kernel, must be 1, 3, 5 or 7

In all cases except 1, an apertureSize × apertureSize separable kernel will be used to

calculate the derivative. For apertureSize = 1 a 3 × 1 or 1 × 3 a kernel is used (Gaussian
smoothing is not done). There is also the special value CV SCHARR (-1) that corresponds to a 3 × 3
Scharr filter that may give more accurate results than a 3 × 3 Sobel. Scharr aperture is
 
−3 0 3
−10 0 10
−3 0 3
for the x-derivative or transposed for the y-derivative.
The function calculates the image derivative by convolving the image with the appropriate
kernel:

dxorder+yorder src
dst(x, y) =
dxxorder · dy yorder
The Sobel operators combine Gaussian smoothing and differentiation so the result is more
or less resistant to the noise. Most often, the function is called with (xorder = 1, yorder = 0,
apertureSize = 3) or (xorder = 0, yorder = 1, apertureSize = 3) to calculate the first x- or
y- image derivative. The first case corresponds to a kernel of:
 
−1 0 1
−2 0 2
−1 0 1
and the second one corresponds to a kernel of:
 
−1 −2 −1
0 0 0
1 2 1

or a kernel of:  
1 2 1
0 0 0
−1 2 −1
2.3. GEOMETRIC IMAGE TRANSFORMATIONS 273

depending on the image origin (origin field of IplImage structure). No scaling is done, so
the destination image usually has larger numbers (in absolute values) than the source image does.
To avoid overflow, the function requires a 16-bit destination image if the source image is 8-bit.
The result can be converted back to 8-bit using the cvConvertScale or the cvConvertScaleAbs
function. Besides 8-bit images the function can process 32-bit floating-point images. Both the
source and the destination must be single-channel images of equal size or equal ROI size.

2.3 Geometric Image Transformations

The functions in this section perform various geometrical transformations of 2D images. That is,
they do not change the image content, but deform the pixel grid, and map this deformed grid to the
destination image. In fact, to avoid sampling artifacts, the mapping is done in the reverse order,
from destination to the source. That is, for each pixel (x, y) of the destination image, the functions
compute coordinates of the corresponding ”donor” pixel in the source image and copy the pixel
value, that is:

dst(x, y) = src(fx (x, y), fy (x, y))

In the case when the user specifies the forward mapping: hgx , gy i : src → dst, the OpenCV
functions first compute the corresponding inverse mapping: hfx , fy i : dst → src and then use
the above formula.
The actual implementations of the geometrical transformations, from the most generic cvRemap
and to the simplest and the fastest cvResize, need to solve the 2 main problems with the above
formula:
1. extrapolation of non-existing pixels. Similarly to the filtering functions, described in the pre-
vious section, for some (x, y) one of fx (x, y) or fy (x, y), or they both, may fall outside of
the image, in which case some extrapolation method needs to be used. OpenCV provides
the same selection of the extrapolation methods as in the filtering functions, but also an ad-
ditional method BORDER TRANSPARENT, which means that the corresponding pixels in the
destination image will not be modified at all.
2. interpolation of pixel values. Usually fx (x, y) and fy (x, y) are floating-point numbers (i.e.
hfx , fy i can be an affine or perspective transformation, or radial lens distortion correction
etc.), so a pixel values at fractional coordinates needs to be retrieved. In the simplest case
the coordinates can be just rounded to the nearest integer coordinates and the correspond-
ing pixel used, which is called nearest-neighbor interpolation. However, a better result can
be achieved by using more sophisticated interpolation methods, where a polynomial function
is fit into some neighborhood of the computed pixel (fx (x, y), fy (x, y)) and then the value of
the polynomial at (fx (x, y), fy (x, y)) is taken as the interpolated pixel value. In OpenCV you
can choose between several interpolation methods, see cvResize.
274 CHAPTER 2. IMGPROC. IMAGE PROCESSING

cvGetRotationMatrix2D (view/add comments)

Calculates the affine matrix of 2d rotation.

CvMat* cv2DRotationMatrix(
CvPoint2D32f center,
double angle,
double scale,
CvMat* mapMatrix );

center Center of the rotation in the source image

angle The rotation angle in degrees. Positive values mean counter-clockwise rotation (the coor-
dinate origin is assumed to be the top-left corner)
scale Isotropic scale factor
mapMatrix Pointer to the destination 2 × 3 matrix
The function cv2DRotationMatrix calculates the following matrix:
 
α β (1 − α) · center.x − β · center.y
−β α β · center.x − (1 − α) · center.y
where

α = scale · cos(angle), β = scale · sin(angle)

The transformation maps the rotation center to itself. If this is not the purpose, the shift should
be adjusted.

cvGetAffineTransform (view/add comments)

Calculates the affine transform from 3 corresponding points.

CvMat* cvGetAffineTransform(
const CvPoint2D32f* src,
const CvPoint2D32f* dst,
CvMat* mapMatrix );
2.3. GEOMETRIC IMAGE TRANSFORMATIONS 275

src Coordinates of 3 triangle vertices in the source image

dst Coordinates of the 3 corresponding triangle vertices in the destination image
mapMatrix Pointer to the destination 2 × 3 matrix

The function cvGetAffineTransform calculates the matrix of an affine transform such that:
 
 0 xi
xi
= mapMatrix · yi 
yi0

1
where

dst(i) = (x0i , yi0 ), src(i) = (xi , yi ), i = 0, 1, 2

cvGetPerspectiveTransform (view/add comments)

Calculates the perspective transform from 4 corresponding points.

CvMat* cvGetPerspectiveTransform(
const CvPoint2D32f* src,
const CvPoint2D32f* dst,
CvMat* mapMatrix );

src Coordinates of 4 quadrangle vertices in the source image

dst Coordinates of the 4 corresponding quadrangle vertices in the destination image
mapMatrix Pointer to the destination 3 × 3 matrix

The function cvGetPerspectiveTransform calculates a matrix of perspective transforms

such that:
 
 0 xi
xi
= mapMatrix · yi 
yi0

1
where

dst(i) = (x0i , yi0 ), src(i) = (xi , yi ), i = 0, 1, 2, 3

276 CHAPTER 2. IMGPROC. IMAGE PROCESSING

cvGetQuadrangleSubPix (view/add comments)

Retrieves the pixel quadrangle from an image with sub-pixel accuracy.

void cvGetQuadrangleSubPix(
const CvArr* src,
CvArr* dst,
const CvMat* mapMatrix );

src Source image

dst Extracted quadrangle

mapMatrix The transformation 2 × 3 matrix [A|b] (see the discussion)

The function cvGetQuadrangleSubPix extracts pixels from src at sub-pixel accuracy and
stores them to dst as follows:

dst(x, y) = src(A11 x0 + A12 y 0 + b1 , A21 x0 + A22 y 0 + b2 )

where

(width(dst) − 1) 0 (height(dst) − 1)
x0 = x − ,y = y −
2 2
and
 
A11 A12 b1
mapMatrix =
A21 A22 b2
The values of pixels at non-integer coordinates are retrieved using bilinear interpolation. When
the function needs pixels outside of the image, it uses replication border mode to reconstruct the
values. Every channel of multiple-channel images is processed independently.

cvGetRectSubPix (view/add comments)

Retrieves the pixel rectangle from an image with sub-pixel accuracy.
2.3. GEOMETRIC IMAGE TRANSFORMATIONS 277

void cvGetRectSubPix(
const CvArr* src,
CvArr* dst,
CvPoint2D32f center );

src Source image

dst Extracted rectangle

center Floating point coordinates of the extracted rectangle center within the source image. The
center must be inside the image

The function cvGetRectSubPix extracts pixels from src:

dst(x, y) = src(x + center.x − (width(dst) − 1) ∗ 0.5, y + center.y − (height(dst) − 1) ∗ 0.5)

where the values of the pixels at non-integer coordinates are retrieved using bilinear interpo-
lation. Every channel of multiple-channel images is processed independently. While the rectangle
center must be inside the image, parts of the rectangle may be outside. In this case, the replication
border mode is used to get pixel values beyond the image boundaries.

cvLogPolar (view/add comments)

Remaps an image to log-polar space.

void cvLogPolar(
const CvArr* src,
CvArr* dst,
CvPoint2D32f center,
double M,
int flags=CV INTER LINEAR+CV WARP FILL OUTLIERS );

src Source image

dst Destination image

278 CHAPTER 2. IMGPROC. IMAGE PROCESSING

center The transformation center; where the output precision is maximal

M Magnitude scale parameter. See below

flags A combination of interpolation methods and the following optional flags:

CV WARP FILL OUTLIERS fills all of the destination image pixels. If some of them corre-
spond to outliers in the source image, they are set to zero
CV WARP INVERSE MAP See below

The function cvLogPolar transforms the source image using the following transformation:
Forward transformation (CV WARP INVERSE MAP is not set):

dst(φ, ρ) = src(x, y)
Inverse transformation (CV WARP INVERSE MAP is set):

dst(x, y) = src(φ, ρ)
where
p
ρ = M · log x2 + y 2 , φ = atan(y/x)
The function emulates the human ”foveal” vision and can be used for fast scale and rotation-
invariant template matching, for object tracking and so forth. The function can not operate in-place.
#include <cv.h>
#include <highgui.h>

int main(int argc, char** argv)

{
IplImage* src;

if( argc == 2 && (src=cvLoadImage(argv[1],1) != 0 )

{
IplImage* dst = cvCreateImage( cvSize(256,256), 8, 3 );
IplImage* src2 = cvCreateImage( cvGetSize(src), 8, 3 );
cvLogPolar( src, dst, cvPoint2D32f(src->width/2,src->height/2), 40,
CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS );
cvLogPolar( dst, src2, cvPoint2D32f(src->width/2,src->height/2), 40,
CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS+CV_WARP_INVERSE_MAP );
cvNamedWindow( "log-polar", 1 );
cvShowImage( "log-polar", dst );
cvNamedWindow( "inverse log-polar", 1 );
cvShowImage( "inverse log-polar", src2 );
2.3. GEOMETRIC IMAGE TRANSFORMATIONS 279

cvWaitKey();
}
return 0;
}

And this is what the program displays when opencv/samples/c/[Link] is passed to

it

cvRemap (view/add comments)

Applies a generic geometrical transformation to the image.

void cvRemap(
const CvArr* src,
CvArr* dst,
const CvArr* mapx,
const CvArr* mapy,
int flags=CV INTER LINEAR+CV WARP FILL OUTLIERS,
CvScalar fillval=cvScalarAll(0) );

src Source image

dst Destination image

mapx The map of x-coordinates (CV 32FC1 image)

280 CHAPTER 2. IMGPROC. IMAGE PROCESSING

mapy The map of y-coordinates (CV 32FC1 image)

flags A combination of interpolation method and the following optional flag(s):

CV WARP FILL OUTLIERS fills all of the destination image pixels. If some of them corre-
spond to outliers in the source image, they are set to fillval

fillval A value used to fill outliers

The function cvRemap transforms the source image using the specified map:

dst(x, y) = src(mapx(x, y), mapy(x, y))

Similar to other geometrical transformations, some interpolation method (specified by user) is
used to extract pixels with non-integer coordinates. Note that the function can not operate in-place.

cvResize (view/add comments)

Resizes an image.

void cvResize(
const CvArr* src,
CvArr* dst,
int interpolation=CV INTER LINEAR );

src Source image

dst Destination image

interpolation Interpolation method:

CV INTER NN nearest-neigbor interpolation

CV INTER LINEAR bilinear interpolation (used by default)
CV INTER AREA resampling using pixel area relation. It is the preferred method for im-
age decimation that gives moire-free results. In terms of zooming it is similar to the
CV INTER NN method
CV INTER CUBIC bicubic interpolation

The function cvResize resizes an image src so that it fits exactly into dst. If ROI is set, the
function considers the ROI as supported.
2.3. GEOMETRIC IMAGE TRANSFORMATIONS 281

cvWarpAffine (view/add comments)

Applies an affine transformation to an image.

void cvWarpAffine(
const CvArr* src,
CvArr* dst,
const CvMat* mapMatrix,
int flags=CV INTER LINEAR+CV WARP FILL OUTLIERS,
CvScalar fillval=cvScalarAll(0) );

src Source image

dst Destination image

mapMatrix 2 × 3 transformation matrix

flags A combination of interpolation methods and the following optional flags:

CV WARP FILL OUTLIERS fills all of the destination image pixels; if some of them corre-
spond to outliers in the source image, they are set to fillval
CV WARP INVERSE MAP indicates that matrix is inversely transformed from the destination
image to the source and, thus, can be used directly for pixel interpolation. Otherwise,
the function finds the inverse transform from mapMatrix

fillval A value used to fill outliers

The function cvWarpAffine transforms the source image using the specified matrix:

dst(x0 , y 0 ) = src(x, y)
where
 
 0 x
x
= mapMatrix · y  if CV WARP INVERSE MAP is not set
y0

 10 
  x
x
= mapMatrix · y 0  otherwise
y
1
282 CHAPTER 2. IMGPROC. IMAGE PROCESSING

The function is similar to cvGetQuadrangleSubPix but they are not exactly the same. cvWarpAffine
requires input and output image have the same data type, has larger overhead (so it is not quite
suitable for small images) and can leave part of destination image unchanged. While cvGetQuad-
rangleSubPix may extract quadrangles from 8-bit images into floating-point buffer, has smaller
overhead and always changes the whole destination image content. Note that the function can not
operate in-place.
To transform a sparse set of points, use the cvTransform function from cxcore.

cvWarpPerspective (view/add comments)

Applies a perspective transformation to an image.

void cvWarpPerspective(
const CvArr* src,
CvArr* dst,
const CvMat* mapMatrix,
int flags=CV INTER LINEAR+CV WARP FILL OUTLIERS,
CvScalar fillval=cvScalarAll(0) );

src Source image

dst Destination image

mapMatrix 3 × 3 transformation matrix

flags A combination of interpolation methods and the following optional flags:

CV WARP FILL OUTLIERS fills all of the destination image pixels; if some of them corre-
spond to outliers in the source image, they are set to fillval
CV WARP INVERSE MAP indicates that matrix is inversely transformed from the destination
image to the source and, thus, can be used directly for pixel interpolation. Otherwise,
the function finds the inverse transform from mapMatrix

fillval A value used to fill outliers

The function cvWarpPerspective transforms the source image using the specified matrix:
2.4. MISCELLANEOUS IMAGE TRANSFORMATIONS 283

 
 0 x
x
= mapMatrix · y  if CV WARP INVERSE MAP is not set
y0

 10 
  x
x
= mapMatrix · y 0  otherwise
y
1
Note that the function can not operate in-place. For a sparse set of points use the cvPerspec-
tiveTransform function from CxCore.

2.4 Miscellaneous Image Transformations

cvAdaptiveThreshold (view/add comments)

Applies an adaptive threshold to an array.

void cvAdaptiveThreshold(
const CvArr* src,
CvArr* dst,
double maxValue,
int adaptive method=CV ADAPTIVE THRESH MEAN C,
int thresholdType=CV THRESH BINARY,
int blockSize=3,
double param1=5 );

src Source image

dst Destination image

maxValue Maximum value that is used with CV THRESH BINARY and CV THRESH BINARY INV

adaptive method Adaptive thresholding algorithm to use: CV ADAPTIVE THRESH MEAN C or

CV ADAPTIVE THRESH GAUSSIAN C (see the discussion)

thresholdType Thresholding type; must be one of

CV THRESH BINARY xxx

CV THRESH BINARY INV xxx
284 CHAPTER 2. IMGPROC. IMAGE PROCESSING

blockSize The size of a pixel neighborhood that is used to calculate a threshold value for the
pixel: 3, 5, 7, and so on

param1 The method-dependent parameter. For the methods CV ADAPTIVE THRESH MEAN C
and CV ADAPTIVE THRESH GAUSSIAN C it is a constant subtracted from the mean or weighted
mean (see the discussion), though it may be negative

The function transforms a grayscale image to a binary image according to the formulas:

CV THRESH BINARY 
maxValue if src(x, y) > T (x, y)
dst(x, y) =
0 otherwise
CV THRESH BINARY INV

0 if src(x, y) > T (x, y)
dst(x, y) =
maxValue otherwise

where T (x, y) is a threshold calculated individually for each pixel.

For the method CV ADAPTIVE THRESH MEAN C it is the mean of a blockSize × blockSize
pixel neighborhood, minus param1.
For the method CV ADAPTIVE THRESH GAUSSIAN C it is the weighted sum (gaussian) of a
blockSize × blockSize pixel neighborhood, minus param1.

cvCvtColor (view/add comments)

Converts an image from one color space to another.

void cvCvtColor(
const CvArr* src,
CvArr* dst,
int code );

src The source 8-bit (8u), 16-bit (16u) or single-precision floating-point (32f) image

dst The destination image of the same data type as the source. The number of channels may be
different

code Color conversion operation that can be specifed using CV src color space 2 dst color space
constants (see below)
2.4. MISCELLANEOUS IMAGE TRANSFORMATIONS 285

The function converts the input image from one color space to another. The function ignores
the colorModel and channelSeq fields of the IplImage header, so the source image color
space should be specified correctly (including order of the channels in the case of RGB space.
For example, BGR means 24-bit format with B0 , G0 , R0 , B1 , G1 , R1 , ... layout whereas RGB means
24-format with R0 , G0 , B0 , R1 , G1 , B1 , ... layout).
The conventional range for R,G,B channel values is:

• 0 to 255 for 8-bit images

• 0 to 65535 for 16-bit images and

• 0 to 1 for floating-point images.

Of course, in the case of linear transformations the range can be specific, but in order to get
correct results in the case of non-linear transformations, the input image should be scaled.
The function can do the following transformations:

• Transformations within RGB space like adding/removing the alpha channel, reversing the
channel order, conversion to/from 16-bit RGB color (R5:G6:B5 or R5:G5:B5), as well as
conversion to/from grayscale using:

RGB[A] to Gray:Y ← 0.299 · R + 0.587 · G + 0.114 · B

and
Gray to RGB[A]:R ← Y, G ← Y, B ← Y, A ← 0

The conversion from a RGB image to gray is done with:

cvCvtColor(src ,bwsrc, CV_RGB2GRAY)

• RGB ↔ CIE [Link] 709 with D65 white point (CV BGR2XYZ, CV RGB2XYZ, CV XYZ2BGR,
CV XYZ2RGB):      
X 0.412453 0.357580 0.180423 R
 Y  ← 0.212671 0.715160 0.072169 · G
Z 0.019334 0.119193 0.950227 B
     
R 3.240479 −1.53715 −0.498535 X
G ← −0.969256 1.875991 0.041556  ·  Y 
B 0.055648 −0.204043 1.057311 Z
X, Y and Z cover the whole value range (in the case of floating-point images Z may exceed
1).
286 CHAPTER 2. IMGPROC. IMAGE PROCESSING

• RGB ↔ YCrCb JPEG (a.k.a. YCC) (CV BGR2YCrCb, CV RGB2YCrCb, CV YCrCb2BGR,

CV YCrCb2RGB)
Y ← 0.299 · R + 0.587 · G + 0.114 · B
Cr ← (R − Y ) · 0.713 + delta
Cb ← (B − Y ) · 0.564 + delta
R ← Y + 1.403 · (Cr − delta)
G ← Y − 0.344 · (Cr − delta) − 0.714 · (Cb − delta)
B ← Y + 1.773 · (Cb − delta)
where 
 128 for 8-bit images
delta = 32768 for 16-bit images
0.5 for floating-point images


Y, Cr and Cb cover the whole value range.

• RGB ↔ HSV (CV BGR2HSV, CV RGB2HSV, CV HSV2BGR, CV HSV2RGB) in the case of

8-bit and 16-bit images R, G and B are converted to floating-point format and scaled to fit
the 0 to 1 range
V ← max(R, G, B)

V −min(R,G,B)

if V 6= 0
S← V
0 otherwise

 60(G − B)/S if V = R
H← 120 + 60(B − R)/S if V = G
240 + 60(R − G)/S if V = B


if H < 0 then H ← H + 360

On output 0 ≤ V ≤ 1, 0 ≤ S ≤ 1, 0 ≤ H ≤ 360.
The values are then converted to the destination data type:

8-bit images
V ← 255V, S ← 255S, H ← H/2(to fit to 0 to 255)
16-bit images (currently not supported)

V < −65535V, S < −65535S, H < −H

32-bit images H, S, V are left as is

2.4. MISCELLANEOUS IMAGE TRANSFORMATIONS 287

• RGB ↔ HLS (CV BGR2HLS, CV RGB2HLS, CV HLS2BGR, CV HLS2RGB). in the case of

8-bit and 16-bit images R, G and B are converted to floating-point format and scaled to fit
the 0 to 1 range.
Vmax ← max(R, G, B)
Vmin ← min(R, G, B)
Vmax + Vmin
L←
2
(
Vmax −Vmin
Vmax +Vmin if L < 0.5
S← Vmax −Vmin
2−(Vmax +Vmin ) if L ≥ 0.5

 60(G − B)/S if Vmax = R
H← 120 + 60(B − R)/S if Vmax = G
240 + 60(R − G)/S if Vmax = B


if H < 0 then H ← H + 360 On output 0 ≤ L ≤ 1, 0 ≤ S ≤ 1, 0 ≤ H ≤ 360.

The values are then converted to the destination data type:

8-bit images
V ← 255V, S ← 255S, H ← H/2(to fit to 0 to 255)

16-bit images (currently not supported)

V < −65535V, S < −65535S, H < −H

32-bit images H, S, V are left as is

• RGB ↔ CIE L*a*b* (CV BGR2Lab, CV RGB2Lab, CV Lab2BGR, CV Lab2RGB) in the case
of 8-bit and 16-bit images R, G and B are converted to floating-point format and scaled to fit
the 0 to 1 range      
X 0.412453 0.357580 0.180423 R
 Y  ← 0.212671 0.715160 0.072169 · G
Z 0.019334 0.119193 0.950227 B
X ← X/Xn , whereXn = 0.950456
Z ← Z/Zn , whereZn = 1.088754
116 ∗ Y 1/3 − 16 for Y > 0.008856

L←
903.3 ∗ Y for Y ≤ 0.008856
a ← 500(f (X) − f (Y )) + delta
b ← 200(f (Y ) − f (Z)) + delta
288 CHAPTER 2. IMGPROC. IMAGE PROCESSING

where
t1/3

for t > 0.008856
f (t) =
7.787t + 16/116 for t <= 0.008856
and 
128 for 8-bit images
delta =
0 for floating-point images
On output 0 ≤ L ≤ 100, −127 ≤ a ≤ 127, −127 ≤ b ≤ 127
The values are then converted to the destination data type:

8-bit images
L ← L ∗ 255/100, a ← a + 128, b ← b + 128

16-bit images currently not supported

32-bit images L, a, b are left as is

• RGB ↔ CIE L*u*v* (CV BGR2Luv, CV RGB2Luv, CV Luv2BGR, CV Luv2RGB) in the case
of 8-bit and 16-bit images R, G and B are converted to floating-point format and scaled to fit
0 to 1 range      
X 0.412453 0.357580 0.180423 R
 Y  ← 0.212671 0.715160 0.072169 · G
Z 0.019334 0.119193 0.950227 B

116Y 1/3 for Y > 0.008856


L←
903.3Y for Y <= 0.008856
u0 ← 4 ∗ X/(X + 15 ∗ Y + 3Z)
v 0 ← 9 ∗ Y /(X + 15 ∗ Y + 3Z)
u ← 13 ∗ L ∗ (u0 − un ) where un = 0.19793943
v ← 13 ∗ L ∗ (v 0 − vn ) where vn = 0.46831096
On output 0 ≤ L ≤ 100, −134 ≤ u ≤ 220, −140 ≤ v ≤ 122.
The values are then converted to the destination data type:

8-bit images

L ← 255/100L, u ← 255/354(u + 134), v ← 255/256(v + 140)

16-bit images currently not supported

32-bit images L, u, v are left as is
2.4. MISCELLANEOUS IMAGE TRANSFORMATIONS 289

The above formulas for converting RGB to/from various color spaces have been taken from
multiple sources on Web, primarily from the Ford98 at the Charles Poynton site.

• Bayer → RGB (CV BayerBG2BGR, CV BayerGB2BGR, CV BayerRG2BGR, CV BayerGR2BGR,

CV BayerBG2RGB, CV BayerGB2RGB, CV BayerRG2RGB, CV BayerGR2RGB) The Bayer
pattern is widely used in CCD and CMOS cameras. It allows one to get color pictures from
a single plane where R,G and B pixels (sensors of a particular component) are interleaved
like this:

R G R G R
G B G B G
R G R G R
G B G B G
R G R G R

The output RGB components of a pixel are interpolated from 1, 2 or 4 neighbors of the pixel
having the same color. There are several modifications of the above pattern that can be
achieved by shifting the pattern one pixel left and/or one pixel up. The two letters C1 and
C2 in the conversion constants CV Bayer C1 C2 2BGR and CV Bayer C1 C2 2RGB indicate
the particular pattern type - these are components from the second row, second and third
columns, respectively. For example, the above pattern has very popular ”BG” type.

cvDistTransform (view/add comments)

Calculates the distance to the closest zero pixel for all non-zero pixels of the source image.

void cvDistTransform(
const CvArr* src,
CvArr* dst,
int distance type=CV DIST L2,
int mask size=3,
const float* mask=NULL,
CvArr* labels=NULL );

src 8-bit, single-channel (binary) source image

dst Output image with calculated distances (32-bit floating-point, single-channel)

290 CHAPTER 2. IMGPROC. IMAGE PROCESSING

distance type Type of distance; can be CV DIST L1, CV DIST L2, CV DIST C or CV DIST USER

mask size Size of the distance transform mask; can be 3 or 5. in the case of CV DIST L1 or
CV DIST C the parameter is forced to 3, because a 3 × 3 mask gives the same result as a
5 × 5 yet it is faster

mask User-defined mask in the case of a user-defined distance, it consists of 2 numbers (hor-
izontal/vertical shift cost, diagonal shift cost) in the case ofa 3 × 3 mask and 3 numbers
(horizontal/vertical shift cost, diagonal shift cost, knight’s move cost) in the case of a 5 × 5
mask

labels The optional output 2d array of integer type labels, the same size as src and dst

The function calculates the approximated distance from every binary image pixel to the nearest
zero pixel. For zero pixels the function sets the zero distance, for others it finds the shortest path
consisting of basic shifts: horizontal, vertical, diagonal or knight’s move (the latest is available for
a 5 × 5 mask). The overall distance is calculated as a sum of these basic distances. Because the
distance function should be symmetric, all of the horizontal and vertical shifts must have the same
cost (that is denoted as a), all the diagonal shifts must have the same cost (denoted b), and all
knight’s moves must have the same cost (denoted c). For CV DIST C and CV DIST L1 types the
distance is calculated precisely, whereas for CV DIST L2 (Euclidian distance) the distance can be
calculated only with some relative error (a 5 × 5 mask gives more accurate results), OpenCV uses
the values suggested in [4]:
CV DIST C (3 × 3) a = 1, b = 1
CV DIST L1 (3 × 3) a = 1, b = 2
CV DIST L2 (3 × 3) a=0.955, b=1.3693
CV DIST L2 (5 × 5) a=1, b=1.4, c=2.1969
And below are samples of the distance field (black (0) pixel is in the middle of white square) in
the case of a user-defined distance:
User-defined 3 × 3 mask (a=1, b=1.5)
4.5 4 3.5 3 3.5 4 4.5
4 3 2.5 2 2.5 3 4
3.5 2.5 1.5 1 1.5 2.5 3.5
3 2 1 1 2 3
3.5 2.5 1.5 1 1.5 2.5 3.5
4 3 2.5 2 2.5 3 4
4.5 4 3.5 3 3.5 4 4.5
User-defined 5 × 5 mask (a=1, b=1.5, c=2)
2.4. MISCELLANEOUS IMAGE TRANSFORMATIONS 291

4.5 3.5 3 3 3 3.5 4.5

3.5 3 2 2 2 3 3.5
3 2 1.5 1 1.5 2 3
3 2 1 1 2 3
3 2 1.5 1 1.5 2 3
3.5 3 2 2 2 3 3.5
4 3.5 3 3 3 3.5 4
Typically, for a fast, coarse distance estimation CV DIST L2, a 3 × 3 mask is used, and for a
more accurate distance estimation CV DIST L2, a 5 × 5 mask is used.
When the output parameter labels is not NULL, for every non-zero pixel the function also
finds the nearest connected component consisting of zero pixels. The connected components
themselves are found as contours in the beginning of the function.
In this mode the processing time is still O(N), where N is the number of pixels. Thus, the
function provides a very fast way to compute approximate Voronoi diagram for the binary image.

CvConnectedComp (view/add comments)

typedef struct CvConnectedComp
{
double area; /* area of the segmented component */
CvScalar value; /* average color of the connected component */
CvRect rect; /* ROI of the segmented component */
CvSeq* contour; /* optional component boundary
(the contour might have child contours corresponding to the holes) */
} CvConnectedComp;

cvFloodFill (view/add comments)

Fills a connected component with the given color.

void cvFloodFill(
CvArr* image,
CvPoint seed point,
CvScalar new val,
CvScalar lo diff=cvScalarAll(0),
CvScalar up diff=cvScalarAll(0),
CvConnectedComp* comp=NULL,
int flags=4,
CvArr* mask=NULL );
292 CHAPTER 2. IMGPROC. IMAGE PROCESSING

image Input 1- or 3-channel, 8-bit or floating-point image. It is modified by the function unless the
CV FLOODFILL MASK ONLY flag is set (see below)
seed point The starting point
new val New value of the repainted domain pixels
lo diff Maximal lower brightness/color difference between the currently observed pixel and one
of its neighbors belonging to the component, or a seed pixel being added to the component.
In the case of 8-bit color images it is a packed value
up diff Maximal upper brightness/color difference between the currently observed pixel and one
of its neighbors belonging to the component, or a seed pixel being added to the component.
In the case of 8-bit color images it is a packed value
comp Pointer to the structure that the function fills with the information about the repainted do-
main. Note that the function does not fill comp->contour field. The boundary of the filled
component can be retrieved from the output mask image using cvFindContours
flags The operation flags. Lower bits contain connectivity value, 4 (by default) or 8, used within
the function. Connectivity determines which neighbors of a pixel are considered. Upper bits
can be 0 or a combination of the following flags:
CV FLOODFILL FIXED RANGE if set, the difference between the current pixel and seed
pixel is considered, otherwise the difference between neighbor pixels is considered (the
range is floating)
CV FLOODFILL MASK ONLY if set, the function does not fill the image (new val is ignored),
but fills the mask (that must be non-NULL in this case)
mask Operation mask, should be a single-channel 8-bit image, 2 pixels wider and 2 pixels taller
than image. If not NULL, the function uses and updates the mask, so the user takes re-
sponsibility of initializing the mask content. Floodfilling can’t go across non-zero pixels in the
mask, for example, an edge detector output can be used as a mask to stop filling at edges.
It is possible to use the same mask in multiple calls to the function to make sure the filled
area do not overlap. Note: because the mask is larger than the filled image, a pixel in mask
that corresponds to (x, y) pixel in image will have coordinates (x + 1, y + 1)

The function fills a connected component starting from the seed point with the specified color.
The connectivity is determined by the closeness of pixel values. The pixel at (x, y) is considered
to belong to the repainted domain if:

grayscale image, floating range

src(x0 , y 0 ) − lo diff <= src(x, y) <= src(x0 , y 0 ) + up diff
2.4. MISCELLANEOUS IMAGE TRANSFORMATIONS 293

grayscale image, fixed range

src(seed.x, seed.y) − lo diff <= src(x, y) <= src(seed.x, seed.y) + up diff

color image, floating range

src(x0 , y 0 )r − lo diffr <= src(x, y)r <= src(x0 , y 0 )r + up diffr

src(x0 , y 0 )g − lo diffg <= src(x, y)g <= src(x0 , y 0 )g + up diffg

src(x0 , y 0 )b − lo diffb <= src(x, y)b <= src(x0 , y 0 )b + up diffb

color image, fixed range

src(seed.x, seed.y)r − lo diffr <= src(x, y)r <= src(seed.x, seed.y)r + up diffr

src(seed.x, seed.y)g − lo diffg <= src(x, y)g <= src(seed.x, seed.y)g + up diffg
src(seed.x, seed.y)b − lo diffb <= src(x, y)b <= src(seed.x, seed.y)b + up diffb

where src(x0 , y 0 ) is the value of one of pixel neighbors. That is, to be added to the connected
component, a pixel’s color/brightness should be close enough to the:

• color/brightness of one of its neighbors that are already referred to the connected component
in the case of floating range

• color/brightness of the seed point in the case of fixed range.

cvInpaint (view/add comments)

Inpaints the selected region in the image.

void cvInpaint(
const CvArr* src,
const CvArr* mask,
CvArr* dst,
double inpaintRadius,
int flags);

src The input 8-bit 1-channel or 3-channel image.

294 CHAPTER 2. IMGPROC. IMAGE PROCESSING

mask The inpainting mask, 8-bit 1-channel image. Non-zero pixels indicate the area that needs
to be inpainted.

dst The output image of the same format and the same size as input.

inpaintRadius The radius of circlular neighborhood of each point inpainted that is considered
by the algorithm.

flags The inpainting method, one of the following:

CV INPAINT NS Navier-Stokes based method.

CV INPAINT TELEA The method by Alexandru Telea [21]

The function reconstructs the selected image area from the pixel near the area boundary.
The function may be used to remove dust and scratches from a scanned photo, or to remove
undesirable objects from still images or video.

cvIntegral (view/add comments)

Calculates the integral of an image.

void cvIntegral(
const CvArr* image,
CvArr* sum,
CvArr* sqsum=NULL,
CvArr* tiltedSum=NULL );

image The source image, W × H, 8-bit or floating-point (32f or 64f)

sum The integral image, (W + 1) × (H + 1), 32-bit integer or double precision floating-point (64f)

sqsum The integral image for squared pixel values, (W + 1) × (H + 1), double precision floating-
point (64f)

tiltedSum The integral for the image rotated by 45 degrees, (W + 1) × (H + 1), the same data
type as sum

The function calculates one or more integral images for the source image as following:
2.4. MISCELLANEOUS IMAGE TRANSFORMATIONS 295

X
sum(X, Y ) = image(x, y)
x<X,y<Y
X
sqsum(X, Y ) = image(x, y)2
x<X,y<Y
X
tiltedSum(X, Y ) = image(x, y)
y<Y,abs(x−X+1)≤Y −y−1

Using these integral images, one may calculate sum, mean and standard deviation over a
specific up-right or rotated rectangular region of the image in a constant time, for example:
X
= sum(x2 , y2 ) − sum(x1 , y2 ) − sum(x2 , y1 ) + sum(x1 , x1 )
x1 <=x<x2 , y1 <=y<y2

It makes possible to do a fast blurring or fast block correlation with variable window size, for
example. In the case of multi-channel images, sums for each channel are accumulated indepen-
dently.

cvPyrMeanShiftFiltering (view/add comments)

Does meanshift image segmentation

void cvPyrMeanShiftFiltering(
const CvArr* src,
CvArr* dst,
double sp,
double sr,
int max level=1,
CvTermCriteria termcrit=
cvTermCriteria(CV TERMCRIT ITER+CV TERMCRIT EPS,5,1));

src The source 8-bit, 3-channel image.

dst The destination image of the same format and the same size as the source.

sp The spatial window radius.

sr The color window radius.

296 CHAPTER 2. IMGPROC. IMAGE PROCESSING

max level Maximum level of the pyramid for the segmentation.

termcrit Termination criteria: when to stop meanshift iterations.
The function implements the filtering stage of meanshift segmentation, that is, the output of the
function is the filtered ”posterized” image with color gradients and fine-grain texture flattened. At
every pixel (X, Y ) of the input image (or down-sized input image, see below) the function executes
meanshift iterations, that is, the pixel (X, Y ) neighborhood in the joint space-color hyperspace is
considered:

(x, y) : X − sp ≤ x ≤ X + sp, Y − sp ≤ y ≤ Y + sp, ||(R, G, B) − (r, g, b)|| ≤ sr

where (R,G,B) and (r,g,b) are the vectors of color components at (X,Y) and (x,y),
respectively (though, the algorithm does not depend on the color space used, so any 3-component
color space can be used instead). Over the neighborhood the average spatial value (X’,Y’) and
average color vector (R’,G’,B’) are found and they act as the neighborhood center on the next
iteration:
(X, Y ) (X 0 , Y 0 ), (R, G, B) (R0 , G0 , B 0 ).
After the iterations over, the color components of the initial pixel (that is, the pixel from where
the iterations started) are set to the final value (average color at the last iteration):
I(X, Y ) < −(R∗, G∗, B∗)
Then max level > 0 , the gaussian pyramid of max level + 1 levels is built, and the above
procedure is run on the smallest layer. After that, the results are propagated to the larger layer
and the iterations are run again only on those pixels where the layer colors differ much ( > sr )
from the lower-resolution layer, that is, the boundaries of the color regions are clarified. Note, that
the results will be actually different from the ones obtained by running the meanshift procedure on
the whole original image (i.e. when max level == 0 ).

cvPyrSegmentation (view/add comments)

Implements image segmentation by pyramids.

void cvPyrSegmentation(
IplImage* src,
IplImage* dst,
CvMemStorage* storage,
CvSeq** comp,
int level,
double threshold1,
double threshold2 );
2.4. MISCELLANEOUS IMAGE TRANSFORMATIONS 297

src The source image

dst The destination image

storage Storage; stores the resulting sequence of connected components

comp Pointer to the output sequence of the segmented components

level Maximum level of the pyramid for the segmentation

threshold1 Error threshold for establishing the links

threshold2 Error threshold for the segments clustering

The function implements image segmentation by pyramids. The pyramid builds up to the level
level. The links between any pixel a on level i and its candidate father pixel b on the adjacent
level are established if p(c(a), c(b)) < threshold1. After the connected components are defined,
they are joined into several clusters. Any two segments A and B belong to the same cluster, if
p(c(A), c(B)) < threshold2. If the input image has only one channel, then p(c1 , c2 ) = |c1 − c2 |. If
the input image has three channels (red, green and blue), then

p(c1 , c2 ) = 0.30(c1r − c2r ) + 0.59(c1g − c2g ) + 0.11(c1b − c2b ).

There may be more than one connected component per a cluster. The images src and dst
should be 8-bit single-channel or 3-channel images or equal size.

cvThreshold (view/add comments)

Applies a fixed-level threshold to array elements.

double cvThreshold(
const CvArr* src,
CvArr* dst,
double threshold,
double maxValue,
int thresholdType );
298 CHAPTER 2. IMGPROC. IMAGE PROCESSING

src Source array (single-channel, 8-bit or 32-bit floating point)

dst Destination array; must be either the same type as src or 8-bit

threshold Threshold value

maxValue Maximum value to use with CV THRESH BINARY and CV THRESH BINARY INV thresh-
olding types

thresholdType Thresholding type (see the discussion)

The function applies fixed-level thresholding to a single-channel array. The function is typi-
cally used to get a bi-level (binary) image out of a grayscale image ( cvCmpS could be also used
for this purpose) or for removing a noise, i.e. filtering out pixels with too small or too large val-
ues. There are several types of thresholding that the function supports that are determined by
thresholdType:

CV THRESH BINARY

maxValue if src(x, y) > threshold
dst(x, y) =
0 otherwise

CV THRESH BINARY INV


0 if src(x, y) > threshold
dst(x, y) =
maxValue otherwise

CV THRESH TRUNC

threshold if src(x, y) > threshold
dst(x, y) =
src(x, y) otherwise

CV THRESH TOZERO

src(x, y) if src(x, y) > threshold
dst(x, y) =
0 otherwise

CV THRESH TOZERO INV


0 if src(x, y) > threshold
dst(x, y) =
src(x, y) otherwise
2.5. STRUCTURAL ANALYSIS AND SHAPE DESCRIPTORS 299

Also, the special value CV THRESH OTSU may be combined with one of the above values. In
this case the function determines the optimal threshold value using Otsu’s algorithm and uses it
instead of the specified thresh. The function returns the computed threshold value. Currently,
Otsu’s method is implemented only for 8-bit images.

2.5 Structural Analysis and Shape Descriptors

cvApproxChains (view/add comments)

Approximates Freeman chain(s) with a polygonal curve.

CvSeq* cvApproxChains(
CvSeq* src seq,
CvMemStorage* storage,
int method=CV CHAIN APPROX SIMPLE,
300 CHAPTER 2. IMGPROC. IMAGE PROCESSING

double parameter=0,
int minimal perimeter=0,
int recursive=0 );

src seq Pointer to the chain that can refer to other chains

storage Storage location for the resulting polylines

method Approximation method (see the description of the function cvFindContours)

parameter Method parameter (not used now)

minimal perimeter Approximates only those contours whose perimeters are not less than
minimal perimeter. Other chains are removed from the resulting structure

recursive If not 0, the function approximates all chains that access can be obtained to from
src seq by using the h next or v next links. If 0, the single chain is approximated

This is a stand-alone approximation routine. The function cvApproxChains works exactly in

the same way as cvFindContours with the corresponding approximation flag. The function returns
pointer to the first resultant contour. Other approximated contours, if any, can be accessed via the
v next or h next fields of the returned structure.

cvApproxPoly (view/add comments)

Approximates polygonal curve(s) with the specified precision.

CvSeq* cvApproxPoly(
const void* src seq,
int header size,
CvMemStorage* storage,
int method,
double parameter,
int parameter2=0 );

src seq Sequence of an array of points

2.5. STRUCTURAL ANALYSIS AND SHAPE DESCRIPTORS 301

header size Header size of the approximated curve[s]

storage Container for the approximated contours. If it is NULL, the input sequences’ storage is
used

method Approximation method; only CV POLY APPROX DP is supported, that corresponds to the
Douglas-Peucker algorithm

parameter Method-specific parameter; in the case of CV POLY APPROX DP it is a desired ap-

proximation accuracy

parameter2 If case if src seq is a sequence, the parameter determines whether the single se-
quence should be approximated or all sequences on the same level or below src seq (see
cvFindContours for description of hierarchical contour structures). If src seq is an array
CvMat* of points, the parameter specifies whether the curve is closed (parameter2!=0) or
not (parameter2 =0)

The function approximates one or more curves and returns the approximation result[s]. In
the case of multiple curves, the resultant tree will have the same structure as the input one (1:1
correspondence).

cvArcLength (view/add comments)

Calculates the contour perimeter or the curve length.

double cvArcLength(
const void* curve,
CvSlice slice=CV WHOLE SEQ,
int isClosed=-1 );

curve Sequence or array of the curve points

slice Starting and ending points of the curve, by default, the whole curve length is calculated

isClosed Indicates whether the curve is closed or not. There are 3 cases:

• isClosed = 0 the curve is assumed to be unclosed.

• isClosed > 0 the curve is assumed to be closed.
302 CHAPTER 2. IMGPROC. IMAGE PROCESSING

• isClosed < 0 if curve is sequence, the flag CV SEQ FLAG CLOSED of ((CvSeq*)curve)->flags
is checked to determine if the curve is closed or not, otherwise (curve is represented by
array (CvMat*) of points) it is assumed to be unclosed.
The function calculates the length or curve as the sum of lengths of segments between subse-
quent points

cvBoundingRect (view/add comments)

Calculates the up-right bounding rectangle of a point set.

CvRect cvBoundingRect( CvArr* points, int update=0 );

points 2D point set, either a sequence or vector (CvMat) of points

update The update flag. See below.
The function returns the up-right bounding rectangle for a 2d point set. Here is the list of
possible combination of the flag values and type of points:
update points action
0 CvContour the bounding rectangle is not calculated, but
it is taken from rect field of the contour
header.
1 CvContour the bounding rectangle is calculated and writ-
ten to rect field of the contour header.
0 CvSeq or CvMat the bounding rectangle is calculated and re-
turned.
1 CvSeq or CvMat runtime error is raised.

cvBoxPoints (view/add comments)

Finds the box vertices.

void cvBoxPoints(
CvBox2D box,
CvPoint2D32f pt[4] );
2.5. STRUCTURAL ANALYSIS AND SHAPE DESCRIPTORS 303

box Box

points Array of vertices

The function calculates the vertices of the input 2d box.

Here is the function code:
void cvBoxPoints( CvBox2D box, CvPoint2D32f pt[4] )
{
float a = (float)cos([Link])*0.5f;
float b = (float)sin([Link])*0.5f;

pt[0].x = [Link].x - a*[Link] - b*[Link];

pt[0].y = [Link].y + b*[Link] - a*[Link];
pt[1].x = [Link].x + a*[Link] - b*[Link];
pt[1].y = [Link].y - b*[Link] - a*[Link];
pt[2].x = 2*[Link].x - pt[0].x;
pt[2].y = 2*[Link].y - pt[0].y;
pt[3].x = 2*[Link].x - pt[1].x;
pt[3].y = 2*[Link].y - pt[1].y;
}

cvCalcPGH (view/add comments)

Calculates a pair-wise geometrical histogram for a contour.

void cvCalcPGH( const CvSeq* contour, CvHistogram* hist );

contour Input contour. Currently, only integer point coordinates are allowed

hist Calculated histogram; must be two-dimensional

The function calculates a 2D pair-wise geometrical histogram (PGH), described in cvIivari-

nen97 for the contour. The algorithm considers every pair of contour edges. The angle between
the edges and the minimum/maximum distances are determined for every pair. To do this each
of the edges in turn is taken as the base, while the function loops through all the other edges.
When the base edge and any other edge are considered, the minimum and maximum distances
from the points on the non-base edge and line of the base edge are selected. The angle between
the edges defines the row of the histogram in which all the bins that correspond to the distance
between the calculated minimum and maximum distances are incremented (that is, the histogram
304 CHAPTER 2. IMGPROC. IMAGE PROCESSING

is transposed relatively to the cvIivarninen97 definition). The histogram can be used for contour
matching.

cvCalcEMD2 (view/add comments)

Computes the ”minimal work” distance between two weighted point configurations.

float cvCalcEMD2(
const CvArr* signature1,
const CvArr* signature2,
int distance type,
CvDistanceFunction distance func=NULL,
const CvArr* cost matrix=NULL,
CvArr* flow=NULL,
float* lower bound=NULL,
void* userdata=NULL );

signature1 First signature, a size1 × dims + 1 floating-point matrix. Each row stores the point
weight followed by the point coordinates. The matrix is allowed to have a single column
(weights only) if the user-defined cost matrix is used

signature2 Second signature of the same format as signature1, though the number of rows
may be different. The total weights may be different, in this case an extra ”dummy” point is
added to either signature1 or signature2

distance type Metrics used; CV DIST L1, CV DIST L2, and CV DIST C stand for one of the
standard metrics; CV DIST USER means that a user-defined function distance func or
pre-calculated cost matrix is used

distance func The user-supplied distance function. It takes coordinates of two points and re-
turns the distance between the points typedef float (*CvDistanceFunction)(const
float* f1, const float* f2, void* userdata);

cost matrix The user-defined size1 × size2 cost matrix. At least one of cost matrix and
distance func must be NULL. Also, if a cost matrix is used, lower boundary (see below)
can not be calculated, because it needs a metric function

flow The resultant size1 × size2 flow matrix: flowi,j is a flow from i th point of signature1
to j th point of signature2
2.5. STRUCTURAL ANALYSIS AND SHAPE DESCRIPTORS 305

lower bound Optional input/output parameter: lower boundary of distance between the two sig-
natures that is a distance between mass centers. The lower boundary may not be calculated
if the user-defined cost matrix is used, the total weights of point configurations are not equal,
or if the signatures consist of weights only (i.e. the signature matrices have a single column).
The user must initialize *lower bound. If the calculated distance between mass centers is
greater or equal to *lower bound (it means that the signatures are far enough) the function
does not calculate EMD. In any case *lower bound is set to the calculated distance be-
tween mass centers on return. Thus, if user wants to calculate both distance between mass
centers and EMD, *lower bound should be set to 0

userdata Pointer to optional data that is passed into the user-defined distance function

The function computes the earth mover distance and/or a lower boundary of the distance
between the two weighted point configurations. One of the applications described in cvRubn-
erSept98 is multi-dimensional histogram comparison for image retrieval. EMD is a a transporta-
tion problem that is solved using some modification of a simplex algorithm, thus the complexity is
exponential in the worst case, though, on average it is much faster. In the case of a real metric
the lower boundary can be calculated even faster (using linear-time algorithm) and it can be used
to determine roughly whether the two signatures are far enough so that they cannot relate to the
same object.

cvCheckContourConvexity (view/add comments)

Tests contour convexity.

int cvCheckContourConvexity( const CvArr* contour );

contour Tested contour (sequence or array of points)

The function tests whether the input contour is convex or not. The contour must be simple,
without self-intersections.

CvConvexityDefect (view/add comments)

Structure describing a single contour convexity defect.
typedef struct CvConvexityDefect
{
306 CHAPTER 2. IMGPROC. IMAGE PROCESSING

CvPoint* start; /* point of the contour where the defect begins */

CvPoint* end; /* point of the contour where the defect ends */
CvPoint* depth_point; /* the farthest from the convex hull point within the defect */
float depth; /* distance between the farthest point and the convex hull */
} CvConvexityDefect;

cvContourArea (view/add comments)

Calculates the area of a whole contour or a contour section.

double cvContourArea(
const CvArr* contour,
CvSlice slice=CV WHOLE SEQ );

contour Contour (sequence or array of vertices)

slice Starting and ending points of the contour section of interest, by default, the area of the
whole contour is calculated
2.5. STRUCTURAL ANALYSIS AND SHAPE DESCRIPTORS 307

The function calculates the area of a whole contour or a contour section. In the latter case the
total area bounded by the contour arc and the chord connecting the 2 selected points is calculated
as shown on the picture below:

Orientation of the contour affects the area sign, thus the function may return a negative result.
Use the fabs() function from C runtime to get the absolute value of the area.

cvContourFromContourTree (view/add comments)

Restores a contour from the tree.

CvSeq* cvContourFromContourTree(
const CvContourTree* tree,
CvMemStorage* storage,
CvTermCriteria criteria );

tree Contour tree

storage Container for the reconstructed contour

criteria Criteria, where to stop reconstruction

The function restores the contour from its binary tree representation. The parameter criteria
determines the accuracy and/or the number of tree levels used for reconstruction, so it is possible
to build an approximated contour. The function returns the reconstructed contour.
308 CHAPTER 2. IMGPROC. IMAGE PROCESSING

cvConvexHull2 (view/add comments)

Finds the convex hull of a point set.

CvSeq* cvConvexHull2(
const CvArr* input,
void* storage=NULL,
int orientation=CV CLOCKWISE,
int return points=0 );

points Sequence or array of 2D points with 32-bit integer or floating-point coordinates

storage The destination array (CvMat*) or memory storage (CvMemStorage*) that will store the
convex hull. If it is an array, it should be 1d and have the same number of elements as the
input array/sequence. On output the header is modified as to truncate the array down to the
hull size. If storage is NULL then the convex hull will be stored in the same storage as the
input sequence

orientation Desired orientation of convex hull: CV CLOCKWISE or CV COUNTER CLOCKWISE

return points If non-zero, the points themselves will be stored in the hull instead of indices if
storage is an array, or pointers if storage is memory storage

The function finds the convex hull of a 2D point set using Sklansky’s algorithm. If storage is
memory storage, the function creates a sequence containing the hull points or pointers to them,
depending on return points value and returns the sequence on output. If storage is a CvMat,
the function returns NULL.
Example. Building convex hull for a sequence or array of points
#include "cv.h"
#include "highgui.h"
#include <stdlib.h>

#define ARRAY 0 /* switch between array/sequence method by replacing 0<=>1 */

void main( int argc, char** argv )

{
IplImage* img = cvCreateImage( cvSize( 500, 500 ), 8, 3 );
cvNamedWindow( "hull", 1 );
2.5. STRUCTURAL ANALYSIS AND SHAPE DESCRIPTORS 309

#if !ARRAY
CvMemStorage* storage = cvCreateMemStorage();
#endif

for(;;)
{
int i, count = rand()%100 + 1, hullcount;
CvPoint pt0;
#if !ARRAY
CvSeq* ptseq = cvCreateSeq( CV_SEQ_KIND_GENERIC|CV_32SC2,
sizeof(CvContour),
sizeof(CvPoint),
storage );
CvSeq* hull;

for( i = 0; i < count; i++ )

{
pt0.x = rand() % (img->width/2) + img->width/4;
pt0.y = rand() % (img->height/2) + img->height/4;
cvSeqPush( ptseq, &pt0 );
}
hull = cvConvexHull2( ptseq, 0, CV_CLOCKWISE, 0 );
hullcount = hull->total;
#else
CvPoint* points = (CvPoint*)malloc( count * sizeof(points[0]));
int* hull = (int*)malloc( count * sizeof(hull[0]));
CvMat point_mat = cvMat( 1, count, CV_32SC2, points );
CvMat hull_mat = cvMat( 1, count, CV_32SC1, hull );

for( i = 0; i < count; i++ )

{
pt0.x = rand() % (img->width/2) + img->width/4;
pt0.y = rand() % (img->height/2) + img->height/4;
points[i] = pt0;
}
cvConvexHull2( &point_mat, &hull_mat, CV_CLOCKWISE, 0 );
hullcount = hull_mat.cols;
#endif
cvZero( img );
for( i = 0; i < count; i++ )
{
#if !ARRAY
pt0 = *CV_GET_SEQ_ELEM( CvPoint, ptseq, i );
#else
pt0 = points[i];
310 CHAPTER 2. IMGPROC. IMAGE PROCESSING

#endif
cvCircle( img, pt0, 2, CV_RGB( 255, 0, 0 ), CV_FILLED );
}

#if !ARRAY
pt0 = **CV_GET_SEQ_ELEM( CvPoint*, hull, hullcount - 1 );
#else
pt0 = points[hull[hullcount-1]];
#endif

for( i = 0; i < hullcount; i++ )

{
#if !ARRAY
CvPoint pt = **CV_GET_SEQ_ELEM( CvPoint*, hull, i );
#else
CvPoint pt = points[hull[i]];
#endif
cvLine( img, pt0, pt, CV_RGB( 0, 255, 0 ));
pt0 = pt;
}

cvShowImage( "hull", img );

int key = cvWaitKey(0);

if( key == 27 ) // ’ESC’
break;

#if !ARRAY
cvClearMemStorage( storage );
#else
free( points );
free( hull );
#endif
}
}

cvConvexityDefects (view/add comments)

Finds the convexity defects of a contour.

CvSeq* cvConvexityDefects(
2.5. STRUCTURAL ANALYSIS AND SHAPE DESCRIPTORS 311

const CvArr* contour,

const CvArr* convexhull,
CvMemStorage* storage=NULL );

contour Input contour

convexhull Convex hull obtained using cvConvexHull2 that should contain pointers or indices
to the contour points, not the hull points themselves (the return points parameter in
cvConvexHull2 should be 0)

storage Container for the output sequence of convexity defects. If it is NULL, the contour or hull
(in that order) storage is used

The function finds all convexity defects of the input contour and returns a sequence of the
CvConvexityDefect structures.

cvCreateContourTree (view/add comments)

Creates a hierarchical representation of a contour.

CvContourTree* cvCreateContourTree(
const CvSeq* contour,
CvMemStorage* storage,
double threshold );

contour Input contour

storage Container for output tree

threshold Approximation accuracy

The function creates a binary tree representation for the input contour and returns the pointer
to its root. If the parameter threshold is less than or equal to 0, the function creates a full binary
tree representation. If the threshold is greater than 0, the function creates a representation with
the precision threshold: if the vertices with the interceptive area of its base line are less than
threshold, the tree should not be built any further. The function returns the created tree.
312 CHAPTER 2. IMGPROC. IMAGE PROCESSING

cvEndFindContours (view/add comments)

Finishes the scanning process.

CvSeq* cvEndFindContours(
CvContourScanner* scanner );

scanner Pointer to the contour scanner

The function finishes the scanning process and returns a pointer to the first contour on the
highest level.

cvFindContours (view/add comments)

Finds the contours in a binary image.

int cvFindContours(
CvArr* image,
CvMemStorage* storage,
CvSeq** first contour,
int header size=sizeof(CvContour),
int mode=CV RETR LIST,
int method=CV CHAIN APPROX SIMPLE,
CvPoint offset=cvPoint(0,0) );

image The source, an 8-bit single channel image. Non-zero pixels are treated as 1’s, zero pixels
remain 0’s - the image is treated as binary. To get such a binary image from grayscale,
one may use cvThreshold, cvAdaptiveThreshold or cvCanny. The function modifies the
source image’s content

storage Container of the retrieved contours

first contour Output parameter, will contain the pointer to the first outer contour

header size Size of the sequence header, ≥ sizeof(CvChain) if method = CV CHAIN CODE,
and ≥ sizeof(CvContour) otherwise
2.5. STRUCTURAL ANALYSIS AND SHAPE DESCRIPTORS 313

mode Retrieval mode

CV RETR EXTERNAL retrives only the extreme outer contours

CV RETR LIST retrieves all of the contours and puts them in the list
CV RETR CCOMP retrieves all of the contours and organizes them into a two-level hierarchy:
on the top level are the external boundaries of the components, on the second level are
the boundaries of the holes
CV RETR TREE retrieves all of the contours and reconstructs the full hierarchy of nested
contours

method Approximation method (for all the modes, except CV LINK RUNS, which uses built-in
approximation)

CV CHAIN CODE outputs contours in the Freeman chain code. All other methods output
polygons (sequences of vertices)
CV CHAIN APPROX NONE translates all of the points from the chain code into points
CV CHAIN APPROX SIMPLE compresses horizontal, vertical, and diagonal segments and
leaves only their end points
CV CHAIN APPROX TC89 L1,CV CHAIN APPROX TC89 KCOS applies one of the flavors of
the Teh-Chin chain approximation algorithm.
CV LINK RUNS uses a completely different contour retrieval algorithm by linking horizontal
segments of 1’s. Only the CV RETR LIST retrieval mode can be used with this method.

offset Offset, by which every contour point is shifted. This is useful if the contours are extracted
from the image ROI and then they should be analyzed in the whole image context

The function retrieves contours from the binary image using the algorithm [19]. The contours
are a useful tool for shape analysis and object detection and recognition.
The function retrieves contours from the binary image and returns the number of retrieved
contours. The pointer first contour is filled by the function. It will contain a pointer to the
first outermost contour or NULL if no contours are detected (if the image is completely black).
Other contours may be reached from first contour using the h next and v next links. The
sample in the cvDrawContours discussion shows how to use contours for connected component
detection. Contours can be also used for shape analysis and object recognition - see squares.c
in the OpenCV sample directory.
Note: the source image is modified by this function.
314 CHAPTER 2. IMGPROC. IMAGE PROCESSING

cvFindNextContour (view/add comments)

Finds the next contour in the image.

CvSeq* cvFindNextContour(
CvContourScanner scanner );

scanner Contour scanner initialized by cvStartFindContours

The function locates and retrieves the next contour in the image and returns a pointer to it. The
function returns NULL if there are no more contours.

cvFitEllipse2 (view/add comments)

Fits an ellipse around a set of 2D points.

CvBox2D cvFitEllipse2(
const CvArr* points );

points Sequence or array of points

The function calculates the ellipse that fits best (in least-squares sense) around a set of 2D
points. The meaning of the returned structure fields is similar to those in cvEllipse except that
size stores the full lengths of the ellipse axises, not half-lengths.

cvFitLine (view/add comments)

Fits a line to a 2D or 3D point set.

void cvFitLine(
const CvArr* points,
int dist type,
double param,
2.5. STRUCTURAL ANALYSIS AND SHAPE DESCRIPTORS 315

double reps,
double aeps,
float* line );

points Sequence or array of 2D or 3D points with 32-bit integer or floating-point coordinates

dist type The distance used for fitting (see the discussion)

param Numerical parameter (C) for some types of distances, if 0 then some optimal value is
chosen

reps Sufficient accuracy for the radius (distance between the coordinate origin and the line). 0.01
is a good default value.

aeps Sufficient accuracy for the angle. 0.01 is a good default value.

line The output line parameters. In the case of a 2d fitting, it is an array of 4 floats (vx,
vy, x0, y0) where (vx, vy) is a normalized vector collinear to the line and (x0, y0)
is some point on the line. in the case of a 3D fitting it is an array of 6 floats (vx, vy,
vz, x0, y0, z0) where (vx, vy, vz) is a normalized vector collinear to the line and
(x0, y0, z0) is some point on the line
P
The function fits a line to a 2D or 3D point set by minimizing i ρ(ri ) where ri is the distance
between the i th point and the line and ρ(r) is a distance function, one of:

dist type=CV DIST L2

ρ(r) = r2 /2 (the simplest and the fastest least-squares method)

dist type=CV DIST L1

ρ(r) = r

dist type=CV DIST L12 r

r2
ρ(r) = 2 · ( 1 + − 1)
2
dist type=CV DIST FAIR
r  r 
ρ (r) = C 2 · − log 1 + where C = 1.3998
C C
316 CHAPTER 2. IMGPROC. IMAGE PROCESSING

dist type=CV DIST WELSCH

C2
    
r 2
ρ (r) = · 1 − exp − where C = 2.9846
2 C

dist type=CV DIST HUBER

r2 /2

if r < C
ρ(r) = where C = 1.345
C · (r − C/2) otherwise

cvGetCentralMoment (view/add comments)

Retrieves the central moment from the moment state structure.

double cvGetCentralMoment(
CvMoments* moments,
int x order,
int y order );

moments Pointer to the moment state structure

x order x order of the retrieved moment, x order >= 0

y order y order of the retrieved moment, y order >= 0 and x order + y order <= 3

The function retrieves the central moment, which in the case of image moments is defined as:
X
µx order, y order = (I(x, y) · (x − xc )x order · (y − yc )y order )
x,y

where xc , yc are the coordinates of the gravity center:

M10 M01
xc = , yc =
M00 M00

cvGetHuMoments (view/add comments)

Calculates the seven Hu invariants.
2.5. STRUCTURAL ANALYSIS AND SHAPE DESCRIPTORS 317

void cvGetHuMoments( const CvMoments* moments,CvHuMoments* hu );

moments The input moments, computed with cvMoments

hu The output Hu invariants

The function calculates the seven Hu invariants, see [Link]

Image_moment, that are defined as:

hu1 = η20 + η02

hu2 = (η20 − η02 )2 + 4η11
2

hu3 = (η30 − 3η12 ) + (3η21 − η03 )2

2

hu4 = (η30 + η12 )2 + (η21 + η03 )2

hu5 = (η30 − 3η12 )(η30 + η12 )[(η30 + η12 )2 − 3(η21 + η03 )2 ] + (3η21 − η03 )(η21 + η03 )[3(η30 + η12 )2 − (η21 + η03 )2 ]
hu6 = (η20 − η02 )[(η30 + η12 )2 − (η21 + η03 )2 ] + 4η11 (η30 + η12 )(η21 + η03 )
hu7 = (3η21 − η03 )(η21 + η03 )[3(η30 + η12 )2 − (η21 + η03 )2 ] − (η30 − 3η12 )(η21 + η03 )[3(η30 + η12 )2 − (η21 + η03 )2 ]

where ηji denote the normalized central moments.

These values are proved to be invariant to the image scale, rotation, and reflection except the
seventh one, whose sign is changed by reflection. Of course, this invariance was proved with the
assumption of infinite image resolution. In case of a raster images the computed Hu invariants for
the original and transformed images will be a bit different.

cvGetNormalizedCentralMoment (view/add comments)

Retrieves the normalized central moment from the moment state structure.

double cvGetNormalizedCentralMoment(
CvMoments* moments,
int x order,
int y order );

moments Pointer to the moment state structure

x order x order of the retrieved moment, x order >= 0

318 CHAPTER 2. IMGPROC. IMAGE PROCESSING

y order y order of the retrieved moment, y order >= 0 and x order + y order <= 3
The function retrieves the normalized central moment:
µx order, y order
ηx order, y order = (y order+x order)/2+1
M00

cvGetSpatialMoment (view/add comments)

Retrieves the spatial moment from the moment state structure.

double cvGetSpatialMoment(
CvMoments* moments,
int x order,
int y order );

moments The moment state, calculated by cvMoments

x order x order of the retrieved moment, x order >= 0
y order y order of the retrieved moment, y order >= 0 and x order + y order <= 3
The function retrieves the spatial moment, which in the case of image moments is defined as:
X
Mx order, y order = (I(x, y) · xx order · y y order )
x,y
where I(x, y) is the intensity of the pixel (x, y).

cvMatchContourTrees (view/add comments)

Compares two contours using their tree representations.

double cvMatchContourTrees(
const CvContourTree* tree1,
const CvContourTree* tree2,
int method,
double threshold );
2.5. STRUCTURAL ANALYSIS AND SHAPE DESCRIPTORS 319

tree1 First contour tree

tree2 Second contour tree

method Similarity measure, only CV CONTOUR TREES MATCH I1 is supported

threshold Similarity threshold

The function calculates the value of the matching measure for two contour trees. The similarity
measure is calculated level by level from the binary tree roots. If at a certain level the difference
between contours becomes less than threshold, the reconstruction process is interrupted and
the current difference is returned.

cvMatchShapes (view/add comments)

Compares two shapes.

double cvMatchShapes(
const void* object1,
const void* object2,
int method,
double parameter=0 );

object1 First contour or grayscale image

object2 Second contour or grayscale image

method Comparison method; CV CONTOUR MATCH I1, CV CONTOURS MATCH I2 or CV CONTOURS MATCH I3

parameter Method-specific parameter (is not used now)

The function compares two shapes. The 3 implemented methods all use Hu moments (see
cvGetHuMoments) (A is object1, B is object2):

method=CV CONTOUR MATCH I1

 
X  1 1 
I1 (A, B) =  mA − mB 

i=1...7 i i
320 CHAPTER 2. IMGPROC. IMAGE PROCESSING

method=CV CONTOUR MATCH I2

X 
mA B

I2 (A, B) = i − mi
i=1...7

method=CV CONTOUR MATCH I3

 
X mA i − mB
I3 (A, B) = i
mA 
i=1...7 i

where

mA A A B B B
i = sign(hi ) · log hi mi = sign(hi ) · log hi

and hA B
i , hi are the Hu moments of A and B respectively.

cvMinAreaRect2 (view/add comments)

Finds the circumscribed rectangle of minimal area for a given 2D point set.

CvBox2D cvMinAreaRect2(
const CvArr* points,
CvMemStorage* storage=NULL );

points Sequence or array of points

storage Optional temporary memory storage

The function finds a circumscribed rectangle of the minimal area for a 2D point set by building
a convex hull for the set and applying the rotating calipers technique to the hull.
Picture. Minimal-area bounding rectangle for contour
2.5. STRUCTURAL ANALYSIS AND SHAPE DESCRIPTORS 321

cvMinEnclosingCircle (view/add comments)

Finds the circumscribed circle of minimal area for a given 2D point set.

int cvMinEnclosingCircle(
const CvArr* points,
CvPoint2D32f* center,
float* radius );

points Sequence or array of 2D points

center Output parameter; the center of the enclosing circle

radius Output parameter; the radius of the enclosing circle

The function finds the minimal circumscribed circle for a 2D point set using an iterative algo-
rithm. It returns nonzero if the resultant circle contains all the input points and zero otherwise (i.e.
the algorithm failed).
322 CHAPTER 2. IMGPROC. IMAGE PROCESSING

cvMoments (view/add comments)

Calculates all of the moments up to the third order of a polygon or rasterized shape.

void cvMoments(
const CvArr* arr,
CvMoments* moments,
int binary=0 );

arr Image (1-channel or 3-channel with COI set) or polygon (CvSeq of points or a vector of
points)

moments Pointer to returned moment’s state structure

binary (For images only) If the flag is non-zero, all of the zero pixel values are treated as zeroes,
and all of the others are treated as 1’s

The function calculates spatial and central moments up to the third order and writes them to
moments. The moments may then be used then to calculate the gravity center of the shape, its
area, main axises and various shape characeteristics including 7 Hu invariants.

cvPointPolygonTest (view/add comments)

Point in contour test.

double cvPointPolygonTest(
const CvArr* contour,
CvPoint2D32f pt,
int measure dist );

contour Input contour

pt The point tested against the contour

measure dist If it is non-zero, the function estimates the distance from the point to the nearest
contour edge
2.5. STRUCTURAL ANALYSIS AND SHAPE DESCRIPTORS 323

The function determines whether the point is inside a contour, outside, or lies on an edge
(or coinsides with a vertex). It returns positive, negative or zero value, correspondingly. When
measure dist = 0, the return value is +1, -1 and 0, respectively. When measure dist 6= 0, it is
a signed distance between the point and the nearest contour edge.
Here is the sample output of the function, where each image pixel is tested against the contour.

cvPointSeqFromMat (view/add comments)

Initializes a point sequence header from a point vector.

CvSeq* cvPointSeqFromMat(
int seq kind,
const CvArr* mat,
CvContour* contour header,
CvSeqBlock* block );

seq kind Type of the point sequence: point set (0), a curve (CV SEQ KIND CURVE), closed curve
(CV SEQ KIND CURVE+CV SEQ FLAG CLOSED) etc.
mat Input matrix. It should be a continuous, 1-dimensional vector of points, that is, it should have
type CV 32SC2 or CV 32FC2
324 CHAPTER 2. IMGPROC. IMAGE PROCESSING

contour header Contour header, initialized by the function

block Sequence block header, initialized by the function
The function initializes a sequence header to create a ”virtual” sequence in which elements
reside in the specified matrix. No data is copied. The initialized sequence header may be passed
to any function that takes a point sequence on input. No extra elements can be added to the
sequence, but some may be removed. The function is a specialized variant of cvMakeSeqHead-
erForArray and uses the latter internally. It returns a pointer to the initialized contour header. Note
that the bounding rectangle (field rect of CvContour strucuture) is not initialized by the function.
If you need one, use cvBoundingRect.
Here is a simple usage example.
CvContour header;
CvSeqBlock block;
CvMat* vector = cvCreateMat( 1, 3, CV_32SC2 );

CV_MAT_ELEM( *vector, CvPoint, 0, 0 ) = cvPoint(100,100);

CV_MAT_ELEM( *vector, CvPoint, 0, 1 ) = cvPoint(100,200);
CV_MAT_ELEM( *vector, CvPoint, 0, 2 ) = cvPoint(200,100);

IplImage* img = cvCreateImage( cvSize(300,300), 8, 3 );

cvZero(img);

cvDrawContours( img,
cvPointSeqFromMat(CV_SEQ_KIND_CURVE+CV_SEQ_FLAG_CLOSED,
vector,
&header,
&block),
CV_RGB(255,0,0),
CV_RGB(255,0,0),
0, 3, 8, cvPoint(0,0));

cvReadChainPoint (view/add comments)

Gets the next chain point.

CvPoint cvReadChainPoint( CvChainPtReader* reader );

reader Chain reader state

The function returns the current chain point and updates the reader position.
2.5. STRUCTURAL ANALYSIS AND SHAPE DESCRIPTORS 325

cvStartFindContours (view/add comments)

Initializes the contour scanning process.

CvContourScanner cvStartFindContours(
CvArr* image,
CvMemStorage* storage,
int header size=sizeof(CvContour),
int mode=CV RETR LIST,
int method=CV CHAIN APPROX SIMPLE,
CvPoint offset=cvPoint(0,
0) );

image The 8-bit, single channel, binary source image

storage Container of the retrieved contours

header size Size of the sequence header, >= sizeof (CvChain) if method =CV CHAIN CODE,
and >= sizeof (CvContour) otherwise

mode Retrieval mode; see cvFindContours

method Approximation method. It has the same meaning in cvFindContours, but CV LINK RUNS
can not be used here

offset ROI offset; see cvFindContours

The function initializes and returns a pointer to the contour scanner. The scanner is used in
cvFindNextContour to retrieve the rest of the contours.

cvStartReadChainPoints (view/add comments)

Initializes the chain reader.

void cvStartReadChainPoints( CvChain* chain, CvChainPtReader* reader );

The function initializes a special reader.

326 CHAPTER 2. IMGPROC. IMAGE PROCESSING

cvSubstituteContour (view/add comments)

Replaces a retrieved contour.

void cvSubstituteContour(
CvContourScanner scanner,
CvSeq* new contour );

scanner Contour scanner initialized by cvStartFindContours

new contour Substituting contour

The function replaces the retrieved contour, that was returned from the preceding call of
cvFindNextContour and stored inside the contour scanner state, with the user-specified contour.
The contour is inserted into the resulting structure, list, two-level hierarchy, or tree, depending on
the retrieval mode. If the parameter new contour is NULL, the retrieved contour is not included
in the resulting structure, nor are any of its children that might be added to this structure later.

2.6 Planar Subdivisions

CvSubdiv2D (view/add comments)

Planar subdivision.
#define CV_SUBDIV2D_FIELDS() \
CV_GRAPH_FIELDS() \
int quad_edges; \
int is_geometry_valid; \
CvSubdiv2DEdge recent_edge; \
CvPoint2D32f topleft; \
CvPoint2D32f bottomright;

typedef struct CvSubdiv2D

{
CV_SUBDIV2D_FIELDS()
}
CvSubdiv2D;
Planar subdivision is the subdivision of a plane into a set of non-overlapped regions (facets)
that cover the whole plane. The above structure describes a subdivision built on a 2d point set,
2.6. PLANAR SUBDIVISIONS 327

where the points are linked together and form a planar graph, which, together with a few edges
connecting the exterior subdivision points (namely, convex hull points) with infinity, subdivides a
plane into facets by its edges.
For every subdivision there exists a dual subdivision in which facets and points (subdivision
vertices) swap their roles, that is, a facet is treated as a vertex (called a virtual point below) of the
dual subdivision and the original subdivision vertices become facets. On the picture below original
subdivision is marked with solid lines and dual subdivision with dotted lines.

OpenCV subdivides a plane into triangles using Delaunay’s algorithm. Subdivision is built
iteratively starting from a dummy triangle that includes all the subdivision points for sure. In this
case the dual subdivision is a Voronoi diagram of the input 2d point set. The subdivisions can
be used for the 3d piece-wise transformation of a plane, morphing, fast location of points on the
plane, building special graphs (such as NNG,RNG) and so forth.

CvQuadEdge2D (view/add comments)

Quad-edge of planar subdivision.
/* one of edges within quad-edge, lower 2 bits is index (0..3)
and upper bits are quad-edge pointer */
typedef long CvSubdiv2DEdge;

/* quad-edge structure fields */

#define CV_QUADEDGE2D_FIELDS() \
int flags; \
struct CvSubdiv2DPoint* pt[4]; \
CvSubdiv2DEdge next[4];

typedef struct CvQuadEdge2D

{
CV_QUADEDGE2D_FIELDS()
}
328 CHAPTER 2. IMGPROC. IMAGE PROCESSING

CvQuadEdge2D;

Quad-edge is a basic element of subdivision containing four edges (e, eRot, reversed e and
reversed eRot):

CvSubdiv2DPoint (view/add comments)

Point of original or dual subdivision.
#define CV_SUBDIV2D_POINT_FIELDS()\
int flags; \
CvSubdiv2DEdge first; \
CvPoint2D32f pt; \
int id;

#define CV_SUBDIV2D_VIRTUAL_POINT_FLAG (1 << 30)

typedef struct CvSubdiv2DPoint

{
CV_SUBDIV2D_POINT_FIELDS()
}
CvSubdiv2DPoint;

id This integer can be used to index auxillary data associated with each vertex of the planar
subdivision
2.6. PLANAR SUBDIVISIONS 329

cvCalcSubdivVoronoi2D (view/add comments)

Calculates the coordinates of Voronoi diagram cells.

void cvCalcSubdivVoronoi2D(
CvSubdiv2D* subdiv );

subdiv Delaunay subdivision, in which all the points are already added

The function calculates the coordinates of virtual points. All virtual points corresponding to
some vertex of the original subdivision form (when connected together) a boundary of the Voronoi
cell at that point.

cvClearSubdivVoronoi2D (view/add comments)

Removes all virtual points.

void cvClearSubdivVoronoi2D( CvSubdiv2D* subdiv );

subdiv Delaunay subdivision

The function removes all of the virtual points. It is called internally in cvCalcSubdivVoronoi2D
if the subdivision was modified after previous call to the function.

cvCreateSubdivDelaunay2D (view/add comments)

Creates an empty Delaunay triangulation.

CvSubdiv2D* cvCreateSubdivDelaunay2D(
CvRect rect,
CvMemStorage* storage );
330 CHAPTER 2. IMGPROC. IMAGE PROCESSING

rect Rectangle that includes all of the 2d points that are to be added to the subdivision

storage Container for subdivision

The function creates an empty Delaunay subdivision, where 2d points can be added using the
function cvSubdivDelaunay2DInsert. All of the points to be added must be within the specified
rectangle, otherwise a runtime error will be raised.
Note that the triangulation is a single large triangle that covers the given rectangle. Hence the
three vertices of this triangle are outside the rectangle rect.

cvFindNearestPoint2D (view/add comments)

Finds the closest subdivision vertex to the given point.

CvSubdiv2DPoint* cvFindNearestPoint2D(
CvSubdiv2D* subdiv,
CvPoint2D32f pt );

subdiv Delaunay or another subdivision

pt Input point

The function is another function that locates the input point within the subdivision. It finds the
subdivision vertex that is the closest to the input point. It is not necessarily one of vertices of the
facet containing the input point, though the facet (located using cvSubdiv2DLocate) is used as a
starting point. The function returns a pointer to the found subdivision vertex.

cvSubdiv2DEdgeDst (view/add comments)

Returns the edge destination.

CvSubdiv2DPoint* cvSubdiv2DEdgeDst(
CvSubdiv2DEdge edge );

edge Subdivision edge (not a quad-edge)

2.6. PLANAR SUBDIVISIONS 331

The function returns the edge destination. The returned pointer may be NULL if the edge is
from dual subdivision and the virtual point coordinates are not calculated yet. The virtual points
can be calculated using the function cvCalcSubdivVoronoi2D.

cvSubdiv2DGetEdge (view/add comments)

Returns one of the edges related to the given edge.

CvSubdiv2DEdge cvSubdiv2DGetEdge( CvSubdiv2DEdge edge, CvNextEdgeType

type );

edge Subdivision edge (not a quad-edge)

type Specifies which of the related edges to return, one of the following:

CV NEXT AROUND ORG next around the edge origin (eOnext on the picture below if e is the
input edge)

CV NEXT AROUND DST next around the edge vertex (eDnext)

CV PREV AROUND ORG previous around the edge origin (reversed eRnext)

CV PREV AROUND DST previous around the edge destination (reversed eLnext)

CV NEXT AROUND LEFT next around the left facet (eLnext)

CV NEXT AROUND RIGHT next around the right facet (eRnext)

CV PREV AROUND LEFT previous around the left facet (reversed eOnext)

CV PREV AROUND RIGHT previous around the right facet (reversed eDnext)
332 CHAPTER 2. IMGPROC. IMAGE PROCESSING

The function returns one of the edges related to the input edge.

cvSubdiv2DNextEdge (view/add comments)

Returns next edge around the edge origin

CvSubdiv2DEdge cvSubdiv2DNextEdge( CvSubdiv2DEdge edge );

edge Subdivision edge (not a quad-edge)

2.6. PLANAR SUBDIVISIONS 333

The function returns the next edge around the edge origin: eOnext on the picture above if e
is the input edge)

cvSubdiv2DLocate (view/add comments)

Returns the location of a point within a Delaunay triangulation.

CvSubdiv2DPointLocation cvSubdiv2DLocate(
CvSubdiv2D* subdiv,
CvPoint2D32f pt,
CvSubdiv2DEdge* edge,
CvSubdiv2DPoint** vertex=NULL );

subdiv Delaunay or another subdivision

pt The point to locate

edge The output edge the point falls onto or right to

vertex Optional output vertex double pointer the input point coinsides with

The function locates the input point within the subdivision. There are 5 cases:
334 CHAPTER 2. IMGPROC. IMAGE PROCESSING

• The point falls into some facet. The function returns CV PTLOC INSIDE and *edge will
contain one of edges of the facet.

• The point falls onto the edge. The function returns CV PTLOC ON EDGE and *edge will
contain this edge.

• The point coincides with one of the subdivision vertices. The function returns CV PTLOC VERTEX
and *vertex will contain a pointer to the vertex.

• The point is outside the subdivsion reference rectangle. The function returns CV PTLOC OUTSIDE RECT
and no pointers are filled.

• One of input arguments is invalid. A runtime error is raised or, if silent or ”parent” error
processing mode is selected, CV PTLOC ERROR is returnd.

cvSubdiv2DRotateEdge (view/add comments)

Returns another edge of the same quad-edge.

CvSubdiv2DEdge cvSubdiv2DRotateEdge(
CvSubdiv2DEdge edge,
int rotate );

edge Subdivision edge (not a quad-edge)

rotate Specifies which of the edges of the same quad-edge as the input one to return, one of
the following:

0 the input edge (e on the picture below if e is the input edge)

1 the rotated edge (eRot)
2 the reversed edge (reversed e (in green))
3 the reversed rotated edge (reversed eRot (in green))
2.6. PLANAR SUBDIVISIONS 335

The function returns one of the edges of the same quad-edge as the input edge.

cvSubdivDelaunay2DInsert (view/add comments)

Inserts a single point into a Delaunay triangulation.

CvSubdiv2DPoint* cvSubdivDelaunay2DInsert(
CvSubdiv2D* subdiv,
CvPoint2D32f pt);

subdiv Delaunay subdivision created by the function cvCreateSubdivDelaunay2D

pt Inserted point

The function inserts a single point into a subdivision and modifies the subdivision topology
appropriately. If a point with the same coordinates exists already, no new point is added. The
function returns a pointer to the allocated point. No virtual point coordinates are calculated at this
stage.
336 CHAPTER 2. IMGPROC. IMAGE PROCESSING

2.7 Motion Analysis and Object Tracking

cvAcc (view/add comments)

Adds a frame to an accumulator.

void cvAcc(
const CvArr* image,
CvArr* sum,
const CvArr* mask=NULL );

image Input image, 1- or 3-channel, 8-bit or 32-bit floating point. (each channel of multi-channel
image is processed independently)

sum Accumulator with the same number of channels as input image, 32-bit or 64-bit floating-point

mask Optional operation mask

The function adds the whole image image or its selected region to the accumulator sum:

sum(x, y) ← sum(x, y) + image(x, y) if mask(x, y) 6= 0

cvMultiplyAcc (view/add comments)

Adds the product of two input images to the accumulator.

void cvMultiplyAcc(
const CvArr* image1,
const CvArr* image2,
CvArr* acc,
const CvArr* mask=NULL );

image1 First input image, 1- or 3-channel, 8-bit or 32-bit floating point (each channel of multi-
channel image is processed independently)
2.7. MOTION ANALYSIS AND OBJECT TRACKING 337

image2 Second input image, the same format as the first one

acc Accumulator with the same number of channels as input images, 32-bit or 64-bit floating-point

mask Optional operation mask

The function adds the product of 2 images or their selected regions to the accumulator acc:

acc(x, y) ← acc(x, y) + image1(x, y) · image2(x, y) if mask(x, y) 6= 0

cvRunningAvg (view/add comments)

Updates the running average.

void cvRunningAvg(
const CvArr* image,
CvArr* acc,
double alpha,
const CvArr* mask=NULL );

image Input image, 1- or 3-channel, 8-bit or 32-bit floating point (each channel of multi-channel
image is processed independently)

acc Accumulator with the same number of channels as input image, 32-bit or 64-bit floating-point

alpha Weight of input image

mask Optional operation mask

The function calculates the weighted sum of the input image image and the accumulator acc
so that acc becomes a running average of frame sequence:

acc(x, y) ← (1 − α) · acc(x, y) + α · image(x, y) if mask(x, y) 6= 0

where α regulates the update speed (how fast the accumulator forgets about previous frames).
338 CHAPTER 2. IMGPROC. IMAGE PROCESSING

cvSquareAcc (view/add comments)

Adds the square of the source image to the accumulator.

void cvSquareAcc(
const CvArr* image,
CvArr* sqsum,
const CvArr* mask=NULL );

image Input image, 1- or 3-channel, 8-bit or 32-bit floating point (each channel of multi-channel
image is processed independently)

sqsum Accumulator with the same number of channels as input image, 32-bit or 64-bit floating-
point

mask Optional operation mask

The function adds the input image image or its selected region, raised to power 2, to the
accumulator sqsum:

sqsum(x, y) ← sqsum(x, y) + image(x, y)2 if mask(x, y) 6= 0

2.8 Feature Detection

cvCanny (view/add comments)

Implements the Canny algorithm for edge detection.

void cvCanny(
const CvArr* image,
CvArr* edges,
double threshold1,
double threshold2,
int aperture size=3 );
2.8. FEATURE DETECTION 339

image Single-channel input image

edges Single-channel image to store the edges found by the function

threshold1 The first threshold

threshold2 The second threshold

aperture size Aperture parameter for the Sobel operator (see cvSobel)

The function finds the edges on the input image image and marks them in the output image
edges using the Canny algorithm. The smallest value between threshold1 and threshold2
is used for edge linking, the largest value is used to find the initial segments of strong edges.

cvCornerEigenValsAndVecs (view/add comments)

Calculates eigenvalues and eigenvectors of image blocks for corner detection.

void cvCornerEigenValsAndVecs(
const CvArr* image,
CvArr* eigenvv,
int blockSize,
int aperture size=3 );

image Input image

eigenvv Image to store the results. It must be 6 times wider than the input image

blockSize Neighborhood size (see discussion)

aperture size Aperture parameter for the Sobel operator (see cvSobel)

For every pixel, the function cvCornerEigenValsAndVecs considers a blockSize×blockSize

neigborhood S(p). It calcualtes the covariation matrix of derivatives over the neigborhood as:
" #
(dI/dx)2 (dI/dx · dI/dy)2
P P
S(p) S(p)
M= P 2
P 2
S(p) (dI/dx · dI/dy) S(p) (dI/dy)

After that it finds eigenvectors and eigenvalues of the matrix and stores them into destination
image in form (λ1 , λ2 , x1 , y1 , x2 , y2 ) where
340 CHAPTER 2. IMGPROC. IMAGE PROCESSING

λ1 , λ2 are the eigenvalues of M ; not sorted

x1 , y1 are the eigenvectors corresponding to λ1

x2 , y2 are the eigenvectors corresponding to λ2

cvCornerHarris (view/add comments)

Harris edge detector.

void cvCornerHarris(
const CvArr* image,
CvArr* harris dst,
int blockSize,
int aperture size=3,
double k=0.04 );

image Input image

harris dst Image to store the Harris detector responses. Should have the same size as image

blockSize Neighborhood size (see the discussion of cvCornerEigenValsAndVecs)

aperture size Aperture parameter for the Sobel operator (see cvSobel).

k Harris detector free parameter. See the formula below

The function runs the Harris edge detector on the image. Similarly to cvCornerMinEigenVal
and cvCornerEigenValsAndVecs, for each pixel it calculates a 2 × 2 gradient covariation matrix M
over a blockSize × blockSize neighborhood. Then, it stores

det(M ) − k trace(M )2

to the destination image. Corners in the image can be found as the local maxima of the
destination image.
2.8. FEATURE DETECTION 341

cvCornerMinEigenVal (view/add comments)

Calculates the minimal eigenvalue of gradient matrices for corner detection.

void cvCornerMinEigenVal(
const CvArr* image,
CvArr* eigenval,
int blockSize,
int aperture size=3 );

image Input image

eigenval Image to store the minimal eigenvalues. Should have the same size as image

blockSize Neighborhood size (see the discussion of cvCornerEigenValsAndVecs)

aperture size Aperture parameter for the Sobel operator (see cvSobel).

The function is similar to cvCornerEigenValsAndVecs but it calculates and stores only the
minimal eigen value of derivative covariation matrix for every pixel, i.e. min(λ1 , λ2 ) in terms of the
previous function.

cvFindCornerSubPix (view/add comments)

Refines the corner locations.

void cvFindCornerSubPix(
const CvArr* image,
CvPoint2D32f* corners,
int count,
CvSize win,
CvSize zero zone,
CvTermCriteria criteria );

image Input image

342 CHAPTER 2. IMGPROC. IMAGE PROCESSING

corners Initial coordinates of the input corners; refined coordinates on output

count Number of corners
win Half of the side length of the search window. For example, if win=(5,5), then a 5 ∗ 2 + 1 × 5 ∗
2 + 1 = 11 × 11 search window would be used
zero zone Half of the size of the dead region in the middle of the search zone over which the
summation in the formula below is not done. It is used sometimes to avoid possible sin-
gularities of the autocorrelation matrix. The value of (-1,-1) indicates that there is no such
size
criteria Criteria for termination of the iterative process of corner refinement. That is, the pro-
cess of corner position refinement stops either after a certain number of iterations or when
a required accuracy is achieved. The criteria may specify either of or both the maximum
number of iteration and the required accuracy
The function iterates to find the sub-pixel accurate location of corners, or radial saddle points,
as shown in on the picture below.

Sub-pixel accurate corner locator is based on the observation that every vector from the center
q to a point p located within a neighborhood of q is orthogonal to the image gradient at p subject
to image and measurement noise. Consider the expression:

i = DIpi T · (q − pi )
where DIpi is the image gradient at the one of the points pi in a neighborhood of q. The value
of q is to be found such that i is minimized. A system of equations may be set up with i set to
zero:
2.8. FEATURE DETECTION 343

X X
(DIpi · DIpi T )q = (DIpi · DIpi T · pi )
i i

where the gradients are summed within a neighborhood (”search window”) of q. Calling the
first gradient term G and the second gradient term b gives:

q = G−1 · b
The algorithm sets the center of the neighborhood window at this new center q and then iterates
until the center keeps within a set threshold.

cvGoodFeaturesToTrack (view/add comments)

Determines strong corners on an image.

void cvGoodFeaturesToTrack(
const CvArr* image
CvArr* eigImage, CvArr* tempImage
CvPoint2D32f* corners
int* cornerCount
double qualityLevel
double minDistance
const CvArr* mask=NULL
int blockSize=3
int useHarris=0
double k=0.04 );

image The source 8-bit or floating-point 32-bit, single-channel image

eigImage Temporary floating-point 32-bit image, the same size as image

tempImage Another temporary image, the same size and format as eigImage

corners Output parameter; detected corners

cornerCount Output parameter; number of detected corners

qualityLevel Multiplier for the max/min eigenvalue; specifies the minimal accepted quality of
image corners
344 CHAPTER 2. IMGPROC. IMAGE PROCESSING

minDistance Limit, specifying the minimum possible distance between the returned corners;
Euclidian distance is used

mask Region of interest. The function selects points either in the specified region or in the whole
image if the mask is NULL

blockSize Size of the averaging block, passed to the underlying cvCornerMinEigenVal or cv-
CornerHarris used by the function

useHarris If nonzero, Harris operator ( cvCornerHarris) is used instead of default cvCorner-

MinEigenVal

k Free parameter of Harris detector; used only if (useHarris! = 0)

The function finds the corners with big eigenvalues in the image. The function first calculates
the minimal eigenvalue for every source image pixel using the cvCornerMinEigenVal function and
stores them in eigImage. Then it performs non-maxima suppression (only the local maxima in
3 × 3 neighborhood are retained). The next step rejects the corners with the minimal eigenvalue
less than qualityLevel · max(eigImage(x, y)). Finally, the function ensures that the distance
between any two corners is not smaller than minDistance. The weaker corners (with a smaller
min eigenvalue) that are too close to the stronger corners are rejected.
Note that the if the function is called with different values A and B of the parameter qualityLevel,
and A ¿ B, the array of returned corners with qualityLevel=A will be the prefix of the output
corners array with qualityLevel=B.

cvHoughLines2 (view/add comments)

Finds lines in a binary image using a Hough transform.

CvSeq* cvHoughLines2(
CvArr* image,
void* storage,
int method,
double rho,
double theta,
int threshold,
double param1=0,
double param2=0 );
2.8. FEATURE DETECTION 345

image The 8-bit, single-channel, binary source image. In the case of a probabilistic method, the
image is modified by the function

storage The storage for the lines that are detected. It can be a memory storage (in this case a
sequence of lines is created in the storage and returned by the function) or single row/single
column matrix (CvMat*) of a particular type (see below) to which the lines’ parameters are
written. The matrix header is modified by the function so its cols or rows will contain the
number of lines detected. If storage is a matrix and the actual number of lines exceeds
the matrix size, the maximum possible number of lines is returned (in the case of standard
hough transform the lines are sorted by the accumulator value)

method The Hough transform variant, one of the following:

CV HOUGH STANDARD classical or standard Hough transform. Every line is represented by

two floating-point numbers (ρ, θ), where ρ is a distance between (0,0) point and the line,
and θ is the angle between x-axis and the normal to the line. Thus, the matrix must be
(the created sequence will be) of CV 32FC2 type
CV HOUGH PROBABILISTIC probabilistic Hough transform (more efficient in case if picture
contains a few long linear segments). It returns line segments rather than the whole
line. Each segment is represented by starting and ending points, and the matrix must
be (the created sequence will be) of CV 32SC4 type
CV HOUGH MULTI SCALE multi-scale variant of the classical Hough transform. The lines are
encoded the same way as CV HOUGH STANDARD

rho Distance resolution in pixel-related units

theta Angle resolution measured in radians

threshold Threshold parameter. A line is returned by the function if the corresponding accumu-
lator value is greater than threshold

param1 The first method-dependent parameter:

• For the classical Hough transform it is not used (0).

• For the probabilistic Hough transform it is the minimum line length.
• For the multi-scale Hough transform it is the divisor for the distance resolution ρ. (The
coarse distance resolution will be ρ and the accurate resolution will be (ρ/param1)).

param2 The second method-dependent parameter:

• For the classical Hough transform it is not used (0).

346 CHAPTER 2. IMGPROC. IMAGE PROCESSING

• For the probabilistic Hough transform it is the maximum gap between line segments
lying on the same line to treat them as a single line segment (i.e. to join them).
• For the multi-scale Hough transform it is the divisor for the angle resolution θ. (The
coarse angle resolution will be θ and the accurate resolution will be (θ/param2)).

The function implements a few variants of the Hough transform for line detection.
Example. Detecting lines with Hough transform.
/* This is a standalone program. Pass an image name as a first parameter
of the program. Switch between standard and probabilistic Hough transform
by changing "#if 1" to "#if 0" and back */
#include <cv.h>
#include <highgui.h>
#include <math.h>

int main(int argc, char** argv)

{
IplImage* src;
if( argc == 2 && (src=cvLoadImage(argv[1], 0))!= 0)
{
IplImage* dst = cvCreateImage( cvGetSize(src), 8, 1 );
IplImage* color_dst = cvCreateImage( cvGetSize(src), 8, 3 );
CvMemStorage* storage = cvCreateMemStorage(0);
CvSeq* lines = 0;
int i;
cvCanny( src, dst, 50, 200, 3 );
cvCvtColor( dst, color_dst, CV_GRAY2BGR );
#if 1
lines = cvHoughLines2( dst,
storage,
CV_HOUGH_STANDARD,
1,
CV_PI/180,
100,
0,
0 );

for( i = 0; i < MIN(lines->total,100); i++ )

{
float* line = (float*)cvGetSeqElem(lines,i);
float rho = line[0];
float theta = line[1];
CvPoint pt1, pt2;
double a = cos(theta), b = sin(theta);
double x0 = a*rho, y0 = b*rho;
2.8. FEATURE DETECTION 347

pt1.x = cvRound(x0 + 1000*(-b));

pt1.y = cvRound(y0 + 1000*(a));
pt2.x = cvRound(x0 - 1000*(-b));
pt2.y = cvRound(y0 - 1000*(a));
cvLine( color_dst, pt1, pt2, CV_RGB(255,0,0), 3, 8 );
}
#else
lines = cvHoughLines2( dst,
storage,
CV_HOUGH_PROBABILISTIC,
1,
CV_PI/180,
80,
30,
10 );
for( i = 0; i < lines->total; i++ )
{
CvPoint* line = (CvPoint*)cvGetSeqElem(lines,i);
cvLine( color_dst, line[0], line[1], CV_RGB(255,0,0), 3, 8 );
}
#endif
cvNamedWindow( "Source", 1 );
cvShowImage( "Source", src );

cvNamedWindow( "Hough", 1 );
cvShowImage( "Hough", color_dst );

cvWaitKey(0);
}
}

This is the sample picture the function parameters have been tuned for:
348 CHAPTER 2. IMGPROC. IMAGE PROCESSING

And this is the output of the above program in the case of probabilistic Hough transform (#if
0 case):

cvPreCornerDetect (view/add comments)

Calculates the feature map for corner detection.

void cvPreCornerDetect(
const CvArr* image,
CvArr* corners,
int apertureSize=3 );

image Input image

2.8. FEATURE DETECTION 349

corners Image to store the corner candidates

apertureSize Aperture parameter for the Sobel operator (see cvSobel)

The function calculates the function

Dx2 Dyy + Dy2 Dxx − 2Dx Dy Dxy

where D? denotes one of the first image derivatives and D?? denotes a second image deriva-
tive.
The corners can be found as local maximums of the function below:
// assume that the image is floating-point
IplImage* corners = cvCloneImage(image);
IplImage* dilated_corners = cvCloneImage(image);
IplImage* corner_mask = cvCreateImage( cvGetSize(image), 8, 1 );
cvPreCornerDetect( image, corners, 3 );
cvDilate( corners, dilated_corners, 0, 1 );
cvSubS( corners, dilated_corners, corners );
cvCmpS( corners, 0, corner_mask, CV_CMP_GE );
cvReleaseImage( &corners );
cvReleaseImage( &dilated_corners );

cvSampleLine (view/add comments)

Reads the raster line to the buffer.

int cvSampleLine(
const CvArr* image
CvPoint pt1
CvPoint pt2
void* buffer
int connectivity=8 );

image Image to sample the line from

pt1 Starting line point

pt2 Ending line point

350 CHAPTER 2. IMGPROC. IMAGE PROCESSING

buffer Buffer to store the line points; must have enough size to store max(|pt2.x − pt1.x| +
1, |pt2.y − pt1.y| + 1) points in the case of an 8-connected line and (|pt2.x − pt1.x| +
|pt2.y − pt1.y| + 1) in the case of a 4-connected line

connectivity The line connectivity, 4 or 8

The function implements a particular application of line iterators. The function reads all of the
image points lying on the line between pt1 and pt2, including the end points, and stores them
into the buffer.

2.9 Object Detection

cvMatchTemplate (view/add comments)

Compares a template against overlapped image regions.

void cvMatchTemplate(
const CvArr* image,
const CvArr* templ,
CvArr* result,
int method );

image Image where the search is running; should be 8-bit or 32-bit floating-point

templ Searched template; must be not greater than the source image and the same data type
as the image

result A map of comparison results; single-channel 32-bit floating-point. If image is W × H and

templ is w × h then result must be (W − w + 1) × (H − h + 1)

method Specifies the way the template must be compared with the image regions (see below)

The function is similar to cvCalcBackProjectPatch. It slides through image, compares the

overlapped patches of size w × h against templ using the specified method and stores the com-
parison results to result. Here are the formulas for the different comparison methods one may
use (I denotes image, T template, R result). The summation is done over template and/or
the image patch: x0 = 0...w − 1, y 0 = 0...h − 1
2.9. OBJECT DETECTION 351

method=CV TM SQDIFF
X
R(x, y) = (T (x0 , y 0 ) − I(x + x0 , y + y 0 ))2
x0 ,y 0

method=CV TM SQDIFF NORMED

0, y0)
− I(x + x0 , y + y 0 ))2
P
x0 ,y 0 (T (x
R(x, y) = qP
0 0 2 0 0 2
P
x0 ,y 0 T (x , y ) · x0 ,y 0 I(x + x , y + y )

method=CV TM CCORR
X
R(x, y) = (T (x0 , y 0 ) · I(x + x0 , y + y 0 ))
x0 ,y 0

method=CV TM CCORR NORMED

0, y0)
· I 0 (x + x0 , y + y 0 ))
P
x0 ,y 0 (T (x
R(x, y) = qP
0 0 2 0 0 2
P
x0 ,y 0 T (x , y ) · x0 ,y 0 I(x + x , y + y )

method=CV TM CCOEFF
X
R(x, y) = (T 0 (x0 , y 0 ) · I(x + x0 , y + y 0 ))
x0 ,y 0

where
T 0 (x0 , y 0 ) = T (x0 , y 0 ) − 1/(w · h) · x00 ,y00 T (x00 , y 00 )
P

I 0 (x + x0 , y + y 0 ) = I(x + x0 , y + y 0 ) − 1/(w · h) · x00 ,y00 I(x + x00 , y + y 00 )

P

method=CV TM CCOEFF NORMED

0 (x0 , y 0 )
· I 0 (x + x0 , y + y 0 ))
P
x0 ,y 0 (T
R(x, y) = qP
0 0 0 2 0 0 0 2
P
x0 ,y 0 T (x , y ) · x0 ,y 0 I (x + x , y + y )

After the function finishes the comparison, the best matches can be found as global minimums
(CV TM SQDIFF) or maximums (CV TM CCORR and CV TM CCOEFF) using the cvMinMaxLoc func-
tion. In the case of a color image, template summation in the numerator and each sum in the
denominator is done over all of the channels (and separate mean values are used for each chan-
nel).
352 CHAPTER 2. IMGPROC. IMAGE PROCESSING
Chapter 3

features2d. Feature Detection and

Descriptor Extraction

3.1 Feature detection and description

image The image. Keypoints (corners) will be detected on this.
keypoints Keypoints detected on the image.
threshold Threshold on difference between intensity of center pixel and pixels on circle around
this pixel. See description of the algorithm.
nonmaxSupression If it is true then non-maximum supression will be applied to detected cor-
ners (keypoints).

cvExtractSURF (view/add comments)

Extracts Speeded Up Robust Features from an image.

void cvExtractSURF(
const CvArr* image,
const CvArr* mask,
CvSeq** keypoints,
CvSeq** descriptors,
CvMemStorage* storage,
CvSURFParams params );

353
354 CHAPTER 3. FEATURES2D. FEATURE DETECTION AND DESCRIPTOR EXTRACTION

image The input 8-bit grayscale image

mask The optional input 8-bit mask. The features are only found in the areas that contain more
than 50% of non-zero mask pixels

keypoints The output parameter; double pointer to the sequence of keypoints. The sequence
of CvSURFPoint structures is as follows:
typedef struct CvSURFPoint
{
CvPoint2D32f pt; // position of the feature within the image
int laplacian; // -1, 0 or +1. sign of the laplacian at the point.
// can be used to speedup feature comparison
// (normally features with laplacians of different
// signs can not match)
int size; // size of the feature
float dir; // orientation of the feature: 0..360 degrees
float hessian; // value of the hessian (can be used to
// approximately estimate the feature strengths;
// see also [Link])
}
CvSURFPoint;

descriptors The optional output parameter; double pointer to the sequence of descriptors.
Depending on the [Link] value, each element of the sequence will be either a
64-element or a 128-element floating-point (CV 32F) vector. If the parameter is NULL, the
descriptors are not computed

storage Memory storage where keypoints and descriptors will be stored

params Various algorithm parameters put to the structure CvSURFParams:

typedef struct CvSURFParams
{
int extended; // 0 means basic descriptors (64 elements each),
// 1 means extended descriptors (128 elements each)
double hessianThreshold; // only features with [Link]
// larger than that are extracted.
// good default value is ˜300-500 (can depend on the
// average local contrast and sharpness of the image).
// user can further filter out some features based on
// their hessian values and other characteristics.
int nOctaves; // the number of octaves to be used for extraction.
// With each next octave the feature size is doubled
// (3 by default)
int nOctaveLayers; // The number of layers within each octave
3.1. FEATURE DETECTION AND DESCRIPTION 355

// (4 by default)
}
CvSURFParams;

CvSURFParams cvSURFParams(double hessianThreshold, int extended=0);

// returns default parameters

The function cvExtractSURF finds robust features in the image, as described in [3]. For each
feature it returns its location, size, orientation and optionally the descriptor, basic or extended. The
function can be used for object tracking and localization, image stitching etc.
See the find [Link] demo in OpenCV samples directory.

cvGetStarKeypoints (view/add comments)

Retrieves keypoints using the StarDetector algorithm.

CvSeq* cvGetStarKeypoints(
const CvArr* image,
CvMemStorage* storage,
CvStarDetectorParams params=cvStarDetectorParams() );

image The input 8-bit grayscale image

storage Memory storage where the keypoints will be stored

params Various algorithm parameters given to the structure CvStarDetectorParams:

typedef struct CvStarDetectorParams
{
int maxSize; // maximal size of the features detected. The following
// values of the parameter are supported:
// 4, 6, 8, 11, 12, 16, 22, 23, 32, 45, 46, 64, 90, 128
int responseThreshold; // threshold for the approximatd laplacian,
// used to eliminate weak features
int lineThresholdProjected; // another threshold for laplacian to
// eliminate edges
int lineThresholdBinarized; // another threshold for the feature
// scale to eliminate edges
int suppressNonmaxSize; // linear size of a pixel neighborhood
// for non-maxima suppression
356 CHAPTER 3. FEATURES2D. FEATURE DETECTION AND DESCRIPTOR EXTRACTION

}
CvStarDetectorParams;

The function GetStarKeypoints extracts keypoints that are local scale-space extremas. The
scale-space is constructed by computing approximate values of laplacians with different sigma’s
at each pixel. Instead of using pyramids, a popular approach to save computing time, all of the
laplacians are computed at each pixel of the original high-resolution image. But each approximate
laplacian value is computed in O(1) time regardless of the sigma, thanks to the use of integral
images. The algorithm is based on the paper Agrawal08 , but instead of a square, hexagon or
octagon it uses an 8-end star shape, hence the name, consisting of overlapping upright and tilted
squares.
Each computed feature is represented by the following structure:
typedef struct CvStarKeypoint
{
CvPoint pt; // coordinates of the feature
int size; // feature size, see CvStarDetectorParams::maxSize
float response; // the approximated laplacian value at that point.
}
CvStarKeypoint;

inline CvStarKeypoint cvStarKeypoint(CvPoint pt, int size, float response);

Below is the small usage sample:
#include "cv.h"
#include "highgui.h"

int main(int argc, char** argv)

{
const char* filename = argc > 1 ? argv[1] : "[Link]";
IplImage* img = cvLoadImage( filename, 0 ), *cimg;
CvMemStorage* storage = cvCreateMemStorage(0);
CvSeq* keypoints = 0;
int i;

if( !img )
return 0;
cvNamedWindow( "image", 1 );
cvShowImage( "image", img );
cvNamedWindow( "features", 1 );
cimg = cvCreateImage( cvGetSize(img), 8, 3 );
cvCvtColor( img, cimg, CV_GRAY2BGR );

keypoints = cvGetStarKeypoints( img, storage, cvStarDetectorParams(45) );

3.1. FEATURE DETECTION AND DESCRIPTION 357

for( i = 0; i < (keypoints ? keypoints->total : 0); i++ )

{
CvStarKeypoint kpt = *(CvStarKeypoint*)cvGetSeqElem(keypoints, i);
int r = [Link]/2;
cvCircle( cimg, [Link], r, CV_RGB(0,255,0));
cvLine( cimg, cvPoint([Link].x + r, [Link].y + r),
cvPoint([Link].x - r, [Link].y - r), CV_RGB(0,255,0));
cvLine( cimg, cvPoint([Link].x - r, [Link].y + r),
cvPoint([Link].x + r, [Link].y - r), CV_RGB(0,255,0));
}
cvShowImage( "features", cimg );
cvWaitKey();
}
358 CHAPTER 3. FEATURES2D. FEATURE DETECTION AND DESCRIPTOR EXTRACTION
Chapter 4

flann. Clustering and Search in

Multi-Dimensional Spaces

4.1 Fast Approximate Nearest Neighbor Search

359
360 CHAPTER 4. FLANN. CLUSTERING AND SEARCH IN MULTI-DIMENSIONAL SPACES
Chapter 5

objdetect. Object Detection

5.1 Cascade Classification

Haar Feature-based Cascade Classifier for Object Detection

The object detector described below has been initially proposed by Paul Viola cvViola01 and
improved by Rainer Lienhart cvLienhart02 . First, a classifier (namely a cascade of boosted clas-
sifiers working with haar-like features) is trained with a few hundred sample views of a particular
object (i.e., a face or a car), called positive examples, that are scaled to the same size (say, 20x20),
and negative examples - arbitrary images of the same size.
After a classifier is trained, it can be applied to a region of interest (of the same size as used
during the training) in an input image. The classifier outputs a ”1” if the region is likely to show the
object (i.e., face/car), and ”0” otherwise. To search for the object in the whole image one can move
the search window across the image and check every location using the classifier. The classifier
is designed so that it can be easily ”resized” in order to be able to find the objects of interest at
different sizes, which is more efficient than resizing the image itself. So, to find an object of an
unknown size in the image the scan procedure should be done several times at different scales.
The word ”cascade” in the classifier name means that the resultant classifier consists of several
simpler classifiers (stages) that are applied subsequently to a region of interest until at some
stage the candidate is rejected or all the stages are passed. The word ”boosted” means that the
classifiers at every stage of the cascade are complex themselves and they are built out of basic
classifiers using one of four different boosting techniques (weighted voting). Currently Discrete
Adaboost, Real Adaboost, Gentle Adaboost and Logitboost are supported. The basic classifiers
are decision-tree classifiers with at least 2 leaves. Haar-like features are the input to the basic
classifers, and are calculated as described below. The current algorithm uses the following Haar-
like features:

361
362 CHAPTER 5. OBJDETECT. OBJECT DETECTION

The feature used in a particular classifier is specified by its shape (1a, 2b etc.), position within
the region of interest and the scale (this scale is not the same as the scale used at the detection
stage, though these two scales are multiplied). For example, in the case of the third line feature (2c)
the response is calculated as the difference between the sum of image pixels under the rectangle
covering the whole feature (including the two white stripes and the black stripe in the middle) and
the sum of the image pixels under the black stripe multiplied by 3 in order to compensate for the
differences in the size of areas. The sums of pixel values over a rectangular regions are calculated
rapidly using integral images (see below and the cvIntegral description).
To see the object detector at work, have a look at the HaarFaceDetect demo.
The following reference is for the detection part only. There is a separate application called
haartraining that can train a cascade of boosted classifiers from a set of samples. See
opencv/apps/haartraining for details.

CvHaarFeature, CvHaarClassifier, CvHaarStageClassifier, CvHaarClas-

sifierCascade (view/add comments)
Boosted Haar classifier structures.
#define CV_HAAR_FEATURE_MAX 3

/* a haar feature consists of 2-3 rectangles with appropriate weights */

typedef struct CvHaarFeature
{
int tilted; /* 0 means up-right feature, 1 means 45--rotated feature */

/* 2-3 rectangles with weights of opposite signs and

with absolute values inversely proportional to the areas of the
rectangles. If rect[2].weight !=0, then
the feature consists of 3 rectangles, otherwise it consists of 2 */
struct
{
5.1. CASCADE CLASSIFICATION 363

CvRect r;
float weight;
} rect[CV_HAAR_FEATURE_MAX];
}
CvHaarFeature;

/* a single tree classifier (stump in the simplest case) that returns the
response for the feature at the particular image location (i.e. pixel
sum over subrectangles of the window) and gives out a value depending
on the response */
typedef struct CvHaarClassifier
{
int count; /* number of nodes in the decision tree */

/* these are "parallel" arrays. Every index \texttt{i}

corresponds to a node of the decision tree (root has 0-th index).

left[i] - index of the left child (or negated index if the

left child is a leaf)
right[i] - index of the right child (or negated index if the
right child is a leaf)
threshold[i] - branch threshold. if feature responce is <= threshold,
left branch is chosen, otherwise right branch is chosen.
alpha[i] - output value correponding to the leaf. */
CvHaarFeature* haar_feature;
float* threshold;
int* left;
int* right;
float* alpha;
}
CvHaarClassifier;

/* a boosted battery of classifiers(=stage classifier):

the stage classifier returns 1
if the sum of the classifiers responses
is greater than \texttt{threshold} and 0 otherwise */
typedef struct CvHaarStageClassifier
{
int count; /* number of classifiers in the battery */
float threshold; /* threshold for the boosted classifier */
CvHaarClassifier* classifier; /* array of classifiers */

/* these fields are used for organizing trees of stage classifiers,

rather than just stright cascades */
int next;
364 CHAPTER 5. OBJDETECT. OBJECT DETECTION

int child;
int parent;
}
CvHaarStageClassifier;

typedef struct CvHidHaarClassifierCascade CvHidHaarClassifierCascade;

/* cascade or tree of stage classifiers */

typedef struct CvHaarClassifierCascade
{
int flags; /* signature */
int count; /* number of stages */
CvSize orig_window_size; /* original object size (the cascade is
trained for) */

/* these two parameters are set by cvSetImagesForHaarClassifierCascade */

CvSize real_window_size; /* current object size */
double scale; /* current scale */
CvHaarStageClassifier* stage_classifier; /* array of stage classifiers */
CvHidHaarClassifierCascade* hid_cascade; /* hidden optimized
representation of the
cascade, created by
cvSetImagesForHaarClassifierCascade */
}
CvHaarClassifierCascade;
All the structures are used for representing a cascaded of boosted Haar classifiers. The cas-
cade has the following hierarchical structure:

Cascade:
Stage,,1,,:
Classifier,,11,,:
Feature,,11,,
Classifier,,12,,:
Feature,,12,,
...
Stage,,2,,:
Classifier,,21,,:
Feature,,21,,
...
...

The whole hierarchy can be constructed manually or loaded from a file or an embedded base
using the function cvLoadHaarClassifierCascade.
5.1. CASCADE CLASSIFICATION 365

cvLoadHaarClassifierCascade (view/add comments)

Loads a trained cascade classifier from a file or the classifier database embedded in OpenCV.

CvHaarClassifierCascade* cvLoadHaarClassifierCascade(
const char* directory,
CvSize orig window size );

directory Name of the directory containing the description of a trained cascade classifier

orig window size Original size of the objects the cascade has been trained on. Note that it is
not stored in the cascade and therefore must be specified separately

The function loads a trained cascade of haar classifiers from a file or the classifier database
embedded in OpenCV. The base can be trained using the haartraining application (see opencv/app-
s/haartraining for details).
The function is obsolete. Nowadays object detection classifiers are stored in XML or YAML
files, rather than in directories. To load a cascade from a file, use the cvLoad function.

cvHaarDetectObjects (view/add comments)

Detects objects in the image.
typedef struct CvAvgComp
{
CvRect rect; /* bounding rectangle for the object (average rectangle of a group) */
int neighbors; /* number of neighbor rectangles in the group */
}
CvAvgComp;

CvSeq* cvHaarDetectObjects(
const CvArr* image,
CvHaarClassifierCascade* cascade,
CvMemStorage* storage,
double scaleFactor=1.1,
int minNeighbors=3,
366 CHAPTER 5. OBJDETECT. OBJECT DETECTION

int flags=0,
CvSize minSize=cvSize(0, 0),
CvSize maxSize=cvSize(0,0) );

image Image to detect objects in

cascade Haar classifier cascade in internal representation

storage Memory storage to store the resultant sequence of the object candidate rectangles

scaleFactor The factor by which the search window is scaled between the subsequent scans,
1.1 means increasing window by 10%

minNeighbors Minimum number (minus 1) of neighbor rectangles that makes up an object.

All the groups of a smaller number of rectangles than min neighbors-1 are rejected. If
minNeighbors is 0, the function does not any grouping at all and returns all the detected
candidate rectangles, which may be useful if the user wants to apply a customized grouping
procedure

flags Mode of operation. Currently the only flag that may be specified is CV HAAR DO CANNY PRUNING.
If it is set, the function uses Canny edge detector to reject some image regions that contain
too few or too much edges and thus can not contain the searched object. The particular
threshold values are tuned for face detection and in this case the pruning speeds up the
processing

minSize Minimum window size. By default, it is set to the size of samples the classifier has been
trained on (∼ 20 × 20 for face detection)

maxSize Maximum window size to use. By default, it is set to the size of the image.

The function finds rectangular regions in the given image that are likely to contain objects the
cascade has been trained for and returns those regions as a sequence of rectangles. The function
scans the image several times at different scales (see cvSetImagesForHaarClassifierCascade).
Each time it considers overlapping regions in the image and applies the classifiers to the regions
using cvRunHaarClassifierCascade. It may also apply some heuristics to reduce number of an-
alyzed regions, such as Canny prunning. After it has proceeded and collected the candidate
rectangles (regions that passed the classifier cascade), it groups them and returns a sequence of
average rectangles for each large enough group. The default parameters (scale factor =1.1,
min neighbors =3, flags =0) are tuned for accurate yet slow object detection. For a faster op-
eration on real video images the settings are: scale factor =1.2, min neighbors =2, flags
5.1. CASCADE CLASSIFICATION 367

=CV HAAR DO CANNY PRUNING, min size =minimum possible face size (for example, ∼ 1/4 to
1/16 of the image area in the case of video conferencing).

#include "cv.h"
#include "highgui.h"

CvHaarClassifierCascade* load_object_detector( const char* cascade_path )

{
return (CvHaarClassifierCascade*)cvLoad( cascade_path );
}

void detect_and_draw_objects( IplImage* image,

CvHaarClassifierCascade* cascade,
int do_pyramids )
{
IplImage* small_image = image;
CvMemStorage* storage = cvCreateMemStorage(0);
CvSeq* faces;
int i, scale = 1;

/* if the flag is specified, down-scale the input image to get a

performance boost w/o loosing quality (perhaps) */
if( do_pyramids )
{
small_image = cvCreateImage( cvSize(image->width/2,image->height/2), IPL_DEPTH_8U,
cvPyrDown( image, small_image, CV_GAUSSIAN_5x5 );
scale = 2;
}

/* use the fastest variant */

faces = cvHaarDetectObjects( small_image, cascade, storage, 1.2, 2, CV_HAAR_DO_CANNY_PR

/* draw all the rectangles */

for( i = 0; i < faces->total; i++ )
{
/* extract the rectanlges only */
CvRect face_rect = *(CvRect*)cvGetSeqElem( faces, i );
cvRectangle( image, cvPoint(face_rect.x*scale,face_rect.y*scale),
cvPoint((face_rect.x+face_rect.width)*scale,
(face_rect.y+face_rect.height)*scale),
CV_RGB(255,0,0), 3 );
}

if( small_image != image )

cvReleaseImage( &small_image );
368 CHAPTER 5. OBJDETECT. OBJECT DETECTION

cvReleaseMemStorage( &storage );
}

/* takes image filename and cascade path from the command line */
int main( int argc, char** argv )
{
IplImage* image;
if( argc==3 && (image = cvLoadImage( argv[1], 1 )) != 0 )
{
CvHaarClassifierCascade* cascade = load_object_detector(argv[2]);
detect_and_draw_objects( image, cascade, 1 );
cvNamedWindow( "test", 0 );
cvShowImage( "test", image );
cvWaitKey(0);
cvReleaseHaarClassifierCascade( &cascade );
cvReleaseImage( &image );
}

return 0;
}

cvSetImagesForHaarClassifierCascade (view/add comments)

Assigns images to the hidden cascade.

void cvSetImagesForHaarClassifierCascade(
CvHaarClassifierCascade* cascade,
const CvArr* sum,
const CvArr* sqsum,
const CvArr* tilted sum,
double scale );

cascade Hidden Haar classifier cascade, created by cvCreateHidHaarClassifierCascade

sum Integral (sum) single-channel image of 32-bit integer format. This image as well as the two
subsequent images are used for fast feature evaluation and brightness/contrast normaliza-
tion. They all can be retrieved from input 8-bit or floating point single-channel image using
the function cvIntegral
sqsum Square sum single-channel image of 64-bit floating-point format
5.1. CASCADE CLASSIFICATION 369

tilted sum Tilted sum single-channel image of 32-bit integer format

scale Window scale for the cascade. If scale =1, the original window size is used (objects
of that size are searched) - the same size as specified in cvLoadHaarClassifierCascade
(24x24 in the case of default face cascade), if scale =2, a two times larger window is
used (48x48 in the case of default face cascade). While this will speed-up search about four
times, faces smaller than 48x48 cannot be detected

The function assigns images and/or window scale to the hidden classifier cascade. If image
pointers are NULL, the previously set images are used further (i.e. NULLs mean ”do not change
images”). Scale parameter has no such a ”protection” value, but the previous value can be re-
trieved by the cvGetHaarClassifierCascadeScale function and reused again. The function is used
to prepare cascade for detecting object of the particular size in the particular image. The function
is called internally by cvHaarDetectObjects, but it can be called by the user if they are using the
lower-level function cvRunHaarClassifierCascade.

cvReleaseHaarClassifierCascade (view/add comments)

Releases the haar classifier cascade.

void cvReleaseHaarClassifierCascade(
CvHaarClassifierCascade** cascade );

cascade Double pointer to the released cascade. The pointer is cleared by the function

The function deallocates the cascade that has been created manually or loaded using cvLoad-
HaarClassifierCascade or cvLoad.

cvRunHaarClassifierCascade (view/add comments)

Runs a cascade of boosted classifiers at the given image location.

int cvRunHaarClassifierCascade(
CvHaarClassifierCascade* cascade,
CvPoint pt,
int start stage=0 );
370 CHAPTER 5. OBJDETECT. OBJECT DETECTION

cascade Haar classifier cascade

pt Top-left corner of the analyzed region. Size of the region is a original window size scaled by
the currenly set scale. The current window size may be retrieved using the cvGetHaarClas-
sifierCascadeWindowSize function

start stage Initial zero-based index of the cascade stage to start from. The function assumes
that all the previous stages are passed. This feature is used internally by cvHaarDetectOb-
jects for better processor cache utilization

The function runs the Haar classifier cascade at a single image location. Before using this
function the integral images and the appropriate scale (window size) should be set using cvSe-
tImagesForHaarClassifierCascade. The function returns a positive value if the analyzed rectangle
passed all the classifier stages (it is a candidate) and a zero or negative value otherwise.
Chapter 6

video. Video Analysis

6.1 Motion Analysis and Object Tracking

cvCalcGlobalOrientation (view/add comments)

Calculates the global motion orientation of some selected region.

double cvCalcGlobalOrientation(
const CvArr* orientation,
const CvArr* mask,
const CvArr* mhi,
double timestamp,
double duration );

orientation Motion gradient orientation image; calculated by the function cvCalcMotionGradi-

ent

mask Mask image. It may be a conjunction of a valid gradient mask, obtained with cvCalcMotion-
Gradient and the mask of the region, whose direction needs to be calculated

mhi Motion history image

timestamp Current time in milliseconds or other units, it is better to store time passed to cvUp-
dateMotionHistory before and reuse it here, because running cvUpdateMotionHistory and
cvCalcMotionGradient on large images may take some time

371
372 CHAPTER 6. VIDEO. VIDEO ANALYSIS

duration Maximal duration of motion track in milliseconds, the same as cvUpdateMotionHistory

The function calculates the general motion direction in the selected region and returns the
angle between 0 degrees and 360 degrees . At first the function builds the orientation histogram
and finds the basic orientation as a coordinate of the histogram maximum. After that the function
calculates the shift relative to the basic orientation as a weighted sum of all of the orientation
vectors: the more recent the motion, the greater the weight. The resultant angle is a circular sum
of the basic orientation and the shift.

cvCalcMotionGradient (view/add comments)

Calculates the gradient orientation of a motion history image.

void cvCalcMotionGradient(
const CvArr* mhi,
CvArr* mask,
CvArr* orientation,
double delta1,
double delta2,
int apertureSize=3 );

mhi Motion history image

mask Mask image; marks pixels where the motion gradient data is correct; output parameter

orientation Motion gradient orientation image; contains angles from 0 to 360 degrees

delta1 See below

delta2 See below

apertureSize Aperture size of derivative operators used by the function: CV SCHARR, 1, 3, 5

or 7 (see cvSobel)

The function calculates the derivatives Dx and Dy of mhi and then calculates gradient orien-
tation as:

Dy(x, y)
orientation(x, y) = arctan
Dx(x, y)
6.1. MOTION ANALYSIS AND OBJECT TRACKING 373

where both Dx(x, y) and Dy(x, y) signs are taken into account (as in the cvCartToPolar func-
tion). After that mask is filled to indicate where the orientation is valid (see the delta1 and
delta2 description).
The function finds the minimum (m(x, y)) and maximum (M (x, y)) mhi values over each pixel
(x, y) neighborhood and assumes the gradient is valid only if

min(delta1, delta2) ≤ M (x, y) − m(x, y) ≤ max(delta1, delta2).

cvCalcOpticalFlowBM (view/add comments)<