API Entry Point

fort::myrmidon::Experiment

class Experiment

Entry point of the fort-myrmidon API.

An Experiment olds a collection of Ant, Identification, Space and Zone and give access to the identified tracking data instantaneous collision and interaction detection through Query .

File convention

Experiment are save to the disk in .myrmidon files. One can use Open(), OpenDataLess(), and Save() to interact with these files.

Linking with acquired data

One can use AddTrackingDataDirectory() to link an Experiment with some tracking data, organized by fort-leto in a tracking data directory. This data must be assigned to a Space (previously created with CreateSpace()). Experiment saves relative links to these tracking data directory. These paths are relative, so one can rename a .myrmidon file on the filesystem with Save(), but it must remains in the same directory.

Tracking meta-data

In fort-myrmidon, tags are not used directly. Instead user are required to make Ant object (through CreateAnt()) and use Identification (through AddIdentification()) to relate a tag value to an Ant. To perform collision and interaction detection, users can create for each Ant a virtual shape, made of a collection of Capsule. Each Capsule is assigned an AntShapeTypeID (an integer starting from 1) which must be previously defined using CreateAntShapeType(). There is no predefined AntShapeTypeID

fort-studio allows to make measurement on close-up of each Ant. These measurement must be assigned to a type, created with CreateMeasurementType(). There is a predefined, undeletable MeasurementTypeID: HEAD_TAIL_MEASUREMENT_TYPE. It is used to automatically determine Identification::AntPosition() and Identification::AntAngle() from fort-studio measurement.

User timed meta-data

Each Ant can also holds a dictionnary of key/value pairs. The key name, type and initial value for each Ant must be defined with SetMetaDataKey(). Through Ant::SetValue(), individual, timed value can be assigned to each Ant. There are no predefined keys.

Working without acquired data

An Experiment is also usuable without linking to any tracking data. OpenDataLess() can be used to open an existing Experiment, previously linked with acquired data, but without requiring the data to be present. Any Query on such Experiment object will report no data, but a TrackingSolver (acquired with CompileTrackingSolver()) could be used, to perform, for example identifications and collision detection on a live tracking datastream of fort-leto. Also Tracking and user-defined meta-data can be manipulated without the need of the often very large tracking data directory to be present on the system.

Public Types

typedef std::unique_ptr<Experiment> Ptr

A pointer to an Experiment.

Public Functions

void Save(const std::string &filepath)

Saves the Experiment at the desired filepath.

Saves the Experiment to filepath. It is not possible to change its parent directory (but file renaming is permitted).

Parameters:

filepath – the desired filesystem location to save the Experiment to

Throws:

std::invalid_argument – if filepath will change the parent directory of the Experiment.

std::string AbsoluteFilePath() const

Path to the underlying .myrmidon file.

Returns:

the absolute filepath to the .myrmidon file

Space::Ptr CreateSpace(const std::string &name)

Creates a new Space.

Parameters:

name – wanted name for the new Space

Returns:

the newly created Space.

void DeleteSpace(SpaceID spaceID)

Deletes a Space.

Parameters:

spaceID – the SpaceID of the Space we want to delete.

Throws:

• std::out_of_range – if spaceID is not a valid ID for one of this Experiment Space.

• std::runtime_error – if spaceID still contains any tracking data directories.

const SpaceByID &Spaces() const

Gets Space defined in the Experiment.

Returns:

a map of the Experiment Space indexed by their SpaceID

std::string AddTrackingDataDirectory(SpaceID spaceID, const std::string &filepath, bool fixCorruptedData = false)

Adds a tracking data directory to one of Experiment’s Space.

Adds a tracking data director acquired with the FORT system to the wanted Space.

Parameters:

• spaceID – the Space the data directory should be associated with

• filepath – path to the directory we want to add

• fixCorruptedData – silently fix any corrupted data,with potentially loss of a large chunk of data. Otherwise a FixableErrors will be thrown.

Throws:

• std::out_of_range – if spaceID is not valid for this Experiment

• std::runtime_error – if filepath is not a valid tracking data directory

• FixableErrors – if the directory contains corrupted data, and fixCorruptedData is false.

• std::domain_error – if filepath contains data that would overlap in Time with another tracking data directory associated with the same space.

• std::invalid_argument – if the tracking data directory is already in use in this experiment.

Returns:

the URI used to designate the tracking data directory

void RemoveTrackingDataDirectory(const std::string &URI)

Removes a Tracking Data Directory from the Experiment.

Parameters:

URI – the URI of the tracking data directory to remove

Throws:

std::invalid_argument – if URI does not designate a tracking data directory in the experiment.

Ant::Ptr CreateAnt()

Creates a new Ant in the Experiment.

Returns:

the newly created Ant

const AntByID &Ants() const

Gets the Ant in the Experiment.

Returns:

the Ant indexed by their AntID in the Experiment.

void DeleteAnt(AntID antID)

Deletes an Ant.

Parameters:

antID – the AntID of the Ant to delete from the experiment

Throws:

• std::out_of_range – if antID is not valid for this Experiment

• std::runtime_error – if the Ant stills have an identification

Identification::Ptr AddIdentification(AntID antID, TagID tagID, const Time &start, const Time &end)

Adds an Identification to the Experiment.

Adds an Identification to the Experiment. Identification are valid for [start,end[. One may obtain a valid Time range using FreeIdentificationRangeAt().

Parameters:

• antID – the targetted Ant designated by its AntID

• tagID – the tag to associate with the Ant

• start – the first valid Time. It can be Time::SinceEver()

• end – the first invalid Time. It can be Time::Forever()

Throws:

• std::out_of_range – if antID is not valid for this Experiment

• OverlapingIdentification – if it will conflict in time with another Identification with the same antID or tagID.

Returns:

the new Identification

void DeleteIdentification(const Identification::Ptr &identification)

Deletes an Identification.

Parameters:

identification – the Identification to delete

Throws:

std::invalid_argument – if identification is not an Identification for an Ant of this Experiment.

std::tuple<fort::Time, fort::Time> FreeIdentificationRangeAt(TagID tagID, const Time &time) const

Computes a valid time range for a tagID.

Queries for a valid time range for a given TagID and Time. The result will be a range [start,end[ containing time. In this range tagID is not used to identify any Ant.

Parameters:

• tagID – the TagID we want a range for

• time – the Time that must be included in the result time range

Throws:

std::runtime_error – if tagID already identifies an Ant at time.

Returns:

two Time that represents an available [start,end[ range for tagID

const std::string &Name() const

The name of the Experiment.

Returns:

a reference to the Experiment’s name

void SetName(const std::string &name)

Sets the Experiment’s name.

Parameters:

name – the new Experiment name

const std::string &Author() const

The author of the Experiment.

Returns:

a reference to the Experiment’s author name

void SetAuthor(const std::string &author)

Sets the Experiment’s author.

Parameters:

author – the new value for the Experiment’s author

const std::string &Comment() const

Comments about the experiment.

Returns:

a reference to the Experiment’s comment

void SetComment(const std::string &comment)

Sets the comment of the Experiment.

Parameters:

comment – the wanted Experiment’s comment

fort::tags::Family Family() const

The kind of tag used in the Experiment.

Gets the family of the tags used in this Experiment. It is automatically determined from the information in TrackingDataDirectory.

Returns:

the family of tag used in the Experiment

double DefaultTagSize() const

The default physical tag size.

Usually an Ant colony are tagged with a majority of tag of a given size in millimeters. Some individuals (like Queens) may often use a bigger tag size that should individually be set in their Identification. This value is then used for Query::ComputeMeasurementFor.

fort-myrmidon uses without white border convention for ARTag and with white border convention Apriltag.

Returns:

the default tag size for the Experiment in millimeters

void SetDefaultTagSize(double defaultTagSize)

Sets the default tag siye in mm.

Parameters:

defaultTagSize – the tag size in millimeter ( the one defined on the tag sheet )

MeasurementTypeID CreateMeasurementType(const std::string &name)

Creates a measurement type.

Parameters:

name – the wanted name for the new measurement

Returns:

the MeasurementTypeID identifying the new measurement type

void DeleteMeasurementType(MeasurementTypeID measurementTypeID)

Deletes a measurement type.

Parameters:

measurementTypeID – the MeasurementTypeID to delete

Throws:

• std::out_of_range – if measurementTypeID is not valid for this Experiment.

• std::invalid_argument – if measurementTypeID is HEAD_TAIL_MEASUREMENT_TYPE_ID.

• std::runtime_error – if some measurement for measurementTypeID exists in the Experiment.

void SetMeasurementTypeName(MeasurementTypeID measurementTypeID, const std::string &name)

Sets the name of a measurement type.

Parameters:

• measurementTypeID – the MeasurementTypeID to modify

• name – the wanted name

Throws:

std::out_of_range – if measurementTypeID is not valid for this Experiment.

std::map<MeasurementTypeID, std::string> MeasurementTypeNames() const

Gets the Experiment defined measurement types.

Returns:

a map of measurement type name by their MeasurementTypeID

AntShapeTypeID CreateAntShapeType(const std::string &name)

Creates a new Ant shape type.

Parameters:

name – the user defined name for the Ant Shape Type

Returns:

the AntShapeTypeID identifying the new Ant shape type.

std::map<AntShapeTypeID, std::string> AntShapeTypeNames() const

Gets the defined Ant shape type.

Returns:

the Ant shape type name by their AntShapeTypeID

void SetAntShapeTypeName(AntShapeTypeID shapeTypeID, const std::string &name)

Changes the name of an Ant Shape type.

Parameters:

• shapeTypeID – the AntShapeTypeID of the shape type to rename

• name – param the new name for the Ant shape type

Throws:

std::out_of_range – if shapeTypeID is not valid for this Experiment.

void DeleteAntShapeType(AntShapeTypeID shapeTypeID)

Removes a virtual Ant shape type.

Parameters:

shapeTypeID – the AntShapeTypeID of the shape type to remove

Throws:

• std::out_of_range – if shapeTypeID is not valid for this Experiment.

• std::runtime_error – if at least one Ant still have a Capsule for shapeTypeID

void SetMetaDataKey(const std::string &key, Value defaultValue)

Adds or modify a user-defined meta data key.

Adds a non-tracking metadata key with type and default defined by defaultValue.

Parameters:

• key – the unique key to add or modify

• defaultValue – the default value for that key. It also determines the type for the key.

Throws:

std::runtime_error – if the following conditions are met:

• key is already registered

• defaultValue would change the type of key

• at least one Ant has a value registered for key

void DeleteMetaDataKey(const std::string &key)

Removes a meta data key.

Parameters:

key – the key to remove

Throws:

• std::out_of_range – if key is not valid for this Experiment.

• std::runtime_error – if at least one Ant has a defined value for key.

std::map<std::string, Value> MetaDataKeys() const

Gets the meta data keys for this Experiment.

Returns:

default Value indexed by key

void RenameMetaDataKey(const std::string &oldKey, const std::string &newKey)

Renames a meta data key.

Parameters:

• oldKey – the key to rename

• newKey – the new key name

Throws:

• std::out_of_range – if oldKey is not valid for this Experiment.

• std::invalid_argument – if newKey is already used in this Experiment.

std::map<AntID, TagID> IdentificationsAt(const Time &time, bool removeUnidentifiedAnt) const

Gets AntID <-> TagID correspondances at a given time.

Parameters:

• time – the wanted Time to query for the correspondances

• removeUnidentifiedAnt – if true, just do not report unidentified at this time. If false std::numeric_limits<TagID>::max() will be returned as a TagID for unidentified Ant.

Returns:

a map with the correspondance between AntID and TagID.

TrackingSolver::Ptr CompileTrackingSolver(bool collisionsIgnoreZones) const

Compiles a TrackingSolver.

Compiles a TrackingSolver, typically use to identify and collide frame from online acquired tracking data.

Returns:

a TrackingSolver for the Experiment.

void EnsureAllDataIsLoaded(const std::function<void(int, int)> &progressCallback, bool fixCorruptedData = false) const

Ensures that all tracking data is loaded.

This operation can take some time.

Parameters:

• progressCallback – a callback to indicate progress. Only called if an operation is actually performed.

• fixCorruptedData – if \true, will try to silently fix corrupted data, leading to potential loss of large chunck of tracking data or a few tag close-ups. Otherwise an exception will be thrown in case of corruption.

Throws:

std::runtime_error – in case of data corruption if fixCorruptedData is \false

Public Static Functions

static inline Experiment::Ptr Open(const std::string &filepath)

Opens an existing Experiment.

Parameters:

filepath – the path to the wanted file

Throws:

std::runtime_error – if filepath is not a valid .myrmidon file.

Returns:

a pointer to the Experiment

static inline Experiment::Ptr OpenDataLess(const std::string &filepath)

Opens an Experiment without associated tracking data.

Opens an Experiment to a .myrmidon file without opening its associated tracking data. This is useful, by example, identify or collides ants from realtime tracking data acquired over the network using a TrackingSolver obtained with CompileTrackingSolver(). When opened in ‘data-less’ mode, no tracking data, tag statistic or measurement will be returned by any Query ( the experiment will appear empty ).

Parameters:

filepath – the path to the wanted file.

Throws:

std::runtime_error – if filepath is not a valid .myrmidon file.

Returns:

the Experiment

static inline Experiment::Ptr Create(const std::string &filepath)

Creates a new Experiment associated with the given filepath.

Creates a new Experiment virtually associated with the desired filepath location. It will not create a new file on the filesystem. The wanted location is required to compute relative path to the associated Tracking Data Directory.

Parameters:

filepath – the filesystem location for the .myrmidon file.

Returns:

the new empty Experiment

Public Static Attributes

static const MeasurementTypeID HEAD_TAIL_MEASUREMENT_TYPE_ID

the default MeasurementTypeID for Head-Tail measuremrent

fort::myrmidon::TrackingSolver

class TrackingSolver

Identifies and Collides Ant from raw tracking data.

This class lets the user to manually identify and track ants from raw tracking data, as for example, obtained from a network stream with fort-hermes

Public Functions

AntID IdentifyAnt(TagID tagID, const Time &time)

Identifies a single ant.

Parameters:

• tagID – the TagID to identify

• time – the time to consider to identify the tag

Returns:

returns the AntID of the Ant tagID is identifying at time, or 0 if there is no matching identification.

void IdentifyFrame(IdentifiedFrame &identified, const fort::hermes::FrameReadout &frame, SpaceID spaceID) const

Identifies Ants from a fort::hermes::FrameReadout

Parameters:

• identified – an IdentifiedFrame that will hold the Ant positions

• frame – the fort::hermes::FrameReadout to identify

• spaceID – the spaceID the frame correspond to

void CollideFrame(IdentifiedFrame &identified, CollisionFrame &collision) const

Collides Ants from an IdentifiedFrame.

Collides Ants from an IdentifiedFrame. identified will be modified to contains for each Ant its current zone. collision frame will be set with all current collision found in identified.

Parameters:

• identified – the IdentifiedFrame with the ant position data and to return ant location.

• collision – the CollisionFrame to return the collision.