Release Notes for Version 22.8 (Aug 9th, 2022)

  • Release 22.8 contains a MOOS Release posted by P.Newman/Oxford July 5th, 2019.

New Applications


pRealm (new MOOS App)

  • The pRealm application is used for shadowing the local MOOSDB and generating on-demand RealmCast reports. These reports are requested and consumed by pMarineViewer or similar app configured to interact with pRealm. Typically pRealm is run on both the shoreside and vehicle communities. This is a major new tool to support large multi-vehicle swarm simulations and in-field deployments. It is also useful for debugging even the simplest missions for new developers.

uFldCollObDetect (new MOOS App)

  • The uFldCollObDetect application is run on the shoreside and maintains a current knowledge of all vehicle positions and obstacle locations and monitors for encounters between vehicles and obstacles that come within a certain range. The closest point of approach (CPA) is noted when the range between a vehicle to an obstacle transitions from closing to opening. Depending on the CPA value, one of three events may be declared, either an encounter, a near miss, or a collision, depending on user configured range parameters.

Modifications to Existing Applications


pHelmIvP

  • All behaviors may now designate themselves optionally as a "constraint" behavior, through the virtual function IvPBehavior::isConstraint() which by default returns false. Many of built-in helm behaviors are constraint behaviors, e.g., AvoidCollision, AvoidObstacle, MaxDepth. When the Helm detects a collection of IvP Functions consisting solely of a group of constraint behaviors, i.e., no goal behaviors like Waypoint, it will NOT publish any of the DESIRED_* values. If this happens only for one iteration, it will just quietly not post anything. If it persists for more than one iteration, it will produce an allstop. This was to handle cases where a mission would transition from one state to another via endflags/conditions, but during one transition iteration there would only be constraint behavior(s), which could produce a non-deterministicdesired_* posting for one iteration.
  • When behaviors post to BHV_EVENT, this is posted as any other variable, but now also will be posted in the AppCasting events of the pHelmIvP AppCast output. Behavior authors can use postEventMessage() or postRepeatableEventMessage(). Each function simply accepts a string but will also append on the beginning the behavior instance name.
  • Behaviors have a new virtual function checkParamCollective() which is called upon helm launch for each new behavior as it is built, including template behaviors. It allows the behavior author to have a function where the overall set of parameters is validated for correctness. Some behaviors have parameters that may each individually be OK, but taken together may be invalid. An example is say, min_range and max_range. In this function we can check that min_range is not more than max_range for example.

lib_ivp_core and lib_ivpbuild

  • IvPBox class: Added "plat" field to the IvPBox class to allow instances to be tagged upon creation in an IvP function as either plateau or basin pieces. This allows the IvPBuild Reflector tool to accept plateaus and basins from Refineries, and ensure that these pieces are not evaluated using the Regressor, but instead are just set to the min (basin) or max (plateau) values if the AOF is defined to support known min/max values.
  • Regressor: The regressor now looks for IvP pieces that were tagged as plateaus or basins and sets their weight directly if applicable.
  • OF_Reflector: The reflector, when accepting plateaus and basins from refineries, will now tag them as such, to allow the Regressor to handle them by setting their weights directly (instead of sampling)
  • BuildUtils: Added two useful utilities. The first, testRegionsApart() will test whether any pair of boxes, in a give vector of boxes, intersects one another. The second, makeRegionsApart() will take a given set of boxes and return a new set where any pair of boxes that intersected is replace by a set of non-intersecing boxes. Boxes of lower "plat magnitude" will be subtracted from boxes of higher plat magnitude. This a useful utility for designers of behavior refineries.
  • RT_UniformX: The UniformX regression tool has been augmented to check basins and plateaus, if they exist, to ensure they do not overlap. This should not really be the case if the users of the RT_UniformX tool have done their job correctly, but it is checked for here anyway and dealt with if need be, to ensure that a valid IPF is generated by this tool. An IPF is valid if each point in the decision space is contained by one and only one piece.

pContactMgrV20

  • A substantially improved contact manager has been given a new name to reflect its introduction with the 22.8 release. It is designed to be backward compatible to the previous contact manager but with enough changes that it deserves its own tag. And for V&V purposes it allows users upgrading to have the former contact manager while they verify a smooth transition.
  • Rendering of range circles has been made more efficient. In the mode where rendering is turned off, the contact manager was posting invisible circles on each iteration. This inefficiency has been fixed.
  • No longer registers and acts on CONTACT_RESOLVED mail. Previousl this needed to be posted by an alert consumer, like a collision avoidance behavior, to tell the contact manager that, should the contact come back in range, another alert needs to be generated. The contact manager now notes when a contact has gone out of cpa_range, and if it ever satisfies the alert criteria again, it posts a new alert. Typically a collision avoidance behavior is also configured to complete/die when the range is greater than the cpa_range.
  • The ontact_max_age default has been changed from 600 to 60 seconds
  • A new max_contacts parameter, set to 500 contacts
  • Added a general Exclusion Filter attached to alerts. The ExFilter class is part of bhvutil library and allows alerts to be configured to match or ignore based on contact group, name, type or position in a defined region.
  • An inclusion or exclusion region can now be associated per alert, or globally for the contact manager.
  • Documentation for this contact manager has been augmented and improved.
  • Improved support for getting information about the closest contact, how long it has been the closest contact and full ordered range report for all contacts.
  • Improved memory management and documentation. Ensures against unbounded growth of contacts and policy for dropping contacts is clarified.
  • Changed the option for visualizing alert ranges, to only publish range circles associate with one alert. This can be chosen by the user at startup, or dynamically switched at run time.

pMarineViewer

  • Major new augmentation to support RealmCasting, a powerful new tool for scoping on any app in a multi-vehicle mission. Clusters of variables can be configured to scope across multiple vehicles in a single table. This works in conjunction with a new app called pRealm, which requires no configuration and runs in each MOOS community. Toggling between appcasting and realmcasting is done with the 'a' key.
  • Augmented the GUI to accept up to twenty buttons for command poking, up from the previous limit of four buttons. Buttons and info fields will automatically resize to accommodate however many buttons are used.
  • Command buttons, when hovering with the mouse, will show what is being commanded upon a button click.
  • VPlug_GeoShapes class was modified to explicitly drop from memory shapes that arrive with active=false. Previously this would just result in the object being ignored, but not removed. This mod guards against unbounded memory growth in pMarineViewer in some longer missions.
  • VPlug_AppCastSettings in lib_geometry was replace with InfoCastSettings in lib_apputil. This class stores all the user preferences applicable to appcasting and realmcasting. The new class is also used by uMACView.
  • An additional variable, REGION_INFO, is published upon startup, and whenever a new vehicle has been detected. This info holds info about the background image, the zoom, the datum, and the pan x/y info. It is intended simply to be logged, and used by alogview upon startup to replicate the background image and orientation to be similar to how pMarineViewer was launched.
  • Points and circles now have support to publish with a duration, and once the duration has been exceeded with now new publication (keyed on label), the object will be dropped from memory.
  • Improved rapid drawing for large sets of Polygons
  • Fixed bug where text/labels for objects off screen would be rendered on screen, appended to other objects' text, rather than simply not being drawn.
  • New Option of ingesting NODE_REPORT info from uFldNodeComms as an intermediary. This enables smoother operation of pMarineViewer in missions with very high number of vehicles and very high time warp. Enabled with node_report_unc=true configuration. Of course must also be running uFldNodeComms.

uFldCollisionDetect

  • Added COLLISION_TOTAL and NEAR_MISS_TOTAL as standard output
  • Added ignore_group and reject_group options. Vehicles in a reject_group will have their node reports rejected on arrival. For vehicles in an ignore_group, encounters will be ignored if the both vehicles are in an ignore_group. Encounters where only one vehicle is in an ignore_group will be treated normally. The group of a vehicle is a field inside a NodeReport, and can be configured per vehicle inside pNodeReporter for a given vehicle.

uFldNodeComms

  • Added ability to control the node report share rate between vehicles, and thus also the rate of node pulses generated.
  • Added the node report share feature which will re-post node reports to NODE_REPORT_UNC, which allows pMarineViewer to ingest a filtered stream of node reports. This enables pMarineViewer to perform better in missions with very high number of vehicles and very high time warp.
  • Added config param to set pulse duration.
  • Added config param, ignore_group, to allow node reports to be ignored that match the specified group.
  • Added config param, msg_groups. If true, then messages between vehicles from different groups will be blocked.

alogview

  • Addressed a bug that could occur if the number of unique MOOS variable names is very large. Alogview, during this initial startup, splits the alog file into a directory of .klog files, one for each variable. During this split stage, the splitter creates a cache of open file pointers to speed the file I/O. Each OS has a max limit on open file pointers, and there may be some number of file pointers otherwise open in other apps. When alogview hits this limit, it may fail. A fix has been made to limit the file pointer cache to 100 elements. Further file pointers will be opened/closed for each write. This may slow the initial launch of alogview for alog files with many unique varnames.
  • alogview now has the ability to automatically start with the (a) background image, (b) zoom, and (c) pan x/y values used when starting with pMarineViewer. (See pMarineViewer also for a note on the addition to that app to support this feature). pMarineViewer posts the variable REGION_INFO which will be logged and read by alogview. Normally this variable is only published in the shoreside mission where pMarineViewer is running. Our recommendation is to bridge this variable to the vehicles as well so it will be in the vehicle log files. This way alogview will have this info if launched only with a vehicle alog file with no shoreside alog file.
  • Added support for AppLogging. Any AppCastingMOOSApp with app_logging enabled, can redirect its terminal output to APP_LOG postings. The terminal output can be viewed alongside playback in alogview.

aloggrep

  • Added the --final option, to output only the final line of the grep output, to the terminal. This allows aloggrep to be used testing/eval scripts.
  • Added the --finalx option, similar to --final, but it only outputs the value field of the log entry line.
  • Added the --finalz option, similar to --final, but it only outputs the timestamp field of the log entry line.
  • Added the -tvo options, similar to the --values_only option except that it will include the timestamp for each line, separated by a comma
  • Added the --format set of command-line options for converting alog data into Matlab or similar plottable format. This also includes calling out data embedded in a string such as INFO=speed=2.4,heading=128. The speed info for example can be extracted with the --subpat command line option.

Modifications to Existing Behaviors


BHV_Waypoint

  • Augmented the Waypoint behavior to support an update to the set of waypoints while holding the "current" waypoint index constant. This was motivated by a mission where the set of points are on a moving ice mass in the arctic.
  • Added the wptflag_on_start configurable flag, by default false. When set to true, it will post a normal wptflag when the behavior starts, as if its origin point is a waypoint.

BHV_AvoidObstacleV21

  • The V21 version is now the best performing and officially supported version of this behavior.
  • The AvoidObstacleV21 behavior uses the new XYPolyExpander class to build the buffer regions around the base obstacle.
  • Modified the AOF_AvoidObstacle class to evaluate maneuvers that intersect the obstacle, but do not intersect until after the allowable time to collision (allowable_ttc). The modification uses the overall min distance to the polygon, for any maneuver, and not the maneuver being evaluated. This creates a slightly more conservative evaluation and avoids the problem where a maneuver more toward the middle of the obstacle can be evaluated with a slightly higher utility.
  • Now supports the rng_flag and cpa_flag feature. The rng_flag is posted either continuously or only when ownship is within a specified range to the obstacle. The cpa_flag is posted upon each CPA encounter with the obstacle. This behavior also now supports a number of macros that may be expanded in these flags or all IvPBehavior flags.

BHV_AvoidCollision (two bug fixes)

  • The CPA Refinery was fixed to address an edge case situation that could briefly calculate an angle wrap-around in the wrong direction. When this happened it was most often when ownship was approaching behind the contact. Typically this calculation persisted for only an iteration or two, but in some cases longer.
  • Fixed a bug between the behavior and the contact manager that could result in the avoid collision behavior instantly retiring after initial spawning.
  • See also the changes made at the IvPContactBehavior superclass level.

BHV_AvdColregs and BHV_AvdColregsV19 (two bug fixes)

  • The CPA Refinery was fixed to address an edge case situation that could briefly calculate an angle wrap-around in the wrong direction. When this happened it was most often when ownship was approaching behind the contact. Typically this calculation persisted for only an iteration or two, but in some cases longer.
  • Fixed a bug between the behavior and the contact manager that could result in the avoid collision behavior instantly retiring after initial spawning.
  • See also the changes made at the IvPContactBehavior superclass level.

Modifications to the IvPBehavior Superclass

  • Added member info on whether the behavior was dynamically spawned, and the spawn basename. The helm, if dynamically spawning a behavior, will mark it as such. This allows the behavior implementation to perhaps do some things differently if wanted. For example, the obstacle avoidance behavior may be working with static obstacles known a priori and it may be working with obstacles detected dynamically via sensors.
  • Added configflag parameter. These flags are posted upon startup, when the behavior is configured, and any time a behavior update has been successfully made.
  • Added the postEventMessage() and postRepeatableEventMessage() functions available to all behaviors. They will result in a posting to the MOOS variable BHV_EVENT. These messages will also show up in the events portion of the pHelmIvP AppCasting output.

Modifications to the IvPContactBehavior Superclass

  • Expanded the number of match_groups and ignore_groups to be more than one. Now any arbitrary groups may be named.
  • Added a post_per_contact_info=true/false parameter that may generally used for any contact behavior. But in the case of AvoidCollision, AvdColregsV17, and AvdColregsV19, when false, it will disable per_contact info, such as posting RANGE_<CONTACT>. This kind of posting will create an unbounded number of MOOS variables in the DB as the number of unique contact names grow. This new parameter is set to false by default. So users of the above three behaviors may find that certain postings no longer happen unless they set post_per_contact_info=true.
  • Added cnflag to all contact behaviors. This flag posted on user defined events, such as entering with a given range, opening to a given range, or hitting the CPA range. Other events may be added such crossing the contact bow or crossing the contact beam.
  • Along with the cnflag, a number of MACROS are now available to all IvPContact behaviors for all flags. This include:
    CN_NAME: Name of the contact
    CN_VTYPE: Vehicle type of the contact
    CN_GROUP: Group name of the contact

    CN_STAR_OF_OS: Boolean true if the contact is on starboard side of ownship

    ROC: Rate of Closure to the contact
    RANGE: Range to the contact

    OS_CN_REL_BNG: Relative Bearing from ownship to the contact
    CN_OS_REL_BNG: Relative Bearing from the contact to ownship
    BNG_RATE: The Bearing rate between ownship and the contact

    OS_FORE_OF_CN: Boolean true if ownship is fore of contact
    OS_AFT_OF_CN: Boolean true if ownship is aft of contact
    OS_PORT_OF_CN: Boolean true if ownship is on port side of contact
    OS_STAR_OF_CN: Boolean true if ownship is on starboard side of contact

    CN_FORE_OF_OS: Boolean true if contact is fore of ownship
    CN_AFT_OF_OS: Boolean true if contact is aft of ownship
    CN_PORT_OF_OS: Boolean true if contact is on port side  of ownship
    CN_STAR_OF_OS: Boolean true if contact is on starboard side of ownship

Modifications to Libraries/Utilities


RefineryCPA (lib_bhvutil)(new utility)

The CPA refinery is a specialized tool for finding/building plateaus found in CPA based objective functions. The identification of plateaus is coupled with the new IvPBuild pipeline discussed below to support contact behaviors that reason about CPA. This includes at least for now, the AvoidCollision behavior as well as the AvdColregs behavior. The refinery is an optional opt-in parameter that will substantially reduce the number of pieces used in building an objective function for a behavior. Depending on the relative vehicle geometry, this can mean a reduction up to 90% of the pieces, and the corresponding savings on CPU time and log file size. This is accomplished with no loss of precision in the objective function.

The Geometry Library (lib_geometry)

  • (GeomUtils) Added the polyRayCPA() function to support the new style of evaluating maneuvers in the obstacle avoidance behavior.
  • (GeomUtils) Fixed bug in bearingMinMaxToPoly(). Erroneous results from certain cases have been fixed.
  • (GeomUtils) Added bearingMinMaxToPolyX() function which also calculates the distance from the given point to the two tangent points on the poly.
  • (GeomUtils) Added randPointOnPoly() function to support simulated lidar returns on a polygon, given a point relative to the polygon.
  • (AngleUtils) Added function for calculating the cross product of three points, to determine colinearity, or left/right turn.
  • (VPlug_GeoShapes class) was modified to explicitly drop from memory shapes that arrive with active=false. Previously this would just result in the object being ignored, but not removed. This mod guards against unbounded memory growth in pMarineViewer in some longer missions.
  • (VPlug_GeoShapes class) modified to support generic memory management of objects with duration.
  • Added XYPolyExpander class. In support of new style of obstacle avoidance although expanded obstacle polys are really only used for visualization.
  • Added XYPolygon area calculation algorithm to support new Voronoi functions.
  • (XYSegList class) Added bearingMinMaxToPolyX() function which also calculates the distance from the given point to the two tangent points on the poly.
  • (XYCircle class) Fixed a bug in one of the constructors that failed to initialize the duration, which could result in a zero duration and non-rendering of circle postings in pMarineViewer.
  • (XYSegList class) Added get_spec_inactive() utility function. This returns a trivially small spec, with bogus points, with just the active=false,label=value portion. This is used in cases where the spec is just being used to "erase" a previously generated spec sent to a viewer like pMarineViewer or alogview. It was motivated by a problem where some perfectly ok convex polygons, which were to be erased, were being rejected by the receiver because the serialization of the polygon rounded the vertex values just so slightly that the polygon was no longer convex and it was thus rejected by the viewer. In these cases, when active=false, the poly is simply to be ignored (replacing a previously active poly). So the points are extra information anyway.
  • (XYPolygon class) Added add_vertex_delta() function which allows a new vertex addition to be rejected if the new vertex is with a given threshold of the previously added vertex. This is a utility used in the XYPolyExpander utility.
  • Added a min_xproduct() function to identify a vertex with the minimum cross product w.r.t. the point on either side. This enables a heuristic for dropping colinear points in a polygon that may prevent the polygon from confirming convexity.
  • (XYObject class) duration for all geo shapes. With general support for an expiration test. This enables easy implementation in pMarineViewer to drop objects from memory after they expire. Makes memory management easier for apps publishing ephemeral artifacts since they don't have to reason about posting an erase (active=false) message.
  • (ConvexHullGenerator class) Substantial improvements in edge case handling especially on the issue of colinear points. It also will now generate a more reasonable response for cases with two vertices, or even one vertex.
  • Fixed a bug in the segRayCPA() function that didn't account for rays with an origin with the segment pointing away.
  • VPlug_AppCastSettings in lib_geometry was replace with InfoCastSettings in lib_apputil.

New Command Line Utilities


mtop.sh (new utility script)

  • This script is a convenience script for launching top for monitoring MOOS apps. The primary launch mode (no args, will look for all Antler processes, and find all child processes. It may also be configured to run on only a given set of apps named by the caller. It can be found in moos-ivp/scripts (which needs to be in the user's shell path).