Aivia Software

Object Relation Tool

With the Object Relation Tool, you can define rules for relating objects. When objects are related, you can calculate relative measurements, such as the numbers of overlapped objects or distances between objects.

Interface

The Object Relation Tool is located in the Spreadsheet tab of the Contents Panel. Click on the Object Relation Tool icon (see right) in the Spreadsheet to open the Object Relation Tool window (see below).

 

 

 

 

Rule Definition

The top section of the Object Relation Tool window has options for creating rules, which are described in the table below.

Name

Description

Name

Description

Relation Name

Specifies the name of the relation rule

From Set

Specifies the primary object set in which the rule will use. This input dictates which object in the relation acts as the “parent” or source of information (eg: measurements) and is the left hand side “one” in the one to one or one to many style relations are derived from

Find

Specifies the type of relationship, list of all relationship types and restrictions listed below in the Rule Types table

Within Range

Specifies the distance to search when using the “All Objects (In Search Range)” Rule Type

In Set

Specifies the secondary object set in which the rule will use. This input dictates which object in the relation acts as the “child” and is the right hand side “one” or “many” in the one to one or one to many style relations are derived from.

With Options

Allows options to be set dictating several parameters for how the processing occurs or the output format

 

Rule Types

Rule Option 1

Description

Rule Option 1

Description

The Nearest Object

Relates each object in the primary set with nearest object found in the secondary set. Nearest here is defined by the closest 2 vertices found between a primary and secondary object. Inputting the same In and From Sets will not produce output.

The Nearest 5 Objects (In Search Range)

Relates each object in the primary set with nearest 5 objects found in the secondary set. Nearest here is defined by the closest 2 vertices found between a primary and secondary object.

All Objects (In Search Range)

Relates each object in the primary set with any object within the specified search range. Within here is defined by any vertex of the secondary object being within ‘search range’ of any vertex of the primary object

Overlapping Objects

Relates each object in the primary set with the overlapped object in the associate set, when multiple secondary objects overlap, the one with the nearest centroid (center of bounding box) to the primary object’s centroid is chosen

 

Using the Object Relation Tool

When you have two object sets you would like to relate, go to the Spreadsheet in Aivia and click on the Object Relation Tool icon to open the Object Relation Tool window. Specify the name of the relation rule in the Rule Name textbox, set the relation rule type in the Association Rule section, and select the object sets to relate in the Primary Set and Associate Set menus. Review the Rule Types section of this page to determine which object set to set as the primary one. Then, click Add to add the rule into the table of relation rules. Check the Open Measurements Dialog on Apply checkbox if you would like to change or add any measurements immediately after the relations are calculated, and then click Apply to calculate the relations.

Adding Relation Measurements

Once relations are established, you can add relation measurements to the related object sets with the Measurement Tool.

 

 

The available, pre-defined relation measurements are given in the table below along with which measurements are available for 2D objects, which measurements are available for 3D objects, which measurements are only available for track (multi-timepoint) objects, which measurements are calculated (non-blank) for the related objects in the Primary Set, and which measurements are calculated for the related objects in the Associate Set. Refer to the Relation section of the Measurement Definitions page for the corresponding measurement definitions.

Measurement

2D Objects

3D Objects

Related Tracks Only

Primary Objects

Associated/Secondary Objects

Measurement

2D Objects

3D Objects

Related Tracks Only

Primary Objects

Associated/Secondary Objects

% Overlapped

x

 

 

x

 

All Relations Count

x

x

x

x

x

Area Overlapped

x

 

 

x

 

First Relation Frame

x

x

x

x

x

Has Relation

x

x

x

x

x

Last Relation Frame

x

x

x

x

x

Relation Primary Count

x

x

x

x

x

Relation Secondary Count

x

x

x

x

x

Relations on Frame

x

x

 

x

x

Relative Acceleration

x

x

x

 

x

Relative Center of Mass Distance

x

x

 

 

x

Relative Center of Mass X

x

x

 

 

x

Relative Center of Mass Y

x

x

 

 

x

Relative Center of Mass Z

 

x

 

 

x

Relative Distance

x

x

 

 

x

Minimum Relative Distance

x

x

 

x

 

Relative Straight Line Velocity

x

x

x

x

 

Relative Straight Line Velocity Squared

x

x

x

x

 

Relative Velocity

x

x

x

 

x

Relative X Position

x

x

 

 

x

Relative Y Position

x

x

 

 

x

Relative Z Position

 

x

 

 

x

 

Nearest Object Specific Measurements

Default nearest object measurements will include any object from any relation defined for the object the measurement is specified on. This means if two nearest relation rules exist (eg: “Relation Rule 1” and “Relation Rule 2” where “Object Set A” is the primary), it will consider both of those rules when calculating the below measurements.

When referencing ID this is the measurement named “ID” NOT the number after the object name. ID is unique per session of Aivia to avoid confusion between two objects both having the same named (eg: “Mesh 14” from two different object sets.)

Measurement

Description

Measurement

Description

Nearest Object ID

Displays the ID of the object found to be the nearest based on the relation definition

Nearest Object Distance

Displays the calculated distance between the nearest 2 vertices of the nearest found object

Nearest Objects Count

Displays the number of objects categorized under the nearest relation rules

Mean Object Distance 3

Displays the mean of the 3 nearest distances between the nearest 2 vertices of the nearest found objects

Mean Object Distance 5

Displays the mean of the 5 nearest distances between the nearest 2 vertices of the nearest found objects

Adding Custom, Advanced Relation Measurements

You can use the Advanced Measurements tool to create custom measurements for objects related through the Object Relation Tool. Some Advanced Measurement Functions that may be useful for your custom relation measurements are in the table below.

Function Name(Input 1, Input 2,...)

Description

Function Name(Input 1, Input 2,...)

Description

RelationCount()

Returns the number of objects that are related to the tracked object

RelationCount(Related Object Set)

Returns the number of objects that are related to the tracked object from the specified object set

RelationCountAtFrame()

Returns the number of objects that are related to the object on any given frame, excluding objects related through lineage

RelationCountAtFrame(Related Object Set)

Returns the number of objects that are related to the object from the specified object set on any given frame, excluding objects related through lineage

RelatedObjects(Statistic Type, Measurement to Summarize)

Calculates the statistical type on the related objects

RelatedObjects(Statistic Type, Measurement to Summarize, Related Object Set)

Calculates the statistical type on the related objects which are from the specified, related object set

RelatedSecondaryObjects(Statistic Type, Measurement to Summarize, Related Object Set)

Calculates the statistical type on the related objects which are from the related object set; the primary related objects are the ones which are statistically grouped

NearestObjectID(Relation Rule)

Displays the ID of the object found to be the nearest based on the relation definition restricted to the input relation rule's data

NearestObjectDistance(Relation Rule)

Displays the calculated distance between the nearest 2 vertices of the nearest found object restricted to the input relation rule's data

NearestObjectsMeanDistance(Relation Rule)

Displays the mean of the all nearest distances between the nearest 2 vertices of the nearest found objects restricted to the input relation rule's data

 

Viewing Relations with the Relational Spreadsheet

The Relational Spreadsheet can be helpful for identifying which objects are related. You can find the relational spreadsheet in the bottom tools section with the label “Relational Spreadsheet”

The Relational Spreadsheet can be used to view multiple types of object hierarchies, but to view relations defined with the Object Relation Tool, choose the ObjectRelation option in the Relation Type menu. Object relation tool defined relations can also be viewed in other structures (Cells, Neurons, Lineage) when the “Include Object Relations” toggle is turned on. The Relational Spreadsheet has three main sections: the hierarchy view, the primary/parent object section, and the secondary/associate/child objects section (see below). See the Relational Spreadsheet wiki entry for more information.

 

Exporting Relations

To export which objects are related to which other objects in CSV format, click on the Export to Excel icon in the Spreadsheet, choose the Export Relations option (see below), navigate to a folder you would like to output the CSVs to, and then click Select Folder. The designated folder is then populated with a CSV file for each object set on the image that is related to another object set. For each object set, the first column of its CSV contains each object with a (primary or secondary) relation. There is a subsequent column for each related object set with the objects related to the object in the first column given in the same row.

 

 

Related Articles