~paparazzi-uav/paparazzi/v5.0-manual

\f[\begin{array}{l} \theta \leftarrow norm(r) \\ r \leftarrow r/ \theta \\ R = \cos{\theta} I + (1- \cos{\theta} ) r r^T + \sin{\theta} \vecthreethree{0}{-r_z}{r_y}{r_z}{0}{-r_x}{-r_y}{r_x}{0} \end{array}\f]

287

288

Inverse transformation can be also done easily, since

289

290

\f[\sin ( \theta ) \vecthreethree{0}{-r_z}{r_y}{r_z}{0}{-r_x}{-r_y}{r_x}{0} = \frac{R - R^T}{2}\f]

291

292

A rotation vector is a convenient and most compact representation of a rotation matrix (since any

293

rotation matrix has just 3 degrees of freedom). The representation is used in the global 3D geometry

294

optimization procedures like calibrateCamera, stereoCalibrate, or solvePnP .

295

296

CV_EXPORTS_W void Rodrigues( InputArray src, OutputArray dst, OutputArray jacobian = noArray() );

297

298

/** @brief Finds a perspective transformation between two planes.

299

300

@param srcPoints Coordinates of the points in the original plane, a matrix of the type CV_32FC2

301

or vector\<Point2f\> .

302

@param dstPoints Coordinates of the points in the target plane, a matrix of the type CV_32FC2 or

303

a vector\<Point2f\> .

304

@param method Method used to computed a homography matrix. The following methods are possible:

305

- **0** - a regular method using all the points

306

- **RANSAC** - RANSAC-based robust method

307

- **LMEDS** - Least-Median robust method

308

- **RHO** - PROSAC-based robust method

309

@param ransacReprojThreshold Maximum allowed reprojection error to treat a point pair as an inlier

310

(used in the RANSAC and RHO methods only). That is, if

311

\f[\| \texttt{dstPoints} _i - \texttt{convertPointsHomogeneous} ( \texttt{H} * \texttt{srcPoints} _i) \| > \texttt{ransacReprojThreshold}\f]

312

then the point \f$i\f$ is considered an outlier. If srcPoints and dstPoints are measured in pixels,

313

it usually makes sense to set this parameter somewhere in the range of 1 to 10.

314

@param mask Optional output mask set by a robust method ( RANSAC or LMEDS ). Note that the input

315

mask values are ignored.

316

@param maxIters The maximum number of RANSAC iterations, 2000 is the maximum it can be.

317

@param confidence Confidence level, between 0 and 1.

318

319

The functions find and return the perspective transformation \f$H\f$ between the source and the

320

destination planes:

321

322

\f[s_i \vecthree{x'_i}{y'_i}{1} \sim H \vecthree{x_i}{y_i}{1}\f]

323

324

so that the back-projection error

325

326

\f[\sum _i \left ( x'_i- \frac{h_{11} x_i + h_{12} y_i + h_{13}}{h_{31} x_i + h_{32} y_i + h_{33}} \right )^2+ \left ( y'_i- \frac{h_{21} x_i + h_{22} y_i + h_{23}}{h_{31} x_i + h_{32} y_i + h_{33}} \right )^2\f]

327

328

is minimized. If the parameter method is set to the default value 0, the function uses all the point

329

pairs to compute an initial homography estimate with a simple least-squares scheme.

330

331

However, if not all of the point pairs ( \f$srcPoints_i\f$, \f$dstPoints_i\f$ ) fit the rigid perspective

332

transformation (that is, there are some outliers), this initial estimate will be poor. In this case,

333

you can use one of the three robust methods. The methods RANSAC, LMeDS and RHO try many different

334

random subsets of the corresponding point pairs (of four pairs each), estimate the homography matrix

335

using this subset and a simple least-square algorithm, and then compute the quality/goodness of the

336

computed homography (which is the number of inliers for RANSAC or the median re-projection error for

337

LMeDs). The best subset is then used to produce the initial estimate of the homography matrix and

338

the mask of inliers/outliers.

339

340

Regardless of the method, robust or not, the computed homography matrix is refined further (using

341

inliers only in case of a robust method) with the Levenberg-Marquardt method to reduce the

342

re-projection error even more.

343

344

The methods RANSAC and RHO can handle practically any ratio of outliers but need a threshold to

345

distinguish inliers from outliers. The method LMeDS does not need any threshold but it works

346

correctly only when there are more than 50% of inliers. Finally, if there are no outliers and the

347

noise is rather small, use the default method (method=0).

348

349

The function is used to find initial intrinsic and extrinsic matrices. Homography matrix is

350

determined up to a scale. Thus, it is normalized so that \f$h_{33}=1\f$. Note that whenever an H matrix

351

cannot be estimated, an empty one will be returned.

352

353

@sa

354

getAffineTransform, getPerspectiveTransform, estimateRigidTransform, warpPerspective,

355

perspectiveTransform

356

357

@note

358

- A example on calculating a homography for image matching can be found at

359

opencv_source_code/samples/cpp/video_homography.cpp

360

361

362

CV_EXPORTS_W Mat findHomography( InputArray srcPoints, InputArray dstPoints,

363

int method = 0, double ransacReprojThreshold = 3,

364

OutputArray mask=noArray(), const int maxIters = 2000,

365

const double confidence = 0.995);

366

367

/** @overload */

368

CV_EXPORTS Mat findHomography( InputArray srcPoints, InputArray dstPoints,

369

OutputArray mask, int method = 0, double ransacReprojThreshold = 3 );

370

371

/** @brief Computes an RQ decomposition of 3x3 matrices.

372

373

@param src 3x3 input matrix.

374

@param mtxR Output 3x3 upper-triangular matrix.

375

@param mtxQ Output 3x3 orthogonal matrix.

376

@param Qx Optional output 3x3 rotation matrix around x-axis.

377

@param Qy Optional output 3x3 rotation matrix around y-axis.

378

@param Qz Optional output 3x3 rotation matrix around z-axis.

379

380

The function computes a RQ decomposition using the given rotations. This function is used in

381

decomposeProjectionMatrix to decompose the left 3x3 submatrix of a projection matrix into a camera

382

and a rotation matrix.

383

384

It optionally returns three rotation matrices, one for each axis, and the three Euler angles in

385

degrees (as the return value) that could be used in OpenGL. Note, there is always more than one

386

sequence of rotations about the three principle axes that results in the same orientation of an

387

object, eg. see @cite Slabaugh . Returned tree rotation matrices and corresponding three Euler angules

388

are only one of the possible solutions.

389

390

CV_EXPORTS_W Vec3d RQDecomp3x3( InputArray src, OutputArray mtxR, OutputArray mtxQ,

391

OutputArray Qx = noArray(),

392

OutputArray Qy = noArray(),

393

OutputArray Qz = noArray());

394

395

/** @brief Decomposes a projection matrix into a rotation matrix and a camera matrix.

396

397

@param projMatrix 3x4 input projection matrix P.

398

@param cameraMatrix Output 3x3 camera matrix K.

399

@param rotMatrix Output 3x3 external rotation matrix R.

400

@param transVect Output 4x1 translation vector T.

401

@param rotMatrixX Optional 3x3 rotation matrix around x-axis.

402

@param rotMatrixY Optional 3x3 rotation matrix around y-axis.

403

@param rotMatrixZ Optional 3x3 rotation matrix around z-axis.

404

@param eulerAngles Optional three-element vector containing three Euler angles of rotation in

405

degrees.

406

407

The function computes a decomposition of a projection matrix into a calibration and a rotation

408

matrix and the position of a camera.

409

410

It optionally returns three rotation matrices, one for each axis, and three Euler angles that could

411

be used in OpenGL. Note, there is always more than one sequence of rotations about the three

412

principle axes that results in the same orientation of an object, eg. see @cite Slabaugh . Returned

413

tree rotation matrices and corresponding three Euler angules are only one of the possible solutions.

414

415

The function is based on RQDecomp3x3 .

416

417

CV_EXPORTS_W void decomposeProjectionMatrix( InputArray projMatrix, OutputArray cameraMatrix,

418

OutputArray rotMatrix, OutputArray transVect,

419

OutputArray rotMatrixX = noArray(),

420

OutputArray rotMatrixY = noArray(),

421

OutputArray rotMatrixZ = noArray(),

422

OutputArray eulerAngles =noArray() );

423

424

/** @brief Computes partial derivatives of the matrix product for each multiplied matrix.

425

426

@param A First multiplied matrix.

427

@param B Second multiplied matrix.

428

@param dABdA First output derivative matrix d(A\*B)/dA of size

429

\f$\texttt{A.rows*B.cols} \times {A.rows*A.cols}\f$ .

430

@param dABdB Second output derivative matrix d(A\*B)/dB of size

431

\f$\texttt{A.rows*B.cols} \times {B.rows*B.cols}\f$ .

432

433

The function computes partial derivatives of the elements of the matrix product \f$A*B\f$ with regard to

434

the elements of each of the two input matrices. The function is used to compute the Jacobian

435

matrices in stereoCalibrate but can also be used in any other similar optimization function.

436

437

CV_EXPORTS_W void matMulDeriv( InputArray A, InputArray B, OutputArray dABdA, OutputArray dABdB );

438

439

/** @brief Combines two rotation-and-shift transformations.

440

441

@param rvec1 First rotation vector.

442

@param tvec1 First translation vector.

443

@param rvec2 Second rotation vector.

444

@param tvec2 Second translation vector.

445

@param rvec3 Output rotation vector of the superposition.

446

@param tvec3 Output translation vector of the superposition.

447

@param dr3dr1

448

@param dr3dt1

449

@param dr3dr2

450

@param dr3dt2

451

@param dt3dr1

452

@param dt3dt1

453

@param dt3dr2

454

@param dt3dt2 Optional output derivatives of rvec3 or tvec3 with regard to rvec1, rvec2, tvec1 and

455

tvec2, respectively.

456

457

The functions compute:

458

459

\f[\begin{array}{l} \texttt{rvec3} = \mathrm{rodrigues} ^{-1} \left ( \mathrm{rodrigues} ( \texttt{rvec2} ) \cdot \mathrm{rodrigues} ( \texttt{rvec1} ) \right ) \\ \texttt{tvec3} = \mathrm{rodrigues} ( \texttt{rvec2} ) \cdot \texttt{tvec1} + \texttt{tvec2} \end{array} ,\f]

460

461

where \f$\mathrm{rodrigues}\f$ denotes a rotation vector to a rotation matrix transformation, and

462

\f$\mathrm{rodrigues}^{-1}\f$ denotes the inverse transformation. See Rodrigues for details.

463

464

Also, the functions can compute the derivatives of the output vectors with regards to the input

465

vectors (see matMulDeriv ). The functions are used inside stereoCalibrate but can also be used in

466

your own code where Levenberg-Marquardt or another gradient-based solver is used to optimize a

467

function that contains a matrix multiplication.

468

469

CV_EXPORTS_W void composeRT( InputArray rvec1, InputArray tvec1,

470

InputArray rvec2, InputArray tvec2,

471

OutputArray rvec3, OutputArray tvec3,

472

OutputArray dr3dr1 = noArray(), OutputArray dr3dt1 = noArray(),

473

OutputArray dr3dr2 = noArray(), OutputArray dr3dt2 = noArray(),

474

OutputArray dt3dr1 = noArray(), OutputArray dt3dt1 = noArray(),

475

OutputArray dt3dr2 = noArray(), OutputArray dt3dt2 = noArray() );

476

477

/** @brief Projects 3D points to an image plane.

478

479

@param objectPoints Array of object points, 3xN/Nx3 1-channel or 1xN/Nx1 3-channel (or

480

vector\<Point3f\> ), where N is the number of points in the view.

481

@param rvec Rotation vector. See Rodrigues for details.

482

@param tvec Translation vector.

483

@param cameraMatrix Camera matrix \f$A = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{_1}\f$ .

484

@param distCoeffs Input vector of distortion coefficients

485

\f$(k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6 [, s_1, s_2, s_3, s_4[, \tau_x, \tau_y]]]])\f$ of

486

4, 5, 8, 12 or 14 elements. If the vector is empty, the zero distortion coefficients are assumed.

487

@param imagePoints Output array of image points, 2xN/Nx2 1-channel or 1xN/Nx1 2-channel, or

488

vector\<Point2f\> .

489

@param jacobian Optional output 2Nx(10+\<numDistCoeffs\>) jacobian matrix of derivatives of image

490

points with respect to components of the rotation vector, translation vector, focal lengths,

491

coordinates of the principal point and the distortion coefficients. In the old interface different

492

components of the jacobian are returned via different output parameters.

493

@param aspectRatio Optional "fixed aspect ratio" parameter. If the parameter is not 0, the

494

function assumes that the aspect ratio (*fx/fy*) is fixed and correspondingly adjusts the jacobian

495

matrix.

496

497

The function computes projections of 3D points to the image plane given intrinsic and extrinsic

498

camera parameters. Optionally, the function computes Jacobians - matrices of partial derivatives of

499

image points coordinates (as functions of all the input parameters) with respect to the particular

500

parameters, intrinsic and/or extrinsic. The Jacobians are used during the global optimization in

501

calibrateCamera, solvePnP, and stereoCalibrate . The function itself can also be used to compute a

502

re-projection error given the current intrinsic and extrinsic parameters.

503

504

@note By setting rvec=tvec=(0,0,0) or by setting cameraMatrix to a 3x3 identity matrix, or by

505

passing zero distortion coefficients, you can get various useful partial cases of the function. This

506

means that you can compute the distorted coordinates for a sparse set of points or apply a

507

perspective transformation (and also compute the derivatives) in the ideal zero-distortion setup.

508

509

CV_EXPORTS_W void projectPoints( InputArray objectPoints,

510

InputArray rvec, InputArray tvec,

511

InputArray cameraMatrix, InputArray distCoeffs,

512

OutputArray imagePoints,

513

OutputArray jacobian = noArray(),

514

double aspectRatio = 0 );

515

516

/** @brief Finds an object pose from 3D-2D point correspondences.

517

518

@param objectPoints Array of object points in the object coordinate space, 3xN/Nx3 1-channel or

519

1xN/Nx1 3-channel, where N is the number of points. vector\<Point3f\> can be also passed here.

520

@param imagePoints Array of corresponding image points, 2xN/Nx2 1-channel or 1xN/Nx1 2-channel,

521

where N is the number of points. vector\<Point2f\> can be also passed here.

522

@param cameraMatrix Input camera matrix \f$A = \vecthreethree{fx}{0}{cx}{0}{fy}{cy}{0}{0}{1}\f$ .

523

@param distCoeffs Input vector of distortion coefficients

524

\f$(k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6 [, s_1, s_2, s_3, s_4[, \tau_x, \tau_y]]]])\f$ of

525

4, 5, 8, 12 or 14 elements. If the vector is NULL/empty, the zero distortion coefficients are

526

assumed.

527

@param rvec Output rotation vector (see Rodrigues ) that, together with tvec , brings points from

528

the model coordinate system to the camera coordinate system.

529

@param tvec Output translation vector.

530

@param useExtrinsicGuess Parameter used for SOLVEPNP_ITERATIVE. If true (1), the function uses

531

the provided rvec and tvec values as initial approximations of the rotation and translation

532

vectors, respectively, and further optimizes them.

533

@param flags Method for solving a PnP problem:

534

- **SOLVEPNP_ITERATIVE** Iterative method is based on Levenberg-Marquardt optimization. In

535

this case the function finds such a pose that minimizes reprojection error, that is the sum

536

of squared distances between the observed projections imagePoints and the projected (using

537

projectPoints ) objectPoints .

538

- **SOLVEPNP_P3P** Method is based on the paper of X.S. Gao, X.-R. Hou, J. Tang, H.-F. Chang

539

"Complete Solution Classification for the Perspective-Three-Point Problem". In this case the

540

function requires exactly four object and image points.

541

- **SOLVEPNP_EPNP** Method has been introduced by F.Moreno-Noguer, V.Lepetit and P.Fua in the

542

paper "EPnP: Efficient Perspective-n-Point Camera Pose Estimation".

543

- **SOLVEPNP_DLS** Method is based on the paper of Joel A. Hesch and Stergios I. Roumeliotis.

544

"A Direct Least-Squares (DLS) Method for PnP".

545

- **SOLVEPNP_UPNP** Method is based on the paper of A.Penate-Sanchez, J.Andrade-Cetto,

546

F.Moreno-Noguer. "Exhaustive Linearization for Robust Camera Pose and Focal Length

547

Estimation". In this case the function also estimates the parameters \f$f_x\f$ and \f$f_y\f$

548

assuming that both have the same value. Then the cameraMatrix is updated with the estimated

549

focal length.

550

551

The function estimates the object pose given a set of object points, their corresponding image

552

projections, as well as the camera matrix and the distortion coefficients.

553

554

@note

555

- An example of how to use solvePnP for planar augmented reality can be found at

556

opencv_source_code/samples/python/plane_ar.py

557

- If you are using Python:

558

- Numpy array slices won't work as input because solvePnP requires contiguous

559

arrays (enforced by the assertion using cv::Mat::checkVector() around line 55 of

560

modules/calib3d/src/solvepnp.cpp version 2.4.9)

561

- The P3P algorithm requires image points to be in an array of shape (N,1,2) due

562

to its calling of cv::undistortPoints (around line 75 of modules/calib3d/src/solvepnp.cpp version 2.4.9)

563

which requires 2-channel information.

564

- Thus, given some data D = np.array(...) where D.shape = (N,M), in order to use a subset of

565

it as, e.g., imagePoints, one must effectively copy it into a new array: imagePoints =

566

np.ascontiguousarray(D[:,:2]).reshape((N,1,2))

567

568

CV_EXPORTS_W bool solvePnP( InputArray objectPoints, InputArray imagePoints,

569

InputArray cameraMatrix, InputArray distCoeffs,

570

OutputArray rvec, OutputArray tvec,

571

bool useExtrinsicGuess = false, int flags = SOLVEPNP_ITERATIVE );

572

573

/** @brief Finds an object pose from 3D-2D point correspondences using the RANSAC scheme.

574

575

@param objectPoints Array of object points in the object coordinate space, 3xN/Nx3 1-channel or

576

1xN/Nx1 3-channel, where N is the number of points. vector\<Point3f\> can be also passed here.

577

@param imagePoints Array of corresponding image points, 2xN/Nx2 1-channel or 1xN/Nx1 2-channel,

578

where N is the number of points. vector\<Point2f\> can be also passed here.

579

@param cameraMatrix Input camera matrix \f$A = \vecthreethree{fx}{0}{cx}{0}{fy}{cy}{0}{0}{1}\f$ .

580

@param distCoeffs Input vector of distortion coefficients

581

\f$(k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6 [, s_1, s_2, s_3, s_4[, \tau_x, \tau_y]]]])\f$ of

582

4, 5, 8, 12 or 14 elements. If the vector is NULL/empty, the zero distortion coefficients are

583

assumed.

584

@param rvec Output rotation vector (see Rodrigues ) that, together with tvec , brings points from

585

the model coordinate system to the camera coordinate system.

586

@param tvec Output translation vector.

587

@param useExtrinsicGuess Parameter used for SOLVEPNP_ITERATIVE. If true (1), the function uses

588

the provided rvec and tvec values as initial approximations of the rotation and translation

589

vectors, respectively, and further optimizes them.

590

@param iterationsCount Number of iterations.

591

@param reprojectionError Inlier threshold value used by the RANSAC procedure. The parameter value

592

is the maximum allowed distance between the observed and computed point projections to consider it

593

an inlier.

594

@param confidence The probability that the algorithm produces a useful result.

595

@param inliers Output vector that contains indices of inliers in objectPoints and imagePoints .

596

@param flags Method for solving a PnP problem (see solvePnP ).

597

598

The function estimates an object pose given a set of object points, their corresponding image

599

projections, as well as the camera matrix and the distortion coefficients. This function finds such

600

a pose that minimizes reprojection error, that is, the sum of squared distances between the observed

601

projections imagePoints and the projected (using projectPoints ) objectPoints. The use of RANSAC

602

makes the function resistant to outliers.

603

604

@note

605

- An example of how to use solvePNPRansac for object detection can be found at

606

opencv_source_code/samples/cpp/tutorial_code/calib3d/real_time_pose_estimation/

607

608

CV_EXPORTS_W bool solvePnPRansac( InputArray objectPoints, InputArray imagePoints,

609

InputArray cameraMatrix, InputArray distCoeffs,

610

OutputArray rvec, OutputArray tvec,

611

bool useExtrinsicGuess = false, int iterationsCount = 100,

612

float reprojectionError = 8.0, double confidence = 0.99,

613

OutputArray inliers = noArray(), int flags = SOLVEPNP_ITERATIVE );

614

615

/** @brief Finds an initial camera matrix from 3D-2D point correspondences.

616

617

@param objectPoints Vector of vectors of the calibration pattern points in the calibration pattern

618

coordinate space. In the old interface all the per-view vectors are concatenated. See

619

calibrateCamera for details.

620

@param imagePoints Vector of vectors of the projections of the calibration pattern points. In the

621

old interface all the per-view vectors are concatenated.

622

@param imageSize Image size in pixels used to initialize the principal point.

623

@param aspectRatio If it is zero or negative, both \f$f_x\f$ and \f$f_y\f$ are estimated independently.

624

Otherwise, \f$f_x = f_y * \texttt{aspectRatio}\f$ .

625

626

The function estimates and returns an initial camera matrix for the camera calibration process.

627

Currently, the function only supports planar calibration patterns, which are patterns where each

628

object point has z-coordinate =0.

629

630

CV_EXPORTS_W Mat initCameraMatrix2D( InputArrayOfArrays objectPoints,

631

InputArrayOfArrays imagePoints,

632

Size imageSize, double aspectRatio = 1.0 );

633

634

/** @brief Finds the positions of internal corners of the chessboard.

635

636

@param image Source chessboard view. It must be an 8-bit grayscale or color image.

637

@param patternSize Number of inner corners per a chessboard row and column

638

( patternSize = cvSize(points_per_row,points_per_colum) = cvSize(columns,rows) ).

639

@param corners Output array of detected corners.

640

@param flags Various operation flags that can be zero or a combination of the following values:

641

- **CV_CALIB_CB_ADAPTIVE_THRESH** Use adaptive thresholding to convert the image to black

642

and white, rather than a fixed threshold level (computed from the average image brightness).

643

- **CV_CALIB_CB_NORMALIZE_IMAGE** Normalize the image gamma with equalizeHist before

644

applying fixed or adaptive thresholding.

645

- **CV_CALIB_CB_FILTER_QUADS** Use additional criteria (like contour area, perimeter,

646

square-like shape) to filter out false quads extracted at the contour retrieval stage.

647

- **CALIB_CB_FAST_CHECK** Run a fast check on the image that looks for chessboard corners,

648

and shortcut the call if none is found. This can drastically speed up the call in the

649

degenerate condition when no chessboard is observed.

650

651

The function attempts to determine whether the input image is a view of the chessboard pattern and

652

locate the internal chessboard corners. The function returns a non-zero value if all of the corners

653

are found and they are placed in a certain order (row by row, left to right in every row).

654

Otherwise, if the function fails to find all the corners or reorder them, it returns 0. For example,

655

a regular chessboard has 8 x 8 squares and 7 x 7 internal corners, that is, points where the black

656

squares touch each other. The detected coordinates are approximate, and to determine their positions

657

more accurately, the function calls cornerSubPix. You also may use the function cornerSubPix with

658

different parameters if returned coordinates are not accurate enough.

659

660

Sample usage of detecting and drawing chessboard corners: :

661

@code

662

Size patternsize(8,6); //interior number of corners

663

Mat gray = ....; //source image

664

vector<Point2f> corners; //this will be filled by the detected corners

665

666

//CALIB_CB_FAST_CHECK saves a lot of time on images

667

//that do not contain any chessboard corners

668

bool patternfound = findChessboardCorners(gray, patternsize, corners,

669

CALIB_CB_ADAPTIVE_THRESH + CALIB_CB_NORMALIZE_IMAGE

670

+ CALIB_CB_FAST_CHECK);

671

672

if(patternfound)

673

cornerSubPix(gray, corners, Size(11, 11), Size(-1, -1),

674

TermCriteria(CV_TERMCRIT_EPS + CV_TERMCRIT_ITER, 30, 0.1));

675

676

drawChessboardCorners(img, patternsize, Mat(corners), patternfound);

677

@endcode

678

@note The function requires white space (like a square-thick border, the wider the better) around

679

the board to make the detection more robust in various environments. Otherwise, if there is no

680

border and the background is dark, the outer black squares cannot be segmented properly and so the

681

square grouping and ordering algorithm fails.

682

683

CV_EXPORTS_W bool findChessboardCorners( InputArray image, Size patternSize, OutputArray corners,

684

int flags = CALIB_CB_ADAPTIVE_THRESH + CALIB_CB_NORMALIZE_IMAGE );

685

686

//! finds subpixel-accurate positions of the chessboard corners

687

CV_EXPORTS bool find4QuadCornerSubpix( InputArray img, InputOutputArray corners, Size region_size );

688

689

/** @brief Renders the detected chessboard corners.

690

691

@param image Destination image. It must be an 8-bit color image.

692

@param patternSize Number of inner corners per a chessboard row and column

693

(patternSize = cv::Size(points_per_row,points_per_column)).

694

@param corners Array of detected corners, the output of findChessboardCorners.

695

@param patternWasFound Parameter indicating whether the complete board was found or not. The

696

return value of findChessboardCorners should be passed here.

697

698

The function draws individual chessboard corners detected either as red circles if the board was not

699

found, or as colored corners connected with lines if the board was found.

700

701

CV_EXPORTS_W void drawChessboardCorners( InputOutputArray image, Size patternSize,

702

InputArray corners, bool patternWasFound );

703

704

/** @brief Finds centers in the grid of circles.

705

706

@param image grid view of input circles; it must be an 8-bit grayscale or color image.

707

@param patternSize number of circles per row and column

708

( patternSize = Size(points_per_row, points_per_colum) ).

709

@param centers output array of detected centers.

710

@param flags various operation flags that can be one of the following values:

711

- **CALIB_CB_SYMMETRIC_GRID** uses symmetric pattern of circles.

712

- **CALIB_CB_ASYMMETRIC_GRID** uses asymmetric pattern of circles.

713

- **CALIB_CB_CLUSTERING** uses a special algorithm for grid detection. It is more robust to

714

perspective distortions but much more sensitive to background clutter.

715

@param blobDetector feature detector that finds blobs like dark circles on light background.

716

717

The function attempts to determine whether the input image contains a grid of circles. If it is, the

718

function locates centers of the circles. The function returns a non-zero value if all of the centers

719

have been found and they have been placed in a certain order (row by row, left to right in every

720

row). Otherwise, if the function fails to find all the corners or reorder them, it returns 0.

721

722

Sample usage of detecting and drawing the centers of circles: :

723

@code

724

Size patternsize(7,7); //number of centers

725

Mat gray = ....; //source image

726

vector<Point2f> centers; //this will be filled by the detected centers

727

728

bool patternfound = findCirclesGrid(gray, patternsize, centers);

729

730

drawChessboardCorners(img, patternsize, Mat(centers), patternfound);

731

@endcode

732

@note The function requires white space (like a square-thick border, the wider the better) around

733

the board to make the detection more robust in various environments.

734

735

CV_EXPORTS_W bool findCirclesGrid( InputArray image, Size patternSize,

736

OutputArray centers, int flags = CALIB_CB_SYMMETRIC_GRID,

737

const Ptr<FeatureDetector> &blobDetector = SimpleBlobDetector::create());

738

739

/** @brief Finds the camera intrinsic and extrinsic parameters from several views of a calibration pattern.

740

741

@param objectPoints In the new interface it is a vector of vectors of calibration pattern points in

742

the calibration pattern coordinate space (e.g. std::vector<std::vector<cv::Vec3f>>). The outer

743

vector contains as many elements as the number of the pattern views. If the same calibration pattern

744

is shown in each view and it is fully visible, all the vectors will be the same. Although, it is

745

possible to use partially occluded patterns, or even different patterns in different views. Then,

746

the vectors will be different. The points are 3D, but since they are in a pattern coordinate system,

747

then, if the rig is planar, it may make sense to put the model to a XY coordinate plane so that

748

Z-coordinate of each input object point is 0.

749

In the old interface all the vectors of object points from different views are concatenated

750

together.

751

@param imagePoints In the new interface it is a vector of vectors of the projections of calibration

752

pattern points (e.g. std::vector<std::vector<cv::Vec2f>>). imagePoints.size() and

753

objectPoints.size() and imagePoints[i].size() must be equal to objectPoints[i].size() for each i.

754

In the old interface all the vectors of object points from different views are concatenated

755

together.

756

@param imageSize Size of the image used only to initialize the intrinsic camera matrix.

757

@param cameraMatrix Output 3x3 floating-point camera matrix

758

\f$A = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}\f$ . If CV\_CALIB\_USE\_INTRINSIC\_GUESS

759

and/or CV_CALIB_FIX_ASPECT_RATIO are specified, some or all of fx, fy, cx, cy must be

760

initialized before calling the function.

761

@param distCoeffs Output vector of distortion coefficients

762

\f$(k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6 [, s_1, s_2, s_3, s_4[, \tau_x, \tau_y]]]])\f$ of

763

4, 5, 8, 12 or 14 elements.

764

@param rvecs Output vector of rotation vectors (see Rodrigues ) estimated for each pattern view

765

(e.g. std::vector<cv::Mat>>). That is, each k-th rotation vector together with the corresponding

766

k-th translation vector (see the next output parameter description) brings the calibration pattern

767

from the model coordinate space (in which object points are specified) to the world coordinate

768

space, that is, a real position of the calibration pattern in the k-th pattern view (k=0.. *M* -1).

769

@param tvecs Output vector of translation vectors estimated for each pattern view.

770

@param flags Different flags that may be zero or a combination of the following values:

771

- **CV_CALIB_USE_INTRINSIC_GUESS** cameraMatrix contains valid initial values of

772

fx, fy, cx, cy that are optimized further. Otherwise, (cx, cy) is initially set to the image

773

center ( imageSize is used), and focal distances are computed in a least-squares fashion.

774

Note, that if intrinsic parameters are known, there is no need to use this function just to

775

estimate extrinsic parameters. Use solvePnP instead.

776

- **CV_CALIB_FIX_PRINCIPAL_POINT** The principal point is not changed during the global

777

optimization. It stays at the center or at a different location specified when

778

CV_CALIB_USE_INTRINSIC_GUESS is set too.

779

- **CV_CALIB_FIX_ASPECT_RATIO** The functions considers only fy as a free parameter. The

780

ratio fx/fy stays the same as in the input cameraMatrix . When

781

CV_CALIB_USE_INTRINSIC_GUESS is not set, the actual input values of fx and fy are

782

ignored, only their ratio is computed and used further.

783

- **CV_CALIB_ZERO_TANGENT_DIST** Tangential distortion coefficients \f$(p_1, p_2)\f$ are set

784

to zeros and stay zero.

785

- **CV_CALIB_FIX_K1,...,CV_CALIB_FIX_K6** The corresponding radial distortion

786

coefficient is not changed during the optimization. If CV_CALIB_USE_INTRINSIC_GUESS is

787

set, the coefficient from the supplied distCoeffs matrix is used. Otherwise, it is set to 0.

788

- **CV_CALIB_RATIONAL_MODEL** Coefficients k4, k5, and k6 are enabled. To provide the

789

backward compatibility, this extra flag should be explicitly specified to make the

790

calibration function use the rational model and return 8 coefficients. If the flag is not

791

set, the function computes and returns only 5 distortion coefficients.

792

- **CALIB_THIN_PRISM_MODEL** Coefficients s1, s2, s3 and s4 are enabled. To provide the

793

backward compatibility, this extra flag should be explicitly specified to make the

794

calibration function use the thin prism model and return 12 coefficients. If the flag is not

795

set, the function computes and returns only 5 distortion coefficients.

796

- **CALIB_FIX_S1_S2_S3_S4** The thin prism distortion coefficients are not changed during

797

the optimization. If CV_CALIB_USE_INTRINSIC_GUESS is set, the coefficient from the

798

supplied distCoeffs matrix is used. Otherwise, it is set to 0.

799

- **CALIB_TILTED_MODEL** Coefficients tauX and tauY are enabled. To provide the

800

backward compatibility, this extra flag should be explicitly specified to make the

801

calibration function use the tilted sensor model and return 14 coefficients. If the flag is not

802

set, the function computes and returns only 5 distortion coefficients.

803

- **CALIB_FIX_TAUX_TAUY** The coefficients of the tilted sensor model are not changed during

804

the optimization. If CV_CALIB_USE_INTRINSIC_GUESS is set, the coefficient from the

805

supplied distCoeffs matrix is used. Otherwise, it is set to 0.

806

@param criteria Termination criteria for the iterative optimization algorithm.

807

808

The function estimates the intrinsic camera parameters and extrinsic parameters for each of the

809

views. The algorithm is based on @cite Zhang2000 and @cite BouguetMCT . The coordinates of 3D object

810

points and their corresponding 2D projections in each view must be specified. That may be achieved

811

by using an object with a known geometry and easily detectable feature points. Such an object is

812

called a calibration rig or calibration pattern, and OpenCV has built-in support for a chessboard as

813

a calibration rig (see findChessboardCorners ). Currently, initialization of intrinsic parameters

814

(when CV_CALIB_USE_INTRINSIC_GUESS is not set) is only implemented for planar calibration

815

patterns (where Z-coordinates of the object points must be all zeros). 3D calibration rigs can also

816

be used as long as initial cameraMatrix is provided.

817

818

The algorithm performs the following steps:

819

820

- Compute the initial intrinsic parameters (the option only available for planar calibration

821

patterns) or read them from the input parameters. The distortion coefficients are all set to

822

zeros initially unless some of CV_CALIB_FIX_K? are specified.

823

824

- Estimate the initial camera pose as if the intrinsic parameters have been already known. This is

825

done using solvePnP .

826

827

- Run the global Levenberg-Marquardt optimization algorithm to minimize the reprojection error,

828

that is, the total sum of squared distances between the observed feature points imagePoints and

829

the projected (using the current estimates for camera parameters and the poses) object points

830

objectPoints. See projectPoints for details.

831

832

The function returns the final re-projection error.

833

834

@note

835

If you use a non-square (=non-NxN) grid and findChessboardCorners for calibration, and

836

calibrateCamera returns bad values (zero distortion coefficients, an image center very far from

837

(w/2-0.5,h/2-0.5), and/or large differences between \f$f_x\f$ and \f$f_y\f$ (ratios of 10:1 or more)),

838

then you have probably used patternSize=cvSize(rows,cols) instead of using

839

patternSize=cvSize(cols,rows) in findChessboardCorners .

840

841

@sa

842

findChessboardCorners, solvePnP, initCameraMatrix2D, stereoCalibrate, undistort

843

844

CV_EXPORTS_W double calibrateCamera( InputArrayOfArrays objectPoints,

845

InputArrayOfArrays imagePoints, Size imageSize,

846

InputOutputArray cameraMatrix, InputOutputArray distCoeffs,

847

OutputArrayOfArrays rvecs, OutputArrayOfArrays tvecs,

848

int flags = 0, TermCriteria criteria = TermCriteria(

849

TermCriteria::COUNT + TermCriteria::EPS, 30, DBL_EPSILON) );

850

851

/** @brief Computes useful camera characteristics from the camera matrix.

852

853

@param cameraMatrix Input camera matrix that can be estimated by calibrateCamera or

854

stereoCalibrate .

855

@param imageSize Input image size in pixels.

856

@param apertureWidth Physical width in mm of the sensor.

857

@param apertureHeight Physical height in mm of the sensor.

858

@param fovx Output field of view in degrees along the horizontal sensor axis.

859

@param fovy Output field of view in degrees along the vertical sensor axis.

860

@param focalLength Focal length of the lens in mm.

861

@param principalPoint Principal point in mm.

862

@param aspectRatio \f$f_y/f_x\f$

863

864

The function computes various useful camera characteristics from the previously estimated camera

865

matrix.

866

867

@note

868

Do keep in mind that the unity measure 'mm' stands for whatever unit of measure one chooses for

869

the chessboard pitch (it can thus be any value).

870

871

CV_EXPORTS_W void calibrationMatrixValues( InputArray cameraMatrix, Size imageSize,

872

double apertureWidth, double apertureHeight,

873

CV_OUT double& fovx, CV_OUT double& fovy,

874

CV_OUT double& focalLength, CV_OUT Point2d& principalPoint,

875

CV_OUT double& aspectRatio );

876

877

/** @brief Calibrates the stereo camera.

878

879

@param objectPoints Vector of vectors of the calibration pattern points.

880

@param imagePoints1 Vector of vectors of the projections of the calibration pattern points,

881

observed by the first camera.

882

@param imagePoints2 Vector of vectors of the projections of the calibration pattern points,

883

observed by the second camera.

884

@param cameraMatrix1 Input/output first camera matrix:

885

\f$\vecthreethree{f_x^{(j)}}{0}{c_x^{(j)}}{0}{f_y^{(j)}}{c_y^{(j)}}{0}{0}{1}\f$ , \f$j = 0,\, 1\f$ . If

886

any of CV_CALIB_USE_INTRINSIC_GUESS , CV_CALIB_FIX_ASPECT_RATIO ,

887

CV_CALIB_FIX_INTRINSIC , or CV_CALIB_FIX_FOCAL_LENGTH are specified, some or all of the

888

matrix components must be initialized. See the flags description for details.

889

@param distCoeffs1 Input/output vector of distortion coefficients

890

\f$(k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6 [, s_1, s_2, s_3, s_4[, \tau_x, \tau_y]]]])\f$ of

891

4, 5, 8, 12 or 14 elements. The output vector length depends on the flags.

892

@param cameraMatrix2 Input/output second camera matrix. The parameter is similar to cameraMatrix1

893

@param distCoeffs2 Input/output lens distortion coefficients for the second camera. The parameter

894

is similar to distCoeffs1 .

895

@param imageSize Size of the image used only to initialize intrinsic camera matrix.

896

@param R Output rotation matrix between the 1st and the 2nd camera coordinate systems.

897

@param T Output translation vector between the coordinate systems of the cameras.

898

@param E Output essential matrix.

899

@param F Output fundamental matrix.

900

@param flags Different flags that may be zero or a combination of the following values:

901

- **CV_CALIB_FIX_INTRINSIC** Fix cameraMatrix? and distCoeffs? so that only R, T, E , and F

902

matrices are estimated.

903

- **CV_CALIB_USE_INTRINSIC_GUESS** Optimize some or all of the intrinsic parameters

904

according to the specified flags. Initial values are provided by the user.

905

- **CV_CALIB_FIX_PRINCIPAL_POINT** Fix the principal points during the optimization.

906

- **CV_CALIB_FIX_FOCAL_LENGTH** Fix \f$f^{(j)}_x\f$ and \f$f^{(j)}_y\f$ .

907

- **CV_CALIB_FIX_ASPECT_RATIO** Optimize \f$f^{(j)}_y\f$ . Fix the ratio \f$f^{(j)}_x/f^{(j)}_y\f$

908

909

- **CV_CALIB_SAME_FOCAL_LENGTH** Enforce \f$f^{(0)}_x=f^{(1)}_x\f$ and \f$f^{(0)}_y=f^{(1)}_y\f$ .

910

- **CV_CALIB_ZERO_TANGENT_DIST** Set tangential distortion coefficients for each camera to

911

zeros and fix there.

912

- **CV_CALIB_FIX_K1,...,CV_CALIB_FIX_K6** Do not change the corresponding radial

913

distortion coefficient during the optimization. If CV_CALIB_USE_INTRINSIC_GUESS is set,

914

the coefficient from the supplied distCoeffs matrix is used. Otherwise, it is set to 0.

915

- **CV_CALIB_RATIONAL_MODEL** Enable coefficients k4, k5, and k6. To provide the backward

916

compatibility, this extra flag should be explicitly specified to make the calibration

917

function use the rational model and return 8 coefficients. If the flag is not set, the

918

function computes and returns only 5 distortion coefficients.

919

- **CALIB_THIN_PRISM_MODEL** Coefficients s1, s2, s3 and s4 are enabled. To provide the

920

backward compatibility, this extra flag should be explicitly specified to make the

921

calibration function use the thin prism model and return 12 coefficients. If the flag is not

922

set, the function computes and returns only 5 distortion coefficients.

923

- **CALIB_FIX_S1_S2_S3_S4** The thin prism distortion coefficients are not changed during

924

the optimization. If CV_CALIB_USE_INTRINSIC_GUESS is set, the coefficient from the

925

supplied distCoeffs matrix is used. Otherwise, it is set to 0.

926

- **CALIB_TILTED_MODEL** Coefficients tauX and tauY are enabled. To provide the

927

backward compatibility, this extra flag should be explicitly specified to make the

928

calibration function use the tilted sensor model and return 14 coefficients. If the flag is not

929

set, the function computes and returns only 5 distortion coefficients.

930

- **CALIB_FIX_TAUX_TAUY** The coefficients of the tilted sensor model are not changed during

931

the optimization. If CV_CALIB_USE_INTRINSIC_GUESS is set, the coefficient from the

932

supplied distCoeffs matrix is used. Otherwise, it is set to 0.

933

@param criteria Termination criteria for the iterative optimization algorithm.

934

935

The function estimates transformation between two cameras making a stereo pair. If you have a stereo

936

camera where the relative position and orientation of two cameras is fixed, and if you computed

937

poses of an object relative to the first camera and to the second camera, (R1, T1) and (R2, T2),

938

respectively (this can be done with solvePnP ), then those poses definitely relate to each other.

939

This means that, given ( \f$R_1\f$,\f$T_1\f$ ), it should be possible to compute ( \f$R_2\f$,\f$T_2\f$ ). You only

940

need to know the position and orientation of the second camera relative to the first camera. This is

941

what the described function does. It computes ( \f$R\f$,\f$T\f$ ) so that:

942

943

\f[R_2=R*R_1

944

T_2=R*T_1 + T,\f]

945

946

Optionally, it computes the essential matrix E:

947

948

\f[E= \vecthreethree{0}{-T_2}{T_1}{T_2}{0}{-T_0}{-T_1}{T_0}{0} *R\f]

949

950

where \f$T_i\f$ are components of the translation vector \f$T\f$ : \f$T=[T_0, T_1, T_2]^T\f$ . And the function

951

can also compute the fundamental matrix F:

952

953

\f[F = cameraMatrix2^{-T} E cameraMatrix1^{-1}\f]

954

955

Besides the stereo-related information, the function can also perform a full calibration of each of

956

two cameras. However, due to the high dimensionality of the parameter space and noise in the input

957

data, the function can diverge from the correct solution. If the intrinsic parameters can be

958

estimated with high accuracy for each of the cameras individually (for example, using

959

calibrateCamera ), you are recommended to do so and then pass CV_CALIB_FIX_INTRINSIC flag to the

960

function along with the computed intrinsic parameters. Otherwise, if all the parameters are

961

estimated at once, it makes sense to restrict some parameters, for example, pass

962

CV_CALIB_SAME_FOCAL_LENGTH and CV_CALIB_ZERO_TANGENT_DIST flags, which is usually a

963

reasonable assumption.

964

965

Similarly to calibrateCamera , the function minimizes the total re-projection error for all the

966

points in all the available views from both cameras. The function returns the final value of the

967

re-projection error.

968

969

CV_EXPORTS_W double stereoCalibrate( InputArrayOfArrays objectPoints,

970

InputArrayOfArrays imagePoints1, InputArrayOfArrays imagePoints2,

971

InputOutputArray cameraMatrix1, InputOutputArray distCoeffs1,

972

InputOutputArray cameraMatrix2, InputOutputArray distCoeffs2,

973

Size imageSize, OutputArray R,OutputArray T, OutputArray E, OutputArray F,

974

int flags = CALIB_FIX_INTRINSIC,

975

TermCriteria criteria = TermCriteria(TermCriteria::COUNT+TermCriteria::EPS, 30, 1e-6) );

976

977

978

/** @brief Computes rectification transforms for each head of a calibrated stereo camera.

979

980

@param cameraMatrix1 First camera matrix.

981

@param distCoeffs1 First camera distortion parameters.

982

@param cameraMatrix2 Second camera matrix.

983

@param distCoeffs2 Second camera distortion parameters.

984

@param imageSize Size of the image used for stereo calibration.

985

@param R Rotation matrix between the coordinate systems of the first and the second cameras.

986

@param T Translation vector between coordinate systems of the cameras.

987

@param R1 Output 3x3 rectification transform (rotation matrix) for the first camera.

988

@param R2 Output 3x3 rectification transform (rotation matrix) for the second camera.

989

@param P1 Output 3x4 projection matrix in the new (rectified) coordinate systems for the first

990

camera.

991

@param P2 Output 3x4 projection matrix in the new (rectified) coordinate systems for the second

992

camera.

993

@param Q Output \f$4 \times 4\f$ disparity-to-depth mapping matrix (see reprojectImageTo3D ).

994

@param flags Operation flags that may be zero or CV_CALIB_ZERO_DISPARITY . If the flag is set,

995

the function makes the principal points of each camera have the same pixel coordinates in the

996

rectified views. And if the flag is not set, the function may still shift the images in the

997

horizontal or vertical direction (depending on the orientation of epipolar lines) to maximize the

998

useful image area.

999

@param alpha Free scaling parameter. If it is -1 or absent, the function performs the default

1000

scaling. Otherwise, the parameter should be between 0 and 1. alpha=0 means that the rectified

1001

images are zoomed and shifted so that only valid pixels are visible (no black areas after

1002

rectification). alpha=1 means that the rectified image is decimated and shifted so that all the

1003

pixels from the original images from the cameras are retained in the rectified images (no source

1004

image pixels are lost). Obviously, any intermediate value yields an intermediate result between

1005

those two extreme cases.

1006

@param newImageSize New image resolution after rectification. The same size should be passed to

1007

initUndistortRectifyMap (see the stereo_calib.cpp sample in OpenCV samples directory). When (0,0)

1008

is passed (default), it is set to the original imageSize . Setting it to larger value can help you

1009

preserve details in the original image, especially when there is a big radial distortion.

1010

@param validPixROI1 Optional output rectangles inside the rectified images where all the pixels

1011

are valid. If alpha=0 , the ROIs cover the whole images. Otherwise, they are likely to be smaller

1012

(see the picture below).

1013

@param validPixROI2 Optional output rectangles inside the rectified images where all the pixels

1014

are valid. If alpha=0 , the ROIs cover the whole images. Otherwise, they are likely to be smaller

1015

(see the picture below).

1016

1017

The function computes the rotation matrices for each camera that (virtually) make both camera image

1018

planes the same plane. Consequently, this makes all the epipolar lines parallel and thus simplifies

1019

the dense stereo correspondence problem. The function takes the matrices computed by stereoCalibrate

1020

as input. As output, it provides two rotation matrices and also two projection matrices in the new

1021

coordinates. The function distinguishes the following two cases:

1022

1023

- **Horizontal stereo**: the first and the second camera views are shifted relative to each other

1024

mainly along the x axis (with possible small vertical shift). In the rectified images, the

1025

corresponding epipolar lines in the left and right cameras are horizontal and have the same

1026

y-coordinate. P1 and P2 look like:

1027

1028

\f[\texttt{P1} = \begin{bmatrix} f & 0 & cx_1 & 0 \\ 0 & f & cy & 0 \\ 0 & 0 & 1 & 0 \end{bmatrix}\f]

1029

1030

\f[\texttt{P2} = \begin{bmatrix} f & 0 & cx_2 & T_x*f \\ 0 & f & cy & 0 \\ 0 & 0 & 1 & 0 \end{bmatrix} ,\f]

1031

1032

where \f$T_x\f$ is a horizontal shift between the cameras and \f$cx_1=cx_2\f$ if

1033

CV_CALIB_ZERO_DISPARITY is set.

1034

1035

- **Vertical stereo**: the first and the second camera views are shifted relative to each other

1036

mainly in vertical direction (and probably a bit in the horizontal direction too). The epipolar

1037

lines in the rectified images are vertical and have the same x-coordinate. P1 and P2 look like:

1038

1039

\f[\texttt{P1} = \begin{bmatrix} f & 0 & cx & 0 \\ 0 & f & cy_1 & 0 \\ 0 & 0 & 1 & 0 \end{bmatrix}\f]

1040

1041

\f[\texttt{P2} = \begin{bmatrix} f & 0 & cx & 0 \\ 0 & f & cy_2 & T_y*f \\ 0 & 0 & 1 & 0 \end{bmatrix} ,\f]

1042

1043

where \f$T_y\f$ is a vertical shift between the cameras and \f$cy_1=cy_2\f$ if CALIB_ZERO_DISPARITY is

1044

set.

1045

1046

As you can see, the first three columns of P1 and P2 will effectively be the new "rectified" camera

1047

matrices. The matrices, together with R1 and R2 , can then be passed to initUndistortRectifyMap to

1048

initialize the rectification map for each camera.

1049

1050

See below the screenshot from the stereo_calib.cpp sample. Some red horizontal lines pass through

1051

the corresponding image regions. This means that the images are well rectified, which is what most

1052

stereo correspondence algorithms rely on. The green rectangles are roi1 and roi2 . You see that

1053

their interiors are all valid pixels.

1054

1055

![image](pics/stereo_undistort.jpg)

1056

1057

CV_EXPORTS_W void stereoRectify( InputArray cameraMatrix1, InputArray distCoeffs1,

1058

InputArray cameraMatrix2, InputArray distCoeffs2,

1059

Size imageSize, InputArray R, InputArray T,

1060

OutputArray R1, OutputArray R2,

1061

OutputArray P1, OutputArray P2,

1062

OutputArray Q, int flags = CALIB_ZERO_DISPARITY,

1063

double alpha = -1, Size newImageSize = Size(),

1064

CV_OUT Rect* validPixROI1 = 0, CV_OUT Rect* validPixROI2 = 0 );

1065

1066

/** @brief Computes a rectification transform for an uncalibrated stereo camera.

1067

1068

@param points1 Array of feature points in the first image.

1069

@param points2 The corresponding points in the second image. The same formats as in

1070

findFundamentalMat are supported.

1071

@param F Input fundamental matrix. It can be computed from the same set of point pairs using

1072

findFundamentalMat .

1073

@param imgSize Size of the image.

1074

@param H1 Output rectification homography matrix for the first image.

1075

@param H2 Output rectification homography matrix for the second image.

1076

@param threshold Optional threshold used to filter out the outliers. If the parameter is greater

1077

than zero, all the point pairs that do not comply with the epipolar geometry (that is, the points

1078

for which \f$|\texttt{points2[i]}^T*\texttt{F}*\texttt{points1[i]}|>\texttt{threshold}\f$ ) are

1079

rejected prior to computing the homographies. Otherwise,all the points are considered inliers.

1080

1081

The function computes the rectification transformations without knowing intrinsic parameters of the

1082

cameras and their relative position in the space, which explains the suffix "uncalibrated". Another

1083

related difference from stereoRectify is that the function outputs not the rectification

1084

transformations in the object (3D) space, but the planar perspective transformations encoded by the

1085

homography matrices H1 and H2 . The function implements the algorithm @cite Hartley99 .

1086

1087

@note

1088

While the algorithm does not need to know the intrinsic parameters of the cameras, it heavily

1089

depends on the epipolar geometry. Therefore, if the camera lenses have a significant distortion,

1090

it would be better to correct it before computing the fundamental matrix and calling this

1091

function. For example, distortion coefficients can be estimated for each head of stereo camera

1092

separately by using calibrateCamera . Then, the images can be corrected using undistort , or

1093

just the point coordinates can be corrected with undistortPoints .

1094

1095

CV_EXPORTS_W bool stereoRectifyUncalibrated( InputArray points1, InputArray points2,

1096

InputArray F, Size imgSize,

1097

OutputArray H1, OutputArray H2,

1098

double threshold = 5 );

1099

1100

//! computes the rectification transformations for 3-head camera, where all the heads are on the same line.

1101

CV_EXPORTS_W float rectify3Collinear( InputArray cameraMatrix1, InputArray distCoeffs1,

1102

InputArray cameraMatrix2, InputArray distCoeffs2,

1103

InputArray cameraMatrix3, InputArray distCoeffs3,

1104

InputArrayOfArrays imgpt1, InputArrayOfArrays imgpt3,

1105

Size imageSize, InputArray R12, InputArray T12,

1106

InputArray R13, InputArray T13,

1107

OutputArray R1, OutputArray R2, OutputArray R3,

1108

OutputArray P1, OutputArray P2, OutputArray P3,

1109

OutputArray Q, double alpha, Size newImgSize,

1110

CV_OUT Rect* roi1, CV_OUT Rect* roi2, int flags );

1111

1112

/** @brief Returns the new camera matrix based on the free scaling parameter.

1113

1114

@param cameraMatrix Input camera matrix.

1115

@param distCoeffs Input vector of distortion coefficients

1116

\f$(k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6 [, s_1, s_2, s_3, s_4[, \tau_x, \tau_y]]]])\f$ of

1117

4, 5, 8, 12 or 14 elements. If the vector is NULL/empty, the zero distortion coefficients are

1118

assumed.

1119

@param imageSize Original image size.

1120

@param alpha Free scaling parameter between 0 (when all the pixels in the undistorted image are

1121

valid) and 1 (when all the source image pixels are retained in the undistorted image). See

1122

stereoRectify for details.

1123

@param newImgSize Image size after rectification. By default,it is set to imageSize .

1124

@param validPixROI Optional output rectangle that outlines all-good-pixels region in the

1125

undistorted image. See roi1, roi2 description in stereoRectify .

1126

@param centerPrincipalPoint Optional flag that indicates whether in the new camera matrix the

1127

principal point should be at the image center or not. By default, the principal point is chosen to

1128

best fit a subset of the source image (determined by alpha) to the corrected image.

1129

@return new_camera_matrix Output new camera matrix.

1130

1131

The function computes and returns the optimal new camera matrix based on the free scaling parameter.

1132

By varying this parameter, you may retrieve only sensible pixels alpha=0 , keep all the original

1133

image pixels if there is valuable information in the corners alpha=1 , or get something in between.

1134

When alpha\>0 , the undistortion result is likely to have some black pixels corresponding to

1135

"virtual" pixels outside of the captured distorted image. The original camera matrix, distortion

1136

coefficients, the computed new camera matrix, and newImageSize should be passed to

1137

initUndistortRectifyMap to produce the maps for remap .

1138

1139

CV_EXPORTS_W Mat getOptimalNewCameraMatrix( InputArray cameraMatrix, InputArray distCoeffs,

1140

Size imageSize, double alpha, Size newImgSize = Size(),

1141

CV_OUT Rect* validPixROI = 0,

1142

bool centerPrincipalPoint = false);

1143

1144

/** @brief Converts points from Euclidean to homogeneous space.

1145

1146

@param src Input vector of N-dimensional points.

1147

@param dst Output vector of N+1-dimensional points.

1148

1149

The function converts points from Euclidean to homogeneous space by appending 1's to the tuple of

1150

point coordinates. That is, each point (x1, x2, ..., xn) is converted to (x1, x2, ..., xn, 1).

1151

1152

CV_EXPORTS_W void convertPointsToHomogeneous( InputArray src, OutputArray dst );

1153

1154

/** @brief Converts points from homogeneous to Euclidean space.

1155

1156

@param src Input vector of N-dimensional points.

1157

@param dst Output vector of N-1-dimensional points.

1158

1159

The function converts points homogeneous to Euclidean space using perspective projection. That is,

1160

each point (x1, x2, ... x(n-1), xn) is converted to (x1/xn, x2/xn, ..., x(n-1)/xn). When xn=0, the

1161

output point coordinates will be (0,0,0,...).

1162

1163

CV_EXPORTS_W void convertPointsFromHomogeneous( InputArray src, OutputArray dst );

1164

1165

/** @brief Converts points to/from homogeneous coordinates.

1166

1167

@param src Input array or vector of 2D, 3D, or 4D points.

1168

@param dst Output vector of 2D, 3D, or 4D points.

1169

1170

The function converts 2D or 3D points from/to homogeneous coordinates by calling either

1171

convertPointsToHomogeneous or convertPointsFromHomogeneous.

1172

1173

@note The function is obsolete. Use one of the previous two functions instead.

1174

1175

CV_EXPORTS void convertPointsHomogeneous( InputArray src, OutputArray dst );

1176

1177

/** @brief Calculates a fundamental matrix from the corresponding points in two images.

1178

1179

@param points1 Array of N points from the first image. The point coordinates should be

1180

floating-point (single or double precision).

1181

@param points2 Array of the second image points of the same size and format as points1 .

1182

@param method Method for computing a fundamental matrix.

1183

- **CV_FM_7POINT** for a 7-point algorithm. \f$N = 7\f$

1184

- **CV_FM_8POINT** for an 8-point algorithm. \f$N \ge 8\f$

1185

- **CV_FM_RANSAC** for the RANSAC algorithm. \f$N \ge 8\f$

1186

- **CV_FM_LMEDS** for the LMedS algorithm. \f$N \ge 8\f$

1187

@param param1 Parameter used for RANSAC. It is the maximum distance from a point to an epipolar

1188

line in pixels, beyond which the point is considered an outlier and is not used for computing the

1189

final fundamental matrix. It can be set to something like 1-3, depending on the accuracy of the

1190

point localization, image resolution, and the image noise.

1191

@param param2 Parameter used for the RANSAC or LMedS methods only. It specifies a desirable level

1192

of confidence (probability) that the estimated matrix is correct.

1193

@param mask

1194

1195

The epipolar geometry is described by the following equation:

1196

1197

\f[[p_2; 1]^T F [p_1; 1] = 0\f]

1198

1199

where \f$F\f$ is a fundamental matrix, \f$p_1\f$ and \f$p_2\f$ are corresponding points in the first and the

1200

second images, respectively.

1201

1202

The function calculates the fundamental matrix using one of four methods listed above and returns

1203

the found fundamental matrix. Normally just one matrix is found. But in case of the 7-point

1204

algorithm, the function may return up to 3 solutions ( \f$9 \times 3\f$ matrix that stores all 3

1205

matrices sequentially).

1206

1207

The calculated fundamental matrix may be passed further to computeCorrespondEpilines that finds the

1208

epipolar lines corresponding to the specified points. It can also be passed to

1209

stereoRectifyUncalibrated to compute the rectification transformation. :

1210

@code

1211

// Example. Estimation of fundamental matrix using the RANSAC algorithm

1212

int point_count = 100;

1213

vector<Point2f> points1(point_count);

1214

vector<Point2f> points2(point_count);

1215

1216

// initialize the points here ...

1217

for( int i = 0; i < point_count; i++ )

1218

{

1219

points1[i] = ...;

1220

points2[i] = ...;

1221

}

1222

1223

Mat fundamental_matrix =

1224

findFundamentalMat(points1, points2, FM_RANSAC, 3, 0.99);

1225

@endcode

1226

1227

CV_EXPORTS_W Mat findFundamentalMat( InputArray points1, InputArray points2,

1228

int method = FM_RANSAC,

1229

double param1 = 3., double param2 = 0.99,

1230

OutputArray mask = noArray() );

1231

1232

/** @overload */

1233

CV_EXPORTS Mat findFundamentalMat( InputArray points1, InputArray points2,

1234

OutputArray mask, int method = FM_RANSAC,

1235

double param1 = 3., double param2 = 0.99 );

1236

1237

/** @brief Calculates an essential matrix from the corresponding points in two images.

1238

1239

@param points1 Array of N (N \>= 5) 2D points from the first image. The point coordinates should

1240

be floating-point (single or double precision).

1241

@param points2 Array of the second image points of the same size and format as points1 .

1242

@param cameraMatrix Camera matrix \f$K = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}\f$ .

1243

Note that this function assumes that points1 and points2 are feature points from cameras with the

1244

same camera matrix.

1245

@param method Method for computing a fundamental matrix.

1246

- **RANSAC** for the RANSAC algorithm.

1247

- **MEDS** for the LMedS algorithm.

1248

@param threshold Parameter used for RANSAC. It is the maximum distance from a point to an epipolar

1249

line in pixels, beyond which the point is considered an outlier and is not used for computing the

1250

final fundamental matrix. It can be set to something like 1-3, depending on the accuracy of the

1251

point localization, image resolution, and the image noise.

1252

@param prob Parameter used for the RANSAC or LMedS methods only. It specifies a desirable level of

1253

confidence (probability) that the estimated matrix is correct.

1254

@param mask Output array of N elements, every element of which is set to 0 for outliers and to 1

1255

for the other points. The array is computed only in the RANSAC and LMedS methods.

1256

1257

This function estimates essential matrix based on the five-point algorithm solver in @cite Nister03 .

1258

@cite SteweniusCFS is also a related. The epipolar geometry is described by the following equation:

1259

1260

\f[[p_2; 1]^T K^{-T} E K^{-1} [p_1; 1] = 0\f]

1261

1262

where \f$E\f$ is an essential matrix, \f$p_1\f$ and \f$p_2\f$ are corresponding points in the first and the

1263

second images, respectively. The result of this function may be passed further to

1264

decomposeEssentialMat or recoverPose to recover the relative pose between cameras.

1265

1266

CV_EXPORTS_W Mat findEssentialMat( InputArray points1, InputArray points2,

1267

InputArray cameraMatrix, int method = RANSAC,

1268

double prob = 0.999, double threshold = 1.0,

1269

OutputArray mask = noArray() );

1270

1271

/** @overload

1272

@param points1 Array of N (N \>= 5) 2D points from the first image. The point coordinates should

1273

be floating-point (single or double precision).

1274

@param points2 Array of the second image points of the same size and format as points1 .

1275

@param focal focal length of the camera. Note that this function assumes that points1 and points2

1276

are feature points from cameras with same focal length and principle point.

1277

@param pp principle point of the camera.

1278

@param method Method for computing a fundamental matrix.

1279

- **RANSAC** for the RANSAC algorithm.

1280

- **LMEDS** for the LMedS algorithm.

1281

@param threshold Parameter used for RANSAC. It is the maximum distance from a point to an epipolar

1282

line in pixels, beyond which the point is considered an outlier and is not used for computing the

1283

final fundamental matrix. It can be set to something like 1-3, depending on the accuracy of the

1284

point localization, image resolution, and the image noise.

1285

@param prob Parameter used for the RANSAC or LMedS methods only. It specifies a desirable level of

1286

confidence (probability) that the estimated matrix is correct.

1287

@param mask Output array of N elements, every element of which is set to 0 for outliers and to 1

1288

for the other points. The array is computed only in the RANSAC and LMedS methods.

1289

1290

This function differs from the one above that it computes camera matrix from focal length and

1291

principal point:

1292

1293

\f[K =

1294

\begin{bmatrix}

1295

f & 0 & x_{pp} \\

1296

0 & f & y_{pp} \\

1297

0 & 0 & 1

1298

\end{bmatrix}\f]

1299

1300

CV_EXPORTS_W Mat findEssentialMat( InputArray points1, InputArray points2,

1301

double focal = 1.0, Point2d pp = Point2d(0, 0),

1302

int method = RANSAC, double prob = 0.999,

1303

double threshold = 1.0, OutputArray mask = noArray() );

1304

1305

/** @brief Decompose an essential matrix to possible rotations and translation.

1306

1307

@param E The input essential matrix.

1308

@param R1 One possible rotation matrix.

1309

@param R2 Another possible rotation matrix.

1310

@param t One possible translation.

1311

1312

This function decompose an essential matrix E using svd decomposition @cite HartleyZ00 . Generally 4

1313

possible poses exists for a given E. They are \f$[R_1, t]\f$, \f$[R_1, -t]\f$, \f$[R_2, t]\f$, \f$[R_2, -t]\f$. By

1314

decomposing E, you can only get the direction of the translation, so the function returns unit t.

1315

1316

CV_EXPORTS_W void decomposeEssentialMat( InputArray E, OutputArray R1, OutputArray R2, OutputArray t );

1317

1318

/** @brief Recover relative camera rotation and translation from an estimated essential matrix and the

1319

corresponding points in two images, using cheirality check. Returns the number of inliers which pass

1320

the check.

1321

1322

@param E The input essential matrix.

1323

@param points1 Array of N 2D points from the first image. The point coordinates should be

1324

floating-point (single or double precision).

1325

@param points2 Array of the second image points of the same size and format as points1 .

1326

@param cameraMatrix Camera matrix \f$K = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}\f$ .

1327

Note that this function assumes that points1 and points2 are feature points from cameras with the

1328

same camera matrix.

1329

@param R Recovered relative rotation.

1330

@param t Recoverd relative translation.

1331

@param mask Input/output mask for inliers in points1 and points2.

1332

: If it is not empty, then it marks inliers in points1 and points2 for then given essential

1333

matrix E. Only these inliers will be used to recover pose. In the output mask only inliers

1334

which pass the cheirality check.

1335

This function decomposes an essential matrix using decomposeEssentialMat and then verifies possible

1336

pose hypotheses by doing cheirality check. The cheirality check basically means that the

1337

triangulated 3D points should have positive depth. Some details can be found in @cite Nister03 .

1338

1339

This function can be used to process output E and mask from findEssentialMat. In this scenario,

1340

points1 and points2 are the same input for findEssentialMat. :

1341

@code

1342

// Example. Estimation of fundamental matrix using the RANSAC algorithm

1343

int point_count = 100;

1344

vector<Point2f> points1(point_count);

1345

vector<Point2f> points2(point_count);

1346

1347

// initialize the points here ...

1348

for( int i = 0; i < point_count; i++ )

1349

{

1350

points1[i] = ...;

1351

points2[i] = ...;

1352

}

1353

1354

// cametra matrix with both focal lengths = 1, and principal point = (0, 0)

1355

Mat cameraMatrix = Mat::eye(3, 3, CV_64F);

1356

1357

Mat E, R, t, mask;

1358

1359

E = findEssentialMat(points1, points2, cameraMatrix, RANSAC, 0.999, 1.0, mask);

1360

recoverPose(E, points1, points2, cameraMatrix, R, t, mask);

1361

@endcode

1362

1363

CV_EXPORTS_W int recoverPose( InputArray E, InputArray points1, InputArray points2,

1364

InputArray cameraMatrix, OutputArray R, OutputArray t,

1365

InputOutputArray mask = noArray() );

1366

1367

/** @overload

1368

@param E The input essential matrix.

1369

@param points1 Array of N 2D points from the first image. The point coordinates should be

1370

floating-point (single or double precision).

1371

@param points2 Array of the second image points of the same size and format as points1 .

1372

@param R Recovered relative rotation.

1373

@param t Recoverd relative translation.

1374

@param focal Focal length of the camera. Note that this function assumes that points1 and points2

1375

are feature points from cameras with same focal length and principle point.

1376

@param pp Principle point of the camera.

1377

@param mask Input/output mask for inliers in points1 and points2.

1378

: If it is not empty, then it marks inliers in points1 and points2 for then given essential

1379

matrix E. Only these inliers will be used to recover pose. In the output mask only inliers

1380

which pass the cheirality check.

1381

1382

This function differs from the one above that it computes camera matrix from focal length and

1383

principal point:

1384

1385

\f[K =

1386

\begin{bmatrix}

1387

f & 0 & x_{pp} \\

1388

0 & f & y_{pp} \\

1389

0 & 0 & 1

1390

\end{bmatrix}\f]

1391

1392

CV_EXPORTS_W int recoverPose( InputArray E, InputArray points1, InputArray points2,

1393

OutputArray R, OutputArray t,

1394

double focal = 1.0, Point2d pp = Point2d(0, 0),

1395

InputOutputArray mask = noArray() );

1396

1397

/** @brief For points in an image of a stereo pair, computes the corresponding epilines in the other image.

1398

1399

@param points Input points. \f$N \times 1\f$ or \f$1 \times N\f$ matrix of type CV_32FC2 or

1400

vector\<Point2f\> .

1401

@param whichImage Index of the image (1 or 2) that contains the points .

1402

@param F Fundamental matrix that can be estimated using findFundamentalMat or stereoRectify .

1403

@param lines Output vector of the epipolar lines corresponding to the points in the other image.

1404

Each line \f$ax + by + c=0\f$ is encoded by 3 numbers \f$(a, b, c)\f$ .

1405

1406

For every point in one of the two images of a stereo pair, the function finds the equation of the

1407

corresponding epipolar line in the other image.

1408

1409

From the fundamental matrix definition (see findFundamentalMat ), line \f$l^{(2)}_i\f$ in the second

1410

image for the point \f$p^{(1)}_i\f$ in the first image (when whichImage=1 ) is computed as:

1411

1412

\f[l^{(2)}_i = F p^{(1)}_i\f]

1413

1414

And vice versa, when whichImage=2, \f$l^{(1)}_i\f$ is computed from \f$p^{(2)}_i\f$ as:

1415

1416

\f[l^{(1)}_i = F^T p^{(2)}_i\f]

1417

1418

Line coefficients are defined up to a scale. They are normalized so that \f$a_i^2+b_i^2=1\f$ .

1419

1420

CV_EXPORTS_W void computeCorrespondEpilines( InputArray points, int whichImage,

1421

InputArray F, OutputArray lines );

1422

1423

/** @brief Reconstructs points by triangulation.

1424

1425

@param projMatr1 3x4 projection matrix of the first camera.

1426

@param projMatr2 3x4 projection matrix of the second camera.

1427

@param projPoints1 2xN array of feature points in the first image. In case of c++ version it can

1428

be also a vector of feature points or two-channel matrix of size 1xN or Nx1.

1429

@param projPoints2 2xN array of corresponding points in the second image. In case of c++ version

1430

it can be also a vector of feature points or two-channel matrix of size 1xN or Nx1.

1431

@param points4D 4xN array of reconstructed points in homogeneous coordinates.

1432

1433

The function reconstructs 3-dimensional points (in homogeneous coordinates) by using their

1434

observations with a stereo camera. Projections matrices can be obtained from stereoRectify.

1435

1436

@note

1437

Keep in mind that all input data should be of float type in order for this function to work.

1438

1439

@sa

1440

reprojectImageTo3D

1441

1442

CV_EXPORTS_W void triangulatePoints( InputArray projMatr1, InputArray projMatr2,

1443

InputArray projPoints1, InputArray projPoints2,

1444

OutputArray points4D );

1445

1446

/** @brief Refines coordinates of corresponding points.

1447

1448

@param F 3x3 fundamental matrix.

1449

@param points1 1xN array containing the first set of points.

1450

@param points2 1xN array containing the second set of points.

1451

@param newPoints1 The optimized points1.

1452

@param newPoints2 The optimized points2.

1453

1454

The function implements the Optimal Triangulation Method (see Multiple View Geometry for details).

1455

For each given point correspondence points1[i] \<-\> points2[i], and a fundamental matrix F, it

1456

computes the corrected correspondences newPoints1[i] \<-\> newPoints2[i] that minimize the geometric

1457

error \f$d(points1[i], newPoints1[i])^2 + d(points2[i],newPoints2[i])^2\f$ (where \f$d(a,b)\f$ is the

1458

geometric distance between points \f$a\f$ and \f$b\f$ ) subject to the epipolar constraint

1459

\f$newPoints2^T * F * newPoints1 = 0\f$ .

1460

1461

CV_EXPORTS_W void correctMatches( InputArray F, InputArray points1, InputArray points2,

1462

OutputArray newPoints1, OutputArray newPoints2 );

1463

1464

/** @brief Filters off small noise blobs (speckles) in the disparity map

1465

1466

@param img The input 16-bit signed disparity image

1467

@param newVal The disparity value used to paint-off the speckles

1468

@param maxSpeckleSize The maximum speckle size to consider it a speckle. Larger blobs are not

1469

affected by the algorithm

1470

@param maxDiff Maximum difference between neighbor disparity pixels to put them into the same

1471

blob. Note that since StereoBM, StereoSGBM and may be other algorithms return a fixed-point

1472

disparity map, where disparity values are multiplied by 16, this scale factor should be taken into

1473

account when specifying this parameter value.

1474

@param buf The optional temporary buffer to avoid memory allocation within the function.

1475

1476

CV_EXPORTS_W void filterSpeckles( InputOutputArray img, double newVal,

1477

int maxSpeckleSize, double maxDiff,

1478

InputOutputArray buf = noArray() );

1479

1480

//! computes valid disparity ROI from the valid ROIs of the rectified images (that are returned by cv::stereoRectify())

1481

CV_EXPORTS_W Rect getValidDisparityROI( Rect roi1, Rect roi2,

1482

int minDisparity, int numberOfDisparities,

1483

int SADWindowSize );

1484

1485

//! validates disparity using the left-right check. The matrix "cost" should be computed by the stereo correspondence algorithm

1486

CV_EXPORTS_W void validateDisparity( InputOutputArray disparity, InputArray cost,

1487

int minDisparity, int numberOfDisparities,

1488

int disp12MaxDisp = 1 );

1489

1490

/** @brief Reprojects a disparity image to 3D space.

1491

1492

@param disparity Input single-channel 8-bit unsigned, 16-bit signed, 32-bit signed or 32-bit

1493

floating-point disparity image. If 16-bit signed format is used, the values are assumed to have no

1494

fractional bits.

1495

@param _3dImage Output 3-channel floating-point image of the same size as disparity . Each

1496

element of _3dImage(x,y) contains 3D coordinates of the point (x,y) computed from the disparity

1497

map.

1498

@param Q \f$4 \times 4\f$ perspective transformation matrix that can be obtained with stereoRectify.

1499

@param handleMissingValues Indicates, whether the function should handle missing values (i.e.

1500

points where the disparity was not computed). If handleMissingValues=true, then pixels with the

1501

minimal disparity that corresponds to the outliers (see StereoMatcher::compute ) are transformed

1502

to 3D points with a very large Z value (currently set to 10000).

1503

@param ddepth The optional output array depth. If it is -1, the output image will have CV_32F

1504

depth. ddepth can also be set to CV_16S, CV_32S or CV_32F.

1505

1506

The function transforms a single-channel disparity map to a 3-channel image representing a 3D

1507

surface. That is, for each pixel (x,y) andthe corresponding disparity d=disparity(x,y) , it

1508

computes:

1509

1510

\f[\begin{array}{l} [X \; Y \; Z \; W]^T = \texttt{Q} *[x \; y \; \texttt{disparity} (x,y) \; 1]^T \\ \texttt{\_3dImage} (x,y) = (X/W, \; Y/W, \; Z/W) \end{array}\f]

1511

1512

The matrix Q can be an arbitrary \f$4 \times 4\f$ matrix (for example, the one computed by

1513

stereoRectify). To reproject a sparse set of points {(x,y,d),...} to 3D space, use

1514

perspectiveTransform .

1515

1516

CV_EXPORTS_W void reprojectImageTo3D( InputArray disparity,

1517

OutputArray _3dImage, InputArray Q,

1518

bool handleMissingValues = false,

1519

int ddepth = -1 );

1520

1521

/** @brief Calculates the Sampson Distance between two points.

1522

1523

The function sampsonDistance calculates and returns the first order approximation of the geometric error as:

1524

\f[sd( \texttt{pt1} , \texttt{pt2} )= \frac{(\texttt{pt2}^t \cdot \texttt{F} \cdot \texttt{pt1})^2}{(\texttt{F} \cdot \texttt{pt1})(0) + (\texttt{F} \cdot \texttt{pt1})(1) + (\texttt{F}^t \cdot \texttt{pt2})(0) + (\texttt{F}^t \cdot \texttt{pt2})(1)}\f]

1525

The fundamental matrix may be calculated using the cv::findFundamentalMat function. See HZ 11.4.3 for details.

1526

@param pt1 first homogeneous 2d point

1527

@param pt2 second homogeneous 2d point

1528

@param F fundamental matrix

1529

1530

CV_EXPORTS_W double sampsonDistance(InputArray pt1, InputArray pt2, InputArray F);

1531

1532

/** @brief Computes an optimal affine transformation between two 3D point sets.

1533

1534

@param src First input 3D point set.

1535

@param dst Second input 3D point set.

1536

@param out Output 3D affine transformation matrix \f$3 \times 4\f$ .

1537

@param inliers Output vector indicating which points are inliers.

1538

@param ransacThreshold Maximum reprojection error in the RANSAC algorithm to consider a point as

1539

an inlier.

1540

@param confidence Confidence level, between 0 and 1, for the estimated transformation. Anything

1541

between 0.95 and 0.99 is usually good enough. Values too close to 1 can slow down the estimation

1542

significantly. Values lower than 0.8-0.9 can result in an incorrectly estimated transformation.

1543

1544

The function estimates an optimal 3D affine transformation between two 3D point sets using the

1545

RANSAC algorithm.

1546

1547

CV_EXPORTS_W int estimateAffine3D(InputArray src, InputArray dst,

1548

OutputArray out, OutputArray inliers,

1549

double ransacThreshold = 3, double confidence = 0.99);

1550

1551

/** @brief Decompose a homography matrix to rotation(s), translation(s) and plane normal(s).

1552

1553

@param H The input homography matrix between two images.

1554

@param K The input intrinsic camera calibration matrix.

1555

@param rotations Array of rotation matrices.

1556

@param translations Array of translation matrices.

1557

@param normals Array of plane normal matrices.

1558

1559

This function extracts relative camera motion between two views observing a planar object from the

1560

homography H induced by the plane. The intrinsic camera matrix K must also be provided. The function

1561

may return up to four mathematical solution sets. At least two of the solutions may further be

1562

invalidated if point correspondences are available by applying positive depth constraint (all points

1563

must be in front of the camera). The decomposition method is described in detail in @cite Malis .

1564

1565

CV_EXPORTS_W int decomposeHomographyMat(InputArray H,

1566

InputArray K,

1567

OutputArrayOfArrays rotations,

1568

OutputArrayOfArrays translations,

1569

OutputArrayOfArrays normals);

1570

1571

/** @brief The base class for stereo correspondence algorithms.

1572

1573

class CV_EXPORTS_W StereoMatcher : public Algorithm

1574

{

1575

public:

1576

enum { DISP_SHIFT = 4,

1577

DISP_SCALE = (1 << DISP_SHIFT)

1578

};

1579

1580

/** @brief Computes disparity map for the specified stereo pair

1581

1582

@param left Left 8-bit single-channel image.

1583

@param right Right image of the same size and the same type as the left one.

1584

@param disparity Output disparity map. It has the same size as the input images. Some algorithms,

1585

like StereoBM or StereoSGBM compute 16-bit fixed-point disparity map (where each disparity value

1586

has 4 fractional bits), whereas other algorithms output 32-bit floating-point disparity map.

1587

1588

CV_WRAP virtual void compute( InputArray left, InputArray right,

1589

OutputArray disparity ) = 0;

1590

1591

CV_WRAP virtual int getMinDisparity() const = 0;

1592

CV_WRAP virtual void setMinDisparity(int minDisparity) = 0;

1593

1594

CV_WRAP virtual int getNumDisparities() const = 0;

1595

CV_WRAP virtual void setNumDisparities(int numDisparities) = 0;

1596

1597

CV_WRAP virtual int getBlockSize() const = 0;

1598

CV_WRAP virtual void setBlockSize(int blockSize) = 0;

1599

1600

CV_WRAP virtual int getSpeckleWindowSize() const = 0;

1601

CV_WRAP virtual void setSpeckleWindowSize(int speckleWindowSize) = 0;

1602

1603

CV_WRAP virtual int getSpeckleRange() const = 0;

1604

CV_WRAP virtual void setSpeckleRange(int speckleRange) = 0;

1605

1606

CV_WRAP virtual int getDisp12MaxDiff() const = 0;

1607

CV_WRAP virtual void setDisp12MaxDiff(int disp12MaxDiff) = 0;

1608

};

1609

1610

1611

/** @brief Class for computing stereo correspondence using the block matching algorithm, introduced and

1612

contributed to OpenCV by K. Konolige.

1613

1614

class CV_EXPORTS_W StereoBM : public StereoMatcher

1615

{

1616

public:

1617

enum { PREFILTER_NORMALIZED_RESPONSE = 0,

1618

PREFILTER_XSOBEL = 1

1619

};

1620

1621

CV_WRAP virtual int getPreFilterType() const = 0;

1622

CV_WRAP virtual void setPreFilterType(int preFilterType) = 0;

1623

1624

CV_WRAP virtual int getPreFilterSize() const = 0;

1625

CV_WRAP virtual void setPreFilterSize(int preFilterSize) = 0;

1626

1627

CV_WRAP virtual int getPreFilterCap() const = 0;

1628

CV_WRAP virtual void setPreFilterCap(int preFilterCap) = 0;

1629

1630

CV_WRAP virtual int getTextureThreshold() const = 0;

1631

CV_WRAP virtual void setTextureThreshold(int textureThreshold) = 0;

1632

1633

CV_WRAP virtual int getUniquenessRatio() const = 0;

1634

CV_WRAP virtual void setUniquenessRatio(int uniquenessRatio) = 0;

1635

1636

CV_WRAP virtual int getSmallerBlockSize() const = 0;

1637

CV_WRAP virtual void setSmallerBlockSize(int blockSize) = 0;

1638

1639

CV_WRAP virtual Rect getROI1() const = 0;

1640

CV_WRAP virtual void setROI1(Rect roi1) = 0;

1641

1642

CV_WRAP virtual Rect getROI2() const = 0;

1643

CV_WRAP virtual void setROI2(Rect roi2) = 0;

1644

1645

/** @brief Creates StereoBM object

1646

1647

@param numDisparities the disparity search range. For each pixel algorithm will find the best

1648

disparity from 0 (default minimum disparity) to numDisparities. The search range can then be

1649

shifted by changing the minimum disparity.

1650

@param blockSize the linear size of the blocks compared by the algorithm. The size should be odd

1651

(as the block is centered at the current pixel). Larger block size implies smoother, though less

1652

accurate disparity map. Smaller block size gives more detailed disparity map, but there is higher

1653

chance for algorithm to find a wrong correspondence.

1654

1655

The function create StereoBM object. You can then call StereoBM::compute() to compute disparity for

1656

a specific stereo pair.

1657

1658

CV_WRAP static Ptr<StereoBM> create(int numDisparities = 0, int blockSize = 21);

1659

};

1660

1661

/** @brief The class implements the modified H. Hirschmuller algorithm @cite HH08 that differs from the original

1662

one as follows:

1663

1664

- By default, the algorithm is single-pass, which means that you consider only 5 directions

1665

instead of 8. Set mode=StereoSGBM::MODE_HH in createStereoSGBM to run the full variant of the

1666

algorithm but beware that it may consume a lot of memory.

1667

- The algorithm matches blocks, not individual pixels. Though, setting blockSize=1 reduces the

1668

blocks to single pixels.

1669

- Mutual information cost function is not implemented. Instead, a simpler Birchfield-Tomasi

1670

sub-pixel metric from @cite BT98 is used. Though, the color images are supported as well.

1671

- Some pre- and post- processing steps from K. Konolige algorithm StereoBM are included, for

1672

example: pre-filtering (StereoBM::PREFILTER_XSOBEL type) and post-filtering (uniqueness

1673

check, quadratic interpolation and speckle filtering).

1674

1675

@note

1676

- (Python) An example illustrating the use of the StereoSGBM matching algorithm can be found

1677

at opencv_source_code/samples/python/stereo_match.py

1678

1679

class CV_EXPORTS_W StereoSGBM : public StereoMatcher

1680

{

1681

public:

1682

enum

1683

{

1684

MODE_SGBM = 0,

1685

MODE_HH = 1,

1686

MODE_SGBM_3WAY = 2

1687

};

1688

1689

CV_WRAP virtual int getPreFilterCap() const = 0;

1690

CV_WRAP virtual void setPreFilterCap(int preFilterCap) = 0;

1691

1692

CV_WRAP virtual int getUniquenessRatio() const = 0;

1693

CV_WRAP virtual void setUniquenessRatio(int uniquenessRatio) = 0;

1694

1695

CV_WRAP virtual int getP1() const = 0;

1696

CV_WRAP virtual void setP1(int P1) = 0;

1697

1698

CV_WRAP virtual int getP2() const = 0;

1699

CV_WRAP virtual void setP2(int P2) = 0;

1700

1701

CV_WRAP virtual int getMode() const = 0;

1702

CV_WRAP virtual void setMode(int mode) = 0;

1703

1704

/** @brief Creates StereoSGBM object

1705

1706

@param minDisparity Minimum possible disparity value. Normally, it is zero but sometimes

1707

rectification algorithms can shift images, so this parameter needs to be adjusted accordingly.

1708

@param numDisparities Maximum disparity minus minimum disparity. The value is always greater than

1709

zero. In the current implementation, this parameter must be divisible by 16.

1710

@param blockSize Matched block size. It must be an odd number \>=1 . Normally, it should be

1711

somewhere in the 3..11 range.

1712

@param P1 The first parameter controlling the disparity smoothness. See below.

1713

@param P2 The second parameter controlling the disparity smoothness. The larger the values are,

1714

the smoother the disparity is. P1 is the penalty on the disparity change by plus or minus 1

1715

between neighbor pixels. P2 is the penalty on the disparity change by more than 1 between neighbor

1716

pixels. The algorithm requires P2 \> P1 . See stereo_match.cpp sample where some reasonably good

1717

P1 and P2 values are shown (like 8\*number_of_image_channels\*SADWindowSize\*SADWindowSize and

1718

32\*number_of_image_channels\*SADWindowSize\*SADWindowSize , respectively).

1719

@param disp12MaxDiff Maximum allowed difference (in integer pixel units) in the left-right

1720

disparity check. Set it to a non-positive value to disable the check.

1721

@param preFilterCap Truncation value for the prefiltered image pixels. The algorithm first

1722

computes x-derivative at each pixel and clips its value by [-preFilterCap, preFilterCap] interval.

1723

The result values are passed to the Birchfield-Tomasi pixel cost function.

1724

@param uniquenessRatio Margin in percentage by which the best (minimum) computed cost function

1725

value should "win" the second best value to consider the found match correct. Normally, a value

1726

within the 5-15 range is good enough.

1727

@param speckleWindowSize Maximum size of smooth disparity regions to consider their noise speckles

1728

and invalidate. Set it to 0 to disable speckle filtering. Otherwise, set it somewhere in the

1729

50-200 range.

1730

@param speckleRange Maximum disparity variation within each connected component. If you do speckle

1731

filtering, set the parameter to a positive value, it will be implicitly multiplied by 16.

1732

Normally, 1 or 2 is good enough.

1733

@param mode Set it to StereoSGBM::MODE_HH to run the full-scale two-pass dynamic programming

1734

algorithm. It will consume O(W\*H\*numDisparities) bytes, which is large for 640x480 stereo and

1735

huge for HD-size pictures. By default, it is set to false .

1736

1737

The first constructor initializes StereoSGBM with all the default parameters. So, you only have to

1738

set StereoSGBM::numDisparities at minimum. The second constructor enables you to set each parameter

1739

to a custom value.

1740

1741

CV_WRAP static Ptr<StereoSGBM> create(int minDisparity, int numDisparities, int blockSize,

1742

int P1 = 0, int P2 = 0, int disp12MaxDiff = 0,

1743

int preFilterCap = 0, int uniquenessRatio = 0,

1744

int speckleWindowSize = 0, int speckleRange = 0,

1745

int mode = StereoSGBM::MODE_SGBM);

1746

};

1747

1748

//! @} calib3d

1749

1750

/** @brief The methods in this namespace use a so-called fisheye camera model.

1751

@ingroup calib3d_fisheye

1752

1753

namespace fisheye

1754

{

1755

//! @addtogroup calib3d_fisheye

1756

//! @{

1757

1758

enum{

1759

CALIB_USE_INTRINSIC_GUESS = 1,

1760

CALIB_RECOMPUTE_EXTRINSIC = 2,

1761

CALIB_CHECK_COND = 4,

1762

CALIB_FIX_SKEW = 8,

1763

CALIB_FIX_K1 = 16,

1764

CALIB_FIX_K2 = 32,

1765

CALIB_FIX_K3 = 64,

1766

CALIB_FIX_K4 = 128,

1767

CALIB_FIX_INTRINSIC = 256

1768

};

1769

1770

/** @brief Projects points using fisheye model

1771

1772

@param objectPoints Array of object points, 1xN/Nx1 3-channel (or vector\<Point3f\> ), where N is

1773

the number of points in the view.

1774

@param imagePoints Output array of image points, 2xN/Nx2 1-channel or 1xN/Nx1 2-channel, or

1775

vector\<Point2f\>.

1776

@param affine

1777

@param K Camera matrix \f$K = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{_1}\f$.

1778

@param D Input vector of distortion coefficients \f$(k_1, k_2, k_3, k_4)\f$.

1779

@param alpha The skew coefficient.

1780

@param jacobian Optional output 2Nx15 jacobian matrix of derivatives of image points with respect

1781

to components of the focal lengths, coordinates of the principal point, distortion coefficients,

1782

rotation vector, translation vector, and the skew. In the old interface different components of

1783

the jacobian are returned via different output parameters.

1784

1785

The function computes projections of 3D points to the image plane given intrinsic and extrinsic

1786

camera parameters. Optionally, the function computes Jacobians - matrices of partial derivatives of

1787

image points coordinates (as functions of all the input parameters) with respect to the particular

1788

parameters, intrinsic and/or extrinsic.

1789

1790

CV_EXPORTS void projectPoints(InputArray objectPoints, OutputArray imagePoints, const Affine3d& affine,

1791

InputArray K, InputArray D, double alpha = 0, OutputArray jacobian = noArray());

1792

1793

/** @overload */

1794

CV_EXPORTS_W void projectPoints(InputArray objectPoints, OutputArray imagePoints, InputArray rvec, InputArray tvec,

1795

InputArray K, InputArray D, double alpha = 0, OutputArray jacobian = noArray());

1796

1797

/** @brief Distorts 2D points using fisheye model.

1798

1799

@param undistorted Array of object points, 1xN/Nx1 2-channel (or vector\<Point2f\> ), where N is

1800

the number of points in the view.

1801

@param K Camera matrix \f$K = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{_1}\f$.

1802

@param D Input vector of distortion coefficients \f$(k_1, k_2, k_3, k_4)\f$.

1803

@param alpha The skew coefficient.

1804

@param distorted Output array of image points, 1xN/Nx1 2-channel, or vector\<Point2f\> .

1805

1806

CV_EXPORTS_W void distortPoints(InputArray undistorted, OutputArray distorted, InputArray K, InputArray D, double alpha = 0);

1807

1808

/** @brief Undistorts 2D points using fisheye model

1809

1810

@param distorted Array of object points, 1xN/Nx1 2-channel (or vector\<Point2f\> ), where N is the

1811

number of points in the view.

1812

@param K Camera matrix \f$K = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{_1}\f$.

1813

@param D Input vector of distortion coefficients \f$(k_1, k_2, k_3, k_4)\f$.

1814

@param R Rectification transformation in the object space: 3x3 1-channel, or vector: 3x1/1x3

1815

1-channel or 1x1 3-channel

1816

@param P New camera matrix (3x3) or new projection matrix (3x4)

1817

@param undistorted Output array of image points, 1xN/Nx1 2-channel, or vector\<Point2f\> .

1818

1819

CV_EXPORTS_W void undistortPoints(InputArray distorted, OutputArray undistorted,

1820

InputArray K, InputArray D, InputArray R = noArray(), InputArray P = noArray());

1821

1822

/** @brief Computes undistortion and rectification maps for image transform by cv::remap(). If D is empty zero

1823

distortion is used, if R or P is empty identity matrixes are used.

1824

1825

@param K Camera matrix \f$K = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{_1}\f$.

1826

@param D Input vector of distortion coefficients \f$(k_1, k_2, k_3, k_4)\f$.

1827

@param R Rectification transformation in the object space: 3x3 1-channel, or vector: 3x1/1x3

1828

1-channel or 1x1 3-channel

1829

@param P New camera matrix (3x3) or new projection matrix (3x4)

1830

@param size Undistorted image size.

1831

@param m1type Type of the first output map that can be CV_32FC1 or CV_16SC2 . See convertMaps()

1832

for details.

1833

@param map1 The first output map.

1834

@param map2 The second output map.

1835

1836

CV_EXPORTS_W void initUndistortRectifyMap(InputArray K, InputArray D, InputArray R, InputArray P,

1837

const cv::Size& size, int m1type, OutputArray map1, OutputArray map2);

1838

1839

/** @brief Transforms an image to compensate for fisheye lens distortion.

1840

1841

@param distorted image with fisheye lens distortion.

1842

@param undistorted Output image with compensated fisheye lens distortion.

1843

@param K Camera matrix \f$K = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{_1}\f$.

1844

@param D Input vector of distortion coefficients \f$(k_1, k_2, k_3, k_4)\f$.

1845

@param Knew Camera matrix of the distorted image. By default, it is the identity matrix but you

1846

may additionally scale and shift the result by using a different matrix.

1847

@param new_size

1848

1849

The function transforms an image to compensate radial and tangential lens distortion.

1850

1851

The function is simply a combination of fisheye::initUndistortRectifyMap (with unity R ) and remap

1852

(with bilinear interpolation). See the former function for details of the transformation being

1853

performed.

1854

1855

See below the results of undistortImage.

1856

- a\) result of undistort of perspective camera model (all possible coefficients (k_1, k_2, k_3,

1857

k_4, k_5, k_6) of distortion were optimized under calibration)

1858

- b\) result of fisheye::undistortImage of fisheye camera model (all possible coefficients (k_1, k_2,

1859

k_3, k_4) of fisheye distortion were optimized under calibration)

1860

- c\) original image was captured with fisheye lens

1861

1862

Pictures a) and b) almost the same. But if we consider points of image located far from the center

1863

of image, we can notice that on image a) these points are distorted.

1864

1865

![image](pics/fisheye_undistorted.jpg)

1866

1867

CV_EXPORTS_W void undistortImage(InputArray distorted, OutputArray undistorted,

1868

InputArray K, InputArray D, InputArray Knew = cv::noArray(), const Size& new_size = Size());

1869

1870

/** @brief Estimates new camera matrix for undistortion or rectification.

1871

1872

@param K Camera matrix \f$K = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{_1}\f$.

1873

@param image_size

1874

@param D Input vector of distortion coefficients \f$(k_1, k_2, k_3, k_4)\f$.

1875

@param R Rectification transformation in the object space: 3x3 1-channel, or vector: 3x1/1x3

1876

1-channel or 1x1 3-channel

1877

@param P New camera matrix (3x3) or new projection matrix (3x4)

1878

@param balance Sets the new focal length in range between the min focal length and the max focal

1879

length. Balance is in range of [0, 1].

1880

@param new_size

1881

@param fov_scale Divisor for new focal length.

1882

1883

CV_EXPORTS_W void estimateNewCameraMatrixForUndistortRectify(InputArray K, InputArray D, const Size &image_size, InputArray R,

1884

OutputArray P, double balance = 0.0, const Size& new_size = Size(), double fov_scale = 1.0);

1885

1886

/** @brief Performs camera calibaration

1887

1888

@param objectPoints vector of vectors of calibration pattern points in the calibration pattern

1889

coordinate space.

1890

@param imagePoints vector of vectors of the projections of calibration pattern points.

1891

imagePoints.size() and objectPoints.size() and imagePoints[i].size() must be equal to

1892

objectPoints[i].size() for each i.

1893

@param image_size Size of the image used only to initialize the intrinsic camera matrix.

1894

@param K Output 3x3 floating-point camera matrix

1895

\f$A = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}\f$ . If

1896

fisheye::CALIB_USE_INTRINSIC_GUESS/ is specified, some or all of fx, fy, cx, cy must be

1897

initialized before calling the function.

1898

@param D Output vector of distortion coefficients \f$(k_1, k_2, k_3, k_4)\f$.

1899

@param rvecs Output vector of rotation vectors (see Rodrigues ) estimated for each pattern view.

1900

That is, each k-th rotation vector together with the corresponding k-th translation vector (see

1901

the next output parameter description) brings the calibration pattern from the model coordinate

1902

space (in which object points are specified) to the world coordinate space, that is, a real

1903

position of the calibration pattern in the k-th pattern view (k=0.. *M* -1).

1904

@param tvecs Output vector of translation vectors estimated for each pattern view.

1905

@param flags Different flags that may be zero or a combination of the following values:

1906

- **fisheye::CALIB_USE_INTRINSIC_GUESS** cameraMatrix contains valid initial values of

1907

fx, fy, cx, cy that are optimized further. Otherwise, (cx, cy) is initially set to the image

1908

center ( imageSize is used), and focal distances are computed in a least-squares fashion.

1909

- **fisheye::CALIB_RECOMPUTE_EXTRINSIC** Extrinsic will be recomputed after each iteration

1910

of intrinsic optimization.

1911

- **fisheye::CALIB_CHECK_COND** The functions will check validity of condition number.

1912

- **fisheye::CALIB_FIX_SKEW** Skew coefficient (alpha) is set to zero and stay zero.

1913

- **fisheye::CALIB_FIX_K1..4** Selected distortion coefficients are set to zeros and stay

1914

zero.

1915

@param criteria Termination criteria for the iterative optimization algorithm.

1916

1917

CV_EXPORTS_W double calibrate(InputArrayOfArrays objectPoints, InputArrayOfArrays imagePoints, const Size& image_size,

1918

InputOutputArray K, InputOutputArray D, OutputArrayOfArrays rvecs, OutputArrayOfArrays tvecs, int flags = 0,

1919

TermCriteria criteria = TermCriteria(TermCriteria::COUNT + TermCriteria::EPS, 100, DBL_EPSILON));

1920

1921

/** @brief Stereo rectification for fisheye camera model

1922

1923

@param K1 First camera matrix.

1924

@param D1 First camera distortion parameters.

1925

@param K2 Second camera matrix.

1926

@param D2 Second camera distortion parameters.

1927

@param imageSize Size of the image used for stereo calibration.

1928

@param R Rotation matrix between the coordinate systems of the first and the second

1929

cameras.

1930

@param tvec Translation vector between coordinate systems of the cameras.

1931

@param R1 Output 3x3 rectification transform (rotation matrix) for the first camera.

1932

@param R2 Output 3x3 rectification transform (rotation matrix) for the second camera.

1933

@param P1 Output 3x4 projection matrix in the new (rectified) coordinate systems for the first

1934

camera.

1935

@param P2 Output 3x4 projection matrix in the new (rectified) coordinate systems for the second

1936

camera.

1937

@param Q Output \f$4 \times 4\f$ disparity-to-depth mapping matrix (see reprojectImageTo3D ).

1938

@param flags Operation flags that may be zero or CV_CALIB_ZERO_DISPARITY . If the flag is set,

1939

the function makes the principal points of each camera have the same pixel coordinates in the

1940

rectified views. And if the flag is not set, the function may still shift the images in the

1941

horizontal or vertical direction (depending on the orientation of epipolar lines) to maximize the

1942

useful image area.

1943

@param newImageSize New image resolution after rectification. The same size should be passed to

1944

initUndistortRectifyMap (see the stereo_calib.cpp sample in OpenCV samples directory). When (0,0)

1945

is passed (default), it is set to the original imageSize . Setting it to larger value can help you

1946

preserve details in the original image, especially when there is a big radial distortion.

1947

@param balance Sets the new focal length in range between the min focal length and the max focal

1948

length. Balance is in range of [0, 1].

1949

@param fov_scale Divisor for new focal length.

1950

1951

CV_EXPORTS_W void stereoRectify(InputArray K1, InputArray D1, InputArray K2, InputArray D2, const Size &imageSize, InputArray R, InputArray tvec,

1952

OutputArray R1, OutputArray R2, OutputArray P1, OutputArray P2, OutputArray Q, int flags, const Size &newImageSize = Size(),

1953

double balance = 0.0, double fov_scale = 1.0);

1954

1955

/** @brief Performs stereo calibration

1956

1957

@param objectPoints Vector of vectors of the calibration pattern points.

1958

@param imagePoints1 Vector of vectors of the projections of the calibration pattern points,

1959

observed by the first camera.

1960

@param imagePoints2 Vector of vectors of the projections of the calibration pattern points,

1961

observed by the second camera.

1962

@param K1 Input/output first camera matrix:

1963

\f$\vecthreethree{f_x^{(j)}}{0}{c_x^{(j)}}{0}{f_y^{(j)}}{c_y^{(j)}}{0}{0}{1}\f$ , \f$j = 0,\, 1\f$ . If

1964

any of fisheye::CALIB_USE_INTRINSIC_GUESS , fisheye::CV_CALIB_FIX_INTRINSIC are specified,

1965

some or all of the matrix components must be initialized.

1966

@param D1 Input/output vector of distortion coefficients \f$(k_1, k_2, k_3, k_4)\f$ of 4 elements.

1967

@param K2 Input/output second camera matrix. The parameter is similar to K1 .

1968

@param D2 Input/output lens distortion coefficients for the second camera. The parameter is

1969

similar to D1 .

1970

@param imageSize Size of the image used only to initialize intrinsic camera matrix.

1971

@param R Output rotation matrix between the 1st and the 2nd camera coordinate systems.

1972

@param T Output translation vector between the coordinate systems of the cameras.

1973

@param flags Different flags that may be zero or a combination of the following values:

1974

- **fisheye::CV_CALIB_FIX_INTRINSIC** Fix K1, K2? and D1, D2? so that only R, T matrices

1975

are estimated.

1976

- **fisheye::CALIB_USE_INTRINSIC_GUESS** K1, K2 contains valid initial values of

1977

fx, fy, cx, cy that are optimized further. Otherwise, (cx, cy) is initially set to the image

1978

center (imageSize is used), and focal distances are computed in a least-squares fashion.

1979

- **fisheye::CALIB_RECOMPUTE_EXTRINSIC** Extrinsic will be recomputed after each iteration

1980

of intrinsic optimization.

1981

- **fisheye::CALIB_CHECK_COND** The functions will check validity of condition number.

1982

- **fisheye::CALIB_FIX_SKEW** Skew coefficient (alpha) is set to zero and stay zero.

1983

- **fisheye::CALIB_FIX_K1..4** Selected distortion coefficients are set to zeros and stay

1984

zero.

1985

@param criteria Termination criteria for the iterative optimization algorithm.

1986

1987

CV_EXPORTS_W double stereoCalibrate(InputArrayOfArrays objectPoints, InputArrayOfArrays imagePoints1, InputArrayOfArrays imagePoints2,

1988

InputOutputArray K1, InputOutputArray D1, InputOutputArray K2, InputOutputArray D2, Size imageSize,

1989

OutputArray R, OutputArray T, int flags = fisheye::CALIB_FIX_INTRINSIC,

1990

TermCriteria criteria = TermCriteria(TermCriteria::COUNT + TermCriteria::EPS, 100, DBL_EPSILON));

1991

1992

//! @} calib3d_fisheye

1993

}

1994

1995

} // cv

1996

1997

#ifndef DISABLE_OPENCV_24_COMPATIBILITY

1998

#include "opencv2/calib3d/calib3d_c.h"

1999

#endif

2000

2001

#endif

Older »