Ruleset Logic Definition

When defining rulesets, the rulesetLogic field captures the boolean filtering expression used to determine if a ship observation is deemed interesting and worth attempting to collect with an earth imaging order. This string consists of filter expressions and boolean logic (and, or) and can be as simply or complexly nested as you desire.

The filter expression syntax is as follows:

FILTER<<<variable, operator, criteria>>>

• variable defines the attribute on the observation upon which the filter will operate.
• operator defines the logical operator that expresses the relationship between the variable and the criteria.
• criteria is the value (or list of values) the variable is compared against.

The overall logic expression consists of one or more filters tied together by and or or boolean operators, with grouping parentheses as appropriate. The expression can be arbitrarily complex.

Operator Definition

These are the supported operators that can be used in a filter expression.

Operator	Description
IN	True if the variable is one of the items in the list of criteria. To match a variable to a single value, use IN with a criteria list containing just a single entry.
NOT_IN	True if the variable is NOT one of the items in the list of criteria.
>, >=, <, <=	Inequality operators in an expression of variable operator criteria. Criteria is a singular numeric value.
WITHIN	True if the variable is a point geometry located within the Polygon/Multipolygon geometry of the criteria.
NOT_WITHIN	True if the variable is a point geometry NOT located within the Polygon/Multipolygon geometry of the criteria.

Variable Definition

These are the supported variables that can be used in a filter expression.

Variable	Supported Operators	Description	Example Filter
mmsi	IN, NOT_IN	Unique identifier of the vessel used by AIS transponders.	FILTER<<<mmsi, IN, [12345, abcde, ah13240]>>>
imo	IN, NOT_IN	Unique ship identifier (similar to mmsi but less likely to be reused by multiple vessels).	FILTER<<<imo, IN, [12345, abcde, ah13240]>>>
flag	IN, NOT_IN	Name of the country under which the vessel operates. See the List of Flags for official name strings to use as criteria.	FILTER<<<flag, NOT_IN, [USA]>>>
vessel_type	IN, NOT_IN	String classification of the vessel category. In practice this is most useful for dark observations, where the category is supplied by the Vantor vessel-detection algorithm (these names differ at times from what AIS uses). See the List of Detected Vessel Types for the possible values. NOTE: string values containing commas must be comma-escaped — see the Notes below.	FILTER<<<vessel_type, IN, [Fishing,Cargo]>>>
numeric_vessel_type	IN, NOT_IN	Numeric classification of the vessel category (AIS ship-type code). In practice this is most useful for lit observations, where the numeric code is supplied by AIS. See the List of Ship Types for the mapping between the numeric values and the strings they represent.	FILTER<<<numeric_vessel_type, IN, [0,3,98]>>>
observation_type	IN, NOT_IN	The type of the observation. lit — observations either from AIS transponder data or at least correlated to that AIS data. dark — observations detected in SAR or EO imagery that are not correlated to AIS.	FILTER<<<observation_type, IN, [lit]>>>
observation_source	IN, NOT_IN	The detection source of the observation. Accepted values: SAR_VD (SAR vessel detection), EO_VD (Vantor EO vessel detection), RF_VD (RF vessel detection), SAR_OIL_SOURCE (vessel suspected as the source of an oil spill in a SAR scene), and SAR_OIL_SPILL (a SAR-detected oil spill).	FILTER<<<observation_source, IN, [SAR_VD, EO_VD]>>>
speed_knots	>, >=, <, <=	Speed of the vessel in knots.	FILTER<<<speed_knots, <=, 8.2>>>
vessel_width	>, >=, <, <=	Width of the vessel in meters.	FILTER<<<vessel_width, <, 50>>>
vessel_length	>, >=, <, <=	Length of the vessel in meters.	FILTER<<<vessel_length, >, 100>>>
oil_spill_area_km2	>, >=, <, <=	Area of a detected oil spill in square kilometers. Applies only to oil-spill observations (those with an observation_source of SAR_OIL_SPILL).	FILTER<<<oil_spill_area_km2, >, 5>>>
ais_class	IN, NOT_IN	The class of the AIS transponder used by the vessel (A or B).	FILTER<<<ais_class, IN, [A]>>>
location	WITHIN, NOT_WITHIN	Point location of the vessel. The criteria must be a WKT string with a Polygon or Multipolygon geometry type.	FILTER<<<location, NOT_WITHIN, POLYGON((0 0.5, 0 2, 2 2, 2 0.5, 0 0.5))>>>
heading_deg	>, >=, <, <=	Direction in degrees (0–360). 0° is North, 90° is East, 180° is South, 270° is West.	FILTER<<<heading_deg, >=, 90>>>
customer	IN, NOT_IN	Name of the customer. Primarily used to limit SAR-to-EO tipping to be driven only by SAR data for the applicable customer, rather than considering dark observations from SAR scenes associated with other customers.	FILTER<<<customer, IN, [Customer1]>>>

Example ruleset strings

FILTER<<<mmsi, IN, [12345, abcde, ah13240]>>>

(FILTER<<<mmsi, IN, [12345, abcde, ah13240]>>> or FILTER<<<speed_knots, <=, 8.2>>>)

((FILTER<<<mmsi, IN, [12345, abcde, ah13240]>>> and FILTER<<<speed_knots, <=, 8.2>>>) or FILTER<<<flag, IN, [Nicaragua, USA]>>>)

Notes

• Do not put single or double quotes around string values. Values will be interpreted correctly as strings or numbers based on their associated variable.
• String criteria values that themselves contain a comma must be escaped by doubling the comma (,,), since a single comma separates items in a criteria list. For example, the category string Cargo Ships, All ships of this type is written as Cargo Ships,, All ships of this type inside a list.
• If you have any boolean operators present, then there must be an outermost set of parentheses wrapping the entire expression.
• Criteria for geometry filters is specified as WKT, and only Polygon and Multipolygon are supported.
• Boolean operators and and or MUST be specified in lower case.
• Filter operators (IN, NOT_WITHIN, >, etc.) are not case-sensitive.