projectPoints

geometryfunctionOpenCV 5.0.0

import { projectPoints } from '@banou/opencv-wasm'

Use after await initOpenCV(). See the initialization and named imports guide.

Explore visually: Perspective-n-point pose →

Estimate a camera-relative object pose from known 3D points and their 2D image observations.

VISUAL WALKTHROUGH3D vision

REFERENCE INPUTKnown 3D object geometry

The shape is known in object coordinates. One calibrated camera sees it at an unknown pose.

→

RESULTReproject using the recovered pose

The final illustrative pose projects the model onto the observed points. A native PnP result must still be checked for depth and reprojection error.

Illustrative example. The stages explain the method; they are not a live OpenCV execution.

Projects 3D points to an image plane.

The function computes the 2D projections of 3D points to the image plane, given intrinsic and extrinsic camera parameters. Optionally, the function computes Jacobians -matrices of partial derivatives of image points coordinates (as functions of all the input parameters) with respect to the particular parameters, intrinsic and/or extrinsic. The Jacobians are used during the global optimization in calibrateCamera, solvePnP, and stereoCalibrate. The function itself can also be used to compute a re-projection error, given the current intrinsic and extrinsic parameters.

Note: Coordinate Systems:

• Input (objectPoints): 3D points in the world coordinate frame.
• Output (imagePoints): 2D projections in pixel coordinates of the image plane, with distortion applied. The coordinates (u, v) are measured in pixels from the top-left corner of the image.

The transformation chain is: World coordinates → Camera coordinates (via rvec/tvec) → Normalized camera coordinates → Distortion applied → Pixel coordinates (via cameraMatrix).

Note: By setting rvec = tvec = [0, 0, 0], or by setting cameraMatrix to a 3x3 identity matrix, or by passing zero distortion coefficients, one can get various useful partial cases of the function. This means, one can compute the distorted coordinates for a sparse set of points or apply a perspective transformation (and also compute the derivatives) in the ideal zero-distortion setup.

projectPoints(objectPoints: Mat, rvec: Mat, tvec: Mat, cameraMatrix: Mat, distCoeffs: Mat, imagePoints: Mat, jacobian: Mat, aspectRatio: number): void;

3 available overloads

projectPoints(objectPoints: Mat, rvec: Mat, tvec: Mat, cameraMatrix: Mat, distCoeffs: Mat, imagePoints: Mat): void;

projectPoints(objectPoints: Mat, rvec: Mat, tvec: Mat, cameraMatrix: Mat, distCoeffs: Mat, imagePoints: Mat, jacobian: Mat): void;

projectPoints(objectPoints: Mat, rvec: Mat, tvec: Mat, cameraMatrix: Mat, distCoeffs: Mat, imagePoints: Mat, jacobian: Mat, aspectRatio: number): void;

objectPoints

Array of object points expressed wrt. the world coordinate frame. A 3xN/Nx3 1-channel or 1xN/Nx1 3-channel (or vector<Point3f> ), where N is the number of points in the view.

rvec

The rotation vector (Rodrigues) that, together with tvec, performs a change of basis from world to camera coordinate system, see calibrateCamera for details.

tvec

The translation vector, see parameter description above.

cameraMatrix

Camera intrinsic matrix \cameramatrix{A} .

distCoeffs

Input vector of distortion coefficients \distcoeffs . If the vector is empty, the zero distortion coefficients are assumed.

imagePoints

Output destination, filled by the native operation. Output array of image points in pixel coordinates, 1xN/Nx1 2-channel, or vector<Point2f> .

jacobian

Output destination, filled by the native operation. Optional output 2Nx(10+<numDistCoeffs>) jacobian matrix of derivatives of image points with respect to components of the rotation vector, translation vector, focal lengths, coordinates of the principal point and the distortion coefficients. In the old interface different components of the jacobian are returned via different output parameters.

aspectRatio

Optional "fixed aspect ratio" parameter. If the parameter is not 0, the function assumes that the aspect ratio (f_x / f_y) is fixed and correspondingly adjusts the jacobian matrix.

Upstream declaration ↗

These signatures describe this package. Upstream documentation can mention optional backends that are absent from this build. Check runtime compatibility before choosing a backend or file format.