Skip to content

PR_BODY.md

Latest commit

 

History

History
135 lines (114 loc) · 7.75 KB

PR_BODY.md

File metadata and controls

135 lines (114 loc) · 7.75 KB
Raw

feat: CPPxDIC newversion — structured outputs, inputs, params, tests, docs, CI

Status: prepared locally, not yet opened. This file is the ready-to-use PR description for main ← newversion. No push / no PR has been created.

Summary

This branch restructures CPPxDIC into clearly separated, default-OFF/gated outputs and inputs, adds a three-tier parameter override chain, a zero-dependency test suite, full documentation, deployment artifacts, and CI — without changing the behaviour of the working camera-pairs pipeline (it stays the default and is never restructured to make room for the new modes).

Section 1 — repository hygiene

  • C++ standard aligned to C++17 across CMakeLists.txt and README.md.

Section 2 — outputs / targets

  • proxyncorr (apps/proxyncorr/) — pass-through 2D DIC driver around CppNCorr; optional target -DBUILD_PROXYNCORR=ON (default OFF).
  • singledic (apps/singledic/) — single-camera DIC stub + MATLAB reference pointer; -DBUILD_SINGLEDIC=ON (default OFF).
  • xdic camera-pairs — isolated and gated behind a compile-time XDIC_MODE=camerapairs|mirrored|multi (default camerapairs).
  • xdic mirrored — skeleton under src/xdic/mirrored/, compiled only for XDIC_MODE=mirrored.
  • xdic multi — placeholder + design note under src/xdic/multi/ with a #error guard, compiled only for XDIC_MODE=multi.

Section 3 — inputs

  • Video ingestion audited/hardened with a documented container/codec comment.
  • Image-folder reader (include/input/image_folder_reader.{h,cpp}) — directory listing + sorted, extension-filtered discovery implemented; frame decoding is a documented TODO.

Section 4 — parameters

  • Three-tier override chain: CLI > config file > compiled defaults, reusing the existing INI param system. New unified config/default.cfg, Config::loadFromConfigFile, and -C/--config.

Section 5 — tests

  • TESTS_PLAN.md (committed in phase A) implemented with a **tiny in-tree assertion harness
    • CTest** (no GoogleTest/Catch2 — zero new deps), under tests/cppxdic_suite/, gated behind BUILD_TESTING (default ON) and only when CPPxDIC is the top-level project.
  • Unit (7 executables): config, XDIC_MODE guard, image-folder reader, Delaunay, temporal filter, face isotropy, surface-stitching math.
  • Integration: IT-3 (2D-path input stage on the real ohtcfrp fixture) runs; IT-1/2/4/5/6/7 are SKIPPED placeholders (no stereo fixture).
  • E2E: E2E-1 (2D regression guard on ohtcfrp with captured golden statistics + tolerance bands) runs; E2E-2 (full stereo) is a SKIPPED placeholder.
  • Result: 10 ctest cases pass (26 inner assertions pass, 9 skipped, 0 failed).

Section 6 — documentation

  • docs/quickstart.md, docs/developer_guide.md, docs/user_guide.md.

Section 7 — deploy

  • Organised the project's real container/HPC assets under deploy/:
    • deploy/docker/ — multi-stage Dockerfile (builds the camera-pairs cppxdic), docker-compose.yml, run.sh helper, and template configs/.
    • deploy/cluster/ — Singularity/Apptainer cppxdic.def, SLURM submit_job.sh (binds OMP_NUM_THREADS to --cpus-per-task, OMP_PROC_BIND=spread), monitor_job.sh, and template configs/.
    • deploy/build.sh (local build, moved via git mv), deploy/build_for_clusters.sh (HPC cheat-sheet), and an umbrella deploy/README.md documenting both paths, the SLURM target (+ PBS/LSF porting note), and the Docker image-tag convention.
    • Internal path references were updated for the new deploy/ location.

Section 8 — CI/CD

  • .github/workflows/ci.yml (push + PR to main/newversion): build, test, lint jobs; .clang-format added.

Intentional stubs and TODO markers

Area What's stubbed Marker / location
singledic logs "not yet implemented" and exits apps/singledic/main.cpp, README_singledic.md
xdic mirrored skeleton only src/xdic/mirrored/, gated by XDIC_MODE=mirrored
xdic multi placeholder, intentionally fails to build src/xdic/multi/multi_mode.cpp (#error "not implemented")
Image-folder reader discovery only; decode is a TODO include/input/image_folder_reader.h (decodeFrames TODO)
proxyncorr working pass-through; in-memory frame hand-off pending TODO block in apps/proxyncorr/main.cpp
Tests (stereo) IT-1/2/4/5/6/7, E2E-2 registered SKIPPED tests/cppxdic_suite/integration/test_integration_skipped.cpp, e2e/test_e2e_ohtcfrp.cpp
Tests (temporal) 2 filterTime invariants SKIPPED tests/cppxdic_suite/unit/test_temporal_filter.cpp

Items needing confirmation / follow-up

  • Test framework choice was resolved as the in-tree harness (no GoogleTest/Catch2).
  • Stereo fixture (calibration .mat + 2-camera frames) is still needed to un-skip the 3D integration/E2E tests and golden-data assertions (TESTS_PLAN open Q2/Q3).
  • filterTime bug (NEW finding): the production temporal filter is numerically unstable — even a constant input diverges (~1e+24..1e+162) across all tested lengths. It feeds the step-F deformation path when step_f_temporal_filtering=true. Fix is out of scope for this test/docs/CI branch (touches production math); tracked separately. Workaround: step_f_temporal_filtering=false.
  • Docker image build could not be verified locally (no Docker daemon); the Dockerfile mirrors the host build flow that was verified.
  • clang-format conformance of new files was not locally verifiable (clang-format not installed); the lint job will report any deltas.

How to review

  1. Tests & harness: tests/cppxdic_suite/framework/test_harness.h, tests/cppxdic_suite/CMakeLists.txt, and the BUILD_TESTING block at the end of the root CMakeLists.txt. Run: cmake -S . -B build -DBUILD_TESTING=ON && cmake --build build -j && (cd build && ctest --output-on-failure).
  2. Camera-pairs safety: confirm the new test wiring and modes are gated/default-OFF and the cppxdic target's sources/deps are unchanged.
  3. Docs: docs/quickstart.md, docs/developer_guide.md, docs/user_guide.md.
  4. Deploy: deploy/README.md (umbrella), deploy/docker/ (Dockerfile, compose, run.sh, configs), deploy/cluster/ (Singularity cppxdic.def, SLURM submit_job.sh/monitor_job.sh, configs), deploy/build_for_clusters.sh.
  5. CI: .github/workflows/ci.yml (note the documented SKIP rationale) + .clang-format.
  6. Known bug: the SKIP reasons in tests/cppxdic_suite/unit/test_temporal_filter.cpp.

Commits (main..newversion)

ci: add GitHub Actions workflow for build, test, lint
chore(deploy): organise parallel/cluster/Docker scripts under deploy/
docs: add user guide
docs: add developer guide
docs: add quickstart guide
test(e2e): add E2E-1 2D regression guard with captured golden baseline
test(integration): add IT-3 fixture test and skipped stereo placeholders
test(unit): add in-tree harness + CTest and unit tests
docs(tests): add TESTS_PLAN.md — awaiting confirmation before implementation
feat(params): implement CLI > config-file > compiled-defaults override chain
feat(input/images): stub image-folder reader with documented interface
fix(input/video): audit and harden existing video ingestion
feat(xdic/multi): add architecture note and placeholder for N-camera mode
feat(xdic/mirrored): add skeleton gated behind XDIC_MODE=mirrored
refactor(xdic): isolate camerapairs mode; gate future modes behind compile flag
feat(singledic): add stub target with MATLAB reference pointer
feat(proxyncorr): scaffold pass-through target from CppNCorr tests
chore: align C++ standard to 17 across CMakeLists and README

🤖 Generated with Claude Code