Stores the graph and energy costs for the Alpha-Expansion algorithm. More...

#include <EnergyModel.hpp>

Public Types
using	UnaryCostFn = std::function< T(int node, int label)>
	Callable that returns the unary cost for assigning `label` to `node`.

using	PairwiseCostFn = std::function< T(int node1, int node2, int label1, int label2)>

Public Member Functions
	EnergyModel (int num_nodes, int num_labels)
	Constructs an energy model with all labels initialized to 0.

int	num_nodes () const
	Returns the total number of nodes.

int	num_labels () const
	Returns the total number of labels.

int	get_label (int node) const
	Returns the current label assigned to `node`.

void	set_label (int node, int label)
	Assigns `label` to `node`.

const std::vector< int > &	get_labels () const
	Returns the full label vector (one entry per node).

void	set_labels (const std::vector< int > &labels)
	Replaces the full label vector.

void	set_unary_cost_fn (UnaryCostFn fn)
	Sets a callback function for unary costs.

void	set_pairwise_cost_fn (PairwiseCostFn fn)
	Sets a callback function for pairwise costs.

T	get_unary_cost (int node, int label) const
	Returns the unary cost for assigning `label` to `node`.

T	get_pairwise_cost (int node1, int node2, int label1, int label2) const
	Returns the pairwise cost for the given node–label pair.

void	set_unary_costs (const std::vector< T > &costs)
	Sets unary costs from a flat row-major array of size `num_nodes * num_labels`.

void	set_pairwise_costs (const std::vector< T > &costs)
	Sets a global pairwise cost matrix of size `num_labels * num_labels`.

void	set_edge_weights (const std::vector< int > &n1s, const std::vector< int > &n2s, const std::vector< T > &weights)
	Sets per-edge smoothness weights (Potts model).

void	add_neighbor (int node1, int node2)
	Adds an undirected edge between `node1` and `node2`.

void	add_grid_edges (int width, int height)
	Populates a 4-connected grid neighbourhood for an image of size `width` × `height`.

const std::vector< int > &	get_neighbors (int node) const
	Returns the neighbours of `node`.

std::vector< int >	get_active_nodes (int alpha_label) const
	Returns the indices of all nodes that do not currently have `alpha_label`.

T	evaluate_total_energy (const std::vector< int > &eval_labels) const
	Evaluates the total energy for a given label assignment.

T	evaluate_total_energy () const
	Evaluates the total energy for the model's current label assignment.

Detailed Description

template<typename T>
class EnergyModel< T >

Stores the graph and energy costs for the Alpha-Expansion algorithm.

An EnergyModel holds the nodes, the neighbor graph and the unary and pairwise cost functions that define the energy to be minimized. Costs can be set as dense arrays (good for image grids) or as callback functions (good for general graphs). If both are set, the array is used.

Template Parameters

T	Numeric type for costs (`int32_t`, `float`, or `double`).

Member Typedef Documentation

◆ PairwiseCostFn

template<typename T >

using EnergyModel< T >::PairwiseCostFn = std::function<T(int node1, int node2, int label1, int label2)>

Callable that returns the pairwise cost for assigning label1 to node1 and label2 to node2.

◆ UnaryCostFn

template<typename T >

using EnergyModel< T >::UnaryCostFn = std::function<T(int node, int label)>

Callable that returns the unary cost for assigning label to node.

Constructor & Destructor Documentation

◆ EnergyModel()

template<typename T >

EnergyModel< T >::EnergyModel	(	int	num_nodes,
		int	num_labels
	)

inline

Constructs an energy model with all labels initialized to 0.

Parameters

num_nodes	Number of nodes (pixels, graph vertices, etc.).
num_labels	Number of labels (classes, segments, communities, etc.).

Member Function Documentation

◆ add_grid_edges()

template<typename T >

void EnergyModel< T >::add_grid_edges	(	int	width,
		int	height
	)

inline

Populates a 4-connected grid neighbourhood for an image of size width × height.

Exceptions

std::invalid_argument if width * height != num_nodes().

◆ add_neighbor()

template<typename T >

void EnergyModel< T >::add_neighbor	(	int	node1,
		int	node2
	)

inline

Adds an undirected edge between node1 and node2.

◆ evaluate_total_energy() [1/2]

template<typename T >

T EnergyModel< T >::evaluate_total_energy ( ) const

inline

Evaluates the total energy for the model's current label assignment.

◆ evaluate_total_energy() [2/2]

template<typename T >

T EnergyModel< T >::evaluate_total_energy ( const std::vector< int > & eval_labels ) const

inline

Evaluates the total energy for a given label assignment.

Parameters

eval_labels Label vector of length num_nodes().

◆ get_active_nodes()

template<typename T >

std::vector< int > EnergyModel< T >::get_active_nodes ( int alpha_label ) const

inline

Returns the indices of all nodes that do not currently have alpha_label.

These are the nodes that take part in an alpha-expansion move for alpha_label.

◆ get_label()

template<typename T >

int EnergyModel< T >::get_label ( int node ) const

inline

Returns the current label assigned to node.

◆ get_labels()

template<typename T >

const std::vector< int > & EnergyModel< T >::get_labels ( ) const

inline

Returns the full label vector (one entry per node).

◆ get_neighbors()

template<typename T >

const std::vector< int > & EnergyModel< T >::get_neighbors ( int node ) const

inline

Returns the neighbours of node.

◆ get_pairwise_cost()

template<typename T >

T EnergyModel< T >::get_pairwise_cost	(	int	node1,
		int	node2,
		int	label1,
		int	label2
	)		const

inline

Returns the pairwise cost for the given node–label pair.

Priority: per-edge weights > dense pairwise array > callback.

◆ get_unary_cost()

template<typename T >

T EnergyModel< T >::get_unary_cost	(	int	node,
		int	label
	)		const

inline

Returns the unary cost for assigning label to node.

Checks the dense array first. If no array is set, it uses the callback function.

◆ num_labels()

template<typename T >

int EnergyModel< T >::num_labels ( ) const

inline

Returns the total number of labels.

◆ num_nodes()

template<typename T >

int EnergyModel< T >::num_nodes ( ) const

inline

Returns the total number of nodes.

◆ set_edge_weights()

template<typename T >

void EnergyModel< T >::set_edge_weights	(	const std::vector< int > &	n1s,
		const std::vector< int > &	n2s,
		const std::vector< T > &	weights
	)

inline

Sets per-edge smoothness weights (Potts model).

For each edge (n1, n2), the pairwise cost is 0 if the two nodes have the same label, and weight if they have different labels. This overrides both the dense pairwise array and the callback for the specified edges.

Exceptions

std::invalid_argument if the three vectors have different sizes.

◆ set_label()

template<typename T >

void EnergyModel< T >::set_label	(	int	node,
		int	label
	)

inline

Assigns label to node.

◆ set_labels()

template<typename T >

void EnergyModel< T >::set_labels ( const std::vector< int > & labels )

inline

Replaces the full label vector.

Parameters

labels Must have size equal to num_nodes().

◆ set_pairwise_cost_fn()

template<typename T >

void EnergyModel< T >::set_pairwise_cost_fn ( PairwiseCostFn fn )

inline

Sets a callback function for pairwise costs.

If set_pairwise_costs() or set_edge_weights() is also called, those take priority.

◆ set_pairwise_costs()

template<typename T >

void EnergyModel< T >::set_pairwise_costs ( const std::vector< T > & costs )

inline

Sets a global pairwise cost matrix of size num_labels * num_labels.

Entry [l1 * num_labels + l2] is the cost of placing label l1 and l2 on adjacent nodes. This overrides any callback, but per-edge weights set via set_edge_weights() take priority over this matrix.

Exceptions

std::invalid_argument if the array size does not match.

◆ set_unary_cost_fn()

template<typename T >

void EnergyModel< T >::set_unary_cost_fn ( UnaryCostFn fn )

inline

Sets a callback function for unary costs.

If set_unary_costs() is also called, the dense array takes priority over this callback.

◆ set_unary_costs()

template<typename T >

void EnergyModel< T >::set_unary_costs ( const std::vector< T > & costs )

inline

Sets unary costs from a flat row-major array of size num_nodes * num_labels.

Entry [node * num_labels + label] is the cost of assigning label to node. This overrides any callback set via set_unary_cost_fn().

Exceptions

std::invalid_argument if the array size does not match.

The documentation for this class was generated from the following file:

src/core/EnergyModel.hpp

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ PairwiseCostFn

◆ UnaryCostFn

Constructor & Destructor Documentation

◆ EnergyModel()

Member Function Documentation

◆ add_grid_edges()

◆ add_neighbor()

◆ evaluate_total_energy() [1/2]

◆ evaluate_total_energy() [2/2]

◆ get_active_nodes()

◆ get_label()

◆ get_labels()

◆ get_neighbors()

◆ get_pairwise_cost()

◆ get_unary_cost()

◆ num_labels()

◆ num_nodes()

◆ set_edge_weights()

◆ set_label()

◆ set_labels()

◆ set_pairwise_cost_fn()

◆ set_pairwise_costs()

◆ set_unary_cost_fn()

◆ set_unary_costs()