Ants and Identifications

py_fort_myrmidon.Ant

class py_fort_myrmidon.Ant

Ant are the main object of interest of an Experiment. They are identified from tags with Identification, have a virtual shape to perform collision and interaction detection, and holds user defined metadata.

Ant can only be created from an Experiment with Experiment.CreateAnt().

Ant are uniquely identified by an ID. By convention we use decimal notation with up to two 0 prefix to display these AntID, as returned by FormatAntID().

Instead of working directly with TagID fort-myrmidon uses Identification to relate a tag value to an Ant. An Ant could have different Identifications, allowing us to use different tag ID to refer to the same individual. One would use IdentifiedAt() to obtain the tag ID that identifies an Ant at a given Time.

Each Ant has an associated virtual shape that is used to compute instantaneous collision detection ( Query.CollideFrame() ), or timed ant interactions ( Query.ComputeAntInteraction() ). These shapes can be defined manually in fort-studio or programmatically accessed and modified with Capsules, AddCaspule(), DeleteCapsule() and ClearCapsules().

Basic visualization of Experiment data can be done through fort-studio. Ants are displayed according to their DisplayStatus and DisplayColor.

Ant can stores timed user defined metadata. These are modifiable using SetValue() and DeleteValue() and accesible through GetValue().

AddCapsule(self: py_fort_myrmidon.Ant, shapeTypeID: int, capsule: py_fort_myrmidon.Capsule) → None

Adds a Capsule to the Ant virtual shape.

Parameters:

  • shapeTypeID (int) – the AntShapeTypeID associated with the capsule

  • capsule (Capsule) – the capsule to add

Raises:

ValueError – if shapeTypeID is not defined in the Experiment

property Capsules

a list of capsules and their type

Type:

List[Tuple[int,Capsule]]

ClearCapsules(self: py_fort_myrmidon.Ant) → None

Removes all capsules for this Ant.

DeleteCapsule(self: py_fort_myrmidon.Ant, index: int) → None

Removes one of the shape

Parameters:

index (int) – the index to remove in Capsules

Raises:

IndexError – if index >= len(self.Capsules())

DeleteValue(self: py_fort_myrmidon.Ant, key: str, time: py_fort_myrmidon.Time) → None

Clears a user defined timed metadata.

Parameters:

  • key (str) – the key to clear

  • time (Time) – the time to clear a value for key

Raises:

IndexError – if key was not previously set for time with SetValue().

property DisplayColor

the color used to display the Ant in fort-studio

Type:

Tuple[int,int,int]

class DisplayState

Enumerates the possible display state for an Ant

Members:

VISIBLE : the Ant is visible

HIDDEN : the Ant is hidden

SOLO : the Ant is visible and all other non-solo ant are hidden

property name
property DisplayStatus

the DisplayState in fort-studio for this Ant

Type:

Ant.DisplayState

GetValue(self: py_fort_myrmidon.Ant, key: str, time: py_fort_myrmidon.Time) → bool | int | float | str | py_fort_myrmidon.Time

Gets user defined timed metadata.

Parameters:

  • key (str) – the key to query

  • time (Time) – the time, possibly infinite to query for

Returns:

the value for key at time, if defined, or the Experiment’s default value.

Return type:

bool, int, float, str or Time

Raises:

IndexError – if key is not defined in Experiment

GetValues(self: py_fort_myrmidon.Ant, key: str) → List[Tuple[py_fort_myrmidon.Time, bool | int | float | str | py_fort_myrmidon.Time]]

Gets metadata key changes over time.

Parameters:

key (str) – the key to list changes

Raises:

IndexError – if key is not defined in Experiment

property ID

the AntID for this Ant

Type:

int

property Identifications

all Identification that target this Ant, ordered by validity time.

Type:

List[Identification]

IdentifiedAt(self: py_fort_myrmidon.Ant, time: py_fort_myrmidon.Time) → int

Gets the TagID identifiying this Ant at a given time

Parameters:

time (Time) – the time we want an identification for

Returns:

the TagID that identifies this Ant at time.

Return type:

int

Raises:

Error – if no tag identifies this Ant at time.

SetValue(self: py_fort_myrmidon.Ant, key: str, value: bool | int | float | str | py_fort_myrmidon.Time, time: py_fort_myrmidon.Time) → None

Sets a user defined timed metadata

Parameters:
Raises:

py_fort_myrmidon.Identification

class py_fort_myrmidon.Identification

Identifications relates tag to Ant with Time and geometric data.

Identification can only be created from an Experiment with Experiment.AddIdentification().

Identifications are bounded in Time in the range [ Start , End [. These attributes can respectively be set to Time.SinceEver() and Time.Forever(). Internally fort-myrmidon ensure the validity of all Identifications. It means that:

  • Two Identifications using the same TagValue cannot overlap in Time.

  • Two Identifications using targeting the same Ant cannot overlap in Time.

If any modification through Experiment.AddIdentification(), Start or End would violate one of these conditions, an OverlappingIdentification exception will be raised.

Identifications also contains geometric informations on how the detected tag is related to the observed Ant. These are the translation and rotation of the Ant, expressed in the tag coordinate reference. Usually, this information is automatically generated from the manual measurement of type Experiment.HEAD_TAIL_MEASUREMENT_TYPE made in fort-studio. Alternatively, users can override this behavior by setting themselves this pose using SetUserDefinedAntPose(). ClearUserDefinedAntPose() can be used to revert to the internally computed pose.

Note

Any angle is measured in radians, with a standard mathematical convention. Since in image processing the y-axis is pointing from the top of the image to the bottom, positive angles appears clockwise.

Identifications also contains the information of the physical tag size used to identify the individual. It can be accessed and set with TagSize. The value DEFAULT_TAG_SIZE (i.e. 0.0) indicates that the Experiment.DefaultTagSize should be used. Therefore, for most Ant, this field should be kept to DEFAULT_TAG_SIZE, excepted for a few individuals, for examples, Queens.

DEFAULT_TAG_SIZE

a value of 0.0 that indicates that the Experiment.DefaultTagSize should be used.

Type:

float

property AntAngle

orientation difference between the ant orientation and its physical tag, expressed in radians.

Type:

float

property AntPosition

Ant center position relative to the tag center. (float64, size[2,1])

Type:

numpy.ndarray

ClearUserDefinedAntPose(self: py_fort_myrmidon.Identification) → None

Removes any user-defined ant-tag relative geometry data and re-enable the one computed from manual measurement made in fort-studio.

property End

the first invalid Time fort this identification, it can be Time.Forever()

Type:

Time

HasDefaultTagSize(self: py_fort_myrmidon.Identification) → bool

Indicates if the Experiment.DefaultTagSize is used

Returns:

True if this Identification uses Experiment.DefaultTagSize, i.e. when TagSize == DEFAULT_TAG_SIZE

Return type:

bool

HasUserDefinedAntPose(self: py_fort_myrmidon.Identification) → bool

Indicates if the user overrided the computed pose.

Returns:

True if the ant position relatively to the tag has been set by the user.

Return type:

bool

SetUserDefinedAntPose(self: py_fort_myrmidon.Identification, antPosition: numpy.ndarray[numpy.float64[2, 1]], antAngle: float) → None

Sets an user defined ant position relatively to the tag, overiding the one computed from manual measurements.

To revert to the automatically computed ones, use ClearUserDefinedAntPose()

Parameters:

  • antPosition (numpy.ndarray[numpy.float64[2,1]]) – the position of the ant relatively to the tag center, in the tag reference frame

  • antAngle (float) – the ant angle relatively to the tag angle, in radians

property Start

the first valid Time fort this identification, it can be Time.SinceEver()

Type:

Time

property TagSize

the Identification tag size in millimeters, could be DEFAULT_TAG_SIZE to use Experiment.DefaultTagSize

Type:

float

property TagValue

the associated TagID of this identification

Type:

int

property TargetAntID

the associated AntID of this identification

Type:

int

py_fort_myrmidon.OverlappingIdentification