Ocpn-Draw and Boundary

[rgleason]

Jon, how dare you try to rewire my brain!

I've got to get a handle on this and it might take a couple of days.
Is this intuitive? At this point I don't know, but I am certainly glad I don't have to describe this to my grandmother! I think she'd do better with semaphore.

Boundary types in Watchdog are used to filter the messages coming back.

- So Watchdog knows or can discover a Boundary's "type" .
- Watch dog sends a message back to Draw based on the "type" selected.
- What is the message?

At the moment the first boundary found when using Distance or Time will be returned. I am trying to work out how to do, sensibly, multiple boundaries.

- It must be the first boundary found that matches the "type" selected.

The watchdog "types" that are returned are:

1. Exclusive=keep out is returned
2. Inclusive=keep in is returned
3. Neither =not Exclusive or Inclusive just a boundary line is returned
4. Any =does not care what type of boundary is returned. Any boundary is returned.

Watchdog and OD communicate through JSON messages.

There is no link between Watchdog and OD except through the JSON messages.
- OD knows what type of boundaries it is controlling, but has no interest in alarms.
- Watchdog knows nothing of boundaries or their properties just that a lat/lon exists inside or outside a boundary and what the type of boundary is.

The OD boundary type only determines where the fill is drawn, i.e. inside, outside or not at all. There is no further meaning applied. It is really up to the user to determine how they would like the boundary drawn and then if they want to use Watchdog, what type of boundary to alarm on.

--------

Okay, so how would I set up a boundary with an appropriate alarm (as my mind is wired)?

In ODraw ---> Purple Boundary Inclusive, 10 points.
In Watchdog ---> An alarm when OwnShip GPS position moves out of boundary.

Set the Watchdog Boundary Type Return Selector to "Inclusive"
Set the Anchor Radio button and make sure that the proper GUID is found
4cb7ffff-2b44-4e1e-ae7d-e3291c4f0000

So now the correct ODraw object is being used for an Anchor alarm.

--- Ok, this works.
---------

At present, we can only setup Watchdog for this one Alarm?

[rgleason]

2nd Alarm in Watchdog

Use ODraw Orange Boundary Point / Ring Inclusive 6036ffff-7838-4444-8c59-01a26311ffff

Set the Watchdog Boundary Type Return Selector to "Inclusive"
Set the Anchor Radio button and make sure that the proper GUID is found
7838-4444-8c59-01a26311ffff

So now the Orange Boundary Point / Ring Inclusive is being used for an Anchor alarm.

---It works.

[rgleason]

Change 2nd Watchdog Alarm

Set the Watchdog Boundary Type Return Selector to "Inclusive"
Move the Radio button from "anchor" and pick "GPS fix is < 0.010000 nm from boundary (in any direction)."

and make sure that the proper GUID is found
7838-4444-8c59-01a26311ffff

So now the Orange Boundary Point / Ring Inclusive is being used for a GPS fix is < 0.010000 nm from boundary (in any direction)."

Now this alarm is messed up according to the way my brain is wired.
It alarms when OwnShip is inside and does not alarm when OwnShip is outside!

In fact, if OwnShip is moved just outside the Inclusive Boundary it alarms because it is <0.01nm away from the boundary.
Why is the alarm working as a "KEEP OUT" rather than "KEEP IN" alarm as it should?

I believe Watchdog is not returning the right "inclusive" instructions regarding the boundary.

[rgleason]

Jon, I think I understand some of the problem (but just the edge of it).

It would be nice if when in Watchdog we could set up a boundary alarm as follows:

1. Pick a Boundary object in the display by clicking on it. Have the GUID and Name come up.

2. Have the type of alarm be determined by the OD graphic type of boundary. Inclusive, Exclusive, Boundary only.

3. Be able to assign the following Alarm conditions to the boundary:

A. OwnShip GPS location
B. OwnShip GPS distance from
C. OtherShip AIS location
D. OtherShip AIS distance from
(Maybe for this it does not matter if the anchor is down or not, just that the ships have gps on.)

=====

Is there some better, easier to program way to do it that users would understand easily?

[jongough]

Rick,
Use the KISS principle. OD just does drawings, it will respond to certain JSON messages (currently only Watchdog is using them) to return information about an object. There are three JSON messages that OD will respond too:

1. Version
2. FindPointInAnyBoundary
3. FindPointInBoundary

The message needs to be in a specific format to get the response you need. As the response is broadcast to all plugins and OCPN the response message contains information about the originating message so that the two can be tied together.

Now, each of these messages will be responded to with the following information which is unique to each message:

1. Version
   • Major - Major version number
   • Minor - Minor version number
   • Patch - Patch version number
   • Date - Date this version was last changed
2. FindPointInAnyBoundary
   • GUID - the GUID of the found boundary
   • Name - The name the user supplied in the properties box
   • Description - The description the user supplied in the properties box
   • Found - true if lat/lon found in any boundary
   • BoundaryObjectType - one of:
     • Boundary
     • Boundary Point
   • BoundaryType - one of:
     • Exclusion
     • Inclusion
     • Neither
     • Unknown - catchall in case something has gone terribly wrong
3. FindPointInBoundary
   • GUID - the supplied GUID
   • Found - true if lat/long found in specific boundary (specified by the GUID)
   • BoundaryObjectType - one of:
     • Boundary
     • Boundary Point
   • BoundaryType - one of:
     • Exclusion
     • Inclusion
     • Neither
     • Unknown - catchall in case something has gone terribly wrong

There may be a need to extend this if arrays/lists of boundaries are needed.

The Watchdog plugin makes use of this information to allow the creation of various simple watches. Currently there are three:

1. Distance from any boundary
2. Time from any boundary
3. Anchor alarm

The first two look for any boundary on a circle at the given 'distance' from the boat. The first boundary found will be returned. It starts at North and moves clockwise around the boat in 1 degree intervals, a check is done at each degree to see if the lat/lon of that point is in a boundary.
If a lat/lon is found in a boundary then a filter of BoundaryType will be used. If the found boundary is filtered out then the process continues with the next point. If boundary is not filtered out then the process stops and the alarm is sounded.

The anchor alarm looks for the current lat/lon of the boat in a specific boundary, the one defined by the GUID. Either the boat is within the boundary or it is not in the boundary. If it is not in the boundary then an alarm is triggered.

So, there should be true separation of purpose between the two plugins. OD just does drawings, Watchdog just does alarms.

If an array/list of boundaries is reported back to the watchdog, then the alarm/display of these may get difficult. If you want multiple alarms, aka the discussion with 3 overlapping boundaries it may be better to make them not overlap. The each of the boundaries can have an alarm set based on whether the boat is in or out of a boundary. The anchor alarm, because it is based of free drawn boundaries is not constrained like the other boundary alarm (distance from a specific lat/lon), so you have have an irregular shaped boundary that defines the true safe anchorage area. Then if you move out of that the alarm will sound.

Hope this helps.

Jon

[jongough]

Rick,
Just in case you though I had forgotten. The 'Get GUID' button uses the 'FindPointInAnyBoundary' to populate the field. Reuse, a wonderful thing!

Jon

[rgleason]

Jon,
This description is very helpful. You have managed to rewire my brain insofar as OD / Watchdog.

1. OD creates Graphical Boundary objects and stores them in the ODnavobj.xml file.
2. Watchdog does not have access to this file and cannot query it directly, nor can it change anything in it directly. (I thought OD and Watchdog shared the ODnavobj.xml file. -There must be some reason that can't happen. Two controllers cannot be accessing the file at the same time? Collisions)
3. OD and Watchdog do not share and work out of a common database; they communicate with each other.
4. OD and Watchdog communicate information using several OD functions (Version, FindPointInAnyBoundary, FindPointInBoundary) where Watchdog sends a specific query to OD and OD answers with the information needed. Watchdog then uses that information to either Set, Query for or Make an alarm.
5. The OD functions must be supported by the Plugin API (external variable) to enable the communication pathway for that particular data. Adding any additional shared OD-Watchdog information exchange requires changing the Plugin API.
6. Watchdog alarms require a timed query to OD and a response back in order to check conditions on the particular Alarm.

Please correct or elaborate. Thanks.

Next Question: Relates to how this system actually works. How do we make the use of the Watchdog Interface clearer to users?

[rgleason]

Watchdog has 3 simple alerts:

1. Distance from any boundary
2. Time from any boundary
3. Anchor alarm

Get GUID' button uses the 'FindPointInAnyBoundary' to populate the field.

FindPointInAnyBoundary
Found - true if lat/lon found in any boundary
FindPointInBoundary
Found - true if lat/long found in specific boundary (specified by the GUID)

1. FindpointInAnyBoundary returns the first boundary found.
2. To be sure that Get GUID returns the correct boundary the boat has to be inside the boundary. If the boat is inside two boundaries the correct GUID may not be returned.

I think we need these parameters so that Watchdog can query successive boundaries and make a small table of Boundaries available with Guid - Name that can be picked by the user.
[Tag] On/Off - Tag "on" means boundary already found, continue searching.
[TagReset] Start over Reset all tags to off. It would normally be 'false' and would return to Watchdog as 'true' if the function no longer found boundaries with Tag=off, signaling all boundaries had been checked.
--This is just an idea, I don't know the best way to do this. Are there some other parameters needed?

These would have to be stored in ODnavobj.xml

[jongough]

Rick,

Originally Posted by rgleason

.....

1. OD creates Graphical Boundary objects and stores them in the ODnavobj.xml file.

Not quite. At the time the object is created it is stored in the ODnavobj.xml.changes file. The ODnavobj.xml file is only written when OCPN is closed down. This allows the ODnavobj.xml file to conatain the 'current' state of all objects across restarts. The ODnavobj.xml.changes contains ALL changes made to objects during an OCPN session. If OCPN closes sucessfully, the changes file is deleted as the main file is complete. If OCPN does not close successfully the changes file is applied after the main file is processed, and, hopefully, the state is the same as when OCPN terminated.

2. Watchdog does not have access to this file and cannot query it directly, nor can it change anything in it directly. (I thought OD and Watchdog shared the ODnavobj.xml file. -There must be some reason that can't happen. Two controllers cannot be accessing the file at the same time? Collisions)

Watchdog can have read access to these files, but then you would need much more of OD inside Watchdog to make sense of them.
The files in use that are relevant to this discussion:

OCPN - navobj.xml & navobj.xml.changes
OD - ODnavobj.xml & ODnavobj.xml.changes
Watchdog - WatchdogConfiguration.xml

The OCPN files contain standard 'gpx' definitions of objects so that they can be moved/copied between devices. i.e. routes, tracks, etc.
The OD files are use the same format, but generally have an 'opencpn' extension applied, as the items would not be understood by any other application.
The Watchdog file, whilst xml, is its own format and quite different to the above.

3. OD and Watchdog do not share and work out of a common database; they communicate with each other.

True

4. OD and Watchdog communicate information using several OD functions (Version, FindPointInAnyBoundary, FindPointInBoundary) where Watchdog sends a specific query to OD and OD answers with the information needed. Watchdog then uses that information to either Set, Query for or Make an alarm.

1. The OD functions must be supported by the Plugin API (external variable) to enable the communication pathway for that particular data. Adding any additional shared OD-Watchdog information exchange requires changing the Plugin API.
2. Watchdog alarms require a timed query to OD and a response back in order to check conditions on the particular Alarm.

Please correct or elaborate. Thanks.

Sort of. The communications inside OCPN between various functions/plugins is via JSON messages. These are text messages, like SMS, that have a special format. The content of the messages is totally up to the users. By using a message rather than an API it is much quicker to change and requires no changes to the underlaying code which would need to support an API.

So, the JSON message, for the OD/Watchdog communications uses some specific 'labels' to make the comms easier. In the explanation I gave before I only mentioned the 'labels'/'values' that were of interest for the information requested/returned. At the moment there is no 'standard' message content for OCPN (it acts as the message handler, all messages pass through OCPN), but perhaps, if we continue to expand the use of messages there should be.

To add new messages or content only requires adding a few lines of code to handle the 'label'/'value' pairs and, if needed, some validation that the required information has been passed.

Watchdog already has a timer in it that tests the alarm conditions once a second. Each time this is done the boundary alarms, if active, will send the requisite message to OD and get an immediate response (this is synchronous messaging, which is a bit heavy handed, but....). I suspect that if/when we implement 'Guard Zones' (and/or AIS Watchdog-OD alarms) this may become overloaded, particularly if there are thousands of AIS targets (there is a discussion on this with changes to scaling to help understand the data being presented).

Next Question: Relates to how this system actually works. How do we make the use of the Watchdog Interface clearer to users?

Hmmm. To me it is quite clear, but then I did do the code and I may have a warped mind! But I think if we make it clear that OD does drawing and Watchdog does alarms and that is all each does. Then use OD to draw objects and applying a logical type (Exclusion/Inclusion/Neither/etc) to change the way they are shown. The user can then use Watchdog to find and alarm upon certain uses of these logical types.

About as clear as muddy water, I know. I suppose it is a bit like WMM, where it supplies the magnetic variation to OCPN, but it is up to OCPN what it does with it, i.e. magnetic COG, magnetic wind directions, etc. WMM does not care how the information is used, and the dashboard does not care how the magnetic variation is found.

Jon

[jongough]

Rick,
I think you are really asking for another message, 'FindPointInAllBoundaries' which will return a list of boundaries that have that point inside. This is simple for OD to do, but makes Watchdog more complicated and will need extra screens and handling which is not really there at the moment. I will have a look and see what can be done, but Sean may not be keen as it could 'muddy' the current Watchdog code.

There would be no changes to the stored data. Neither ODnavobj.xml(.changes) nor WatchdogConfiguration.xml would change as each alarm would still be the same as it is now, just the method of choosing the boundary would change.

Jon

Originally Posted by rgleason

Watchdog has 3 simple alerts:

1. Distance from any boundary
2. Time from any boundary
3. Anchor alarm

FindPointInAnyBoundary
Found - true if lat/lon found in any boundary
FindPointInBoundary
Found - true if lat/long found in specific boundary (specified by the GUID)

1. FindpointInAnyBoundary returns the first boundary found.
2. To be sure that Get GUID returns the correct boundary the boat has to be inside the boundary. If the boat is inside two boundaries the correct GUID may not be returned.

I think we need these parameters so that Watchdog can query successive boundaries and make a small table of Boundaries available with Guid - Name that can be picked by the user.
[Tag] On/Off - Tag "on" means boundary already found, continue searching.
[TagReset] Start over Reset all tags to off. It would normally be 'false' and would return to Watchdog as 'true' if the function no longer found boundaries with Tag=off, signaling all boundaries had been checked.
--This is just an idea, I don't know the best way to do this. Are there some other parameters needed?

These would have to be stored in ODnavobj.xml

[rgleason]

Jon, I am just trying to understand. Do do anything on account of me right now. I should understand it all better first.

[rgleason]

Thanks for taking the time to explain . I will digest it. May have a couple of other questions later.

[jongough]

Rick,
To make getting the GUID easier you will now find a 'Copy xxx GUID' on the right click popup of all OD objects. You can then use this to paste into the Watchdog plugin guid box (or paste it anywhere else for that matter). This is in patch 587.

Jon

[rgleason]

Git fetch is 2170e8d #146 which is #586.
So the right click GUID selection does not appear.

I have uploaded a very recent new version of Opencpn and OD plugin.
Also I've consolidated the most current plugins into 4.1.1108 PI Win.

[rgleason]

I just tried setting two overlapping Boundary Inclusive Alarms.
OwnShip placed in one of the Boundaries and not in the other.
There is an immediate alarm for both boundaries.

This does not seem right to me.
Should we force a limit to the number of anchor boundaries to just one?