Struct Annotation 

pub struct Annotation {
    pub sample_start: Integer,
    pub sample_count: Option<Integer>,
    pub freq_lower_edge: Option<Number>,
    pub freq_upper_edge: Option<Number>,
    pub label: Option<String>,
    pub comment: Option<String>,
    pub generator: Option<String>,
    pub uuid: Option<String>,
    /* private fields */
}

A single entry of the SigMF annotations array.

Optional core fields are stored as Options and are omitted from serialized JSON when None. Unknown keys encountered during deserialization (typically extension fields) are retained and serialized back out unchanged; see Annotation::extra_fields and Annotation::insert_extra.

Prefer Annotation::builder, which checks frequency bounds, over Annotation::new, which performs no validation.

Fields

sample_start: Integer

Index of the first sample covered by this annotation (core:sample_start).

sample_count: Option<Integer>

Number of samples covered by this annotation (core:sample_count).

Per the SigMF specification, an absent value means the annotation extends to the end of the recording.

freq_lower_edge: Option<Number>

Lower edge of the annotated feature’s frequency range in Hz (core:freq_lower_edge).

freq_upper_edge: Option<Number>

Upper edge of the annotated feature’s frequency range in Hz (core:freq_upper_edge).

label: Option<String>

Short human-readable label for the annotation (core:label).

comment: Option<String>

Free-text human-readable comment (core:comment).

generator: Option<String>

Name of the entity (person or software) that created the annotation (core:generator).

uuid: Option<String>

RFC 4122 UUID identifying this annotation (core:uuid).

Implementations

impl Annotation

pub fn builder(sample_start: Integer) -> AnnotationBuilder

Starts building an Annotation that begins at sample_start (core:sample_start).

Equivalent to AnnotationBuilder::new.

Examples

use sigmf::annotation::Annotation;

let annotation = Annotation::builder(4096)
    .sample_count(1024)
    .frequency_range(2.400e9, 2.402e9)
    .label("burst")
    .build()?;
assert_eq!(annotation.get_sample_start(), 4096);
assert_eq!(annotation.get_sample_count(), Some(1024));

let json = serde_json::to_value(&annotation)?;
assert_eq!(json["core:label"], "burst");
assert!(json.get("core:comment").is_none());

pub fn new( sample_start: Integer, sample_count: Option<Integer>, freq_lower_edge: Option<Number>, freq_upper_edge: Option<Number>, label: Option<String>, comment: Option<String>, generator: Option<String>, uuid: Option<String>, ) -> Self

Creates an Annotation directly from all of its core fields, with no extra fields.

Unlike AnnotationBuilder::build, this performs no validation; in particular, frequency bounds are not checked for finiteness, ordering, or being supplied together.

Examples

use sigmf::annotation::Annotation;

let annotation = Annotation::new(
    0,
    Some(1000),
    None,
    None,
    Some("preamble".to_string()),
    None,
    Some("my-detector".to_string()),
    None,
);
assert_eq!(annotation.get_label().as_deref(), Some("preamble"));
assert!(annotation.extra_fields().is_empty());

pub fn extra_fields(&self) -> &Map<String, Value>

Returns the fields of this annotation that are not modeled by a typed field, keyed by their full JSON key.

These are the keys that did not map to a typed field during deserialization (typically extension fields), plus any added via Annotation::insert_extra. They are serialized alongside the typed core fields.

pub fn insert_extra( &mut self, key: impl Into<String>, value: Value, ) -> Result<Option<Value>, String>

Inserts or replaces an extra (non-typed) field, returning the previous value for key if one was present.

The key is stored as given; namespace syntax and extension declarations are not checked here (see crate::validation).

Errors

Returns an error message if key is one of the core: annotation keys modeled by a typed field on Annotation (for example core:sample_start); set those through the corresponding field or setter instead.

pub fn set_sample_start(&mut self, sample_start: Integer)

Sets the index of the first annotated sample (core:sample_start).

pub fn set_sample_count(&mut self, sample_count: Integer)

Sets the number of annotated samples (core:sample_count).

pub fn set_freq_lower_edge(&mut self, freq_lower_edge: Number)

Sets the lower frequency edge in Hz (core:freq_lower_edge).

The value is not validated against the upper edge.

pub fn set_freq_upper_edge(&mut self, freq_upper_edge: Number)

Sets the upper frequency edge in Hz (core:freq_upper_edge).

The value is not validated against the lower edge.

pub fn set_label(&mut self, label: String)

Sets the short human-readable label (core:label).

pub fn set_comment(&mut self, comment: String)

Sets the free-text comment (core:comment).

pub fn set_generator(&mut self, generator: String)

Sets the name of the annotation’s creator (core:generator).

pub fn set_uuid(&mut self, uuid: String)

Sets the annotation UUID (core:uuid).

The value is stored as given; it is not checked to be a valid UUID.

pub fn get_sample_start(&self) -> Integer

Returns the index of the first annotated sample (core:sample_start).

pub fn get_sample_count(&self) -> Option<Integer>

Returns the number of annotated samples (core:sample_count), if set.

pub fn get_freq_lower_edge(&self) -> Option<Number>

Returns the lower frequency edge in Hz (core:freq_lower_edge), if set.

pub fn get_freq_upper_edge(&self) -> Option<Number>

Returns the upper frequency edge in Hz (core:freq_upper_edge), if set.

pub fn get_label(&self) -> Option<String>

Returns a copy of the label (core:label), if set.

pub fn get_comment(&self) -> Option<String>

Returns a copy of the comment (core:comment), if set.

pub fn get_generator(&self) -> Option<String>

Returns a copy of the creator name (core:generator), if set.

pub fn get_uuid(&self) -> Option<String>

Returns a copy of the annotation UUID (core:uuid), if set.

impl Annotation

pub fn extension<T: SigmfExtension>(&self) -> Result<T, SigmfError>

Reads extension T from this annotation’s fields.

Only the keys listed in SigmfExtension::FIELDS are considered; absent keys are simply omitted before deserialization.

Errors

Returns SigmfError::InvalidMetadata if T’s scope is not ExtensionScope::Annotation or the fields do not deserialize into T.

pub fn set_extension<T: SigmfExtension>( &mut self, extension: &T, ) -> Result<(), SigmfError>

Writes extension T into this annotation.

All of T’s declared FIELDS are first removed, then the serialized fields are inserted, so fields omitted by serialization are cleared. core:extensions is not modified.

Errors

Returns SigmfError::InvalidMetadata if T’s scope is not ExtensionScope::Annotation, extension does not serialize to a JSON object, or it serializes a key not listed in FIELDS; returns SigmfError::Serde if serialization fails. Nothing is changed on error.

pub fn remove_extension<T: SigmfExtension>(&mut self) -> Result<(), SigmfError>

Removes all of extension T’s declared fields from this annotation.

Errors

Returns SigmfError::InvalidMetadata if T’s scope is not ExtensionScope::Annotation.

Trait Implementations

impl Clone for Annotation

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Annotation

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Annotation

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Annotation

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.