From be281478dc017797348f3ef92428bc78a3c74dd1 Mon Sep 17 00:00:00 2001 From: Pekka Paalanen Date: Mon, 20 Jun 2022 16:24:34 +0300 Subject: [PATCH] tests/color_util: doc rgb_diff_stat and scalar_stat Add documentation for test authors. Signed-off-by: Pekka Paalanen --- tests/color_util.c | 62 ++++++++++++++++++++++++++++++++++++++++++++++ tests/color_util.h | 8 ++++++ 2 files changed, 70 insertions(+) diff --git a/tests/color_util.c b/tests/color_util.c index 1f0928b6..da5eb5a3 100644 --- a/tests/color_util.c +++ b/tests/color_util.c @@ -373,6 +373,25 @@ lcmsMAT3_invert(struct lcmsMAT3 *result, const struct lcmsMAT3 *mat) lcmsMAT3_from_weston_matrix(result, &inv); } +/** Update scalar statistics + * + * \param stat The statistics structure to update. + * \param val A sample of the variable whose statistics you are collecting. + * \param pos The "position" that generated the current value. + * + * Accumulates min, max, sum and count statistics with the given value. + * Stores the position related to the current max and min each. + * + * To use this, declare a variable of type struct scalar_stat and + * zero-initialize it. Repeatedly call scalar_stat_update() to accumulate + * statistics. Then either directly read out what you are interested in from + * the structure, or use the related accessor or printing functions. + * + * If you also want to collect a debug log of all calls to this function, + * initialize the .dump member to a writable file handle. This is easiest + * with fopen_dump_file(). Remember to fclose() the handle after you have + * no more samples to add. + */ void scalar_stat_update(struct scalar_stat *stat, double val, @@ -397,12 +416,14 @@ scalar_stat_update(struct scalar_stat *stat, } } +/** Return the average of the previously seen values. */ float scalar_stat_avg(const struct scalar_stat *stat) { return stat->sum / stat->count; } +/** Print scalar statistics with pos.r only */ void scalar_stat_print_float(const struct scalar_stat *stat) { @@ -426,6 +447,20 @@ print_rgb_at_pos(const struct scalar_stat *stat, double scale) testlog(" avg %8.5f\n", scalar_stat_avg(stat) * scale); } +/** Print min/max/avg for each R/G/B/two-norm statistics + * + * \param stat The statistics to print. + * \param title A custom title to include in the heading which shall be printed + * like "%s error statistics:". + * \param scaling_bits Determines a scaling factor for the printed numbers as + * 2^scaling_bits - 1. + * + * Usually RGB values are stored in unsigned integer representation. 8-bit + * integer range is [0, 255] for example. Passing scaling_bits=8 will multiply + * all values (differences, two-norm errors, and position values) by + * 2^8 - 1 = 255. This makes interpreting the recorded errors more intuitive + * through the integer encoding precision perspective. + */ void rgb_diff_stat_print(const struct rgb_diff_stat *stat, const char *title, unsigned scaling_bits) @@ -446,6 +481,33 @@ rgb_diff_stat_print(const struct rgb_diff_stat *stat, print_rgb_at_pos(&stat->two_norm, scale); } +/** Update RGB difference statistics + * + * \param stat The statistics structure to update. + * \param ref The reference color to compare to. + * \param val The color produced by the algorithm under test; a sample. + * \param pos The position to be recorded with extremes. + * + * Computes the RGB difference by subtracting the reference color from the + * sample. This signed difference is tracked separately for each color channel + * in a scalar_stat to find the min, max, and average signed difference. The + * two-norm (Euclidean length) of the RGB difference vector is tracked in + * another scalar_stat. + * + * The position is stored separately for each of the eight min/max + * R/G/B/two-norm values recorded. A good way to use position is to record + * the algorithm input color. + * + * To use this, declare a variable of type struct rgb_diff_stat and + * zero-initalize it. Repeatedly call rgb_diff_stat_update() to accumulate + * statistics. Then either directly read out what you are interested in from + * the structure or use rgb_diff_stat_print(). + * + * If you also want to collect a debug log of all calls to this function, + * initialize the .dump member to a writable file handle. This is easiest + * with fopen_dump_file(). Remember to fclose() the handle after you have + * no more samples to add. + */ void rgb_diff_stat_update(struct rgb_diff_stat *stat, const struct color_float *ref, diff --git a/tests/color_util.h b/tests/color_util.h index 7a361a6b..fab42440 100644 --- a/tests/color_util.h +++ b/tests/color_util.h @@ -123,6 +123,10 @@ transfer_fn_name(enum transfer_fn fn); void lcmsMAT3_invert(struct lcmsMAT3 *result, const struct lcmsMAT3 *mat); +/** Scalar statistics + * + * See scalar_stat_update(). + */ struct scalar_stat { double min; struct color_float min_pos; @@ -145,6 +149,10 @@ struct scalar_stat { FILE *dump; }; +/** RGB difference statistics + * + * See rgb_diff_stat_update(). + */ struct rgb_diff_stat { struct scalar_stat rgb[COLOR_CHAN_NUM]; struct scalar_stat two_norm;