init

enriched-qwen3-coder-next/Common/DTS.Common/Events/RegionOfInterest.md

@@ -0,0 +1,38 @@
+---
+source_files:
+  - Common/DTS.Common/Events/RegionOfInterest/RegionOfInterestChangedEvent.cs
+generated_at: "2026-04-16T03:24:29.831249+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "b57954f8953ae512"
+---
+
+# RegionOfInterest
+
+### 1. Purpose  
+This module defines a Prism-based event (`RegionOfInterestChangedEvent`) used to publish notifications when the current region of interest (ROI) changes in the application. It serves as a decoupling mechanism in the MVVM pattern, allowing view models or services to subscribe to ROI changes without direct references, enabling reactive UI updates or downstream processing (e.g., image analysis, rendering, or logging) in response to ROI modifications.
+
+### 2. Public Interface  
+- **`RegionOfInterestChangedEvent`**  
+  - *Type*: `class` (inherits from `Prism.Events.PubSubEvent<IRegionOfInterest>`)  
+  - *Behavior*: A Prism `PubSubEvent` that carries an `IRegionOfInterest` payload. When published (via `Publish`), all subscribers receive the new ROI instance. This event is *not* thread-safe by default (Prism’s `PubSubEvent` uses the synchronization context of the publisher unless configured otherwise).  
+
+### 3. Invariants  
+- The event payload is always of type `IRegionOfInterest` (from `DTS.Common.Interface.RegionOfInterest`).  
+- The event is *publish-only* in this file—no custom logic is defined for subscription, filtering, or persistence.  
+- No validation or normalization of the `IRegionOfInterest` instance is performed by this class; validity of the payload is assumed to be enforced by publishers.  
+
+### 4. Dependencies  
+- **External**:  
+  - `Prism.Events` (specifically `PubSubEvent<TPayload>`)  
+  - `DTS.Common.Interface.RegionOfInterest` (for the `IRegionOfInterest` interface)  
+- **Internal**:  
+  - *Consumers*: Any module/service/view model that needs to react to ROI changes (e.g., via `IEventAggregator.GetEvent<RegionOfInterestChangedEvent>().Subscribe(...)`).  
+  - *Producers*: Code that calls `eventAggregator.GetEvent<RegionOfInterestChangedEvent>().Publish(roi)`, where `roi` implements `IRegionOfInterest`.  
+
+### 5. Gotchas  
+- **No default thread-safety**: Subscribers may execute on the publisher’s thread context; if the publisher is on a background thread, subscribers must handle cross-thread access (e.g., via `Subscribe(..., ThreadOption.PublisherThread)` or UI dispatcher invocation).  
+- **Lifetime management**: Subscribers must manually unsubscribe (e.g., in `Dispose` or view model cleanup) to avoid memory leaks, as Prism’s `PubSubEvent` holds strong references by default.  
+- **No null-safety guarantee**: The event does not enforce non-null payloads; publishers must ensure `IRegionOfInterest` instances are valid (though `null` may be used intentionally to signal "clear ROI" if documented elsewhere).  
+- **Interface dependency**: Behavior relies entirely on the contract of `IRegionOfInterest`; changes to that interface may silently break subscribers.  
+- *None identified from source alone* regarding ordering guarantees, deduplication, or historical quirks—these would require inspection of publishers/subscribers.