Skip to content

examples: unify doc samples across bindings + fix 3 bugs#5971

Merged
Grantim merged 7 commits into
masterfrom
doc-samples-unify-and-cover
Apr 24, 2026
Merged

examples: unify doc samples across bindings + fix 3 bugs#5971
Grantim merged 7 commits into
masterfrom
doc-samples-unify-and-cover

Conversation

@Grantim
Copy link
Copy Markdown
Contributor

@Grantim Grantim commented Apr 23, 2026

Summary

  • Unifies C / C# / Python doc samples to match the cpp canonical: same inputs, same algorithm parameters, same output filenames. C samples drop CLI-arg handling in favor of hardcoded filenames, matching cpp/py convention.
  • Fixes 3 bugs that the audit surfaced along the way.
  • Bug-free same-named samples now demonstrate the same thing in every binding, so a reader flipping between language tabs in the Doxygen page won't see different algorithms.

Bugs fixed

File Bug
examples/c-examples/MeshICP.dox.c refMop was constructed from meshFloating instead of meshReference, so ICP was aligning a mesh onto itself. meshReference was loaded but never used.
examples/cpp-examples/MeshLoadSave.dox.cpp if ( loadRes.has_value() ) error-check condition was inverted — the success branch printed the error and exited 1.
examples/python-examples/GlobalRegistration.dox.py p2pl_inaccuracy = icp.getMeanSqDistToPlane(p2pt_metric) — passed the point metric where the plane metric belongs.

Other notable changes

  • C# class-name fix: Collision / CollisionPrecise / CollisionSelf renamed to *Example so the Program.cs reflection dispatcher can actually discover them (it filters on EndsWith("Example")).
  • Pedagogical completeness: MeshFixDegeneracies.dox.cpp and Triangulation.dox.cpp now save their results.
  • MeshModification.dox.py now builds a torus programmatically (matching cpp) instead of loading mesh.stl; the parametrize entry in test_python_samples.py drops input_files accordingly.
  • C# MeshDecimate.dox.cs switched to cpp canonical params (maxDeletedFaces=1000, maxError=0.05f, subdivideParts=64) plus the packOptimally() pre-step.

Known test breakage — requires S3 fixture refresh

The C# MeshDecimate test will fail against the current S3 autotest fixture (s3://data-autotest/test_data_2025-05-13/doc_samples/c-sharp/MeshDecimateExample/decimated_mesh.stl) because the canonical params produce a different mesh. The fixture needs to be regenerated with the updated sample and uploaded to a fresh dated snapshot, then the default URL in .github/actions/python-regression-tests/action.yml bumped. Will be done manually before merge.

Scope boundaries

This PR only touches changes that are fixture-independent (except for the one intentional break above). The following items are deferred to a follow-up because they would change existing fixture comparisons:

  • C# MeshBoolean / MeshFillHole / MeshFixDegeneracies / MeshOffset logic alignment
  • Python filename renames: LaplacianExampleLaplacianDeformation, NoiseDenoiseExampleNoiseDenoise, Triangulation_v3Triangulation
  • Python output filename renames (e.g., decimatedMesh.stldecimated_mesh.stl)
  • New parametrize entries for Collision / SignedDistance / ContourTriangulation / MeshFixDegeneracies / MeshFromText / Triangulation_v2 in Python, and for Collision* / FreeFormDeformation / MeshICP / Triangulation in C#
  • Adding the 14 missing C# .dox.cs samples to close parity with C++

Test plan

  • Python regression tests (Linux / Windows / macOS) — expect MeshModification still green; MeshICP output unchanged (only getStatusInfo rename); GlobalRegistration output unchanged (only print-order + metric fix in stderr)
  • C# samples test (Windows) — expect all current entries green except MeshDecimate which fails until S3 fixture refresh
  • C++ / C examples build cleanly on all platforms (only source change; they aren't runtime-tested)
  • Doxygen build has no broken \include warnings

🤖 Generated with Claude Code

Grantim and others added 5 commits April 23, 2026 23:23
Align C/C#/Python doc samples to match cpp canonical (same inputs,
same algorithm parameters, same output filenames) where fixture-safe.
C samples lose CLI arg handling in favor of hardcoded filenames,
matching cpp/py convention.

Bugs surfaced during the audit:
- MeshICP.dox.c: refMop was constructed from meshFloating instead
  of meshReference, so ICP was aligning a mesh onto itself.
- MeshLoadSave.dox.cpp: error-check condition was inverted; the
  success path printed the error and exited 1.
- GlobalRegistration.dox.py: p2pl_inaccuracy passed the point
  metric to getMeanSqDistToPlane instead of the plane metric.

Other notable changes:
- C# Collision / CollisionPrecise / CollisionSelf classes renamed
  to *Example so Program.cs reflection dispatcher can invoke them.
- MeshFixDegeneracies.dox.cpp and Triangulation.dox.cpp now save
  their results (were pedagogically incomplete).
- MeshDecimate.dox.cs switched to cpp canonical params; the
  existing S3 fixture was generated with the prior params, so the
  C# MeshDecimate test will fail until the fixture is refreshed.
- MeshModification.dox.py now builds a torus programmatically
  (matching cpp) instead of loading mesh.stl; the corresponding
  parametrize entry in test_python_samples.py drops input_files.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The original file had `MR_std_vector_MR_EdgeId_Size` / `_At` with
capital S/A inside a dead `#else` branch that was never compiled.
My rewrite inherited that typo and it broke the build on platforms
that no longer silently warn. Use the real lowercase helpers
`_size` / `_at`, matching the convention used across other
c-examples (e.g. MeshStitchHole.dox.c).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Comment thread examples/c-examples/GlobalRegistration.dox.c
Comment thread examples/c-examples/MeshOffset.dox.c
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The change drops code examples that might be useful for users. Maybe better to update other languages' examples instead?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this sample seems much more complicated than other langs, do we actually need it all? mb just add outNewFaces usage to all langs?

Comment thread examples/c-sharp-examples/Collision.dox.cs
Comment thread examples/c-sharp-examples/CollisionSelf.dox.cs
p2pt_inaccuracy = icp.getMeanSqDistToPoint(value=p2pt_metric)
print(f"RMS point-to-point distance: {p2pt_metric} ± {p2pt_inaccuracy}")
p2pt_inaccuracy = icp.getMeanSqDistToPoint(p2pt_metric)
print(f"RMS point-to-point distance: {p2pt_metric} \u00b1 {p2pt_inaccuracy}")
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is the code point preferred over an explicit symbol?

Grantim and others added 2 commits April 24, 2026 14:50
…Holes

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…x.py

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@Grantim Grantim merged commit 8fdc8ed into master Apr 24, 2026
35 checks passed
@Grantim Grantim deleted the doc-samples-unify-and-cover branch April 24, 2026 12:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants