API Entry Point

py_fort_myrmidon.Experiment

class py_fort_myrmidon.Experiment

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.

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

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.

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.

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.

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 on the filesystem. 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 filesystem.

property AbsoluteFilePath

the absolute filepath of the Experiment

Type:: str

AddIdentification(self: py_fort_myrmidon.Experiment, antID: int, tagID: int, start: py_fort_myrmidon.Time = {Time:-∞}, end: py_fort_myrmidon.Time = {Time:+∞}) → py_fort_myrmidon.Identification

Adds an Identification to the Experiment

Parameters:

antID (int) – the ant to target
tagID (int) – the TagID to use
start (Time) – the first valid Time for the Identification
end (Time) – the first invalid Time for the Identification

Returns:

the newly created Identification

Return type:

Identification

Raises:

IndexError – if antID is not valid for the Experiment
OverlappingIdentification – if the resulting Identification would overlap in time with another one, either for a given antID or tagID.

AddTrackingDataDirectory(self: py_fort_myrmidon.Experiment, spaceID: int, filepath: str, fixCorruptedData: bool = False) → str

Adds a tracking data directory to the Experiment.

Parameters:

spaceID (int) – the space to add the tracking data directory to.
filepath (str) – the filepath to the tracking data directory.
fixCorruptedData (bool) – In the event that some tracking data is corrupted, if False a FixableError will be raised. Otherwise an attempt to recover as much data as possible eill be made, but it may potentially remove a large chunk of data.

Returns:

the relative path from self.AbsoluteFilePath to filepath,: that will be the URI to identify the tracking data directory.

Return type:

str

Raises:

IndexError – if spaceID is not valid for this Experiment
RuntimeError – if filepath is not a valid tracking data directory.
FixableError – if fixCorruptedData is False and any data corruption is found.
RuntimeError – if the data will overlap in time with another directory in the same space
RuntimeError – if the data is used by another space
ValueError – if the tag family does not match with other directory in the experiment

property AntShapeTypeNames

the ant shape type name by their AntShapeTypeID

Type:: Dict[int,str]

property Ants

the Ant indexed by their AntID.

Type:: Dict[int,Ant]

property Author

the author of the Experiment

Type:: str

property Comment

a comment about the Experiment

Type:: str

CompileTrackingSolver(self: py_fort_myrmidon.Experiment, collisionsIgnoreZones: bool = False) → py_fort_myrmidon.TrackingSolver

Compiles a TrackingSolver that can be used to identify and collide ant from raw data.

Returns:: the compiled tracking solver.
Return type:: TrackingSolver

CreateAnt(self: py_fort_myrmidon.Experiment) → py_fort_myrmidon.Ant

Creates a new Ant in the Experiment.

Returns:: the newly created Ant
Return type:: Ant

CreateAntShapeType(self: py_fort_myrmidon.Experiment, name: str) → int

Creates a new Ant shape type

Parameters:: name (str) – the name of the ant shape type
Returns:: the AntShapeTypeID for the new type
Return type:: int

CreateMeasurementType(self: py_fort_myrmidon.Experiment, name: str) → int

Creates a new measurement type

Parameters:: name (str) – the name of the measurement type
Returns:: the MeasurementTypeID for the new type
Return type:: int

CreateSpace(self: py_fort_myrmidon.Experiment, name: str) → py_fort_myrmidon.Space

Creates a new Space in this Experiment.

Parameters:: name (str) – the name for the new space
Returns:: the newly created Space
Return type:: Space

property DefaultTagSize

the default tag size in mm used in the Experiment

Type:: float

DeleteAnt(self: py_fort_myrmidon.Experiment, antID: int) → None

Deletes an Ant from the Experiment

Parameters:

antID (int) – the AntID of the Ant to remove

Raises:

IndexError – if antID is invalid for the experiment
RuntimeError – if the ant still have Identification targetting her

DeleteAntShapeType(self: py_fort_myrmidon.Experiment, antShapeTypeID: int) → None

Deletes an Ant shape type

Parameters:: antShapeTypeID (int) – the type to delete
Raises:: IndexError – if antShapeTypeID is not valid for Experiment

DeleteIdentification(self: py_fort_myrmidon.Experiment, identification: py_fort_myrmidon.Identification) → None

Deletes an Identification from this Experiment

Parameters:: identification (Identification) – the Identification to remove
Raises:: ValueError – if identification is not a valid Identification object from this Experiment.

DeleteMeasurementType(self: py_fort_myrmidon.Experiment, measurementTypeID: int) → None

Deletes a measurement type

Parameters:

measurementTypeID (int) – the measurement type to delete

Raises:

IndexError – if measurementTypeID is not valid for Experiment
ValueError – if measurementTypeID is HEAD_TAIL_MEASUREMENT_TYPE_ID

DeleteMetaDataKey(self: py_fort_myrmidon.Experiment, key: str) → None

Deletes a meta data key

Parameters:

key (str) – the key to delete

Raises:

IndexError – if key is not valid for this Experiment
RuntimeError – if any Ant contains timed data for key

DeleteSpace(self: py_fort_myrmidon.Experiment, spaceID: int) → None

Deletes a Space from this Experiment.

Parameters:: spaceID (str) – the spaceID of this space
Raises:: IndexError – if spaceID is not a valid for this Experiment.

EnsureAllDataIsLoaded(self: py_fort_myrmidon.Experiment, fixCorruptedData: bool = False) → None

Ensures all tracking data is loaded.

Ensures that all tracking data, statistics and close-up are available.

Parameters:: fixCorruptedData (bool) – if True, will silently fix any data corruption. This could lead to the loss of large chunck of tracking data. Otherwise a RuntimeError is raised summarizing all data corruption found.
Raises:: RuntimeError – if fixCorruptedData is False and some data corruption is found.

property Family

the TagFamily used in the Experiment

Type:: TagFamily

FreeIdentificationRangeAt(self: py_fort_myrmidon.Experiment, tagID: int, time: py_fort_myrmidon.Time) → Tuple[py_fort_myrmidon.Time, py_fort_myrmidon.Time]

Returns an available time range for a tag.

Parameters:

tagID (int) – the tagID to query for
time (Time) – a time that must be contained in the result.

Returns:

A time range (can be (Time.SinceEver() , Time.Forever() )) containing time where tagID is not used by any Identification.

Return type:

Tuple[Time, Time]

Raises:

RuntimeError – if tagID already identifies an Ant at time

IdentificationsAt(self: py_fort_myrmidon.Experiment, time: py_fort_myrmidon.Time, *, removeUnidentifiedAnt: bool = True) → Dict[int, int]

Gets AntID <-> TagID correspondances at a given Time

Parameters:

time (Time) – the wanted Time for the correspondance matching.
removeUnidentifiedAnt – if true, Ant without an Identification at time will not be part of the result. Otherwise the associated tagID value will be 2^32-1.

property MeasurementTypeNames

the measurement type name by their MeasurementTypeID

Type:: Dict[int,str]

property MetaDataKeys

metadata key default value by their unique keys. Object are bool, int, float, str or Time

Type:: Dict[str,object]

property Name

the name of the Experiment

Type:: str

static Open(filepath: str) → py_fort_myrmidon.Experiment

Opens an existing Experiment on the filesystem

Parameters:: filepath (str) – the filepath to open.
Returns:: the Experiment located at filepath
Return type:: Experiment
Raises:: RuntimeError – if filepath does not contains a valid Experiment or associated tracking data is not accessible.

static OpenDataLess(filepath: str) → py_fort_myrmidon.Experiment

Opens an existing Experiment on the filesystem in dataless mode.

In dataless mode, no associated tracking data will be opened, but a TrackingSolver can be used to identify Ants in live tracking situation.

Parameters:: filepath (str) – the filepath to open.
Returns:: the Experiment located at filepath
Return type:: Experiment
Raises:: RuntimeError – if filepath does not contains a valid Experiment

RemoveTrackingDataDirectory(self: py_fort_myrmidon.Experiment, URI: str) → None

Removes a tracking data directory from the Experiment.

Parameters:: URI (str) – the URI that identifies the tracking data directory
Raises:: IndexError – if URI does not identifies a tracking data directory in this experiment.

RenameMetaDataKey(self: py_fort_myrmidon.Experiment, oldKey: str, newKey: str) → None

Renames a meta data key

Parameters:

oldKey (str) – the old name of the key
newKey (str) – the new name for the key

Raises:

IndexError – if oldKey is invalid for the Experiment
ValueError – if newKey is in use for the Experiment

Save(self: py_fort_myrmidon.Experiment, filepath: str) → None

Saves the experiment on the filesystem.

Parameters:: filepath – the filepath to save the experiment to.
Raises:: ValueError – if filepath would change the directory of the Experiment on the filesystem.

SetAntShapeTypeName(self: py_fort_myrmidon.Experiment, antShapeTypeID: int, name: str) → None

Sets the name for an Ant shape type

Parameters:

antShapeTypeID (int) – the type to modify
name (str) – the wanted name

Raises:

IndexError – if antShapeTypeID is invalid for this Experiment

SetMeasurementTypeName(self: py_fort_myrmidon.Experiment, measurementTypeID: int, name: str) → None

Sets the name for a measurement type

Parameters:

measurementTypeID (int) – the type to modify
name (str) – the wanted name

Raises:

IndexError – if measurementTypeID is invalid for this Experiment

SetMetaDataKey(self: py_fort_myrmidon.Experiment, key: str, defaultValue: bool | int | float | str | py_fort_myrmidon.Time) → None

Adds or modifies a meta data key

Parameters:

key (str) – the key to modify
defaultValue (object) – the default value for the key. It will sets its type. Must be a boolean, an int, a float, a str or a Time

Raises:

RuntimeError – if the following conditions are met: a) key is already registered, b) defaultValue would change the type of key and c) at least one Ant has a value registered for key

property Spaces

this Experiment space indexed by their SpaceID

Type:: Dict[int,Space]

__init__(self: py_fort_myrmidon.Experiment, filepath: str) → None

Initialize an experiment from a specified filesystem location. This location will be used to determine relative path to the tracking data.

Parameters:: filepath (str) – the wanted filesystem path to the experiment.
Returns:: a new empty Experiment associated with filepath
Return type:: Experiment

py_fort_myrmidon.TrackingSolver

class py_fort_myrmidon.TrackingSolver

A TrackingSolver is used to Identify and Collide raw tracking data

CollideFrame(self: py_fort_myrmidon.TrackingSolver, frame: py_fort_myrmidon.IdentifiedFrame) → py_fort_myrmidon.CollisionFrame

Runs Ant zone detection and collision detection on an IdentifiedFrame

Parameters:

frame (py_fort_myrmidon.IdentifiedFrame) – the IdentifiedFrame containing position data for the Ant. It will be modified to hold the current detected zone for the Ant.

Returns: