| # param
Includes: | <AR/ar.h>
## Introduction ARToolKit functions for handling calibrated camera parameters. ## Functions `arParamClear` Create a camera parameter structure representing an idealised lens. `arParamIdeal2Observ` Use lens distortion parameters to convert idealised (zero-distortion) window coordinates to observed (distorted) coordinates. `arParamIdeal2ObservLTf` Use a lookup-table camera parameter to convert idealised (zero-distortion) window coordinates to observed (distorted) coordinates. `arParamLoad` Load lens parameters from a file. `arParamLoadFromBuffer` Load lens parameters from a buffer. `arParamLTCreate` Allocate and calculate a lookup-table camera parameter from a standard camera parameter. `arParamLTFree` Dispose of a memory allocated to a lookup-table camera parameter. `arParamObserv2Ideal` Use lens distortion parameters to convert observed (distorted) window coordinates to idealised (zero-distortion) coordinates. `arParamObserv2IdealLTf` Use a lookup-table camera parameter to convert observed (distorted) window coordinates to idealised (zero-distortion) coordinates. `arParamSave` Save lens parameters to a file. ### arParamClear Create a camera parameter structure representing an idealised lens.
    int arParamClear(
        ARParam *param,
        int xsize,
        int ysize,
        int dist_function_version );
##### Parameters `param` Pointer to an ARParam structure which will be filled out with the resulting camera parameters. `xsize` The horizontal dimension of the image. `ysize` The vertical dimension of the image. `dist_function_version` Allows creation of parameters with an older version of the lens distortion model. Pass AR_DIST_FUNCTION_VERSION_DEFAULT to create an ARParam with the current lens distortion model, or a lesser integer to use an earlier version. ##### Return Value 0 if the function completed successfully, or -1 in case of error. ##### Discussion This function creates a camera parameter structure representing an idealised lens, that is, a lens with a symmetrical perspective projection and no distortion. This idealised lens is useful in cases where you wish to match the lens model of an OpenGL camera with the same window dimensions. ### arParamIdeal2Observ Use 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 idealised normalised window coordinate x axis value. `iy` Input idealised normalised window coordinate y axis value. `ox` Pointer to ARdouble, which on return will hold the observed normalised window coordinate x axis value. `oy` Pointer to ARdouble, which on return will hold the observed 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 Value 0 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. ##### Discussion See 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. See Also arParamObserv2Ideal arParamObserv2IdealLTf ### arParamIdeal2ObservLTf Use a lookup-table camera parameter to convert idealised (zero-distortion) window coordinates to observed (distorted) coordinates.
    int arParamIdeal2ObservLTf(
        ARParamLTf *paramLTf,
        float ix,
        float iy,
        float *ox,
        float *oy);
##### Parameters `paramLTf` A lookup-table based version of the lens distortion parameters. These values are generated as part of the camera calibration process in ARToolKit, and converted to a lookup table by arParamLTCreate(). `ix` Input idealised normalised window coordinate x axis value. `iy` Input idealised normalised window coordinate y axis value. `ox` Pointer to ARdouble, which on return will hold the observed normalised window coordinate x axis value. `oy` Pointer to ARdouble, which on return will hold the observed normalised window coordinate y axis value. ##### Return Value 0 in case of function success, or -1 if an error occured. One possible error condition is the case where the input portion of the pair is outside the range of coordinates covered by the lookup table. ##### Discussion See function arParamObserv2IdealLTf() 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. See Also arParamLTCreate arParamIdeal2Observ arParamObserv2IdealLTf ### arParamLoad Load lens parameters from a file.
    int arParamLoad(
        const char *filename,
        int num,
        ARParam *param,
        ...);
##### Parameters `filename` Path to file from which to load the parameters. The file pointed to should be a file saved with arParamSave. `num` Number of ARParams to be loaded, normally 1. `param` Pointer to the ARParam structure into which the parameters will be read. ##### Return Value 0 if successful, or -1 if an error occured. ##### Discussion See the discussion under ARParam for more info. See Also ARParam arParamLoadFromBuffer arParamSave ### arParamLoadFromBuffer Load lens parameters from a buffer.
    int arParamLoadFromBuffer(
        const void *buffer,
        size_t bufsize,
        ARParam *param);
##### Parameters `buffer` Buffer from which the parameter(s) will be loaded. The buffer could be (for example) the contents of a parameter file read with fread(). `bufsize` Size of the contents of buffer. `param` Pointer to the ARParam structure into which the parameters will be read. ##### Return Value 0 if successful, or -1 if an error occured. ##### Discussion See the discussion under ARParam for more info. See Also ARParam arParamLoad arParamSave ### arParamLTCreate Allocate and calculate a lookup-table camera parameter from a standard camera parameter.
    ARParamLT *arParamLTCreate(
        ARParam *param,
        int offset );
##### Parameters `param` A pointer to an ARParam structure from which the lookup table will be generaeted. This ARParam structure will be copied, and the original may be disposed of. `offset` An integer value which specifies how much the lookup table values will be padded around the original camera parameters size. Normally, the default value AR_PARAM_LT_DEFAULT_OFFSET (defined elsewhere in this header) should be used. However, when using a camera with a large amount of lens distortion, a higher value may be required to cope with the corners or sides of the camera image frame. ##### Return Value A pointer to a newly-allocated ARParamLT structure, or NULL if an error occurred. Once the ARParamLT is no longer needed, it should be disposed of by calling arParamLTFree() on it. ##### Discussion A lookup-table based camera parameter offers significant performance savings in certain ARToolKit operations (including unwarping of pattern spaces) compared to use of the standard camera parameter. The original ARParam camera parameters structure is copied into the ARParamLT structure, and is available as paramLT->param. See Also arParamLTFree ### arParamLTFree Dispose of a memory allocated to a lookup-table camera parameter.
    int arParamLTFree(
        ARParamLT **paramLT_p );
##### Parameters `paramLT_p` Pointer to a pointer to the paramLT structure to be disposed of. On return, the location pointed to will be set to NULL. ##### Return Value -1 if an error occurred, or 0 in the case of no error. See Also arParamLTCreate ### arParamObserv2Ideal Use 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 or inverse conversions. ##### Return Value 0 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. ##### Discussion This 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. See Also arParamIdeal2Observ arParamIdeal2ObservLTf ### arParamObserv2IdealLTf Use a lookup-table camera parameter to convert observed (distorted) window coordinates to idealised (zero-distortion) coordinates.
    int arParamObserv2IdealLTf(
        ARParamLTf *paramLTf,
        float ox,
        float oy,
        float *ix,
        float *iy);
##### Parameters `paramLTf` A lookup-table based version of the lens distortion parameters. These values are generated as part of the camera calibration process in ARToolKit, and converted to a lookup table by arParamLTCreate(). `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. ##### Return Value 0 in case of function success, or -1 if an error occured. One possible error condition is the case where the input portion of the pair is outside the range of coordinates covered by the lookup table. ##### Discussion This 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. See Also arParamObserv2Ideal arParamIdeal2ObservLTf ### arParamSave Save lens parameters to a file.
    int arParamSave(
        const char *filename,
        const int num,
        const ARParam *param,
        ...);
##### Parameters `filename` Path to file to which to save the parameters. The file pointed to may later be reloaded with arParamLoad. `num` Number of ARParams to be saved, normally 1. `param` Pointer to the ARParam structure to save. ##### Return Value 0 if successful, or -1 if an error occured. ##### Discussion See the discussion under ARParam for more info. See Also ARParam arParamLoad arParamLoadFromBuffer ## Typedefs `ARParam` Structure holding camera parameters, including image size, projection matrix and lens distortion parameters. `ARParamLT` Structure holding camera parameters, in lookup table form. ### ARParam Structure holding camera parameters, including image size, projection matrix and lens distortion parameters.
    typedef struct {
        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. ##### Discussion ARToolKit'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. See Also arParamClear arParamLoad arParamSave ### ARParamLT Structure holding camera parameters, in lookup table form.
    typedef struct {
        ARParam param;
        ARParamLTf paramLTf;
        //ARParamLTi   paramLTi;
    } ARParamLT;
##### Fields `paramLTf` The lookup table. `param` A copy of original ARParam from which the lookup table was calculated. ##### Discussion ARToolKit'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. This version of the structure contains a pre-calculated lookup table of values covering the camera image width and height, plus a padded border. ## 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_PARAM_LT_DEFAULT_OFFSET` Default padding added around a lookup-table based camera parameter. ### AR_DIST_FACTOR_NUM_MAX Maximum number of values in a distortion factor array.
    #define AR_DIST_FACTOR_NUM_MAX 9
##### Discussion See function arParamObserv2Ideal() for discussion. ### AR_DIST_FUNCTION_VERSION_DEFAULT Default version for functions accepting a "distortion function version" parameter.
    #define AR_DIST_FUNCTION_VERSION_DEFAULT 4
##### Discussion See function arParamObserv2Ideal() for discussion. ### AR_DIST_FUNCTION_VERSION_MAX Maximum version allowable for functions accepting a "distortion function version" parameter.
    #define AR_DIST_FUNCTION_VERSION_MAX 4
##### Discussion See function arParamObserv2Ideal() for discussion. ### AR_PARAM_LT_DEFAULT_OFFSET Default padding added around a lookup-table based camera parameter.
    #define AR_PARAM_LT_DEFAULT_OFFSET 15
##### Discussion See function arParamLTCreate() for discussion. Last Updated: Monday, October 05, 2015