ENH: Use NumberToString for lossless float metadata in NIfTI reader

[hjmjohnson]

Summary

Fixes float/double precision loss in ITK persistence-layer serialization (ITK issue #3249).

When ITK IO modules write numeric metadata to text-based format headers using default std::ostream precision (6 significant digits), values like 1.2345678901234568 are truncated to "1.23457", which parses back to a different bit pattern. This PR applies itk::ConvertNumberToString() (shortest exact round-trip string via Google double-conversion) consistently across 6 IO modules.

Files Fixed

Module	File	Code Path Fixed
NIfTI	itkNiftiImageIO.cxx	Read path: pixdim[], intent_p1/2/3, scl_slope/inter, cal_max/min, slice_duration → MetaDataDictionary strings
MetaImage	itkMetaImageIO.cxx + .h	Write path: scalar double/float keys, vector<double> loop, WriteMatrixInMetaData<> template
NRRD	itkNrrdImageIO.cxx	Write path: explicit float/double specializations of _dump_metadata_to_stream<T>
PolygonGroupSpatialObject XML	itkPolygonGroupSpatialObjectXMLFile.cxx	Write path: 3D polygon vertex coordinates (Point<double,3>)
FreeSurfer ASCII Mesh	itkFreeSurferAsciiMeshIO.h	Write path: WritePoints<T> loop template
VoxBoCUB	itkVoxBoCUBImageIO.cxx	Write path: m_Spacing[0/1/2] in CUB text header

Files Verified Correct (No Fix Needed)

• itkNrrdImageIO.cxx — Array<double/float> already uses ConvertNumberToString via itkArrayOutputSpecialization.cxx
• itkVoxBoCUBImageIO.cxx lines 682-684 — origin deliberately cast to int (CUB stores integer voxel coordinates)

Test Coverage

Adds a new commit (ENH: Add precision round-trip tests) with 4 precision regression tests:

• NIfTI (itkNiftiImageIOTest3.cxx): TestNiftiFloatMetadataPrecision() — writes image with 0.12345679-mm spacing, reads back, verifies MetaDataDictionary["pixdim[1]"] parses to the exact float32 bit pattern
• MetaImage (itkMetaImageIOMetaDataTest.cxx): encapsulates hpDouble=1.2345678901234568 and hpFloat=1.2345679f, writes/reads .mha, checks exact equality via stod/stof (bypasses the existing loose 1e-6 tolerance)
• NRRD (itkNrrdMetaDataTest.cxx): same pattern for native double and float NRRD metadata keys
• VoxBoCUB (itkVoxBoCUBImageIOTest.cxx): creates image with 0.123456789012345 spacing, writes/reads CUB, asserts GetSpacing()[0] == original double

All 4 tests FAIL against the unfixed IO code and PASS with this PR applied.

Root Cause

Default std::ostream precision is 6 significant digits. Float needs ≥8 and double needs ≥17 for lossless serialization. itk::ConvertNumberToString() (wrapping double-conversion::ToShortest()) produces the shortest decimal string that round-trips exactly.

Closes #3249

Test Plan

• itkNiftiVectorImageTest — includes TestNiftiFloatMetadataPrecision
• itkMetaImageIOMetaDataTest
• itkNrrdMetaDataTest
• itkVoxBoCUBImageIOTest1
• CI green on CDash

[greptile-apps]

Greptile Summary

This PR systematically fixes floating-point precision loss in six ITK IO modules by replacing default std::ostream serialization (6 significant digits) with itk::ConvertNumberToString(), which produces the shortest decimal string guaranteed to round-trip exactly. The fix is correct and well-motivated, addresses a long-standing data-fidelity issue (#3249), and includes four targeted regression tests that verify bit-exact round-trips for both float and double.

Key changes:

• NIfTI (itkNiftiImageIO.cxx): Converts pixdim[], quaternion parameters, srow matrix, intent parameters, slope/intercept, and cal/toffset metadata to use ConvertNumberToString. The srow loop refactor is clean and correct.
• MetaImage (itkMetaImageIO.cxx/.h): Fixes scalar double/float keys, vector<double> loop, and the WriteMatrixInMetaData<> template in the header.
• NRRD (itkNrrdImageIO.cxx): Adds explicit double and float template specializations of _dump_metadata_to_stream within the itk namespace.
• PolygonGroupSpatialObject XML, FreeSurfer ASCII Mesh, VoxBoCUB: Each gets ConvertNumberToString on the relevant write path.
• Tests: Four new precision round-trip sub-tests, one per module.

Minor issues noted: the joinElements helper in itkMetaImageIO.cxx is now unused after its one call site was replaced with a manual loop, and the VoxBoCUB precision test does not remove its temporary file.

Confidence Score: 5/5

Safe to merge — all remaining findings are P2 style/cleanup suggestions that do not affect correctness.

The core precision fix is correct and well-tested across all six IO modules. The only issues found are a now-unused static helper function (may generate a compiler warning) and a missing temp-file cleanup in the VoxBoCUB test — neither affects runtime behavior or test correctness. No P0 or P1 issues present.

Modules/IO/Meta/src/itkMetaImageIO.cxx — unused joinElements function may generate a compiler warning; Modules/Nonunit/Review/test/itkVoxBoCUBImageIOTest.cxx — precision test temp file not cleaned up.

Important Files Changed

Filename	Overview
Modules/IO/NIFTI/src/itkNiftiImageIO.cxx	All floating-point NIfTI metadata fields (pixdim, intent_p1/2/3, scl_slope/inter, cal_max/min, slice_duration, toffset, quaternion params, srow matrix) now use ConvertNumberToString; srow loop refactor is correct.
Modules/IO/Meta/src/itkMetaImageIO.cxx	Fixes double/float scalar and vector metadata serialization; however, the joinElements static helper is now dead code after the vector path was replaced with a manual loop.
Modules/IO/Meta/include/itkMetaImageIO.h	WriteMatrixInMetaData template now uses ConvertNumberToString for each matrix element; change is correct and complete.
Modules/IO/NRRD/src/itkNrrdImageIO.cxx	Adds explicit double and float specializations of _dump_metadata_to_stream within the itk namespace; correct use of template specialization, no issues.
Modules/IO/MeshFreeSurfer/include/itkFreeSurferAsciiMeshIO.h	Removes outputFile.precision(6) and std::fixed, replaces with ConvertNumberToString; correct fix for precision loss in point coordinate serialization.
Modules/Nonunit/Review/src/itkVoxBoCUBImageIO.cxx	Spacing values now serialized with ConvertNumberToString; correct and minimal change.
Modules/IO/SpatialObjects/src/itkPolygonGroupSpatialObjectXMLFile.cxx	Polygon vertex coordinates now serialized with ConvertNumberToString; correct fix.
Modules/Nonunit/Review/test/itkVoxBoCUBImageIOTest.cxx	New precision sub-test verifies spacing round-trip, but the temporary precision file is never removed after the test completes.
Modules/IO/NIFTI/test/itkNiftiImageIOTest3.cxx	New TestNiftiFloatMetadataPrecision function correctly verifies pixdim round-trip; proper cleanup on pass path.
Modules/IO/Meta/test/itkMetaImageIOMetaDataTest.cxx	New double/float precision sub-tests verify bit-exact round-trip via stod/stof; well-structured and clear.
Modules/IO/NRRD/test/itkNrrdMetaDataTest.cxx	Existing test logic inversion fixed (EXIT_SUCCESS/EXIT_FAILURE swapped back to correct sense); new precision sub-tests added correctly.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[NIfTI / MetaImage / NRRD\nVoxBoCUB / FreeSurfer / PolygonXML\nIO Write Path] --> B{Numeric metadata\nfield}
    B -->|float / double| C["itk::ConvertNumberToString()\n(Google double-conversion ToShortest)\nShortest exact round-trip string"]
    B -->|int / string / other| D[Default ostream <<\nno change]
    C --> E[Text header / MetaDataDictionary string]
    D --> E
    E --> F[Disk file]
    F --> G[IO Read Path]
    G --> H["std::stof / std::stod\nor direct float parse"]
    H --> I{Bit-exact round-trip?}
    I -->|With fix: YES| J[Correct metadata value]
    I -->|Before fix: NO\n6-digit truncation| K[Different float bit-pattern]

Loading

_{Reviews (2): Last reviewed commit: "ENH: Add precision round-trip tests for ..." | Re-trigger Greptile}

[hjmjohnson]

Added a second commit that applies the same lossless float fix to MetaImage IO (itkMetaImageIO.cxx / itkMetaImageIO.h).

Three call sites corrected in the metadata serialization loop:

• ExposeMetaData<double> and ExposeMetaData<float> → ConvertNumberToString()
• ExposeMetaData<std::vector<double>> → manual loop with ConvertNumberToString() (replacing joinElements which streamed with default precision)
• WriteMatrixInMetaData<N>() template in the header → ConvertNumberToString() per element

All 18 MetaImage IO tests pass.

[hjmjohnson]

Third commit: NRRD IO fix (itkNrrdImageIO.cxx).

The generic _dump_metadata_to_stream<T>() helper streamed scalar double and float metadata with default 6-digit precision. Added explicit template specializations for those two types that use itk::ConvertNumberToString().

Note: Array<double> and Array<float> were already lossless — their operator<< specializations in itkArrayOutputSpecialization.cxx already use ConvertNumberToString().

All 33 NRRD tests pass.

[dzenanz]

Looks good on a glance.

My change request (removal of local joinElements function: #6003 (review)) is addressed, thanks Hans!

[seanm]

@seanm I plan to merge this at the end of the workday today (2026-04-03) if no further change requests or delay requests are made.

Please delay. Today is a holiday here, but I did determine at the end of yesterday that this breaks several of our tests. Likely just slight numerical differences, but I'd like to check early next week.

[N-Dekker]

Thanks Hans! I think it's OK now, but you might of course consider my "nitpicks" 😺

[seanm]

Please delay. Today is a holiday here, but I did determine at the end of yesterday that this breaks several of our tests. Likely just slight numerical differences, but I'd like to check early next week.

[hjmjohnson]

@seanm Understood — I'll hold off on merging. Please take the time you need to investigate; early next week is fine.

When you have a chance, it would help to know:

• Which test(s) fail and in what format/module (NIfTI, MetaImage, NRRD, …)?
• Are the failures hard errors (wrong read-back values) or tolerance checks that need adjusting for the higher-precision strings?

The change from 6 significant digits (default ostream) to shortest-round-trip precision is intentional, so any downstream comparisons against hardcoded 6-digit strings will need updating — happy to help with that once you share specifics.

[N-Dekker]

@hjmjohnson Do I understand correctly that some output files may become much larger, with this PR? Especially when writing data "for all points" (for example, their coordinates)...?

[hjmjohnson]

@seanm Do you need any assistance with this task?

[seanm]

When you have a chance, it would help to know:

* Which test(s) fail and in what format/module (NIfTI, MetaImage, NRRD, …)?

nifti. I don't use the others.

* Are the failures hard errors (wrong read-back values) or tolerance checks that need adjusting for the higher-precision strings?

tolerance checks. I just need to confirm the results are not wildly different... should know today...

OK all is well, the differences are small.