Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 16 additions & 8 deletions .github/ISSUE_TEMPLATE/bug_report.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
7 changes: 5 additions & 2 deletions .github/ISSUE_TEMPLATE/feature_request.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
12 changes: 12 additions & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
## Problem and scope
<!-- What problem does this solve, and what changes for the user?
Link a related issue if any. -->

## Validation actually performed
<!-- Commands or manual steps run, environment/Qt variant, inputs, and results.
For numerical checks, include references, units, and tolerances.
A successful build alone does not verify UI or scientific behavior. -->

## Limitations
<!-- Checks not run and why, platforms/Qt variants not checked, and remaining risks.
If none, say so. -->
64 changes: 64 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -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.
6 changes: 6 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
46 changes: 46 additions & 0 deletions docs/architecture.md
Original file line number Diff line number Diff line change
@@ -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.
Loading