DP44/enriched-qwen3-coder-next/Common/DTS.Common/Interface/RegionOfInterest.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common/Interface/RegionOfInterest/IRegionOfInterest.cs	2026-04-16T02:57:51.269981+00:00	Qwen/Qwen3-Coder-Next-FP8	1	79c0c78dabaa068e

RegionOfInterest

1. Purpose

This module defines the IRegionOfInterest interface, which represents a configurable time- or sample-based region of interest (ROI) for signal processing or data analysis within the DTS system. It enables consumers to specify a temporal span (Start, End), associate it with specific channels (via ChannelNames and ChannelIds), and control its activation state (IsEnabled) and default status (IsDefault). As it implements INotifyPropertyChanged, it supports data binding and reactive UI updates when its properties change. The interface is designed to be implemented by concrete ROI types used throughout the application for segmenting, filtering, or analyzing time-series data.

2. Public Interface

• string Suffix { get; set; }
  Gets or sets a user-defined suffix appended to the ROI’s display name (e.g., for labeling or grouping). Changing this property raises PropertyChanged.

• double Start { get; set; }
  Gets or sets the inclusive start boundary of the ROI, expressed in the same unit as the underlying data (e.g., seconds, samples). Changing this property raises PropertyChanged.

• double End { get; set; }
  Gets or sets the exclusive end boundary of the ROI, expressed in the same unit as Start. Changing this property raises PropertyChanged.

• bool IsEnabled { get; set; }
  Gets or sets a flag indicating whether the ROI is active and should be considered in processing. Changing this property raises PropertyChanged.

• bool IsDefault { get; set; }
  Gets or sets a flag indicating whether this ROI is the default ROI (e.g., applied when no other ROI is selected). Changing this property raises PropertyChanged.

• string[] ChannelNames { get; set; }
  Gets or sets the human-readable names of channels associated with this ROI. Changing this property raises PropertyChanged.
  Note: Assignment replaces the entire array; partial updates require reassignment.

• long[] ChannelIds { get; set; }
  Gets or sets the unique identifiers (e.g., hardware or logical channel IDs) corresponding to ChannelNames. The arrays ChannelNames and ChannelIds are expected to be parallel (i.e., ChannelIds[i] corresponds to ChannelNames[i]). Changing this property raises PropertyChanged.

• void SetChannelNamesNoNotify(string[] names)
  Sets ChannelNames to names without raising PropertyChanged events. Useful for batch initialization or bulk updates where intermediate state changes should not trigger UI updates. The caller must ensure names is not null and matches the length of ChannelIds if ChannelIds has been previously set.

• void SetChannelIdsNoNotify(long[] ids)
  Sets ChannelIds to ids without raising PropertyChanged events. Must be used in conjunction with SetChannelNamesNoNotify for consistent channel metadata updates. The caller must ensure ids is not null and matches the length of ChannelNames if ChannelNames has been previously set.

• void ResetSuffix()
  Resets Suffix to its default value (implementation-defined; typically string.Empty). Behavior implies a property change notification should be raised, though the interface does not explicitly guarantee this—consumers should verify via testing or implementation.

3. Invariants

• Start and End must satisfy Start <= End for valid ROI definitions (though enforcement is not specified in the interface and may be deferred to implementations or consumers).
• ChannelNames and ChannelIds must have identical array lengths when both are non-null.
• ChannelNames and ChannelIds are expected to be parallel arrays: index i in ChannelNames corresponds to index i in ChannelIds.
• IsDefault should be true for at most one ROI instance within a given collection (e.g., a list of ROIs), though this constraint is not enforced by the interface itself.
• Implementations must raise PropertyChanged for all property setters except when using SetChannelNamesNoNotify or SetChannelIdsNoNotify.
• ResetSuffix() is expected to restore Suffix to a canonical default (e.g., ""), but the exact behavior is implementation-specific.

4. Dependencies

• Depends on:

  • System.ComponentModel (for INotifyPropertyChanged).
  • System (implicit via string, double, bool, long, void, string[], long[]).

• Depended on by (inferred):

  • Any component that manages or renders ROIs (e.g., ROI editors, analysis pipelines, UI view models).
  • Likely consumed by concrete types in DTS.Common.Interface.RegionOfInterest.* or downstream modules (e.g., DTS.Processing.*).
  • Data binding frameworks (e.g., WPF, MAUI) via INotifyPropertyChanged.

5. Gotchas

• No validation in interface: The interface does not enforce Start <= End, non-null arrays, or matching lengths of ChannelNames and ChannelIds. Implementations must handle these constraints.
• SetChannelNamesNoNotify/SetChannelIdsNoNotify are low-level: Misuse (e.g., setting only one array) can leave the ROI in an inconsistent state. Callers must update both arrays atomically if needed.
• ResetSuffix() behavior is unspecified: The interface does not define what the "default" suffix is or whether PropertyChanged is raised. Implementations may vary.
• No explicit ordering guarantee: The order of channels in ChannelNames/ChannelIds is significant but not validated; consumers must preserve ordering semantics.
• No thread-safety guarantees: As with most INotifyPropertyChanged implementations, this interface does not imply thread-safe property updates.
• None identified from source alone.