HawkeyeVision/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

VisionBuilder.UI is a modular .NET 8.0 WinForms application for industrial computer vision. It processes images through configurable operation pipelines, supports AI inference (YOLO/ONNX), and integrates with HawkEye camera hardware. The solution uses Ninject for DI and follows MVVM patterns.

Build Commands

dotnet build VisionBuilder.UI.sln -c Debug      # GPU build (YoloV8.Gpu + OnnxRuntime.Gpu)
dotnet build VisionBuilder.UI.sln -c CPU         # CPU-only build (YoloV8 + OnnxRuntime)
dotnet build VisionBuilder.UI.sln -c Release     # Production build

The Debug and Release configurations pull GPU NuGet packages; CPU configuration pulls CPU-only packages. This is controlled by conditional <PackageReference> blocks in Hawkeye.VisionBuilder.Workflow.csproj.

Testing

Test framework: MSTest (Microsoft.NET.Test.Sdk 17.12.0, MSTest 3.6.4)

dotnet test VisionBuilder.UI.sln                            # Run all tests
dotnet test VisionBuilder.UI.Tests/                         # Primary unit tests only
dotnet test --filter "FullyQualifiedName~ClassName.Method"  # Single test

Test projects: VisionBuilder.UI.Tests, VisionBuilder.UI.Recipes.Scripted.Tests, IDSTest

Solution Architecture

The solution is organized into logical groups:

Starters (entry points):

• Hawkeye.VisionBuilder — Main WinExe. Program.cs bootstraps the Ninject kernel, creates the WorkflowList and OperationDiscoveryService, then runs MainWindow.

Core Modules:

• Hawkeye.VisionBuilder.Workflow — Image processing pipeline engine. Contains BaseOperation, Context, WorkflowList, OperationDiscoveryService, and all operation implementations. See its own CLAUDE.md for detailed operation/recipe documentation.
• VisionBuilder.UI.Common — Shared contracts: IPlugin, IVisionBuilderModule, IRecognitionControl, IImageSource, service interfaces, MVVM ViewModels, command/event system.
• VisionBuilder.UI.Windows — WinForms UI controls (PreviewWindow, ErrorPreview, Stats, SingleCameraControl).

Framework (reusable libraries under framework/):

• Inspectron.Camera, Inspectron.Settings, Inspectron.HawkEye, Inspectron.Fastbuffer, Inspectron.Ringbuffer, MaterialSkin.Core — Hardware abstraction, settings management, and UI theming. Some target netstandard2.1.

Sources (image input providers):

• Sources.Emulation — File-based emulated camera for development.
• Sources.Hawkeye — Real HawkEye hardware source.
• Sources.IDS — IDS industrial camera integration.

Plugins (extend functionality via IPlugin interface):

• B24SiemensPlugin, CandyboxPlugin, PralinenPLC, PackstrasseBarcodeReader, etc.
• Plugins register services into the Ninject kernel at global and per-camera scope.

Recipes (workflow serialization):

• Recipes.HawkeyeRecipe — Binary .hrcp and XML .xhrcp recipe formats.
• Recipes.Scripted — Script-based recipe execution.

Key Architectural Patterns

Operation Pipeline

Images flow through a chain of BaseOperation subclasses. Each operation receives a Context (holding ActiveImage, Memory dictionary, GraphicsElements) and implements InterpretInternal(Context). Operations are discovered at runtime via reflection by OperationDiscoveryService. Categories: AI/, Simple/, Filters/, Morphology/, Image/, Basic/.

Plugin System

Plugins implement IPlugin with two registration points:

• RegisterGlobalModules(IKernel) — app-wide services
• RegisterCameraModules(IKernel, string cameraName) — per-camera services

Modules implement IVisionBuilderModule.InitializeModule() for deferred initialization.

For detailed plugin architecture documentation and step-by-step implementation guide, see docs/PLUGIN_SYSTEM.md.

Recognition Control

IRecognitionControl manages the per-camera image processing lifecycle (start/stop/pause, image loop, events). BaseRecognitionControl provides the threading, loop, and event infrastructure — subclasses implement Initialize, WarmUp, ProcessImage, and GetRecipesData. Each camera gets its own singleton instance via the child kernel. For full implementation guide, settings reference, and existing implementations, see docs/RECOGNITION_CONTROL.md.

DI Container

Ninject StandardKernel is the root container. Child kernels (Ninject.Extensions.ChildKernel) scope per-camera services. All service resolution flows through the kernel — avoid new for services.

Event/Command System

IEvent / IEventHandler<TEvent> in VisionBuilder.UI.Common/Commands/. Key events: SessionStartedEvent, SessionEndedEvent, ImageProcessedEvent, ErrorsInSequenceEvent. IRecognitionControl surfaces these as Action<T> events.

Key Dependencies

• OpenCvSharp4 — Core image processing
• YoloV8 / YoloV8.Gpu — AI object detection (conditional on build config)
• IronPython 3.4.0 — Python scripting integration
• Ninject — Dependency injection
• CommunityToolkit.Mvvm — MVVM support (ObservableObject, RelayCommand)
• Serilog — Structured logging
• Scintilla.NET — Code editor component in UI
• MaterialSkin.Core — Material Design WinForms theming

Conventions

• Target platform is x64 Windows, but new code should be cross-platform — use Avalonia for UI, avoid WinForms-only or Windows-specific APIs.
• Culture is forced to en-US at startup.
• Nullable reference types are enabled across most projects.
• Operation attributes: [Category("name")] for UI grouping, [NotForTool] to exclude properties from serialization, [IgnoreOperation] to hide from discovery.
• Recipe serialization supports both binary (.hrcp) and XML (.xhrcp) formats. Prefer XML for new work. Override SaveXML/LoadXML/GetOperationElementName for custom serialization.