Queries And Matchers

fort::myrmidon::Query

class Query

Queries are computation on an Experiment tracking data.

This class is a wrapper for all data queries that can be made on an Experiment. They takes advantages of multithreading to have efficient computation time.

Note

Some queries have two version, one returing up to two std::vector, and one with a storeMethod parameter. The later is to be used with bindings, or when a different data structure is needed.

Note

For very small Experiment in number of Ant, most of the query operation are IO bounded, and the multithreading overhead will impact performance by 40-50% in computation time, as threads are waiting for data inpout to come. This is the case for IdentifyFrames(), and ComputeAntTrajectories(). When collision detection is required, multi-threading can largely help, especially with a large number of individuals. Threading is controlled with QueryArgs::SingleThreaded

Public Static Functions

static ComputedMeasurement::List ComputeMeasurementFor(const Experiment &experiment, AntID antID, MeasurementTypeID typeID)

Computes all measurement for an Ant.

Parameters:

experiment – the Experiment to query for
antID – the desired Ant
typeID – the desired measurement type

Returns:

a ComputedMeasurement::List of the Measurement for the Ant

static ExperimentDataInfo GetDataInformations(const Experiment &experiment)

Gets tracking data statistics about the Experiment.

Returns:: an ExperimentDataInfo structure of informations

static TagStatistics::ByTagID ComputeTagStatistics(const Experiment &experiment, const std::function<void(int, int)> &progressCallback = [](int, int){}, bool fixCorruptedData = false)

Computes TagStatistics for an experiment.

Parameters:

experiment – the Experiment to query for
fixCorruptedData – a boolean indicating if data corruption should be ignored and silently fixed. Please note that it could cause the loss of large chunk of tracking data. If false, an exception will be thrown.

Returns:

the TagStatistics indexed by TagID

static void IdentifyFramesFunctor(const Experiment &experiment, std::function<void(const IdentifiedFrame::Ptr&)> storeData, const IdentifyFramesArgs &args = IdentifyFramesArgs())

Identifies ants in frames - functor version.

Identifies Ants in frames, data will be reported ordered by time.

Note

Zones for Ant will not be computed unless specified with IdentifyFrameArgs::ComputeZones.

Note

This version aimed to be used by language bindings to avoid large data copy.

Parameters:

experiment – the Experiment to query for
storeData – a functor to store/convert the data
args – the IdentifyFrameArgs to use for this query

static void IdentifyFrames(const Experiment &experiment, std::vector<IdentifiedFrame::Ptr> &result, const IdentifyFramesArgs &args = IdentifyFramesArgs())

Identifies ants in frames.

Identifies Ants in frames, data will be reported ordered by time.

Note

Zones for Ant will not be computed unless specified with IdentifyFrameArgs::ComputeZones.

Parameters:

experiment – the Experiment to query for
result – the resulting IdentifiedFrame
args – the IdentifyFrameArgs to use for this query

static void CollideFramesFunctor(const Experiment &experiment, std::function<void(const CollisionData &data)> storeData, const CollideFramesArgs &args = CollideFramesArgs())

Finds Collision in tracking frames - functor version.

Finds Collision between ants in frames, data will be reported ordered by time. Zones for each Ant will also be computed.

Note

This version aimed to be used by language bindings to avoid large data copy.

Parameters:

experiment – the Experiment to query for
storeData – a functor to store the data as it is produced
args – the QueryArgs to use for this query

static void CollideFrames(const Experiment &experiment, std::vector<CollisionData> &result, const CollideFramesArgs &args = CollideFramesArgs())

Finds Collision in tracking frames.

Finds Collision between ants in frames, data will be reported ordered by time. Zones for each Ant will also be computed.

Parameters:

experiment – the Experiment to query for
result – the resulting IdentifiedFrame and CollisionFrame
args – the QueryArgs to use for this query

static void ComputeAntTrajectoriesFunctor(const Experiment &experiment, std::function<void(const AntTrajectory::Ptr&)> storeTrajectory, const ComputeAntTrajectoriesArgs &args = ComputeAntTrajectoriesArgs())

Computes trajectories for ants - functor version.

Computes ant trajectories in the experiment. A trajectory is the consecutive position of an Ant in a Space, with detection gap under ComputeAntTrajectoriesArgs::MaximumGap. These will be reported ordered by ending time.

Note

This version aimed to be used by language bindings to avoid large data copy.

Parameters:

experiment – the Experiment to query for
storeTrajectory – a functor to store/covert the data
args – the ComputeAntTrajectoriesArgs to use for this query

static void ComputeAntTrajectories(const Experiment &experiment, std::vector<AntTrajectory::Ptr> &trajectories, const ComputeAntTrajectoriesArgs &args = ComputeAntTrajectoriesArgs())

Computes trajectories for ants.

Computes ant trajectories in the experiment. A trajectory is the consecutive position of an Ant in a Space, with detection gap under ComputeAntTrajectoriesArgs::MaximumGap. These will be reported ordered by ending time.

Parameters:

experiment – the Experiment to query for
trajectories – a container for storing the results.
args – the ComputeAntTrajectoriesArgs to use for this query

static void ComputeAntInteractionsFunctor(const Experiment &experiment, std::function<void(const AntTrajectory::Ptr&)> storeTrajectory, std::function<void(const AntInteraction::Ptr&)> storeInteraction, const ComputeAntInteractionsArgs &args = ComputeAntInteractionsArgs())

Computes interactions for ants - functor version.

Computes ant interactions, i.e. time intervals where two Ants collides. These will be reported ordered by ending time.

The parameter ComputeAntInteractionsArgs::ReportFullTrajectories controls if full trajectories should be reported in AntTrajectorySegment or if only a summary should be reported. The former have an high impact on the amount of RAM required to perform the query efficiently or at all.

Note

This version aimed to be used by language bindings to avoid large data copy.

Parameters:

experiment – the Experiment to query for
storeTrajectory – a functor to store/convert trajectories
storeInteraction – a functor to store/convert interaction
args – the ComputeAntInteractionsArgs

static void ComputeAntInteractions(const Experiment &experiment, std::vector<AntTrajectory::Ptr> &trajectories, std::vector<AntInteraction::Ptr> &interactions, const ComputeAntInteractionsArgs &args = ComputeAntInteractionsArgs())

Computes interactions for ants.

Computes ant interactions, i.e. time intervals where two Ants collides. These will be reported ordered by ending time.

The parameter ComputeAntInteractionsArgs::ReportFullTrajectories controls if full trajectories should be reported in AntTrajectorySegment or if only a summary should be reported. The former have an high impact on the amount of RAM required to perform the query efficiently or at all.

Parameters:

experiment – the Experiment to query for
trajectories – container for the AntTrajectory results
interactions – container for AntInteraction results
args – the ComputeAntInteractionsArgs

static void FindVideoSegments(const Experiment &experiment, std::vector<VideoSegment> &segments, SpaceID space, const fort::Time &start, const fort::Time &end)

Finds the VideoSegment in a Space of the Experiment.

Note

it would be extremly computationally inefficient to query for a large range [start;end].

Parameters:

experiment – the Experiment to query for
segments – container for the VideoSegment results
space – the SpaceID of the Space to query for
start – the first Time to query a video frame for
end – the last Time to query a video frame for

static std::vector<std::tuple<AntID, Time, Time>> GetMetaDataKeyRanges(const Experiment &e, const std::string &key, const Value &value)

Gets the time ranges where metadata key has a given value.

Parameters:

e – the Experiment to query for
key – the key to query for
value – the value to check equality to

Throws:

std::out_of_range – if key is not defined in Experiment
std::invalid_argument – if value is not of the right type for key

Returns:

a vector of tuple of AntID and time range where key is equal to value.

static std::tuple<std::vector<std::string>, std::vector<TagID>, Eigen::MatrixXd> GetTagCloseUps(const Experiment &e, const std::function<void(int, int)> &progressCallback, bool fixCorruptedData = false)

Gets the tag close-up in the experiment.

Parameters:

e – the Experiment to query for
progrssCallback – a callback for the progress of the operation
fixCorruptedData – a boolean that will make data corruption error silently ignored. Could lead to the loss of some tag close-up

Returns:

a tuple of a vector of string, TagID, and an Eigen::Matrix

struct CollideFramesArgs : public fort::myrmidon::Query::QueryArgs 

Arguments for CollideFrames.

Arguments for CollideFrames() and CollideFramesFunctor().

Public Members

bool CollisionsIgnoreZones: Collision detection happens over different zones (default: false).

struct ComputeAntInteractionsArgs : public fort::myrmidon::Query::QueryArgs 

Arguments for ComputeAntInteractions.

Arguments for ComputeAntInteractions() and ComputeAntInteractionsFunctor().

Public Functions

ComputeAntInteractionsArgs(): Builds default arguments.

Public Members

Duration MaximumGap: Maximum Duration before considering the trajectory be two different parts (default: 1s)

std::shared_ptr<myrmidon::Matcher> Matcher

Matcher to reduce the query to an Ant subset (default: to nullptr, i.e.

anything).

bool ReportFullTrajectories

Reports full trajectories.

If false only mean trajectory during interactions will be reported, otherwise trajectory will be computed like ComputeAntTrajectories() and AntInteraction wil points to sub-segment (default: true).

bool CollisionsIgnoreZones: Collisions, and therefore interactions, happens over different zones.

bool SegmentOnMatcherValueChange: If a combined matcher value changes, create a new object.

struct ComputeAntTrajectoriesArgs : public fort::myrmidon::Query::QueryArgs 

Arguments for ComputeAntTrajectories.

Arguments for ComputeAntTrajectories() and ComputeAntTrajectoriesFunctor().

Public Members

Duration MaximumGap: Maximum Duration before considering the trajectory be two different parts (default: 1s)

std::shared_ptr<myrmidon::Matcher> Matcher

Matcher to reduce the query to an Ant subset (default: to nullptr, i.e.

anything).

bool ComputeZones: Computes the zone of each Ant (default: false)

bool SegmentOnMatcherValueChange: If a combined matcher value changes, create a new object.

struct IdentifyFramesArgs : public fort::myrmidon::Query::QueryArgs 

Arguments for IdentifyFrames.

Arguments for IdentifyFrames() and IdentifyFramesFunctor().

Public Members

bool ComputeZones: enables zone computation without collision detection

struct QueryArgs

Arguments for any Query.

Subclassed by fort::myrmidon::Query::CollideFramesArgs, fort::myrmidon::Query::ComputeAntInteractionsArgs, fort::myrmidon::Query::ComputeAntTrajectoriesArgs, fort::myrmidon::Query::IdentifyFramesArgs

Public Functions

QueryArgs(): Builds default arguments.

Public Members

Time Start: First Time to consider (default: Time::SinceEver())

Time End: Last Time to consider (default: Time::Forever())

bool SingleThreaded: Uses a single thread for computation (default: false)

bool AllocationInCurrentThread: Forces result allocation from the calling thread (default: false)

fort::myrmidon::Matcher

class Matcher

A Matcher helps to build complex Query by adding one or several constraints.

Matchers works either on single Ant for trajectory computation, or on a pair of Ant when considering interactions. Some matcher have no real meaning outside of interaction (i.e. InteractionType()) and would match any trajectory.

Base Matchers

One would use the following function to get a Matcher :

AntID() : one of the considered Ant in the result should match a given AntID
AntMetaData() : one of the key-value user defined meta-data pair for one of the Ant should match.
AntDistanceSmallerThan(),AntDistanceGreaterThan() : for interaction queries only, ensure some criterion for the distance between the two considedred Ant.
AntAngleSmallerThan()/AntAngleGreaterThan() : for interaction queries only, ensure that angle between Ant meets some criterion.
AntDisplacement(): matches interaction were the displacement of either of the Ant is kept under a threshold.

Combination

Using And() or Or(), one can combine several Matcher together to build more complex criterion. For example to build a Matcher that matches ID 001 or 002:

 {c++}
using namespace fort::myrmidon;
auto m = Matcher::Or(Matcher::AntID(1),Matcher::AntID(2));

Public Types

typedef std::shared_ptr<Matcher> Ptr: A pointer to a Matcher.

Public Static Functions

static Ptr And(std::vector<Ptr> matchers)

Combines several Matcher together in conjunction.

Parameters:: matchers – the matchers to combine
Returns:: a new Matcher which will match only when all matchers also matches.

static Ptr Or(std::vector<Ptr> matchers)

Combines several Matcher together in disjunction.

Parameters:: matchers – the matchers to combine
Returns:: a new Matcher which will match if any of the matchers matches.

static Ptr AntID(AntID antID)

Matches a given AntID.

In case of interactions, matches any interaction with one of the Ant having antID.

Parameters:: antID – the AntID to match against
Returns:: a Matcher that matches Ant with the given antID

static Ptr AntMetaData(const std::string &key, const Value &value)

Matches a given user meta data key/value.

In case of interactions, matches any interaction with one of the Ant meeting the criterion.

Parameters:

key – the key to match against
value – the value to match against

Returns:

a Matcher that matches Ant with key is value.

static Ptr AntDistanceSmallerThan(double distance)

Matches a distance between two Ants.

In case of trajectories, it matches anything.

Parameters:: distance – the distance to be smaller.
Returns:: a Matcher that matches when two Ant lies within the given distance

static Ptr AntDistanceGreaterThan(double distance)

Matches a distance between two Ants.

In case of trajectories, it matches anything.

Parameters:: distance – the distance to be greater.
Returns:: a Matcher that matches two Ant further appart than distance.

static Ptr AntAngleSmallerThan(double angle)

Matches an absolute angle between two Ants.

In case of trajectories, it matches anything.

Parameters:: angle – the angle to be smaller (in radians).
Returns:: a Matcher that matches when the absolute angle between two Ants is smaller than angle.

static Ptr AntAngleGreaterThan(double angle)

Matches an absolute angle between two Ants.

In case of trajectories, it matches anything.

Parameters:: angle – the angle to be greater to (in radians).
Returns:: a Matcher that matches when the absolute angle between two Ants is greater than angle.

static Ptr InteractionType(AntShapeTypeID type1, AntShapeTypeID type2)

Matches an InteractionType.

Matches (type1,type2) and (type2,type1) interactions. In the case of trajectories, it matches anything.

Parameters:

type1 – the first AntShapeTypeID to match
type2 – the second AntShapeTypeID to match

Returns:

a Matcher that matches a given InteractionType or its opposite.

static Ptr AntDisplacement(double under, Duration minimumGap)

Matches Ant displacement.

Matches Trajectories and Interactions where Ant displacement between two consecutive position is smaller than under. If minimumGap is not zero, this check will be enforced only if there was at least minimumGap Time ellapsed between the two positions.

Parameters:

under – maximal allowed displacement in pixels
minimumGap – minimal time gap

Returns:

a Matcher that reject large displacements in a tracking gap.

Queries’ result structures

fort::myrmidon::AntTrajectory

struct AntTrajectory

Defines a trajectory for an Ant.

Public Types

typedef std::shared_ptr<AntTrajectory> Ptr: A pointer to the trajectory.

Public Functions

Time End() const

End Time for this Trajectory.

Returns:: a Time computed from Start and the Positions data.

Public Members

AntID Ant: Reports the AntID of the Ant this trajectory refers to.

SpaceID Space: Reports the Space this trajectory is taking place.

Time Start

Reports the starting Time of this trajectory.

Reports the starting Time of this trajectory. Positions first column are second offset from this time.

Eigen::Matrix<double, Eigen::Dynamic, 5> Positions

Reports the time and position in the frame.

first column: offset in second since Start
second and third column: X,Y position in the image
fourth column: Angle in ]-π,π], in trigonometric orientation. As in images Y axis points bottom, positove angle appears clockwise.
fith column: the zone of the ant

fort::myrmidon::AntInteraction

struct AntInteraction

Defines an interaction between two Ants.

Public Types

typedef std::shared_ptr<AntInteraction> Ptr: A pointer to the interaction structure.

Public Members

InteractionID IDs

The IDs of the two Ant.

The ID of the two Ant. Always reports IDs.first < IDs.second.

InteractionTypes Types

Virtual shape body part that were in contact.

Virtual shape body part that were in contact during the interaction.

std::variant<std::pair<AntTrajectorySegment, AntTrajectorySegment>, std::pair<AntTrajectorySummary, AntTrajectorySummary>> Trajectories

Reports the AntTrajectory or their summary for each Ant during the interaction.

The trajectories are truncated to the interaction timing.

Time Start: Reports the Time the interaction starts.

Time End: Reports the Time the interaction ends.

SpaceID Space: Reports the SpaceID where the interaction happend.

fort::myrmidon::AntTrajectorySegment

struct AntTrajectorySegment

Defines a sub segment of a trajectory.

Public Members

AntTrajectory::Ptr Trajectory: The refering trajectory.

size_t Begin: The starting index of the segment in the referring trajectory.

size_t End: The index after the last index in the referring trajectory.

fort::myrmidon::AntTrajectorySummary

struct AntTrajectorySummary

Defines a trajectory sub-segment summary.

Public Members

Eigen::Vector3d Mean: The mean position during the trajectory.

std::set<ZoneID> Zones: The list of zone traversed by the trajectory.

fort::myrmidon::IdentifiedFrame

struct IdentifiedFrame

A video frame were Ant have been identified from their TagID.

Public Types

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

typedef Eigen::Matrix<double, Eigen::Dynamic, 5, Eigen::RowMajor> PositionMatrix

A Matrix of ant position.

The first column is the AntID
The second and third columns are the x,y position in the original video frame.
The fourth column is the ant angle
The fifth column is the ant current zone or 0 if in no zone or zones aren’t computed.

Public Functions

bool Contains(uint64_t antID) const

Tests if the frame contains an Ant.

Parameters:: antID – the AntID of the Ant to test for.
Returns:: true if antID is in Positions

std::tuple<AntID, const Eigen::Ref<const Eigen::Vector3d>, ZoneID> At(size_t index) const

Extract Ant position data at a given row.

Parameters:: index – the row we want to extract data from
Returns:: the AntID, x,y,angle position and the ZoneID for the Ant at index.

Public Members

Time FrameTime: The acquisition Time of this frame.

SpaceID Space: The Space this frame belongs to.

size_t Height: The original height of the video frame.

size_t Width: The original width of the video frame.

PositionMatrix Positions: The position of each ant in that frame.

fort::myrmidon::CollisionFrame

struct CollisionFrame

Reports all Collision happening at a given time.

Public Types

typedef std::shared_ptr<CollisionFrame> Ptr: A pointer to a CollisionFrame.

Public Members

Time FrameTime: The Time when the interaction happens.

SpaceID Space: Reports the Space this frame is taken from.

std::vector<Collision> Collisions: The Collision taking place at FrameTime.

struct Collision

Defines an interaction between two Ant, ponctual in Time.

Public Members

InteractionID IDs

The AntID of the two Ants interacting.

The AntID of the two Ants interacting. Please note that IDS.first < IDs.second remains always true, to ensure uniqueness of IDs for AntInteraction.

InteractionTypes Types: Reports all virtual AntShapeTypeID interacting between the two Ants.

ZoneID Zone

Reports the Zone where the interaction happened.

Reports the Zone where the interaction happened, the corresponding Space is reported in CollisionFrame. 0 means the default zone.

fort::myrmidon::ComputedMeasurement

struct ComputedMeasurement

Represents a Measurement in millimeters at a given Time.

Measurement in myrmidon are automatically converted to MM given the Experiment tag family and size, and the size of the tag measured in the image.

Public Types

typedef std::vector<ComputedMeasurement> List: A list of measurement.

Public Members

fort::Time Time: the Time of the Measurement

double LengthMM: the value in mm of the measurement

double LengthPixel: the value of the measurement in pixels

fort::myrmidon::TagStatistics

struct TagStatistics

Statistics about a TagID in the experiment.

Public Types

typedef std::map<TagID, TagStatistics> ByTagID: A map of TagStatistics indexed by TagID.

typedef Eigen::Matrix<uint64_t, Eigen::Dynamic, 1> CountVector: A vector of count.

fort::myrmidon::ExperimentDataInfo

struct ExperimentDataInfo

Reports global tracking data stats for an Experiment.

Public Members

uint64_t Frames: The number of tracked frame in the Experiment.

Time Start: The Time of the first tracked frame.

Time End: the Time of the last tracked frame

std::map<SpaceID, SpaceDataInfo> Spaces: Data infos for all Space.

struct SpaceDataInfo

Reports global tracking data stats for a Space.

Public Members

std::string URI: The URI used to designate the Space.

std::string Name: The name of the Space.

uint64_t Frames: The number of frame in the Space.

Time Start: The first Time present in the Space.

Time End: The last Time present in the Space.

std::vector<TrackingDataDirectoryInfo> TrackingDataDirectories: Infos for all tracking data directories, ordered in Time.

struct TrackingDataDirectoryInfo

Reports information about a tracking data directory.

Public Members

std::string URI: The URI used in the GUI to designate the tracking data directory.

std::string AbsoluteFilePath: The absolute filepath on the directory on the system.

uint64_t Frames: The number of Frames in this directory.

Time Start: The first frame Time.

Time End: The last frame Time.