diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index dc0317cb..850083dd 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -8,26 +8,34 @@ assignees: '' --- **Describe the bug** -A clear and concise description of what the bug is. +Describe the problem and what you were trying to do. +For usage questions and support, visit https://groups.io/g/Interferometry. **To Reproduce** Steps to reproduce the behavior: 1. Go to '...' 2. Click on '....' -3. Scroll down to '....' -4. See error +3. Use these inputs/settings: '...' +4. Observe '...' + +Does it happen every time? Did an earlier version work? **Expected behavior** A clear and concise description of what you expected to happen. -**Screenshots** -If applicable, add screenshots to help explain your problem. +**Observed behavior** +What actually happened? Include relevant error text, if available. + +**Samples or screenshots (optional)** +Add a small sample or screenshot if it helps explain or reproduce the problem. +Remove private data before sharing. For numerical differences, include reference +values, their source, units, and tolerances if known. **Desktop (please complete the following information):** - - OS: [e.g. Windows, Linux, Mac + version informations] + - OS and version: [e.g. Windows, Linux, macOS] - DFTFringe version: [e.g. 6.2, sha76d1f40, ...] - Build: [e.g. from GitHub release, from GitHub Actions artifacts, your own build, ...] - - Dependencies versions: [for your own builds only, add version for QT, OpenCV, qwtPlot, ...] + - Dependency/toolchain versions: [for your own builds, Qt, OpenCV, Qwt, compiler, ...] **Additional context** -Add any other context about the problem here. +Add any related issues, workarounds, or other context here. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index bbcbbe7d..c11158c0 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -9,12 +9,15 @@ assignees: '' **Is your feature request related to a problem? Please describe.** A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] +For usage questions and support, visit https://groups.io/g/Interferometry. **Describe the solution you'd like** -A clear and concise description of what you want to happen. +Describe what you would like to do and the result you would expect. **Describe alternatives you've considered** A clear and concise description of any alternative solutions or features you've considered. **Additional context** -Add any other context or screenshots about the feature request here. +Optionally add examples, screenshots, your DFTFringe version and platform, or +existing behavior you want to preserve. For numerical features, reference +values, their source, units, and tolerances are helpful if known. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..062f845f --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,12 @@ +## Problem and scope + + +## Validation actually performed + + +## Limitations + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..72fc4c2c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,64 @@ +# Contributing to DFTFringe + +For usage questions and support, visit the +[Interferometry group](https://groups.io/g/Interferometry). GitHub issues are +welcome for bug reports and feature suggestions. + +## Describe the change + +Explain the problem and the user-visible outcome you want. For a bug, include +the steps and inputs that reproduce it, what you expected, and what actually +happened. Screenshots or a small sample can help; remove private data before +sharing. For numerical differences, include reference values, their source, +units, settings, and tolerances when known. + +Keep the explanation proportionate: a small fix may need only a few sentences +in the PR. For larger changes, discussing alternatives and compatibility early +can save rework, especially when scientific conventions, saved data, or +dependencies are affected. + +## Make a focused change + +Use the [architecture map](docs/architecture.md) to find relevant code, then +trace the implementation and callers. For stateful changes, check both user +actions and loading or initialization paths. Keep fixes narrow, preserve +unrelated behavior, and avoid mixing in cleanup or broad refactoring. +Update directly related documentation and add focused regression coverage +where practical. + +See the [README](README.md) for setup. Match the Qt version, compiler, and +dependency toolchain to the project you are building: + +- [DFTFringe.pro](DFTFringe.pro): Qt 6, C++17. +- [DFTFringe_QT5.pro](DFTFringe_QT5.pro): Qt 5, C++14. + +The existing CI configurations show platform-specific setup, dependency +versions, and build commands: +[Windows Qt 6](.github/workflows/build-windows.yml), +[Linux Qt 6](.github/workflows/build-linux.yml), +[macOS](.github/workflows/build-macos.yml), +[Windows Qt 5](.github/workflows/build-windows-QT5.yml), and +[Linux Qt 5](.github/workflows/build-linux-QT5.yml). +Consider both Qt variants when shared code is affected. The qmake project files +explicitly list sources, headers, forms, and resources; update the relevant +lists when adding files. Leave generated build output, personal configuration, +and unrelated logs or research files out of the contribution. + +## Check and submit + +Choose checks that exercise the change: relevant tests, builds, static checks, +or a focused manual workflow. For a UI fix, repeat the reproduction steps and +check nearby behavior. For numerical changes, compare with stated references +and tolerances. A successful build alone does not establish UI or scientific +correctness. + +Review the complete diff before submitting. In the PR, explain the problem and +scope, link a related issue if any, and report validation **actually performed**: +commands or manual steps, environment and Qt variant, inputs, and results. +Separately note checks not run, why, and any remaining limitations or risks. +Do not present planned checks or unobserved CI results as completed validation. + +Contributors are responsible for understanding and reviewing their changes, +checking results, and respecting licenses and data privacy, whether they use +AI assistance or not. Generated code and tool output need the same scrutiny as +any other contribution; no particular editor or assistant is required. diff --git a/README.md b/README.md index 05832394..2657c260 100644 --- a/README.md +++ b/README.md @@ -364,6 +364,12 @@ aqt install-tool windows desktop tools_ifw :building_construction: Under construction :building_construction: +# Contributing + +See the [contribution guide](CONTRIBUTING.md) for focused changes and validation +expectations, and the [architecture map](docs/architecture.md) for code navigation. +No particular editor or AI tool is required. + # How to analyse crashlog :warning: This method is for Windows only. diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 00000000..e232a46d --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,46 @@ +# Architecture map + +This is a navigation aid describing the current implementation, not a required +design or a refactoring proposal. + +## Main entry points + +| Area | Where to look | +| --- | --- | +| Window composition and signal/slot wiring | [mainwindow.cpp](../mainwindow.cpp) and [mainwindow.h](../mainwindow.h): `MainWindow` sets up the interferogram, analysis, and result views, controls, and surface manager connections. | +| Phase-map generation | [dftarea.cpp](../dftarea.cpp): `DFTArea::makeSurface` calculates and unwraps phase, applies configured flips and fringe spacing, and emits `newWavefront`. The PSI path also emits `newWavefront`. | +| Surface operations and file I/O | [surfacemanager.cpp](../surfacemanager.cpp) and [surfacemanager.h](../surfacemanager.h): `SurfaceManager` keeps `m_wavefronts` and the current index, coordinates processing and surface operations, and implements `readWaveFront` and `writeWavefront`. | +| Per-wavefront data | [wavefront.h](../wavefront.h) and [wavefront.cpp](../wavefront.cpp): arrays, masks, outlines, Zernike values, metadata, and processing flags. | +| Zernike processing | [zernikeprocess.cpp](../zernikeprocess.cpp): routines called by the surface manager for fitting Zernike terms, filling voids, and nulling terms. | + +## From analysis to results + +`MainWindow` connects `DFTArea::newWavefront` to +`SurfaceManager::createWaveFrontFromPhaseMap`, which populates a wavefront, +sets up its mask, and starts processing. + +`SurfaceManager::generateSurfacefromWavefront` coordinates Zernike fitting, +void filling, masking, nulling, and optional blur. Its branches depend on +wavefront state and mirror geometry; for example, elliptical surfaces take a +separate path. + +`SurfaceManager::sendSurface` computes metrics and passes the wavefront to the +contour, profile, 3D, simulation, and Foucault views. Selection and control +updates also travel through Qt signals and slots. + +## State and build navigation + +- Wavefront arrays are OpenCV matrices. The `wavefront` copy constructor and + `cloneMatricesFrom` clone the matrices, while default copy assignment is + memberwise and can share matrix storage. `createWaveFrontFromPhaseMap` + directly assigns its phase matrix to `wf->data`. +- Preferences are not centralized in one class. `MainWindow` restores window + geometry and state using `QSettings`; `SurfaceManager` also reads and writes + processing preferences. [mirrordlg.cpp](../mirrordlg.cpp) handles mirror + settings, including fringe spacing and flips. +- [DFTFringe.pro](../DFTFringe.pro) is the Qt 6/C++17 qmake project; + [DFTFringe_QT5.pro](../DFTFringe_QT5.pro) is the Qt 5/C++14 project. + Both explicitly list sources, headers, forms, and resources and configure + platform-specific external libraries. See the [README](../README.md) for + setup and [contribution guidance](../CONTRIBUTING.md) for validation and + platform build links.