NAME
get_projection_matrix  Projects RGB data into a 2D 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_64linuxgnu
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.
 DIVIDE_BY_RED  0.
 DIVIDE_BY_GREEN  1.
 DIVIDE_BY_BLUE  2.
 DIVIDE_BY_SUM
 ONTO_RG_PLANE
 ONTO_RB_PLANE
 ONTO_GB_PLANE
 ONTO_UNIT_SPHERE
 INVALID_PROJECTION_METHOD

double max_projection_coordinate

Max value in projected coords.
DESCRIPTION
This routine projects RGB data into a 2D 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