easy_vision.python.core.matchers

easy_vision.python.core.matchers.argmax_matcher

Argmax matcher implementation.

This class takes a similarity matrix and matches columns to rows based on the maximum value per column. One can specify matched_thresholds and to prevent columns from matching to rows (generally resulting in a negative training example) and unmatched_theshold to ignore the match (generally resulting in neither a positive or negative training example).

This matcher is used in Fast(er)-RCNN.

Note: matchers are used in TargetAssigners. There is a create_target_assigner factory function for popular implementations.

class easy_vision.python.core.matchers.argmax_matcher.ArgMaxMatcher(matched_threshold, unmatched_threshold=None, negatives_lower_than_unmatched=True, force_match_for_each_row=False, use_matmul_gather=False)

Bases: easy_vision.python.core.matchers.matcher.Matcher

Matcher based on highest value.

This class computes matches from a similarity matrix. Each column is matched to a single row.

To support object detection target assignment this class enables setting both matched_threshold (upper threshold) and unmatched_threshold (lower thresholds) defining three categories of similarity which define whether examples are positive, negative, or ignored: (1) similarity >= matched_threshold: Highest similarity. Matched/Positive! (2) matched_threshold > similarity >= unmatched_threshold: Medium similarity.

Depending on negatives_lower_than_unmatched, this is either Unmatched/Negative OR Ignore.

3. unmatched_threshold > similarity: Lowest similarity. Depending on flag

   negatives_lower_than_unmatched, either Unmatched/Negative OR Ignore.

For ignored matches this class sets the values in the Match object to -2.

__init__(matched_threshold, unmatched_threshold=None, negatives_lower_than_unmatched=True, force_match_for_each_row=False, use_matmul_gather=False)

Construct ArgMaxMatcher.

Parameters:

• matched_threshold – Threshold for positive matches. Positive if sim >= matched_threshold, where sim is the maximum value of the similarity matrix for a given column. Set to None for no threshold.
• unmatched_threshold – Threshold for negative matches. Negative if sim < unmatched_threshold. Defaults to matched_threshold when set to None.
• negatives_lower_than_unmatched – Boolean which defaults to True. If True then negative matches are the ones below the unmatched_threshold, whereas ignored matches are in between the matched and umatched threshold. If False, then negative matches are in between the matched and unmatched threshold, and everything lower than unmatched is ignored.
• force_match_for_each_row – If True, ensures that each row is matched to at least one column (which is not guaranteed otherwise if the matched_threshold is high). Defaults to False. See argmax_matcher_test.testMatcherForceMatch() for an example.
• use_matmul_gather – Force constructed match objects to use matrix multiplication based gather instead of standard tf.gather. (Default: False).

Raises:

ValueError – if unmatched_threshold is set but matched_threshold is not set or if unmatched_threshold > matched_threshold.

class easy_vision.python.core.matchers.argmax_matcher.YOLOArgMaxMatcher(matched_threshold, num_anchors_per_location, feature_map_index, use_matmul_gather=False)

Bases: easy_vision.python.core.matchers.argmax_matcher.ArgMaxMatcher

YOLO Matcher based on highest value.

This class computes matches from a similarity matrix. Each column is matched to a single row. Target with similarity >= matched_threshold or with highest similarity is matched/positive.

For YOLO, columns will have anchors on all feature_maps, we will gather the columns/anchors on the specified feature_map_index in the end

__init__(matched_threshold, num_anchors_per_location, feature_map_index, use_matmul_gather=False)

Construct ArgMaxMatcher.

Parameters:

• matched_threshold – Threshold for positive matches. Positive if sim >= matched_threshold, where sim is the maximum value of the similarity matrix for a given column. Set to None for no threshold.
• use_matmul_gather – Force constructed match objects to use matrix multiplication based gather instead of standard tf.gather. (Default: False).

Raises:

ValueError – if unmatched_threshold is set but matched_threshold is not set or if unmatched_threshold > matched_threshold.

easy_vision.python.core.matchers.bipartite_matcher

Bipartite matcher implementation.

class easy_vision.python.core.matchers.bipartite_matcher.GreedyBipartiteMatcher(use_matmul_gather=False)

Bases: easy_vision.python.core.matchers.matcher.Matcher

Wraps a Tensorflow greedy bipartite matcher.

__init__(use_matmul_gather=False)

Constructs a Matcher.

Parameters:use_matmul_gather – Force constructed match objects to use matrix multiplication based gather instead of standard tf.gather. (Default: False).

easy_vision.python.core.matchers.matcher

Matcher interface and Match class.

This module defines the Matcher interface and the Match object. The job of the matcher is to match row and column indices based on the similarity matrix and other optional parameters. Each column is matched to at most one row. There are three possibilities for the matching:

1. match: A column matches a row.
2. no_match: A column does not match any row.
3. ignore: A column that is neither ‘match’ nor no_match.

The ignore case is regularly encountered in object detection: when an anchor has a relatively small overlap with a ground-truth box, one neither wants to consider this box a positive example (match) nor a negative example (no match).

The Match class is used to store the match results and it provides simple apis to query the results.

class easy_vision.python.core.matchers.matcher.Match(match_results, use_matmul_gather=False)

Bases: object

Class to store results from the matcher.

This class is used to store the results from the matcher. It provides convenient methods to query the matching results.

__init__(match_results, use_matmul_gather=False)

Constructs a Match object.

Parameters:

• match_results – Integer tensor of shape [N] with (1) match_results[i]>=0, meaning that column i is matched with row match_results[i]. (2) match_results[i]=-1, meaning that column i is not matched. (3) match_results[i]=-2, meaning that column i is ignored.
• use_matmul_gather – Use matrix multiplication based gather instead of standard tf.gather. (Default: False).

Raises:

ValueError – if match_results does not have rank 1 or is not an integer int32 scalar tensor

gather_based_on_match(input_tensor, unmatched_value, ignored_value)

Gathers elements from input_tensor based on match results.

For columns that are matched to a row, gathered_tensor[col] is set to input_tensor[match_results[col]]. For columns that are unmatched, gathered_tensor[col] is set to unmatched_value. Finally, for columns that are ignored gathered_tensor[col] is set to ignored_value.

Note that the input_tensor.shape[1:] must match with unmatched_value.shape and ignored_value.shape

Parameters:

• input_tensor – Tensor to gather values from.
• unmatched_value – Constant tensor value for unmatched columns.
• ignored_value – Constant tensor value for ignored columns.

Returns:

A tensor containing values gathered from easy_vision.python.input_tensor.

The shape of the gathered tensor is [match_results.shape[0]] + input_tensor.shape[1:].

Return type:

gathered_tensor

ignored_column_indicator()

Returns boolean column indicator where True means the colum is ignored.

Returns:boolean vector which is True for all ignored column indices. Return type:column_indicator

ignored_column_indices()

Returns column indices that are ignored (neither Matched nor Unmatched).

The indices returned by this op are always sorted in increasing order.

Returns:int32 tensor of shape [K] with column indices. Return type:column_indices

match_results

The accessor for match results.

Returns:the tensor which encodes the match results.

matched_column_indicator()

Returns column indices that are matched.

Returns:int32 tensor of shape [K] with column indices. Return type:column_indices

matched_column_indices()

Returns column indices that match to some row.

The indices returned by this op are always sorted in increasing order.

Returns:int32 tensor of shape [K] with column indices. Return type:column_indices

matched_row_indices()

Returns row indices that match some column.

The indices returned by this op are ordered so as to be in correspondence with the output of matched_column_indicator(). For example if self.matched_column_indicator() is [0,2], and self.matched_row_indices() is [7, 3], then we know that column 0 was matched to row 7 and column 2 was matched to row 3.

Returns:int32 tensor of shape [K] with row indices. Return type:row_indices

num_ignored_columns()

Returns number (int32 scalar tensor) of matched columns.

num_matched_columns()

Returns number (int32 scalar tensor) of matched columns.

num_unmatched_columns()

Returns number (int32 scalar tensor) of unmatched columns.

unmatched_column_indicator()

Returns column indices that are unmatched.

Returns:int32 tensor of shape [K] with column indices. Return type:column_indices

unmatched_column_indices()

Returns column indices that do not match any row.

The indices returned by this op are always sorted in increasing order.

Returns:int32 tensor of shape [K] with column indices. Return type:column_indices

unmatched_or_ignored_column_indices()

Returns column indices that are unmatched or ignored.

The indices returned by this op are always sorted in increasing order.

Returns:int32 tensor of shape [K] with column indices. Return type:column_indices

class easy_vision.python.core.matchers.matcher.Matcher(use_matmul_gather=False)

Bases: object

Abstract base class for matcher.

__init__(use_matmul_gather=False)

Constructs a Matcher.

Parameters:use_matmul_gather – Force constructed match objects to use matrix multiplication based gather instead of standard tf.gather. (Default: False).

match(similarity_matrix, valid_rows=None, scope=None)

Computes matches among row and column indices and returns the result.

Computes matches among the row and column indices based on the similarity matrix and optional arguments.

Parameters:

• similarity_matrix – Float tensor of shape [N, M] with pairwise similarity where higher value means more similar.
• valid_rows – A boolean tensor of shape [N] indicating the rows that are valid for matching.
• scope – Op scope name. Defaults to ‘Match’ if None.

Returns:

A Match object with the results of matching.