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
Episodethe 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()
- 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
- 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_centroidsbut including the centroids removed by the user, marked as (-1, -1)
- property final_identities: Generator[int | None, None, None]#
Identities of
all_final_identitiesexcluding 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()orall_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