DP44/enriched-qwen3-coder-next/DataPRO/Modules/DatabaseImporter/DatabaseImport/Classes/RegionsAndZones.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/Modules/DatabaseImporter/DatabaseImport/Classes/RegionsAndZones/Zone.cs DataPRO/Modules/DatabaseImporter/DatabaseImport/Classes/RegionsAndZones/RegionAdorner.cs DataPRO/Modules/DatabaseImporter/DatabaseImport/Classes/RegionsAndZones/Region.cs	2026-04-16T04:32:32.660920+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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/<Image>, 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).