init

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

@@ -0,0 +1,52 @@
+---
+source_files:
+  - Common/DTS.CommonCore/Interface/RegionOfInterest/IRegionOfInterest.cs
+generated_at: "2026-04-16T02:17:44.659996+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "59ff4edea9524aba"
+---
+
+# RegionOfInterest
+
+### **Purpose**  
+This module defines the `IRegionOfInterest` interface, which standardizes the contract for regions of interest (ROIs) across the system—typically representing selectable time or frequency intervals associated with specific channels. It enables UI and business logic components to bind to ROI metadata (e.g., `Start`, `End`, `IsEnabled`) and react to changes via `INotifyPropertyChanged`. The interface supports default/placeholder ROIs (`IsDefault`), custom naming via `Suffix`, and channel-specific scoping (`ChannelNames`), while providing optimized mutation paths (`SetChannelNamesNoNotify`) to avoid unnecessary notifications during batch updates.
+
+---
+
+### **Public Interface**  
+
+| Member | Signature | Behavior |
+|--------|-----------|----------|
+| `Suffix` | `string Suffix { get; set; }` | Gets or sets a user-defined suffix appended to the ROI’s display name (e.g., `"Peak"` → `"ROI_Peak"`). Modifying this triggers `PropertyChanged`. |
+| `Start` | `double Start { get; set; }` | Gets or sets the inclusive start boundary of the ROI (e.g., time in seconds or frequency in Hz). Modifying this triggers `PropertyChanged`. |
+| `End` | `double End { get; set; }` | Gets or sets the exclusive end boundary of the ROI. Must be ≥ `Start`. Modifying this triggers `PropertyChanged`. |
+| `IsEnabled` | `bool IsEnabled { get; set; }` | Gets or sets whether the ROI is active (e.g., processed or rendered). Modifying this triggers `PropertyChanged`. |
+| `IsDefault` | `bool IsDefault { get; set; }` | Gets or sets whether this ROI is a system-provided default (e.g., auto-generated). Typically immutable by user actions. Modifying this triggers `PropertyChanged`. |
+| `ChannelNames` | `string[] ChannelNames { get; set; }` | Gets or sets the ordered list of channel identifiers this ROI applies to (e.g., `["CH1", "CH3"]`). Modifying this triggers `PropertyChanged`. |
+| `SetChannelNamesNoNotify` | `void SetChannelNamesNoNotify(string[] names)` | Sets `ChannelNames` *without* raising `PropertyChanged`. Intended for bulk initialization or internal state synchronization where notifications would be redundant or problematic. |
+| `ResetSuffix` | `void ResetSuffix()` | Resets `Suffix` to its default value (e.g., empty string or system-defined fallback). Behavior implies a `PropertyChanged` event for `Suffix` is raised *unless* the implementation explicitly suppresses it (source does not specify—see *Gotchas*). |
+
+---
+
+### **Invariants**  
+- `Start ≤ End` must hold at all times; implementations are expected to enforce this (e.g., via validation in setters).  
+- `ChannelNames` must be non-null; empty arrays are permitted (indicating no channels).  
+- `IsDefault` implies immutability constraints: while not enforced by the interface, implementations typically prevent modification of `Start`, `End`, `ChannelNames`, or `Suffix` for default ROIs.  
+- `SetChannelNamesNoNotify` must *not* raise `PropertyChanged`; all other property setters *must* raise `PropertyChanged` (per `INotifyPropertyChanged` contract).  
+
+---
+
+### **Dependencies**  
+- **Depends on**: `System.ComponentModel` (for `INotifyPropertyChanged`).  
+- **Depended on by**: UI layers (e.g., WPF/XAML bindings), ROI management services (e.g., `ROIManager`), and serialization modules (e.g., JSON converters for ROI persistence).  
+- **No direct external library dependencies** beyond .NET Base Class Library.  
+
+---
+
+### **Gotchas**  
+- **`ResetSuffix` behavior ambiguity**: The interface does not specify whether `ResetSuffix` raises `PropertyChanged`. Implementations may differ—some may suppress notifications (e.g., if resetting to current value), others may unconditionally raise the event. Callers should assume notification *may* occur.  
+- **`ChannelNames` mutability**: The property setter accepts `string[]`, but the interface does not clarify whether the array is copied (defensive copy) or referenced. Implementations may mutate the backing store if the caller retains a reference to the passed array.  
+- **No validation in interface**: While `Start ≤ End` is an expected invariant, the interface itself does not enforce it—validation must be implemented in concrete types.  
+- **`IsDefault` semantics**: The interface does not define *how* `IsDefault` affects behavior (e.g., whether it blocks edits or affects serialization). This is implementation-specific.  
+- **No thread-safety guarantees**: `INotifyPropertyChanged` implementations are typically not thread-safe; concurrent modifications may cause race conditions in event handlers.