# 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

```bash
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)

```bash
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`](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`](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.