u_autoexpgain.c File Reference

Automatically compute exposure and gain values from an image stream. More...

#include "math/m_api.h"
#include "util/u_autoexpgain.h"
#include "util/u_debug.h"
#include "util/u_format.h"
#include "util/u_logging.h"
#include "util/u_misc.h"
#include "util/u_var.h"
#include <assert.h>
#include <math.h>
#include <stdint.h>
#include <stdio.h>

Include dependency graph for u_autoexpgain.c:

Data Structures
struct	u_autoexpgain
	Auto exposure and gain (AEG) adjustment algorithm state. More...

Macros
#define	AEG_TRACE(...)   U_LOG_IFL_T(aeg->log_level, __VA_ARGS__)
#define	AEG_DEBUG(...)   U_LOG_IFL_D(aeg->log_level, __VA_ARGS__)
#define	AEG_INFO(...)   U_LOG_IFL_I(aeg->log_level, __VA_ARGS__)
#define	AEG_WARN(...)   U_LOG_IFL_W(aeg->log_level, __VA_ARGS__)
#define	AEG_ERROR(...)   U_LOG_IFL_E(aeg->log_level, __VA_ARGS__)
#define	AEG_ASSERT(predicate, ...)
#define	AEG_ASSERT_(predicate)   AEG_ASSERT(predicate, "Assertion failed " #predicate)
#define	LEVELS   256
	Possible pixel intensity values, only 8-bit supported. More...
#define	INITIAL_BRIGHTNESS   0.5
#define	INITIAL_MAX_BRIGHTNESS_STEP   0.1
#define	INITIAL_THRESHOLD   0.1
#define	GRID_COLS   32
	Amount of columns for the histogram sample grid. More...

Enumerations
enum	u_aeg_state {   IDLE = 0 , BRIGHTEN , STOP_BRIGHTEN , DARKEN ,   STOP_DARKEN }
	AEG State machine states. More...
enum	u_aeg_action { GOOD = 0 , DARK , BRIGHT }
	This actions are triggered when the image is too dark, bright or good enough. More...

Functions
static const char *	state_to_string (enum u_aeg_state state)
static const char *	action_to_string (enum u_aeg_action action)
static void	set_state (struct u_autoexpgain *aeg, enum u_aeg_action action)
	Defines the AEG state machine transitions. More...
static void	brightness_to_expgain (struct u_autoexpgain *aeg, float brightness, float *out_exposure, float *out_gain)
	Maps a brightness in [0, 1] to a pair of exposure and gain values based on a piecewise function. More...
static void	update_expgain (struct u_autoexpgain *aeg)
	Update exposure and gain based on current brightness value. More...
static float	get_score (struct u_autoexpgain *aeg, struct xrt_frame *xf)
	Returns a value in the range [-1, 1] describing how dark-bright the image is, 0 means it's alright. More...
static void	update_brightness (struct u_autoexpgain *aeg, struct xrt_frame *xf)
struct u_autoexpgain *	u_autoexpgain_create (enum u_aeg_strategy strategy, bool enabled_from_start, int frame_delay)
	Create auto exposure and gain (AEG) algorithm object. More...
void	u_autoexpgain_add_vars (struct u_autoexpgain *aeg, void *root, char *prefix)
	Setup UI for the AEG algorithm. More...
void	u_autoexpgain_update (struct u_autoexpgain *aeg, struct xrt_frame *xf)
	Update the AEG with a frame. More...
float	u_autoexpgain_get_exposure (struct u_autoexpgain *aeg)
	Get currently computed exposure value in usecs. More...
float	u_autoexpgain_get_gain (struct u_autoexpgain *aeg)
	Get currently computed gain value in the [0, 255] range. More...
void	u_autoexpgain_destroy (struct u_autoexpgain **aeg)
	Destroy AEG object. More...

Detailed Description

Automatically compute exposure and gain values from an image stream.

Author

Mateo de Mayo mateo.nosp@m..dem.nosp@m.ayo@c.nosp@m.olla.nosp@m.bora..nosp@m.com

Macro Definition Documentation

AEG_ASSERT

#define AEG_ASSERT	(		predicate,
			...
	)

Value:

        do {                                                                                                           \
                bool p = predicate;                                                                                    \
                if (!p) {                                                                                              \
                        U_LOG(U_LOGGING_ERROR, __VA_ARGS__);                                                           \
                        assert(false && "AEG_ASSERT failed: " #predicate);                                             \
                        exit(EXIT_FAILURE);                                                                            \
                }                                                                                                      \
        } while (false);

GRID_COLS

#define GRID_COLS   32

Amount of columns for the histogram sample grid.

LEVELS

#define LEVELS   256

Possible pixel intensity values, only 8-bit supported.

Enumeration Type Documentation

u_aeg_action

enum u_aeg_action

This actions are triggered when the image is too dark, bright or good enough.

u_aeg_state

enum u_aeg_state

AEG State machine states.

Enumerator
STOP_BRIGHTEN	Avoid oscillations by.
STOP_DARKEN	Similar to STOP_BRIGHTEN.

Function Documentation

brightness_to_expgain()

static void brightness_to_expgain ( struct u_autoexpgain *  aeg, float  brightness, float *  out_exposure, float *  out_gain  )

static

Maps a brightness in [0, 1] to a pair of exposure and gain values based on a piecewise function.

These are steps for constructing a piecewise linear function that maps brightness into (exposure, gain) pairs.

< Brightness

< Exposure

< Gain

Referenced by update_expgain().

get_score()

static float get_score ( struct u_autoexpgain *  aeg, struct xrt_frame *  xf  )

static

Returns a value in the range [-1, 1] describing how dark-bright the image is, 0 means it's alright.

References GRID_COLS, u_autoexpgain::histogram, LEVELS, u_autoexpgain::strategy, U_AEG_STRATEGY_DYNAMIC_RANGE, U_AEG_STRATEGY_TRACKING, and u_format_block_size().

set_state()

static void set_state ( struct u_autoexpgain *  aeg, enum u_aeg_action  action  )

static

Defines the AEG state machine transitions.

The main idea is that if brightness needs to change then we go from IDLE to BRIGHTEN/DARKEN. To avoid oscillations we detect overshootings and exponentially backoff our brightness step. We only reset our overshoots counter after the image have been good for frame_delay frames, this delay is counted during STOP_DARKEN/STOP_BRIGHTEN states.

A diagram of the state machine is below:

References u_autoexpgain::state.

u_autoexpgain_add_vars()

void u_autoexpgain_add_vars	(	struct u_autoexpgain *	aeg,
		void *	root,
		char *	prefix
	)

Setup UI for the AEG algorithm.

u_autoexpgain_create()

struct u_autoexpgain * u_autoexpgain_create	(	enum u_aeg_strategy	strategy,
		bool	enabled_from_start,
		int	frame_delay
	)

Create auto exposure and gain (AEG) algorithm object.

Parameters

strategy	What objective is preferred for the algorithm.
enabled_from_start	Update exposure/gain from the start.
frame_delay	About how many frames does it take for exp and gain to settle in.

Returns

struct u_autoexpgain* Created object

References u_autoexpgain::enable, u_autoexpgain::state, and U_TYPED_CALLOC.

u_autoexpgain_destroy()

void u_autoexpgain_destroy

(

struct u_autoexpgain **

aeg

)

Destroy AEG object.

u_autoexpgain_get_exposure()

float u_autoexpgain_get_exposure

(

struct u_autoexpgain *

aeg

)

Get currently computed exposure value in usecs.

References u_autoexpgain::exposure.

Referenced by update_expgain().

u_autoexpgain_get_gain()

float u_autoexpgain_get_gain

(

struct u_autoexpgain *

aeg

)

Get currently computed gain value in the [0, 255] range.

References u_autoexpgain::gain.

Referenced by update_expgain().

u_autoexpgain_update()

void u_autoexpgain_update	(	struct u_autoexpgain *	aeg,
		struct xrt_frame *	xf
	)

Update the AEG with a frame.

Referenced by update_expgain().

update_expgain()

static void update_expgain ( struct u_autoexpgain *  aeg )

static

Update exposure and gain based on current brightness value.

References u_autoexpgain::brightness, brightness_to_expgain(), u_autoexpgain::exposure, u_autoexpgain::gain, and u_autoexpgain::last_brightness.