org.appliedtopology.tda4j.io

Generic delimited-text point clouds, distance matrices, and persistence diagrams -- fields split on , or any run of whitespace, so plain-whitespace-separated files (Dionysus/JavaPlex's own convention) parse with these same methods too.

DIPHA's own binary container format -- little-endian throughout, every file starting with the magic number 8067171840 followed by an Int64 file-type tag -- verified directly against DIPHA/dipha's own include/dipha/file_types.h and README.md (see .claude/WORKLOG-io-module.md), not reconstructed from a secondhand description.

'''Axis order''': DIPHA's IMAGE_DATA format is explicitly "x-fastest" (g(1) varies fastest) -- the OPPOSITE of CubicalImage.fromFlatArray's own convention (its LAST shape axis is fastest, matching ordinary row-major Array[Array[...]].flatten). readImageData/writeImageData reverse the shape to line the two conventions up (a flat array with axis-0 fastest is, by definition, already in row-major order for the REVERSED shape) -- pinned with a hand-built asymmetric-shape fixture, not just reasoned through, since transposing an image preserves its homology and a barcode-only test cannot catch getting this backwards.

GUDHI's own OFF/nOFF point-cloud format and .pers persistence-diagram format -- verified against gudhi.inria.fr's own file-format documentation (see .claude/WORKLOG-io-module.md). GUDHI's cubical-complex module also reads Perseus's cubical toplex format directly, byte-for-byte the same as real Perseus (confirmed against GUDHI's own Bitmap_cubical_complex_base.h reader source) -- see Perseus.readCubicalToplex for that, not duplicated here.

Perseus's own cubical toplex ("dense grid") input format, and its per-dimension persistence-interval output format -- verified against Perseus's own documentation page and cross-checked against GUDHI's own Bitmap_cubical_complex_base.h reader source (GUDHI's cubical-complex module reads real Perseus files directly), not reconstructed from memory. See .claude/WORKLOG-io-module.md.

'''Axis order''': "lexicographic order" in Perseus's own sense has the FIRST declared axis fastest-varying -- confirmed from GUDHI's own compute_position_in_bitmap/multiplier construction (multipliers[0] = 1), the only place either project's exact stride arithmetic is spelled out in source rather than prose. This is the OPPOSITE of CubicalImage.fromFlatArray's own last-axis-fastest convention -- the same reversal Dipha.readImageData already needs, for the same underlying reason, and handled the same way here.

'''Periodic boundaries''' (a negative grid size, GUDHI's own extension to this format) are not representable by CubicalGridStream and are rejected outright with a clear error rather than silently misinterpreted.

'''Missing cubes''': Perseus reserves filtration value -1 for a cube absent from the complex entirely -- CubicalGridStream has no "absent cell" concept, so -1 is mapped to Double.PositiveInfinity (GUDHI's own documented convention for the same gap), which has the intended effect: the cell exists in the stream but is never reached by any finite-threshold computation.

'''Perseus's own simplicial toplex format is deliberately not implemented here''' -- no primary-source verification of it was done (see .claude/WORKLOG-io-module.md), and a wrong parser for it would be worse than none.

Ripser's own input file formats (ripser.cpp's read_point_cloud/read_lower_distance_matrix/ read_upper_distance_matrix/read_distance_matrix/read_binary) -- verified directly against github.com/Ripser/ripser's own source (see .claude/WORKLOG-io-module.md), not reconstructed from documentation: a wrong flat-index convention here would silently produce a plausible-looking wrong matrix rather than an error.

'''Not implemented''': --format sparse (a triplet edge list -- tda4j has no "only these edges are known, the rest are unknown rather than infinite" metric-space type, so this is a real, open design question, not an oversight -- see the worklog) and --format dipha (use Dipha.scala directly instead, which reads the exact same file DIPHA itself produces).