Panoptica¶

Submodules¶

panoptica.instance_approximator module¶

class panoptica.instance_approximator.ConnectedComponentsInstanceApproximator(cca_backend: CCABackend | None = None)¶

Bases: InstanceApproximator

Instance approximator using connected components algorithm for panoptic segmentation evaluation.

cca_backend¶

The connected components algorithm backend.

Type:: CCABackend

__init__(self, cca_backend: CCABackend) -> None: Initialize the ConnectedComponentsInstanceApproximator.

_approximate_instances(self, semantic_pair: SemanticPair, **kwargs) -> UnmatchedInstancePair: Approximate instances using the connected components algorithm.

Example: >>> cca_approximator = ConnectedComponentsInstanceApproximator(cca_backend=CCABackend.cc3d) >>> semantic_pair = SemanticPair(…) >>> result = cca_approximator.approximate_instances(semantic_pair)

_abc_impl = <_abc._abc_data object>¶

_approximate_instances(semantic_pair: SemanticPair, **kwargs) → UnmatchedInstancePair¶

Approximate instances using the connected components algorithm.

Parameters:

semantic_pair (SemanticPair) – The semantic pair to be approximated.
**kwargs – Additional keyword arguments.

Returns:

The result of the instance approximation.

Return type:

UnmatchedInstancePair

classmethod _yaml_repr(node) → dict¶

Abstract method for representing the class in YAML.

Parameters:: node – The object instance to represent in YAML.
Returns:: A dictionary representation of the class.
Return type:: dict

class panoptica.instance_approximator.InstanceApproximator¶

Bases: SupportsConfig

Abstract base class for instance approximation algorithms in panoptic segmentation evaluation.

None¶

_approximate_instances(self, semantic_pair: SemanticPair, **kwargs) -> UnmatchedInstancePair | MatchedInstancePair: Abstract method to be implemented by subclasses for instance approximation.

approximate_instances(self, semantic_pair: SemanticPair, **kwargs) -> UnmatchedInstancePair | MatchedInstancePair: Perform instance approximation on the given SemanticPair.

Raises:: ValueError – If there are negative values in the semantic maps, which is not allowed.

Example: >>> class CustomInstanceApproximator(InstanceApproximator): … def _approximate_instances(self, semantic_pair: SemanticPair, **kwargs) -> UnmatchedInstancePair | MatchedInstancePair: … # Implementation of instance approximation algorithm … pass … >>> approximator = CustomInstanceApproximator() >>> semantic_pair = SemanticPair(…) >>> result = approximator.approximate_instances(semantic_pair)

_abc_impl = <_abc._abc_data object>¶

abstract _approximate_instances(semantic_pair: SemanticPair, label_group: LabelGroup | None = None, **kwargs) → UnmatchedInstancePair | MatchedInstancePair¶

Abstract method to be implemented by subclasses for instance approximation.

Parameters:

semantic_pair (SemanticPair) – The semantic pair to be approximated.
label_group (LabelGroup | None, optional) – Information about the label group being processed. Defaults to None.
**kwargs – Additional keyword arguments.

Returns:

The result of the instance approximation.

Return type:

UnmatchedInstancePair | MatchedInstancePair

_yaml_repr(node) → dict¶

Abstract method for representing the class in YAML.

Parameters:: node – The object instance to represent in YAML.
Returns:: A dictionary representation of the class.
Return type:: dict

approximate_instances(semantic_pair: SemanticPair, verbose: bool = False, label_group: LabelGroup | None = None, **kwargs) → UnmatchedInstancePair | MatchedInstancePair¶

Perform instance approximation on the given SemanticPair.

Parameters:

semantic_pair (SemanticPair) – The semantic pair to be approximated.
label_group (LabelGroup | None, optional) – Information about the label group being processed. Defaults to None.
**kwargs – Additional keyword arguments.

Returns:

The result of the instance approximation.

Return type:

UnmatchedInstancePair | MatchedInstancePair

Raises:

ValueError – If there are negative values in the semantic maps, which is not allowed.

class panoptica.instance_approximator.OneHotConnectedComponentsInstanceApproximator(cca_backend: CCABackend | None = None)¶

Bases: InstanceApproximator

Instance approximator that first applies one-hot encoding to the prediction and reference arrays, then runs connected components on each channel and merges the results.

_abc_impl = <_abc._abc_data object>¶

_approximate_instances(semantic_pair: SemanticPair, label_group: LabelGroup | None = None) → UnmatchedInstancePair¶

Abstract method to be implemented by subclasses for instance approximation.

Parameters:

semantic_pair (SemanticPair) – The semantic pair to be approximated.
label_group (LabelGroup | None, optional) – Information about the label group being processed. Defaults to None.
**kwargs – Additional keyword arguments.

Returns:

The result of the instance approximation.

Return type:

UnmatchedInstancePair | MatchedInstancePair

_one_hot(arr)¶

classmethod _yaml_repr(node) → dict¶

Abstract method for representing the class in YAML.

Parameters:: node – The object instance to represent in YAML.
Returns:: A dictionary representation of the class.
Return type:: dict

panoptica.instance_evaluator module¶

panoptica.instance_matcher module¶

class panoptica.instance_matcher.InstanceMatchingAlgorithm¶

Bases: SupportsConfig

Abstract base class for instance matching algorithms in panoptic segmentation evaluation.

_match_instances(self, unmatched_instance_pair: UnmatchedInstancePair, context: MatchingContext = None, **kwargs) -> InstanceLabelMap: Abstract method to be implemented by subclasses for instance matching.

match_instances(self, unmatched_instance_pair: UnmatchedInstancePair, **kwargs) -> MatchedInstancePair: Perform instance matching on the given UnmatchedInstancePair.

Example: >>> class CustomInstanceMatcher(InstanceMatchingAlgorithm): … def _match_instances(self, unmatched_instance_pair: UnmatchedInstancePair, context: MatchingContext = None, **kwargs) -> InstanceLabelMap: … # Implementation of instance matching algorithm … pass … >>> matcher = CustomInstanceMatcher() >>> unmatched_instance_pair = UnmatchedInstancePair(…) >>> result = matcher.match_instances(unmatched_instance_pair)

_abc_impl = <_abc._abc_data object>¶

_calculate_matching_metric_pairs(unmatched_instance_pair: UnmatchedInstancePair, context: MatchingContext | None, matching_metric: Metric) → List[Tuple[float, Tuple[int, int]]]¶

Calculate matching metric pairs based on context.

Parameters:

unmatched_instance_pair – The unmatched instance pair.
context – The matching context. If None, defaults to non-part group behavior.
matching_metric – The metric to use for matching.

Returns:

List of (matching_score, (ref_label, pred_label)) tuples.

abstract _match_instances(unmatched_instance_pair: UnmatchedInstancePair, context: MatchingContext | None = None, **kwargs) → InstanceLabelMap¶

Abstract method to be implemented by subclasses for instance matching.

Parameters:

unmatched_instance_pair (UnmatchedInstancePair) – The unmatched instance pair to be matched.
context (Optional[MatchingContext]) – Context information for matching. If None, a default context will be created.
**kwargs – Additional keyword arguments.

Returns:

The result of the instance matching.

Return type:

InstanceLabelMap

_yaml_repr(node) → dict¶

Abstract method for representing the class in YAML.

Parameters:: node – The object instance to represent in YAML.
Returns:: A dictionary representation of the class.
Return type:: dict

match_instances(unmatched_instance_pair: UnmatchedInstancePair, label_group=None, n_ref_labels=None, processing_pair_orig_shape=None, **kwargs) → MatchedInstancePair¶

Perform instance matching on the given UnmatchedInstancePair.

Parameters:

unmatched_instance_pair (UnmatchedInstancePair) – The unmatched instance pair to be matched.
label_group – The label group object for this group.
n_ref_labels – Number of reference labels.
processing_pair_orig_shape – Original shape of the processing pair.
**kwargs – Additional keyword arguments.

Returns:

The result of the instance matching.

Return type:

MatchedInstancePair

class panoptica.instance_matcher.MatchingContext(label_group: LabelGroup | None = None, n_ref_labels: int | None = None, processing_pair_orig_shape: Tuple | None = None)¶

Bases: object

Encapsulates context information needed for matching operations.

property is_part_group: bool¶: Check if this context represents a part group.

label_group: LabelGroup | None = None¶

n_ref_labels: int | None = None¶

processing_pair_orig_shape: Tuple | None = None¶

class panoptica.instance_matcher.MaxBipartiteMatching(matching_metric: Metric = Metric.IOU, matching_threshold: float = 0.5)¶

Bases: ThresholdBasedMatching

Instance matching algorithm that performs optimal one-to-one matching based on maximum bipartite graph matching.

This implementation maximizes the global matching score between predictions and references.

_abc_impl = <_abc._abc_data object>¶

_create_cost_matrix(ref_labels: List[int], pred_labels: List[int], mm_pairs: List[Tuple[float, Tuple[int, int]]], matching_threshold: float) → ndarray¶: Create cost matrix for bipartite matching.

_match_instances(unmatched_instance_pair: UnmatchedInstancePair, context: MatchingContext | None = None, *, matching_threshold: float, **kwargs) → InstanceLabelMap¶

Perform optimal instance matching based on maximum bipartite graph matching.

Parameters:

unmatched_instance_pair (UnmatchedInstancePair) – The unmatched instance pair to be matched.
context (Optional[MatchingContext]) – The matching context.
matching_threshold (float) – The threshold for matching instances.
**kwargs – Additional keyword arguments.

Returns:

The result of the instance matching.

Return type:

InstanceLabelMap

_solve_bipartite_matching(cost_matrix: ndarray, ref_labels: List[int], pred_labels: List[int]) → InstanceLabelMap¶: Solve the bipartite matching problem and return labelmap.

classmethod _yaml_repr(node) → dict¶

Abstract method for representing the class in YAML.

Parameters:: node – The object instance to represent in YAML.
Returns:: A dictionary representation of the class.
Return type:: dict

class panoptica.instance_matcher.MaximizeMergeMatching(matching_metric: Metric = Metric.IOU, matching_threshold: float = 0.5)¶

Bases: ThresholdBasedMatching

Instance matching algorithm that performs many-to-one matching based on metric. Will merge if combined instance metric is greater than individual one. Only matches if at least a single instance exceeds the threshold.

matching_metric¶

The metric to be used for matching.

Type:: Metric

matching_threshold¶

The threshold for matching instances.

Type:: float

_abc_impl = <_abc._abc_data object>¶

_match_instances(unmatched_instance_pair: UnmatchedInstancePair, context: MatchingContext | None = None, *, matching_threshold: float, **kwargs) → InstanceLabelMap¶

Perform many-to-one instance matching based on metric values.

Parameters:

unmatched_instance_pair (UnmatchedInstancePair) – The unmatched instance pair to be matched.
context (Optional[MatchingContext]) – The matching context.
matching_threshold (float) – The threshold for matching instances.
**kwargs – Additional keyword arguments.

Returns:

The result of the instance matching.

Return type:

InstanceLabelMap

classmethod _yaml_repr(node) → dict¶

Abstract method for representing the class in YAML.

Parameters:: node – The object instance to represent in YAML.
Returns:: A dictionary representation of the class.
Return type:: dict

new_combination_score(pred_labels: list[int], new_pred_label: int, ref_label: int, unmatched_instance_pair: UnmatchedInstancePair)¶

class panoptica.instance_matcher.NaiveThresholdMatching(matching_metric: Metric = Metric.IOU, matching_threshold: float = 0.5, allow_many_to_one: bool = False)¶

Bases: ThresholdBasedMatching

Instance matching algorithm that performs threshold-based matching.

matching_metric¶

The metric used for matching.

Type:: Metric

matching_threshold¶

The threshold for matching instances.

Type:: float

allow_many_to_one¶

Whether to allow many-to-one matching.

Type:: bool

_abc_impl = <_abc._abc_data object>¶

_match_instances(unmatched_instance_pair: UnmatchedInstancePair, context: MatchingContext | None = None, *, matching_threshold: float, **kwargs) → InstanceLabelMap¶

Perform threshold-based instance matching.

Parameters:

unmatched_instance_pair (UnmatchedInstancePair) – The unmatched instance pair to be matched.
context (Optional[MatchingContext]) – The matching context.
matching_threshold (float) – The threshold for matching instances.
**kwargs – Additional keyword arguments.

Returns:

The result of the instance matching.

Return type:

InstanceLabelMap

classmethod _yaml_repr(node) → dict¶

Abstract method for representing the class in YAML.

Parameters:: node – The object instance to represent in YAML.
Returns:: A dictionary representation of the class.
Return type:: dict

class panoptica.instance_matcher.ThresholdBasedMatching(matching_metric: Metric = Metric.IOU, matching_threshold: float = 0.5)¶

Bases: InstanceMatchingAlgorithm

Base class for matchers that rely on a metric and a cutoff threshold.

_abc_impl = <_abc._abc_data object>¶

abstract _match_instances(unmatched_instance_pair: UnmatchedInstancePair, context: MatchingContext | None = None, *, matching_threshold: float, **kwargs) → InstanceLabelMap¶

Abstract method to be implemented by subclasses for instance matching.

Parameters:

unmatched_instance_pair (UnmatchedInstancePair) – The unmatched instance pair to be matched.
context (Optional[MatchingContext]) – Context information for matching. If None, a default context will be created.
matching_threshold (float) – The threshold to use for matching instances in this operation.
**kwargs – Additional keyword arguments.

Returns:

The result of the instance matching.

Return type:

InstanceLabelMap

classmethod _yaml_repr(node) → dict¶

Abstract method for representing the class in YAML.

Parameters:: node – The object instance to represent in YAML.
Returns:: A dictionary representation of the class.
Return type:: dict

match_instances(unmatched_instance_pair: UnmatchedInstancePair, label_group=None, n_ref_labels=None, processing_pair_orig_shape=None, *, matching_threshold: float | None = None, **kwargs) → MatchedInstancePair¶

Perform instance matching on the given UnmatchedInstancePair.

Parameters:

unmatched_instance_pair (UnmatchedInstancePair) – The unmatched instance pair to be matched.
label_group – The label group object for this group.
n_ref_labels – Number of reference labels.
processing_pair_orig_shape – Original shape of the processing pair.
**kwargs – Additional keyword arguments.

Returns:

The result of the instance matching.

Return type:

MatchedInstancePair

panoptica.instance_matcher.map_instance_labels(processing_pair: UnmatchedInstancePair, labelmap: InstanceLabelMap) → MatchedInstancePair¶

Map instance labels based on the provided labelmap and create a MatchedInstancePair.

Parameters:

processing_pair (UnmatchedInstancePair) – The unmatched instance pair containing original labels.
labelmap (InstanceLabelMap) – The instance label map obtained from instance matching.

Returns:

The result of mapping instance labels.

Return type:

MatchedInstancePair

Panoptica¶

Submodules¶

panoptica.instance_approximator module¶

panoptica.instance_evaluator module¶

panoptica.instance_matcher module¶

panoptica.panoptica_aggregator module¶

panoptica.panoptica_evaluator module¶

panoptica.panoptica_result module¶

panoptica.panoptica_statistics module¶