moos-ivp.org IvP ManPages Pavlab MIT 2.680 LAMSS Goby NOWISTHETIMEFORALLGOODMENTOCO NOWISTHETIMEFORALN Edit

23 Contact Related Behaviors of the IvP Helm

23.1 Static Versus Dynamically Spawned Behaviors
23.2 Exclusion Filters
     23.2.1 Types of Contact Exclusion Filters
     23.2.2 Configuring Exclusion Filters Globally or Locally
     23.2.3 Enabling Strict Filtering
     23.2.4 Failing an Exclusion Filter on Spawned Behavior
23.3 Contact Flags
     23.3.1 Contact Flag Trigger Tags
     23.3.2 Contact Flag Macros
23.4 Properties Common to All Contact Related Behaviors
     23.4.1 Common Behavior Configuration Parameters
     23.4.2 Closest Point of Approach Calculations

The section contains is a description of five behaviors currently written for the helm that reason about relative position to another vehicle or contact.

The AvoidCollision behavior

The AvdColregsV19 behavior

The CutRange behavior

The Shadow behavior

The Trail behavior

Each behavior needs to be continuously updated with the position and trajectory of a given contact. The helm subscribes to the MOOS variable, NODE_REPORT, which may have content similar to:

 NODE_REPORT= "NAME=alpha,TYPE=UUV,MOOSDB_TIME=39.01,TIME=1252348077.59,
               X=51.71,Y=-35.50,LAT=43.824981,LON=-70.329755,SPD=2.00,HDG=118.85,
               YAW=118.84754,DEPTH=4.63,LENGTH=3.8,MODE=SURVEYING"

This contact information is stored in the helm information buffer for any behavior that wishes to retrieve it on any iteration. Since each behavior type needs to reason about contact information, the common code for this is handled in superclass called IvPContactBehavior. So for these behaviors, the class hierarchy looks like:

Figure 23.1: IvP Contact Behaviors: The contact-related behaviors share a common superclass to streamline the development of contact behaviors and provide a level consistency between behaviors.

23.1 Static Versus Dynamically Spawned Behaviors [top]

A contact behavior may be configured in one of two ways. The simplest way is to reason about a particular contact with a name known at mission time. This is more appropriate for a behavior that needs to operate on one contact at a time, such as a trail or cut-range behavior. While it is technically possible to try to cut-range or trail multiple contacts simultaneously, and the IvP solver will support such an attempt, typically such behaviors are focused on a single contact. Configuration of the behavior simply names the contact

   contact = mothership

A second type of configuration is possible when we would like to have several simultaneous instances of the same behavior, as during collision avoidance with multiple contacts. In this case the behavior is configured to enable templating, and the contact name is left unspecified until a new contact emerges:

   templating = spawn
   contact = to_be_determined

A templating contact behavior works closely with a contact manager, either the pBasicContactMgr app or the newer version, pContactMgrV20. The contact manager is responsible for generating the MOOS posting events that trigger the spawning of a new behavior. As depicted in Figure 23.2 below, the contact manager applies a certain configurable criteria to a contact, and if it passes that criteria, it generates an alert to the helm, resulting in a spawned behavior.

Figure 23.2: Relationship between the contact manager and spawned contact-related behaviors: (1) A contact closes range to ownship, crossing a range threshold. (2) The contact manager makes note and changes the internal record associated with the contact. (3) An alert it generated and received by the helm. (4) The helm spawns a new contact-related behavior dedicated to this contact.x

Typically the contact manager criteria for generating an alert is based on the range of the contact to ownship. However, the contact manager may also utilize additional filters, providing user configurable selectivity as to which contacts generate alerts resulting in behavior spawnings. These filters may be configured at the contact manager level, e.g., ignore all contacts of type sailboat. Or they may be configure at the behavior level, e.g., one collision avoidance behavior matches sailboats, and another collision avoidance behavior matches motorboats. This is covered in part in the documentation of pContactMgrV20, but portion that is accessible through behavior configuration is described next.

23.2 Exclusion Filters [top]

An exclusion filter is tool for allowing the contact manager and/or the helm to treat distinct contacts differently, or ignore selectively handle contacts with a certain property. The contact manager has an exclusion filter, and all behaviors have an exclusion filter. They can safely ignored if one wishes to simple treat all contacts equally, but they can provide some powerful options when applied to particular situation.

23.2.1 Types of Contact Exclusion Filters [top]

Contact exclusion filters may be configured around four different types of properties:

name: This is the most direct method but rather brittle. But if there is a particular named vehicle that you'd like to handle differently, it can be just called out by name.
type: The vehicle type is part of the incoming NODE_REPORT message, e.g., UUV, USV and so on.
group: The vehicle group is part of the incoming NODE_REPORT message, e.g., friendly, foe and so on.
region: A convex polygon describing a region of the operation area.

Each of the above four properties can be configured as match or ignore filters. For example, match_type=kayak indicates that the contact must by of type kayak. Likewise ignore_type=kayak indicates that the contact must be of some type other than kayak. The same is true for name, group, and region properties. This makes eight possible configuration parameters available to all contact behaviors when templating is enabled:

match_group and ignore_group
match_name and ignore_name
match_type and ignore_type
match_region and ignore_region

Multiple entries for each property may be used. If for example multiple match_name configurations are used, a contact will pass the filter if it matches at least one. If multiple ignore_name configurations are used, a contact will pass the filter only if it has a name different from all.

The region property is a bit different from the other three properties. While a contact's name, type, and group properties tend not to change as a mission unfolds, the contact position does. When the region is used by the contact manager as a filter it applies only to that moment in time. If, for example, the contact was outside a match_region but then enters it, it will now pass the filter and an alert will be generated, provided all other filter and range criteria are met. Likewise if the contact manager generated an alert for a contact, but then moved out of a match_region or into an ignore_region, the previously generated alert will not somehow be retracted.

One last note about region filters: non-convex regions may be implemented by using two or more convex regions that "cover" the desired non-convex region. And consistent with the above discussion, the approximating convex regions may harmlessly overlap.

23.2.2 Configuring Exclusion Filters Globally or Locally [top]

As shown in Figure 23.2 above, the contact manager is the gatekeeper for sending the helm alert messages that may trigger the spawning of the behavior. Users can configure the exclusion filters in one of two ways:

Global configuration via the contact manager, pContactMgrV20, or
Local configuration via individual behaviors in the helm.
A third configuration method, dealing with behaviors after they have been spawned, is discussed in Section ???.

The former is method is arguably more convenient but the filters apply to all behavior templates equally. If the contact manager is configured to ignore sailboats, there is no way to otherwise configure the helm to have a spawnable behavior that will handle sailboats. Maybe you really do want to just ignore all sailboats. But if instead you'd like to have one type of behavior ignore sailboats and another type of behavior ignore motorboats, then the filter needs to be configured at the behavior level instead.

Figure 23.3 below depicts a helm locally configured with two distinct behavior templates, with the filter configuration done in the helm configuration. In this way, one distinct behavior is used for Contact Abe, and another for Contact Ben. It may be that both are collision avoidance behaviors, but perhaps the safety region around Abe is larger than Ben. Likewise the filter could have involved the vehicle type, group or region.

Figure 23.3: Configuration of contact filter at the local behavior level: Compare with Figure 23.2, the match filters are provided in the helm configuration rather than the contact manager configuration. This allows different behavior types or templates to work with different contacts. In the previous example in Figure 23.2 every matched contact was handled by the same behavior type.

Using both global and local exclusion filters is certainly allowable, but keep in mind that if a contact is excluded at the global contact manager level, it does not matter what configurations are specified at the local behavior level.

23.2.3 Enabling Strict Filtering [top]

Filtering based on the contact type or group depends on this information being known about the contacts. Typically this is embedded in each incoming NODE_REPORT. In some cases, especially in sensor-based contact management, this information may not be known.

For match filtering, this is not an issue. This is because the spirit of match filtering is that, for example if we say that a contact must be of type motor-boat, and the contact type is unknown, it's pretty clear that condition is not satisfied and thus the contact with unknown type is filtered out.

With ignore filtering it is more ambiguous. This is because the spirit of ignore filtering is that, for example if we say that a contact cannot be of type motor-boat, and the contact type is unknown, we might be inclined to say that it should not be filtered out. The user may however want to be strict about this and say that it should be filtered out since we don't know the contact type, and for all we know it could be a motor-boat.

To allow the user to have some control and be explicit about the above situation, filtering can be configured to be strict by setting strict_ignore to be true or false. The below set of examples hopefully makes this clear.

Contact Type	Ignore Group	Strict Ignore	Filtered Out
sailboat	sailboat	true or false	yes
sailboat	motorboat	true or false	no
unknown	motorboat	false	no
unknown	motorboat	true	yes

The strict_ignore parameter, as with other filtering parameters, is also used in configuring the contact manager, applied globally and overriding any local filter behavior configurations.

23.2.4 Failing an Exclusion Filter on Spawned Behavior [top]

The primary use of exclusion filters is to affect which behaviors are spawned. However, the configured criteria is based on the vehicle properties of group, name, platform type and location, and these properties may change after a behavior is spawned. Normally a contact behavior does not complete, and exit, until it has gone out of range. The user may also opt to have the behavior exit if its properties change after spawning such that it no longer satisfies the original exclusion filter.

A contact behavior will accept the following three configuration parameters:

exit_on_filter_group: If true, will apply the current known group name to an exclusion filter.
exit_on_filter_vtype: If true, will apply the current known vehicle to an exclusion filter.
exit_on_filter_region: If true, will apply the current known vehicle position to the region component of an exclusion filter.

The default for all parameters is false. A common example is when a detected change of group name or vehicle type is learned via communications or sensors. A vehicle may also move into a region where a behavior may be configured to be no longer concerned with a contact. Failing the exclusion filter in a spawned behavior will simply result in the exit/removal of the behavior from the helm, and deletion of the behavior from memory space.

Unlike the group, vehicle type and region components of an exclusion filter, the vehicle name component of the exclusion filter is not re-assesed after a behavior has spawned, since contact behaviors are essentially keyed by vehicle name.

While the above three parameters are supported by all contact behaviors, not all contact behaviors respect this additional feature. Currently (Aug 2021) only the collision avoidance behaviors (CPA based and COLREGS based) support this feature. Support in additional behaviors will be rolled in on future updates.

23.3 Contact Flags [top]

Available after Release 19.8.1, contact flags are an additional way to configure behaviors to post configurable information upon events based on the relative position between ownship and the contact. Most other types of behavior flags contain simply a variable value pair. For example:

   endflag = RETURN = true

Contact flags allow the user to check for expected results over the course of a mission. It also allows missions to be configured on contact related events such as posting a message to command-and-control or to another vessel when the relative position or range to a contact has been achieved.

23.3.1 Contact Flag Trigger Tags [top]

With contact flags, a trigger tag is included with the flag configuration corresponding to certain events. For example, the @cpa trigger tag will ensure the configured flag will be posted at the time of an observed CPA between ownship and the contact:

   cnflag = @cpa SEND_MESSAGE = true

The trigger tag is always at the beginning of the flag configuration with at least one white space between the tag and the rest of the flag configuration. The trigger tags only apply to contact flags, for contact behaviors, using the cnflag parameter.

Supported trigger flags:

Trigger Flag	Meaning
@cpa:	When the closes point of approach is observed
@os_passes_cn:	When ownship passes contact's beam
@os_passes_cn_port	When ownship passes contact's port beam
@os_passes_cn_star:	When ownship passes contact's starboard beam
@cn_passes_os	When ownship passes contact's beam
@cn_passes_os_port	When contact passes contact's port beam
@cn_passes_os_star	When contact passes contact's starboard beam
@os_crosses_cn	When ownship crosses contact's side
@os_crosses_cn_bow	When ownship crosses contact's side fore of contact
@os_crosses_cn_stern	When ownship crosses contact's side aft of contact
@cn_crosses_os	When contact crosses ownship's side
@cn_crosses_os_bow	When contact crosses ownship's side fore of ownship
@cn_crosses_os_stern	When contact crosses ownship's side aft of ownship

An example is given in Figure 23.4 below of an encounter between ownship and a contact. The relevant trigger tags are shown.

Figure 23.4: An example encounter with trigger tags: As a contact passes ownship various trigger tags become satisfied. The first two trigger tags are based purely on range and are triggered as the vehicle enters the range. The last trigger tag is triggered as the contact opens range to 60. As the two vehicles pass, several trigger tags are satisfied simultaneously.

23.3.2 Contact Flag Macros [top]

Contact flags have a number of supported macros that may be expanded in any value component of a posting. For example, the range between ownship and the contact can be used in a cnflag posting:

   cnflag = @cpa RANGE_TO_CONTACT = $[RANGE]

The value of $[RANGE] is determined at the moment the flag is triggered. Supported macros:

MACROS	Meaning
`$[RANGE]`	Range between ownship and contact
`$[CN_NAME]`	Name of the contact
`$[CN_GROUP]`	Name of the contact
`$[CN_VTYPE]`	Vehicle type of the contact
`$[ROC]`	Rate of Closure between ownship and the contact
`$[OS_CN_REL_BNG]`	Relative bearing of the contact to ownship
`$[CN_OS_REL_BNG]`	Relative bearing of ownship to the contact
`$[BNG_RATE]`	Bearing Rate
`$[CN_SPD_IN_OS_POS]`	Speed of contact in the direction of ownship position
`$[OS_FORE_OF_CN]`	true if ownship is currently fore of the contact
`$[OS_AFT_OF_CN]`	true if ownship is currently aft of the contact
`$[OS_PORT_OF_CN]`	true if ownship is currently on port side of the contact
`$[OS_STAR_OF_CN]`	true if ownship is currently on starboard side of the contact
`$[CN_FORE_OF_OS]`	true if the contact is currently fore of ownship
`$[CN_AFT_OF_OS]`	true if the contact is currently aft of ownship
`$[CN_PORT_OF_OS]`	true if the contact is currently on port side of ownship
`$[CN_STAR_OF_OS]`	true if the contact is currently on starboard side of ownship

23.4 Properties Common to All Contact Related Behaviors [top]

Contact related behaviors are distinct from non contact related behaviors in that they share a fair amount of functionality in dealing with their contact of interest. Contact related behaviors are implemented as a subclass of the IvPContactBehavior class, which is a subclass of the IvPBehavior class. Much of the shared functionality of contact related behaviors is implemented in the former. The shared functionality includes several common configuration parameters, and mechanisms for reasoning about the closest point of approach (CPA) between the platform and contact for candidate maneuver considerations. These topics are discussed next, prior to the sections on the behaviors themselves.

23.4.1 Common Behavior Configuration Parameters [top]

The following set of parameters are common to all the contact related behaviors:

Listing 23.1 - Configuration Parameters Common to Contact Behaviors.

Parameter	Description
bearing_lines	If true, a visual artifict will be produced for rendering the bearing line between ownship and the contact when the behavior is running. Not all behaviors implement this feature.
contact	Name or unique identifier of a contact to be avoided.
decay	Time interval during which extrapolated position slows to a halt.
exit_on_filter_group	If true, and if an exclusion filter is implemented for this contact behavior, an early exit of the behavior may be allowed when or if the group name changes and no longer satisfies the exclusion filter. The default is false.
exit_on_filter_vtype	If true, and if an exclusion filter is implemented for this contact behavior, an early exit of the behavior may be allowed when or if the vehicle type changes and no longer satisfies the exclusion filter. The default is false.
exit_on_filter_region	It true, and if an exclusion filter is implemented for this contact behavior, an early exit of the behavior may be allowed when or if the contact moves into a region that would no longer satisfy the exclusion filter. The default it false.
extrapolate	If true, contact position is extrapolated from last position and trajectory.
ignore_group:	If specified, the contact group may not match the given ignore group. If multiple ignore groups are specified, the contact group must be different than all ignore groups. Introduced after Release 19.8.1. Section 23.2
ignore_name:	If specified, the contact name may not match the given ignore name. If multiple ignore names are specified, the contact name must be different than all ignore names. Introduced after Release 19.8.1. Section 23.2
ignore_region:	If specified, the contact group may be in the given ignore region. If multiple ignore regions are specified, the contact position must be external to all ignore regions. Introduced after Release 19.8.1. Section 23.2
ignore_type:	If specified, the contact type may not match the given ignore type. If multiple ignore types are specified, the contact type must be different than all ignore types. Introduced after Release 19.8.1. Section 23.2
match_group:	If specified, the contact group must match the given match group. If multiple match groups are specified, the contact group must match at least one match group. Introduced after Release 19.8.1. Section 23.2
match_name:	If specified, the contact name must match the given match name. If multiple match names are specified, the contact name must match at least one. Introduced after Release 19.8.1. Section 23.2
match_region:	If specified, the contact must reside in the given convex region. If multiple match regions are specified, the contact position must be in at least one match region. The multiple regions essentially can together support a non-convex regins. Introduced after Release 19.8.1. Section 23.2
match_type:	If specified, the contact type must match the given match type. If multiple match types are specified, the contact type must match at least one match type. Introduced after Release 19.8.1. Section 23.2
on_no_contact_ok	If false, a helm error is posted if no contact information exists. Applicable in the more rare case that a contact behavior is statically configured for a named contact. The default is true.
strict_ignore	If true, and if one of the ignore exclusion filter components is enabled, then an exclusion filter will fail if the contact report is missing information related to the filter. For example if the contact group information is unknown. The default is true.
time_on_leg	The time on leg, in seconds, used for calculating closest point of approach.

The contact parameter specifies the contact name or identifier. This name is used as a key by the behaviors for querying the contact position and trajectory. It must match the contact name received by the helm in an incoming NODE_REPORT message. The contact name may be specified at helm launch time, but it may also be specified at run time if the behavior is configured as a template for dynamic spawning. The latter is more common, for example, in a collision avoidance behavior where the name or ID of the contact is not known until a contact manager alerts the helm. See the Berta mission in Section 34 for an example of this usage.

The extrapolate and decay parameters are used to address the situation where a contact/node report has significant delays between updates. Extrapolation is enabled by setting the extrapolate parameter to true, which is the default. The behavior may be configured to have limited extrapolation by setting a decay time interval. The extrapolated position is based on the last known contact position, heading and speed. The speed used for calculations may begin decaying at the beginning of the decay interval and will have decayed to zero at the end of the decay interval. The default setting is "decay = 15, 30", in seconds. The idea is shown in Figure 23.5.

Figure 23.5: Contact Extrapolations: Contact related behaviors may use an extrapolated position of the contact to compensate for periods of no new reports for the contact. A decay period may be used to effectively halt the extrapolated contact position after some specified period of time. In the example in this figure, the decay window is [15, 30] seconds. After 30 seconds, the extrapolated position does not extend further.

The on_no_contact_ok parameter determines how the behavior should regard the situation where it is unable to find any information about a given contact. If this parameter is set to true, the default, then the behavior will post a warning, BHV_WARNING if no contact information is found. Otherwise the behavior will post an error with BHV_ERROR. In the latter case the helm may interpret this as request to halt the helm and come to zero speed and depth.

The time_on_leg parameter refers to the behavior's calculations of the closest point of approach (CPA) for candidate maneuver legs. A candidate maneuver leg is defined by a the heading, speed, and time-on-leg components. Longer time-on-leg settings tend to report deceivingly worrisome CPA distances even for contacts at a great distance, and lower time-on-leg settings tend to report deceivingly comfortable CPA distances even for vehicles at relatively low distances. The default setting for this parameter is 60 seconds.

23.4.2 Closest Point of Approach Calculations [top]

The IvP functions produced by contact-related behaviors are defined over the domain of possible heading and speed choices. The utility assigned to a point in this domain (a heading-speed pair) depends in part on the calculated closest point of approach (CPA) between the candidate maneuver leg, and the contact leg formed from the contact's position and trajectory. Figure 23.6 shows the relationship between CPA and candidate maneuvers , where =heading and v=speed, for a given relative position between ownship and a given contact vehicle and trajectory. The IvP function generated by the AvoidCollision behavior applies a further user-defined utility function to the CPA calculation for a candidate maneuver, . The form of f() is determined by configuration parameters specific to the individual behavior.

Figure 23.6: The closest point of approach mapping: The function on the right indicates the relative change in calculated closest point of approach between ownship and contact position and trajectory shown on the left.

For contact related behaviors, an important quality of a candidate action , is the {closest point of approach (CPA)} between two vehicles during a candidate leg. A behavior producing an objective function with CPA as a component of its utility function needs to perform many variations of this calculation on each new call to generate an IvP objective function. The algorithm is given here, highlighting a few areas where caching may be exploited to improve efficiency.

Our own current position is known and given by (, ), and the other vehicle's current position and trajectory is given by (, , , ). To compute the CPA distance for a given , first the time t_min when the minimum distance between two vehicles occurs is computed. The distance between the two vehicles at the current time can by determined by the Pythagorean theorem. Generally, for any given time t (where the current time is t=0), and assuming the other vehicle stays on a constant trajectory, the distance between the two vehicles for any chosen is given by:

where

The stationary point is obtained by taking the first derivative with respect to \tol:

Since there is no maximum distance, this stationary point always represents the closest point of approach, and therefore:

The value of t_min may be in the past, i.e., less than zero, if the two vehicles are currently opening range. Or t_min may be well beyond t, the time length of the candidate maneuver . Therefore the value of t_min is clipped by [0, t]. Furthermore t_min is zero when the two vehicles have the same heading and speed (the only condition where is zero). The actual CPA value is then obtained by plugging t_min back into first equation above.

As mentioned before, this calculation is a common component in the underlying utility function for behaviors dealing with relative vehicle motion. A behavior, within a single iteration of the control cycle, will perform a sequence of calculations on different values. However, all calculations have the same values of current vehicle position (, ), and current position and trajectory of the other vehicle (, , , ). To make this overall sequence of calculations faster, all terms in , , and above comprised exclusively of , , , , , are calculated once and cached for later calculations.

Page built from LaTeX source using the texwiki program.