Aivia Software
Spatial Relations Tool
- John Stansberry
With the Spatial 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 Spatial Relation Tool an independent tab control denoted with 
General UI
Orange - Selected Spatial Relation Rule and file options
Relation Name and Selector
A drop down selector for the selected spatial relation rule
Loaded Rules
Rules which exist in Aivia but do not belong to an individual field
This is useful when a rule needs to be applied to multiple images, saved between sessions, or kept for recording purposes
Applied Rules
Rules which exist on the active image displayed in Aivia
Icons from left to right
Create new Spatial Relations Rule
Rename the selected rule
Remove/Delete the selected rule
Clear all Loaded Rules (Note this does not clear the Applied Rules)
Load rule from file
Save rule to file
Green - Indicator for Loaded vs Applied
“Creating” for loaded
This denotes that when the rule is created a copy will be placed in the “Applied” section and that copy will now be the active spatial relations rule
“Editing” for applied
This denotes that you are modifying data on the image
Blue - Spatial Relation Settings
Analysis Type
Type of Analysis defined for the rule
Options
Co-localization
Nearest Neighbor
From
Identifies the source object group to which the relation will interact
Sometimes referred to as the “Primary”, “Parent”, or “Root” of the relation
This is important to distinguish because the direction of the relationship matters
eg: When finding the nearest object in the picture, Red → Blue matches the red to the nearest blue, however, Blue → Red would match all blue objects with the singular red object
Find
Specifies the type of relationship, list of all relationship types and restrictions listed below in the Rule Types table
Parameters
Search Range
The maximum search distance to attempt to find objects to relate
This number is important because it limits the number of objects to compare, larger search range can increase processing time exponentially and is recommended to be kept small when dealing with many objects
Min Overlap
The minimum required overlap to be considered related
In Set
Identifies the other half of the objects in which the relation will interact
Sometimes referred to as the “Secondary” or “Child” of the relation
For the same reasons as the “From” object group, it is important to distinguish which objects to match within the relation
In Set by default do not have measurements generated for them because in many cases the relation is many objects to a single Primary object
Pink - Selected measurements to be generated when the Spatial Relation Rule is applied
Purple - Create/Apply the Spatial Relation Rule to the active image with the given parameters
Rule Types
Co-localization | Dimensions | Description |
Overlap (All) | 2D+3D | Relates each object in the primary set with the overlapped object(s) in the associate set |
Overlap (Nearest Centroid) | 2D | 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 |
Overlap (Full) | 2D | Relates each object in the primary set with the overlapped object(s) in the associate set where the overlapped object is completely inside of the primary |
Overlap (Partial) | 2D | Relates each object in the primary set with the overlapped object(s) in the associate set where the overlapped object is intersecting the primary but not completely inside |
Overlap (Min % Based) | 2D | Relates each object in the primary set with the overlapped object(s) in the associate set where the overlapped area is at least covering the defined percentage of the primary objects area |
Nearest Neighbor | Dimensions | Description |
The Nearest Object | 2D+3D | Relates each object in the primary set with a single object in the associated set where two vertices of the objects are the smallest distance apart |
The Nearest 5 Objects (In Search Range) | 2D+3D | Relates each object in the primary set with up to 5 object(s) (prioritizing smallest distance) in the associated set in which any vertex of the associated object is within the search range of any vertex on the primary object. |
All Objects (In Search Range) | 2D+3D | Relates each object in the primary set with object(s) in the associated set in which any vertex of the associated object is within the search range of any vertex on the primary object. |
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 |
% 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 name (eg: “Mesh 14” from two different object sets.)
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 |
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.
