panoptica

panoptica.evaluator

panoptica.instance_approximator

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

class panoptica.instance_approximator.InstanceApproximator

Bases: ABC

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:

AssertionError – 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, **kwargs) → UnmatchedInstancePair | MatchedInstancePair

Abstract method to be implemented by subclasses for instance approximation.

Parameters:

  • semantic_pair (SemanticPair) – The semantic pair to be approximated.

  • **kwargs – Additional keyword arguments.

Returns:

The result of the instance approximation.

Return type:

UnmatchedInstancePair | MatchedInstancePair

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

Perform instance approximation on the given SemanticPair.

Parameters:

  • semantic_pair (SemanticPair) – The semantic pair to be approximated.

  • **kwargs – Additional keyword arguments.

Returns:

The result of the instance approximation.

Return type:

UnmatchedInstancePair | MatchedInstancePair

Raises:

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

panoptica.instance_matcher

class panoptica.instance_matcher.DesperateMarriageMatching

Bases: InstanceMatchingAlgorithm

_abc_impl = <_abc._abc_data object>
class panoptica.instance_matcher.InstanceMatchingAlgorithm

Bases: ABC

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

None
_match_instances(self, unmatched_instance_pair

UnmatchedInstancePair, **kwargs) -> Instance_Label_Map: 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, **kwargs) -> Instance_Label_Map: … # 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>
abstract _match_instances(unmatched_instance_pair: UnmatchedInstancePair, **kwargs) → InstanceLabelMap

Abstract method to be implemented by subclasses for instance matching.

Parameters:

  • unmatched_instance_pair (UnmatchedInstancePair) – The unmatched instance pair to be matched.

  • **kwargs – Additional keyword arguments.

Returns:

The result of the instance matching.

Return type:

Instance_Label_Map

match_instances(unmatched_instance_pair: UnmatchedInstancePair, **kwargs) → MatchedInstancePair

Perform instance matching on the given UnmatchedInstancePair.

Parameters:

  • unmatched_instance_pair (UnmatchedInstancePair) – The unmatched instance pair to be matched.

  • **kwargs – Additional keyword arguments.

Returns:

The result of the instance matching.

Return type:

MatchedInstancePair

class panoptica.instance_matcher.MatchUntilConvergenceMatching

Bases: InstanceMatchingAlgorithm

_abc_impl = <_abc._abc_data object>
class panoptica.instance_matcher.MaximizeMergeMatching(matching_metric: Metric = Metric.IOU, matching_threshold: float = 0.5)

Bases: InstanceMatchingAlgorithm

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

_match_instances(self, unmatched_instance_pair

UnmatchedInstancePair, **kwargs) -> Instance_Label_Map:

Raises:

AssertionError – If the specified IoU threshold is not within the valid range.

_abc_impl = <_abc._abc_data object>
_match_instances(unmatched_instance_pair: UnmatchedInstancePair, **kwargs) → InstanceLabelMap

Perform one-to-one instance matching based on IoU values.

Parameters:

  • unmatched_instance_pair (UnmatchedInstancePair) – The unmatched instance pair to be matched.

  • **kwargs – Additional keyword arguments.

Returns:

The result of the instance matching.

Return type:

Instance_Label_Map

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: InstanceMatchingAlgorithm

Instance matching algorithm that performs one-to-one matching based on IoU values.

iou_threshold

The IoU threshold for matching instances.

Type:

float

__init__(self, iou_threshold

float = 0.5) -> None: Initialize the NaiveOneToOneMatching instance.

_match_instances(self, unmatched_instance_pair

UnmatchedInstancePair, **kwargs) -> Instance_Label_Map: Perform one-to-one instance matching based on IoU values.

Raises:

AssertionError – If the specified IoU threshold is not within the valid range.

Example: >>> matcher = NaiveOneToOneMatching(iou_threshold=0.6) >>> unmatched_instance_pair = UnmatchedInstancePair(…) >>> result = matcher.match_instances(unmatched_instance_pair)

_abc_impl = <_abc._abc_data object>
_match_instances(unmatched_instance_pair: UnmatchedInstancePair, **kwargs) → InstanceLabelMap

Perform one-to-one instance matching based on IoU values.

Parameters:

  • unmatched_instance_pair (UnmatchedInstancePair) – The unmatched instance pair to be matched.

  • **kwargs – Additional keyword arguments.

Returns:

The result of the instance matching.

Return type:

Instance_Label_Map

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 (Instance_Label_Map) – The instance label map obtained from instance matching.

Returns:

The result of mapping instance labels.

Return type:

MatchedInstancePair

Example: >>> unmatched_instance_pair = UnmatchedInstancePair(…) >>> labelmap = [([1, 2], [3, 4]), ([5], [6])] >>> result = map_instance_labels(unmatched_instance_pair, labelmap)

panoptica.instance_evaluator

panoptica.instance_evaluator._evaluate_instance(reference_arr: ndarray, prediction_arr: ndarray, ref_idx: int, eval_metrics: list[Metric]) → dict[Metric, float]

Evaluate a single instance.

Parameters:

  • ref_labels (np.ndarray) – Reference instance segmentation mask.

  • pred_labels (np.ndarray) – Predicted instance segmentation mask.

  • ref_idx (int) – The label of the current instance.

  • iou_threshold (float) – The IoU threshold for considering a match.

Returns:

Tuple containing True Positives (int), Dice coefficient (float), and IoU (float).

Return type:

Tuple[int, float, float]

panoptica.instance_evaluator.evaluate_matched_instance(matched_instance_pair: MatchedInstancePair, eval_metrics: list[Metric] = [Metric.DSC, Metric.IOU, Metric.ASSD], decision_metric: Metric | None = Metric.IOU, decision_threshold: float | None = None, edge_case_handler: EdgeCaseHandler | None = None, **kwargs) → PanopticaResult

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

Parameters:

  • processing_pair (UnmatchedInstancePair) – The unmatched instance pair containing original labels.

  • labelmap (Instance_Label_Map) – The instance label map obtained from instance matching.

Returns:

The result of mapping instance labels.

Return type:

MatchedInstancePair

Example: >>> unmatched_instance_pair = UnmatchedInstancePair(…) >>> labelmap = [([1, 2], [3, 4]), ([5], [6])] >>> result = map_instance_labels(unmatched_instance_pair, labelmap)

panoptica.result