Thanks for your interest in improving Virtual Path Vision! This document describes how to report issues, propose features, and submit pull requests.
感谢你参与 Virtual Path Vision 的开发!本文说明如何反馈问题、提出功能建议与提交代码。
By participating you agree to abide by our Code of Conduct. 参与本项目即表示你同意遵守行为准则。
- Bug reports – open an issue using the Bug report template.
- Feature requests – open an issue using the Feature request template.
- Pull requests – fix a bug, add a processing mode, improve docs or translations.
- Translations – add a new
.resxfile (see Internationalization).
| Requirement | Version |
|---|---|
| OS | Windows 10 / 11 (x64) |
| .NET SDK | 8.0 |
| IDE | Visual Studio 2022 / Rider / VS Code |
git clone https://github.com/virtual-path/virtual-path-vision.git
cd virtual-path-vision
dotnet restore
dotnet build
dotnet run --project VirtualPathVision/VirtualPathVision.csprojOr open VirtualPathVision.sln in Visual Studio 2022 and press F5.
There is a headless regression suite (no UI process required):
dotnet run --project VirtualPathVision.Tests/VirtualPathVision.Tests.csprojIt prints one line per assertion and exits non-zero on failure. Coverage is described in Known Limitations and in the source files themselves.
Building is not enough. XAML compiles happily while being wrong at runtime — a
StylewhoseTargetTypedoes not match the element is not a compile error, and the failure only appears when the window loads. Launch the app after touching XAML.
- Language – C# with
<Nullable>enable</Nullable>; keep the existing file-scoped namespace style. - UI – WPF/XAML. Colours must reference theme brushes (
{DynamicResource ...}), never hard-coded hex, so both the light and dark themes keep working. - ViewModels / text – all user-visible strings must go through
TranslationServiceand the.resxfiles (add bothStrings.resxandStrings.en.resxentries). - Formatting – follow
.editorconfig(4-space indent, CRLF). - Native code – the
AI/andComponents/OpenCVScalar/HSV values are functional (detection), not UI colours — do not remap them. - XAML styles do not cross
TargetType.GlassTextBox(TargetType="TextBox") applied to a<PasswordBox>compiles without error and throws at load time, taking the whole window with it. When a control needs a restyled look, add a style for its own type to both themes. Note also that aControlTemplatetrigger must name a property of that control type —<Trigger Property="Text" ...>does not transfer toPasswordBox, which usesPassword. - Threading on the capture path. Capture runs on a background thread, so UI updates there must
be non-blocking. Use
InvokeUifor per-frame refreshes (it de-duplicates, keeping the newest frame) andPostUifor one-shot events (dropping one is unrecoverable — a dropped "capture stopped" leaves the panel stale). A blockingDispatcher.Invokemakes the capture thread wait for the UI thread; while closing, the UI thread waits for the capture loop. That mutual wait hung the app permanently untilVideoCaptureComponent.StopCapturewas changed to take everything it needs before waiting and to never touch_lockafterwards. - Do not release native handles while the loop may still be using them.
capture.Release()andMat.Dispose()must happen after the capture loop has exited, not after a fixed timeout.
- The solution builds with 0 errors (
dotnet build). - No new warnings were introduced.
- Tests pass:
dotnet run --project VirtualPathVision.Tests/VirtualPathVision.Tests.csproj. - The app launches (
dotnet run --project VirtualPathVision/VirtualPathVision.csproj) — XAML mistakes are not compile errors. - UI changes work in both light and dark themes.
- New UI strings are localized (zh-CN + en-US).
- Any new assertion was checked by injecting the bug it is meant to catch and confirming it goes red — an assertion that passes either way proves nothing.
- The PR description explains what changed and why; link related issues.
- Screenshots are attached for visible UI changes.
Keep them short and imperative. A light Conventional-Commits style is welcome:
feat: add CLAHE adaptive enhancement mode
fix: prevent preview from overflowing on high-resolution cameras
docs: refresh README project structure
ui: unify card layout across panels
By contributing you agree that your contributions are licensed under the GNU General Public License v3.0.