cv::PCA::PCA()

PCA::PCA();
PCA::PCA(
  cv::InputArray data,                    // Data, as rows or cols in 2d array
  cv::InputArray mean,                    // average, if known, 1-by-n or n-by-1
  int            flags,                   // Are vectors rows or cols of 'data'
  int            maxComponents = 0        // Max dimensions to retain
);

The PCA object has a default constructor, cv::PCA(), which simply builds the PCA object and initializes the empty structure. The second form executes the default construction, then immediately proceeds to pass its arguments to PCA::operator()() (discussed next). 

cv::PCA::operator()()

PCA::operator()(
  cv::InputArray data,                    // Data, as rows or cols in 2d array
  cv::InputArray mean,                    // average, if known, 1-by-n or n-by-1
  int            flags,                   // Are vectors rows or cols of 'data'
  int            maxComponents = 0        // Max dimensions to retain
);

The overloaded operator()() for PCA builds the model of the distribution inside of the PCA object. The data argument is an array containing all of the samples that constitute the distribution. Optionally, mean, a second array that contains the mean value in each dimension, can be supplied (mean can either be n × 1 or 1 × n). The data can be arranged as an n × D (n rows of samples, each of D dimensions) or D × n array (n columns of samples, each of D dimensions). The flags argument is currently used only to specify the arrangement of the data in data and mean. In particular, flags can be set to either cv::PCA_DATA_AS_ROW or cv::PCA_DATA_AS_COL, to indicate that either data is n × D and mean is n × 1 or data is D × n and mean is 1 × n, respectively. The final argument, maxComponents, specifies the maximum number of components (dimensions) that PCA should retain. By default, all of the components are retained.

cv::PCA::project()

cv::Mat PCA::project(                     // Return results, as a 2d matrix
  cv::InputArray  vec                     // points to project, rows or cols, 2d
) const;

void PCA::project(
  cv::InputArray  vec                     // points to project, rows or cols, 2d
  cv::OutputArray result                  // Result of projection, reduced space
) const;

Once you have loaded your reference distribution with cv::PCA::operator()(), you can start asking the PCA object to do useful things for you like compute the KLT projection of some set of vectors onto the basis vectors computed by the principal component analysis. The cv::PCA::project() function has two forms; the first returns a matrix containing the results of the projections, while the second writes the results to a matrix you provide. The advantage of the first form is that you can use it in matrix expressions.

The vec argument contains the input vectors. vec is required to have the same number of dimensions and the same “orientation” as the data array that was passed to PCA when the distribution was first analyzed (i.e., if your data was columns when you called cv::PCA::operator()(), vec should also have the data arranged into columns).

The returned array will have the same number of objects as vec with the same orientation, but the dimensionality of each object will be whatever was passed to maxComponents when the PCA object was first configured with cv::PCA::operator()().

cv::PCA::backProject()

cv::Mat PCA::backProject(             // Return results, as a 2d matrix
  cv::InputArray  vec                 // Result of projection, reduced space
} const;

void PCA::backProject(
  cv::InputArray  vec                 // Result of projection, reduced space
  cv::OutputArray result              // "reconstructed" vectors, full dimension
) const;

The cv::PCA::backProject() function performs the reverse operation of cv::PCA::project(), with the analogous restrictions on the input and output arrays. The vec argument contains the input vectors, which this time are from the projected space. They will have the same number of dimensions as you specified with maxComponents when you configured the PCA object and the same “orientation” as the data array that was passed to PCA when the distribution was first analyzed (i.e., if your data was columns when you called cv::PCA::operator(), vec should also have the data arranged into columns).

The returned array will have the same number of objects as vec with the same orientation, but the dimensionality of each object will be the dimensionality of the original data you gave to the PCA object when the PCA object was first configured with cv::PCA::operator()().

cv::SVD::operator()()

SVD::& SVD::operator() (
  cv::InputArray A,                     // Linear system, array to be decomposed
  int            flags = 0              // what to construct, can A be scratch
);

The operator cv::SVD::operator()() passes to the cv::SVD object the matrix to be decomposed. The matrix A, as described earlier, is decomposed into a matrix U, a matrix V (actually the transpose of V, which we will call Vt), and a set of singular values (which are the diagonal elements of the matrix W).

The flags can be any one of cv::SVD::MODIFY_A, cv::SVD::NO_UV, or cv::SVD::FULL_UV. The latter two are mutually exclusive, but either can be combined with the first. The flag cv::SVD::MODIFY_A indicates that it is OK to modify the matrix A when computing. This speeds up computation a bit and saves some memory. It is more important when the input matrix is already very large. The flag cv::SVD::NO_UV tells cv::SVD to not explicitly compute the matrices U and Vt, while the flag cv::SVD::FULL_UV indicates that not only would you like U and Vt computed, but that you would also like them to be represented as full-size square orthogonal matrices.

cv::SVD::compute()

void SVD::compute(
  cv::InputArray  A,                // Linear system, array to be decomposed
  cv::OutputArray W,                // Output array 'W', singular values
  cv::OutputArray U,                // Output array 'U', left singular vectors
  cv::OutputArray Vt,               // Output array 'Vt', right singular vectors
  int             flags = 0         // what to construct, and if A can be scratch
);

This function is an alternative to using cv::SVD::operator()() to decompose the matrix A. The primary difference is that the matrices W, U, and Vt are stored in the user-supplied arrays, rather than being kept internally. The flags supported are exactly those supported by cv::SVD::operator()().

cv::SVD::solveZ()

void SVD::solveZ(
  cv::InputArray  A,                // Linear system, array to be decomposed
  cv::OutputArray z                 // One possible solution (unit length)
);

Given an underdetermined (singular) linear system, cv::SVD::solveZ() will (attempt to) find a unit length solution of and place the solution in the array z. Because the linear system is singular, however, it may have no solution, or it may have an infinite family of solutions. cv::SVD::solveZ() will find a solution, if one exists. If no solution exists, then the return value will be a vector that minimizes , even if this is not, in fact, zero.

cv::SVD::backSubst()

void SVD::backSubst(
  cv::InputArray  b,                // Righthand side of linear system
  cv::OutputArray x                 // Found solution to linear system
);

void SVD::backSubst(
  cv::InputArray  W,                // Output array 'W', singular values
  cv::InputArray  U,                // Output array 'U', left singular vectors
  cv::InputArray  Vt,               // Output array 'Vt', right singular vectors
  cv::InputArray  b,                // Righthand side of linear system
  cv::OutputArray x                 // Found solution to linear system
);

Assuming that the matrix A has been previously passed to the cv::SVD object (and thus decomposed into U, W, and Vt), the first form of cv::SVD::backSubst() attempts to solve the system:

The second form does the same thing, but expects the matrices W, U, and Vt to be passed to it as arguments. The actual method of computing dst is to evaluate the following expression:

This method produces a pseudosolution for an overdetermined system, which is the best solution in the sense of minimizing the least-squares error.⁵ Of course, it will also exactly solve a correctly determined linear system.

cv::theRNG()

cv::RNG& theRNG( void );                  // Return a random number generator

The cv::theRNG() function returns the default random number generator for the thread from which it was called. OpenCV automatically creates one instance of cv::RNG for each thread in execution. This is the same random number generator that is implicitly accessed by functions like cv::randu() or cv::randn(). Those functions are convenient if you want a single number or to initialize a single array. However, if you have a loop of your own that needs to generate a lot of random numbers, you are better off grabbing a reference to a random number generator—in this case, the default generator, but you could use your own instead—and using RNG::operator T() to get your random numbers (more on that operator shortly).

cv::RNG()

cv::RNG::RNG( void );
cv::RNG::RNG( uint64 state );             // create using the seed 'state'

You can create an RNG object with either the default constructor, or by passing it a 64-bit unsigned integer that it will use as the seed of the random number sequence. If you call the default constructor (or pass 0 to the second variation) the generator will initialize with a standardized value.⁶

cv::RNG::operator T(), where T is your favorite type

cv::RNG::operator uchar();
cv::RNG::operator schar();
cv::RNG::operator ushort();
cv::RNG::operator short int();
cv::RNG::operator int();
cv::RNG::operator unsigned();
cv::RNG::operator float();
cv::RNG::operator double();

cv::RNG::operator T() is really a set of different methods that return a new random number from cv::RNG of some specific type. Each of these is an overloaded cast operator, so in effect you cast the RNG object to whatever type you want, as shown in Example 7-1. (The style of the cast operation is up to you; this example shows both the int(x) and the (int)x forms.)

cv::RNG rng = cv::theRNG();
cout << "An integer:      " << (int)rng   << endl;
cout << "Another integer: " << int(rng)   << endl;
cout << "A float:         " << (float)rng << endl;
cout << "Another float:   " << float(rng) << endl;

When integer types are generated, they will be generated (using the MWC algorithm described earlier and thus uniformly) across the entire range of available values. When floating-point types are generated, they will always be in the range from the interval [0.0, 1.0).⁷

cv::RNG::operator()

unsigned int cv::RNG::operator()();       // Return random value from 0-UINT_MAX
unsigned int cv::RNG::operator()( unsigned int N );  // Return value from 0-(N-1)

When you are generating integer random numbers, the overloaded operator()() allows a convenient way to just grab another one. In essence, calling my_rng() is equivalent to calling (unsigned int)my_rng. The somewhat-more-interesting form of cv::RNG::operator()() takes an integer argument N. This form returns (using the MWC algorithm described earlier and thus uniformly) a random unsigned integer modulo N. Thus, the range of integers returned by my_rng( N ) is then the range of integers from 0 to N-1.

cv::RNG::uniform()

int    cv::RNG::uniform( int a,    int b    );     // Return value from a-(b-1)
float  cv::RNG::uniform( float a,  float b  );     // Return value in range [a,b)
double cv::RNG::uniform( double a, double b );     // Return value in range [a,b)

This function allows you to generate a random number uniformly (using the MWC algorithm) in the interval [a, b).

cv::RNG::gaussian()

double  cv::RNG::gaussian( double sigma ); // Gaussian number, zero mean,
                                           // std-dev='sigma'

This function allows you to generate a random number from a zero-mean Gaussian distribution (using the Ziggurat algorithm) with standard deviation sigma.

cv::RNG::fill()

void  cv::RNG::fill(
  InputOutputArray mat,             // Input array, values will be overwritten
  int              distType,        // Type of distribution (Gaussian or uniform)
  InputArray       a,               // min (uniform) or mean (Gaussian)
  InputArray       b                // max (uniform) or std-deviation (Gaussian)
 );

The cv::RNG::fill() algorithm fills a matrix mat of up to four channels with random numbers drawn from a specific distribution. That distribution is selected by the distType argument, which can be either cv::RNG::UNIFORM or cv::RNG::NORMAL. In the case of the uniform distribution, each element of mat will be filled with a random value generated from the interval . In the case of the Gaussian (cv::RNG::NORMAL) distribution, each element is generated from a distribution with the mean taken from a and the standard deviation taken from b:. It is important to note that the arrays a and b are not of the dimension of mat; instead, they are n_c × 1 or 1 × n_c where n_c is the number of channels in mat (i.e., there is not a separate distribution for each element of mat; a and b specify one distribution, not one distribution for every element of mat.)