It took me a while to figure out what was meant with

    OpenCV Error: Assertion failed (i < 0) in getMat

While searching for this error message I found [a list of error
messages](https://adventuresandwhathaveyou.wordpress.com/2014/03/14/opencv-error-messages-suck/)
which also explained what the problem was: The data type for `rvecs` was
not a simple `cv::Mat` but a `std::vector<cv::Mat>`.

After I fixed that, I got the next error message:

    OpenCV Error: Assertion failed (ni > 0 && ni == ni1) in
    collectCalibrationData, file
    /build/buildd/opencv-2.4.9+dfsg/modules/calib3d/src/calibration.cpp,
    line 3193

The problem here was that my data type for the `objectPoints` was just
`vector<Vec3f>` and not `vector<vector<Vec3f>>`.

In order to save other people the time looking for this, I added
explicit examples of the needed data types into the documentation of the
function. I had to re-read the current version a couple of times until I
can read the needed levels of `vector<>`. Having this example would have
really helped me there.

Conflicts:
	modules/calib3d/include/opencv2/calib3d.hpp

Updated the documents to give warning to the users of `findHomography` that the function may return an empty matrix in some cases. 
The user must take care of checking that.

The `calib3d.hpp` has a definition of the constant that does not contain the prefix "CV_".
The affected methods were `findHomography` and `findEssentialMat`.
Now the documentation updates the definition of the constants to conform to the header.

Fixed inconsistency with flag names for solvePnP. 
The default value for the function lacks the CV_ prefix. The code checks against "ITERATIVE". The suggested values for the parameters *include* the prefix.
Even though the enum CV_ITERATIVE (+ CV_P3P, CV_EPNP) = ITERATIVE (& P3P, EPNP), lets show to the users only one of them.
Now the user sees only {ITERATIVE, P3P, EPNP}.

Added sample of work of Fisheye::undistortImage and its description to documentation. Removed readPoints and readExtrinsic (useless)

Added function decomposeHomographyMat. New files added are homography_decomp.cpp and test_homography_decomp.cpp.
Modified files calib3d.hpp and camera_calibration_and_3d_reconstruction.rst.