v0.28.0

What changed and why

Two additions that finish the "show a result on a cut-out" work of 0.27.0, plus one fix to the HUD line colours.

CvDispCtrl.ClipOverlayToImage — keep the result overlay inside the image

Opt-in; the default is the old behaviour.

0.27.0 added ViOverlay.CropTo for showing a result on a cut-out, and left clipping to the renderer. CvDispCtrl
clipped the overlay only at the edge of its display area, not at the image. A cut-out rarely has the display's
aspect ratio, so the fit leaves margins, and lines crossing the cut plus items outside it were drawn in those margins,
as if the image went on. A consumer measured it on 0.26.3 (the rendering code is unchanged in 0.27.0). The run was
offscreen at 96 DPI, with a Mono8 frame and the consumer's overlay: lines crossing the cut, and a polygon and a label
outside it. Results:

• A 400×150 frame fitted into a 400×400 display put 6305 overlay pixels in the margins above and below.
• 150×400 put 4582 in the side margins.
• A matching aspect ratio still put 56 there, because the fit keeps a small border.
• Geometry wholly inside the image put none.

How much bleeds depends on what is drawn. A wider margin only leaves more room for it.

• ClipOverlayToImage = true draws Overlay only inside the rectangle the image occupies on screen.
• Two things are not clipped to the image. The corner summary HUD (ViOverlayLabel.IsHud with a corner
  alignment, the block CropTo puts back in its corner) is one. Its text keeps its screen size, so on a small cut-out
  the block is larger than the image as drawn, and clipping it would leave only the header line — which looks like a
  complete one-line HUD. With the option on, that HUD is drawn after the other items, so it sits on top. Editable
  Shapes are the other, so a handle on the image border can still be grabbed. Both are still clipped at the edge of
  the display area.
• What turning it on costs: every other item is cut at the image edge, labels included. Label text keeps its
  screen size, so the smaller the image is drawn (a small tile, zoomed out), the more of an edge label is lost.
• The default stays false: the overlay runs to the edge of the display area, and a label on the image border stays
  readable where the fit leaves a margin on that side. At the display's own aspect ratio that margin is only a few
  pixels, so such a label is mostly cut either way.
• Turn it on where a cut-out is shown (a result view fed by ViOverlay.CropTo and CamFrame.Crop). The docs of
  ViOverlay.CropTo and ViOverlayLabel.IsHud and the core and Imaging READMEs now point to it.
• Note on 0.27.0: its notes said renderers ignore ViOverlayLabel.IsHud. CvDispCtrl now reads it, but only
  while ClipOverlayToImage is on, as described above. With the option off, nothing changes.

Regressions:

• ClipOverlayToImageKeepsTheFitMarginsClean covers top/bottom (400×150) and side (150×400) margins. In the same run,
  the default draws in the margins (the control), and the option leaves them clean while drawing exactly the same
  pixels inside the image.
• ClipLeavesTheCornerHudAndEditShapesWhole checks the HUD on a thin strip: it stays whole with the option on. A label
  with the same text and position but no HUD mark is clipped (the control). Edit shapes are not clipped to the image.

ViOverlayLabel.Hud — the summary HUD as data

A screen that shows the HUD apart from the image (a text panel beside a process monitor) had to parse the label's
text — "[OK] title\nline…" — for the verdict and the lines. The text is built for drawing: its format and colour
can change (translated wording, for one). A verdict read back from it would then show an OK in the NG colour, and
nothing would look broken.

• ViHudSummary(bool IsOk, string Title, IReadOnlyList<(string Text, ViOverlayColor? Color)> Lines, ViHudPos Pos) —
  what ViHud.AddSummary was given. Every AddSummary overload sets it on the label it adds. A label that is not a
  summary, or that was built by hand, has Hud == null. IsHud (a corner-anchored summary) and Hud (its content)
  are separate.
• Lines are the detail lines as given, without the title line. An entry may contain a line break, so do not count
  drawn lines from it. A null colour means the verdict colour.
• The summary keeps its own read-only copy of the lines, whichever way it is built. Equality compares the lines'
  content. CropTo keeps the same summary.
• It is a value for code to read, not a storage format. The tuple element names do not exist at run time, so
  System.Text.Json needs IncludeFields (or a converter), and Json.NET writes Item1/Item2 — the same as
  ViOverlayPoly.Points.
• The label's Text is unchanged, so hosts that parse it keep working.

Fix: HUD line colours when a coloured line contains a line break

In the coloured AddSummary overloads, a coloured entry containing \n got one colour slot for two drawn lines. Every
following line's colour then shifted by one, and the last fell back to the verdict colour. This has been so since the
overload was added. Each drawn line of the entry now gets its colour.

Version

0.28.0 — minor. Added: CvDispCtrl.ClipOverlayToImage / ClipOverlayToImageProperty (CvInspect.Wpf),
ViHudSummary and ViOverlayLabel.Hud (CvInspect). Changed: CvDispCtrl reads IsHud when the new option is on,
and the coloured AddSummary fills each drawn line's colour. CvInspect.Imaging changes only in documentation;
CvInspect.Imaging.Gev does not change (lockstep).

The version rule in the PR template and Directory.Build.props now also describes a patch exception: an opt-in
addition that completes the previous minor's feature may ship as a patch. This release does not use it. It began as
0.27.1 under that exception, and became a minor when the HUD data joined it.

Checks

• dotnet build CvInspect.sln -c Release --no-incremental reports 0 warnings
• main is an ancestor of this branch (the release-pr-guard job verifies it)
• the tag will be created on the merge commit, main merged back into dev afterwards, and dev bumped to the next -dev version