Ants and Identifications

fort::myrmidon::Ant

class Ant

Main object of interest of any Experiment.

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.

Naming

Ant are uniquely identified by their ID. By convention we use decimal notation with up to two 0 prefix to display an ID, as returned by AntFormatID.

Identification

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

Ant Virtual Shape

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

Visualization meta-data

Basic visualization of Experiment data can be done through fort-studio. Ants are displayed according to their DisplayStatus() and DisplayColor(), which can be programmaticaly modified using SetDisplayStatus() and SetDisplayColor().

User defined meta-data (named values)

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

Note

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

Public Types

enum class DisplayState

The DisplayState of an Ant in an Experiment.

Values:

enumerator VISIBLE: the Ant is visible

enumerator HIDDEN: the Ant is hidden

enumerator SOLO: Ant is visible and all non-SOLO Ant will be hidden.

typedef std::shared_ptr<Ant> Ptr: A pointer to an Ant.

Public Functions

TagID IdentifiedAt(const Time &time) const

Gets the TagID identifying this Ant at a given time.

Gets the TagID identifying this Ant at a given Time. If no Identification are valid for this time, an an exception will be thrown.

Parameters:: time – the Time for which we want the identification
Throws:: std::runtime_error – if there no valid Identification for this time.
Returns:: a TagID that identify this ant at this time.

const IdentificationList &Identifications() const

Gets the Identification targetting this Ant.

Gets the Identification targetting this Ant. These Identification will always be sorted in Time and never overlaps.

Returns:: an Identification::List of Identification that target this object.

fort::myrmidon::AntID ID() const

Gets the AntID of an Ant.

Ants gets an unique ID in an Experiment, with a minimal value of 1. 0 is an invalid/undefined AntID.

Returns:: the AntID of the Ant

const Color &DisplayColor() const

Gets the Display Color of an Ant.

Each Ant has a defined Color for display in fort-studio.

Returns:: a const reference to the Color used to display the Ant in fort-studio.

void SetDisplayColor(const Color &color)

Sets the Ant display color.

Parameters:: color – the new Color to use to display the Ant in fort-studio.

DisplayState DisplayStatus() const

Gets the Ant display state.

When visualizing ant in fort-studio, any Ant has different DisplayState :

DisplayState::VISIBLE: the Ant is visible if they are no other Ant which are in DisplayState::SOLO
DisplayState::HIDDEN: the Ant is not displayed
DisplayState::SOLO: the Ant is visible as any other Ant which are in DisplayState::SOLO.

Returns:: the DisplayState for this Ant.

void SetDisplayStatus(DisplayState s)

Sets the Ant display state.

Parameters:: s – the wanted DisplayState

const Value &GetValue(const std::string &key, const Time &time) const

Gets user defined timed metadata.

Gets the value for a key at time. Values are set with SetValue(). If no value is sets prior to Time (including -∞), the Experiment default value for key will be returned.

Parameters:

key – the key of the user defined key in Experiment
time – the Time we want the value for (infinite Time are valid)

Throws:

std::out_of_range – if name is not a defined metadata key in Experiment.

Returns:

the wanted Value for key at time, or the Experiment default one

void SetValue(const std::string &key, const Value &value, const Time &time)

Sets a user defined timed metadata.

Sets key to value starting from time. If time is Time::SinceEver(), sets the starting value for name instead of the Experiment’s default value for key.

Parameters:

key – the metadata key to set
value – the desired Value
time – the first Time after which name will be set to value. It can be Time::SinceEver().

Throws:

std::out_of_range – if name is not a defined key in Experiment
std::invalid_argument – if time is Time::Forever()
std::runtime_error – if value is not of the right type for key

void DeleteValue(const std::string &key, const Time &time)

Removes any user defined value at a given time.

Removes any value defined at a time.

Parameters:

key – the key to remove
time – the Time to remove. It can be Time::SinceEver().

Throws:

std::out_of_range – if no value for key at time have been previously set with SetValue().

const std::map<Time, Value> &GetValues(const std::string &key) const

Gets all metadata key value changes over time.

Parameters:: key – the key to list
Returns:: the values of key over the time

void AddCapsule(AntShapeTypeID shapeTypeID, const std::shared_ptr<Capsule> &capsule)

Adds a Capsule to the Ant virtual shape list.

Adds a Capsule to the Ant virtual shape, associated with the shapeTypeID body part.

Parameters:

shapeTypeID – the AntShapeTypeID for the Capsule
capsule – the Capsule

Throws:

std::invalid_argument – if shapeTypeID is not defined in Experiment

const TypedCapsuleList &Capsules() const

Gets all capsules for this Ant.

Returns:: a TypedCapsuleList representing the virtual shape of the Ant

void DeleteCapsule(const size_t index)

Delete one of the virtual shape.

Parameters:: index – the index in the Capsules() to remove
Throws:: std::out_of_range – if index is greate or equal to the size of Capsules().

void ClearCapsules(): Deletes all virtual shape parts.

fort::myrmidon::Identification

class Identification

Relates tags to Ant.

An Identification relates a TagID to an Ant, with Time validity data and geometric data.

Time validy

Identification are bounded in Time in the range [Start(),End()[. Start() can be Time::SinceEver() and End() can be Time::ForEver(). These value are modifiable with SetStart() and SetEnd().

Internally fort-myrmidon ensure time validity of Identification. It means that:

Two Identification using the same TagValue cannot overlap in Time.
Two Identification pointing to the same Ant cannot overlap in Time.

Pose information

Identification also contains geometric information on how the detected tag is related to the observed Ant. These are the translation and rotation of the Ant, in the tag coordinate reference.

Usually, this information is automatically generated from the manual measurement HEAD_TAIL_MEASUREMENT_TYPE made in fort-studio. Alternatively, users can override this behavior by setting themselves the relative pose using SetUserDefinedAntPose(). ClearUserDefinedAntPose() can be used to revert to the internally computed pose.

Tag Size

Identifications also contains the information of the physical tag size used to identify the individual. It can be accessed and set with TagSize and SetTagSize. 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, appart for a few individuals, for examples, Queens.

Note

An Identification can only be created from an Experiment with Experiment::AddIdentification.

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.

Public Types

typedef std::shared_ptr<Identification> Ptr: A pointer to an Identification.

Public Functions

TagID TagValue() const

Gets the TagID of this Identification.

The associated TagID of an Identification is immuable.

Returns:: the TagID used by this Identification

void SetEnd(const Time &end)

Sets the ending validity time for this Identification.

Sets the ending validity Time for this Identification, i.e. the first Time where this Identification becomes invalid (Identification are valid for [Start(),End()[).

Parameters:: end – the ending Time. It can be Time::Forever().
Throws:: OverlappingIdentification – if end will make two Identification overlap in Time.

const Time &Start() const

Gets the starting validity time.

First Time where this Identification becomes valid.

Returns:: the Time where where this Identification becomes valid. It can return Time::SinceEver()

const Time &End() const

Gets the ending validity time.

First Time where this Identification becomes unvalid.

Returns:: the first Time where this Identification becomes unvalid. It can return Time::Forever()

Eigen::Vector2d AntPosition() const

Gets the Ant center position relatively to the tag center.

Gets the Ant center position relatively to the tag center. This offset is expressed in the tag reference frame.

Returns:: an Eigen::Vector2d of the Ant center relative to the tag center.

double AntAngle() const

Gets the Ant angle relatively to the tag rotation.

Gets the Ant position relatively to the tag center. This offset is expressed in the tag reference frame.

Note

Angles use standard mathematical orientation. One has to remember that the y-axis in image processing is pointing from top to bottom, so when looking at the image, positive angle are clockwise, which is the opposite of most mathematical drawing when y is pointing from bottom to top.

Returns:: the angle in radian between the tag orientation and the ant orientation.

bool HasUserDefinedAntPose() const

Indicates if Identification has a user defined pose.

Returns:: true if the Identification has a user defined pose set with SetUserDefinedAntPose()

void SetUserDefinedAntPose(const Eigen::Vector2d &antPosition, double antAngle)

Sets a user defined Ant pose.

Parameters:

antPosition – the offset, from the tag center to the Ant center, expressed in the tag reference frame.
antAngle – the Ant angle, relative to the tag angle.

void ClearUserDefinedAntPose()

Clears any user defined pose.

Clears any user defined pose for this Identification. fort-myrmidon will re-compute the Ant pose from HEAD_TAIL_MEASUREMENT_TYPE measurement made in fort-studio.

void SetTagSize(double size)

Sets the tag size for this Identification.

Parameters:: size – the tag size in millimeters for this Identification. Can be Identification::DEFAULT_TAG_SIZE to force the use of the Experiment::DefaultTagSize().

double TagSize() const

Gets the tag size for this Identification.

Returns:: size the tag size in millimeters for this Identification. If equal to Identification::DEFAULT_TAG_SIZE the Experiment::DefaultTagSize() is used instead.

bool HasDefaultTagSize() const

Checks if Experiment::DefaultTagSize() is used.

Returns:: true if this Identification uses Experiment::DefaultTagSize()

Public Static Attributes

static const double DEFAULT_TAG_SIZE: Value use to mark the Identification to use the Experiment::DefaultTagSize()