## param
## IntroductionARToolKit functions for handling calibrated camera parameters. ## Functions`arParamIdeal2Observ`Use lens distortion parameters to convert idealised (zero-distortion) window coordinates to observed (distorted) coordinates. `arParamObserv2Ideal`Use lens distortion parameters to convert observed (distorted) window coordinates to idealised (zero-distortion) coordinates.
## arParamIdeal2ObservUse lens distortion parameters to convert idealised (zero-distortion) window coordinates to observed (distorted) coordinates. int arParamIdeal2Observ( const ARdouble dist_factor[AR_DIST_FACTOR_NUM_MAX], const ARdouble ix, const ARdouble iy, ARdouble *ox, ARdouble *oy, const int dist_function_version ); ## Parameters-
`dist_factor` An array of ARdouble values holding the lens distortion parameters. These values are generated as part of the camera calibration process in ARToolKit. The exact number of values from the array used by the function is determined by the distortion function version, but does not exceed AR_DIST_FACTOR_NUM_MAX. -
`ix` Input observed normalised window coordinate x axis value. -
`iy` Input observed normalised window coordinate y axis value. -
`ox` Pointer to ARdouble, which on return will hold the idealised normalised window coordinate x axis value. -
`oy` Pointer to ARdouble, which on return will hold the idealised normalised window coordinate y axis value. -
`dist_function_version` -
An integer, in the range [1, AR_DIST_FUNCTION_VERSION_MAX] which determines the algorithm used to interpret the dist_factor values. See function arParamObserv2Ideal() for full discussion.
## Return Value0 in case of function success, or -1 if an error occured. At present the only error possible is an invalid value of dist_function_version. ## DiscussionSee function arParamObserv2Ideal() for full discussion. This function is the output function of the pair. It's inputs are idealised coordinates, e.g. taken from OpenGL. The outputs are the location where in a distorted image where the same point would lie. ## arParamObserv2IdealUse lens distortion parameters to convert observed (distorted) window coordinates to idealised (zero-distortion) coordinates. int arParamObserv2Ideal( const ARdouble dist_factor[AR_DIST_FACTOR_NUM_MAX], const ARdouble ox, const ARdouble oy, ARdouble *ix, ARdouble *iy, const int dist_function_version ); ## Parameters-
`dist_factor` An array of ARdouble values holding the lens distortion parameters. These values are generated as part of the camera calibration process in ARToolKit. The exact number of values from the array used by the function is determined by the distortion function version, but does not exceed AR_DIST_FACTOR_NUM_MAX. -
`ix` Input observed normalised window coordinate x axis value. -
`iy` Input observed normalised window coordinate y axis value. -
`ox` Pointer to ARdouble, which on return will hold the idealised normalised window coordinate x axis value. -
`oy` Pointer to ARdouble, which on return will hold the idealised normalised window coordinate y axis value. -
`dist_function_version` -
An integer, in the range [1, AR_DIST_FUNCTION_VERSION_MAX] which determines the algorithm used to interpret the dist_factor values. The values correspond to the following algorithms: version 1: The original ARToolKit lens model, with a single radial distortion factor, plus center of distortion. version 2: Improved distortion model, introduced in ARToolKit v4.0. This algorithm adds a quadratic term to the radial distortion factor of the version 1 algorithm. version 3: Improved distortion model with aspect ratio, introduced in ARToolKit v4.0. The addition of an aspect ratio to the version 2 algorithm allows for non-square pixels, as found e.g. in DV image streams. version 4: OpenCV-based distortion model, introduced in ARToolKit v4.3. This differs from the standard OpenCV model by the addition of a scale factor, so that input values do not exceed the range [-1.0, 1.0] in either forward nor inverse conversions.
## Return Value0 in case of function success, or -1 if an error occured. At present the only error possible is an invalid value of dist_function_version. ## DiscussionThis function is used by ARToolKit to convert for the the effects of lens distortion in images which have been acquired from lens-based optical systems. All lenses introduce some amount of lens distortion. ARToolKit includes calibration utilities to measure the centre of distortion and the radial distortion factors in the x and y dimensions. This calibration information is saved as part of the camera parameters. This function is one of a pair of functions which convert between OBSERVED window coordinates (i.e. the location of a known reference point, as measured in the x-y viewing plane of an image containing lens distortion) and IDEALISED coordinates (i.e. the location of the same reference point as measured in an image containing no radial distortion, e.g. an image rendered using OpenGL's viewing model.) This function is the input function of the pair. It's inputs are distorted coordinates, e.g. taken from an image acquired from a camera The outputs are the location where in an idealised image (e.g. generated with OpenGL) where the same point would lie. ## Typedefs`ARParam`Structure holding camera parameters, including image size, projection matrix and lens distortion parameters.
## ARParamStructure holding camera parameters, including image size, projection matrix and lens distortion parameters. typedef struct _ARParam { int xsize; int ysize; ARdouble mat[3][4]; ARdouble dist_factor[AR_DIST_FACTOR_NUM_MAX]; int dist_function_version; // Must be last field in structure (as will not be written to disk). } ARParam; ## Fields-
`xsize` The width in pixels of images returned by arVideoGetImage() for the camera. -
`ysize` The height in pixels of images returned by arVideoGetImage() for the camera. -
`mat` The projection matrix for the calibrated camera parameters. This can be converted to an OpenGL projection matrix by the function arglCameraFrustumRHf(). -
`dist_factor` See function arParamObserv2Ideal() for discussion. -
`dist_function_version` See function arParamObserv2Ideal() for discussion.
## DiscussionARToolKit's tracking depends on accurate knowledge of the properties of the imaging system used to acquire input images. This structure holds the properties of an imaging system for internal use in ARToolKit. This information is used throughout the entire ARToolKit pipeline, including knowing the size of images being returned by the video library, marker detection and pose estimation, and warping of camera images for video-see-through registration.
## Structs and Unions`_ARParam`Structure holding camera parameters, including image size, projection matrix and lens distortion parameters.
## _ARParam## Fields-
`xsize` The width in pixels of images returned by arVideoGetImage() for the camera. -
`ysize` The height in pixels of images returned by arVideoGetImage() for the camera. -
`mat` The projection matrix for the calibrated camera parameters. This can be converted to an OpenGL projection matrix by the function arglCameraFrustumRHf(). -
`dist_factor` See function arParamObserv2Ideal() for discussion. -
`dist_function_version` See function arParamObserv2Ideal() for discussion.
## DiscussionARToolKit's tracking depends on accurate knowledge of the properties of the imaging system used to acquire input images. This structure holds the properties of an imaging system for internal use in ARToolKit. This information is used throughout the entire ARToolKit pipeline, including knowing the size of images being returned by the video library, marker detection and pose estimation, and warping of camera images for video-see-through registration.
## Macro Definitions`AR_DIST_FACTOR_NUM_MAX`Maximum number of values in a distortion factor array. `AR_DIST_FUNCTION_VERSION_DEFAULT`Default version for functions accepting a "distortion function version" parameter. `AR_DIST_FUNCTION_VERSION_MAX`Maximum version allowable for functions accepting a "distortion function version" parameter.
## AR_DIST_FACTOR_NUM_MAXMaximum number of values in a distortion factor array. #define AR_DIST_FACTOR_NUM_MAX 9 ## DiscussionSee function arParamObserv2Ideal() for discussion. ## AR_DIST_FUNCTION_VERSION_DEFAULTDefault version for functions accepting a "distortion function version" parameter. #define AR_DIST_FUNCTION_VERSION_DEFAULT 4 ## DiscussionSee function arParamObserv2Ideal() for discussion. ## AR_DIST_FUNCTION_VERSION_MAXMaximum version allowable for functions accepting a "distortion function version" parameter. #define AR_DIST_FUNCTION_VERSION_MAX 4 ## DiscussionSee function arParamObserv2Ideal() for discussion. |