Relate many-to-one

Relate objects of two classes based on a variety of metrics (e.

Description

Relate objects of two classes based on a variety of metrics (e.g. spatial overlap or proximity). The assigned relationships are of the form many-to-one, where many input "child" objects can be related to at most, one "parent" object (see "Relate many-to-many" and "Relate one-to-one" modules for alternatives). Measurements associated with this relationship (e.g. distance from child to parent surface) are stored as measurements of the relevant child object.

Parameters

Parameter	Description
Parent (larger) objects	Input reference objects. The "Child (smaller) objects" will be related to these, with children assigned one parent based on, for example, closest proximity or maximum spatial overlap. There's no guarantee of each parent object being assigned at least one child.
Child (smaller) objects	Objects to relate to the parents. Each child will be assigned at most one parent. There's no guarantee a child will be assigned any parent, especially when using options such as "Limit linking by distance".
Method to relate objects	The metric by which parent and child objects will be related: "Matching IDs" Parents and children will be related if they have the same ID number. Since object ID numbers are unique within an object collection there will always be no more than one parent to a child. "Proximity" Children are related to the spatially-closest object from the parent collection. The exact distances used (e.g. centroid to centroid or surface to surface) are controlled by the "Reference mode" parameter. "Spatial overlap" Children are related to the object from the parent collection they have the greatest spatial overlap with. Spatial overlap is defined as the number of coincident object coordinates.
Reference mode	Controls the method used for determining proximity-based relationships: "Centroid" Distances are from child object centroids to parent object centroids. These distances are always positive; increasing as the distance between centroids increases. "Child centroid to parent surface" Distances are from child object centroids to the closest point on parent object surfaces. These distances increase in magnitude the further from the parent surface a child centroid is; however, they are assigned a positive value if the child is outside the parent and a negative value if the child is inside the parent. For example, a centroid 5px outside the object will be simply "5px", whereas a centroid 5px from the surface, but contained within the parent object will be recorded as "-5px". "Surface" Distances are between the closest points on the child and parent surfaces. These distances increase in magnitude the greater the minimum parent-child surface distance is; however, they are assigned a positive value if the closest child surface point is outside the parent and a negative value if the closest child surface point is inside the parent. For example, a closest child surface point 5px outside the object will be simply "5px", whereas a closest child surface point 5px from the surface, but contained within the parent object will be recorded as "-5px". Note: Any instances where the child and parent surfaces overlap will be recorded as "0px" distance.
Limit linking by distance	When selected, objects will only be related if the distance between them (as calculated by the "Reference mode" metric) is less than or equal to the distance defined by "Maximum linking distance (px)".
Maximum linking distance (px)	If "Limit linking by distance" is selected, this is the maximum permitted distance between objects for them to be assigned a relationship.
Inside/outside mode	When relating children to parent surfaces it's possible to only include children inside, outside or on the edge of the parent.This parameter controls which children are allowed to be related to the parents. Choices are: Inside and outside (all distances), Inside only (distances < 0), Inside and on surface (distances <= 0), On surface only (distances = 0), Outside and on surface (distances >= 0), Outside only (distances > 0).
Minimum overlap (%)	Percentage of total child volume overlapping with the parent object.
Require centroid overlap	When selected, child objects are only related to a parent if their centroid is inside the parent object (i.e. the child object centroid is coincident with a parent object coordinate).
Only link objects in same frame	When selected, child and parent objects must be in the same time frame for them to be linked.
Calculate fractional distance	When selected, the fractional distance of the child object between the centre and surface of the parent is calculated. This option is only available when relating children to the parent surface. The calculation can be computationally intensive when dealing with many objects.
Enable multithreading	Process multiple object relationships simultaneously. This can provide a speed improvement when working on a computer with a multi-core CPU.