NAME

get_projection_matrix - Projects RGB data into a 2-D space

SYNOPSIS

#include "c/c_projection.h"

Example compile flags (system dependent):
  -DLINUX_X86_64 -DLINUX_X86_64_OPTERON  -DGNU_COMPILER 
   -I/home/kobus/include
   -L/home/kobus/misc/load/linux_x86_64_opteron -L/usr/lib/x86_64-linux-gnu
  -lKJB                               -lfftw3  -lgsl -lgslcblas -ljpeg  -lSVM -lstdc++                    -lpthread -lSLATEC -lg2c    -lacml -lacml_mv -lblas -lg2c      -lncursesw 


int get_projection_matrix
(
	Matrix **output_mpp,
	const Matrix *input_mp,
	Projection_method projection_method,
	Invalid_chromaticity_action invalid_chromaticity_action,
	double max_projection_coordinate,
	double absolute_pixel_error,
	double relative_pixel_error,
	Matrix **error_box_mpp,
	Matrix **error_points_mpp
);

PARAMETERS

Matrix **output_mpp
Output chromaticity matrix.
const Matrix *input_mp
Input RGB matrix.
Projection_method projection_method
Type of chromaticity.

Possible values for a 

Projection_method
are as follows: The first four are set based on backwards compatability. Hopefully all the dependencies on the specific values have been purged, but by using the same numeric values as before, things won't break regardless.
double max_projection_coordinate
Max value in projected coords.

DESCRIPTION

This routine projects RGB data into a 2-D space, normally a chromaticity space specified by the argument "projection_method". "projection method" should be one of DIVIDE_BY_RED, DIVIDE_BY_GREEN, DIVIDE_BY_BLUE, DIVIDE_BY_SUM, ONTO_RG_PLANE, ONTO_GB_PLANE, or ONTO_RB_PLANE. If "projection_method" is one of DIVIDE_BY_RED, DIVIDE_BY_GREEN, or DIVIDE_BY_BLUE, then the argument "max_projection_coordinate" should be used to limit the size of the result in the case of denominators being too close to zero. Ideally, the effect of attempting to exceed "max_projection_coordinate" should be under the control of the argument "invalid_chromaticity_action", but currently this argument is ignored. However, in order to be compatable with future code, the argument "invalid_chromaticity_action" should be set to TRUNCATE_INVALID_CHROMATICITY for these three projection methods. If "projection_method" is DIVIDE_BY_SUM, then "max_projection_coordinate" is used to specify the reciprocal of the smallest value of the sum which is considered valid. For example, if "max_projection_coordinate" is 1000, then any pixel with R+G+B < 0.001 is considered invalid, and an action dictated by invalid_chromaticity_action is taken. Possible actions are SKIP_INVALID_CHROMATICITY, ZERO_INVALID_CHROMATICITY, and NEGATE_INVALID_CHROMATICITY. If "projection_method" is one of ONTO_RG_PLANE, ONTO_GB_PLANE, or ONTO_RB_PLANE, the "max_projection_coordinate" argument is essentially ignored, but should have the value DBL_NOT_SET. If "max_projection_coordinate" is negative, then a default value is used. If one (or both) of "error_box_mpp" or "error_points_mpp" are not NULL, and "projection method" is one of DIVIDE_BY_RED, DIVIDE_BY_GREEN, DIVIDE_BY_BLUE, or DIVIDE_BY_SUM, then a result representing the range of points based on "absolute_pixel_error" and "relative_pixel_error" is computed. If "error_box_mpp" and "error_points_mpp" are both NULL, then the error parameters "absolute_pixel_error" and "relative_pixel_error" are ignored, but by convention they should have the value DBL_NOT_SET. A more specific routine get_divide_by_sum_projection_matrix() is available if it is known in advance that the projection method will be DIVIDE_BY_SUM.

RETURNS

NO_ERROR on success; ERROR on failure.

NOTE

The semantics of the routines in this module are ugly, and hopefully they will be changed for the better. However, it is recomended that these routines are used for colour projection regardless, to be consistent. Comments are welcome. (In other words, help use fix (and test!) this stuff, rather than reinventing the wheel).

NOTE

If the projection method is DIVIDE_BY_SUM, then the number of rows in the projected data can be less than that of the input. Similarly, the number of rows in the error results are not easily determined from the input size.

DISCLAIMER

This software is not adequatedly tested. It is recomended that results are checked independantly where appropriate.

AUTHOR

Kobus Barnard

DOCUMENTER

Kobus Barnard, Lindsay Martin

SEE ALSO

get_divide_by_sum_projection_matrix , project_matrix , divide_by_sum_project_matrix , project_matrix_onto_unit_sphere , get_projection_vector , project_vector , back_project_matrix , back_project_vector