ST 0601 metadata API¶
Typed UAS Local Set codecs, lossless mutation, preferred representations, MISP/UTC conversion, and receiver-visible Report-on-Change state.
stanag4609.st0601 ¶
Typed, lossless decoding for the MISB ST 0601 UAS Local Set.
ST0601_KEY
module-attribute
¶
ST0601_SDCC_SOURCE_TAGS
module-attribute
¶
ST0601_SDCC_SOURCE_TAGS = frozenset({*range(5, 23), 50, 51, 52, 64, 75, 79, 80, 90, 91, 92, 93, 96, 104, 113, 114, 117, 118, 119})
_SEMANTIC_INTEGER_TYPES
module-attribute
¶
_SEMANTIC_INTEGER_TYPES: Mapping[int, type[int]] = MappingProxyType({34: IcingDetected, 47: GenericFlagData, 60: WeaponLoad, 61: WeaponFired, 62: LaserPRFCode, 63: SensorFieldOfViewName, 77: OperationalMode, 124: PositioningMethodSource, 125: PlatformStatus, 126: SensorControlMode})
ST0601_REPRESENTATION_PREFERENCES
module-attribute
¶
ST0601_REPRESENTATION_PREFERENCES: Mapping[ST0601Semantic, RepresentationPreference] = MappingProxyType({ST0601Semantic.PLATFORM_PITCH: RepresentationPreference(ST0601Semantic.PLATFORM_PITCH, (90, 6), ('ST 0601.8-16',)), ST0601Semantic.PLATFORM_ROLL: RepresentationPreference(ST0601Semantic.PLATFORM_ROLL, (91, 7), ('ST 0601.8-16',)), ST0601Semantic.PLATFORM_ANGLE_OF_ATTACK: RepresentationPreference(ST0601Semantic.PLATFORM_ANGLE_OF_ATTACK, (92, 50), ('ST 0601.8-16',)), ST0601Semantic.PLATFORM_SIDESLIP: RepresentationPreference(ST0601Semantic.PLATFORM_SIDESLIP, (93, 52), ('ST 0601.8-16',)), ST0601Semantic.TARGET_WIDTH: RepresentationPreference(ST0601Semantic.TARGET_WIDTH, (96, 22), ('ST 0601.9-20', 'ST 0601.9-21')), ST0601Semantic.DENSITY_ALTITUDE: RepresentationPreference(ST0601Semantic.DENSITY_ALTITUDE, (103, 38), ('ST 0601.9-20', 'ST 0601.9-21')), ST0601Semantic.SENSOR_HEIGHT: RepresentationPreference(ST0601Semantic.SENSOR_HEIGHT, (104, 75, 15), ('ST 0601.8-17', 'ST 0601.9-20', 'ST 0601.9-21')), ST0601Semantic.ALTERNATE_PLATFORM_HEIGHT: RepresentationPreference(ST0601Semantic.ALTERNATE_PLATFORM_HEIGHT, (105, 76, 69), ('ST 0601.8-17', 'ST 0601.9-20', 'ST 0601.9-21')), ST0601Semantic.FRAME_CENTER_HEIGHT: RepresentationPreference(ST0601Semantic.FRAME_CENTER_HEIGHT, (78, 25), ('ST 0601.8-17',))})
FIELD_DEFINITIONS
module-attribute
¶
FIELD_DEFINITIONS: dict[int, FieldDefinition] = {1: FieldDefinition(1, 'Checksum', 'uint', 2), 2: FieldDefinition(2, 'Precision Time Stamp', 'timestamp', 8, 'MISP microseconds since epoch'), 3: FieldDefinition(3, 'Mission ID', 'text', None, maximum_length=127), 4: FieldDefinition(4, 'Platform Tail Number', 'text', None, maximum_length=127), 5: _mapped(5, 'Platform Heading Angle', 2, 0, 360, units='degrees'), 6: _mapped(6, 'Platform Pitch Angle', 2, -20, 20, units='degrees', signed=True, special_raw=-2 ** 15, special_value=SpecialValue.OUT_OF_RANGE), 7: _mapped(7, 'Platform Roll Angle', 2, -50, 50, units='degrees', signed=True, special_raw=-2 ** 15, special_value=SpecialValue.OUT_OF_RANGE), 8: FieldDefinition(8, 'Platform True Airspeed', 'uint', 1, 'm/s'), 9: FieldDefinition(9, 'Platform Indicated Airspeed', 'uint', 1, 'm/s'), 10: FieldDefinition(10, 'Platform Designation', 'text', None, maximum_length=127), 11: FieldDefinition(11, 'Image Source Sensor', 'text', None, maximum_length=127), 12: FieldDefinition(12, 'Image Coordinate System', 'text', None, maximum_length=127), 13: _mapped(13, 'Sensor Latitude', 4, -90, 90, units='degrees', signed=True, special_raw=-2 ** 31, special_value=SpecialValue.RESERVED), 14: _mapped(14, 'Sensor Longitude', 4, -180, 180, units='degrees', signed=True, special_raw=-2 ** 31, special_value=SpecialValue.RESERVED), 15: _mapped(15, 'Sensor True Altitude', 2, -900, 19000, units='metres'), 16: _mapped(16, 'Sensor Horizontal Field of View', 2, 0, 180, units='degrees'), 17: _mapped(17, 'Sensor Vertical Field of View', 2, 0, 180, units='degrees'), 18: _mapped(18, 'Sensor Relative Azimuth Angle', 4, 0, 360, units='degrees'), 19: _mapped(19, 'Sensor Relative Elevation Angle', 4, -180, 180, units='degrees', signed=True, special_raw=-2 ** 31, special_value=SpecialValue.RESERVED), 20: _mapped(20, 'Sensor Relative Roll Angle', 4, 0, 360, units='degrees'), 21: _mapped(21, 'Slant Range', 4, 0, 5000000, units='metres'), 22: _mapped(22, 'Target Width', 2, 0, 10000, units='metres'), 23: _mapped(23, 'Frame Center Latitude', 4, -90, 90, units='degrees', signed=True, special_raw=-2 ** 31, special_value=SpecialValue.OFF_EARTH), 24: _mapped(24, 'Frame Center Longitude', 4, -180, 180, units='degrees', signed=True, special_raw=-2 ** 31, special_value=SpecialValue.OFF_EARTH), 25: _mapped(25, 'Frame Center Elevation', 2, -900, 19000, units='metres'), 26: _mapped(26, 'Offset Corner Latitude Point 1', 2, -Fraction(3, 40), Fraction(3, 40), units='degrees', signed=True, special_raw=-2 ** 15, special_value=SpecialValue.OFF_EARTH), 27: _mapped(27, 'Offset Corner Longitude Point 1', 2, -Fraction(3, 40), Fraction(3, 40), units='degrees', signed=True, special_raw=-2 ** 15, special_value=SpecialValue.OFF_EARTH), 28: _mapped(28, 'Offset Corner Latitude Point 2', 2, -Fraction(3, 40), Fraction(3, 40), units='degrees', signed=True, special_raw=-2 ** 15, special_value=SpecialValue.OFF_EARTH), 29: _mapped(29, 'Offset Corner Longitude Point 2', 2, -Fraction(3, 40), Fraction(3, 40), units='degrees', signed=True, special_raw=-2 ** 15, special_value=SpecialValue.OFF_EARTH), 30: _mapped(30, 'Offset Corner Latitude Point 3', 2, -Fraction(3, 40), Fraction(3, 40), units='degrees', signed=True, special_raw=-2 ** 15, special_value=SpecialValue.OFF_EARTH), 31: _mapped(31, 'Offset Corner Longitude Point 3', 2, -Fraction(3, 40), Fraction(3, 40), units='degrees', signed=True, special_raw=-2 ** 15, special_value=SpecialValue.OFF_EARTH), 32: _mapped(32, 'Offset Corner Latitude Point 4', 2, -Fraction(3, 40), Fraction(3, 40), units='degrees', signed=True, special_raw=-2 ** 15, special_value=SpecialValue.OFF_EARTH), 33: _mapped(33, 'Offset Corner Longitude Point 4', 2, -Fraction(3, 40), Fraction(3, 40), units='degrees', signed=True, special_raw=-2 ** 15, special_value=SpecialValue.OFF_EARTH), 34: _integer(34, 'Icing Detected', 1, minimum=0, maximum=2), 35: _mapped(35, 'Wind Direction', 2, 0, 360, units='degrees'), 36: _mapped(36, 'Wind Speed', 1, 0, 100, units='m/s'), 37: _mapped(37, 'Static Pressure', 2, 0, 5000, units='mbar'), 38: _mapped(38, 'Density Altitude', 2, -900, 19000, units='metres'), 39: _integer(39, 'Outside Air Temperature', 1, units='Celsius', signed=True), 40: _mapped(40, 'Target Location Latitude', 4, -90, 90, units='degrees', signed=True, special_raw=-2 ** 31, special_value=SpecialValue.OFF_EARTH), 41: _mapped(41, 'Target Location Longitude', 4, -180, 180, units='degrees', signed=True, special_raw=-2 ** 31, special_value=SpecialValue.OFF_EARTH), 42: _mapped(42, 'Target Location Elevation', 2, -900, 19000, units='metres'), 43: _mapped(43, 'Target Track Gate Width', 1, 0, 510, units='pixels'), 44: _mapped(44, 'Target Track Gate Height', 1, 0, 510, units='pixels'), 45: _mapped(45, 'Target Error Estimate - CE90', 2, 0, 4095, units='metres'), 46: _mapped(46, 'Target Error Estimate - LE90', 2, 0, 4095, units='metres'), 47: _integer(47, 'Generic Flag Data', 1, minimum=0, maximum=63), 48: FieldDefinition(48, 'Security Local Set', 'security', None), 49: _mapped(49, 'Differential Pressure', 2, 0, 5000, units='mbar'), 50: _mapped(50, 'Platform Angle of Attack', 2, -20, 20, units='degrees', signed=True, special_raw=-2 ** 15, special_value=SpecialValue.OUT_OF_RANGE), 51: _mapped(51, 'Platform Vertical Speed', 2, -180, 180, units='m/s', signed=True, special_raw=-2 ** 15, special_value=SpecialValue.OUT_OF_RANGE), 52: _mapped(52, 'Platform Sideslip Angle', 2, -20, 20, units='degrees', signed=True, special_raw=-2 ** 15, special_value=SpecialValue.OUT_OF_RANGE), 53: _mapped(53, 'Airfield Barometric Pressure', 2, 0, 5000, units='mbar'), 54: _mapped(54, 'Airfield Elevation', 2, -900, 19000, units='metres'), 55: _mapped(55, 'Relative Humidity', 1, 0, 100, units='percent'), 56: _integer(56, 'Platform Ground Speed', 1, units='m/s'), 57: _mapped(57, 'Ground Range', 4, 0, 5000000, units='metres'), 58: _mapped(58, 'Platform Fuel Remaining', 2, 0, 10000, units='kilograms'), 59: FieldDefinition(59, 'Platform Call Sign', 'text', None, maximum_length=127), 60: _integer(60, 'Weapon Load', 2), 61: _integer(61, 'Weapon Fired', 1), 62: _integer(62, 'Laser PRF Code', 2), 63: _integer(63, 'Sensor Field of View Name', 1, minimum=0, maximum=8), 64: _mapped(64, 'Platform Magnetic Heading', 2, 0, 360, units='degrees'), 65: FieldDefinition(65, 'UAS Datalink LS Version Number', 'uint', 1), 67: _mapped(67, 'Alternate Platform Latitude', 4, -90, 90, units='degrees', signed=True, special_raw=-2 ** 31, special_value=SpecialValue.RESERVED), 68: _mapped(68, 'Alternate Platform Longitude', 4, -180, 180, units='degrees', signed=True, special_raw=-2 ** 31, special_value=SpecialValue.RESERVED), 69: _mapped(69, 'Alternate Platform Altitude', 2, -900, 19000, units='metres'), 70: FieldDefinition(70, 'Alternate Platform Name', 'text', None, maximum_length=127), 71: _mapped(71, 'Alternate Platform Heading', 2, 0, 360, units='degrees'), 72: FieldDefinition(72, 'Event Start Time', 'timestamp', 8, 'microseconds UTC'), 73: FieldDefinition(73, 'RVT Local Set', 'rvt', None), 74: FieldDefinition(74, 'VMTI Local Set', 'vmti', None), 75: _mapped(75, 'Sensor Ellipsoid Height', 2, -900, 19000, units='metres'), 76: _mapped(76, 'Alternate Platform Ellipsoid Height', 2, -900, 19000, units='metres'), 77: _integer(77, 'Operational Mode', 1, minimum=0, maximum=5), 78: _mapped(78, 'Frame Center Height Above Ellipsoid', 2, -900, 19000, units='metres'), 79: _mapped(79, 'Sensor North Velocity', 2, -327, 327, units='m/s', signed=True, special_raw=-2 ** 15, special_value=SpecialValue.OUT_OF_RANGE), 80: _mapped(80, 'Sensor East Velocity', 2, -327, 327, units='m/s', signed=True, special_raw=-2 ** 15, special_value=SpecialValue.OUT_OF_RANGE), 81: FieldDefinition(81, 'Image Horizon Pixel Pack', 'horizon', None, maximum_length=20), 82: _mapped(82, 'Corner Latitude Point 1 (Full)', 4, -90, 90, units='degrees', signed=True, special_raw=-2 ** 31, special_value=SpecialValue.OFF_EARTH), 83: _mapped(83, 'Corner Longitude Point 1 (Full)', 4, -180, 180, units='degrees', signed=True, special_raw=-2 ** 31, special_value=SpecialValue.OFF_EARTH), 84: _mapped(84, 'Corner Latitude Point 2 (Full)', 4, -90, 90, units='degrees', signed=True, special_raw=-2 ** 31, special_value=SpecialValue.OFF_EARTH), 85: _mapped(85, 'Corner Longitude Point 2 (Full)', 4, -180, 180, units='degrees', signed=True, special_raw=-2 ** 31, special_value=SpecialValue.OFF_EARTH), 86: _mapped(86, 'Corner Latitude Point 3 (Full)', 4, -90, 90, units='degrees', signed=True, special_raw=-2 ** 31, special_value=SpecialValue.OFF_EARTH), 87: _mapped(87, 'Corner Longitude Point 3 (Full)', 4, -180, 180, units='degrees', signed=True, special_raw=-2 ** 31, special_value=SpecialValue.OFF_EARTH), 88: _mapped(88, 'Corner Latitude Point 4 (Full)', 4, -90, 90, units='degrees', signed=True, special_raw=-2 ** 31, special_value=SpecialValue.OFF_EARTH), 89: _mapped(89, 'Corner Longitude Point 4 (Full)', 4, -180, 180, units='degrees', signed=True, special_raw=-2 ** 31, special_value=SpecialValue.OFF_EARTH), 90: _mapped(90, 'Platform Pitch Angle (Full)', 4, -90, 90, units='degrees', signed=True, special_raw=-2 ** 31, special_value=SpecialValue.OUT_OF_RANGE), 91: _mapped(91, 'Platform Roll Angle (Full)', 4, -90, 90, units='degrees', signed=True, special_raw=-2 ** 31, special_value=SpecialValue.OUT_OF_RANGE), 92: _mapped(92, 'Platform Angle of Attack (Full)', 4, -90, 90, units='degrees', signed=True, special_raw=-2 ** 31, special_value=SpecialValue.OUT_OF_RANGE), 93: _mapped(93, 'Platform Sideslip Angle (Full)', 4, -180, 180, units='degrees', signed=True, special_raw=-2 ** 31, special_value=SpecialValue.OUT_OF_RANGE), 94: FieldDefinition(94, 'MIIS Core Identifier', 'miis', None, maximum_length=50), 95: FieldDefinition(95, 'SAR Motion Imagery Local Set', 'sar', None), 96: _imap(96, 'Target Width Extended', 0, 1500000, units='metres'), 97: FieldDefinition(97, 'Range Image Local Set', 'range_image', None), 98: FieldDefinition(98, 'Geo-Registration Local Set', 'geo_registration', None), 99: FieldDefinition(99, 'Composite Imaging Local Set', 'composite_imaging', None), 100: FieldDefinition(100, 'Segment Local Set', 'segment', None, multiple=True), 101: FieldDefinition(101, 'Amend Local Set', 'amend', None, multiple=True), 102: FieldDefinition(102, 'SDCC-FLP', 'sdcc', None, multiple=True), 103: _imap(103, 'Density Altitude Extended', -900, 40000, units='metres'), 104: _imap(104, 'Sensor Ellipsoid Height Extended', -900, 40000, units='metres'), 105: _imap(105, 'Alternate Platform Ellipsoid Height Extended', -900, 40000, units='metres'), 106: FieldDefinition(106, 'Stream Designator', 'text', None, maximum_length=127), 107: FieldDefinition(107, 'Operational Base', 'text', None, maximum_length=127), 108: FieldDefinition(108, 'Broadcast Source', 'text', None, maximum_length=127), 109: _imap(109, 'Range To Recovery Location', 0, 21000, units='km', maximum_length=4), 110: _integer(110, 'Time Airborne', None, units='seconds', minimum=0, maximum=2 ** 32 - 1, maximum_length=4), 111: _integer(111, 'Propulsion Unit Speed', None, units='RPM', minimum=0, maximum=2 ** 32 - 1, maximum_length=4), 112: _imap(112, 'Platform Course Angle', 0, 360, units='degrees'), 113: _imap(113, 'Altitude AGL', -900, 40000, units='metres', maximum_length=4), 114: _imap(114, 'Radar Altimeter', -900, 40000, units='metres', maximum_length=4), 115: FieldDefinition(115, 'Control Command', 'control_command', None, multiple=True), 116: FieldDefinition(116, 'Control Command Verification List', 'command_verification', None), 117: _imap(117, 'Sensor Azimuth Rate', -1000, 1000, units='degrees/second', maximum_length=4), 118: _imap(118, 'Sensor Elevation Rate', -1000, 1000, units='degrees/second', maximum_length=4), 119: _imap(119, 'Sensor Roll Rate', -1000, 1000, units='degrees/second', maximum_length=4), 120: _imap(120, 'On-board MI Storage Percent Full', 0, 100, units='percent', maximum_length=3), 121: FieldDefinition(121, 'Active Wavelength List', 'active_wavelengths', None), 122: FieldDefinition(122, 'Country Codes', 'country_codes', None), 123: _integer(123, 'Number of NAVSATs in View', 1), 124: _integer(124, 'Positioning Method Source', 1, minimum=1, maximum=255), 125: _integer(125, 'Platform Status', 1, minimum=0, maximum=12), 126: _integer(126, 'Sensor Control Mode', 1, minimum=0, maximum=6), 127: FieldDefinition(127, 'Sensor Frame Rate Pack', 'frame_rate', None, maximum_length=16), 128: FieldDefinition(128, 'Wavelengths List', 'wavelengths', None), 129: FieldDefinition(129, 'Target ID', 'text', None, maximum_length=32), 130: FieldDefinition(130, 'Airbase Locations', 'airbase_locations', None, maximum_length=24), 131: FieldDefinition(131, 'Take-off Time', 'timestamp', None, maximum_length=8), 132: _imap(132, 'Transmission Frequency', 1, 99999, units='MHz', maximum_length=4), 133: _integer(133, 'On-board MI Storage Capacity', None, units='gigabytes', minimum=0, maximum=2 ** 32 - 1, maximum_length=4), 134: _imap(134, 'Zoom Percentage', 0, 100, units='percent', maximum_length=4), 135: FieldDefinition(135, 'Communications Method', 'text', None, maximum_length=127), 136: _integer(136, 'Leap Seconds', None, units='seconds', signed=True, minimum=-2 ** 31, maximum=2 ** 31 - 1, maximum_length=4), 137: _integer(137, 'Correction Offset', None, units='microseconds', signed=True, minimum=-2 ** 63, maximum=2 ** 63 - 1, maximum_length=8), 138: FieldDefinition(138, 'Payload List', 'payload_list', None), 139: FieldDefinition(139, 'Active Payloads', 'active_payloads', None), 140: FieldDefinition(140, 'Weapons Stores', 'weapons_stores', None), 141: FieldDefinition(141, 'Waypoint List', 'waypoint_list', None), 142: FieldDefinition(142, 'View Domain', 'view_domain', None)}
ChecksumError ¶
Bases: DecodeError
A checksum is absent, misplaced, malformed, or incorrect.
DecodeError ¶
Bases: Stanag4609Error, ValueError
Input is complete enough to inspect but is not valid.
NeedMoreData ¶
IMAPB ¶
Fixed-length ST 1201 IMAPB encoder and decoder.
encode ¶
encode(value: Real | IMAPSpecialValue) -> bytes
Encode a number or losslessly re-emit an explicit special value.
decode ¶
decode(data: bytes, *, overflow_policy: IMAPOverflowPolicy = PRESERVE) -> float | IMAPSpecialValue
Decode a fixed-length IMAP value.
Special values retain their exact wire representation by default so
the invoking standard can apply item-specific semantics. Use
:attr:IMAPOverflowPolicy.CLAMP when the parent document does not
define alternate behavior for the below-minimum and above-maximum
signals; ST 1201 then resolves them to the corresponding range bound.
IMAPSpecialValue
dataclass
¶
IMAPSpecialValue(kind: IMAPSpecialKind, raw: bytes)
A non-numeric IMAP code word, including its original representation.
KLVPacket
dataclass
¶
A Universal KLV packet with its original length encoding.
LocalSet
dataclass
¶
LocalSet(items: tuple[LocalSetItem, ...], raw: bytes)
Ordered Local Set items; duplicate and unknown tags are preserved.
LocalSetItem
dataclass
¶
One Local Set item, preserving the exact tag and length octets.
KLVStreamParser ¶
KLVStreamParser(*, key_length: int = 16, key_prefix: bytes | None = b'\x06\x0e+4', canonical: bool = True, recover: bool = False, max_value_length: int = 64 * 1024 * 1024, validate_smpte_keys: bool | None = None)
Incrementally reconstruct fixed-width-key KLV packets.
Input chunks may split the key, BER length, or value at any byte boundary. Completed bytes are released immediately, and declared values are bounded.
SecurityLocalSet
dataclass
¶
SecurityLocalSet(packet: KLVPacket | None, local_set: LocalSet, fields: tuple[SecurityField, ...], standalone: bool)
Decoded standalone or ST 0601-embedded Security Metadata Local Set.
RVTLocalSet
dataclass
¶
RVTLocalSet(packet: KLVPacket | None, local_set: LocalSet, fields: tuple[RVTField, ...], standalone: bool)
VMTILocalSet
dataclass
¶
VMTILocalSet(packet: KLVPacket | None, local_set: LocalSet, fields: tuple[VMTIField, ...], targets: tuple[VTarget, ...], standalone: bool, algorithms: tuple[AlgorithmLocalSet, ...] = (), ontologies: tuple[OntologyLocalSet, ...] = ())
Decoded standalone or ST 0601-embedded VMTI Local Set.
VMTIValidationContext
dataclass
¶
VMTIValidationContext(vmti_frame_timestamp: int | datetime | None = None, parent_timestamp: int | datetime | None = None, frame_period_microseconds: Fraction | int | float | None = None, frame_width: int | None = None, frame_height: int | None = None, total_targets_detected: int | None = None, different_image_source: bool = False, ontology_resolver: OntologyResolver | None = None)
External producer/frame facts needed by conditional ST 0903 requirements.
Integer timestamps and frame periods use microseconds. The context performs no clock inference: callers supply the VMTI-MI frame time, the containing parent time, and/or the frame period when those facts are known.
RangeImageLocalSet
dataclass
¶
RangeImageLocalSet(timestamp: datetime, document_version: int, enumerations: RangeImageEnumerations, sprm: float | None = None, sprm_uncertainty: float | None = None, sprm_row: float | None = None, sprm_column: float | None = None, sections_x: int = 1, sections_y: int = 1, transformation: GeneralizedTransformation | None = None, sections: tuple[SectionData, ...] = (), leap_seconds: int | None = None, extensions: Mapping[int, RawRangeValue] = dict(), packet: KLVPacket | None = None, local_set: LocalSet | None = None, fields: tuple[RangeField, ...] = (), standalone: bool = True)
A standalone or embedded ST 1002.3 Range Image Local Set.
effective_sprm_coordinates ¶
Return the effective SPRM (row, column) image coordinates.
ST 1002.1-07 and ST 1002.1-08 make the image center the default for each omitted coordinate independently. Image dimensions are caller context because the Range Image Local Set does not carry them.
SDCCFLP
dataclass
¶
SDCCFLP(matrix_size: int, parse_control: SDCCParseControl, standard_deviations: tuple[SDCCValue, ...], correlation_coefficients: tuple[SDCCValue | None, ...], standard_deviation_imap_bounds: tuple[Real, Real] | None = None, source_tags: tuple[int, ...] = ())
One upper-triangular standard-deviation/correlation matrix.
Correlations use the ST 1010 row-major upper-triangle order. In a sparse
matrix, None represents a zero/unknown coefficient omitted from the
wire value by the Bit Vector. source_tags is parent-set context and is
not encoded by ST 1010 itself.
correlation ¶
Return a symmetric matrix cell, including its diagonal deviation.
MIISCoreIdentifier
dataclass
¶
MIISCoreIdentifier(version: int, sensor_quality: IdentifierQuality = NONE, platform_quality: IdentifierQuality = NONE, sensor_id: UUID | None = None, platform_id: UUID | None = None, window_id: UUID | None = None, minor_id: UUID | None = None, raw: bytes = b'')
A typed ST 1204.3 binary Core Identifier value.
SARMotionImageryLocalSet
dataclass
¶
SARMotionImageryLocalSet(ground_plane_squint_angle: MappedValue, look_direction: LookDirection, document_version: int, grazing_angle: MappedValue | None = None, image_plane: ImagePlane | None = None, range_resolution: MappedValue | None = None, cross_range_resolution: MappedValue | None = None, range_pixel_size: MappedValue | None = None, cross_range_pixel_size: MappedValue | None = None, image_rows: int | None = None, image_columns: int | None = None, range_direction_angle: MappedValue | None = None, true_north_direction: MappedValue | None = None, range_layover_angle: MappedValue | None = None, ground_aperture_angular_extent: MappedValue | None = None, aperture_duration: int | None = None, ground_track_angle: MappedValue | None = None, minimum_detectable_velocity: MappedValue | None = None, true_pulse_repetition_frequency: MappedValue | None = None, pulse_repetition_frequency_scale_factor: MappedValue | None = None, transmit_rf_center_frequency: MappedValue | None = None, transmit_rf_bandwidth: MappedValue | None = None, radar_cross_section_scale_factor_polynomial: MDAP | None = None, reference_frame_timestamp: datetime | None = None, reference_frame_grazing_angle: MappedValue | None = None, reference_frame_ground_plane_squint_angle: MappedValue | None = None, reference_frame_range_direction_angle: MappedValue | None = None, reference_frame_range_layover_angle: MappedValue | None = None, extensions: Mapping[int, RawSARValue] = dict(), packet: KLVPacket | None = None, local_set: LocalSet | None = None, standalone: bool = True)
Typed ST 1206.1 SAR Motion Imagery metadata.
GeoRegistrationLocalSet
dataclass
¶
GeoRegistrationLocalSet(document_version: int, algorithm_name: str, algorithm_version: str, row_column: MDAP | None = None, latitude_longitude: MDAP | None = None, second_image_name: str | None = None, algorithm_configuration_id: UUID | None = None, elevation: MDAP | None = None, pixel_uncertainty: HeterogeneousIMAPArray | None = None, geo_uncertainty: HeterogeneousIMAPArray | None = None, extensions: Mapping[int, RawGeoRegistrationValue] = dict(), local_set: LocalSet | None = None)
Typed ST 1601.2 value embedded in a contextual parent Local Set.
CompositeImagingLocalSet
dataclass
¶
CompositeImagingLocalSet(document_version: int, sub_image_rows: int, sub_image_columns: int, sub_image_position_x: int, sub_image_position_y: int, z_order: int, timestamp: datetime | None = None, source_image_rows: int | None = None, source_image_columns: int | None = None, source_aoi_rows: int | None = None, source_aoi_columns: int | None = None, source_aoi_position_x: int | None = None, source_aoi_position_y: int | None = None, active_rows: int | None = None, active_columns: int | None = None, active_offset_x: int | None = None, active_offset_y: int | None = None, transparency: int = 0, extensions: Mapping[int, RawCompositeValue] = dict(), local_set: LocalSet | None = None)
One source/sub-image mapping embedded in an ST 1607 segment.
SpecialValue ¶
Bases: Enum
Non-numeric MISB values that must remain semantically distinct.
IcingDetected ¶
Bases: IntEnum
ST 0601 Item 34 icing-detector state.
GenericFlagData ¶
Bases: IntFlag
ST 0601 Item 47 aircraft and image Boolean flags.
SensorFieldOfViewName ¶
Bases: IntEnum
ST 0601 Item 63 generic sensor lens selection.
OperationalMode ¶
Bases: IntEnum
ST 0601 Item 77 motion-imagery operational category.
PositioningMethodSource ¶
Bases: IntFlag
ST 0601 Item 124 navigation-source bit set.
PlatformStatus ¶
Bases: IntEnum
ST 0601 Item 125 platform flight-lifecycle mode.
SensorControlMode ¶
Bases: IntEnum
ST 0601 Item 126 sensor-control operational status.
WeaponLoad ¶
Bases: int
ST 0601 Item 60 packed station, substation, type, and variant.
WeaponFired ¶
Bases: int
ST 0601 Item 61 packed released-weapon station and substation.
LaserPRFCode ¶
Bases: int
ST 0601 Item 62 three/four-digit laser code using digits 1 through 8.
UpdateAction ¶
Bases: Enum
Sentinel actions accepted by lossless Local Set updates.
FieldDecodingMode ¶
Bases: Enum
Policy for malformed values carried by otherwise valid known fields.
ST0601Semantic ¶
Bases: Enum
Logical values that have multiple ST 0601 wire representations.
VerticalDatum ¶
Bases: Enum
Vertical reference used to interpret an ST 0601 elevation value.
RepresentationPreference
dataclass
¶
RepresentationPreference(semantic: ST0601Semantic, tags: tuple[int, ...], requirement_ids: tuple[str, ...])
Normative preferred-to-legacy tag order for one logical value.
ST0601FieldExpectation
dataclass
¶
Producer-supplied expected value for one decoded ST 0601 field.
matches ¶
Return whether a decoded value satisfies this expectation.
ST0601RepeatedFieldExpectation
dataclass
¶
ST0601RepeatedFieldExpectation(occurrences: tuple[ST0601FieldExpectation, ...])
Producer-supplied values for every occurrence of one multi-use field.
Local Set item order is generally arbitrary, so matching is one-to-one and
order-independent. Each expected occurrence can still carry its own mapped
value tolerance through :class:ST0601FieldExpectation.
matches ¶
Return whether observed values have a one-to-one expectation match.
ST0601ValidationContext
dataclass
¶
ST0601ValidationContext(metadata_birth_timestamp: int | datetime | None = None, imap_system_precisions: Mapping[int, int | float | Fraction] = dict(), vmti_context: VMTIValidationContext | None = None, field_expectations: Mapping[int, ST0601FieldExpectation | ST0601RepeatedFieldExpectation] = dict())
External facts required to validate conditional ST 0601 semantics.
metadata_birth_timestamp is the producer-known time of birth shared by
all metadata carried in one UAS Datalink Local Set instance. Integer values
are MISP Time System microseconds since the epoch. An aware datetime is
accepted as a coordinate representation for that continuous count; use
:func:utc_to_misp_timestamp before encoding a civil UTC instant.
imap_system_precisions maps
variable-length IMAP tags to the producer precision each value must retain.
vmti_context supplies facts about the imagery processed by an embedded
Item 74 VMTI set; its parent timestamp is checked against and then derived
from the enclosing ST 0601 Item 2. field_expectations supplies
authoritative producer or test-harness values for singleton or multi-use
root fields; explicit tolerances account for mapped-value quantization.
required_imap_length ¶
Return the shortest wire length for one configured IMAP tag.
RawFieldValue
dataclass
¶
Explicit wire value for adding or replacing an untyped extension tag.
FieldDefinition
dataclass
¶
FieldDefinition(tag: int, name: str, kind: Literal['uint', 'sint', 'mapped', 'imap', 'vmti', 'miis', 'security', 'rvt', 'range_image', 'geo_registration', 'composite_imaging', 'sar', 'sdcc', 'segment', 'amend', 'horizon', 'frame_rate', 'control_command', 'command_verification', 'active_wavelengths', 'country_codes', 'wavelengths', 'airbase_locations', 'payload_list', 'active_payloads', 'weapons_stores', 'waypoint_list', 'view_domain', 'text', 'timestamp'], length: int | None, units: str | None = None, signed: bool = False, physical_min: Fraction | None = None, physical_max: Fraction | None = None, special_raw: int | None = None, special_value: SpecialValue | None = None, integer_min: int | None = None, integer_max: int | None = None, maximum_length: int | None = None, multiple: bool = False)
DecodedField
dataclass
¶
DecodedField(definition: FieldDefinition, value: Any, raw: bytes, item: LocalSetItem)
ResolvedUASField
dataclass
¶
ResolvedUASField(preference: RepresentationPreference, field: DecodedField, ignored: tuple[DecodedField, ...] = ())
One selected ST 0601 representation and lower-priority fields ignored.
ResolvedTargetElevation
dataclass
¶
ResolvedTargetElevation(field: DecodedField, datum: VerticalDatum | None, frame_height: ResolvedUASField | None)
Item 42 with its receiver-visible MSL or HAE interpretation.
FieldDecodingIssue
dataclass
¶
FieldDecodingIssue(tag: int, name: str, message: str, raw: bytes, item: LocalSetItem)
A known field that could not be typed but remains available losslessly.
IMAPFieldValue
dataclass
¶
A value and selected wire length for a variable-length IMAP field.
for_precision
classmethod
¶
for_precision(tag: int, value: int | float | Fraction, precision: int | float | Fraction) -> IMAPFieldValue
Select the shortest ST 0601 IMAP length meeting precision.
ST 0107.3-09 requires variable-length IMAP values to use the fewest bytes that preserve the producer's system precision. The ST 1201 IMAPA length-selection process supplies that byte count, while the field is encoded with its ST 0601-defined IMAPB bounds.
ImageHorizonPixelPack
dataclass
¶
ImageHorizonPixelPack(start_x: int, start_y: int, end_x: int, end_y: int, start_latitude: int | float | Fraction | SpecialValue | None = None, start_longitude: int | float | Fraction | SpecialValue | None = None, end_latitude: int | float | Fraction | SpecialValue | None = None, end_longitude: int | float | Fraction | SpecialValue | None = None)
ST 0601 Item 81 horizon endpoints and optional WGS-84 coordinates.
None means an optional trailing coordinate was omitted by truncation.
:attr:SpecialValue.ERROR means the producer explicitly transmitted the
signed-int32 minimum error indicator for that coordinate.
SensorFrameRatePack
dataclass
¶
ST 0601 Item 127 frame-rate ratio encoded as BER-OID integers.
ControlCommand
dataclass
¶
ST 0601 Item 115 command record.
ControlCommandVerificationList
dataclass
¶
ST 0601 Item 116 acknowledged Control Command identifiers.
ActiveWavelengthList
dataclass
¶
ST 0601 Item 121 identifiers of wavelengths currently in use.
CountryCodes
dataclass
¶
CountryCodes(coding_method: int, overflight: str | SpecialValue, operator: str | SpecialValue | None = None, manufacture: str | SpecialValue | None = None)
ST 0601 Item 122 platform and operational country-code pack.
WavelengthRecord
dataclass
¶
WavelengthRecord(wavelength_id: int, minimum_nm: int | float | Fraction, maximum_nm: int | float | Fraction, name: str)
One custom sensor wavelength definition from ST 0601 Item 128.
WavelengthsList
dataclass
¶
WavelengthsList(records: tuple[WavelengthRecord, ...])
ST 0601 Item 128 list of custom wavelength definitions.
AirbaseLocation
dataclass
¶
AirbaseLocation(latitude: int | float | Fraction, longitude: int | float | Fraction, hae: int | float | Fraction | None = None)
One WGS-84 airbase location with optional height above ellipsoid.
AirbaseLocations
dataclass
¶
AirbaseLocations(takeoff: AirbaseLocation | SpecialValue, recovery: AirbaseLocation | SpecialValue | None = None)
ST 0601 Item 130 take-off and optional recovery locations.
PayloadRecord
dataclass
¶
One platform payload definition from ST 0601 Item 138.
PayloadList
dataclass
¶
PayloadList(total_count: int, records: tuple[PayloadRecord, ...])
A complete or distributed fragment of the ST 0601 payload table.
ActivePayloads
dataclass
¶
Payload identifiers selected in the ST 0601 Item 139 bit set.
WeaponStatus
dataclass
¶
WeaponStatus(general_status: int, fuze_enabled: bool = False, laser_enabled: bool = False, target_enabled: bool = False, weapon_armed: bool = False)
Defined general and engagement bits in an Item 140 weapon status.
WeaponStore
dataclass
¶
WeaponStore(station_id: int, hardpoint_id: int, carriage_id: int, store_id: int, status: WeaponStatus, weapon_type: str)
One physical weapon store, its status, and display type.
WeaponsStores
dataclass
¶
WeaponsStores(records: tuple[WeaponStore, ...])
Distributed list fragment carried by ST 0601 Item 140.
WaypointInfo
dataclass
¶
Control mode and creation source flags for an Item 141 waypoint.
WaypointRecord
dataclass
¶
WaypointRecord(waypoint_id: int, prosecution_order: int, info: WaypointInfo | None = None, location: AirbaseLocation | None = None)
One waypoint record from a complete or distributed waypoint list.
WaypointList
dataclass
¶
WaypointList(records: tuple[WaypointRecord, ...])
Distributed list fragment carried by ST 0601 Item 141.
ViewDomainPair
dataclass
¶
Starting angle and positive angular range for one sensor axis.
normalized_end
property
¶
Return the end angle wrapped into the circular [0, 360) domain.
ViewDomain
dataclass
¶
ViewDomain(azimuth: ViewDomainPair | SpecialValue | None = None, elevation: ViewDomainPair | SpecialValue | None = None, roll: ViewDomainPair | SpecialValue | None = None)
Azimuth, elevation, and roll limits from ST 0601 Item 142.
MetadataSubstreamID
dataclass
¶
Local or universal identifier for an Amend/Segment metadata substream.
SegmentLocalSet
dataclass
¶
SegmentLocalSet(local_set: LocalSet, fields: tuple[DecodedField, ...], substream_id: MetadataSubstreamID, issues: tuple[FieldDecodingIssue, ...] = ())
A typed ST 1607 Segment Local Set embedded in ST 0601 Item 100.
AmendLocalSet
dataclass
¶
AmendLocalSet(local_set: LocalSet, fields: tuple[DecodedField, ...], substream_id: MetadataSubstreamID, issues: tuple[FieldDecodingIssue, ...] = ())
A typed ST 1607 Amend Local Set embedded in ST 0601 Item 101.
UASLocalSet
dataclass
¶
UASLocalSet(packet: KLVPacket, local_set: LocalSet, fields: tuple[DecodedField, ...], issues: tuple[FieldDecodingIssue, ...] = ())
misp_timestamp_microseconds
property
¶
Return the exact Item 2 MISP count, without implying UTC.
effective_fields
property
¶
effective_fields: tuple[DecodedField, ...]
Fields after applying ST 0601 preferred-representation rules.
utc_timestamp ¶
Convert Item 2 to UTC using packet Items 136/137 or overrides.
Item 136 is optional on the wire, so conversion deliberately fails when neither the packet nor the caller supplies the accumulated leap-second value. Item 137 defaults to zero when absent. Explicit arguments take precedence over packet values, which lets applications use a trusted external leap-second table or post-flight correction.
preferred_field ¶
preferred_field(semantic: ST0601Semantic | str) -> ResolvedUASField | None
Resolve one logical value to its normative preferred representation.
target_elevation ¶
target_elevation() -> ResolvedTargetElevation | None
Resolve Item 42's datum from current Items 25 and 78.
imapa_length ¶
Calculate the byte length selected by the ST 1201 IMAPA process.
decode_ber_length ¶
decode_ber_length(data: Buffer, offset: int = 0, *, canonical: bool = True, max_octets: int = 8, max_value: int | None = None) -> tuple[int, int]
Decode one definite BER length, returning (value, octets_used).
decode_ber_oid ¶
decode_ber_oid(data: Buffer, offset: int = 0, *, canonical: bool = True, max_octets: int = 10, max_value: int | None = None) -> tuple[int, int]
Decode one BER-OID integer, returning (value, octets_used).
encode_ber_length ¶
Encode a non-negative length using minimal definite-form BER.
encode_ber_oid ¶
Encode a non-negative integer using minimal base-128 BER-OID form.
running_sum_16 ¶
Return the big-endian 16-bit word sum, modulo 2**16.
For an ST 0601 packet, pass every byte from the Universal Key through the Checksum item's length octet, excluding the two checksum value octets.
parse_local_set ¶
parse_local_set(data: Buffer, *, canonical: bool = True, max_item_length: int = 64 * 1024 * 1024) -> LocalSet
Parse all Local Set items while preserving byte-for-byte encodings.
decode_security_local_set ¶
decode_security_local_set(data: bytes | KLVPacket, *, standalone: bool = True, require_required: bool = True, context: SecurityMarkingContext | None = None) -> SecurityLocalSet
Decode one standalone or nested ST 0102.12 Security Metadata Local Set.
decode_rvt_local_set ¶
decode_rvt_local_set(data: bytes | KLVPacket, *, standalone: bool = True, verify_checksum: bool = True, context: RVTValidationContext | None = None) -> RVTLocalSet
Decode a standalone Universal RVT packet or an embedded LS value.
decode_vmti_local_set ¶
decode_vmti_local_set(data: bytes | KLVPacket, *, standalone: bool | None = None, verify_checksum: bool = True, max_targets: int = 100000, context: VMTIValidationContext | None = None) -> VMTILocalSet
Decode one standalone Universal KLV or embedded VMTI Local Set value.
decode_range_image_local_set ¶
decode_range_image_local_set(data: bytes | KLVPacket, *, standalone: bool = True, verify_checksum: bool = True) -> RangeImageLocalSet
Decode a standalone Universal ST 1002 packet or embedded Local Set value.
encode_range_image_local_set ¶
encode_range_image_local_set(value: RangeImageLocalSet, *, standalone: bool = True, float_width: int = 8, preserve: bool = False) -> bytes
Encode an ST 1002.3 Range Image Local Set with owned standalone CRC.
decode_sdcc_flp ¶
decode_sdcc_flp(data: bytes, *, mode1_standard_deviation_format: SDCCValueFormat | None = None, standard_deviation_imap_bounds: tuple[Real, Real] | None = None, require_mode: Literal[1, 2] | None = None, max_matrix_size: int = 1024) -> SDCCFLP
Decode one bounded ST 1010 SDCC-FLP value.
Mode 1 leaves standard-deviation atoms opaque unless the parent-defined representation is supplied. The same applies to IMAP deviations whose parent-defined bounds are unavailable.
encode_sdcc_flp ¶
encode_sdcc_flp(value: SDCCFLP) -> bytes
Encode and structurally validate one ST 1010 SDCC-FLP value.
decode_miis_core_identifier ¶
decode_miis_core_identifier(data: bytes) -> MIISCoreIdentifier
Decode and structurally validate one ST 1204.3 binary Core Identifier.
encode_miis_core_identifier ¶
encode_miis_core_identifier(core: MIISCoreIdentifier) -> bytes
Encode one ST 1204.3 Core Identifier binary value.
decode_sar_motion_imagery_local_set ¶
decode_sar_motion_imagery_local_set(data: bytes | KLVPacket, *, standalone: bool = True) -> SARMotionImageryLocalSet
Decode a standalone Universal ST 1206 packet or embedded Local Set value.
encode_sar_motion_imagery_local_set ¶
encode_sar_motion_imagery_local_set(value: SARMotionImageryLocalSet, *, standalone: bool = True, preserve: bool = False) -> bytes
Encode an ST 1206.1 standalone packet or embedded Local Set value.
decode_geo_registration_local_set ¶
decode_geo_registration_local_set(data: bytes, *, max_text_length: int = 4096) -> GeoRegistrationLocalSet
Decode an embedded ST 1601.2 Geo-Registration Local Set value.
encode_geo_registration_local_set ¶
encode_geo_registration_local_set(value: GeoRegistrationLocalSet, *, preserve: bool = False, max_text_length: int = 4096) -> bytes
Encode an embedded ST 1601.2 Geo-Registration Local Set value.
decode_composite_imaging_local_set ¶
decode_composite_imaging_local_set(data: bytes) -> CompositeImagingLocalSet
Decode an embedded ST 1602.2 Composite Imaging Local Set value.
encode_composite_imaging_local_set ¶
encode_composite_imaging_local_set(value: CompositeImagingLocalSet, *, preserve: bool = False) -> bytes
Encode an embedded ST 1602.2 Composite Imaging Local Set value.
misp_timestamp_to_utc ¶
misp_timestamp_to_utc(timestamp: int | datetime, *, leap_seconds: int, correction_offset: int = 0) -> datetime
Convert an ST 0601/MISP Precision Time Stamp coordinate to UTC.
ST 0601 Item 2 is a continuous MISP Time System count, not a UTC/POSIX
timestamp. Item 137 is added to that count before Item 136's accumulated
leap-second offset is removed. A :class:datetime input is interpreted as
the existing decoded coordinate representation of the MISP count; its
timezone.utc marker does not make the unadjusted value UTC.
utc_to_misp_timestamp ¶
Convert an aware UTC datetime to ST 0601 Item 2 microseconds.
This is the inverse of :func:misp_timestamp_to_utc for a caller-supplied
leap-second value. The returned integer is suitable for
:func:encode_uas_local_set; include the same leap-second value as Item 136
when the receiver must perform the conversion without an external table.
_branch_getall ¶
_branch_getall(fields: tuple[DecodedField, ...], tag: int) -> tuple[DecodedField, ...]
resolve_preferred_uas_field ¶
resolve_preferred_uas_field(fields: Iterable[DecodedField], semantic: ST0601Semantic | str) -> ResolvedUASField | None
Select the representation a conforming ST 0601 decoder must use.
Preference order combines the full-range, HAE, and extended-representation
rules in ST 0601.19 Section 6.1. The returned ignored fields remain
available for diagnostics and lossless round trips.
resolve_target_elevation ¶
resolve_target_elevation(fields: Iterable[DecodedField]) -> ResolvedTargetElevation | None
Interpret Item 42 using ST 0601.19 Section 8.42.1.
Item 42 is MSL when only Item 25 is receiver-current, HAE when Item 78 is
current, and HAE when both are current. Without either frame-height item,
the numeric elevation is retained but its datum is intentionally unknown.
Call this with a :class:ReportOnChangeSnapshot field set for sparse
streams so present has the standard's receiver-current meaning.
effective_uas_fields ¶
effective_uas_fields(fields: Iterable[DecodedField]) -> tuple[DecodedField, ...]
Return fields with superseded scalar representations filtered out.
_bind_sdcc_source_tags ¶
_bind_sdcc_source_tags(local_set: LocalSet, fields: tuple[DecodedField, ...]) -> tuple[DecodedField, ...]
Validate Item 102 adjacency and attach its parent Refined Source List.
_mapped ¶
_mapped(tag: int, name: str, length: int, physical_min: int | Fraction, physical_max: int | Fraction, *, units: str, signed: bool = False, special_raw: int | None = None, special_value: SpecialValue | None = None) -> FieldDefinition
_integer ¶
_integer(tag: int, name: str, length: int | None, *, units: str | None = None, signed: bool = False, minimum: int | None = None, maximum: int | None = None, maximum_length: int | None = None) -> FieldDefinition
_imap ¶
_imap(tag: int, name: str, physical_min: int, physical_max: int, *, units: str, maximum_length: int = 8) -> FieldDefinition
_integer_domain ¶
_validate_horizon_geometry ¶
_validate_horizon_geometry(start_x: int, start_y: int, end_x: int, end_y: int, *, error_type: type[Exception]) -> None
_decode_horizon_coordinate ¶
_decode_horizon_coordinate(raw: bytes, *, maximum: int) -> float | SpecialValue
decode_image_horizon_pixel_pack ¶
decode_image_horizon_pixel_pack(data: bytes) -> ImageHorizonPixelPack
Decode the truncatable ST 0601 Item 81 defined-length pack.
decode_sensor_frame_rate_pack ¶
decode_sensor_frame_rate_pack(data: bytes) -> SensorFrameRatePack
Decode the two-element truncatable ST 0601 Item 127 pack.
decode_control_command ¶
decode_control_command(data: bytes) -> ControlCommand
Decode one ST 0601 Item 115 command pack.
decode_control_command_verification_list ¶
decode_control_command_verification_list(data: bytes) -> ControlCommandVerificationList
Decode the ST 0601 Item 116 BER-OID command acknowledgement list.
_decode_ber_oid_values ¶
decode_active_wavelength_list ¶
decode_active_wavelength_list(data: bytes) -> ActiveWavelengthList
Decode the ST 0601 Item 121 BER-OID wavelength identifier list.
decode_country_codes ¶
decode_country_codes(data: bytes) -> CountryCodes
Decode the ST 0601 Item 122 country-code VLP.
decode_wavelengths_list ¶
decode_wavelengths_list(data: bytes) -> WavelengthsList
Decode the ST 0601 Item 128 VLP of wavelength-record FLPs.
decode_airbase_locations ¶
decode_airbase_locations(data: bytes) -> AirbaseLocations
Decode the ST 0601 Item 130 take-off/recovery location VLP.
_validate_payload_records ¶
_validate_payload_records(total_count: int, records: tuple[PayloadRecord, ...], *, error_type: type[Exception]) -> None
decode_payload_list ¶
decode_payload_list(data: bytes) -> PayloadList
Decode a complete or distributed ST 0601 Item 138 payload list.
decode_active_payloads ¶
decode_active_payloads(data: bytes) -> ActivePayloads
Decode the little-bit-indexed ST 0601 Item 139 payload bit set.
decode_weapons_stores ¶
decode_weapons_stores(data: bytes) -> WeaponsStores
Decode the ST 0601 Item 140 VLP of weapon-store records.
_validate_waypoint_records ¶
_validate_waypoint_records(records: tuple[WaypointRecord, ...], *, error_type: type[Exception]) -> None
decode_waypoint_list ¶
decode_waypoint_list(data: bytes) -> WaypointList
Decode the ST 0601 Item 141 VLP of waypoint records.
_decode_view_domain_pair ¶
_decode_view_domain_pair(data: bytes, *, index: int) -> ViewDomainPair | SpecialValue
decode_view_domain ¶
decode_view_domain(data: bytes) -> ViewDomain
Decode the ordered, end-truncatable ST 0601 Item 142 domain pairs.
decode_metadata_substream_id ¶
decode_metadata_substream_id(data: bytes) -> MetadataSubstreamID
Decode an Item 143 pack for use within a Segment or Amend Local Set.
_decode_metadata_branch ¶
_decode_metadata_branch(data: bytes, *, kind: Literal['segment', 'amend'], field_decoding: FieldDecodingMode, depth: int, max_depth: int) -> SegmentLocalSet | AmendLocalSet
decode_segment_local_set ¶
decode_segment_local_set(data: bytes, *, field_decoding: FieldDecodingMode = STRICT, max_depth: int = 16) -> SegmentLocalSet
Decode an ST 1607 Segment LS embedded as ST 0601 Item 100.
decode_amend_local_set ¶
decode_amend_local_set(data: bytes, *, field_decoding: FieldDecodingMode = STRICT, max_depth: int = 16) -> AmendLocalSet
Decode an ST 1607 Amend LS embedded as ST 0601 Item 101.
_decode_field ¶
_decode_field(item: LocalSetItem, definition: FieldDefinition, *, vmti_context: VMTIValidationContext | None = None) -> DecodedField
_round_fraction ¶
Round a fraction to nearest integer with ties to even.
_encode_horizon_coordinate ¶
_encode_horizon_coordinate(value: int | float | Fraction | SpecialValue, *, name: str, maximum: int) -> bytes
encode_image_horizon_pixel_pack ¶
encode_image_horizon_pixel_pack(pack: ImageHorizonPixelPack) -> bytes
Encode an ST 0601 Item 81 pack using end-only truncation.
encode_sensor_frame_rate_pack ¶
encode_sensor_frame_rate_pack(pack: SensorFrameRatePack) -> bytes
Encode ST 0601 Item 127, truncating the default denominator of one.
_encode_timestamp_value ¶
encode_control_command ¶
encode_control_command(command: ControlCommand) -> bytes
Encode one ST 0601 Item 115 command pack.
encode_control_command_verification_list ¶
encode_control_command_verification_list(acknowledgements: ControlCommandVerificationList) -> bytes
Encode an ST 0601 Item 116 command acknowledgement list.
_encode_ber_oid_values ¶
encode_active_wavelength_list ¶
encode_active_wavelength_list(wavelengths: ActiveWavelengthList) -> bytes
Encode an ST 0601 Item 121 active wavelength identifier list.
encode_country_codes ¶
encode_country_codes(countries: CountryCodes) -> bytes
Encode an ST 0601 Item 122 country-code VLP with end-only truncation.
encode_wavelengths_list ¶
encode_wavelengths_list(wavelengths: WavelengthsList) -> bytes
Encode an ST 0601 Item 128 VLP of custom wavelength definitions.
_encode_airbase_location ¶
_encode_airbase_location(location: AirbaseLocation | SpecialValue) -> bytes
encode_airbase_locations ¶
encode_airbase_locations(locations: AirbaseLocations) -> bytes
Encode an ST 0601 Item 130 VLP with canonical recovery truncation.
encode_payload_list ¶
encode_payload_list(payloads: PayloadList) -> bytes
Encode a complete or distributed ST 0601 Item 138 payload list.
encode_active_payloads ¶
encode_active_payloads(active: ActivePayloads) -> bytes
Encode ST 0601 Item 139 using payload IDs as little-indexed bits.
encode_weapons_stores ¶
encode_weapons_stores(stores: WeaponsStores) -> bytes
Encode an ST 0601 Item 140 VLP of weapon-store records.
encode_waypoint_list ¶
encode_waypoint_list(waypoints: WaypointList) -> bytes
Encode a complete or distributed ST 0601 Item 141 waypoint list.
_encode_view_domain_pair ¶
_encode_view_domain_pair(pair: ViewDomainPair | SpecialValue, *, index: int, value_length: int) -> bytes
encode_view_domain ¶
encode_view_domain(domain: ViewDomain, *, value_length: int = 3) -> bytes
Encode ST 0601 Item 142 with a configurable IMAPB precision.
encode_metadata_substream_id ¶
encode_metadata_substream_id(identifier: MetadataSubstreamID) -> bytes
Encode an Item 143 pack for use within a Segment or Amend Local Set.
_encode_metadata_branch ¶
encode_segment_local_set ¶
Encode an ST 1607 Segment LS value for ST 0601 Item 100.
encode_amend_local_set ¶
Encode an ST 1607 Amend LS value for ST 0601 Item 101.
encode_field_value ¶
Encode one currently supported ST 0601 field value.
Fixed mapped fields that define the ST 0601 Out of Range sentinel
encode that sentinel when a numeric producer value lies outside the field's
physical domain, as required by ST 0601.13-27. Other range violations remain
errors; in particular, an Off Earth condition must be supplied
explicitly because it cannot be inferred from an invalid coordinate alone.
_ordered_local_set_entries ¶
_ordered_local_set_entries(values: Mapping[int, Any], *, first_tags: tuple[int, ...] = ()) -> list[tuple[int, Any]]
_validate_metadata_birth_timestamp ¶
_validate_metadata_birth_timestamp(timestamp: object, context: ST0601ValidationContext | None, *, error_type: type[Exception]) -> None
_validate_imap_system_precision ¶
_validate_imap_system_precision(lengths: Mapping[int, int], context: ST0601ValidationContext | None, *, error_type: type[Exception]) -> None
_validate_field_expectations ¶
_validate_field_expectations(uas: UASLocalSet, context: ST0601ValidationContext | None, *, error_type: type[Exception]) -> None
_embedded_vmti_context ¶
_embedded_vmti_context(parent_timestamp: object, context: ST0601ValidationContext | None, *, error_type: type[Exception]) -> VMTIValidationContext | None
encode_uas_local_set ¶
encode_uas_local_set(values: Mapping[int, Any], *, context: ST0601ValidationContext | None = None) -> bytes
Encode supported ST 0601 fields and append the required checksum.
Tag 2 is emitted first and the computed Tag 1 checksum is emitted last. Other tags are normally numeric; Item 102 groups instead preserve each declared Refined Source List order immediately before the SDCC-FLP.
update_uas_local_set ¶
update_uas_local_set(source: bytes | UASLocalSet, updates: Mapping[int, Any | RawFieldValue | UpdateAction], *, field_decoding: FieldDecodingMode = STRICT, context: ST0601ValidationContext | None = None) -> bytes
Losslessly update selected ST 0601 items and recompute the checksum.
Untouched items retain their exact tag, length, and value octets. Updating a
repeated extension tag replaces all its occurrences with one canonical item.
Unsupported tags require :class:RawFieldValue to make raw-wire intent
explicit.
decode_uas_local_set ¶
decode_uas_local_set(data: bytes | KLVPacket, *, verify_checksum: bool = True, require_timestamp: bool = True, require_version: bool = True, field_decoding: FieldDecodingMode = STRICT, context: ST0601ValidationContext | None = None) -> UASLocalSet
Decode one ST 0601 Universal KLV packet and its known fields.
PRESERVE retains an otherwise structurally valid packet when an
individual known field cannot be decoded. The raw item remains in
local_set and a diagnostic is added to issues; checksum, required
tags, singleton rules, and Local Set structure remain strict.
stanag4609.st0601_state ¶
Stateful MISB ST 0601 Report-on-Change reconstruction.
DecodeError ¶
Bases: Stanag4609Error, ValueError
Input is complete enough to inspect but is not valid.
LimitExceeded ¶
Bases: DecodeError
A declared size exceeds a configured safety limit.
KLVPacket
dataclass
¶
A Universal KLV packet with its original length encoding.
ActivePayloads
dataclass
¶
Payload identifiers selected in the ST 0601 Item 139 bit set.
ActiveWavelengthList
dataclass
¶
ST 0601 Item 121 identifiers of wavelengths currently in use.
ControlCommand
dataclass
¶
ST 0601 Item 115 command record.
ControlCommandVerificationList
dataclass
¶
ST 0601 Item 116 acknowledged Control Command identifiers.
DecodedField
dataclass
¶
DecodedField(definition: FieldDefinition, value: Any, raw: bytes, item: LocalSetItem)
FieldDecodingIssue
dataclass
¶
FieldDecodingIssue(tag: int, name: str, message: str, raw: bytes, item: LocalSetItem)
A known field that could not be typed but remains available losslessly.
FieldDecodingMode ¶
Bases: Enum
Policy for malformed values carried by otherwise valid known fields.
PayloadList
dataclass
¶
PayloadList(total_count: int, records: tuple[PayloadRecord, ...])
A complete or distributed fragment of the ST 0601 payload table.
PayloadRecord
dataclass
¶
One platform payload definition from ST 0601 Item 138.
ResolvedTargetElevation
dataclass
¶
ResolvedTargetElevation(field: DecodedField, datum: VerticalDatum | None, frame_height: ResolvedUASField | None)
Item 42 with its receiver-visible MSL or HAE interpretation.
ResolvedUASField
dataclass
¶
ResolvedUASField(preference: RepresentationPreference, field: DecodedField, ignored: tuple[DecodedField, ...] = ())
One selected ST 0601 representation and lower-priority fields ignored.
SpecialValue ¶
Bases: Enum
Non-numeric MISB values that must remain semantically distinct.
ST0601Semantic ¶
Bases: Enum
Logical values that have multiple ST 0601 wire representations.
UASLocalSet
dataclass
¶
UASLocalSet(packet: KLVPacket, local_set: LocalSet, fields: tuple[DecodedField, ...], issues: tuple[FieldDecodingIssue, ...] = ())
misp_timestamp_microseconds
property
¶
Return the exact Item 2 MISP count, without implying UTC.
effective_fields
property
¶
effective_fields: tuple[DecodedField, ...]
Fields after applying ST 0601 preferred-representation rules.
utc_timestamp ¶
Convert Item 2 to UTC using packet Items 136/137 or overrides.
Item 136 is optional on the wire, so conversion deliberately fails when neither the packet nor the caller supplies the accumulated leap-second value. Item 137 defaults to zero when absent. Explicit arguments take precedence over packet values, which lets applications use a trusted external leap-second table or post-flight correction.
preferred_field ¶
preferred_field(semantic: ST0601Semantic | str) -> ResolvedUASField | None
Resolve one logical value to its normative preferred representation.
target_elevation ¶
target_elevation() -> ResolvedTargetElevation | None
Resolve Item 42's datum from current Items 25 and 78.
WavelengthRecord
dataclass
¶
WavelengthRecord(wavelength_id: int, minimum_nm: int | float | Fraction, maximum_nm: int | float | Fraction, name: str)
One custom sensor wavelength definition from ST 0601 Item 128.
WavelengthsList
dataclass
¶
WavelengthsList(records: tuple[WavelengthRecord, ...])
ST 0601 Item 128 list of custom wavelength definitions.
WaypointList
dataclass
¶
WaypointList(records: tuple[WaypointRecord, ...])
Distributed list fragment carried by ST 0601 Item 141.
WaypointRecord
dataclass
¶
WaypointRecord(waypoint_id: int, prosecution_order: int, info: WaypointInfo | None = None, location: AirbaseLocation | None = None)
One waypoint record from a complete or distributed waypoint list.
WeaponsStores
dataclass
¶
WeaponsStores(records: tuple[WeaponStore, ...])
Distributed list fragment carried by ST 0601 Item 140.
WeaponStore
dataclass
¶
WeaponStore(station_id: int, hardpoint_id: int, carriage_id: int, store_id: int, status: WeaponStatus, weapon_type: str)
One physical weapon store, its status, and display type.
ReportOnChangeSnapshot
dataclass
¶
ReportOnChangeSnapshot(timestamp: datetime, fields: tuple[DecodedField, ...], updated_tags: tuple[int, ...], cleared_tags: tuple[int, ...], expired_tags: tuple[int, ...], issues: tuple[FieldDecodingIssue, ...] = ())
One reconstructed receiver view after applying an ST 0601 packet.
effective_fields
property
¶
effective_fields: tuple[DecodedField, ...]
Current fields after preferred-representation rules are applied.
utc_timestamp ¶
Convert the current MISP timestamp with Items 136/137 or overrides.
preferred_field ¶
preferred_field(semantic: ST0601Semantic | str) -> ResolvedUASField | None
Resolve a current logical value to its preferred representation.
target_elevation ¶
target_elevation() -> ResolvedTargetElevation | None
Resolve current Item 42 against receiver-current Items 25 and 78.
ReportOnChangeState ¶
ReportOnChangeState(*, refresh_period: timedelta = timedelta(seconds=30), field_decoding: FieldDecodingMode = PRESERVE, max_items_per_tag: int = 1024)
Reconstruct the receiver-visible state of an ST 0601 packet stream.
Positive-length values remain current until replaced, cleared by a zero-length item, or absent for more than the configured refresh period. The standard's three mandatory packet fields are always taken from the current packet and are not subject to Report-on-Change expiry.
Multiple instances of one tag are retained and replaced as an atomic group. Standards-specific distributed-list and Segment/Amend lifecycle semantics remain the responsibility of their dedicated evaluators.
last_seen
property
¶
Return an immutable snapshot of positive-length update times.
observe ¶
observe(packet: bytes | KLVPacket | UASLocalSet) -> ReportOnChangeSnapshot
Apply one packet and return the resulting receiver-visible snapshot.
ControlCommandIssue
dataclass
¶
One ST 0601 Item 115/116 command-lifecycle violation.
ControlCommandSnapshot
dataclass
¶
ControlCommandSnapshot(timestamp: datetime, outstanding_commands: Mapping[int, ControlCommand], issued_at: Mapping[int, datetime], acknowledged_ids: tuple[int, ...], updated_ids: tuple[int, ...], newly_acknowledged_ids: tuple[int, ...], issues: tuple[ControlCommandIssue, ...] = (), field_issues: tuple[FieldDecodingIssue, ...] = ())
Current issued-command and acknowledgement receiver state.
ControlCommandState ¶
ControlCommandState(*, max_command_history: int = 65536, field_decoding: FieldDecodingMode = PRESERVE)
Validate the cross-packet lifecycle of ST 0601 Items 115 and 116.
A newly issued command ID must increase beyond every earlier command ID. Repetitions retain the original command text and effective issue time. An Item 116 acknowledgement closes its referenced command, after which Item 115 must not repeat it. History is intentionally bounded so hostile or indefinitely long streams cannot grow receiver memory without limit.
observe ¶
observe(packet: bytes | KLVPacket | UASLocalSet) -> ControlCommandSnapshot
Apply one packet and return the resulting command lifecycle.
WavelengthTableIssue
dataclass
¶
One cross-packet ST 0601 wavelength-table violation.
WavelengthTableSnapshot
dataclass
¶
WavelengthTableSnapshot(timestamp: datetime, custom_records: Mapping[int, WavelengthRecord], active_ids: tuple[int, ...] | None, updated_ids: tuple[int, ...], expired_ids: tuple[int, ...], cleared_custom_table: bool, active_expired: bool, active_cleared: bool, issues: tuple[WavelengthTableIssue, ...] = (), field_issues: tuple[FieldDecodingIssue, ...] = ())
Current custom table and active wavelength selection.
known_ids
property
¶
Return predefined IDs 0..6 followed by current custom IDs.
WavelengthTableState ¶
WavelengthTableState(*, refresh_period: timedelta = timedelta(seconds=30), max_custom_records: int = 4096, field_decoding: FieldDecodingMode = PRESERVE)
Reconstruct distributed ST 0601 Items 121/128 receiver state.
Custom wavelength records are keyed by their IDs and expire independently. Active IDs are checked against predefined IDs 0..6 and custom records defined within the current refresh window.
observe ¶
observe(packet: bytes | KLVPacket | UASLocalSet) -> WavelengthTableSnapshot
Apply one ST 0601 packet and validate its current wavelength references.
PayloadTableIssue
dataclass
¶
One cross-packet ST 0601 payload-table violation.
PayloadTableSnapshot
dataclass
¶
PayloadTableSnapshot(timestamp: datetime, total_count: int | None, records: Mapping[int, PayloadRecord], active_ids: frozenset[int] | None, updated_ids: tuple[int, ...], expired_ids: tuple[int, ...], table_restarted: bool, table_cleared: bool, table_expired: bool, active_cleared: bool, active_expired: bool, issues: tuple[PayloadTableIssue, ...] = (), field_issues: tuple[FieldDecodingIssue, ...] = ())
PayloadTableState ¶
PayloadTableState(*, refresh_period: timedelta = timedelta(seconds=30), max_payload_records: int = 4096, field_decoding: FieldDecodingMode = PRESERVE)
Reconstruct distributed ST 0601 Items 138/139 receiver state.
observe ¶
observe(packet: bytes | KLVPacket | UASLocalSet) -> PayloadTableSnapshot
Apply one packet and validate Item 139 against current Item 138 records.
WeaponsStoresSnapshot
dataclass
¶
WeaponsStoresSnapshot(timestamp: datetime, records: Mapping[tuple[int, int, int, int], WeaponStore], updated_addresses: tuple[tuple[int, int, int, int], ...], expired_addresses: tuple[tuple[int, int, int, int], ...], cleared: bool, field_issues: tuple[FieldDecodingIssue, ...] = ())
Current receiver view of the distributed Item 140 stores list.
WeaponsStoresState ¶
WeaponsStoresState(*, refresh_period: timedelta = timedelta(seconds=30), max_weapon_records: int = 4096, field_decoding: FieldDecodingMode = PRESERVE)
Reconstruct distributed ST 0601 Item 140 receiver state.
A weapon record's four-part physical address is its identity. Records sent in separate packets merge into one receiver list, updates replace the record at the same address, and each address expires independently.
observe ¶
observe(packet: bytes | KLVPacket | UASLocalSet) -> WeaponsStoresSnapshot
Apply one packet and return the reconstructed Weapons Stores list.
WaypointListIssue
dataclass
¶
One cross-packet ST 0601 waypoint-list violation.
WaypointListSnapshot
dataclass
¶
WaypointListSnapshot(timestamp: datetime, records: Mapping[int, WaypointRecord], updated_ids: tuple[int, ...], expired_ids: tuple[int, ...], cleared: bool, order_conflicts: Mapping[int, tuple[int, ...]], issues: tuple[WaypointListIssue, ...] = (), field_issues: tuple[FieldDecodingIssue, ...] = ())
Current distributed Item 141 waypoint list and derived order views.
current_ids
property
¶
Return all current IDs; distributed reordering may expose more than one.
planned_ids
property
¶
Return planned IDs ordered by prosecution order and then ID.
historical_ids
property
¶
Return historical IDs with the most recently assigned order first.
cancelled_ids
property
¶
Return IDs carrying the repeatable 0x7FFF cancellation marker.
WaypointListState ¶
WaypointListState(*, refresh_period: timedelta = timedelta(seconds=30), max_waypoint_records: int = 4096, field_decoding: FieldDecodingMode = PRESERVE)
Reconstruct distributed ST 0601 Item 141 receiver state by Waypoint ID.
observe ¶
observe(packet: bytes | KLVPacket | UASLocalSet) -> WaypointListSnapshot
Apply one packet and return the reconstructed Waypoint List.
decode_uas_local_set ¶
decode_uas_local_set(data: bytes | KLVPacket, *, verify_checksum: bool = True, require_timestamp: bool = True, require_version: bool = True, field_decoding: FieldDecodingMode = STRICT, context: ST0601ValidationContext | None = None) -> UASLocalSet
Decode one ST 0601 Universal KLV packet and its known fields.
PRESERVE retains an otherwise structurally valid packet when an
individual known field cannot be decoded. The raw item remains in
local_set and a diagnostic is added to issues; checksum, required
tags, singleton rules, and Local Set structure remain strict.
effective_uas_fields ¶
effective_uas_fields(fields: Iterable[DecodedField]) -> tuple[DecodedField, ...]
Return fields with superseded scalar representations filtered out.
misp_timestamp_to_utc ¶
misp_timestamp_to_utc(timestamp: int | datetime, *, leap_seconds: int, correction_offset: int = 0) -> datetime
Convert an ST 0601/MISP Precision Time Stamp coordinate to UTC.
ST 0601 Item 2 is a continuous MISP Time System count, not a UTC/POSIX
timestamp. Item 137 is added to that count before Item 136's accumulated
leap-second offset is removed. A :class:datetime input is interpreted as
the existing decoded coordinate representation of the MISP count; its
timezone.utc marker does not make the unadjusted value UTC.
resolve_preferred_uas_field ¶
resolve_preferred_uas_field(fields: Iterable[DecodedField], semantic: ST0601Semantic | str) -> ResolvedUASField | None
Select the representation a conforming ST 0601 decoder must use.
Preference order combines the full-range, HAE, and extended-representation
rules in ST 0601.19 Section 6.1. The returned ignored fields remain
available for diagnostics and lossless round trips.
resolve_target_elevation ¶
resolve_target_elevation(fields: Iterable[DecodedField]) -> ResolvedTargetElevation | None
Interpret Item 42 using ST 0601.19 Section 8.42.1.
Item 42 is MSL when only Item 25 is receiver-current, HAE when Item 78 is
current, and HAE when both are current. Without either frame-height item,
the numeric elevation is retained but its datum is intentionally unknown.
Call this with a :class:ReportOnChangeSnapshot field set for sparse
streams so present has the standard's receiver-current meaning.
ST 0603 MISP timestamp conversion¶
Use the standard's integer mapping when converting between Nano Precision and Precision Time Stamp representations. The nanosecond-to-microsecond direction uses ST 0603.5's required half-up rule rather than Python's bankers rounding.
from stanag4609 import nano_precision_to_precision_timestamp
microseconds = nano_precision_to_precision_timestamp(9_572_831)
assert microseconds == 9_573
stanag4609.st0603 ¶
MISB ST 0603.5 MISP timestamp representations and conversions.
__all__
module-attribute
¶
nano_precision_to_precision_timestamp ¶
Convert an ST 0603 Nano Precision Time Stamp to microseconds.
ST 0603.5 section 7.3 requires integer half-up rounding: add 500 nanoseconds, then divide by 1000. The conversion is lossy.
precision_to_nano_precision_timestamp ¶
Convert an ST 0603 Precision Time Stamp to exact nanoseconds.
The result remains a timestamp representation and therefore must fit the unsigned 64-bit domain defined by ST 0603.5.
stanag4609.st1607_state ¶
Stateful ST 1607 Segment and Amend hierarchy evaluation.
DecodeError ¶
Bases: Stanag4609Error, ValueError
Input is complete enough to inspect but is not valid.
LimitExceeded ¶
Bases: DecodeError
A declared size exceeds a configured safety limit.
KLVPacket
dataclass
¶
A Universal KLV packet with its original length encoding.
SecurityField
dataclass
¶
SecurityField(tag: int, name: str, value: Any, raw: bytes, item: LocalSetItem | KLVPacket)
SecurityLocalSet
dataclass
¶
SecurityLocalSet(packet: KLVPacket | None, local_set: LocalSet, fields: tuple[SecurityField, ...], standalone: bool)
Decoded standalone or ST 0601-embedded Security Metadata Local Set.
AmendLocalSet
dataclass
¶
AmendLocalSet(local_set: LocalSet, fields: tuple[DecodedField, ...], substream_id: MetadataSubstreamID, issues: tuple[FieldDecodingIssue, ...] = ())
A typed ST 1607 Amend Local Set embedded in ST 0601 Item 101.
DecodedField
dataclass
¶
DecodedField(definition: FieldDefinition, value: Any, raw: bytes, item: LocalSetItem)
FieldDecodingIssue
dataclass
¶
FieldDecodingIssue(tag: int, name: str, message: str, raw: bytes, item: LocalSetItem)
A known field that could not be typed but remains available losslessly.
FieldDecodingMode ¶
Bases: Enum
Policy for malformed values carried by otherwise valid known fields.
MetadataSubstreamID
dataclass
¶
Local or universal identifier for an Amend/Segment metadata substream.
SegmentLocalSet
dataclass
¶
SegmentLocalSet(local_set: LocalSet, fields: tuple[DecodedField, ...], substream_id: MetadataSubstreamID, issues: tuple[FieldDecodingIssue, ...] = ())
A typed ST 1607 Segment Local Set embedded in ST 0601 Item 100.
SpecialValue ¶
Bases: Enum
Non-numeric MISB values that must remain semantically distinct.
UASLocalSet
dataclass
¶
UASLocalSet(packet: KLVPacket, local_set: LocalSet, fields: tuple[DecodedField, ...], issues: tuple[FieldDecodingIssue, ...] = ())
misp_timestamp_microseconds
property
¶
Return the exact Item 2 MISP count, without implying UTC.
effective_fields
property
¶
effective_fields: tuple[DecodedField, ...]
Fields after applying ST 0601 preferred-representation rules.
utc_timestamp ¶
Convert Item 2 to UTC using packet Items 136/137 or overrides.
Item 136 is optional on the wire, so conversion deliberately fails when neither the packet nor the caller supplies the accumulated leap-second value. Item 137 defaults to zero when absent. Explicit arguments take precedence over packet values, which lets applications use a trusted external leap-second table or post-flight correction.
preferred_field ¶
preferred_field(semantic: ST0601Semantic | str) -> ResolvedUASField | None
Resolve one logical value to its normative preferred representation.
target_elevation ¶
target_elevation() -> ResolvedTargetElevation | None
Resolve Item 42's datum from current Items 25 and 78.
ReportOnChangeSnapshot
dataclass
¶
ReportOnChangeSnapshot(timestamp: datetime, fields: tuple[DecodedField, ...], updated_tags: tuple[int, ...], cleared_tags: tuple[int, ...], expired_tags: tuple[int, ...], issues: tuple[FieldDecodingIssue, ...] = ())
One reconstructed receiver view after applying an ST 0601 packet.
effective_fields
property
¶
effective_fields: tuple[DecodedField, ...]
Current fields after preferred-representation rules are applied.
utc_timestamp ¶
Convert the current MISP timestamp with Items 136/137 or overrides.
preferred_field ¶
preferred_field(semantic: ST0601Semantic | str) -> ResolvedUASField | None
Resolve a current logical value to its preferred representation.
target_elevation ¶
target_elevation() -> ResolvedTargetElevation | None
Resolve current Item 42 against receiver-current Items 25 and 78.
ReportOnChangeState ¶
ReportOnChangeState(*, refresh_period: timedelta = timedelta(seconds=30), field_decoding: FieldDecodingMode = PRESERVE, max_items_per_tag: int = 1024)
Reconstruct the receiver-visible state of an ST 0601 packet stream.
Positive-length values remain current until replaced, cleared by a zero-length item, or absent for more than the configured refresh period. The standard's three mandatory packet fields are always taken from the current packet and are not subject to Report-on-Change expiry.
Multiple instances of one tag are retained and replaced as an atomic group. Standards-specific distributed-list and Segment/Amend lifecycle semantics remain the responsibility of their dedicated evaluators.
last_seen
property
¶
Return an immutable snapshot of positive-length update times.
observe ¶
observe(packet: bytes | KLVPacket | UASLocalSet) -> ReportOnChangeSnapshot
Apply one packet and return the resulting receiver-visible snapshot.
MISMMSecurityContext
dataclass
¶
MISMMSecurityContext(sci_shi: bool = False, caveats: bool = False, releasing_instructions: bool = False, expected_classification: SecurityClassification | None = None, expected_country_coding_method: CountryCodingMethod | None = None, expected_classifying_country: str | None = None, expected_sci_shi: str | None = None, expected_caveats: str | None = None, required_releasing_countries: frozenset[str] = frozenset(), expected_object_country_coding_method: ObjectCountryCodingMethod | None = None, required_object_countries: frozenset[str] = frozenset(), minimum_security_metadata_version: int | None = None)
Declare which context-dependent ST 0102 markings apply to a stream.
ST 0902 Table 1 includes Security Local Set Items 4, 5, and 6, while ST 0102 makes each mandatory only when the corresponding marking applies. The default therefore requires the six unconditional Security sub-items without inventing mission-specific security policy.
MIISCoreIdentifier
dataclass
¶
MIISCoreIdentifier(version: int, sensor_quality: IdentifierQuality = NONE, platform_quality: IdentifierQuality = NONE, sensor_id: UUID | None = None, platform_id: UUID | None = None, window_id: UUID | None = None, minor_id: UUID | None = None, raw: bytes = b'')
A typed ST 1204.3 binary Core Identifier value.
GeoRegistrationLocalSet
dataclass
¶
GeoRegistrationLocalSet(document_version: int, algorithm_name: str, algorithm_version: str, row_column: MDAP | None = None, latitude_longitude: MDAP | None = None, second_image_name: str | None = None, algorithm_configuration_id: UUID | None = None, elevation: MDAP | None = None, pixel_uncertainty: HeterogeneousIMAPArray | None = None, geo_uncertainty: HeterogeneousIMAPArray | None = None, extensions: Mapping[int, RawGeoRegistrationValue] = dict(), local_set: LocalSet | None = None)
Typed ST 1601.2 value embedded in a contextual parent Local Set.
CompositeImagingLocalSet
dataclass
¶
CompositeImagingLocalSet(document_version: int, sub_image_rows: int, sub_image_columns: int, sub_image_position_x: int, sub_image_position_y: int, z_order: int, timestamp: datetime | None = None, source_image_rows: int | None = None, source_image_columns: int | None = None, source_aoi_rows: int | None = None, source_aoi_columns: int | None = None, source_aoi_position_x: int | None = None, source_aoi_position_y: int | None = None, active_rows: int | None = None, active_columns: int | None = None, active_offset_x: int | None = None, active_offset_y: int | None = None, transparency: int = 0, extensions: Mapping[int, RawCompositeValue] = dict(), local_set: LocalSet | None = None)
One source/sub-image mapping embedded in an ST 1607 segment.
MetadataBranchKind ¶
Bases: str, Enum
ST 1607 child operation represented by a metadata branch.
MetadataBranchSnapshot
dataclass
¶
MetadataBranchSnapshot(path: MetadataSubstreamPath, kind: MetadataBranchKind, fields: tuple[DecodedField, ...], updated_tags: tuple[int, ...], cleared_tags: tuple[int, ...], expired_tags: tuple[int, ...], field_issues: tuple[FieldDecodingIssue, ...] = ())
Current Report-on-Change state for one identified metadata branch.
MetadataTreeSnapshot
dataclass
¶
MetadataTreeSnapshot(timestamp: datetime, root: ReportOnChangeSnapshot, branches: Mapping[MetadataSubstreamPath, MetadataBranchSnapshot], expired_paths: tuple[MetadataSubstreamPath, ...])
Receiver-visible root and identified ST 1607 branch hierarchy.
effective_fields ¶
effective_fields(path: MetadataSubstreamPath = ()) -> tuple[DecodedField, ...]
Apply each Segment/Amend overlay along path to root state.
effective_composite_timestamp ¶
effective_composite_timestamp(path: MetadataSubstreamPath) -> datetime
Resolve ST 1602 Item 1, inheriting the parent timestamp when omitted.
effective_geo_registration ¶
effective_geo_registration(path: MetadataSubstreamPath = ()) -> GeoRegistrationLocalSet | None
Resolve the ST 1601 result effective at an ST 1607 branch path.
Parallel Amend Local Sets carry distinct geo-registration results under their Metadata Substream Identifier paths. Report-on-Change inheritance and deletion are applied before returning the typed Item 98 value.
effective_security ¶
effective_security(path: MetadataSubstreamPath = ()) -> Mapping[int, SecurityField] | None
Return root security with branch-specific country fields overlaid.
ST1607PolicyIssue
dataclass
¶
ST1607PolicyIssue(code: str, requirement: str, message: str, path: MetadataSubstreamPath, tags: tuple[int, ...] = ())
One ST 1607 hierarchy policy violation.
_BranchState
dataclass
¶
_BranchState(kind: MetadataBranchKind, fields: dict[int, tuple[DecodedField, ...]], field_seen: dict[int, datetime], observed_at: datetime)
MetadataTreeState ¶
MetadataTreeState(*, refresh_period: timedelta = timedelta(seconds=30), max_branches: int = 1024, max_fields_per_branch: int = 1024, field_decoding: FieldDecodingMode = PRESERVE)
Reconstruct and evaluate ST 1607 substreams carried by ST 0601.
decode_uas_local_set ¶
decode_uas_local_set(data: bytes | KLVPacket, *, verify_checksum: bool = True, require_timestamp: bool = True, require_version: bool = True, field_decoding: FieldDecodingMode = STRICT, context: ST0601ValidationContext | None = None) -> UASLocalSet
Decode one ST 0601 Universal KLV packet and its known fields.
PRESERVE retains an otherwise structurally valid packet when an
individual known field cannot be decoded. The raw item remains in
local_set and a diagnostic is added to issues; checksum, required
tags, singleton rules, and Local Set structure remain strict.
validate_mismms_current_state ¶
validate_mismms_current_state(fields: Iterable[DecodedField] | UASLocalSet, *, field_issues: Iterable[FieldDecodingIssue] = (), require_security: bool = True, require_miis: bool = True, security_context: MISMMSecurityContext | None = None, effective_security: Mapping[int, object] | None = None) -> tuple[MISMMSValidationIssue, ...]
Validate a reconstructed current ST 0902 minimum-metadata view.
A :class:UASLocalSet carries its preserve-mode diagnostics automatically.
When passing a reconstructed field iterable, also pass the corresponding
receiver-state field_issues. Malformed known fields are intentionally
absent from the decoded field collection; retaining their diagnostics
distinguishes invalid population from an item that was never populated.
validate_st1602_composite ¶
validate_st1602_composite(snapshot: MetadataTreeSnapshot) -> tuple[ST1607PolicyIssue, ...]
Validate cross-segment ST 1602 composite-image requirements.
validate_st1607_security ¶
validate_st1607_security(snapshot: MetadataTreeSnapshot) -> tuple[ST1607PolicyIssue, ...]
Validate child security overrides required by ST 1607 Section 9.
validate_st1607_mismms ¶
validate_st1607_mismms(snapshot: MetadataTreeSnapshot, *, require_security: bool = True, require_miis: bool = True, security_context: MISMMSecurityContext | None = None) -> tuple[ST1607PolicyIssue, ...]
Validate MISP/ST 0902 completeness at ST 1607-required tree levels.
_walk_branch ¶
_walk_branch(source: SegmentLocalSet | AmendLocalSet, parent_path: MetadataSubstreamPath, kind: MetadataBranchKind, result: list[tuple[MetadataSubstreamPath, MetadataBranchKind, SegmentLocalSet | AmendLocalSet]]) -> None
ST 0806 RVT metadata embedded by Item 73¶
Independent RVT packets carry their own timestamp and CRC-32. Embedded Item 73
values omit the Universal Key, outer length, and CRC. Supply
RVTValidationContext when producer-known metadata time of birth is available;
the codec fails rather than silently treating an absent or mismatched timestamp
as externally assured.
from datetime import datetime, timezone
from stanag4609 import RVTValidationContext, decode_rvt_local_set
context = RVTValidationContext(
metadata_birth_timestamp=datetime(2024, 1, 2, tzinfo=timezone.utc),
)
rvt = decode_rvt_local_set(independent_rvt_packet, context=context)
stanag4609.st0806 ¶
MISB ST 0806.4 Remote Video Terminal Local Set codecs.
RVT_LOCAL_SET_KEY
module-attribute
¶
POI_LOCAL_SET_KEY
module-attribute
¶
AOI_LOCAL_SET_KEY
module-attribute
¶
USER_DEFINED_LOCAL_SET_KEY
module-attribute
¶
_RVT_DEFINITIONS
module-attribute
¶
_RVT_DEFINITIONS = {1: _Definition('CRC-32', 'uint', 4), 2: _Definition('Precision Time Stamp', 'timestamp', 8), 3: _Definition('Platform True Airspeed', 'uint', 2), 4: _Definition('Platform Indicated Airspeed', 'uint', 2), 5: _Definition('Telemetry Accuracy Indicator', 'uint', 1), 6: _Definition('Frag Circle Radius', 'uint', 2), 7: _Definition('Frame Code', 'uint', 4), 8: _Definition('RVT LS Version Number', 'uint', 1), 9: _Definition('Video Data Rate', 'uint', 4), 10: _Definition('Digital Video File Format', 'text', maximum_length=127), 11: _Definition('User Defined Local Set', 'user'), 12: _Definition('Point of Interest Local Set', 'poi'), 13: _Definition('Area of Interest Local Set', 'aoi'), 14: _Definition('MGRS Zone', 'uint', 1, 1, 60), 15: _Definition('MGRS Latitude Band and Grid Square', 'mgrs_grid', 3), 16: _Definition('MGRS Easting', 'uint', 3, 0, 99999), 17: _Definition('MGRS Northing', 'uint', 3, 0, 99999), 18: _Definition('MGRS Zone Second Value', 'uint', 1, 1, 60), 19: _Definition('MGRS Latitude Band and Grid Square Second Value', 'mgrs_grid', 3), 20: _Definition('MGRS Easting Second Value', 'uint', 3, 0, 99999), 21: _Definition('MGRS Northing Second Value', 'uint', 3, 0, 99999)}
_POI_DEFINITIONS
module-attribute
¶
_POI_DEFINITIONS = {1: _Definition('POI/AOI Number', 'uint', 2), 2: _Definition('POI Latitude', 'latitude', 4), 3: _Definition('POI Longitude', 'longitude', 4), 4: _Definition('POI Altitude', 'altitude', 2), 5: _Definition('POI/AOI Type', 'uint', 1, 1, 4), 6: _Definition('POI/AOI Text', 'text', maximum_length=2048), 7: _Definition('POI Source Icon', 'text', maximum_length=127), 8: _Definition('POI/AOI Source ID', 'text', maximum_length=255), 9: _Definition('POI/AOI Label', 'text', 16), 10: _Definition('Operation ID', 'text', maximum_length=127)}
_AOI_DEFINITIONS
module-attribute
¶
_AOI_DEFINITIONS = {1: _Definition('POI/AOI Number', 'uint', 2), 2: _Definition('Corner Latitude Point 1', 'latitude', 4), 3: _Definition('Corner Longitude Point 1', 'longitude', 4), 4: _Definition('Corner Latitude Point 3', 'latitude', 4), 5: _Definition('Corner Longitude Point 3', 'longitude', 4), 6: _Definition('POI/AOI Type', 'uint', 1, 1, 4), 7: _Definition('POI/AOI Text', 'text', maximum_length=2048), 8: _Definition('POI/AOI Source ID', 'text', maximum_length=255), 9: _Definition('POI/AOI Label', 'text', 16), 10: _Definition('Operation ID', 'text', maximum_length=127)}
ChecksumError ¶
Bases: DecodeError
A checksum is absent, misplaced, malformed, or incorrect.
DecodeError ¶
Bases: Stanag4609Error, ValueError
Input is complete enough to inspect but is not valid.
KLVPacket
dataclass
¶
A Universal KLV packet with its original length encoding.
LocalSet
dataclass
¶
LocalSet(items: tuple[LocalSetItem, ...], raw: bytes)
Ordered Local Set items; duplicate and unknown tags are preserved.
LocalSetItem
dataclass
¶
One Local Set item, preserving the exact tag and length octets.
KLVStreamParser ¶
KLVStreamParser(*, key_length: int = 16, key_prefix: bytes | None = b'\x06\x0e+4', canonical: bool = True, recover: bool = False, max_value_length: int = 64 * 1024 * 1024, validate_smpte_keys: bool | None = None)
Incrementally reconstruct fixed-width-key KLV packets.
Input chunks may split the key, BER length, or value at any byte boundary. Completed bytes are released immediately, and declared values are bounded.
RVTErrorValue ¶
Bases: Enum
Explicit ST 0806 geolocation error indicator.
RVTUserDataType ¶
Bases: Enum
Type selected by the two high bits of User Defined LS Item 1.
RVTValidationContext
dataclass
¶
Producer facts needed to validate contextual ST 0806 semantics.
RawRVTValue
dataclass
¶
Explicit bytes for an extension item that ST 0806 does not define.
RVTPointOfInterest
dataclass
¶
RVTUserDefinedData
dataclass
¶
RVTUserDefinedData(identifier: int, data_type: RVTUserDataType, value: str | int | bytes, value_length: int | None = None)
RVTLocalSet
dataclass
¶
RVTLocalSet(packet: KLVPacket | None, local_set: LocalSet, fields: tuple[RVTField, ...], standalone: bool)
_Definition
dataclass
¶
_Definition(name: str, kind: Literal['uint', 'timestamp', 'text', 'mgrs_grid', 'latitude', 'longitude', 'altitude', 'poi', 'aoi', 'user'], length: int | None = None, minimum: int | None = None, maximum: int | None = None, maximum_length: int | None = None)
encode_ber_length ¶
Encode a non-negative length using minimal definite-form BER.
encode_ber_oid ¶
Encode a non-negative integer using minimal base-128 BER-OID form.
parse_local_set ¶
parse_local_set(data: Buffer, *, canonical: bool = True, max_item_length: int = 64 * 1024 * 1024) -> LocalSet
Parse all Local Set items while preserving byte-for-byte encodings.
_decode_mapped ¶
_decode_mapped(data: bytes, minimum: int, maximum: int, *, signed: bool, error_code: int | None = None) -> float | RVTErrorValue
_encode_mapped ¶
_encode_mapped(value: int | float | Fraction | RVTErrorValue, length: int, minimum: int, maximum: int, *, signed: bool, error_code: int | None = None) -> bytes
_ensure_unique ¶
_ensure_unique(local_set: LocalSet, *, repeated: frozenset[int] = frozenset()) -> None
_decode_subordinate ¶
_decode_subordinate(data: bytes, definitions: dict[int, _Definition], required: frozenset[int], *, kind: Literal['POI', 'AOI']) -> RVTPointOfInterest | RVTAreaOfInterest
decode_point_of_interest ¶
decode_point_of_interest(data: bytes) -> RVTPointOfInterest
Decode an ST 0806 Point of Interest Local Set value.
decode_area_of_interest ¶
decode_area_of_interest(data: bytes) -> RVTAreaOfInterest
Decode an ST 0806 Area of Interest Local Set value.
decode_user_defined_data ¶
decode_user_defined_data(data: bytes) -> RVTUserDefinedData
Decode the exact two-item ST 0806 User Defined Local Set.
_encode_subordinate ¶
_encode_subordinate(values: Mapping[int, Any], definitions: dict[int, _Definition], required: frozenset[int], *, kind: Literal['POI', 'AOI']) -> bytes
encode_point_of_interest ¶
Encode one ST 0806 Point of Interest Local Set value.
encode_area_of_interest ¶
Encode one ST 0806 Area of Interest Local Set value.
encode_user_defined_data ¶
encode_user_defined_data(record: RVTUserDefinedData) -> bytes
Encode the exact two-item ST 0806 User Defined Local Set.
_validate_metadata_birth_timestamp ¶
_validate_metadata_birth_timestamp(timestamp: bytes | None, context: RVTValidationContext | None, *, error_type: type[Exception]) -> None
decode_rvt_local_set ¶
decode_rvt_local_set(data: bytes | KLVPacket, *, standalone: bool = True, verify_checksum: bool = True, context: RVTValidationContext | None = None) -> RVTLocalSet
Decode a standalone Universal RVT packet or an embedded LS value.
encode_rvt_local_set ¶
encode_rvt_local_set(values: Mapping[int, Any], *, standalone: bool = True, context: RVTValidationContext | None = None) -> bytes
Encode an ST 0806 RVT Local Set, owning the standalone CRC item.