colregs 0.1.0

package/data/facts.json

@@ -0,0 +1,308 @@
+{
+ "note": "The fact record a consumer evaluates applicability predicates against. Three orthogonal axes plus scalars; there is no separate COLREGS vessel-class field, because under COLREGS what a vessel is follows from what it is doing.",
+ "axes": {
+  "propulsion": {
+   "values": [
+    "power",
+    "sail",
+    "oars"
+   ],
+   "cites": {
+    "power": "3(b)",
+    "sail": "3(c)",
+    "oars": "25(d)(ii)"
+   },
+   "note": "A vessel under sail with propelling machinery in use is 'power' (Rule 3(c)); the 25(e) day shape is the only trace motorsailing leaves at night."
+  },
+  "activity": {
+   "values": [
+    "none",
+    "fishing",
+    "trawling",
+    "towing",
+    "pushing",
+    "being_towed",
+    "nuc",
+    "ram",
+    "ram_underwater",
+    "cbd",
+    "mine",
+    "pilot",
+    "diving"
+   ],
+   "cites": {
+    "fishing": "3(d)",
+    "trawling": "26(b)",
+    "nuc": "3(f)",
+    "ram": "3(g)",
+    "ram_underwater": "27(d)",
+    "cbd": "3(h)",
+    "mine": "27(f)",
+    "pilot": "29(a)",
+    "diving": "27(e)",
+    "towing": "24(a)",
+    "pushing": "24(b)",
+    "being_towed": "24(e)"
+   },
+   "note": "'ram_underwater' is a vessel restricted in her ability to maneuver that is dredging or engaged in underwater operations (27(d)); it is a refinement of 'ram', not a peer of it, and predicates written for 'ram' also read it."
+  },
+  "position": {
+   "values": [
+    "underway",
+    "anchored",
+    "aground",
+    "moored"
+   ],
+   "cites": {
+    "underway": "3(i)"
+   },
+   "note": "Rule 3(i): underway means not at anchor, not made fast to the shore, not aground."
+  }
+ },
+ "modifiers": {
+  "making_way": {
+   "type": "boolean",
+   "refines": "position=underway",
+   "note": "Undefined in the Rules; it means moving through the water. Underway but not making way is free drifting. Only the 26/27-family predicates read it (26(b)(iii), 26(c)(iii), 27(a)(iii), 27(b)(iii)); Rules 23 and 25 gate on 'underway' alone, so a power-driven vessel drifting in neutral still shows full running lights.",
+   "actuable": true
+  }
+ },
+ "numerics": {
+  "length_m": {
+   "type": "number",
+   "unit": "m",
+   "cite": "3(j)",
+   "note": "Length overall. COLREGS thresholds are 7, 12, 20, 50 and 100 m.",
+   "actuable": true,
+   "signalk": "design.length.value.overall"
+  },
+  "tow_length_m": {
+   "type": "number",
+   "unit": "m",
+   "cite": "24(a)(i)",
+   "note": "From the stern of the towing vessel to the after end of the tow.",
+   "actuable": true,
+   "signalk": null
+  },
+  "max_speed_kn": {
+   "type": "number",
+   "unit": "kn",
+   "cite": "23(d)(ii)",
+   "note": "Read only by 23(d)(ii). No SignalK path publishes it; design.maxSpeed does not exist in the schema. Kept because the rule has it.",
+   "actuable": true,
+   "signalk": null
+  },
+  "gear_extent_m": {
+   "type": "number",
+   "unit": "m",
+   "cite": "26(c)(ii)",
+   "actuable": false,
+   "signalk": null
+  },
+  "beam_m": {
+   "type": "number",
+   "unit": "m",
+   "cite": "24(g)",
+   "actuable": false,
+   "signalk": "design.beam.value"
+  }
+ },
+ "booleans": {
+  "composite_unit": {
+   "cite": "24(b)",
+   "actuable": false
+  },
+  "non_displacement": {
+   "cite": "23(b)",
+   "actuable": false,
+   "note": "Air-cushion vessel operating in non-displacement mode."
+  },
+  "wig": {
+   "cite": "23(c)",
+   "actuable": false
+  },
+  "near_channel": {
+   "cite": "30(e)",
+   "actuable": false,
+   "note": "At anchor in or near a narrow channel, fairway, or where other vessels normally navigate."
+  },
+  "inconspicuous_partly_submerged_tow": {
+   "cite": "24(g)",
+   "actuable": false
+  },
+  "towed_alongside": {
+   "cite": "24(c)",
+   "actuable": false
+  },
+  "obstruction_exists": {
+   "cite": "27(d)",
+   "actuable": false
+  }
+ },
+ "enums": {
+  "obstruction_side": {
+   "values": [
+    "port",
+    "starboard"
+   ],
+   "cite": "27(d)(i)",
+   "actuable": false
+  }
+ },
+ "actuable_subset": {
+  "note": "What a switching consumer needs and can get: the three axes (decodable from navigation.state), making_way, and length_m. Everything else is education-side.",
+  "fields": [
+   "propulsion",
+   "activity",
+   "position",
+   "making_way",
+   "length_m"
+  ]
+ },
+ "signalk_navigation_state": {
+  "source": "@signalk/signalk-schema schemas/groups/navigation.json (state.value.enum)",
+  "verified": "2026-08-29",
+  "decode": {
+   "not under command": {
+    "activity": "nuc",
+    "position": "underway"
+   },
+   "anchored": {
+    "activity": "none",
+    "position": "anchored"
+   },
+   "moored": {
+    "activity": "none",
+    "position": "moored"
+   },
+   "sailing": {
+    "propulsion": "sail",
+    "activity": "none",
+    "position": "underway"
+   },
+   "motoring": {
+    "propulsion": "power",
+    "activity": "none",
+    "position": "underway"
+   },
+   "towing < 200m": {
+    "propulsion": "power",
+    "activity": "towing",
+    "position": "underway",
+    "tow_length_m": {
+     "lte": 200
+    }
+   },
+   "towing > 200m": {
+    "propulsion": "power",
+    "activity": "towing",
+    "position": "underway",
+    "tow_length_m": {
+     "gt": 200
+    }
+   },
+   "pushing": {
+    "propulsion": "power",
+    "activity": "pushing",
+    "position": "underway"
+   },
+   "fishing": {
+    "activity": "fishing",
+    "position": "underway"
+   },
+   "fishing-hampered": {
+    "activity": "fishing",
+    "position": "underway",
+    "annex_ii_signal": "purse_seine_hampered"
+   },
+   "trawling": {
+    "activity": "trawling",
+    "position": "underway"
+   },
+   "trawling-shooting": {
+    "activity": "trawling",
+    "position": "underway",
+    "annex_ii_signal": "shooting"
+   },
+   "trawling-hauling": {
+    "activity": "trawling",
+    "position": "underway",
+    "annex_ii_signal": "hauling"
+   },
+   "pilotage": {
+    "activity": "pilot"
+   },
+   "not-under-way": {},
+   "aground": {
+    "activity": "none",
+    "position": "aground"
+   },
+   "restricted manouverability": {
+    "activity": "ram"
+   },
+   "restricted manouverability towing < 200m": {
+    "propulsion": "power",
+    "activity": "ram",
+    "also_activity": "towing",
+    "tow_length_m": {
+     "lte": 200
+    }
+   },
+   "restricted manouverability towing > 200m": {
+    "propulsion": "power",
+    "activity": "ram",
+    "also_activity": "towing",
+    "tow_length_m": {
+     "gt": 200
+    }
+   },
+   "restricted manouverability underwater operations": {
+    "activity": "ram_underwater"
+   },
+   "constrained by draft": {
+    "propulsion": "power",
+    "activity": "cbd",
+    "position": "underway"
+   },
+   "mine clearance": {
+    "activity": "mine"
+   }
+  },
+  "undecodable": [
+   "Reserved for future amendment of Navigational Status for HSC",
+   "Reserved for future amendment of Navigational Status for WIG",
+   "Reserved for future use-11",
+   "Reserved for future use-12",
+   "Reserved for future use-13",
+   "Reserved for future use-14",
+   "not defined (example)"
+  ],
+  "lossy": [
+   {
+    "what": "fishing or trawling at anchor",
+    "why": "Rule 26(a) applies 'whether underway or at anchor', but 'fishing' and 'anchored' are mutually exclusive values of one flat enum, so the pair cannot be stated.",
+    "cite": "26(a)"
+   },
+   {
+    "what": "making way vs. underway-but-not-making-way",
+    "why": "No enum value distinguishes them, and no SignalK path carries the boolean. 26(b)(iii), 26(c)(iii), 27(a)(iii) and 27(b)(iii) all turn on it.",
+    "cite": "27(a)(i) vs 27(a)(iii)"
+   },
+   {
+    "what": "pilotage underway vs. at anchor",
+    "why": "'pilotage' fixes activity but says nothing about position; 29(a)(ii) and 29(a)(iii) prescribe different lights.",
+    "cite": "29(a)"
+   },
+   {
+    "what": "not-under-way",
+    "why": "Decodes to no axis at all: it excludes 'underway' but does not say which of anchored, moored or aground holds.",
+    "cite": "3(i)"
+   },
+   {
+    "what": "vessel or object being towed, and diving",
+    "why": "No enum value exists for either; 24(e) and 27(e) are unreachable from navigation.state.",
+    "cite": "24(e), 27(e)"
+   }
+  ]
+ }
+}

package/data/geometry.json

@@ -0,0 +1,372 @@
+{
+ "ruleset": "international",
+ "source": "Annex I - Positioning and Technical Details of Lights and Shapes (33 CFR 84), International text",
+ "note": "The structured half of the image payload: where each light sits and what it looks like, so a renderer can draw a configuration instead of picking a scan. Bearing arcs live in lights.json; this file carries heights, spacings, colour and intensity.",
+ "vertical_positioning": [
+  {
+   "cite": "AnxI.2(a)(i)",
+   "light": "masthead",
+   "which": "forward (or the only one)",
+   "when": {
+    "propulsion": "power",
+    "length_m": {
+     "gte": 20
+    }
+   },
+   "datum": "hull",
+   "min_m": 6,
+   "max_m": 12,
+   "also": "if the breadth of the vessel exceeds 6 m, not less than that breadth",
+   "text": "The forward masthead light, or if only one masthead light is carried, then that light, at a height above the hull of not less than 6 meters, and, if the breadth of the vessel exceeds 6 meters, then at a height above the hull not less than such breadth, so however that the light need not be placed at a greater height above the hull than 12 meters."
+  },
+  {
+   "cite": "AnxI.2(a)(ii)",
+   "light": "masthead",
+   "which": "after",
+   "when": {
+    "propulsion": "power",
+    "length_m": {
+     "gte": 20
+    }
+   },
+   "datum": "forward masthead light",
+   "min_m": 4.5,
+   "text": "when two masthead lights are carried the after one shall be at least 4.5 meters vertically higher than the forward one."
+  },
+  {
+   "cite": "AnxI.2(b)",
+   "light": "masthead",
+   "constraint": "separation",
+   "text": "The vertical separation of the masthead lights of power-driven vessels shall be such that in all normal conditions of trim the after light will be seen over and separate from the forward light at a distance of 1000 meters from the stem when viewed from sea level."
+  },
+  {
+   "cite": "AnxI.2(c)",
+   "light": "masthead",
+   "when": {
+    "propulsion": "power",
+    "length_m": {
+     "gte": 12,
+     "lt": 20
+    }
+   },
+   "datum": "gunwale",
+   "min_m": 2.5,
+   "text": "The masthead light of a power-driven vessel of 12 meters but less than 20 meters in length shall be placed at a height above the gunwale of not less than 2.5 meters."
+  },
+  {
+   "cite": "AnxI.2(d)",
+   "light": "masthead",
+   "when": {
+    "propulsion": "power",
+    "length_m": {
+     "lt": 12
+    }
+   },
+   "datum": "gunwale",
+   "min_m": null,
+   "also": "when a masthead light, or the 23(d)(i) all-round light, is carried in addition to sidelights, it shall be at least 1 m higher than the sidelights",
+   "datum_secondary": "sidelights",
+   "min_above_sidelights_m": 1,
+   "text": "A power-driven vessel of less than 12 meters in length may carry the uppermost light at a height of less than 2.5 meters above the gunwale. When, however, a masthead light is carried in addition to sidelights and a sternlight or the all-round light prescribed in Rule 23(d)(i) is carried in addition to sidelights, then such masthead light or all-round light shall be carried at least 1 meter higher than the sidelights."
+  },
+  {
+   "cite": "AnxI.2(e)",
+   "light": "masthead",
+   "when": {
+    "activity": [
+     "towing",
+     "pushing"
+    ]
+   },
+   "datum": "forward masthead light",
+   "min_m": 4.5,
+   "text": "One of the two or three masthead lights prescribed for a power-driven vessel when engaged in towing or pushing another vessel shall be placed in the same position as either the forward masthead light or the after masthead light, provided that, if carried on the after mast, the lowest after masthead light shall be at least 4.5 meters vertically higher than the forward masthead light."
+  },
+  {
+   "cite": "AnxI.2(f)(i)",
+   "light": "masthead",
+   "constraint": "clearance",
+   "text": "The masthead lights or lights prescribed in Rule 23(a) shall be so placed as to be above and clear of all other lights and obstructions except as described in paragraph (f)(ii)."
+  },
+  {
+   "cite": "AnxI.2(f)(ii)",
+   "light": "all_round",
+   "applies_to_entries": [
+    "27b-id",
+    "28"
+   ],
+   "text": "When it is impracticable to carry the all-round lights prescribed by Rule 27(b)(i) or Rule 28 below the masthead lights, they may be carried above the after masthead light(s) or vertically in between the forward masthead light(s) and after masthead light(s), provided that in the latter case the requirement of paragraph 3(c) shall be complied with."
+  },
+  {
+   "cite": "AnxI.2(g)",
+   "light": "sidelights",
+   "when": {
+    "propulsion": "power"
+   },
+   "datum": "forward masthead light",
+   "max_fraction_of_masthead_height": 0.75,
+   "text": "The sidelights of a power-driven vessel shall be placed at a height above the hull not greater than three quarters of that of the forward masthead light. They shall not be so low as to be interfered with by deck lights."
+  },
+  {
+   "cite": "AnxI.2(h)",
+   "light": "sidelights",
+   "combined": true,
+   "when": {
+    "propulsion": "power",
+    "length_m": {
+     "lt": 20
+    }
+   },
+   "datum": "masthead light",
+   "min_below_m": 1,
+   "text": "The sidelights, if in a combined lantern and carried on a power-driven vessel of less than 20 meters in length, shall be placed not less than 1 meter below the masthead light."
+  },
+  {
+   "cite": "AnxI.2(i)(i)",
+   "constraint": "vertical line spacing",
+   "when": {
+    "length_m": {
+     "gte": 20
+    }
+   },
+   "min_spacing_m": 2,
+   "lowest_light": {
+    "datum": "hull",
+    "min_m": 4,
+    "except": "where a towing light is required"
+   },
+   "text": "On a vessel of 20 meters in length or more such lights shall be spaced not less than 2 meters apart, and the lowest of these lights shall, except where a towing light is required, be placed at a height of not less than 4 meters above the hull."
+  },
+  {
+   "cite": "AnxI.2(i)(ii)",
+   "constraint": "vertical line spacing",
+   "when": {
+    "length_m": {
+     "lt": 20
+    }
+   },
+   "min_spacing_m": 1,
+   "lowest_light": {
+    "datum": "gunwale",
+    "min_m": 2,
+    "except": "where a towing light is required"
+   },
+   "text": "On a vessel of less than 20 meters in length such lights shall be spaced not less than 1 meter apart and the lowest of these lights shall, except where a towing light is required, be placed at a height of not less than 2 meters above the gunwale."
+  },
+  {
+   "cite": "AnxI.2(i)(iii)",
+   "constraint": "vertical line spacing",
+   "equal_spacing": true,
+   "text": "When three lights are carried they shall be equally spaced."
+  },
+  {
+   "cite": "AnxI.2(j)",
+   "applies_to_entries": [
+    "26b-id",
+    "26c-id"
+   ],
+   "datum": "sidelights",
+   "min_multiple_of_pair_spacing": 2,
+   "text": "The lower of the two all-round lights prescribed for a vessel when engaged in fishing shall be at a height above the sidelights not less than twice the distance between the two vertical lights."
+  },
+  {
+   "cite": "AnxI.2(k)",
+   "applies_to_entries": [
+    "30a"
+   ],
+   "datum": "after anchor light",
+   "min_m": 4.5,
+   "also": {
+    "when": {
+     "length_m": {
+      "gte": 50
+     }
+    },
+    "datum": "hull",
+    "min_m": 6
+   },
+   "text": "The forward anchor light prescribed in Rule 30(a)(i), when two are carried, shall not be less than 4.5 meters above the after one. On a vessel of 50 meters or more in length this forward anchor light shall be placed at a height of not less than 6 meters above the hull."
+  }
+ ],
+ "horizontal_positioning": [
+  {
+   "cite": "AnxI.3(a)",
+   "light": "masthead",
+   "constraint": "separation",
+   "min_fraction_of_length": 0.25,
+   "need_not_exceed_m": 50,
+   "forward_light_max_fraction_of_length_from_stem": 0.5,
+   "text": "Except as specified in paragraph (e), when two masthead lights are prescribed for a power-driven vessel, the horizontal distance between them shall not be less than one quarter of the length of the vessel but need not be more than 50 meters. The forward light shall be placed not more than one half of the length of the vessel from the stem."
+  },
+  {
+   "cite": "AnxI.3(b)",
+   "light": "sidelights",
+   "when": {
+    "propulsion": "power",
+    "length_m": {
+     "gte": 20
+    }
+   },
+   "text": "On a power-driven vessel of 20 meters or more in length the sidelights shall not be placed in front of the forward masthead lights. They shall be placed at or near the side of the vessel."
+  },
+  {
+   "cite": "AnxI.3(c)",
+   "applies_to_entries": [
+    "27b-id"
+   ],
+   "min_offset_from_centerline_m": 2,
+   "text": "When the lights prescribed in Rule 27(b)(i) are placed vertically between the forward masthead light(s) and the after masthead light(s), these all-round lights shall be placed at a horizontal distance of not less than 2 meters from the fore and aft centerline of the vessel in the athwartship direction."
+  },
+  {
+   "cite": "AnxI.3(d)",
+   "light": "masthead",
+   "text": "When only one masthead light is prescribed for a power-driven vessel, this light shall be exhibited forward of amidships. For a vessel of less than 20 meters in length, the vessel shall exhibit one masthead light as far forward as is practicable."
+  }
+ ],
+ "direction_indicating": [
+  {
+   "cite": "AnxI.4(a)",
+   "applies_to_entries": [
+    "26c-gear"
+   ],
+   "horizontal_from_identity_lights_m": {
+    "min": 2,
+    "max": 6
+   },
+   "vertical": "not higher than the 26(c)(i) all-round white light and not lower than the sidelights",
+   "text": "The light indicating the direction of the outlying gear from a vessel engaged in fishing as prescribed in Rule 26(c)(ii) shall be placed at a horizontal distance of not less than 2 meters and not more than 6 meters away from the two all-round red and white lights. This light shall be placed not higher than the all-round white light prescribed in Rule 26(c)(i) and not lower than the sidelights."
+  },
+  {
+   "cite": "AnxI.4(b)",
+   "applies_to_entries": [
+    "27d"
+   ],
+   "horizontal_from_ram_lights_m": {
+    "min": 2
+   },
+   "vertical": "the upper of these lights shall not be higher than the lower of the three 27(b)(i) lights",
+   "text": "The lights and shapes on a vessel engaged in dredging or underwater operations to indicate the obstructed side and/or the side on which it is safe to pass, as prescribed in Rule 27(d)(i) and (ii), shall be placed at the maximum practical horizontal distance, but in no case less than 2 meters, from the lights or shapes prescribed in Rule 27(b)(i) and (ii). In no case shall the upper of these lights or shapes be at a greater height than the lower of the three lights or shapes prescribed in Rule 27(b)(i) and (ii)."
+  }
+ ],
+ "shapes": {
+  "cite": "AnxI.6",
+  "color": "black",
+  "ball": {
+   "min_diameter_m": 0.6,
+   "cite": "AnxI.6(a)(i)"
+  },
+  "cone": {
+   "min_base_diameter_m": 0.6,
+   "height_equals_diameter": true,
+   "cite": "AnxI.6(a)(ii)"
+  },
+  "cylinder": {
+   "min_diameter_m": 0.6,
+   "height_multiple_of_diameter": 2,
+   "cite": "AnxI.6(a)(iii)"
+  },
+  "diamond": {
+   "composition": "two cones with a common base",
+   "cite": "AnxI.6(a)(iv)"
+  },
+  "vertical_spacing_min_m": 1.5,
+  "small_vessel_relief": {
+   "when": {
+    "length_m": {
+     "lt": 20
+    }
+   },
+   "text": "In a vessel of less than 20 meters in length shapes of lesser dimensions but commensurate with the size of the vessel may be used and the distance apart may be correspondingly reduced."
+  }
+ },
+ "colors": {
+  "cite": "AnxI.7",
+  "standard": "CIE Publication No. 2.2 (TC-1.6), 1975, 'Colors of Light Signals'",
+  "chromaticity_corners": {
+   "white": {
+    "x": [
+     0.525,
+     0.525,
+     0.452,
+     0.31,
+     0.31,
+     0.443
+    ],
+    "y": [
+     0.382,
+     0.44,
+     0.44,
+     0.348,
+     0.283,
+     0.382
+    ]
+   },
+   "green": {
+    "x": [
+     0.028,
+     0.009,
+     0.3,
+     0.203
+    ],
+    "y": [
+     0.385,
+     0.723,
+     0.511,
+     0.356
+    ]
+   },
+   "red": {
+    "x": [
+     0.68,
+     0.66,
+     0.735,
+     0.721
+    ],
+    "y": [
+     0.32,
+     0.32,
+     0.265,
+     0.259
+    ]
+   },
+   "yellow": {
+    "x": [
+     0.612,
+     0.618,
+     0.575,
+     0.575
+    ],
+    "y": [
+     0.382,
+     0.382,
+     0.425,
+     0.406
+    ]
+   }
+  }
+ },
+ "intensity": {
+  "cite": "AnxI.8",
+  "formula": "I = 3.43e6 * T * D^2 * K^-D",
+  "terms": {
+   "I": "luminous intensity in candelas under service conditions",
+   "T": "threshold factor, 2e-7 lux",
+   "D": "range of visibility (luminous range) in nautical miles",
+   "K": "atmospheric transmissivity; 0.8 for prescribed lights"
+  },
+  "table_cd_by_range_nm": {
+   "1": 0.9,
+   "2": 4.3,
+   "3": 12,
+   "4": 27,
+   "5": 52,
+   "6": 94
+  }
+ },
+ "sectors": {
+  "cite": "AnxI.9",
+  "horizontal": {
+   "sidelights_forward": "shall show the minimum required intensities in the forward direction; intensities decrease to reach practical cut-off between 1 and 3 degrees outside the prescribed sectors"
+  }
+ }
+}