--- source_files: - DataPRO/Modules/DatabaseImporter/DatabaseImport/Classes/RegionsAndZones/Zone.cs - DataPRO/Modules/DatabaseImporter/DatabaseImport/Classes/RegionsAndZones/RegionAdorner.cs - DataPRO/Modules/DatabaseImporter/DatabaseImport/Classes/RegionsAndZones/Region.cs generated_at: "2026-04-16T04:32:32.660920+00:00" model: "Qwen/Qwen3-Coder-Next-FP8" schema_version: 1 sha256: "cd00dc5bfe396de9" --- # RegionsAndZones ## Documentation: Regions and Zones Module ### 1. Purpose This module provides data structures and UI adorning capabilities for defining and managing spatial regions and zones within test object templates, primarily for ISO-compliant test configuration. It enables users to define named zones (e.g., anatomical or functional areas) containing one or more rectangular regions, each associated with metadata (e.g., direction, filter class, transducer location) used to generate ISO codes and filter available channels. The module bridges raw template data (`TemplateZone`, `TemplateRegion`) with WPF-based UI interaction (via `RegionAdorner`) and supports bidirectional conversion between in-memory objects and ISO database representations. --- ### 2. Public Interface #### `Zone` class - **`Zone(Zone copy, TestObjectTemplate template)`** Copy constructor. Initializes a new `Zone` by copying properties (`Description`, `Image`, `Regions`) from an existing `Zone`, preserving `ISODllZone`, and preloading picture filenames. - **`Zone(TemplateZone z, TestObjectTemplate template)`** Constructor from ISO `TemplateZone`. Loads `Description`, `Image`, and `Regions` (converted to `Region` objects). Attempts to load and cache the zone picture as a `BitmapImage` if the file exists. - **`string Name { get; set; }`** Zone name, sourced from `ISODllZone.ZoneName`. - **`string Description { get; set; }`** Zone description, sourced from `ISODllZone.Description` (defaults to `""`). - **`string Image { get; set; }`** Filename of the zone picture, sourced from `ISODllZone.Picture`. - **`TemplateZone ISODllZone { get; }`** Read-only reference to the underlying ISO `TemplateZone` object. - **`string[] AllPictures { get; }`** Thread-safe array of filenames (not full paths) in the `ZonePictures` subdirectory of the app base directory. Populates on first access. - **`void PopulateFilenamesIfNeeded()`** Ensures `_fileNames` is populated (only if empty), using a lock to prevent concurrent population. - **`int PictureIndex { get; set; }`** Index into `AllPictures` for the currently selected picture. Setting triggers loading of the corresponding image into `PictureSource`. Index `-1` sets `PictureSource` to `null`. - **`string GetPictureName()`** Returns the filename of the currently selected picture (empty string if `PictureIndex < 0`). - **`System.Windows.Media.ImageSource PictureSource { get; set; }`** The WPF `ImageSource` for the currently selected picture. - **`Region[] Regions { get; set; }`** Array of `Region` objects in this zone. `get` returns a copy; `set` replaces the internal list. #### `RegionAdorner` class - **`RegionAdorner(UIElement adornedElement, TestObjectTemplate template, Contexts context)`** Constructor. Creates a new adorner for an `Image` (or other `UIElement`). Initializes `_region`, sets up mouse event handlers, and configures visual path (AliceBlue stroke, 60% opacity, initially hidden). - **`Point GetUpperLeft()`** Returns the upper-left corner of `SelectRect`, adjusted for scaling between the adorned element’s `RenderSize` and its `Source` dimensions. - **`Point GetLowerRight()`** Returns the lower-right corner of `SelectRect`, similarly scaled. - **`bool IsNew { get; set; }`** Controls visibility of region add/delete UI: `true` → `RegionAddVisibility=Visible`, `RegionDeleteVisibility=Hidden`; `false` → vice versa. - **`Rect SelectRect { get; set; }`** Bounding rectangle of the region in adorner coordinates. Setting it updates `MyRegion.RegionUpperLeft`/`RegionBottomRight` via `GetUpperLeft()`/`GetLowerRight()`. - **`Region MyRegion { get; set; }`** Reference to the associated `Region` object. - **`Contexts Context { get; set; }`** Context enum (`EditTestObject` or `EditTestObjectTemplate`) indicating usage mode. - **`event RegionSelectedHandler OnRegionSelected`** Raised on `MouseLeftButtonDown`. - **`event EndSelectionHandler OnEndSelection`** Raised on `MouseLeftButtonUp` (via `EndSelection()`). - **`void DrawSelection(...)`** Updates `SelectRect` to a rectangle defined by `AnchorPoint` and current mouse position (used during region creation). - **`void MoveSelection(...)`** Updates `SelectRect` by translating it by the mouse delta (used during region movement). #### `Region` class - **`Region(RegionAdorner adorner, TestObjectTemplate template)`** Constructor for a *new* region. Sets default name/description, assigns `Template`, initializes `RegionChannels`/`RegionUIChannels` from template, and calls `DetermineAvailableISOSettings()`. - **`Region(TestObjectTemplate template, TemplateRegion r)`** Constructor from ISO `TemplateRegion`. Populates all properties from `r` (e.g., `RegionUpperLeft`, `RegionDirection`, `ISOCode`) and calls `FilterRegionChannels()` and `SetISOCode()`. - **`string RegionName { get; set; }`** User-facing region name. - **`string RegionDescription { get; set; }`** User-facing region description. - **`Point RegionUpperLeft { get; set; }`** Upper-left coordinate (WPF `Point`) of the region. - **`Point RegionBottomRight { get; set; }`** Lower-right coordinate (WPF `Point`) of the region. - **`MMEDirections RegionDirection { get; set; }`** Direction metadata (e.g., "Anterior", "Posterior"). Setting updates `_directionIndex` and calls `SetISOCode()`. - **`MMEFilterClasses RegionFilterClass { get; set; }`** Filter class metadata. Setting updates `_filterClassIndex` and calls `SetISOCode()`. - **`MMEFineLocations1 RegionFineLocation1 { get; set; }`** Fine location 1 metadata. Setting updates `_fineLocation1Index` and calls `SetISOCode()`. - **`MMEFineLocations2 RegionFineLocation2 { get; set; }`** Fine location 2 metadata. Setting updates `_fineLocation2Index` and calls `SetISOCode()`. - **`MMEFineLocations3 RegionFineLocation3 { get; set; }`** Fine location 3 metadata. Setting calls `SetISOCode()`. - **`MMETransducerMainLocation RegionMainLocation { get; set; }`** Main transducer location metadata. Setting updates `_mainLocationIndex` and calls `SetISOCode()`. - **`MMEPhysicalDimensions RegionPhysicalDimension { get; set; }`** Physical dimension metadata. Setting updates `_physicalDimensionIndex` and calls `SetISOCode()`. - **`MMEPositions RegionPosition { get; set; }`** Position metadata. Setting updates `_positionIndex` and calls `SetISOCode()`. - **`MMETestObjects RegionTestObject { get; set; }`** Test object type (e.g., "Breast", "Brain"). - **`TestObjectTemplate Template { get; set; }`** Reference to the parent template. Setting triggers `DetermineAvailableISOSettings()`. - **`string[] AllDirections { get; set; }`** Available direction options (from template). `set` also populates `AllDirectionsStrings`. - **`string[] AllDirectionsStrings { get; }`** Human-readable direction names (e.g., `"Anterior"`). - **`MMEFilterClasses[] AllFilterClasses { get; set; }`** Available filter classes. `set` populates `AllFilterClassStrings`. - **`string[] AllFilterClassStrings { get; }`** Human-readable filter class names. - **`MMEFineLocations1[] AllFineLocations1 { get; set; }`** Available fine location 1 options. `set` populates `AllFineLocations1Strings`. - **`string[] AllFineLocations1Strings { get; }`** Human-readable fine location 1 names (`"??"` for null). - **`MMEFineLocations2[] AllFineLocations2 { get; set; }`** Available fine location 2 options. `set` populates `AllFineLocations2Strings`. - **`string[] AllFineLocations2Strings { get; }`** Human-readable fine location 2 names. - **`int FineLocation2Index { get; set; }`** Index into `AllFineLocations2`. Setting updates `RegionFineLocation2` and calls `FilterRegionChannels()`. - **`MMEFineLocations3[] AllFineLocations3 { get; set; }`** Available fine location 3 options. `set` populates `AllFineLocations3Strings`. - **`string[] AllFineLocations3Strings { get; }`** Human-readable fine location 3 names. - **`MMETransducerMainLocation[] AllMainLocations { get; set; }`** Available main location options. `set` populates `AllMainLocationsStrings`. - **`string[] AllMainLocationsStrings { get; }`** Human-readable main location names (`"????"` for null). - **`MMEPhysicalDimensions[] AllPhysicalDimensions { get; set; }`** Available physical dimension options. `set` populates `AllPhysicalDimensionStrings`. - **`string[] AllPhysicalDimensionStrings { get; }`** Human-readable physical dimension names (`"??"` for null). - **`MMEPositions[] AllPositions { get; set; }`** Available position options. `set` populates `AllPositionStrings`. - **`string[] AllPositionStrings { get; }`** Human-readable position names. - **`string ISOCode { get; set; }`** 16-character ISO code string (e.g., `"BREAST?ANTERIOR???????"`). Generated by `SetISOCode()` from metadata fields. - **`TestObjectTemplateChannel[] RegionChannels { get; set; }`** List of channels *available* for this region (filtered by `RegionMainLocation`, `RegionDirection`, etc.). `set` triggers `DetermineAvailableISOSettings()`. - **`TemplateChannelUI[] RegionUIChannels { get; set; }`** UI-friendly channel list (mirrors `RegionChannels`). - **`Visibility RegionAddVisibility { get; set; }`** UI visibility flag for "add region" controls. - **`Visibility RegionDeleteVisibility { get; set; }`** UI visibility flag for "delete region" controls. - **`TemplateRegion ToISORegion(TestObjectTemplate template, Zone zone, int number)`** Converts this `Region` to a `TemplateRegion` for ISO export. Uses `RegionUpperLeft`/`RegionBottomRight` (converted to `System.Drawing.Point`), and maps null metadata to ISO defaults (`"?"`, `"??"`, `"????"`). --- ### 3. Invariants - **Picture filename consistency**: `PictureIndex` must be in `[0, AllPictures.Length-1]` or `-1`. Setting `PictureIndex` to `-1` sets `PictureSource` to `null`. - **ISO code format**: `ISOCode` is always 16 characters, with `"?"`, `"??"`, or `"????"` used for missing metadata fields. - **Channel filtering**: `RegionChannels` is always a subset of `Template.TemplateAllChannels`, filtered by `RegionMainLocation`, `RegionDirection`, `RegionFilterClass`, `RegionFineLocation1/2/3`, `RegionPhysicalDimension`, and `RegionPosition`. - **Metadata consistency**: `RegionDirection`, `RegionFilterClass`, etc., are always `null` or a valid object from their respective `All*` arrays. - **Thread safety**: `_fileNames` population is guarded by a static lock (`MyLock`), and `AllPictures` always accesses `_fileNames` under this lock. - **Region bounds**: `RegionUpperLeft` and `RegionBottomRight` are WPF `Point` coordinates relative to the adorned image. --- ### 4. Dependencies - **Imports/References**: - `System`, `System.Collections.Generic`, `System.Linq` (core .NET) - `System.Windows`, `System.Windows.Controls`, `System.Windows.Documents`, `System.Windows.Input`, `System.Windows.Media`, `System.Windows.Shapes` (WPF) - `System.ComponentModel` (`INotifyPropertyChanged`) - `App` (from `Application.Current`), `IsoDb`, `TestObjectTemplate`, `TemplateZone`, `TemplateRegion`, `MMEDirections`, `MMEFilterClasses`, `MMEFineLocations1/2/3`, `MMETransducerMainLocation`, `MMEPhysicalDimensions`, `MMEPositions`, `MMETestObjects`, `TestObjectTemplateChannel`, `TemplateChannelUI` (all inferred from usage). - **External resources**: - `ZonePictures` subdirectory in `AppDomain.CurrentDomain.BaseDirectory` (for zone images). - **Depended on by**: - UI layers (e.g., WPF adorner layers using `RegionAdorner`). - Database import/export logic (via `ToISORegion` and `Zone` constructors). --- ### 5. Gotchas - **Picture loading failure**: If `Image` is set but the file does not exist at `ZonePictures/`, `PictureIndex` is set to `-1` silently (no exception thrown). - **Scaling assumptions**: `GetUpperLeft()`/`GetLowerRight()` assume the adorned element is an `Image` with a `BitmapImage` source. Scaling logic may be incorrect if `Source` dimensions are unavailable or non-integer. - **`FineLocation2Index` setter**: Only updates `RegionFineLocation2` and calls `FilterRegionChannels()`; does *not* update `_fineLocation2Index` directly (relies on `RegionFineLocation2` setter). - **`RegionFineLocation3` setter**: Does not update `_fineLocation3Index` (empty `else` block), unlike other fine location properties. - **`AllPictures` thread safety**: While `_fileNames` population is thread-safe, `AllPictures` returns a *snapshot* array. Concurrent modifications to `_fileNames` (e.g., via `PopulateFilenames()`) during enumeration could cause `IndexOutOfRangeException` if not for the lock (but `AllPictures` itself is safe). - **`Region` constructor from `TemplateRegion`**: Uses `((App)Application.Current).IsoDb` for lookups. If `IsoDb` is not initialized, this will throw a `NullReferenceException`. - **`RegionChannels`/`RegionUIChannels`**: The `set` accessor for `RegionChannels` calls `DetermineAvailableISOSettings()`, which may overwrite previously set values (e.g., `RegionDirection`, `RegionFilterClass`). - **ISO code generation**: `SetISOCode()` uses `"?"` for null `RegionTestObject`, but `"???"` for null `RegionMainLocation` (inconsistent padding).