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 a segmented animal(s) defined with a contour in a specific frame.

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

id_image_index: int#: Index of the identification image position in the HDF5 file

seems_like_individual: bool#: Unicity condition or not huge 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 give by a user during the validation process

user_generated_centroids: list[tuple[float, float] | None] = None#: List of centroids generated by the user during the validation processes

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

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

__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 multiple blobs in its past or future overlapping history

This method is used to check whether the blob is a crossing.

Returns:: If True the blob splits into two or multiple overlapping blobs in its “past” or “future” history, depending on the parameter “direction”.
Return type:: bool

property has_multiple_next: bool[source]#

Flag indicating if the blob has multiple blobs in its past or future overlapping history

This method is used to check whether the blob is a crossing.

Returns:: If True the blob splits into two or multiple overlapping blobs in its “past” or “future” history, depending on the parameter “direction”.
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 pixels in self intersect with the pixels in other

Parameters:: other (<Blob object>) – An instance of the class Blob
Returns:: True if the lists of pixels of both blobs have non-empty intersection
Return type:: bool

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

Given two consecutive blob objects updates 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 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]#

List of the animal/s centroid/s in the blob, considering the potential centroids that might have been added by the user during the validation.

By default the centroid will be the center of mass of the blob of pixels defined by the blob. It can be different if the user modified the default centroid during validation or generated more centroids.

Returns:: List of tuples (x, y) indicating the centroids of the blob.
Return type:: list

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 as images in color are still not considered.
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 used to train the crossings detector and the identification model.

Return type:

ndarray

get_bbox_mask() → ndarray[source]#

Computes the 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

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 during the validation GUI. It populates the private attributes user_generated_identities and user_generated_centroids.

Parameters:

new_identity (int) – new value for the identity of the blob
old_identity (int) – old value of the identity of the blob. It must be specified when the blob has multiple identities already assigned.
centroid (tuple) – centroid which identity must be updated.

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 called in the validation GUI when the used updates the identity of a given blob.

Returns the frame range where identity changes occurred

Parameters:

old_identity (int) – Previous identity of the blob
new_identity (int) – New identity of the blob
centroid (tuple) – [description]

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