Coordinate transform

Coordinate transform

Typedefs

typedef void(* va_distort_func)(const va_camera_parameters* , const double* , double*)

Functions

double va_from_frame(const va_coordinate_frame* frame, const double* input, int dimensions, double* output)
double va_to_frame(const va_coordinate_frame* frame, const double* input, int dimensions, double* output)
int va_invert_frame(const va_coordinate_frame* input, va_coordinate_frame* output)
int va_preserves_shape(const va_coordinate_frame* frame)
int va_world_to_pixel(const va_coordinate_frame* world_frame, const va_camera_parameters* camera, const double* input, int count, int dimensions, double* output)
int va_pixel_to_world(const va_coordinate_frame* camera_frame, const va_camera_parameters* camera, const double* input, int count, int dimensions, double* output)
int va_frame_scaling_factors(const va_coordinate_frame* frame, double* x_factor, double* y_factor)
int va_to_pixel_scaling_terms(const va_coordinate_frame* world_frame, const va_camera_parameters* camera, double* x_factor, double* y_factor, double* x_translation, double* y_translation)
double va_to_pixel_scaling_at(const va_coordinate_frame* world_frame, const va_camera_parameters* camera, double world_x, double world_y, double world_z)
int va_to_world_scaling_terms(const va_coordinate_frame* camera_frame, const va_camera_parameters* camera, double* x_factor, double* y_factor, double* x_translation, double* y_translation)
double va_to_world_scaling_at(const va_coordinate_frame* camera_frame, const va_camera_parameters* camera, double pixel_x, double pixel_y)
int va_world_to_pixel_3d(const va_coordinate_frame* world_frame, const va_camera_parameters* camera, va_distort_func distort, const double* input, int dimensions, double* output)
int va_pixel_to_world_3d(const va_coordinate_frame* camera_frame, const va_camera_parameters* camera, va_distort_func undistort, const double* input, double* output)
double va_pixel_distance(const va_coordinate_frame* world_frame, const va_camera_parameters* camera, const double* start_point, const double* end_point, int dimensions)
int va_sample_count(const va_coordinate_frame* world_frame, const va_coordinate_frame* camera_frame, const va_camera_parameters* camera, const double* start_point_world, const double* end_point_world, int dimensions, double* start_point_pixel=0, double* end_point_pixel=0)
int va_is_translation(const va_coordinate_frame* world_frame)
void va_distort(const va_camera_parameters* camera, const double* input, double* output)
void va_undistort(const va_camera_parameters* camera, const double* input, double* output)

Typedef Documentation

typedef void(* va_distort_func)(const va_camera_parameters* , const double* , double*)

A non-linear distortion function used in conversions between world and pixel coordinates. Maps given coordinates to target coordinates.

See also
va_world_to_pixel_3d()
va_pixel_to_world_3d()

Function Documentation

void va_distort(const va_camera_parameters* camera, const double* input, double* output )

Converts a point in normalized image coordinates to pixel coordinates by applying a lens distortion model.

Parameters
cameraCamera calibration data.
inputThe normalized image coordinates (x, y).
outputPixel coordinates (x, y).
int va_frame_scaling_factors(const va_coordinate_frame* frame, double* x_factor, double* y_factor )

Extracts horizontal and vertical scaling factors from a coordinate frame, provided that the frame represents a 2D scaling. The rationale for this function is that when a coordinate frame represents scaling and no rotation or other affine deformations, it is often much faster to just scale the coordinates than to apply the full transformation.

Note that this function does not take a possible scaling of the z coordinate into account. Thus, the returned scaling factors are only valid if z = 0. In other cases, the scaling factors must be adjusted according to perspective projection.

Parameters
framethe coordinate frame from which scaling factors are to be extracted.
x_factorhorizontal scaling factor. Accurate only if frame is a 2D scaling transformation. If it is not, an approximate scaling factor at the principal point (where optical axis intersects world xy plane) will be stored.
y_factorvertical scaling factor.
Returns
1 if frame represents 2D scaling, 0 otherwise
double va_from_frame(const va_coordinate_frame* frame, const double* input, int dimensions, double* output )

Converts the coordinates of a point in a coordinate frame to coordinates in the enclosing frame. This function can be used for example to convert a point in world coordinates to the camera reference frame using the world frame as a parameter.

Parameters
framethe coordinate frame that contains the input point
inputcoordinates of the point in frame.
dimensionsthe number of dimensions in input and output (either 2 or 3). If dimensions is two, the input z is assumed to be zero, and output z will not be stored.
outputan array of at least dimensions elements for storing the result. If the three-dimensional homogeneous input point (1-by-4 column vector) is denoted by X and the frame (4-by-4 matrix) by F, the result is FX. The function supports in-place transformation: input and output can be the same array.
Returns
the z coordinate of the output point.
double world_point[] = { -100, 50, 0 };
double camera_point[3];
va_from_frame(img->world_frame, world_point, 3, camera_point);
int va_invert_frame(const va_coordinate_frame* input, va_coordinate_frame* output )

Creates an inverse of a coordinate frame. The original coordinate frame transforms points in it to its enclosing frame whereas the inverse does the opposite. Returns 1 on success and 0 if input cannot be inverted.

int va_is_translation(const va_coordinate_frame* world_frame)

Returns true if world_frame is pure translation (i.e. 3x3 identity matrix).

double va_pixel_distance(const va_coordinate_frame* world_frame, const va_camera_parameters* camera, const double* start_point, const double* end_point, int dimensions )

Given two points, start_point and end_point in the specified world frame and camera set-up, returns the distance between the points in pixels. If the distance cannot be calculated, returns NAN. If start_point and end_point are the same, returns 0.

int va_pixel_to_world(const va_coordinate_frame* camera_frame, const va_camera_parameters* camera, const double* input, int count, int dimensions, double* output )

Converts pixel coordinates in the given image to the world coordinate system. In general, there is no unique solution. This function assumes that the target object is planar and forms the xy plane of the world coordinate system. Consequently, the z coordinate of the result will always be zero and does not need to be calculated.

Parameters
camera_framethe location and orientation of the camera reference frame in world coordinates. This is the inverse of the world frame.
cameracamera calibration parameters
inputa pointer to pixel coordinates. This array contains count pairs of (x, y) coordinates so that the total number is 2 times count.
countthe number of (x, y) coordinates in input
dimensionsthe number of dimensions in the output array (2 or 3). If the number of dimensions is three, the z coordinate will be set to zero.
outputan array of at least dimensions times count numbers to store the world coordinates.
Returns
The numbers of points transformed successfully. If a transformation fails, the corresponding coordinates in the output array will be set to NAN.
int va_pixel_to_world_3d(const va_coordinate_frame* camera_frame, const va_camera_parameters* camera, va_distort_func undistort, const double* input, double* output )

Converts a point in pixel coordinates to world coordinates. This function assumes that the z coordinate of the pixel in the world coordinate system is zero.

Parameters
camera_frameThe position of the camera in world coordinates.
cameraCamera calibration data.
undistortA non-linear undistortion function that maps coordinates distorted by the lens back to normalized image coordinates. May be a null pointer.
inputThe pixel coordinates (x, y) of an input pixel.
outputAn array for storing the resulting world coordinates. Must be able to hold at least two numbers. Since the z coordinate is assumed to be zero, no space for it is needed.
Returns
1 on success, 0 on failure. The conversion fails if the resulting point would not be in front of the camera.
int va_preserves_shape(const va_coordinate_frame* frame)

Returns 1 if frame is a 2-D rotation or scaling transformation that preserves the shape of an object. If frame contains shearing, non-uniform scaling or 3-D terms, returns 0. This function can be used to test if the shape of an object is the same in the world and on the image plane.

int va_sample_count(const va_coordinate_frame* world_frame, const va_coordinate_frame* camera_frame, const va_camera_parameters* camera, const double* start_point_world, const double* end_point_world, int dimensions, double* start_point_pixel = 0, double* end_point_pixel = 0 )

Given two points, start_point and end_point in the specified world frame and camera set-up, returns the minimum number of equally spaced samples that must be taken along the line connecting start_point and end_point to guarantee that each pixel is sampled at least once. Pixel coordinates of start and end points are stored in start_point_pixel and end_point_pixel unless they are null pointers. If coordinate transform does not succeed, returns 0 and does not write anything to start_point_pixel and end_point_pixel.

double va_to_frame(const va_coordinate_frame* frame, const double* input, int dimensions, double* output )

Converts coordinates in a coordinate to an inner coordinate frame. The function works as if frame was first inverted using va_invert_frame and then passed to va_from_frame. If you need to convert many points at once, it is more efficient to first invert frame with va_invert_frame() and then call va_from_frame().

Parameters
framethe frame to which the coordinates are to be moved. This frame must be in the same coordinate system as the input point.
inputthe coordinates of a point outside of the frame.
dimensionsthe number of dimensions in input and output (either 2 or 3). If dimensions is two, the input z is assumed to be zero, and output z will not be stored.
outputan array of at least dimensions elements for storing the result. If the three-dimensional homogeneous input point (1-by-4 column vector) is denoted by X and the frame (4-by-4 matrix) by F, the result is inv(F)X. The function supports in-place transformation: input and output can be the same array.
Returns
the z coordinate of the output point or NAN if the transformation fails.
double va_to_pixel_scaling_at(const va_coordinate_frame* world_frame, const va_camera_parameters* camera, double world_x, double world_y, double world_z )

Returns an approximate scaling factor from world to pixel coordinates around the given point. The result is accurate if the camera is linear and the world frame only represents scaling and/or translation. Returns NAN on failure.

int va_to_pixel_scaling_terms(const va_coordinate_frame* world_frame, const va_camera_parameters* camera, double* x_factor, double* y_factor, double* x_translation, double* y_translation )

Calculates scaling and translation terms that can be used to transform world coordinates to pixel coordinates directly. World coordinates can be transformed to pixel coordinates directly by scaling and translation if world_frame represents a 2D scaling (see va_frame_scaling_factors) and there are no non-linear terms in camera.

Returns
1 if world coordinates can be transformed to pixels using scaling and translation, 0 otherwise.
double va_to_world_scaling_at(const va_coordinate_frame* camera_frame, const va_camera_parameters* camera, double pixel_x, double pixel_y )

Returns an approximate scaling factor from pixel to world coordinates around the given point. The result is accurate if the camera is linear and the camera frame only represents scaling and/or translation. Returns NAN on failure.

int va_to_world_scaling_terms(const va_coordinate_frame* camera_frame, const va_camera_parameters* camera, double* x_factor, double* y_factor, double* x_translation, double* y_translation )

Calculates scaling and translation terms that can be used to transform pixel coordinates to world coordinates directly. Scaling and translation are accurate over the whole image if the camera is linear and the camera frame only represents scaling and/or translation.

void va_undistort(const va_camera_parameters* camera, const double* input, double* output )

Converts a point in pixel coordinates to normalized image coordinates by applying an inverse lens distortion model.

Parameters
cameraCamera calibration data.
inputPixel coordinates (x, y).
outputNormalized image coordinates (x, y).
int va_world_to_pixel(const va_coordinate_frame* world_frame, const va_camera_parameters* camera, const double* input, int count, int dimensions, double* output )

Converts coordinates in the world coordinate system to pixel coordinates in the given image.

Parameters
world_framethe location and orientation of the world coordinate system in the camera reference frame.
cameracamera calibration parameters
inputa pointer to world coordinates. This array contains count (x, y) or (x, y, z) coordinates. If dimensions is two, the points are assumed to be on the xy plane of the input coordinate system (z = 0).
countthe number of (x, y) coordinates in input
dimensionsthe number of dimensions in input coordinates (2 or 3). If the number of dimensions is two, z is assumed to be zero.
outputan array of at least 2 times count numbers to store the pixel coordinates.
Returns
The number of points transformed successfully. If a transformation fails, the corresponding coordinates in the output array will be set to NAN.
int va_world_to_pixel_3d(const va_coordinate_frame* world_frame, const va_camera_parameters* camera, va_distort_func distort, const double* input, int dimensions, double* output )

Converts a point in world coordinates to pixel coordinates.

Parameters
world_frameThe position of the world coordinate system with respect to the camera.
cameraCamera calibration data.
distortA non-linear distortion function that models the effect of a lens. Maps normalized image coordinates to distorted pixel coordinates. May be a null pointer.
inputWorld coordinates. The input array must contain dimensions entries.
dimensionsEither 2 or 3. If dimensions is two, the z coordinate is assumed to be zero.
outputAn array for storing the resulting pixel coordinates. Must be able to hold at least two numbers.
Returns
1 on success, 0 on failure. The conversion fails if the input point is not in front of the camera.