CvInspect.Wpf 0.33.0

CvInspect.Wpf

WPF display and shape-editing controls for the CvInspect machine-vision toolkit, based on OpenCvSharp.

• CvDispCtrl — an image display control with a dockable toolbar (grab / live toggle / fit / zoom / pan / clear), a status bar (cursor position, pixel value, image size, zoom level), and a right-click menu (load / save image file, view operations). Renders OpenCvSharp.Mat frames, renderer-neutral result overlays (ViOverlay), and interactive teaching shapes.
• Teaching shapes — the draggable shapes (CvEditShape family: rotated rect, segment, circle, arc, concentric ring) and the contract by which option POCOs supply them (ICvShapeSource, implemented by every CvInspect option that has geometry, and by host-defined options the same way) live in the core package under CvInspect.Vision.Edit. This package draws them and turns mouse drags into moves, corner resizes and rotation/angle/radius grips; each drag writes straight back into the POCO through the shape's Changed event.

Install

dotnet add package CvInspect.Wpf

This package references only the managed assemblies (CvInspect → OpenCvSharp4). Pick a native OpenCV runtime yourself in the application project, e.g.:

dotnet add package OpenCvSharp4.runtime.win

Quick start

<Window xmlns:cv="clr-namespace:CvInspect.Controls;assembly=CvInspect.Wpf" ...>
  <cv:CvDispCtrl Frame="{Binding Frame}"
                 Overlay="{Binding Overlay}"
                 Shapes="{Binding Shapes}"
                 GrabCommand="{Binding GrabCmd}"
                 ContinuousCommand="{Binding LiveCmd}"
                 StopCommand="{Binding StopCmd}"
                 LoadFrameCommand="{Binding LoadFrameCmd}"
                 IsRunning="{Binding IsLive}" />
</Window>

Property editor

CvPropEditCtrl unfolds any option POCO into category groups and rows — checkbox for bool, text for numbers and strings, combo for enums, a button for Action, a read-only line list for enumerables, and an indented block of child rows for a nested object — using only the standard System.ComponentModel attributes, which the core's [CvCategory] / [CvName] / [CvDesc] derive from. So a core Cv*Opt needs nothing extra:

<cv:CvPropEditCtrl Source="{Binding ToolOpt}" Committed="OnCommitted" />

Because a list row reads and enumerates a property that nothing read before — a lazy getter that talks to a device, a list another thread is filling — reading is guarded: a property whose getter or enumeration throws is left out of the editor instead of taking the whole control down with it, and a CvLog warning names it. Setting Source never throws because of one bad property.

A list row prints at most the first 20 items and then stops enumerating — it appends … (+N) when the count is cheap to know and a bare … otherwise, so a large array or an endless lazy sequence cannot freeze the editor just by being shown.

A property becomes a nested block only when it carries [TypeConverter(typeof(ExpandableObjectConverter))] — nothing else is walked into, so an option POCO never drags a whole object graph onto the screen. The block follows the value's runtime type, and when the property starts returning a different instance (a mode switch that swaps the detail object) the child rows are rebuilt, so the POCO must raise PropertyChanged for that property at the moment it swaps; otherwise the old rows keep writing into the discarded object. Nesting stops at three levels, and a level past the limit is not drawn at all rather than left half-drawn.

A nested block with no child rows is hidden entirely, heading and all — a mode whose detail object exposes nothing to edit leaves no trace on screen, and the block appears when the mode changes to one that does. Expect this while checking that a property finally shows up. Hiding it is the point: an empty heading would make "there is nothing to unfold" look exactly like "this could not be read", and those two deserve different reactions. If you need to tell them apart in code, CvPropNestedRowVm.HasChildren is public.

Rules the rows follow: [Browsable(false)] hides, [ReadOnly(true)] or a getter-only property disables — except list and nested rows, which show or unfold instead of assigning the value itself and so stay enabled — group order comes from ICvOrderedCategory (or a "N. " prefix on plain [Category] strings), and numeric text commits on Enter or focus loss — an unparsable entry is rejected and the row snaps back to the stored value, so what you see is always what is stored. The control references no UI library; it adopts the host theme's SecondaryTextBrush and PrimaryBrush when those keys exist (and follows them when the host swaps its dictionary at run time) and falls back to fixed colors otherwise.

Frame lifetime

Frame accepts two kinds of value, with different lifetime rules:

• Mat — CvDispCtrl copies the pixels into its own buffer, so the host may Dispose() the Mat right after setting the property. That copy is the price of a type that can be disposed underneath the control.
• ICvPixelSource (the core contract, implemented by CamFrame in CvInspect.Imaging) — the control holds the pixel array by reference and copies it only once, into the WPF back buffer. The reference is kept for the status-bar pixel probe and for file save, not for rendering — so a buffer that changes after publishing does not tear the picture, it makes those two disagree with what is on screen. This relies on the contract that Pixels is immutable once published; a source that recycles its buffer must not implement it.

Supported formats either way: 8-bit with 1 (Gray8), 3 (Bgr24) or 4 (Bgra32) channels; anything else shows the no-image placeholder. A value of any other type also shows the placeholder and logs a warning through CvLog.

The Mat passed to LoadFrameCommand is owned by the receiver — the view-model disposes it when done (typically after assigning it back to Frame).

Overlay and shape coordinates are in the pixel space of the image being displayed — bind an image and coordinates from the same space, whether that is the original or a derived (scaled) stage image.

Localization and theming

UI strings (menu labels, placeholder text) come from CvLoc in the core package, under the cv: scope. Labels are re-read every time the context menu opens, so a language switch applies without rebuilding the control.

CvDispCtrl's toolbar and status bar colors come from the first of: a value set on the instance, a resource key defined anywhere above it (application dictionary, window, the control's own Resources), or a fixed default. Keys are held as resource references, so swapping the host's color dictionary at run time (a light/dark switch) repaints every display without a restart.

<ResourceDictionary xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
                    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
                    xmlns:cv="clr-namespace:CvInspect.Controls;assembly=CvInspect.Wpf">
  <SolidColorBrush x:Key="{x:Static cv:CvDispCtrl.ToolbarBackgroundKey}" Color="#2D2D30" />
  <SolidColorBrush x:Key="{x:Static cv:CvDispCtrl.StatusBarForegroundKey}" Color="#B4B4B4" />
</ResourceDictionary>

Write the key through x:Static: a typo then fails loudly when the dictionary loads (a XamlParseException whose inner exception names the member) — the build does not check it — while a mistyped key string is silently ignored and the default stays. The value must be a Brush. A non-null value of another type under one of these four keys is ignored, and each display logs a CvLog warning naming the key when it picks the value up.

The instance properties take a direct value, a binding, a DynamicResource or a style setter, and win over the keys. Clearing a direct value (ClearValue) returns that instance to the next source: a style setter if there is one, otherwise the key. CvDispCtrl is not a Control, so by WPF's rules an implicit style in a window's or user control's resources does not reach a CvDispCtrl created by a DataTemplate (one in the application's resources does) — inside templates, use the keys or set the property on the element in the template. The image area stays dark (#2A2A2A) in every theme.

Toolbar accent colors use the host theme's PrimaryBrush / SuccessBrush / DangerBrush resource keys when present, and CvPropEditCtrl uses SecondaryTextBrush / PrimaryBrush; both fall back to fixed colors otherwise and follow a dictionary swap the same way — no UI library is referenced.

Targets

net8.0-windows, AnyCPU. The native OpenCV runtime is chosen by the consuming application.

Versions

The four CvInspect packages move together — upgrade them as a set. This is a 0.x API: breaking changes happen, so pin versions. What changed in each release is on the Releases page, one entry per version; read the entries between the version you are on and the one you are moving to.

License

Apache-2.0. Not affiliated with OpenCV or OpenCvSharp.