va_coordinate_transform.h🔗

#include <va_coordinate_transform.h>

Typedefs

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: va_world_to_pixel_3d()
See: va_pixel_to_world_3d()

Functions

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.

double world_point[] = { -100, 50, 0 };
double camera_point[3];

va_from_frame(img->world_frame, world_point, 3, camera_point);

Return

the z coordinate of the output point.

Parameters

frame: the coordinate frame that contains the input point
input: coordinates of the point in frame.
dimensions: the 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.
output: an 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.

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().

Return

the z coordinate of the output point or NAN if the transformation fails.

Parameters

frame: the frame to which the coordinates are to be moved. This frame must be in the same coordinate system as the input point.
input: the coordinates of a point outside of the frame.
dimensions: the 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.
output: an 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.

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 VA_SUCCESS on success, VA_ERR_NOT_INVERTIBLE if input cannot be inverted.

int va_preserves_shape(const va_coordinate_frame *frame)🔗

Returns a non-zero value 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_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.

Return

The number of points transformed successfully. If a transformation fails, the corresponding coordinates in the output array will be set to NAN.

Parameters

world_frame: the location and orientation of the world coordinate system in the camera reference frame.
camera: camera calibration parameters
input: a 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).
count: the number of (x, y) coordinates in input
dimensions: the number of dimensions in input coordinates (2 or 3). If the number of dimensions is two, z is assumed to be zero.
output: an array of at least 2 times count numbers to store the pixel coordinates.

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 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.

Return

The number of points transformed successfully. If a transformation fails, the corresponding coordinates in the output array will be set to NAN.

Parameters

camera_frame: the location and orientation of the camera reference frame in world coordinates. This is the inverse of the world frame.
camera: camera calibration parameters
input: a pointer to pixel coordinates. This array contains count pairs of (x, y) coordinates so that the total number is 2 times count.
count: the number of (x, y) coordinates in input
dimensions: the 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.
output: an array of at least dimensions times count numbers to store the world coordinates.

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.

Return

VA_SUCCESS if frame represents 2D scaling, VA_ERR_INVALID_PARAMETER otherwise. Nothing is written in x_factor or y_factor in the error case.

Parameters

frame: the coordinate frame from which scaling factors are to be extracted.
x_factor: horizontal 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_factor: vertical scaling 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)🔗

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.

Return: VA_SUCCESS if world coordinates can be transformed to pixels using scaling and translation, VA_ERR_INVALID_PARAMETER otherwise. Nothing is written in the output parameters in the error case.

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_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. Returns VA_SUCCESS on success, VA_ERR_INVALID_PARAMETER if either va_is_linear_camera(camera) or va_frame_scaling_factors(camera_frame) returns an error.

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_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.

Return

VA_SUCCESS on success, VA_ERR_INVALID_PARAMETER on failure. The conversion fails if the input point is not in front of the camera.

Parameters

world_frame: The position of the world coordinate system with respect to the camera.
camera: Camera calibration data.
distort: A non-linear distortion function that models the effect of a lens. Maps normalized image coordinates to distorted pixel coordinates. May be a null pointer.
input: World coordinates. The input array must contain dimensions entries.
dimensions: Either 2 or 3. If dimensions is two, the z coordinate is assumed to be zero.
output: An array for storing the resulting pixel coordinates. Must be able to hold at least two numbers.

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.

Return

VA_SUCCESS on success, VA_ERR_INVALID_PARAMETER on failure. The conversion fails if the resulting point would not be in front of the camera.

Parameters

camera_frame: The position of the camera in world coordinates.
camera: Camera calibration data.
undistort: A non-linear undistortion function that maps coordinates distorted by the lens back to normalized image coordinates. May be a null pointer.
input: The pixel coordinates (x, y) of an input pixel.
output: An 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.

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_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.

int va_is_translation(const va_coordinate_frame *world_frame)🔗

Returns a non-zero value if world_frame is pure translation (i.e.

3x3 identity matrix) and 0 otherwise.

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

camera: Camera calibration data.
input: The normalized image coordinates (x, y).
output: Pixel coordinates (x, y).

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

camera: Camera calibration data.
input: Pixel coordinates (x, y).
output: Normalized image coordinates (x, y).