Blob#

Warning

The code reference is a work in progress and may contain inconsistencies.

class idtrackerai.Blob(contour: ndarray, frame_number: int = -1, bbox_img_id: str = '', pixels_are_from_eroded_blob: bool = False)[source]#

Represents one or more segmented animals, defined by a contour, in a specific frame.

contour: ndarray#

The coordinates of the contour defining self with shape [n_points, 2]

episode: int#

Index of the Episode the blob belongs to

id_image_index: int#

Index of the identification image position in the HDF5 file

seems_like_individual: bool#

True if the blob’s frame has exactly n_animals blobs or if its area is not much bigger than the typical individual area

used_for_training_crossings: bool = False#

Flag indicating if the blob has been used to train the crossing CNN

was_a_crossing: bool = False#

Flag indicating whether the blob was created after splitting a crossing blob during the crossings interpolation process

identity: int | None = None#

Identity of the blob assigned during the identification process

fragment_identifier: int = -1#

Indicates the index of the Fragment that contains the blob, -1 means no associated Fragment

user_generated_identities: list[int | None] = None#

List of identities of the blob, some of which might have been given by the user during the validation process

user_generated_centroids: list[tuple[float, float] | None] = None#

List of centroids generated by the user during the validation process

identity_corrected_solving_jumps: int | None = None#

Identity of the blob after correcting impossible velocity jumps

identities_corrected_closing_gaps: list | None = None#

Identity of the blob after crossings interpolation

exclusive_roi: int = -1#

Exclusive ROI where the blob belongs to

identity_certainty: float = nan#

Confidence of the identity assigned to the blob

__init__(contour: ndarray, frame_number: int = -1, bbox_img_id: str = '', pixels_are_from_eroded_blob: bool = False) → None[source]#
frame_number: int#

The index of the frame where self belongs to

bbox_img_id: str#

Name of the dataset containing the blob’s bounding box image in the episode’s bounding box images HDF5 file

is_an_individual: bool#

Flag indicating self represents a single animal.

forced_crossing: bool = False#

Indicates if the crossing attribute has been forced by set_individual_with_identity_0_as_crossings()

next: tuple[Blob, ...]#

The Blob s from the next frame that overlap with self

previous: tuple[Blob, ...]#

The Blob s from the previous frame that overlap with self

property convexHull: ndarray[source]#

Convex hull of the contour computed with cv2.convexHull()

property area: float[source]#

Area of the contour computed with cv2.contourArea()

property bbox_corners: BoundingBoxCoordinates[source]#

A NamedTuple of the bottom, left, top and right values of the bounding box

property extension: float#

Extension measured as the length of the diagonal of the bounding box

property centroid: tuple[float, float][source]#

Center of mass (x, y) of the contour, or the mean of its points if the contour has zero area

property orientation: float#

Angle in radians of the contour’s main axis, computed from its second order central moments

__getstate__() → dict[str, Any][source]#

Helper for pickle.

property is_a_crossing: bool#

Flag indicating whether the blob represents two or more animals together. It is the negative of is_an_individual.

property has_multiple_previous: bool[source]#

Flag indicating if the blob has a split in its past overlapping history

Following the chain of unique previous blobs, checks whether some of them overlaps with multiple blobs in its previous frame. The result is cached in all the visited blobs. This method is used to check whether the blob is a crossing.

Returns:

True if some blob in the past overlapping history of self has multiple previous blobs.

Return type:

bool

property has_multiple_next: bool[source]#

Flag indicating if the blob has a split in its future overlapping history

Following the chain of unique next blobs, checks whether some of them overlaps with multiple blobs in its next frame. The result is cached in all the visited blobs. This method is used to check whether the blob is a crossing.

Returns:

True if some blob in the future overlapping history of self has multiple next blobs.

Return type:

bool

property has_a_next_crossing: bool[source]#

Flag indicating if the blob has a crossing in its future overlapping history

Returns:

If True the blob has a crossing in its “future” history

Return type:

bool

property has_a_previous_crossing: bool[source]#

Flag indicating if the blob has a crossing in its past overlapping history

Returns:

If True the blob has a crossing in its “past” history

Return type:

bool

is_a_sure_individual() → bool[source]#

Flag indicating that the blob is a sure individual according to some heuristics and it can be used to train the crossing detector CNN.

is_a_sure_crossing() → bool[source]#

Flag indicating that the blob is a sure crossing according to some heuristics and it can be used to train the crossing detector CNN.

Return type:

bool

overlaps_with(other: Blob) → bool[source]#

Computes whether the contour of self overlaps with the contour of other

Parameters:

other (Blob) – An instance of the class Blob

Returns:

True if any point of one contour lies inside (or on) the other contour

Return type:

bool

now_points_to(other: Blob) → None[source]#

Links self with other, a blob from the next frame, updating their respective overlapping histories

Parameters:

other (Blob) – An instance of the class Blob

square_distance_to(other: Blob | tuple | list | ndarray) → float[source]#

Returns the squared distance from the centroid of self to other (or to the centroid of other if it is a Blob).

Parameters:

other (Blob or tuple) – An instance of the class Blob or a tuple (x,y)

Returns:

Squared distance between centroids

Return type:

float

distance_from_countour_to(point: Sequence[float]) → float[source]#

Returns the distance between point and the closest point in the contour of the blob.

Parameters:

point (tuple) – (x,y)

Returns:

Smallest distance between point and the contour of the blob.

Return type:

float

property assigned_identities: list[None] | list[int] | list[int | None]#

Identities assigned to the blob during the tracking process

property assigned_centroids: list[tuple[float, float]]#

Centroids assigned to the blob during the tracking process.

It considers the default centroid of the blob at segmentation time or new centroids added to the blob during the interpolation of the crossings.

Returns:

List of pairs (x, y) indicating the position of each individual in the blob.

Return type:

list

property final_centroids: Generator[tuple[float, float], None, None]#

Centroids of the animals in the blob, considering the centroids that might have been modified or added by the user during the validation. Centroids removed by the user are skipped.

By default the centroid is the center of mass of the blob’s contour. It can be different if the user modified the default centroid during validation or generated more centroids.

Returns:

Tuples (x, y) indicating the centroids of the blob.

Return type:

Generator

property all_final_centroids: list#

Like final_centroids but including the centroids removed by the user, marked as (-1, -1)

property final_identities: Generator[int | None, None, None]#

Identities of all_final_identities excluding the ones removed by the user (marked as -1)

property all_final_identities: list#

Identities of the blob after the tracking process and after potential modifications by the users during the validation procedure.

get_image_for_identification(img_size: int, bbox_img: ndarray, resolution_reduction: float) → ndarray[source]#

Generates the image used to train and evaluate the crossing detector CNN and the identification model.

Parameters:
  • img_size (int) – Size of the identification image. The number of channels is always 1 since color images are not supported yet.

  • bbox_img (np.ndarray) – Bounding box image of the blob. This is the image extracted directly from the bounding box, with any size and without the background subtracted.

  • resolution_reduction (float) – Resolution reduction to apply when creating the identification image

Returns:

Square image with black background, centered at the blob’s centroid and rotated according to the blob’s orientation.

Return type:

ndarray

get_bbox_mask() → ndarray[source]#

Computes a binary mask with the same size as the bounding box image, with ones where the blob is.

Returns:

Binary np.ndarray image

Return type:

np.ndarray

update_centroid(old_centroid: tuple[float, float], new_centroid: tuple[float, float], identity: int) → None[source]#

[Validation] Updates the centroid of the blob.

Parameters:
  • old_centroid (tuple) – Centroid to be updated

  • new_centroid (tuple) – Coordinates of the new centroid

  • identity (int) – Identity of the centroid to be updated

init_validator_variables() → None[source]#

Initializes the user generated centroids and identities (None meaning “unchanged”) if they do not exist yet

index_and_centroid_closer_to(centroid: tuple, identity: int | None) → tuple[int, tuple[float, float], float][source]#

Finds the final centroid with the given identity (any identity if None) closest to centroid.

Returns:

Its index, the centroid itself and its squared distance to centroid.

Raises:

ValueError – If no centroid matches identity.

remove_centroid(identity: int, centroid: tuple) → None[source]#

[Validation] Deletes a centroid of the blob.

Parameters:
  • identity (int) – Identity of the centroid to be deleted

  • centroid (tuple) – Centroid to be deleted from the blob

add_centroid(centroid: tuple[float, float], identity: int | None) → None[source]#

[Validation] Adds a centroid with a given identity to the blob.

This method is used in the validation GUI. It is useful to add centroids for crossing blobs that are missing some centroids, or to individual blobs that should have been classified as crossings and are also missing some centroids.

Parameters:
  • centroid (tuple) – Centroid to be added to the blob

  • identity (int) – Identity of the centroid to be added

update_identity(old_identity: int | None, new_identity: int | None, close_to_centroid: tuple[float, float]) → tuple[float, float][source]#

[Validation] Updates the identity of the blob.

This method is used in the validation GUI. It populates the attributes user_generated_identities and user_generated_centroids.

Parameters:
  • old_identity (int) – Old value of the identity of the blob. It must be specified when the blob has multiple identities already assigned.

  • new_identity (int) – New value for the identity of the blob, -1 removes the centroid.

  • close_to_centroid (tuple) – The updated centroid is the one closest to this point.

Returns:

The updated centroid, (-1, -1) if it has been removed.

Return type:

tuple

propagate_identity(old_identity: int | None, new_identity: int | None, centroid: tuple[float, float]) → tuple[int, int][source]#

[Validation] Propagates the new identity to next and previous blobs.

This method is called in the validation GUI when the user updates the identity of a given blob. The propagation stops at the limits of the blob’s fragment.

Parameters:
  • old_identity (int) – Previous identity of the blob

  • new_identity (int) – New identity of the blob

  • centroid (tuple) – Centroid of the blob whose identity has been updated

Returns:

First and last frames where the identity has been modified.

Return type:

tuple

property bbox_in_frame_coordinates#

Bbox in frame coordinates

Deprecated since version 6.0.0: Use bbox_corners() instead

property estimated_body_length#

Estimated body length

Deprecated since version 6.0.0: Use extension() instead

bbox_contains_point()[source]#

Bbox contains point

Deprecated since version 6.0.0: Use contains_point() instead

property all_final_ids_and_centroids#

All final ids and centroids

Deprecated since version 6.0.0: Use all_final_identities() or all_final_centroids() instead

property has_been_modified#

Has been modified

Deprecated since version 6.0.0: Check if user_generated_identities() is not None instead

property properties#

Properties

Deprecated since version 6.0.0: Use summary() instead